IMS EMH Structure Help

When running in an IMS Shared Queues environment, with Fast Path transactions defined (FPATH=YES on the APPLCTN or TRANSACT macros), IMS uses CQS to put globally queued input and output messages on a shared EMHQ structure on the coupling facility. There are several differences between shared queue support for Fast Path transactions and full function transactions that are important to understand when sizing the EMHQ structure.

The Fast Path Input Edit/Routing Exit (DBFHAGU0) can specify, for each input message, one of three Sysplex Processing Codes (SPCs). They determine whether the input message is to be queued locally (LOCAL ONLY), queued globally (GLOBAL ONLY), or queued globally only if the number of messages queued locally is already more than six (LOCAL FIRST). To size the EMHQ structure, it is necessary to understand which of these options is being used, and for LOCAL FIRST, an approximation of how often a message will be queued globally because of the length of the local queue.

All Fast Path transactions are defined as single segment, response mode transactions. This means that any input device can have at most only one transaction in progress. For example, if there were 10,000 terminals in the network, there could be a maximum total of 10,000 input and output messages on the EMHQ (it is, of course, unlikely that every terminal would have a transaction in progress).

Each terminal in the network is allocated an EMH buffer whose size cannot exceed some system defined maximum. This maximum size is the largest of the FPBUF=size parameter on the TERMINAL macro, the FPATH=size parameter on the APPLCTN or TRANSACT macro, or the EMHL=size parameter in DFSPBxxx. As Fast Path messages arrive from a terminal, its initial buffer size may be increased to hold a larger message size. Not every message will be that large. In fact, most of them probably won't. For example, an input message may be only 600 bytes while the output message may be 1200 bytes. Only one of them will be on the queue at any time. The actual size of the message determines what is put on the EMHQ - not the size of the buffer. Each message (including its EMH prefix and CQS prefix) will use one or more 512-byte data elements. So a 600 byte message and a 1000 byte message would both require two data elements.

Beginning with IMS V4, ALL IMS terminals are eligible to enter Fast Path transactions. However, this does not mean that all terminals WILL enter Fast Path transactions. So even if there are 10,000 terminals in the network, the user may know that only 2000 (for example) will actually enter Fast Path transactions.

Summarizing the above, not all transactions are queued to the shared EMHQ, there can be only a single input or output message per terminal on the EMHQ, the maximum size of the message is limited by the size of the EMH buffer defined, and every terminal is eligible to enter a Fast Path transaction which MIGHT end up on the EMHQ, although the user may know that some terminals will never enter a Fast Path transaction.

EMHQ Structures:

Shared EMH, like its full function counterpart, requires a primary structure in the coupling facility and, optionally, an overflow structure to be used by CQS to prevent the primary structure from filling up.  Each structure must be defined in the CFRM policy with a maximum size (SIZE) and (optionally) an initial size (INITSIZE) and a minimum size (MINSIZE).  CQS supports overflow processing by identifying long queues and moving them to the overflow structure when the primary structure reaches a system defined full threshold (OVFLWMAX in CQSSGxxx). Prior to using overflow, if INITSIZE has been specified, CQS will attempt to ALTER the size of the primary structure in increments up to the maximum SIZE.  CQS does not ALTER the size of the overflow structure, although the user may do it with the SETXCF ALTER command.

CQS overflow threshold processing is based solely on the number of data elements in use and does not consider the number of list entries in use. It is possible, if the entry-to-element ratio is wrong (not enough list entries - too many data elements), that the structure could become full due to running out of list entries before the overflow threshold is reached. CQS does not ALTER this ratio.

If either the primary or overflow structure is defined with INITSIZE and ALLOWAUTOALT(YES), the allocated size and/or the entry-to-element ratio will be adjusted automatically by the system in increments up to the maximum size when FULLTHRESHOLD defined in the CFRM policy (default is 80% full) is reached. This threshold processing by the system considers both the list entries in use and data elements in use and will adjust the ratio if necessary.

DEDB-only systems:

Many users include the FPCTRL macro in their sysgen to enable Fast Path only for access to DEDBs, with no intention of ever using the Expedited Message Handler for Fast Path transactions. However, since Fast Path transactions can be added dynamically using online change, a minimum size EMHQ structure is still required. The CFSIZER tool will calculate what this minimum size is. Since the structure will not be used, only a primary structure need be defined - not an overflow structure.

Sizing the structures:

