Planning your coupling facility and offload storage environment

Use this topic when planning the initial sizes, and formats of your coupling facility (CF) structures, and shared message data set (SMDS) environment or Db2® environment.

This section contains information about the following topics:

Defining coupling facility resources

If you intend to use shared queues, you must define the coupling facility structures that IBM MQ will use in your CFRM policy. To do this you must first update your CFRM policy with information about the structures, and then activate the policy.

Your installation probably has an existing CFRM policy that describes the Coupling Facilities available. The IXCMIAPU z/OS® utility is used to modify the contents of the policy based on textual statements you provide. The utility is described in the MVS Setting up a Sysplex manual. You must add statements to the policy that define the names of the new structures, the Coupling Facilities that they are defined in, and what size the structures are.

The CFRM policy also determines whether IBM MQ structures are duplexed and how they are reallocated in failure scenarios. Shared queue recovery contains recommendations for configuring CFRM for System Managed Rebuild processing.

Deciding your offload storage environment

The message data for shared queues can be offloaded from the coupling facility and stored in either a Db2 table or in an IBM MQ managed data set called a shared message data set (SMDS). Messages which are too large to store in the coupling facility (that is, larger than 63 KB) must always be offloaded, and smaller messages may optionally be offloaded to reduce coupling facility space usage.

For more information, see Specifying offload options for shared messages.

Planning your structures

A queue-sharing group requires a minimum of two structures to be defined. The first structure, known as the administrative structure, is used to coordinate IBM MQ internal activity across the queue-sharing group. No user data is held in this structure. It has a fixed name of qsg-name CSQ_ADMIN (where qsg-name is the name of your queue-sharing group). Subsequent structures are used to hold the messages on IBM MQ shared queues. Each structure can hold up to 512 shared queues.

Using multiple structures
A queue-sharing group can connect to up to 64 coupling facility structures. One of these structures must be the administration structure, one of these structures might be the SYSAPPL structure. So you can use up to 63 (62 with SYSAPPL) structures for IBM MQ data. You might choose to use multiple structures for any of the following reasons:
  • You have some queues that are likely to hold a large number of messages and so require all the resources of an entire coupling facility.
  • You have a requirement for a large number of shared queues, so they must be split across multiple structures because each structure can contain only 512 queues.
  • RMF reports on the usage characteristic of a structure suggest that you should distribute the queues it contains across a number of Coupling Facilities.
  • You want some queue data to held in a physically different coupling facility from other queue data for data isolation reasons.
  • Recovery of persistent shared messages is performed using structure level attributes and commands, for example BACKUP CFSTRUCT. To simplify backup and recovery, you could assign queues that hold nonpersistent messages to different structures from those structures that hold persistent messages.
When choosing which Coupling Facilities to allocate the structures in, consider the following points:
  • Your data isolation requirements.
  • The volatility of the coupling facility (that is, its ability to preserve data through a power outage).
  • Failure independence between the accessing systems and the coupling facility, or between Coupling Facilities.
  • The level of coupling facility Control Code (CFCC) installed on the coupling facility ( IBM MQ requires Level 9 or higher).

Planning the size of your structures

The administrative structure ( qsg-name CSQ_ADMIN) must be large enough to contain 1000 list entries for each queue manager in the queue-sharing group. When a queue manager starts, the structure is checked to see if it is large enough for the number of queue managers currently defined to the queue-sharing group. Queue managers are considered as being defined to the queue-sharing group if they have been added by the CSQ5PQSG utility. You can check which queue managers are defined to the group with the MQSC DISPLAY GROUP command.

Table 1 shows the minimum required size for the administrative structure for various numbers of queue managers defined in the queue-sharing group. These sizes were established for a CFCC level 14 coupling facility structure; for higher levels of CFCC, they probably need to be larger.

Table 1. Minimum administrative structure sizes
Number of queue managers defined in queue-sharing group Required storage
1 6144 KB
2 6912 KB
3 7976 KB
4 8704 KB
5 9728 KB
6 10496 KB
7 11520 KB
8 12288 KB
9 13056 KB
10 14080 KB
11 14848 KB
12 15616 KB
13 16640 KB
14 17408 KB
15 18176 KB
16 19200 KB
17 19968 KB
18 20736 KB
19 21760 KB
20 22528 KB
21 23296 KB
22 24320 KB
23 25088 KB
24 25856 KB
25 27136 KB
26 27904 KB
27 28672 KB
28 29696 KB
29 30464 KB
30 31232 KB
31 32256 KB

When you add a queue manager to an existing queue-sharing group, the storage requirement might have increased beyond the size recommended in Table 1. If so, use the following procedure to estimate the required storage for the CSQ_ADMIN structure: Issue MQSC command /pf DISPLAY CFSTATUS(*), where /cpf is for an existing member of the queue-sharing group, and extract the ENTSMAX information for the CSQ_ADMIN structure. If this number is less than 1000 times the total number of queue managers you want to define in the queue-sharing group (as reported by the DISPLAY GROUP command), increase the structure size.

