This chapter describes how to configure the MessageQ MVS Client. Before you configure MessageQ, create the four datasets that may be required for your MVS application by editing and running JCLs included in the MVS Client media kit.
Table 3-1 provides an overview of how to create the datasets required to run MessageQ MVS Client applications.
Table 3-2 describes the configuration options for the MVS Client.
To configure the MessageQ MVS Client, use the MVS Client Configuration JCL, DMQCONF as shown in Listing 3-1. A copy of this JCL is located in DMQ.V3R2.CNTL. The configuration file is a VSAM ESDS. Edit the JCL file to add the appropriate settings and job card, then submit the job for processing.
Update and run this JCL whenever changes to the definitions of any of the following system configuration elements are needed.
Listing 3-1
Configuration JCL DMQCONF
//******************************************
//ALLOC EXEC PGM=IDCAMS
//*
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DELETE (DMQ.V3R2.INI)
DEFINE CLUSTER( -
NAME(DMQ.V3R2.INI) -
VOLUMES(TSOUSR) -
RECORD(132 132) -
NONINDEXED -
RECORDSIZE(132 132) -
NONSPANNED -
SHAREOPTIONS(2 3) -
FREESPACE (20 0) -
CISZ(1024) -
SPEED -
) -
DATA(NAME(DMQ.V3R2.INI.DATA))
/*
//*
//ALLOCP EXEC PGM=IDCAMS
//*
//SYSPRINT DD SYSOUT=*
//*
//OUTFILE DD DSN=DMQ.V3R2.INI,DISP=SHR -
//INFILE DD *
(Default Server)
TransportType=TCP/IP
Hostname=server_host
Endpoint=5000
ReconnectInterval=0
(Failover)
EnableAutomaticFailover=0
TransportType=TCP/IP
Hostname=failover_host
Endpoint=5000
(Logging)
ErrorEvents=1
SentMessages=0
ReceivedMessages=0
SentCICSMessages=0
ReceivedCICSMessages=0
(MRS)
Enabled=0
JournalPath=./
JournalFileSize=0
JournalCycle=0
JournalSizeFixed=0
PreAllocate=1
JournalBlockSize=0
(Trace)
PamsTrace=0
DmqclTrace=0
//SYSIN DD *
REPRO INFILE(INFILE) OUTFILE(OUTFILE)
//*
//ST1 EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//IN DD DSN=DMQ.V3R2.INI,DISP=SHR -
//SYSIN DD *
PRINT -
CHAR -
INFILE(IN)
/*
//
Note: The MessageQ configuration file entries are case insensitive. All records are translated to uppercase.
Configuring the connection to the MessageQ Client Library Server (CLS) on the MessageQ message server system consists of the following two items:
Configuring the Server Connection
The default server identifies the MessageQ server system for all connections to the message queuing bus. If automatic reconnection is enabled, applications that are attempting to connect to a server (or lose a connection to the CLS), try to reconnect when the network connection to the server is available. Client applications also reconnect in the event that the CLS or host server system is stopped and restarted.
During an automatic reconnect event, the MessageQ MVS Client attempts to connect only to the default server. Automatic reconnect does not attempt to use the failover server.
After a successful reconnect, the application is automatically attached to the message queuing bus and messaging operations can continue without interruption. All pending messages in the SAF journal are sent to the CLS before new operations can be performed. For example, when a Default Server
pams_get_msg operation triggers the reconnect threshold and a successful automatic reconnect and attach operation completes, the SAF journal is completely drained before the pams_get_msg function call returns. Table 3-3 shows the default server configuration options.
If the primary (default) server is not available and automatic failover is enabled, the MessageQ MVS Client provides the option of connecting to a failover CLS. The failover options are ignored if automatic reconnect to the default server is enabled.
By enabling automatic failover, a MVS Client will transparently try to attach to the failover server when the CLS on the primary server group is not available. Attempts to connect to the failover server are made only during a call to pams_attach_q.
Using the failover capability requires additional planning and work in order for messages to be sent and received correctly. The message queues used by MessageQ MVS Client applications are implemented by the MessageQ server group. The message queues, and any recoverable message journals, are located on the server system.
When connecting to the failover group, the queue address used by the MVS Client is likely to change (unless the MessageQ group started on the failover system has the same group ID as the primary server group). Recoverable messages sent to the client using the queue address of the primary server group are not delivered to the client when it reattaches to the failover server in a different MessageQ server group.
The simplest use of automatic failover is when MVS Client applications attach to a temporary queue and use a request/response style of messaging. These applications send requests to one or more servers that return responses to the queue address that sent the request. If failover occurs, the MVS Client application is automatically reattached to a new temporary queue and request messages are sent and responses delivered to the new queue address. The application is unaware that a failover event occurred, except that any pending response is not received.
Automatic failover is not appropriate for all applications. When client applications attach to a specific permanent queue and receive recoverable messages sent to that queue address, they depend on the message queuing resources of that MessageQ group. Recoverable messages sent to the queue address while the client application is not attached are saved on that system. If the client reconnects to the same queue name or number, but on a different (failover) MessageQ group, the recoverable messages on the MessageQ group where the default CLS is located are not delivered to the new queue address used by the MVS Client.
On the other hand, the previous scenario could use failover by making the MessageQ server group (and all disk-based queuing resources) also failover to another system so that messages previously sent to the MVS Client are received after a failover transition. Table 3-4 describes the automatic failover server configuration options.
The MVS Client logging features enables developers to:
DMQELOG file for troubleshooting purposes. Logging events is an effective way to monitor the run time behavior of an application.
Table 3-5 describes the logging configuration options. Note that you must perform a pams_attach_q operation for any of the "Log Messages" options to take effect.
To perform error logging, an error log file must be created. To create an error log file, modify the DMQELOG JCL statement code that is illustrated in Listing 3-2 (supplied with the MVS Client) and submit the job for processing. The error log file must be VSAM ESDS. The template JCL is contained in DMQ.V3R3.CNTL as member DMQELOG. A DD card for DMQELOG must be present in your MessageQ application execution JCL.
Listing 3-2 DMQELOG JCL Code
//******************************************
//ALLOC EXEC PGM=IDCAMS
//*
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DELETE (DMQ.V3R2.ELOG)
DEFINE CLUSTER( -
NAME(DMQ.V3R2.ELOG) -
VOLUMES(TSOUSR) -
RECORD(132 132) -
NONINDEXED -
RECORDSIZE(132 132) -
NONSPANNED -
SHAREOPTIONS(2 3) -
FREESPACE (20 0) -
CISZ(1024) -
SPEED -
) -
DATA(NAME(DMQ.V3R2.ELOG.DATA))
/*
//*
//ALLOCP EXEC PGM=IDCAMS
//*
//SYSPRINT DD SYSOUT=*
//*
//OUTFILE DD DSN=DMQ.V3R2.ELOG,DISP=SHR
//INFILE DD *
DMQ ERROR LOG
//SYSIN DD *
REPRO INFILE(INFILE) OUTFILE(OUTFILE)
//*
//ST1 EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//IN DD DSN=DMQ.V3R2.ELOG,DISP=SHR
//SYSIN DD *
PRINT -
CHAR -
INFILE(IN)
/*
//
To perform message logging, a log file must be created. To create a log file, modify the DMQLOG JCL statement that is illustrated in Listing 3-3 (supplied with the MVS Client) and submit the job for processing. The log file must be a VSAM ESDS. The template JCL is contained in DMQ.V3R3.CNTL as member DMQLOG. A DD card for DMQLOG must be present in your MessageQ application execution JCL.
Listing 3-3 DMQLOG JCL Code
//******************************************
//ALLOC EXEC PGM=IDCAMS
//*
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DELETE (DMQ.V3R2.LOG)
DEFINE CLUSTER( -
NAME(DMQ.V3R2.LOG) -
VOLUMES(TSOUSR) -
RECORD(1000 500) -
NONINDEXED -
RECORDSIZE(132 400) -
NONSPANNED -
SHAREOPTIONS(2 3) -
FREESPACE (20 0) -
CISZ(1024) -
SPEED -
) -
DATA(NAME(DMQ.V3R2.LOG.DATA))
/*
//*
//ALLOCP EXEC PGM=IDCAMS
//*
//SYSPRINT DD SYSOUT=*
//*
//OUTFILE DD DSN=DMQ.V3R2.LOG,DISP=SHR
//INFILE DD *
DMQ LOG
//SYSIN DD *
REPRO INFILE(INFILE) OUTFILE(OUTFILE)
//*
//ST1 EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//IN DD DSN=DMQ.V3R2.LOG,DISP=SHR
//SYSIN DD *
PRINT -
CHAR -
INFILE(IN)
/*
//
Message Recovery Services (MRS) are the MessageQ services that manage the automatic redelivery of critical messages. Messages that are sent using a recoverable delivery mode are written to the local store-and-forward (SAF) journal when the connection to the server system is not available.
The MessageQ Client ensures delivery of recoverable messages to the CLS on the MessageQ Server by providing a store-and-forward (SAF) journal to store recoverable messages when the connection to a CLS is not available. Local SAF journal processing is available when Message Recovery Services (MRS) are enabled in the MessageQ Client configuration.
When message recovery is enabled, messages sent using the following reliable delivery modes are saved to the store and forward file:
When the connection to the CLS is re-established, all messages in the SAF journal are sent before new messages are processed. The SAF messages are transmitted in first-in/first-out (FIFO) order. When the connection to CLS is reestablished, a return status of PAMS__LINK_UP is used to indicate that journal processing is no longer active.
Messages are sent from the SAF when one of the following events occurs:
The MRS section of the initialization file is optional if recoverable messaging is not used. See Listing 3-4 for the MRS configuration options.
Listing 3-4
MRS Configuration Options
(MRS)
Enabled=0
JournalPath=./
JournalFileSize=0
JournalCycle=0
JournalSizeFixed=0
PreAllocate=1
JournalBlockSize=0
When the MRS Enabled field is set to zero, MRS is disabled. If the Enabled field is set to "1", message recovery services are enabled. The MessageQ MVS Client uses a store and forward (SAF) file to store messages that cannot be delivered because a connection to the message queuing server is not available. When the connection to the server is restored, messages are delivered from the SAF file first, then normal messaging communication is restored.
If message recovery services are enabled in the initialization file, a SAF file must be created. The SAF file is a VSAM Key Sequenced Data Set (KSDS). The JCL to create this is located in DMQ.V3R2.CNTL, as member DMQJRNL. A DD card for DMQJRNL must be present in the MessageQ application execution JCL.
To create a SAF file, modify the DMQJRNL JCL job statements illustrated in Listing 3-5 (supplied with the MVS Client) and submit the job for processing. The template JCL is contained in the DMQ.V3R2.CNTL as member DMQJRNL.
Listing 3-5 Create SAF File
//******************************************
//ALLOC EXEC PGM=IDCAMS
//*
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DELETE (DMQ.V3R2.SAF)
DEFINE CLUSTER( -
NAME(DMQ.V3R2.SAF) -
VOLUMES(TSOUSR) -
RECORD(500 100) -
INDEXED KEY(4 0) -
RECORDSIZE(2048 32000) -
UNIQUE NONSPANNED -
SHAREOPTIONS(2 3) -
FREESPACE (20 0) -
CISZ(32000) -
SPEED -
) -
DATA(NAME(DMQ.V3R2.SAF.DATA)) -
INDEX(NAME(DMQ.V3R2.SAF.INDEX))
/*
//*
//ALLOCP EXEC PGM=IDCAMS
//*
//SYSPRINT DD SYSOUT=*
//*
//OUTFILE DD DSN=DMQ.V3R2.SAF,DISP=SHR
//INFILE DD *
0000000000000000000000000000000000000000DMQCL SAF V1.0
//SYSIN DD *
REPRO INFILE(INFILE) OUTFILE(OUTFILE)
//*
//ST1 EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//IN DD DSN=DMQ.V3R2.SAF,DISP=SHR
//SYSIN DD *
PRINT -
CHAR -
INFILE(IN)
/*
//
Tracing can be a useful debugging tool, because it allows you to enable and disable MessageQ MVS Client application processing activity trace output. The trace output may create large SYSOUT files on your system, and should be used only to monitor specific application behavior. Table 3-6 shows the tracing configuration options.
The MVS Client media kit contains sample programs to test your configuration. The sample programs are located in the DMQ.V3R2.SRC dataset. The JCL to compile all of the sample C programs is member DMQC370 in dataset DMQ.V3R2.CNTL. The JCL to linkedit all the sample C programs is member DMQLINK in dataset DMQ.V3R2.CNTL. DMQLINK requires a preallocated dataset for the linkage editor to store the executable programs. Please consult your Systems Programmer for the optimum block size for your disk configuration. The default name used by the supplied JCL procedures is DMQ.V3R2.LINKLIB. DMQRUN is located in DMQ.V3R2.CNTL. This JCL procedure executes the sample programs. Listing 3-6 lists the DMQRUN JCL.
Listing 3-6 The DMQRUN JCL File
//DMQRUN JOB ,DMQ,CLASS=A,
// MSGCLASS=X,MSGLEVEL=(1,1)
// TIME=(5,00)
//******************************************
//RUNIT EXEC PGM=XGET
//STEPLIB DD DSN=DMQ.V3R2,LINKLIB,DISP=SHR
// DD DSN=CEE.V1R5M0.SCEERUN,DISP=SHR
//*
//DMQINI DD DSN=DMQ.V3R2.INI,DISP=SHR
//DMQELOG DD DSN=DMQ.V3R2.ELOG,DISP=SHR
//DMQLOG DD DSN=DMQ.V3R2.LOG,DISP=SHR
//DMQJRNL DD DSN=DMQ.V3R2.SAF,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSOUT DD *
The XGET example shown in Listing 3-6 attaches to a temporary queue on the server node, sends ten messages to itself, and receives them based on selection criteria. In addition, it sends ten more messages and receives them based on their priority setting. The C source statements for XGET is located in DMQ.V3R2.SRC.
To run an MVS Client program, you must have a MessageQ group, including a CLS running on a server system. No special group or queue definitions are required. Listing 3-7 shows the output of running the XGET sample program.
Listing 3-7 XGET Program Output
X_Get Select Example starting...
Attached to queue: `20, 1'
Putting messages:
Put Message:
Text: `first message'
Class: FIRST
Type: ODD
Getting FIRST messages
Got message:
Class: FIRST
Type: ODD
Exited from MessageQ.
Pams_Get_msg Example complete....