DEFINE CFSTRUCT on z/OS

Use the MQSC command DEFINE CFSTRUCT to define queue manager CF level capability, message offload environment, and backup and recovery parameters for a coupling facility application structure.

Use MQSC commands

For information on how we use MQSC commands, see Performing local administration tasks using MQSC commands.

We can issue this command from sources 2CR. For an explanation of the source symbols, see Sources from which we can issue MQSC commands on z/OS .

• Syntax diagram
• Usage notes for DEFINE CFSTRUCT
• Parameter descriptions for DEFINE CFSTRUCT

Synonym: DEF CFSTRUCT

DEFINE CFSTRUCT

Offload attributes

Usage notes for DEFINE CFSTRUCT

1. This command is valid only on z/OS when the queue manager is a member of a queue sharing group.
2. This command cannot specify the CF administration structure (CSQ_ADMIN).
3. Before any newly defined CF structure can be used by any queues, the structure must be defined in the Coupling Facility Resource Management (CFRM) policy data set.
4. Only CF structures with RECOVER(YES) defined can be backed up and recovered.

Parameter descriptions for DEFINE CFSTRUCT

(structure-name)

Name of the coupling facility application structure that has queue manager CF level capability and backup and recovery parameters we want to define. This parameter is required.

The name:

• Cannot have more than 12 characters.
• Must start with an uppercase letter (A through Z).
• Can include only the characters A through Z and 0 through 9.

The name of the queue sharing group to which the queue manager is connected is prefixed to the name you supply. The name of the queue sharing group is always four characters, padded with @ symbols if necessary. For example, if we use a queue sharing group named NY03 and you supply the name PRODUCT7, the resultant coupling facility structure name is NY03PRODUCT7. The administrative structure for the queue sharing group (in this case NY03CSQ_ADMIN) cannot be used for storing messages.

CFCONLOS

This parameter specifies the action to be taken when a queue manager loses connectivity to the CF structure. The value can be:

ASQMGR

The action taken is based on the setting of the CFCONLOS queue manager attribute.

TERMINATE

The queue manager ends when connectivity to the structure is lost.

TOLERATE

The queue manager tolerates loss of connectivity to the structure without terminating.

This parameter is only valid from CFLEVEL(5).

CFLEVEL( integer )

Specifies the functional capability level for this CF application structure. Value can be one of the following:

1

A CF structure that can be "auto-created" by a queue manager at command level 520.

2

A CF structure at command level 520 that can only be created or deleted by a queue manager at command level 530 or greater.

3

A CF structure at command level 530. This CFLEVEL is required if we want to use persistent messages on shared queues (if RECOVER(YES) is set), or for message grouping (when a local queue is defined with INDXTYPE(GROUPID)), or both.

We can only increase the value of CFLEVEL to 3 if all the queue managers in the queue sharing group are at command level 530 or greater - this is to ensure that there are no latent command level 520 connections to queues referencing the structure.

We can only decrease the value of CFLEVEL from 3 if all the queues that reference the CF structure are both empty (have no messages or uncommitted activity) and closed.

4

This CFLEVEL supports all the CFLEVEL(3) functions. CFLEVEL(4) allows queues defined with CF structures at this level to have messages with a length greater than 63 KB.

Only a queue manager with a command level of 600 or above can connect to a CF structure at CFLEVEL(4).

We can only increase the value of CFLEVEL to 4 if all the queue managers in the queue sharing group are at command level 600 or greater.

We can only decrease the value of CFLEVEL from 4 if all the queues that reference the CF structure are both empty (have no messages or uncommitted activity) and closed.

5

This CFLEVEL supports all functions for CFLEVEL(4). In addition, CFLEVEL(5) enables the following new functions. If altering an existing CFSTRUCT to CFLEVEL(5), we must review other attributes as indicated:

• queues defined with CF structures at this level can have message data offloaded to either shared message data sets (SMDS), or Db2, under control of the OFFLOAD attribute. The offload threshold and size parameters (such as OFFLD1TH, and OFFLD1SZ) determine whether any particular messages are offloaded given its size and current CF structure utilization. If using SMDS offload, the DSGROUP, DSBUFS, DSEXPAND and DSBLOCK attributes are respected.
• structures at CFLEVEL(5) allow the queue manager to tolerate a loss of connectivity to the CF structure. The CFCONLOS attribute determines queue manager behavior when a loss of connectivity is detected, and the RECAUTO attribute controls subsequent automatic structure recovery behavior.
• messages containing IBM MQ message properties are stored in a different format on shared queues in a CFLEVEL(5) structure. This format leads to internal processing optimizations. Additional application migration capabilities are also available and these are enabled via the queue PROPCTL attribute.

Only a queue manager with a command level of 710 or above can connect to a CF structure at CFLEVEL(5).

Note:

We can decrease the value of CFLEVEL from 5 if all the queues that reference the CF structure are both empty, that is the queues, and CF structure have no messages or uncommitted activity, and are closed.

DESCR( string )

Plain-text comment that provides descriptive information about the object when an operator issues the DISPLAY CFSTRUCT command.