The size of the structures required to hold IBM MQ messages depends on the likely number and size of the messages to be held on a structure concurrently, together with an estimate of the likely number of concurrent units of work.

The graph in Figure 1 shows how large you should make your CF structures to hold the messages on your shared queues. To calculate the allocation size you need to know
  • The average size of messages on your queues
  • The total number of messages likely to be stored in the structure

Find the number of messages along the horizontal axis. (Ticks are at multiples of 2, 5, and 8.) Select the curve that corresponds to your message size and determine the required value from the vertical axis. For example, for 200 000 messages of length 1 KB gives a value in the range 256 through 512MB.

Table 2 provides the same information in tabular form.

Figure 1. Calculating the size of a coupling facility structure
Use the following table to help calculate how large to make your coupling facility structures
Use this table to help calculate how large to make your coupling facility structures:
Table 2. Calculating the size of a coupling facility structure
Number of messages 1 KB 2 KB 4 KB 8 KB 16 KB 32 KB 63 KB
100 6 6 7 7 8 10 14
1000 8 9 12 17 27 48 88
10000 25 38 64 115 218 423 821
100000 199 327 584 1097 2124 4177 8156

Your CFRM policy should include the following statements:

INITSIZE is the size in KB that XES allocates to the structure when the first connector connects to it. SIZE is the maximum size that the structure can attain. FULLTHRESHOLD sets the percentage value of the threshold at which XES issues message IXC585E to indicate that the structure is getting full. A best practice is to ensure that INITSIZE and SIZE are within a factor of 2.

For example, with the figures determined previously, you might include the following statements: 

STRUCTURE NAME(structure-name)
INITSIZE(value from graph in KB, that is, multiplied by 1024)
SIZE(something larger)
FULLTHRESHOLD(85)


STRUCTURE NAME(QSG1APPLICATION1)
INITSIZE(262144) /* 256 MB */
SIZE(524288) /* 512 MB */
FULLTHRESHOLD(85)

If the structure use reaches the threshold where warning messages are issued, intervention is required. You might use IBM MQ to inhibit MQPUT operations to some of the queues in the structure to prevent applications from writing more messages, start more applications to get messages from the queues, or quiesce some of the applications that are putting messages to the queue.

Alternatively, you can use XES facilities to alter the structure size in place. The following z/OS command: 

SETXCF START,ALTER,STRNAME= structure-name,SIZE= newsize

alters the size of the structure to newsize, where newsize is a value that is less than the value of SIZE specified on the CFRM policy for the structure, but greater than the current coupling facility size.

You can monitor the use of a coupling facility structure with the MQSC DISPLAY GROUP command.

If no action is taken and a queue structure fills up, an MQRC_STORAGE_MEDIUM_FULL return code is returned to the application. If the administration structure becomes full, the exact symptoms depend on which processes experience the error, but they might include the following problems:
  • No responses to commands.
  • Queue manager failure as a result of problems during commit processing.
Certain system queues are provided with CFSTRUCT attributes which specify an application structure CSQSYSAPPL prefixed with the queue-sharing group name. The CSQSYSAPPL structure is an application structure for system queues. For details of creating the coupling facility structures see Task 10: Set up the coupling facility.
With the default definitions, the SYSTEM.QSG.CHANNEL.SYNCQ and SYSTEM.QSG.UR.RESOLUTION.QUEUE use this structure. Table 3 demonstrates an example of how to estimate the message data sizes for the default queues.
Table 3. Table showing CSQSYSAPPL usage against sizing.
qsg-name CSQSYSAPPL usage sizing
SYSTEM.QSG.CHANNEL.SYNCQ 2 messages of 500 bytes per active instance of a shared channel
SYSTEM.QSG.UR.RESOLUTION.QUEUE 1000 messages of 2 KB

The suggested initial structure definition values are as follows: 


STRUCTURE NAME(qsgname CSQSYSAPPL)
INITSIZE(20480)          /* 20 MB */
SIZE(30720)            /* 30 MB */
FULLTHRESHOLD(85)

These values can be adjusted depending on your use of shared channels and group units of recovery.

Mapping shared queues to structures

The CFSTRUCT attribute of the queue definition is used to map the queue to a structure.

IBM MQ adds the name of the queue-sharing group to the beginning of the CFSTRUCT attribute. For a structure defined in the CFRM policy with name qsg-name SHAREDQ01, the definition of a queue that uses this structure is: 

DEFINE QLOCAL( myqueue ) QSGDISP(SHARED) CFSTRUCT(SHAREDQ01)