ALTER CFSTRUCT (alter CF application structure) on z/OS

On z/OS®, use the MQSC command ALTER CFSTRUCT to alter the CF application structure backup and recovery parameters, and offload environment parameters for any specified application structure.

Using MQSC commands

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

Parameters not specified in the ALTER CFSTRUCT command result in the existing values for those parameters being left unchanged.

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

Syntax diagram
Usage notes
Parameter descriptions for ALTER CFSTRUCT

Syntax diagram

Synonym: ALT CFSTRUCT

ALTER CFSTRUCT

Offload attributes

Usage notes

This command cannot specify the CF administration structure (CSQ_ADMIN).
This command is valid only when the queue manager is a member of a queue sharing group.

Parameter descriptions for ALTER CFSTRUCT

(structure-name)

Name of the coupling facility application structure with queue manager CF level capability and backup and recovery parameters you 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 you 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 terminates when connectivity to the structure is lost. This is the default value when CFLEVEL is increased to 5.
TOLERATE: The queue manager tolerates loss of connectivity to the structure without terminating.

The CFCONLOS 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 you want to use persistent messages for either one or both of the following reasons:

On shared queues, if RECOVER(YES) is set.
For message grouping when a local queue is defined with INDXTYPE(GROUPID).

You 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.

You 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 greater can connect to a CF structure at CFLEVEL(4).

You 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.

You 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), you 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: You 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.

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).
Db2: Offload messages from coupling facility to Db2. This value is the default assumption when CFLEVEL is increased to 5.

Offloading messages using Db2 has significant performance impact. If you want to use offload rules as a means of increasing capacity, the SMDS option should be specified.

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 you 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, 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 (less than approximately 140 bytes) it may 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.

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. Headers and descriptors typically require approximately 400 bytes.

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).
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.

'data.set.name.*': 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 queue manager name can form all or part of any qualifier in the data set name.; 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, then the DSGROUP parameter must also be specified.

The DSGROUP 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.

The DSBLOCK 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.

These buffers use virtual storage. You should work with the z/OS systems programmer to ensure there is sufficient auxiliary storage available before increasing the number of buffers.

The DSBUFS 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.

The DSEXPAND 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.)

You 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.

You 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.

You 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 are automatically recovered. (The synonym is Y).
NO: The structure is not automatically recovered. (The synonym is N). This is the default value when CFLEVEL is increased to 5.

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

The RECAUTO parameter is only valid from CFLEVEL(5).