Plan your coupling facility and offload storage environment
Use this topic when planning the initial sizes, and formats of our coupling facility
(CF) structures, and shared message data set (SMDS) environment or Db2 environment.
This section contains information about the following topics:
If you intend to use shared queues, we must define the coupling facility structures that
IBM MQ will use in your CFRM policy. To do this we 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.
We must add statements to the policy that defines 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 resilience to failures that affect the coupling facility.
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 can optionally be offloaded to reduce coupling
facility space usage.
A queue sharing group (QSG) 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-nameCSQ_ADMIN
(where qsg-name is the name of our queue sharing group). Subsequent
structures are known as application strucutres, and are used to hold the messages on
IBM MQ shared queues. Each structure can hold
up to 512 shared queues.
An application structure named qsg-nameCSQSYSAPPL is used for system queues.
Defining this structure is optional, but it is required in order to use certain features. By default,
the SYSTEM.QSG.CHANNEL.SYNCQ and SYSTEM.QSG.UR.RESOLUTION.QUEUE queues are defined on the
qsg-nameCSQSYAPPL structure.
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. If it is defined, another of these structures might
be the qsg-nameCSQSYSAPPL structure. We can use up to 63 (62 if
qsg-nameCSQSYSAPPL is defined) structures for message data.
We might choose to use multiple application structures for any of the following reasons:
We have some queues that are likely to hold a large number of messages and so require all the
resources of an entire coupling facility.
We 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 we 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).
Plan the size of our structures
The administrative structure
The administrative structure (qsg-nameCSQ_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 qsg-nameCSQ_ADMIN
structure:
Issue MQSC command DISPLAY CFSTATUS(CSQ_ADMIN) on an existing member of the
queue sharing group.
Extract the ENTSMAX information for the CSQ_ADMIN structure.
If this number is less than 1000 times the total number of queue managers we want to define in
the queue sharing group, increase the structure size.
Application structures
The size of the application structures required to hold IBM MQ messages depends on the likely number and size of the messages to be held on a structure
concurrently.
The graph in Figure 1
shows how large we should make your CF structures to hold the messages on your shared queues. To
calculate the allocation size we need the following information:
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.
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 512 MB.
Table 2
provides the same information in tabular form.
Figure 1. Calculating the size of a coupling facility structure
Use this table to help calculate how large to make your coupling facility structures:
Number of messages
1 KB
2 KB
4 KB
8 KB
16 KB
32 KB
63 KB
100
6 MB
6 MB
7 MB
7 MB
8 MB
10 MB
14 MB
1000
8 MB
9 MB
12 MB
17 MB
27 MB
48 MB
88 MB
10000
25 MB
38 MB
64 MB
115 MB
218 MB
423 MB
821 MB
100000
199 MB
327 MB
584 MB
1097 MB
2124 MB
4177 MB
8156 MB
Your CFRM policy should include the following statements:
INITSIZE is the size in KB that the structure is allocated with when the first
queue manager connects to it.
SIZE is the maximum size that the structure can attain.
FULLTHRESHOLD sets the percentage value of the threshold at which
z/OS 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)
If the structure use reaches the threshold where warning messages are issued, intervention is
required. We 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 z/OS facilities to alter
the structure size in place. The following z/OS command:
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 CFSTATUS 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.
The CSQSYSAPPL structure
The qsg-nameCSQSYSAPPL structure is an application structure for system queues.
Table 3
demonstrates an example of how to estimate the message data sizes for the default queues defined on
the qsg-nameCSQSYSAPPL structure.
qsg-nameCSQSYSAPPL 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:
These values can be adjusted depending on your use of shared channels and group units of
recovery.
Mapping shared queues to structures
To define an application structure to IBM MQ, use
the DEFINE CFSTRUCT command.
When you define a structure to IBM MQ, do not include the
QSG name prefix in the structure name. For example, to define an application structure
to IBM MQ that has the name
qsg-nameAPPLICATION1 in the CFRM policy, issue the following command:
DEFINE CFSTRUCT(APPLICATION1)
The CFSTRUCT attribute of the queue definition is used to map the queue to a structure. Specify
the name of the CF structure without the QSG name prefix in this attribute. For example, the following
command defines a shared queue on the APPLICATION1 structure:
Plan your shared message data set (SMDS) environment
If we are using queue sharing groups with SMDS offloading, IBM MQ needs to connect to a group of shared message data sets. Use this topic to help understand the data set requirements, and configuration required to store IBM MQ message data.
Plan your Db2 environment
If we are using queue sharing groups, IBM MQ needs to attach to a Db2 subsystem that is a member of a data sharing group. Use this topic to help understand the Db2 requirements used to hold IBM MQ data.