Determining the correct size specifications for the primary EMHQ structure depends on the ability to accurately estimate the number and size of the messages on that structure at any one time. A maximum SIZE should be selected, so that the overflow structure only needs to be used under extreme conditions, for example, if all scheduling stops but messages continue to be queued. The size of the overflow structure should be large enough to accommodate those extreme conditions.

The CFSIZER tool provides sizing recommendations based on user-provided input. The user must estimate the number of messages on the structure at one time, and the number of data elements associated with those messages, and provide those numbers to the tool. The tool then returns a recommendation for the SIZE (or INITSIZE) parameter for the EMHQ Structure definition in the CFRM policy. The user may want to run this tool several times, once with the maximum number of messages and data elements possible and once with the average number of messages and data elements. The two values returned can then be used as the SIZE and INITSIZE values for the CFRM policy definition. It should be noted, however, that in a well tuned system, the average number of messages on the shared EMHQ will be very small. A better technique might be to estimate the number of messages and data elements required when messages are queued due to high volumes, for example, during peak periods, and use this number as the INITSIZE.

CQS puts some control list entries on the EMHQ structure, to help it manage the structure. CQS puts at least 3 list entries and 3 data elements on the EMHQ structure. These numbers may increase, based upon the number of CQSs in the sysplex and the number of structure processes that are in progress or have been performed, such as structure checkpoint, structure rebuild, and overflow processing.  CFSIZER factors these numbers into the formula.

The CFSIZER tool requires two input values:

How many messages will be on the EMHQ at on time (EMH Message Number)

The EMH Message Number is the total number of input and output messages on the EMHQ at any one time. Each message will require exactly one list entry. It is up to the user to decide how many messages to allow for, but the absolute maximum is the total number of unique static and dynamic (ETO) terminals defined to all the IMSs in the IMSplex.

One or more of the following methods can be used to calculate the value for the EMH

• Define an EMH Message Number of 1 if your IMS system is a DEDB-only Fast Path system.

• Calculate the absolute maximum EMH Message Number from the number of TERMINAL macros in the SYSGEN plus the maximum number of dynamically allocated (ETO) terminals that might ever enter a Fast Path transaction.  This EMHQ structure would accommodate the situation where all of the terminals entered a Fast Path transaction that could not be processed locally and were all on the EMHQ at the same time.

• Calculate the realistic maximum EMH Message Number by multiplying the peak transaction rate (transactions per second) by some arbitrary period of time.  For example, if the peak transaction rate were 200tps, and you wanted to be able to hold 15 seconds of message traffic on the EMHQ structure (representing a period of 15 seconds where no work was processed), then the EMH Message Number would be 200*15=3000.

• Alternatively, if a stress (high volume) test environment is available, the realistic maximum can be determined by running at projected peak volumes for an extended period of time and periodically examining the CQS structure statistics to determine what the maximum number of list entries in use is. One might even introduce some simulated problems which would cause the queues to build up, such as too few IFP regions to process the work.

The current list entries in use value may be determined by issuing the following command:

/CQQUERY STATISTICS STRUCTURE(emhq-structure-name)

or by issuing the following CQS query from a user-written CQS client:

CQSQUERY FUNC=STATISTICS (QSPNTRC field in DSECT CQSQRYST)

In IMS V8 (and later) the list entry high water mark can be extracted from CQS statistics from one of the following:

• CQS structure checkpoint log record (x'6001')

• CQS statistics user exit (defined in BPE configuration proclib members)

• CSLZQRY macro issued from a user-written Automated Operator Program (AOP) that registers to SCI.

We feel that sizing the EMHQ structure based on the average number of messages is not very useful since the average number of messages may be very close to zero.  The structure should be sized for periods when there are more than the average number of messages on the queue. The EMH Message Number (emhnum) is used in the Data Element Number formula below.

How many data elements will those messages require (Data Element Number)?

Data Element Number
The input and output message, which includes a 32-byte CQS prefix, the EMHB global header or IMS prefix (252 bytes for IMS V6 & V7 and 352 bytes for IMS V8), plus the actual message text (llzz+trancode+data),is referred to as a data object. CQS stores each data object in one or more 512-byte data elements associated with a single list entry. Remember that a 600-byte message and a 1000-byte message both require two data elements, whereas an 1025-byte message requires three data elements. This should be factored in when calculating the data element number.

Use one of the following methods to calculate the value to use for the Data Element Number:

• Define a Data Element Number of 1 if your IMS system is a DEDB-only Fast Path system and you do not intend to use the EMH.

• Determine the average number of data elements used by each input and output message. This can be done either by knowledge of the application, or by examining existing IMS log records. If applying knowledge of the application, don't forget to add in the IMS prefix.

• Fast Path input transactions are logged as type x'5901' log records and output responses as type x'5903' log records. An examination of a sufficient number of these log records can tell you what the average message size is (the IMS prefix is part of the log record). From the size of the message, determine the average number of data elements required for the message (avgelemnum). DO NOT use the average message size, as this can be misleading. For example, the average of 600 and 1200 is 900, which would imply two data elements. However, only the 600-byte message would use two data elements; the 1200-byte message would require three. The number of  data elements required to hold a number of messages equal to the EMH Message Number would then be: emhnum * avgelemnum.

Using the same techniques described for extracting list entry usage when a stress test system (or existing production shared queue system) is available, look at the actual usage of data elements for input and output messages.  Use this number to determine the average number of data elements per message.

Other factors to consider:

There are several other factors to consider when specifying parameters in the structure definition of the CFRM policy and in CQSSGxxx.

In the CFRM policy:

• SIZE determines the maximum size that the structure can ever be.If the space is not needed (assuming an INITSIZE has been specified), then it will not be allocated. So making this parameter large enough for the absolute maximum is not necessarily a bad thing.

• INITSIZE specifies the initial structure size when first allocated by CQS. Both CQS and the system may increase this size if it reaches a user-defined threshold (OVFLWMAX in CQSSGxxx and FULLTHRESHOLD in the CFRM policy). So making this parameter a little smaller than the realistic maximum is also not a bad thing.

• ALLOWAUTOALT(YES) enables the system to monitor a structure and when the structure reaches a structure full threshold (FULLTHRESHOLD), to automatically alter (adjust) the size of the structure and/or the entry-to-element ratio.

• FULLTHRESHOLD(nn) sets a percentage structure full threshold (default is 80%) at which the structure will be automatically altered by the system. It applies to both list entries
  and data elements. Since the system can alter not only the structure size but the entry-to-element ratio, this is a better technique for monitoring structure size than CQS overflow processing, which can only alter the size. Also, CQS would not catch a problem with running out of list entries, perhaps resulting in a structure full condition before overflow processing kicked in. So, this value should be set lower than the CQS OVFLWMAX value. In this way, CQS overflow processing kicks in only when the structure has reached its maximum size.

• MINSIZE determines the minimum size to which a structure can be reduced by automatic structure alter. This is important, because if the structure becomes too small, Event Monitor Controls (EMCs) are eliminated from the structure and notification to IMS of messages on the queue cease. The CFSIZER will provide a MINSIZE for the EMHQ structure which, if specified in the CFRM policy, will set a lower limit on structure size which would guarantee that EMCs are not deleted. However, you might want to set this value higher since you don't want the structure to be reduced too much during periods when actual usage is small and then not have enough room in the coupling facility later to increase its size if needed.

In CQSSGxxx:

• OBJAVGSZ is used by CQS to determine the entry-to-element ratio. It was mentioned above that the average message size is not necessarily a good tool for determining how many data elements are needed for the average message. Instead, the user should use the technique described above to determine the average number of data elements required per message, and then set OBJAVGSZ accordingly. Since running out of list entries is worse than running out of data elements (CQS doesn't monitor list entries), it is better to round this number down. For example, if the average message requires 2.5 data elements, a ratio of 1:2 is better than 1:3, so OBJAVGSZ should be set to provide this ratio. Any number between 512 and 1024 would do that.

• OVFLWMAX determines the percentage of data elements in use that will trigger CQS overflow processing. If running with ALLOWAUTOALT enabled, this number should be higher than FULLTHRESHOLD specified in the CFRM policy, allowing the system to adjust not only the size of the structure but also the entry-to-element ratio.

• OVFLWSTR defines an overflow structure. We hope this is never used, but if it is needed, then it should be large enough to accommodate the overflow from the primary structure. If the primary structure has an absolute maximum SIZE, then an overflow structure is probably not needed, but if it is sized at something below the absolute maximum, then it is wise to have an overflow structure and just hope it's not needed.

Quick and dirty:

If you don't want to go through all this, let the system (CQS and OS) adjust the structure size for you. Pick a large SIZE and a small INITSIZE and then just let it find its own level.