Plan the 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
- Plan the shared message data set (SMDS) environment
- Plan the Db2 environment
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.
Plan the 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.
- Use 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 we 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.
- 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).
Plan 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. We 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.
| 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.
| 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(272144) /* 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, we 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.
We 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.
| 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)