Design of the sample

The following sections describe each of the programs that comprise the Mail Manager sample application. The relationships between the programs and the panels that the application uses is shown in Figure 43 for the TSO version, and Figure 44 for the CICS Transaction Server for OS/390 version.

Figure 43. Programs and panels for the TSO versions of the Mail Manager. This figure shows the names for the COBOL version.
 The diagram shows the relationship between programs  and panels for the TSO version of the Mail Manager. These are described in the following text detailing the application design.

Figure 44. Programs and panels for the CICS version of the Mail Manager
 The diagram shows the relationship between programs  and panels for the CICS(R) version of the Mail Manager. These are described in the following text detailing the application design.

Menu program

In the TSO environment, the menu program is invoked by the CLIST. In the CICS environment, the program is invoked by transaction MAIL.

The menu program (CSQ4TVD1 for TSO, CSQ4CVD1 for CICS) is the initial program in the suite. It displays the menu (CSQ4VDP1 for TSO, VD1 for CICS) and invokes the other programs when they are selected from the menu.

The program first obtains the user's ID:

After the program has obtained the user ID, it checks to ensure that the user has a mail queue (CSQ4SAMP.MAILMGR.userid). If a mail queue does not exist, the program creates one by putting a message on the system-command input queue. The message contains the WebSphere MQ for z/OS command DEFINE QLOCAL. The object definition that this command uses sets the maximum depth of the queue to 9999 messages.

The program also creates a temporary dynamic queue to handle replies from the system-command input queue. To do this, the program uses the MQOPEN call, specifying the SYSTEM.DEFAULT.MODEL.QUEUE as the template for the dynamic queue. The queue manager creates the temporary dynamic queue with a name that has the prefix CSQ4SAMP; the remainder of the name is generated by the queue manager.

The program then opens the user's mail queue and finds the number of messages on the queue by inquiring about the current depth of the queue. To do this, the program uses the MQINQ call, specifying the MQIA_CURRENT_Q_DEPTH selector.

The program then performs a loop that displays the menu and processes the selection that the user makes. The loop is stopped when the user presses the PF3 key. When a valid selection is made, the appropriate program is started; otherwise an error message is displayed.

Get-mail and display-message programs

In the TSO versions of the application, the get-mail and display-message functions are performed by the same program (CSQ4TVD2). In the CICS version of the application, these functions are performed by separate programs (CSQ4CVD2 and CSQ4CVD3).

The Mail Awaiting panel (CSQ4VDP2 for TSO, VD2 for CICS; see Figure 45 for an example) shows all the messages that are on the user's mail queue. To create this list, the program uses the MQGET call to browse all the messages on the queue, saving information about each one. In addition to the information displayed, the program records the MsgId and CorrelId of each message.

Figure 45. Example of a panel showing a list of waiting messages
 --------------------- WebSphere MQ for z/OS Sample Programs ------- ROW 16 OF 29
 COMMAND ==>                                                Scroll    ===> PAGE
                                                              USERID - NTSFV02
                               Mail Manager System            QMGR   - VC4
                                  Mail Awaiting

                       Msg      Mail        Date       Time
                       No       From        Sent       Sent
                  16
                       16      Deleted
                       17      JOHNJ      01/06/1993  12:52:02
                       18      JOHNJ      01/06/1993  12:52:02
                       19      JOHNJ      01/06/1993  12:52:03
                       20      JOHNJ      01/06/1993  12:52:03
                       21      JOHNJ      01/06/1993  12:52:03
                       22      JOHNJ      01/06/1993  12:52:04
                       23      JOHNJ      01/06/1993  12:52:04
                       24      JOHNJ      01/06/1993  12:52:04
                       25      JOHNJ      01/06/1993  12:52:05
                       26      JOHNJ      01/06/1993  12:52:05
                       27      JOHNJ      01/06/1993  12:52:05
                       28      JOHNJ      01/06/1993  12:52:06
                       29      JOHNJ      01/06/1993  12:52:06

From the Mail Awaiting panel the user can select one message and display the contents of the message (see Figure 46 for an example). The program uses the MQGET call to remove this message from the queue, using the MsgId and CorrelId that the program noted when it browsed all the messages. This MQGET call is performed using the MQGMO_SYNCPOINT option. The program displays the contents of the message, then declares a syncpoint: this commits the MQGET call, so the message now no longer exists.

Figure 46. Example of a panel showing the contents of a message
 --------------------- WebSphere MQ for z/OS Sample Programs ---------------------
 COMMAND ==>
                                                              USERID - NTSFV02
                               Mail Manager System            QMGR   - VC4
                                  Received Mail

  Mail sent from JOHNJ    at VC4

  Sent on the 01/06/1993 at 12:52:02
  ------------------------------------ Message -------------------------------
 | HELLO FROM JOHNJ                                                           |
 |                                                                            |
 |                                                                            |
 |                                                                            |
 |                                                                            |
 |                                                                            |
 |                                                                            |
 |                                                                            |
 |                                                                            |
 |                                                                            |
 '----------------------------------------------------------------------------'


 

An obvious extension to the function provided by the Mail Manager is to give the user the option to leave the message on the queue after viewing its contents. To do this, you would have to back out the MQGET call that removes the message from the queue, after displaying the message.

Send-mail program

When the user has completed the Send Mail panel (CSQ4VDP4 for TSO, VD4 for CICS), the send-mail program (CSQ4TVD4 for TSO, CSQ4CVD4 for CICS) puts the message on the receiver's mail queue. To do this, the program uses the MQPUT1 call. The destination of the message depends on how the user has filled the fields in the Send Mail panel:

The program does not accept blank messages, and it removes leading blanks from each line of the message text.

If the MQPUT1 call is successful, the program displays a message that shows that the user name and queue manager name to which the message was put. If the call is unsuccessful, the program checks specifically for the reason codes that indicate the queue or the queue manager do not exist; these are MQRC_UNKNOWN_OBJECT_NAME and MQRC_UNKNOWN_OBJECT_Q_MGR. The program displays its own error message for each of these errors; for other errors, the program displays the completion and reason codes returned by the call.

Nickname program

When the user defines a nickname, the nickname program (CSQ4TVD5 for TSO, CSQ4CVD5 for CICS) creates a queue that has the nickname as part of its name. The program does this by putting a message on the system-command input queue. The message contains the WebSphere MQ for z/OS command DEFINE QALIAS or DEFINE QREMOTE. The type of queue that the program creates depends on how the user has filled the fields of the Create Nickname panel (CSQ4VDP5 for TSO, VD5 for CICS):

The program also creates a temporary dynamic queue to handle replies from the system-command input queue.

If the queue manager cannot create the nickname queue for a reason that the program expects (for example, the queue already exists), the program displays its own error message. If the queue manager cannot create the queue for a reason that the program does not expect, the program displays up to two of the error messages that are returned to the program by the command server.

Note:
For each nickname, the nickname program creates only an alias queue or a local definition of a remote queue. The local queues to which these queue names resolve are created only when the user ID that is contained in the nickname is used to start the Mail Manager application.