The string should contain only displayable characters. The maximum length is 64 characters. In a DBCS installation, it can contain DBCS characters (subject to a maximum length of 64 bytes).

Note: If characters are used that are not in the coded character set identifier (CCSID) for this queue manager, they might be translated incorrectly if the information is sent to another queue manager.

LIKE( cfstruct-name )

The name of a CFSTRUCT object, with attributes used to model this definition.

The initial values of all attributes are copied from the object, except any DSGROUP attribute is ignored because each structure requires its own unique value.

OFFLOAD

Specify whether offloaded message data is to be stored in a group of shared message data sets or in Db2.

SMDS

Offload messages from coupling facility to shared message data set (SMDS). This value is the default assumption when a new structure is defined with CFLEVEL(5).

DB2

Offload messages from coupling facility to Db2. This value is the default assumption when an existing structure is increased to CFLEVEL(5) using DEFINE with the REPLACE option.

Offloading messages using Db2 has significant performance impact. To use the offload rules as a means of increasing capacity, the SMDS option should be specified or assumed.

This parameter is only valid from CFLEVEL(5). At CFLEVEL(4) any message offloading is always to Db2, and only applies to messages greater than the maximum coupling facility entry size. Note:

If we change the offload technique (from Db2 to SMDS or the other way) then all new messages will be written using the new method but any existing large messages stored using the previous technique can still be retrieved. The relevant Db2 message table or shared message data sets will continue to be used until the queue managers have detected that there are no further messages stored in the old format.

If SMDS is specified or assumed, then the DSGROUP parameter is also required. It can be specified either on the same command or on a previous DEFINE or ALTER command for the same structure.

OFFLD1TH(percentage) OFFLD1SZ(size)

OFFLD2TH(percentage) OFFLD2SZ(size)

OFFLD3TH(percentage) OFFLD3SZ(size)

Specify rules for when messages smaller than the maximum coupling facility entry size are to be offloaded to external storage (shared message data sets or Db2 tables) instead of being stored in the application structure. These rules can be used to increase the effective capacity of the structure. The offloaded message still requires an entry in the coupling facility containing message control information, and a descriptor referring to the offloaded message data, but the amount of structure space required is less than the amount that would be needed to store the whole message.

If the message data is very small (of the order of 100 bytes) it might fit into the same coupling facility entry as the message control information, without needing additional data elements. In this case, no space can be saved, so any offload rules are ignored and the message data is not offloaded. The actual number varies, depending whether more than the default headers are used, or if message properties are being stored.

Messages exceeding the maximum coupling facility entry size (63.75 KB including control information) are always offloaded as they cannot be stored in a coupling facility entry. Messages where the message body exceeds 63 KB are also offloaded to ensure that enough space is available for the control information. Additional rules to request offloading of smaller messages can be specified using these pairs of keywords. Each rule indicates that when the usage of the structure (in either elements or entries) exceeds the specified threshold percentage value, the message data will be offloaded if the total size of the coupling facility entry required to store the whole message (including message data, headers and descriptors) exceeds the specified size value. The minimal set of headers and descriptors require approximately 400 bytes, however this could be greater if other headers or properties are added. This figure would also be greater if an MQMD version greater than 1 is used.

percentage

The usage threshold percentage value is an integer in the range 0 (meaning this rule always applies) to 100 (meaning this rule only applies when the structure is full). For example, OFFLD1TH(75) OFFLD1SZ(32K) means that when the structure is over 75% full, messages greater than 32 kilobytes in size are offloaded.

size

The message size value should be specified as an integer followed by K, giving the number of kilobytes in the range 0K to 64K. As messages exceeding 63.75 KB are always offloaded, the value 64K is allowed as a simple way to indicate that the rule is not being used.

In general, the smaller the numbers, the more messages are offloaded.

A message is offloaded if any offload rule matches. The normal convention is that a later rule would be for a higher usage level and a smaller message size than an earlier one, but no check is made for consistency or redundancy between the rules.

When structure ALTER processing is active, the number of used elements or entries can temporarily exceed the reported total number, giving a percentage exceeding 100, because the new elements or entries are made available during ALTER processing but the total is only updated when the ALTER completes. At such times, a rule specifying 100 for the threshold may temporarily take effect. If a rule is not intended to be used at all, it should specify 64K for the size.

The default values assumed for the offload rules when defining a new structure at CFLEVEL(5) or upgrading an existing structure to CFLEVEL(5) depend on the OFFLOAD method option. For OFFLOAD(SMDS), the default rules specify increasing amounts of offloading as the structure becomes full. This increases the effective structure capacity with minimal performance impact. For OFFLOAD( Db2 ), the default rules have the same threshold values as for SMDS but the size values are set to 64K so that the rules never apply and messages are offloaded only if they are too large to be stored in the structure, as for CFLEVEL(4).

For OFFLOAD(SMDS) the defaults are:

• OFFLD1TH(70) OFFLD1SZ(32K)
• OFFLD2TH(80) OFFLD2SZ(4K)
• OFFLD3TH(90) OFFLD3SZ(0K)

