Using the Common Queue Server

Starting CQS

You can activate CQS in one of two ways:

• As a z/OS® task, using the z/OS START command
• As a z/OS batch job

In addition, IMS automatically starts CQS, when appropriate.

Restarting CQS

Depending on whether a CQS structure contains data, you can warm start CQS or cold start CQS:

• If the structure is empty, you must cold start CQS.
• If the structure contains data, you can either warm start or cold start CQS.

When you have completed restarting CQS, the CQS ready message is issued (CQS0020I).

CQS warm start

During a warm start, CQS reads the checkpoint data set to find the log token representing the last system checkpoint. When CQS finds this log token, it initiates a warm start. If CQS fails to find this log token in the checkpoint data set, it reads the log token from the structure. If CQS finds the log token, it issues a WTOR in order to allow you to confirm the use of this token.

CQS cold start

When CQS cold starts after connecting to an empty structure, CQS purges all log records for the structure and performs a system checkpoint. After the system checkpoint is complete, the structure and CQS restart is complete.

Using CQS user-supplied exit routines

You can use the following exit routines to monitor and modify CQS activities:

• CQS Initialization/Termination exit routine
• CQS Client Connection exit routine
• CQS Queue Overflow exit routine
• CQS Structure Statistics exit routine
• CQS Structure Event exit routine

Changing the size of coupling facility structures

The initial size of a structure on the coupling facility is determined by the value of the INITSIZE parameter in the CFRM policy. CQS allows you to dynamically reconfigure the size of a structure.

When the first CQS connects to a structure, the value specified for INITSIZE is the size of that structure. If enough free space does not exist for this INITSIZE value, the size of the structure becomes that of the available space in the coupling facility.

Initiating system checkpoint

As a system checkpoint for recovering CQS information during restart, each CQS writes its own control blocks to the z/OS log. To retrieve this restart information, CQS also writes information to the CQS checkpoint data set. CQS does not quiesce activity while the checkpoint is in progress.

Checkpoint data sets

For each structure pair, CQS maintains a checkpoint data set. CQS writes to a checkpoint data set and then uses it during restart. Checkpoint data sets are dynamically allocated during CQS initialization.

How CQS restarts after system checkpoint

During CQS restart, CQS reads the log records from the last system checkpoint and rebuilds the work that was in progress.

Initiating structure checkpoint

Recovering structures

z/OS allows you to rebuild structures. You rebuild structures either by copying them or by recovering them.

Rebuilding structures

One or more CQSs must be running in order to copy or recover structures and the messages on those structures. When the new structure is allocated, policy changes (such as structure location) are applied.

Copying structures

If at least one CQS has access to the structure when structure rebuild is initiated, one of the CQS systems that still has access to the structure copies all of the messages (both recoverable and irrecoverable) from that structure to the new structure.

Recovering structures

If no CQS has access to the structure when structure rebuild is initiated, the structure is recovered from the SRDS and the z/OS log. Irrecoverable messages (such as Fast Path input messages) are lost.

Deleting structures

You can delete a structure when no CQS is connected to it. To delete a structure:

1. Shut down all CQSs that are connected to the structure.
2. Delete any failed persistent connections.
   Attention: If a CQS fails while it is connected to a structure, allow it to restart so that it can clean up any work that was in process at the time it failed. This command can be used to terminate the failed connections when you must delete the structure. If this command is used incorrectly, the queues or resources might be lost.

   Issue the following command:

   SETXCF FORCE,CONNECTION,STRNAME=strname,CONNAME=ALL

3. Issue the command:

   SETXCF FORCE,STRUCTURE,STRNAME=strname

   Ensure that the strname value in this command is the same as the strname value that is specified in the CQS global structure definition parameters in PROCLIB member data set CQSSGxxx and the CQS local structure definition parameters in PROCLIB member data set CQSSLxxx.

Deleting message queues

You can delete message queues on a structure by deleting the structure.

Monitoring shared queue usage

You can monitor usage of the IMS shared message queue structure by using the Queue Space Notification exit routine (DFSQSSP0). The exit is passed information about the total number of allocated and in-use entries and elements in the primary and overflow message queue structures. This information can be used to prevent the message queue structure from becoming full.

If you are writing a program that directly accesses a CQS structure, you can receive information about that structure's utilization by using the FEEDBACK= and FEEDBACKLEN= parameters on the CQSPUT and CQSDEL macros.

CQS logging and the z/OS logger

The z/OS system logger records all information necessary for CQS to recover structures and restart. CQS provides a File Select and Formatting Print utility to read the log records.

Related reading: For more information about defining the log stream, see z/OS MVS Programming: Sysplex Services Guide.