CQSSGxxx member of the IMS PROCLIB data set

A particular CQS can support queue structures, resource structures, or a combination of both queue structures and resource structures. Each CQS sharing a structure must point to a CQSSGxxx member containing identical structure definition parameters.

Syntax

You can use the IMS Syntax Checker to modify this member of the IMS PROCLIB data set.

AA

Usage

Point all CQSs to the same CQSSGxxx member to avoid parameter mismatches. CQS connects to each structure that is defined in the member. The structures defined in the CQSSGxxx member must also be defined in the CQSSLxxx member of the IMS PROCLIB data set.

If you are using queue structures, define an overflow structure name OVFLWSTR= if there is a possibility that you use an overflow structure. If you have to add an overflow structure later, the structure and all CQSs must be cold started.

If the STRUCTURE statement for an EMHQ structure is deleted from the CQSSGxxx member of the IMS PROCLIB data set, resources for the EMHQ structure are not allocated. These resources include the EMHQ structure's associated overflow structure, structure recovery data sets, and CQS log.

If you use RECOVERABLE=NO, consider that:

• RECOVERABLE=NO structures are truly not recoverable. If the structure fails, the data in it is lost. Before using RECOVERABLE=NO, carefully consider whether you can tolerate the loss of data in your CQS shared queues structure if the structure or the coupling facility hardware fails. For example, a nonrecoverable queue might be acceptable for a test or development system; it might be unacceptable for a production system. Consider using a duplexed structure for a RECOVERABLE=NO structure in a production environment to provide redundancy.
• The failure of a nonrecoverable structure causes all CQSs that are connected to that structure to abend (ABENDU0373). If the structure was in overflow mode and the primary structure failed, the overflow structure is deleted. If the structure was in overflow and the overflow structure failed, the primary structure is cold started, and the overflow structure is not reallocated. All objects in the structures are lost. When the CQSs are restarted, they connect to an empty structure, resynchronize with their clients, and proceed with an empty queue. This processing is required to ensure that work that was in-flight when the structure failed is correctly resolved during the resynchronization at CQS restart.
• Changing between RECOVERABLE=NO and RECOVERABLE=YES requires a cold start of the CQS queue structure. You must delete the structure and the z/OS® log stream, and scratch and reallocate the SRDS and system checkpoint data sets.
• Nonrecoverable structures require that SRDS data sets (SRDSDSN1=, SRDSDSN2=) be specified and allocated. Although the SRDS data sets are not used for recovery, client-initiated structure checkpoints (including the CQSCHKPT macro, the /CQCHKPT IMS command, and CQS normal shut down checkpoints requested through the IMS /CQSET command) are still allowed. These checkpoints can be useful for diagnostics, as an alternative to taking a memory dump of the structure. Internally generated CQS structure checkpoints are skipped for nonrecoverable structures.
• RECOVERABLE=NO structures require that a z/OS log stream name be specified on the LOGNAME= parameter; however, the log stream does not have to be defined, and it is neither opened nor written to.
• When you start CQS with a RECOVERABLE=NO structure, message CQS0370I is issued, indicating that the structure is not recoverable.
• When you restart a CQS with a nonrecoverable structure, all restarts are cold starts (of the CQS, not the structure). When CQS connects to a structure that is not empty, message CQS0370I is issued, indicating that CQS is forcing a cold start for the structure.

Parameters

Use the following parameters to define a structure to CQS. At least one STRUCTURE or RSRCSTRUCTURE definition is required.

STRUCTURE ()

Defines a queue structure to CQS. This keyword can be repeated. Keyword parameters must be enclosed within parentheses.

Example: STRUCTURE (STRNAME=strname, SRDSDSN1=srsdsn1, ...)

The following keyword parameters are available to the STRUCTURE definition:

CHKNEARFULL

Optional parameter specifying whether (YES) or not (NO) CQS automatically takes a structure checkpoint when the log stream near-full conditions are detected. The default is NO.

The log stream near-full conditions happen in one of the following situations:

• Log stream usage reaches the 1/3 point between the high offload threshold percentage and 100% full (0.33% of the delta).
• Log stream usage reaches the 2/3 point between the high offload threshold percentage and 100% full (0.67% of the delta).

