Common Queue Server overview

Common Queue Server (CQS) is a generalized server that manages data objects on a coupling facility list structure. CQS manages two types of structures: queue structures and resource structures. CQS receives, maintains, and distributes data objects from these structures on behalf of clients. IMS is one example of a CQS client that uses CQS to manage both its shared queues and shared resources.

This topic contains General-use Programming Interface information.

CQS uses the z/OS® coupling facility as a repository for data objects. Storage in a coupling facility is divided into distinct objects called structures. Authorized programs use structures to implement data sharing and high-speed serialization. The coupling facility stores and arranges the data according to list structures. Queue structures contain collections of data objects that share the same name, which are known as queues. Resource structures contain data objects that are organized as uniquely named resources.

CQS runs on z/OS. The CQS client must also run on z/OS. CQS runs in a separate address space that can be started by the client.

Clients communicate with CQS by using CQS requests that are supported by CQS macro statements. Using these macros, CQS clients can communicate with CQS and manipulate client data on shared coupling facility structures. The following figure shows the communications and the relationship between clients, CQSs, and the coupling facility.

Figure 1. Client systems, CQS, and the coupling facility
This figure shows the communications between clients, CQSs and a coupling facility in a sysplex.

Related reading:

  • CQS requests are described in IMS Version 15.4 System Programming APIs.
  • See z/OS MVS Setting Up a Sysplex for complete details about setting up a sysplex.

CQS benefits

CQS enables users to take advantage of the benefits of a Parallel Sysplex® (sysplex) environment. These benefits include:

Automatic work load balancing
CQS places data objects on shared queues where they can be processed by any participating client system.

Any participating client system can use CQS to retrieve a data object from the shared queues.

Incremental growth
Customers can add new systems as workload increases.
Reliability
For both shared queues and resources, if one client system fails, the remaining client systems process the work.

CQS components

CQS uses the following components:

Primary structure
A z/OS coupling facility list structure that contains shared queues.
Resource structure
A z/OS coupling facility list structure that contains uniquely named resources.
Overflow structure
A z/OS coupling facility list structure that contains shared queues when the primary structure reaches an installation-specified overflow threshold. The overflow structure is optional.
z/OS log stream
A shared z/OS log stream that contains all CQS log records from all CQSs connected to a structure pair. This log stream is important for recovery of shared queues, if necessary. Each structure pair has an associated log stream.
Checkpoint data set
A local data set that contains CQS system checkpoint information.
Structure recovery data sets (SRDSs)
Shared data sets that contain structure checkpoint information for shared queues on a structure pair. Each structure pair has two associated SRDSs.

CQS functions

CQS performs the following functions:

Processes CQS requests
An architected interface that clients use to access CQS or data objects on a queue structure or a resource structure.
Notification of work on a queue
Clients register interest in the shared queues. If an empty queue becomes non-empty, CQS notifies its registered clients.
Records restart and recovery information
CQS records all the information necessary for restart and recovery in the z/OS system logger.
CQS system checkpoint
CQS system checkpoint writes log records relating to a particular CQS to the CQS log. The log records contain information necessary for CQS to restart and recover work.
Structure checkpoint
Structure rebuild
Structure rebuild is a z/OS process that allows another instance of a structure to be allocated with the same name and data reconstructed from the initial structure instance.
Overflow processing
CQS provides an overflow option to help prevent a queue full condition. When the primary list structure reaches the overflow threshold value, CQS attempts to dynamically increase the size of the primary structure, offloads selected queues to an overflow structure, or rejects requests for selected queues.

CQS requirements

The CQS has coupling facility requirements that are documented in the IMS Version 15.4 Release Planning.

Related reading:  See z/OS MVS Setting Up a Sysplex for more information on:

  • The planning required to migrate to a sysplex that uses a coupling facility
  • Hardware configurations of a sysplex
  • The software products that can use the coupling facility
  • The tasks for migrating to a coupling environment
  • Checklists for installing the sysplex hardware and software