The Mail Manager sample application is a suite of programs that demonstrates the sending and receiving of messages, both within a single environment and across different environments. The application is a simple electronic mailing system that allows users to exchange messages, even if they use different queue managers.
The application demonstrates how to create queues using the MQOPEN call and by putting WebSphere MQ for z/OS commands on the system-command input queue.
Three versions of the application are provided:
The Mail Manager is provided in versions that run in two environments. The preparation you must carry out before you run the application depends on the environment you want to use.
A user can access mail queues and nickname queues from both TSO and CICS so long as their sign-on user IDs are the same on each system.
Before you can send messages to another queue manager, you must set up a message channel to that queue manager. To do this, use the channel control function of WebSphere MQ, described in WebSphere MQ Intercommunication.
Follow these steps:
A separate CLIST is provided for each language version of the sample:
| For the COBOL version: | CSQ4RVD1 |
| For the C version: | CSQ4RCD1 |
To start the sample in the TSO environment, execute your tailored version of the CLIST from the TSO command processor within ISPF.
To start the sample in the CICS Transaction Server for z/OS environment, run transaction MAIL. If you have not already signed-on to CICS, the application prompts you to enter a user ID to which it can send your mail.
When you start the application, it opens your mail queue. If this queue does not already exist, the application creates one for you. Mail queues have names of the form CSQ4SAMP.MAILMGR.userid, where userid depends on the environment:
All parts of the queue names that the Mail Manager uses must be uppercase.
The application then presents a menu panel that has options for:
The menu panel also shows you how many messages are waiting on your mail queue. Each of the menu options displays a further panel:
In the user name field you can enter either a user ID or a nickname that you created using the Mail Manager. You can leave the queue manager name field blank if the user's mail queue is owned by the same queue manager that you are using, and you must leave it blank if you entered a nickname in the user name field:
For example, if you want to send a message to user JONESM on remote queue manager QM12, you could send them a message in either of two ways:
Nicknames are queues that have names of the form CSQ4SAMP.MAILMGR.userid.nickname, where userid is your own user ID and nickname is the nickname that you want to use. With names structured in this way, users can each have their own set of nicknames.
The type of queue that the program creates depends on how you fill in the fields of the Create Nickname panel:
For example, if your own user ID is SMITHK and you create a nickname called MARY for user JONESM (who uses the remote queue manager QM12), the nickname program creates a local definition of a remote queue named CSQ4SAMP.MAILMGR.SMITHK.MARY. This definition resolves to Mary's mail queue, which is CSQ4SAMP.MAILMGR.JONESM at queue manager QM12. If you are using queue manager QM12 yourself, the program instead creates an alias queue of the same name (CSQ4SAMP.MAILMGR.SMITHK.MARY).
The C version of the TSO application makes greater use of ISPF's message-handling capabilities than does the COBOL version. You may notice that different error messages are displayed by the C and COBOL versions.
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 z/OS version.
Figure 43. Programs and panels for the TSO versions of the Mail Manager. This figure shows the names for the COBOL version.
|
Figure 44. Programs and panels for the CICS version of the Mail Manager
 |
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.
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 2|
| 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.
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 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.
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.