If you specify CHKNEARFULL=YES, CQS will take additional structure checkpoints when the z/OS log stream structure usage crosses the near-full thresholds. During the CQS message queue structure checkpoint process, CQS issues a log record delete request to the z/OS logger to relieve the log stream full condition. Using CHKNEARFULL=YES can help avoid log stream structure full situations; however, it might also result in additional CQS structure checkpoints.

If you specify CHKNEARFULL=NO, CQS will not take any additional structure checkpoints when log stream usage crosses the near-full thresholds. Specify CHKNEARFULL=NO or omit this parameter if you do not want CQS to take additional structure checkpoints when the z/OS log stream structure gets close to full.

LOGNAME=

Is the required 1- to 26-character name of the z/OS log stream that CQS uses to record all information related to the structure. The installation must have previously defined this name to the z/OS system logger.

All CQS address spaces that connect to a queue structure must use the same value for this parameter. The value specified by the CQS that initially allocates the structure is the value that is used for the life of the structure.

OBJAVGSZ=

Specifies the average size of a data object that is written to a queue on this structure. This value can range from 128 bytes to 61312 bytes or from 1K to 59K. The following list defines some IMS object sizes:

IMS client

The object size is the size of the IMS message plus some control information.

IMS queue manager messages

If the user message and the message queue prefix both fit completely into one queue buffer, the object size is the sum of the user message and the message queue prefix. If both parts do not fit into one queue buffer, the object size is the size of the portion of the message and the message queue prefix that do fit into one queue buffer. The size of an IMS message queue buffer is specified to the IMS control region by the QBUFSZ execution parameter.

IMS expedited message handler messages

The object size is the size of the user message plus 240 bytes (the size of the EMHB global header).

Each object in a CQS queue structure is stored using one entry and one or more 512-byte elements. The entry contains control data about the object on the queue. The elements contain the message data (IMS and CQS prefixes, and client data). The OBJAVGSZ parameter is used by CQS to determine the ratio of the number of entries to the number of elements within the coupling facility structure. OBJAVGSZ applies only to the initial allocation of the structure; it cannot be used to change the entry-to-element ratio of a structure that is already allocated.

For a structure defined with ALLOWAUTOALT(NO) in the CFRM policy, you must cold start the structure to change the entry-to-element ratio. This is because once CQS connects to a structure, it preserves the actual number of entries and elements obtained. If a structure rebuild occurs, CQS uses the actual entry-to-element ratio from these saved values when it connects to the rebuild structure, and not the values from OBJAVGSZ. This is done to ensure that the rebuild structure has a similar number of entries and elements as the old structure, to reduce the chance of a rebuild failure.

For a structure defined with ALLOWAUTOALT(YES), you still must cold start the structure to change the entry-to-element ratio to a specific value (for example, to set the ratio to a value you have computed based on your message sizes). However, z/OS dynamically changes the entry-to-element ratio if it is not correct for the size of the objects in the structure.

Recommendation: Define your queue structures with the ALLOWAUTOALT(YES) parameter, to allow z/OS to dynamically adjust the entry-to-element ratio as necessary.

Recommendation: Specify the OBJAVGSZ to be the average of the sizes of all the objects passed to CQS by a CQSPUT request. CQS adds its own prefix containing control information to every object placed on the structure. CQS adds the length of its prefix to the OBJAVGSZ value that you specify to get the true average object size. Therefore, OBJAVGSZ should reflect only the average size of the objects as they are passed to CQS, not the average size of the object on the coupling facility.

If the OBJAVGSZ is too small, too much space in the structure is allocated for control information. The structure becomes full when all the space for data is used up, even though space for control information is still available.

If the OBJAVGSZ is too large, too much space in the structure is allocated for data. The structure becomes full when all the control space is used up, even though space for data is still available.

Example: Five objects are put on the structure by a CQSPUT request. The sizes of the objects are:

object 1

134 bytes

object 2

1066 bytes

object 3

3200 bytes

object 4

172 bytes

object 5

345 bytes

The average object size is calculated to be 983 bytes.

     (134 + 1066 + 3200 + 172 + 345)/5 = 983

OVFLWMAX=

Specifies the maximum threshold percentage for overflow processing. This value indicates the percentage of the structure that must be in use before CQS goes into overflow mode. This value can be from 50 to 100. For example, if OVFLWMAX=75, the structure is put into overflow mode when the structure usage reaches 75% of the structure size. The default is 70%.

The value specified by the CQS that initially allocates the structure is used for the life of the structure.

