If you 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.
A
shared message data set (described by the keyword SMDS) is a data set used by a queue
manager to store offloaded message data for shared messages stored in a coupling facility structure.
Note: When defining SMDS data sets for a structure, you must have one for each queue
manager.
When this form of data offloading is enabled, the CFSTRUCT requires an
associated group of shared message data sets, one data set for each queue manager in the
queue sharing group. The group of shared message data sets is defined to IBM MQ using the DSGROUP parameter on the
CFSTRUCT definition. Additional parameters can be used to supply further
optional information, such as the number of buffers to use and expansion attributes for the data
sets.
Each queue manager can write to the data set which it owns, to store shared message data for
messages written through that queue manager, and can read all of the data sets in the group.
A list describing the status and attributes for each data set associated with the structure is
maintained internally as part of the CFSTRUCT definition, so each queue manager
can check the definition to find out which data sets are currently available.
This data set information can be displayed using the DISPLAY CFSTATUS
TYPE(SMDS) command to display current status and availability, and the DISPLAY
SMDS command to display the parameter settings for the data sets associated with a
specified CFSTRUCT.
Individual shared message data sets are effectively identified by the combination of the owning
queue manager name (usually specified using the SMDS keyword) and the
CFSTRUCT structure name.
This section describes the following topics:
See DEFINE CFSTRUCT for
details of these parameters.
For information on managing your shared message data sets, see Managing shared message data sets for
further details.
The DSGROUP parameter
The DSGROUP parameter on the CFSTRUCT definition
identifies the group of data sets in which large messages for that structure are to be stored.
Additional parameters may be used to specify the logical block size to be used for space allocation
purposes and values for the buffer pool size and automatic data set expansion options.
The
DSGROUP parameter must be set up before offloading to data sets can be enabled.
- If a new CFSTRUCT is being defined at CFLEVEL(5) and
the option OFFLOAD(SMDS) is specified or assumed, then the
DSGROUP parameter must be specified on the same command.
- If an existing CFSTRUCT is being altered to increase the
CFLEVEL to CFLEVEL(5) and the option
OFFLOAD(SMDS) is specified or assumed, then the DSGROUP
parameter must be specified on the same command if it is not already set.
The DSBLOCK parameter
Space within each data set is allocated to queues as logical blocks of a fixed size (usually 256
KB) specified using the DSBLOCK parameter on the CFSTRUCT
definition, then allocated to individual messages as ranges of pages of 4 KB (corresponding to the
physical block size and control interval size) within each logical block. The logical block size
also determines the maximum amount of message data that can be read or written in a single I/O
operation, which is the same as the buffer size for the SMDS buffer pool.
A larger value of the DSBLOCK parameter can improve performance for very
large messages by reducing the number of separate I/O operations. However, a smaller value decreases
the amount of buffer storage required for each active request. The default value for the
DSBLOCK parameter is 256 KB, which provides a reasonable balance between these
requirements, so specifying this parameter might not normally be necessary.
Shared message data set characteristics
A shared message data set is defined as a VSAM linear data set (LDS). Each offloaded message is
stored in one or more blocks in the data set. The stored data is addressed directly by information
in the coupling facility entries, like an extended form of virtual storage. There is no separate
index or similar control information stored in the data set itself.
The direct addressing scheme means that for messages which fit into one block, only a single I/O
operation is needed to read or write the block. When a message spans more than one block, the I/O
operations for each block can be fully overlapped to minimize elapsed time, provided that sufficient
buffers are available.
The shared message data set also contains a small amount of general control information,
consisting of a header in the first page, which includes recovery and restart status information,
and a space map checkpoint area which is used to save the free block space map at queue manager
normal termination.
Shared message data set space management
As background information for capacity, performance and operational considerations, it might be
useful to understand the concepts of how space in shared message data sets is managed by the queue
managers.
Free space in each shared message data set is tracked by its owning queue manager using a space
map which indicates the number of pages in use within each logical block. The space map is
maintained in main storage while the data set is open and saved in the data set when it is closed
normally. (In recovery situations the space map is automatically rebuilt by scanning the messages in
the coupling facility structure to find out which data set pages are currently in use).
When a shared message with offloaded message data is being written, the queue manager allocates a
range of pages for each message block. If there is a partly used current logical block for the
specified queue, the queue manager allocates space starting at the next free page in that block,
otherwise it allocates a new logical block. If the whole message does not fit within the current
logical block, the queue manager splits the message data at the end of the logical block and
allocates a new logical block for the next message block. This is repeated until space has been
allocated for the whole message. Any unused space in the last logical block is saved as the new
current logical block for the queue. When the data set is closed normally, any unused pages in
current logical blocks are returned to the space map before it is saved.
When a shared message with offloaded message data has been read and is ready to be deleted, the
queue manager processes the delete request by transferring the coupling facility entry for the
message to a clean-up list monitored by the owning queue manager (which may be the same queue
manager). When entries arrive on this list, the owning queue manager reads and deletes the entries
and returns the freed ranges of pages to the space map. When all used pages in a logical block have
been freed the block becomes available for reuse.
Access to shared message data sets
Each shared message data set must be on shared direct access storage which is accessible to all
queue managers in the queue sharing group.
During normal running, each queue manager opens its own shared message data set for read/write
access, and opens any active shared message data sets for other queue managers for read-only access,
so it can read messages stored by those queue managers. This means that each queue manager userid
requires at least UPDATE access to its own shared message data set and READ access to all other
shared message data sets for the structure.
If it is necessary to recover shared message data sets using RECOVER CFSTRUCT,
the recovery process can be executed from any queue manager in the queue sharing group. A queue
manager which may be used to perform recovery processing requires UPDATE access to all data sets
that it may need to recover
Creating a shared message data set
Each shared message data set should normally be created before the corresponding
CFSTRUCT definition is created or altered to enable the use of this form of
message offloading, as the CFSTRUCT definition changes will normally take
effect immediately, and the data set will be required as soon as a queue manager attempts to access
a shared queue which has been assigned to that structure. A sample job to allocate and pre-format a
shared message data set is provided in SCSQPROC(CSQ4SMDS). The job must be customized and run to
allocate a shared message data set for each queue manager which uses a CFSTRUCT with OFFLOAD(SMDS).
If the queue manager finds that offload support has been enabled and tries to open its shared
message data set but it has not yet been created, the shared message data set will be flagged as
unavailable. The queue manager will then be unable to store any large messages until the data set
has been created and the queue manager has been notified to try again, for example using the
START SMDSCONN command.
A shared message data set is created as a VSAM linear data set using an Access Method Services
DEFINE CLUSTER command. The definition must specify SHAREOPTIONS(2
3) to allow one queue manager to open it for write access and any number of queue
managers to read it at the same time. The default control interval size of 4 KB must be used. If the
data set may need to expand beyond 4 GB, it must be defined using an SMS data class which has the
VSAM extended addressability attribute. A shared message data set is eligible to reside in the
extended addressing space (EAS) part of an extended address volumes (EAV).
Each shared message data set can either be empty or pre-formatted to binary zeros (using
CSQJUFMT or a similar utility such as the sample job SCSQPROC(CSQ4SMDS)), before
its initial use. If it is empty or only partly formatted when it is opened, the queue manager
automatically formats the remaining space to binary zeros.
Shared message data set performance and capacity considerations
Each shared message data set is used to store offloaded data for shared messages written to the
associated CFSTRUCT by the owning queue manager, from regions within the same
system. The stored data for each message includes a descriptor (currently about 350 bytes), the
message headers and the message body. Each offloaded message is stored in one or more pages
(physical blocks of size 4 KB) in the data set.
The data set space required for a given number of offloaded messages can therefore be estimated
by rounding up the overall message size (including the descriptor) to the next multiple of 4 KB and
then multiplying by the number of messages.
As for a page set, when a shared message data set is almost full, it can optionally be expanded
automatically. The default behavior for this automatic expansion can be set using the
DSEXPAND parameter on the CFSTRUCT definition. This
setting can be overridden for each queue manager using the DSEXPAND parameter
on the ALTER SMDS command. Automatic expansion is triggered when the data set
reaches 90% full and more space is required. If expansion is allowed but an expansion attempt is
rejected by VSAM because no secondary space allocation was specified when the data set was defined,
expansion is retried using a secondary allocation of 20% of the current size of the data set.
Provided that the shared message data set is defined with the extended addressability attribute,
the maximum size is only limited by VSAM considerations to a maximum of 16 TB or 59 volumes. This is
significantly larger than the 64 GB maximum size of a local page set.
Activating a shared message data set
When a queue manager has successfully connected to an application coupling facility structure, it
checks whether that structure definition specifies offloading using an associated
DSGROUP parameter. If so, the queue manager allocates and opens its own shared
message data set for write access, then it opens for read access any existing shared message data
sets owned by other queue managers.
When a shared message data set is opened for the first time (before it has been recorded as
active within the queue sharing group), the first page will not yet contain a valid header. The
queue manager fills in header information to identify the queue sharing group, the structure name
and the owning queue manager.
After the header has been completed, the queue manager registers the new shared message data set
as active and broadcasts an event to notify any other active queue managers about the new data set.
Every time a queue manager opens a shared message data set it validates the header information to
ensure that the correct data set is still being used and that it has not been damaged.