MSGQUEUE macro

You must include the MSGQUEUE macro statement when the type of definition specified in the IMSCTRL macro statement is ALL, ON-LINE, CTLBLKS, or NUCLEUS.

Dynamic definition

The characteristics of the three message queue data sets cannot be dynamically defined.

Supported environments

The MSGQUEUE macro can be used in the DB/DC, DBCTL, and DCCTL environments.

Syntax

Positional parameters

The MSGQUEUE macro statement does not include positional parameters.

Keyword parameters

To find which parameters apply to your IMS configuration, refer to Selecting the appropriate macros to define your system.

BUFFERS=

Specifies the number of buffers to allocate for message queue management, and the block size to be assigned for all three message queue data sets. If nbr is not specified, a default of 255 is used. The minimum nbr specification is 3; the maximum is 9999. At execution time, the minimum value for buffers in a shared queues environment is increased to 200. If size3 is not specified, it is calculated by the following formula:

SIZE3 = ((SIZE1+SIZE2-1)/SIZE1) x ((SIZE1+55)/56) x 56

For the division operations in this formula, only the integer portion of the result is used; the fractional portion of the result is truncated.

This calculation can leave null space at the end of the buffer block for short and long message records.

size1 and size2 should be an even multiple of the QBLKS LRECL of 56.

If the RECLNG defaults of size1 (504) and size2 (2520) are used, then size3 of BUFFERS equals 2520. The maximum specification for size3 is 30632, or the track length of the device on which the data set resides, whichever is smaller. All sizes specified are rounded up to multiples of 4.

RECLNG can be changed before a cold start of IMS, but if a smaller value is specified before a BUILDQ restart, the restart might abend.

You should not allocate less space for a restart of IMS than was allocated for the prior execution. If a smaller logical record length has been allocated, or if less space for the Message Queue data sets has been allocated for restart with BUILDQ, the restart process may terminate abnormally.

DSETS=

Specifies the device types on which the three message queue data sets (IMS.QBLKS, IMS.SHMSG, and IMS.LGMSG, respectively) are to reside. If all three data sets are to reside on the same device type, you can specify just the first parameter.

You can specify the following device types: 2305, 3330, 3340, 3350, 3375, 3380, 3390, or LGDK.

When using a 3350, specify the drive format used—3330 or 3350.

LGDK is a generic definition for disk drives that have a track size equal to or greater than 32767 bytes. The 3375, 3380, 3390, and future devices can also be defined as LGDK.

MRQPSBN=

Specifies the one- to eight-character alphanumeric name of the IBM® IMS Queue Control Facility for z/OS® (QCF) program specification block. This parameter allows you to override the default MRQ PSB name. If not specified, the default name of MRQPSB is used by the QCF licensed program. The MRQ program can be either defined in system definition with the APPLCTN macro, or, if DRD is enabled, defined dynamically with the CREATE PGM NAME(MRQPSB) SET(BMPTYPE(Y),SCHDTYPE(PARALLEL)). The default name is MRQPSB. Regardless of whether you use the default name, you must include a PSB for the message region in the stage 1 system definition. If you do not use the default name, you must specify a name for the MRQPSBN block with the MRQPSBN keyword. If an error is made in specifying the MRQPSBN PSB name, a warning message is issued, and the default name is used.

Note: The MRQPSBN block is for the exclusive use of MRQ and QCF programs. It cannot be used by other user application programs running as MPPs, BMPs, or IFPs. If an attempt is made to use the PSB block by some other user application program, IMS returns a status code of MR and an AIBRETRN code of 000000F0 on the call.

RECLNG=

Specifies the logical record lengths for the short and long message queue data sets, respectively.

The minimum value for size1 is 392. This size includes user data length of 64 bytes plus minimum prefix size of 328. The value specified for size1 must be large enough to accommodate the ISC/LU6.1 (type 84) prefix and the Conversation Extension (type 8D) prefix. If shared queues are used, it must also include an additional X'28' bytes. If size1 is not specified, a default of 504 is assigned.

The minimum value for size2 is 1176. If size2 is not specified, a default of 2520 is assigned. The value specified for size2:

• Must be equal to or greater than size1.
• Cannot exceed the track length of the device on which the data set resides.
• Must be divisible by 4. If it is not, IMS uses the next greater value that is divisible by four as the value of size2.
• Should be even multiples of the QBLKS LRECL of 56.
• Should not exceed the size of the OLDS data set block minus the sum of the block descriptor word length (4 bytes) and prefix item.

If a message does not fit in a large queue record (size2), IMS either spans it to other queue records, or rejects the message with an error.

Choose values for size1 and size2 based on the sizes of the messages processed by the queue manager. When determining which size message queue record to use, the queue manager calculates the size of the message prefix, subtracts that value from the size of the short message queue buffer, and then doubles the remaining value. The queue manager then compares that value to the average user data length for the destination. If the remainder buffer size is greater than or equal to the average user data size, then the short message queue buffer is used. If the remainder buffer size is less than the average user data size, then the large message queue buffer is used. The length of the message prefix varies based on the IMS system options specified.

SHUTDWN=

Specifies the number of records to be reserved in each data set to allow the system to automatically shut down if the data set becomes filled with unprocessed messages. The maximum valid specification is 32767. The default is 30. In an XRF system, this parameter also reserves the number of records in each of the local message queue data sets (IMS.LGMSGL, IMS.SHMSGL, or IMS.QBLKSL) for shutdown.

The number of records specified should provide enough space in each data set to allow for an orderly shutdown, which depends on message throughput and the number of regions that are scheduled. In general, the following calculation applies:

• Maximum number of output messages between synchronization points per application x number of regions scheduled + 1 input message per logical terminal active at the same time.

Usage information

Some messages (such as MFS) from an input terminal can span message queue records. If messages span message queue records, the size of the input segment has no limit. When messages do not span message queue records, the maximum allowable size for input segments is size2 minus the amount for various prefix items included with the data portion of the message queue record.

The maximum size allowed for output segments is size2 minus the amount for various prefix items included with the data portion of the LRECL (message queue record).

Attention: When an output message segment that spans queue records is formatted by MFS, the message might be truncated or formatted incorrectly. To avoid such problems, increase size2 to prevent spanning.

For messages that span message queue records, the first item (basic) is included in each record of the message. Also, if RACF is generated, the RACF item plus a small (4-byte) system segment is included. All other prefix items, if applicable, appear only in the first record of the message.

The values for size1 and size2 should be tuned for your system.

Related reading: For information about how to tune the values of size1 and size2 after IMS is operational, refer to Message queue data set allocation in DB/DC and DCCTL environments, and to Initial Optimizing of IMS Buffer Pools in IMS Version 15.5 System Administration.

The result of this tuning should yield a value for size1 such that the I/O activity is equally split between the IMS.SHMSG data set, containing input and output message segments up to the length of size1, and the IMS.LGMSG data set, containing all input and output message segments larger than size1.

RECLNG can be changed before a cold start of IMS, but if a smaller value is specified before a BUILDQ restart, the restart may abnormally terminate.

If emergency restart procedures using BUILDQ are to be used, reallocation of logical record and data set spaces must be done carefully. The BUILDQ procedure always restores the message queue entries to the relative position in the respective queue data sets they had at the time they were saved. If the logical record or data set size has been decreased, it may be impossible to perform the restart.