The Credit Check sample application is a suite of programs that demonstrates how to use many of the features provided by WebSphere MQ for z/OS. It shows how the many component programs of an application can pass messages to each other using message queuing techniques.
The sample can run as a stand-alone CICS application. However, to demonstrate how to design a message queuing application that uses the facilities provided by both the CICS and IMS environments, one module is also supplied as an IMS batch message processing program. This extension to the sample is described in The IMS extension to the Credit Check sample.
You can also run the sample on more than one queue manager, and send messages between each instance of the application. To do this, see The Credit Check sample with multiple queue managers.
The CICS programs are delivered in C and COBOL. The single IMS program is delivered only in C. The supplied data sets are shown in Table 53 and Table 54.
The application demonstrates a method of assessing the risk when bank customers ask for loans. The application shows how a bank could work in two ways to process loan requests:
The financial and security details in the application have been kept simple so that the message queuing techniques are clear.
To prepare and run the Credit Check sample, perform the following steps:
The immediate and batch inquiry panels are similar--Figure 47 shows the Immediate Inquiry panel.
Figure 47. Immediate Inquiry panel for the Credit Check sample application
+--------------------------------------------------------------------------------+
| CSQ4VB2 WebSphere MQ for z/OS Sample Programs |
| |
| Credit Check - Immediate Inquiry |
| |
| Specify details of the request, then press Enter. |
| Name . . . . . . . . . ____________________ |
| Social security number ___ __ ____ |
| Bank account name . . ______________________________ |
| Account number . . . . __________ |
| Amount requested . . . 012345 |
| Response from CHECKING ACCOUNT for name : ____________________ |
| Account information not found |
| Credit worthiness index - NOT KNOWN |
| .. |
| .. |
| .. |
| .. |
| .. |
| .. |
| .. |
| .. |
| .. |
| MESSAGE LINE |
| F1=Help F3=Exit F5=Make another inquiry |
+--------------------------------------------------------------------------------+
The Credit Check sample application checks that the data you enter in the 'Amount requested' field of the inquiry panels is in the form of integers.
If you enter one of the following account numbers, the application finds the appropriate account name, average account balance, and credit worthiness index in the VSAM data set CSQ4BAQ:
You can enter any, or no, information in the other fields. The application retains any information that you do enter and returns the same information in the reports that it generates.
This section describes the design of each of the programs that comprise the Credit Check sample application. For a discussion of some of the techniques that were considered during the design of the application, see Design considerations.
Figure 48 shows the programs that make up the application, and also the queues that these programs serve. In this figure, the prefix CSQ4SAMP has been omitted from all the queue names to make the figure easier to understand.
Figure 48. Programs and queues for the Credit Check sample application (COBOL programs only). In the sample application, the queue names shown in this figure have the prefix 'CSQ4SAMP.'
|
When you start the conversational-mode CICS transaction MVB1, this starts the user-interface program for the application. This program puts inquiry messages on queue CSQ4SAMP.B2.INQUIRY and gets replies to those inquiries from a reply-to queue that it specifies when it makes the inquiry. From the user interface you can submit either immediate or batch inquiries:
Important differences between the properties of messages used in the application when in batch and immediate mode are:
However, in all cases, the properties of loan request messages are propagated throughout the application. So, for example, all messages that result from a high-priority request will also have a high priority.
The Credit Application Manager (CAM) program performs most of the processing for the Credit Check application.
The CAM is started by the CKTI trigger monitor (supplied with WebSphere MQ for z/OS) when a trigger event occurs on either queue CSQ4SAMP.B2.INQUIRY or queue CSQ4SAMP.B2.REPLY.n, where n is an integer that identifies one of a set of reply queues. The trigger message contains data that includes the name of the queue on which the trigger event occurred.
The CAM uses queues with names of the form CSQ4SAMP.B2.WAITING.n to store information about inquiries it is processing. The queues are named so that they are each paired with a reply-to queue; for example, queue CSQ4SAMP.B2.WAITING.3 contains the input data for a particular inquiry, and queue CSQ4SAMP.B2.REPLY.3 contains a set of reply messages (from programs that query databases) all relating to that same inquiry. To understand the reasons behind this design, see Separate inquiry and reply queues in the CAM.
If the trigger event occurs on queue CSQ4SAMP.B2.INQUIRY, the CAM opens the queue for shared access. It then tries to open each reply queue until a free one is found. If it cannot find a free reply queue, the CAM logs the fact and terminates normally.
If the trigger event occurs on queue CSQ4SAMP.B2.REPLY.n, the CAM opens the queue for exclusive access. If the return code reports that the object is already in use, the CAM terminates normally. If any other error occurs, the CAM logs the error and terminates. The CAM opens the corresponding waiting queue and the inquiry queue, then starts getting and processing messages. From the waiting queue, the CAM recovers details of partially-completed inquiries.
For the sake of simplicity in this sample, the names of the queues used are held in the program. In a business environment, the queue names would probably be held in a file accessed by the program.
The CAM first attempts to get a message from the inquiry queue using the MQGET call with the MQGMO_SET_SIGNAL option. If a message is available immediately, the message is processed; if no message is available, a signal is set.
The CAM then attempts to get a message from the reply queue, again using the MQGET call with the same option. If a message is available immediately, the message is processed; otherwise a signal is set.
When both signals are set, the program waits until one of the signals is posted. If a signal is posted to indicate a message is available, the message is retrieved and processed. If the signal expires or the queue manager is terminating, the program terminates.
A message retrieved by the CAM may be one of four types:
The CAM processes these messages as follows:
For all loan requests, the CAM requests the average balance of the customer's checking account. It does this by putting a request message on alias queue CSQ4SAMP.B2.OUTPUT.ALIAS. This queue name resolves to queue CSQ4SAMP.B3.MESSAGES, which is processed by the checking-account program, CSQ4CVB3. When the CAM puts a message on this alias queue, it specifies the appropriate CSQ4SAMP.B2.REPLY.n queue for the reply-to queue. An alias queue is used here so that program CSQ4CVB3 can easily be replaced by another program that processes a base queue of a different name. To do this, you simply redefine the alias queue so that its name resolves to the new queue. Also, you could assign differing access authorities to the alias queue and to the base queue.
If a user requests a loan that is larger than 10000 units, the CAM initiates checks on other databases as well. It does this by putting a request message on queue CSQ4SAMP.B4.MESSAGES, which is processed by the distribution program, CSQ4CVB4. The process serving this queue propagates the message to queues served by programs that have access to other records such as credit card history, savings accounts, and mortgage payments. The data from these programs is returned to the reply-to queue specified in the put operation. Additionally, a propagation message is sent to the reply-to queue by this program to specify how many propagation messages have been sent.
In a business environment, the distribution program would probably reformat the data provided to match the format required by each of the other types of bank account.
Any of the queues referred to here can be on a remote system.
For each inquiry message, the CAM initiates an entry in the memory-resident Inquiry Record Table (IRT). This record contains:
The CAM copies the inquiry message on to the waiting queue with:
The CAM puts these messages on queue CSQ4SAMP.DEAD.QUEUE, where they can be examined. If this put operation fails, the message is lost and the program continues. For more information on the design of this part of the program, see How the sample handles unexpected messages.
When the CAM has received all the replies it is expecting for an inquiry, it processes the replies and creates a single response message. It consolidates into one message all the data from all reply messages that have the same CorrelId. This response is put on the reply-to queue specified in the original loan request. The response message is put within the same unit of work that contains the retrieval of the final reply message. This is to simplify recovery by ensuring that there is never a completed message on queue CSQ4SAMP.B2.WAITING.n.
The CAM copies on to queue CSQ4SAMP.B2.WAITING.n all the messages that it receives. It sets the fields of the message descriptor like this:
When an inquiry has been completed, the messages for a specific inquiry are removed from the waiting queue during answer processing. Therefore, at any time, the waiting queue contains all messages relevant to in-progress inquiries. These messages are used to recover details of in-progress inquiries if the program has to restart. The different priorities are set so that inquiry messages are recovered before propagations or reply messages.
The checking-account program is started by a trigger event on queue CSQ4SAMP.B3.MESSAGES. After it has opened the queue, this program gets a message from the queue using the MQGET call with the wait option, and with the wait interval set to 30 seconds.
The program searches VSAM data set CSQ4BAQ for the account number in the loan request message. It retrieves the corresponding account name, average balance, and credit worthiness index, or notes that the account number is not in the data set.
The program then puts a reply message (using the MQPUT1 call) on the reply-to queue named in the loan request message. For this reply message, the program:
The program continues to get messages from the queue until the wait interval expires.
The distribution program is started by a trigger event on queue CSQ4SAMP.B4.MESSAGES. To simulate the distribution of the loan request to other agencies that have access to records such as credit card history, savings accounts, and mortgage payments, the program puts a copy of the same message on all the queues in the namelist CSQ4SAMP.B4.NAMELIST. There are three of these queues, with names of the form CSQ4SAMP.Bn.MESSAGES, where n is 5, 6, or 7. In a business application, the agencies could be at separate locations, so these queues could be remote queues. If you want to modify the sample application to show this, see The Credit Check sample with multiple queue managers.
The distribution program performs the following steps:
The agency-query program is supplied as both a COBOL program and a C program. Both programs have the same design. This shows that programs of different types can easily coexist within a WebSphere MQ application, and that the program modules that comprise such an application can easily be replaced.
An instance of the program is started by a trigger event on any of these queues:
After it has opened the appropriate queue, this program gets a message from the queue using the MQGET call with the wait option, and with the wait interval set to 30 seconds.
The program simulates the search of an agency's database by searching the VSAM data set CSQ4BAQ for the account number that was passed in the loan request message. It then builds a reply that includes the name of the queue it is serving and a credit-worthiness index. To simplify the processing, the credit-worthiness index is selected at random.
When putting the reply message, the program uses the MQPUT1 call and:
The program sends the reply message to the reply-to queue named in the loan request message. (The name of the queue manager that owns the reply-to queue is also specified in the loan request message.)
This section discusses:
The application could use a single queue for both inquiries and replies, but it was designed to use separate queues for the following reasons:
The application can support multiple CAMs and can recover in-progress inquiries effectively by using paired reply-to and waiting queues.
The user-interface program handles errors very simply by reporting them directly to the user. The other programs do not have user interfaces, so they have to handle errors in other ways. Also, in many situations (for example, if an MQGET call fails) these other programs do not know the identity of the user of the application.
The other programs put error messages on a CICS temporary storage queue called CSQ4SAMP. You can browse this queue using the CICS-supplied transaction CEBR. The programs also write error messages to the CICS CSML log.
When you design a message-queuing application, you must decide how to handle messages that arrive on a queue unexpectedly. The two basic choices are:
If you choose the second option:
To ensure that the application smoothly handles all inquiries with minimal impact from outside activities, the Credit Check sample application uses the second option. To allow you to keep the sample separate from other applications that use the same queue manager, the Credit Check sample does not use the system dead-letter queue: instead, it uses its own dead-letter queue. This queue is named CSQ4SAMP.DEAD.QUEUE. The sample truncates any messages that are longer than the buffer area provided for the sample programs. You can use the Browse sample application to browse messages on this queue, or use the Print Message sample application to print the messages together with their message descriptors.
However, if you extend the sample to run across more than one queue manager, unexpected messages, or messages that cannot be delivered, could be put on the system dead-letter queue by the queue manager.
The programs in the Credit Check sample application declare syncpoints to ensure that:
To achieve this, a single unit of work is used to cover the getting of a message, the processing of that message, and any subsequent put operations.
When the user-interface program (CSQ4CVB1) sends messages, it uses the MQPMO_DEFAULT_CONTEXT option. This means that the queue manager generates both identity and origin context information. The queue manager gets this information from the transaction that started the program (MVB1) and from the user ID that started the transaction.
When the CAM sends inquiry messages, it uses the MQPMO_PASS_IDENTITY_CONTEXT option. This means that the identity context information of the message being put is copied from the identity context of the original inquiry message. With this option, origin context information is generated by the queue manager.
When the CAM sends reply messages, it uses the MQPMO_ALTERNATE_USER_AUTHORITY option. This causes the queue manager to use an alternate user ID for its security check when the CAM opens a reply-to queue. The CAM uses the user ID of the submitter of the original inquiry message. This means that users are allowed to see replies to only those inquiries they have originated. The alternate user ID is obtained from the identity context information in the message descriptor of the original inquiry message.
When the query programs (CSQ4CVB3/4/5) send reply messages, they use the MQPMO_PASS_IDENTITY_CONTEXT option. This means that the identity context information of the message being put is copied from the identity context of the original inquiry message. With this option, origin context information is generated by the queue manager.
The application has to monitor the progress of all the "live" inquiries it is processing at any one time. To do this it uses the unique message identifier of each loan request message to associate all the information it has about each inquiry.
The CAM copies the MsgId of the inquiry message into the CorrelId of all the request messages it sends for that inquiry. The other programs in the sample (CSQ4CVB3 - 5) copy the CorrelId of each message they receive into the CorrelId of their reply message.
You can use the Credit Check sample application to demonstrate distributed queuing by installing the sample on two queue managers and CICS systems (with each queue manager connected to a different CICS system). When the sample program is installed, and the trigger monitor (CKTI) is running on each system, you need to:
A version of the checking-account program is supplied as an IMS batch message processing (BMP) program. It is written in the C language.
The program performs the same function as the CICS version, except that to obtain the account information, the program reads an IMS database instead of a VSAM file. If you replace the CICS version of the checking-account program with the IMS version, you see no difference in the method of using the application.
To prepare and run the IMS version you must:
Another way of using the IMS checking-account program is to make it serve one of the queues that receives messages from the distribution program. In the delivered form of the Credit Check sample application, there are three of these queues (B5/6/7.MESSAGES), all served by the agency-query program. This program searches a VSAM data set. To compare the use of the VSAM data set and the IMS database, you could make the IMS checking-account program serve one of these queues instead. To do this, you must alter the definition of the namelist CSQ4SAMP.B4.NAMELIST to replace one of the CSQ4SAMP.Bn.MESSAGES queues with the CSQ4SAMP.B3.IMS.MESSAGES queue. You can use any one of:
You can then run the sample from CICS transaction MVB1 as usual. The user sees no difference in operation or response. The IMS BMP stops either after receiving a stop message or after being inactive for five minutes.
This program runs as a BMP. You must start the program using its JCL before any WebSphere MQ messages are sent to it.
The program searches an IMS database for the account number in the loan request messages. It retrieves the corresponding account name, average balance, and credit worthiness index.
The program sends the results of the database search to the reply-to queue named in the WebSphere MQ message being processed. The message returned appends the account type and the results of the search to the message received so that the transaction building the response can confirm that the correct query is being processed. The message is in the form of three 79-character groups, as follows:
'Response from CHECKING ACCOUNT for name : JONES J B' ' Opened 870530, 3-month average balance = 000012.57' ' Credit worthiness index - BBB'
When running as a message-oriented BMP, the program drains the IMS message queue, then reads messages from the WebSphere MQ for z/OS queue and processes them. No information is received from the IMS message queue. The program reconnects to the queue manager after each checkpoint because the handles have been closed.
When running in a batch-oriented BMP, the program continues to be connected to the queue manager after each checkpoint because the handles are not closed.