Recommendation: If your structure is defined with ALLOWAUTOALT(YES) in the CFRM policy, you should also code the FULLTHRESHOLD parameter in the policy, and specify a value that is at least five percent lower than the value specified on OVFLWMAX. This is to allow the z/OS auto alter function to adjust the entry-to-element ratio and the structure size before CQS enters overflow processing.

OVFLWSTR=

Is the 1- to 16-character name of the optional coupling facility structure to which CQS connects for structure overflow processing. The name must follow the same naming convention as the structure name specified by the STRNAME= parameter. When CQS is processing in overflow mode, selected queues are written to this structure instead of to the primary structure.

If an overflow structure is not specified and an overflow condition is detected, CQS rejects requests to add data objects to those queues that were selected for overflow.

If an overflow structure is specified, CQS connects to the overflow structure during CQS initialization and then again during phase one of overflow threshold processing. If CQS detects that the overflow structure size is less than 30% of the primary structure size, the overflow structure is considered to be too small and CQS issues the CQS0268W message. CQS is allowed to initialize even though the overflow structure is too small. CQS disconnects from and deletes the overflow structure at the end of CQS initialization.

CQS does not attempt to connect to the overflow structure again until the overflow threshold is reached. If at that time the overflow structure size is still less than 30% of the primary structure size, CQS again issues the CQS0268W message. CQS goes into overflow mode, but the overflow structure is not used. Requests to add data objects to those queues that were selected for overflow are rejected.

Recommendation: Define the size of the overflow structure in the CFRM policy to be at least X% of the primary structure size, where X is the value specified for the OVFLWMAX= parameter. The value specified for the OVFLWMAX= parameter indicates the percentage of the primary structure that must be in use before CQS goes into overflow mode, the overflow threshold. For example, if the overflow threshold was defined with the OVFLWMAX= parameter to be 75% of the primary structure size, the size of the overflow structure should be at least 75% of the primary structure size. If a value is not specified for the OVFLWMAX= parameter, the overflow threshold defaults to 70% and the size of the overflow structure should be at least 70% of the primary structure size.

An overflow structure name can be defined only when the structure is cold started. Once structures have been allocated, an overflow structure cannot be added unless the structure and all CQSs are cold started.

All CQS address spaces that connect to a queue structure must use the same value for this parameter. The value specified by the CQS that initially allocates the structure is used for the life of the structure.

RECOVERABLE=

Optional parameter specifying whether (YES) or not (NO) the queue structure is recoverable. The default is YES.

By default, CQS queue structures are defined as recoverable. When data on a queue structure is changes, CQS records the change in a log record in the z/OS system log stream that is associated with the structure. Periodically, the contents of the queue structure are written to a structure recovery data set (SRDS). If a queue structure fails, CQS reallocates the structure and recovers it by first restoring the data from the last SRDS, and then applying any subsequent changes using the data from the z/OS log stream. This is the default for CQS queue structures (RECOVERABLE=YES).

You can optionally define a CQS queue structure as nonrecoverable (RECOVERABLE=NO). In this case, CQS does not write log records to a z/OS log stream. CQS does write structure checkpoint to an SRDS if one is requested; however, the checkpoints are not used for recovery. Using a nonrecoverable structure saves the overhead of using the z/OS logger. If the structure fails, however, all objects on the structure are lost.

SRDSDSN1=

Is a required 1- to 44-character data set name of the cataloged VSAM data set that is used for the first structure recovery data set. The data set name is used to dynamically allocate the data set when a structure checkpoint is requested. For a given structure checkpoint request, CQS uses either structure recovery data set 1 or data set 2. CQS alternates between the two data sets for structure checkpoint processing.

All CQS address spaces that connect to a queue structure must use the same value for this parameter. The value specified by the CQS that initially allocates the structure is the value that is used for the life of the structure.

SRDSDSN2=

Is a required 1- to 44-character data set name for the cataloged VSAM data set that is used for the second structure recovery data set. The data set name is used to dynamically allocate the data set when a structure checkpoint is requested. For a given structure checkpoint request, CQS uses either structure recovery data set 1 or data set 2. CQS alternates between the two data sets for structure checkpoint processing.

All CQS address spaces that connect to a queue structure must use the same value for this parameter. The value specified by the CQS that initially allocates the structure is the value that is used for the life of the structure.

STRMIN=

Specifies the value for the minimum primary structure size to which CQS can connect. This value is specified in units of 4 KB blocks and can be any value from 0 to the maximum structure size of 524288 (a 2-GB structure).