For OFFLOAD( Db2 ) the defaults are:

• OFFLD1TH(70) OFFLD1SZ(64K)
• OFFLD2TH(80) OFFLD2SZ(64K)
• OFFLD3TH(90) OFFLD3SZ(64K)

If the OFFLOAD method option is changed from Db2 to SMDS or back when the current offload rules all match the default values for the old method, the offload rules are switched to the default values for the new method. However, if any of the rules have been changed, the current values are kept when switching method.

These parameters are only valid from CFLEVEL(5). At CFLEVEL(4) any message offloading is always to Db2, and only applies to messages greater than the maximum coupling facility entry size.

DSGROUP

For OFFLOAD(SMDS), specify the generic data set name to be used for the group of shared message data sets associated with this structure (one for each queue manager), with exactly one asterisk indicating where the queue manager name should be inserted to form the specific data set name.

dsname.prefix.*.dsname.suffix

The value must be a valid data set name when the asterisk is replaced by a queue manager name of up to four characters.

The entire parameter value must be enclosed in quotation marks.

This parameter cannot be changed after any data sets have been activated for the structure.

If SMDS is specified or assumed, then the DSGROUP parameter must also be specified.

This parameter is only valid from CFLEVEL(5).

DSBLOCK

For OFFLOAD(SMDS), specify the logical block size, which is the unit in which shared message data set space is allocated to individual queues.

8K

16K

32K

64K

128K

256K

512K

1M

Each message is written starting at the next page within the current block and is allocated further blocks as needed. A larger size decreases space management requirements and reduces I/O for large messages, but increases buffer space requirements and disk space requirements for small queues.

This parameter cannot be changed after any data sets have been activated for the structure.

This parameter is only valid from CFLEVEL(5).

DSBUFS

For OFFLOAD(SMDS), specify the number of buffers to be allocated in each queue manager for accessing shared message data sets, as a number in the range 1 - 9999. The size of each buffer is equal to the logical block size. SMDS buffers are allocated in memory objects residing in z/OS 64-bit storage (above the bar).

number

This parameter can be overridden for individual queue managers using the DSBUFS parameter on ALTER SMDS.

When this parameter is altered, any queue managers which are already connected to the structure (and which do not have an individual DSBUFS override value) dynamically increase or decrease the number of data set buffers being used for this structure to match the new value. If the specified target value cannot be reached, the affected queue manager adjusts the DSBUFS parameter associated with its own individual SMDS definition (as for the ALTER SMDS command) to match the actual new number of buffers.

This parameter is only valid from CFLEVEL(5).

DSEXPAND

For OFFLOAD(SMDS), this parameter controls whether the queue manager should expand a shared message data set when it becomes nearly full, and further blocks are required in the data set.

YES

Expansion is supported.

Each time expansion is required, the data set is expanded by the secondary allocation specified when the data set was defined. If no secondary allocation was specified, or it was specified as zero, then a secondary allocation amount of approximately 10% of the existing size is used

NO

No automatic data set expansion is to take place.

This parameter can be overridden for individual queue managers using the DSEXPAND parameter on ALTER SMDS.

If an expansion attempt fails, the DSEXPAND override for the affected queue manager is automatically changed to NO to prevent further expansion attempts, but it can be changed back to YES using the ALTER SMDS command to enable further expansion attempts.

When this parameter is altered, any queue managers which are already connected to the structure (and which do not have an individual DSEXPAND override value) immediately start using the new parameter value.

This parameter is only valid from CFLEVEL(5).

RECOVER

Specifies whether CF recovery is supported for the application structure. Values are:

NO

CF application structure recovery is not supported. (The synonym is N.)

YES

CF application structure recovery is supported. (The synonym is Y.)

We can only set RECOVER(YES) if the structure has a CFLEVEL of 3 or higher. Set RECOVER(YES) if you intend to use persistent messages.

We can only change RECOVER(NO) to RECOVER(YES) if all the queue managers in the queue sharing group are at command level 530 or greater; this is to ensure that there are no latent command level 520 connections to queues referencing the CFSTRUCT.

We can only change RECOVER(YES) to RECOVER(NO) if all the queues that reference the CF structure are both empty (have no messages or uncommitted activity) and closed.

RECAUTO

Specifies the automatic recovery action to be taken when a queue manager detects that the structure is failed or when a queue manager loses connectivity to the structure and no systems in the sysplex have connectivity to the coupling facility that the structure is allocated in. Values can be:

YES

The structure and associated shared message data sets which also need recovery will be automatically recovered (The synonym is Y.)

NO

The structure will not be automatically recovered. (The synonym is N.)

This parameter has no effect for structures defined with RECOVER(NO).

This parameter is only valid from CFLEVEL(5).

REPLACE and NOREPLACE

Defines whether the existing definition is to be replaced with this one. This parameter is optional.

REPLACE

The definition should replace any existing definition of the same name. If a definition does not exist, one is created. If we use the REPLACE option, all queues that use this CF structure must be empty and closed.

NOREPLACE

The definition should not replace any existing definition of the same name.

Parent topic: MQSC commands