Defining temporary storage pools for temporary storage data sharing

Using TS data sharing means replacing main or auxiliary storage for your TS queues with one or more TS pools, where the scope and function of each TS pool is similar to a QOR. Each TS pool is defined, using MVS™ cross-system extended services (XES), as a keyed list structure in a coupling facility. This means you must define the pool using the coupling facility resource manager (CFRM) policy statements. Using the CFRM policy definition utility, IXCMIAPU, you specify the size of the list structures required, and their placement within a coupling facility. For an example of this utility, see member IXCCFRMP in the SYS1.SAMPLIB library, in the OS/390 MVS Setting Up a Sysplex manual. An example of a definition statement is shown in Figure 4.

Figure 4. Example of defining the estimated size of a list structure
 
 STRUCTURE  NAME(DFHXQLS_PRODTSQ1)
    SIZE(1000)
    INITSIZE(500)
    PREFLIST(FACIL01,FACIL02)
 

The name of the list structure for a TS data sharing pool is created by appending the TS pool name to the prefix DFHXQLS_, giving DFHXQLS_poolname. When defined, you must activate the CFRM policy using the MVS operator command SETXCF START.

When a list structure is allocated, it may have an initial size and a maximum size specified in the CFRM policy. (All structure sizes are rounded up to the next multiple of 256K at allocation time). Provided that space is available in the coupling facility, a list structure can be dynamically expanded from its initial size towards its maximum size, or contracted to free up coupling facility space for other purposes. Note that if the initial structure allocation becomes full, the structure does not expand automatically, even if the structure allocated is less than the specified maximum size. To expand a list structure when the allocation becomes full, you can expand it (up to its maximum size) using the following SETXCF command:

SETXCF START,ALTER,STRNAME=DFHXQLS_poolname,SIZE=nnnn

Approximate storage calculations

Start of changeA coupling facility structure contains not only stored data but also the information needed to manage and access that data, in a similar way to a key-sequenced data set. The data for each entry in the coupling facility is stored as a chain of fixed size (usually 256-byte) elements, which means that the exact length for variable-length data has to be stored separately. CICS® does this by including a length prefix in the stored data, so space calculations have to allow for each entry using a whole number of elements. The amount of internal control information depends on the level of functionality and performance of the coupling facility control code for the current CFLEVEL. The storage requirements can increase for a higher CFLEVEL. For more information about how the coupling facility structure storage is organized, seeEnd of change

Start of changeThe easiest way to calculate accurate structure storage requirements is to use the web-based IBM® CFSizer tool at http://www-1.ibm.com/servers/eserver/zseries/cfsizer/ . The tool takes these factors into account and communicates with a coupling facility at a current CFLEVEL to perform the calculation. You need to enter some minimum input to get an accurate storage calculation as follows:

MAXQUEUES
specifies the maximum number of data lists that are reserved when the structure list is allocated by CICS. This determines the maximum number of large queues that can be stored in the structure and corresponds to the MAXQUEUES server parameter. A large queue is where the total size of the data items exceeds 32K. It is stored in a separate list in the structure. Although you should specify a large enough number, specifying an excessively large number will use up an unnecessary amount of coupling facility storage for unused preallocated list headers. The valid range is from 1 to 999999. The default is 1000.
Average rounded item size
specifies the average amount of storage required for each TS queue item. Note that each item has a two-byte length prefix and is stored as one or more 256-byte elements. This number should range from 1 to 32768. This value determines the entry to element ratio that is used to calculate the required structure size.

If all queue items are approximately the same size, calculate this value by taking the average data size, adding two, and rounding up to the next multiple of 256. If queue items are different sizes, round up each size first before taking the average. For example, if half of the items are 100 bytes and half are 300 bytes, then the rounded sizes are 256 and 512. The average rounded item size is half way between those values, 384, which is more accurate than taking the overall average item size of 200 and rounding it up to 256.

Total number of items in all queues
specifies the total number of entries in all of the TS queues.
Target Usage Percent
specifies the percentage of the structure space which the given total number of items are expected to use. Specify a number in the range of 1 to 100. The default is 75. This leaves some free space for temporary expansion, and to give time to expand the structure in response to warning messages (which normally start at 80%) if the initial free space is not enough.
Max Expansion Percent
specifies the percentage that the structure can expand. If a non-zero value is specified here, the maximum structure size will be greater than the initial structure size by an amount sufficient to allow for a further expansion of the total amount of data by this percentage. For example, if the value 200 is specified, the initial size will be enough to store the specified total number of items, but the maximum size will be enough to store three times that number of items.
End of change

Alternatively you can use the following calculation, which applies up to CFLEVEL 11 of the coupling facility. If you have a coupling facility at CFLEVEL 12, you need to change the calculation to add 10% and 2MB to the sizings in the formula below.

Storage calculations
Item entry size = (170 + (average item size, rounded up to next 256))
                    + 5% extra for control information

Total size  =  200K
                + (number of large queues x 1K)
                + (number of items in all queues x item entry size)

The calculation determines the size of a structure that would be approximately 100% full for the specified level of usage. For practical operation, however, a reasonable proportion of free space must be available, not only to minimize the risk of the structure becoming totally full but also to avoid triggering low space warning messages and additional activity to alter entry to element ratios. The maximum normal usage should therefore aim to be about 75% of the structure size. Expected usage values should therefore be adjusted upwards to allow for the required amount of free space (for example, by about one third to aim for 75% usage.

Notes:
  1. If you have a small queue with multiple items that does not exceed 32K, then all the queue items are stored as the data portion of the queue index entry. If the queue exceeds 32K, then it is converted to a form where one item per entry is stored in a separate list and referred to by the queue index entry.
  2. The amount of element storage required is two bytes more than the data item size due to the length prefix on each item.
  3. Defining the CFRM policy statements for a list structure does not actually create the list structure, this is done by a TS server during its initialization.

For information about the TS server system initialization parameters, see Setting up and running a temporary storage server.

For information about defining list structures, see the following MVS publications:

[[ Contents Previous Page | Next Page Index ]]