The default value is 0, indicating that CQS accepts the size as allocated by the coupling facility. If the coupling facility is constrained, the structure can be allocated to something smaller than that defined by the CFRM policy. Depending on the size, the structure might overflow sooner than expected.

Recommendation: Specify a value for STRMIN= that is less than the structure size that is defined in the policy.

The value specified by the CQS that initially allocates the structure is used for the life of the structure.

When the first CQS connects to an empty structure, that structure is allocated on the coupling facility. After it is allocated, the structure remains on the coupling facility regardless of whether a CQS is connected to it.

If, during connection to a structure, CQS determines that the size of the structure is smaller than the minimum size and the structure is empty, CQS terminates. In this case, the installation needs to redefine the use of the coupling facility to ensure that the required size can be allocated. If CQS connects to a structure that is smaller than the minimum size, but the structure contains data objects, CQS does not terminate. CQS attempts to use the smaller structure because it already contains data. In this case, CQS issues a message that allows an operator to initiate a structure rebuild in order to increase the structure size.

STRNAME=

The required 1- to 16-character name of the primary coupling facility structure to which CQS connects.

The installation must have defined the structure name in the CFRM administrative policy. The structure name must follow the naming rules of the CFRM. For names with fewer than 16 characters, CQS pads the name with blanks. The valid characters are A-Z, 0-9, and the following special characters:

 $ @ # _

Names must be uppercase and start with an alphabetic character.

Restriction: Avoid using names that IBM® uses for its structures. Do not begin structure names with the letters A-I, or with the character string SYS. If you do name a structure beginning with the letters A-I or SYS, your name might conflict with an existing or future IBM-defined structure name.

RSRCSTRUCTURE ()

Defines a resource structure to CQS. An IMSplex can define only one resource structure; name uniqueness is within one resource structure. Keyword parameters must be enclosed within parentheses.

If you use shared queues, and you want IMS to manage serial programs across the IMSplex, you must define a resource structure. You must also identify the resource structure on the CSLRIxxx member of the IMS PROCLIB data set RSRCSTRUCTURE parameter.

Example: RSRCSTRUCTURE (STRNAME=strname)

The following keyword parameters are available:

STRNAME=

The required 1- to 16-character name of the coupling facility list structure to which CQS connects. This parameter defines the name of the resource structure used by RM to keep IMS resource information.

The installation must have defined the structure name in the CFRM administrative policy. The structure name must follow the naming rules of the CFRM. For names with fewer than 16 characters, CQS pads the name with blanks. The valid characters are A-Z, 0-9, and the characters $, &, # and _. Names must be uppercase and start with an alphabetic character.

Restriction: Avoid using names IBM uses for its structures. Do not begin structure names with the letters A-I, or with the character string SYS.

ELEMENT=

Specifies the data element value of the entry-to-element ratio for resources that are used to allocate the resource structure. The number of data elements depends upon the resource type. To calculate the number of data elements needed, use the formulas in the topic Calculating resource structure entry and element values. Valid values are from 1 to 65,535. The default is 1.

ENTRY=

Specifies the entry value of the entry-to-element ratio for resources that are used to allocate the resource structure. Each resource is stored on the resource structure using one entry and either zero, one, or more elements. The number of entries is equal to the number of resources. To calculate the number of entries needed, use the formulas in the topic Calculating resource structure entry and element values. Valid values are from 1 to 65,535. The default is 1.

For a structure defined with ALLOWAUTOALT(NO) in the CFRM policy, you must cold start the structure to change the entry-to-element ratio. This is because once CQS connects to a structure, it preserves the actual number of entries and elements obtained. If a structure rebuild occurs, CQS uses the actual entry-to-element ratio from these saved values when it connects to the rebuild structure, and not the values from ELEMENT or ENTRY. This is done to ensure that the rebuild structure has a similar number of entries and elements as the old structure, to reduce the chance of a rebuild failure.

For a structure defined with ALLOWAUTOALT(YES), you still must cold start the structure to change the entry-to-element ratio to a specific value (for example, to set the ratio to a value you have computed based on your message sizes). However, z/OS dynamically changes the entry-to-element ratio if it is not correct for the size of the objects in the structure.

Recommendation: Define your resource structure with the ALLOWAUTOALT(YES) parameter, to allow z/OS to dynamically adjust the entry-to-element ratio as necessary.