Storage tuning user exit interface

The storage tuning user exit can be used when running on CICS® or when running on non-CICS with library routine retention. The name of the exit is as follows:

CEECSTX for CICS
CEEBSTX for non-CICS

The storage tuning exit is loaded when Language Environment loads its other runtime load modules. If the load of the storage tuning exit is not successful, Language Environment will not issue a message and will not attempt to call the storage tuning exit.

The storage tuning user exit must be written in assembler and must be reentrant.

Syntax: Storage_Tuning_User_Exit (CEESTXPTR)

CEESTXPTR (INPUT): A pointer to the storage tuning user exit control block (CEESTX). Figure 1 shows a mapping of the storage tuning user exit control block.

Figure 1. CEESTX control block map

The CEESTX elements are described as follows:

version (INPUT)

A 1-byte field containing the control block version. This field will be set to 0x02 since this is the second version.

flags (INPUT/OUTPUT)

A 1-byte field containing flags. The layout of these flags is as follows:

   x... .... collect-storage-usage
   .x.. .... collect-storage-alloc
   ..00 0000 reserved

A one-byte field containing flags. The flags are defined as follows:

collect-storage-usage (INPUT/OUTPUT)

This flag is used to tell Language Environment to collect storage usage information. Language Environment only uses this flag when the storage tuning user exit is called during enclave initialization and automatic storage tuning for CICS is not running.

0: Do not collect storage usage information.
1: Collect storage usage information and call the storage tuning user exit during enclave termination with the storage usage information.

Note: When the storage tuning user exit is used to collect storage usage information, it will increase the time it takes for an application to run.

collect-storage-alloc (INPUT/OUTPUT)

This flag is used to tell Language Environment® to collect storage allocation information. Language Environment only uses this flag when the storage tuning user exit is called during enclave initialization. The flag values are:

0: Do not collect storage allocation information.
1: Collect storage allocation information and call the storage tuning user exit during enclave termination with the storage allocation information.

Note: There is significantly less overhead collecting storage allocation information compared to collecting storage usage information.

function-code (INPUT)

A 4-byte integer field containing the code of the function being performed when the storage tuning user exit gets control. The function code values are:

1: Region initialization
2: Region termination
3: Enclave initialization
4: Enclave termination
5: New load module (CICS only)

user-word (INPUT/OUTPUT)

A fullword that can be used to communicate information between successive calls to the storage tuning user exit. The first time the storage tuning user exit is called, this field is 0. The storage tuning user exit may modify the value in this field when it is called for region initialization. The value is saved by Language Environment and returned on subsequent invocations.

program-entry-point (INPUT)

When the storage tuning user exit is called for region initialization and region termination, this field is zero.

When the storage tuning user exit is called for enclave initialization, enclave termination, and new load module, this field contains the entry point address of the main program.

Note: When C, C++, or PL/I is the main program, this field contains the address of the main program and not the address of CEESTART.

addr-CEEUOPT (INPUT)

When the storage tuning user exit is called for region initialization and region termination, this field is zero.

When the storage tuning user exit is called for enclave initialization, enclave termination, and new load module, this field contains the address of the CEEUOPT link-edited with the main program. If no CEEUOPT is link-edited with the main program, this field is zero.

addr-CICS-info (INPUT)

When running on non-CICS, this field is set to zero.

When running on CICS, this field contains the address of the CEESTX CICS specific control block.

See Figure 2 for a mapping of the control block.

Figure 2. CEESTX CICS-specific control block map

The CEESTX CICS-specific control block elements are described as follows:

flags (INPUT/OUTPUT)

When the storage tuning user exit is called for region initialization and region termination, this field is reserved.

When the storage tuning user exit is called for enclave initialization, enclave termination, and new load module, this field contains a 1-byte area containing flags. The layout of these flags is as follows:

        x... .... load-mod-eligible
        .x.. .... automatic tuning
        .000 0000 reserved

The flags are defined as follows:

load-mod-eligible (INPUT/OUTPUT)

For each load module loaded by CICS, there is a unique load-mod-eligible flag available to the storage tuning user exit. The flag is input/output when the storage tuning user exit is called for the new load module function. The flag is output only when the storage tuning user exit is called for enclave initialization and enclave termination.

When Language Environment automatic storage tuning for CICS is not being used, the initial value of the flag is zero. When Language Environment automatic storage tuning for CICS is being used, the initial value of the flag indicates if Language Environment automatic storage tuning for CICS will be performing automatic storage tuning for enclaves started to run the load module.

This flag is used by the storage tuning user exit to indicate to Language Environment if the storage tuning user exit should be called for enclave initialization when the load module is called to start an enclave. For example, when the storage tuning user exit is called for the new load module function, it can determine if it wants to tune the storage options for the enclaves that are started to run the load module. If the storage tuning user exit decides it does want to tune the enclaves for this load module, it must set the flag on.

0: Do not call the storage tuning user exit when the program is used to start an enclave. If Language Environment automatic storage tuning for CICS is being used, do not perform automatic storage tuning when the program is used to start an enclave.
1: Call the storage tuning user exit when the program is used to start a Language Environment enclave. If Language Environment automatic storage tuning for CICS is being used, perform automatic storage tuning when the program is used to start an enclave.

automatic-tuning (INPUT)

This bit indicates if automatic storage tuning for CICS is being used.

0: Automatic storage tuning for CICS is not being used.
1: Automatic storage tuning for CICS is being used.

addr-SYSEIB (INPUT)

A pointer to the CICS system EIB (EXEC Interface Block).

addr-load-mod-name (INPUT)

When the storage tuning user exit is called for region initialization and region termination, this field is zero.

When the storage tuning user exit is called for enclave initialization, enclave termination, and new load module, this field contains:

A pointer to an 8 byte character field that has the name of the load module loaded by CICS if you are running with CICS Transaction Server Release 2 or Release 3 with APAR PQ31262 or with CICS/ESA Version 4 with APAR PQ31185.
A zero if you are not running with the APARs listed above.

Note: The storage tuning user exit will be called for the new load module function for every program that is Language Environment-enabled. Not every program loaded by CICS will be the main program.

addr-autotune-storage-settings (INPUT)

When the storage tuning user exit is called for region initialization and region termination, this field is zero. When the storage tuning user exit is called for enclave initialization, enclave termination, and new load module, this field contains:

A zero when running on a CICS region that is not running with automatic storage tuning for CICS.
A pointer to a copy of the CEESTX storage values control block when running on a CICS region using automatic storage tuning for CICS. This control block has the storage values that is used by Language Environment for automatic storage tuning. There is a copy of this control block for each load module. This control block is an input only control block and must not be changed by the storage tuning user exit.

addr-autotune-storage-override (INPUT)

When the storage tuning user exit is called for region initialization, region termination, enclave initialization, and new load module, this field is zero. When the storage tuning user exit is called for enclave termination this field contains:

A zero when running on a CICS region that is not running with automatic storage tuning for CICS.
A pointer to a copy of the CEESTX storage values control block when running on a CICS region using Automatic Storage Tuning for CICS. This control block can be changed by the storage tuning user exit as a way to override the initial size values set by Automatic Storage Tuning for CICS. Language Environment initializes the flags in the first word of the CEESTX storage values control block to hex zeros before calling the storage tuning user exit.

addr-storage-info (INPUT)

When the storage tuning user exit is called for region initialization and region termination, this field is zero.

When the storage tuning user exit is called for enclave initialization, enclave termination, and new load module, this field contains the address of a control block that is used to pass Language Environment storage information between Language Environment and the storage tuning user exit. There are three forms of the control block:

The CEESTX storage values control block
The CEESTX storage used control block
The CEESTX storage allocated control block.

When the storage tuning user exit is called with the enclave initialization function or the new load module function, the CEESTX storage values control block is passed.

When running on non-CICS or on CICS without automatic storage tuning:

All of the fields in the control block are output only fields except for the first word. The first word is an input/output field. Language Environment initializes the flags in the first word to hex zeros before calling the storage tuning user exit.
All other fields will not be initialized.

When running on CICS with automatic storage tuning:

All of the fields in the control block are output only fields except for the first word. The first word is an input/output field. Language Environment initializes the flags in the first word to hex zeros before calling the storage tuning user exit.
All other fields will not be initialized.
The storage option values provided at the new load module call are used as the starting values by automatic storage tuning.
The storage option value provided at enclave initialization call are ignored.

See Figure 3 for a mapping of the CEESTX storage values control block.

Figure 3. Mapping of the CEESTX storage values control block

When the storage tuning user exit is called with the enclave termination function, the CEESTX storage used control block or the CEESTX storage allocated control block is passed to the storage tuning user exit to provide storage information collected by Language Environment. The CEESTX storage used control block is passed when the storage tuning user exit requested Language Environment to collect storage usage information. The CEESTX storage allocated control block is passed when the storage tuning user exit requested Language Environment to collect storage allocation information. All of the fields in the control block are input only. See Figure 4 for a mapping of the CEESTX storage used control block. See Figure 5 for a mapping of the CEESTX storage allocated control block map.

The CEESTX storage values control block elements are described as follows:

stg-flags (OUTPUT)

A 1-byte field containing flags. The layout of these flags is as follows:

       0... .... STACK options not provided
       1... .... STACK options provided
       .0.. .... LIBSTACK options not provided
       .1.. .... LIBSTACK options provided
       ..0. .... HEAP options not provided
       ..1. .... HEAP options provided
       ...0 .... ANYHEAP options not provided
       ...1 .... ANYHEAP options provided
       .... 0... BELOWHEAP options not provided
       .... 1... BELOWHEAP options provided
       .... .000 reserved

There is a flag for each storage runtime option that can be altered by the storage tuning user exit. The exit must turn on the flags for the storage runtime options for which it is providing values.

STACK-flags (OUTPUT)

A 2-byte field containing flags. The layout of these flags is as follows:

Byte 0
          0... .... STACK initial size not provided
          1... .... STACK initial size provided
          .0.. .... STACK increment size not provided
          .1.. .... STACK increment size provided
          ..0. .... STACK location not provided
          ..1. .... STACK location provided
          ...0 .... STACK disposition not provided
          ...1 .... STACK disposition provided
          .... 0000 reserved
Byte 1
          0... .... STACK location ANYWHERE
          1... .... STACK location BELOW
          .0.. .... STACK disposition KEEP
          .1.. .... STACK disposition FREE
          ..00 0000 reserved

In byte 0, there is a flag for each STACK suboption. The exit must set the flags in byte 0 to indicate the STACK suboptions for which it is providing values.

The STACK location can be set to ANYWHERE only if ALL31(ON) is in effect. If the STACK location is set to ANYWHERE, and ALL31(OFF) is in effect, the STACK location is not changed.

STACK-init-size (OUTPUT)

A fullword binary field used to indicate the number of bytes for the STACK initial size.

STACK-incr-size (OUTPUT)

A fullword binary field used to indicate the number of bytes for the STACK increment size.

LIBSTACK-flags (OUTPUT)

A 2-byte field containing flags. The layout of these flags is as follows:

Byte 0
          0... .... LIBSTACK initial size not provided
          1... .... LIBSTACK initial size provided
          .0.. .... LIBSTACK increment size not provided
          .1.. .... LIBSTACK increment size provided
          ..0. .... LIBSTACK disposition not provided
          ..1. .... LIBSTACK disposition provided
          ...0 0000 reserved
Byte 1
          0... .... LIBSTACK disposition KEEP
          1... .... LIBSTACK disposition FREE
          .000 0000 reserved

In byte 0, there is a flag for each LIBSTACK suboption. The exit must set the flags in byte 0 to indicate the LIBSTACK suboptions for which it is providing values.

LIBSTACK-init-size (OUTPUT)

A fullword binary field used to indicate the number of bytes for the LIBSTACK initial size.

LIBSTACK-incr-size (OUTPUT)

A fullword binary field used to indicate the number of bytes for the LIBSTACK increment size.

HEAP-flags (OUTPUT)

A 2-byte field containing flags. The layout of these flags is as follows:

Byte 0
          0... .... HEAP initial size not provided
          1... .... HEAP initial size provided
          .0.. .... HEAP increment size not provided
          .1.. .... HEAP increment size provided
          ..0. .... HEAP location not provided
          ..1. .... HEAP location provided
          ...0 .... HEAP disposition not provided
          ...1 .... HEAP disposition provided
          .... 0... HEAP initial size 24 not provided
          .... 1... HEAP initial size 24 provided
          .... .0.. HEAP increment size 24 not provided
          .... .1.. HEAP increment size 24 provided
          .... ..00 reserved
Byte 1
          0... .... HEAP location ANYWHERE
          1... .... HEAP location BELOW
          .0.. .... HEAP disposition FREE
          .1.. .... HEAP disposition KEEP
          ..00 0000 reserved

In byte 0, there is a flag for each HEAP suboption. The exit must set the flags in byte 0 to indicate the HEAP suboptions for which it is providing values.

HEAP-init-size (OUTPUT)

A fullword binary field used to indicate the number of bytes for the HEAP initial size.

HEAP-incr-size (OUTPUT)

A fullword binary field used to indicate the number of bytes for the HEAP increment size.

HEAP-init-size24 (OUTPUT)

A fullword binary field used to indicate the number of bytes for the HEAP initial size for the heap storage obtained below the 16-MB line for applications with ANYWHERE in the HEAP runtime option.

HEAP-incr-size24 (OUTPUT)

A fullword binary field used to indicate the number of bytes for the HEAP increment size for the heap storage increments obtained below the 16-MB line for applications with ANYWHERE in the HEAP runtime option.

ANYHEAP-flags (OUTPUT)

A 2-byte field containing flags. The layout of these flags is as follows:

Byte 0
          0... .... ANYHEAP initial size not provided
          1... .... ANYHEAP initial size provided
          .0.. .... ANYHEAP increment size not provided
          .1.. .... ANYHEAP increment size provided
          ..0. .... ANYHEAP location not provided
          ..1. .... ANYHEAP location provided
          ...0 .... ANYHEAP disposition not provided
          ...1 .... ANYHEAP disposition provided
          .... 0000 reserved
Byte 1
          0... .... ANYHEAP location ANYWHERE
          1... .... ANYHEAP location BELOW
          .0.. .... ANYHEAP disposition KEEP
          .1.. .... ANYHEAP disposition FREE
          ..00 0000 reserved

In byte 0, there is a flag for each ANYHEAP suboption. The exit must set the flags in byte 0 to indicate the ANYHEAP suboptions for which it is providing values.

ANYHEAP-init-size (OUTPUT)

A fullword binary field used to indicate the number of bytes for the ANYHEAP initial size.

ANYHEAP-incr-size (OUTPUT)

A fullword binary field used to indicate the number of bytes for the ANYHEAP increment size.

BELOWHEAP-flags (OUTPUT)

A 2-byte field containing flags. The layout of these flags is as follows:

Byte 0
          0... .... BELOWHEAP initial size not provided
          1... .... BELOWHEAP initial size provided
          .0.. .... BELOWHEAP increment size not provided
          .1.. .... BELOWHEAP increment size provided
          ..0. .... BELOWHEAP disposition not provided
          ..1. .... BELOWHEAP disposition provided
          ...0 0000 reserved
Byte 1
          0... .... BELOWHEAP disposition KEEP
          1... .... BELOWHEAP disposition FREE
          .000 0000 reserved

In byte 0, there is a flag for each BELOWHEAP suboption. The exit must set the flags in byte 0 to indicate the BELOWHEAP suboptions for which it is providing values.

BELOWHEAP-init-size (OUTPUT)

A fullword binary field used to indicate the number of bytes for the BELOWHEAP initial size.

BELOWHEAP-incr-size (OUTPUT)

A fullword binary field used to indicate the number of bytes for the BELOWHEAP increment size.

Figure 4 shows a mapping of the CEESTX storage used control block. (See Figure 3 for a mapping of the CEESTX storage input control block.)

Figure 4. CEESTX storage used control block map

The CEESTX storage output control block elements are described as follows:

Each field is a fullword binary field that corresponds to the information in the Language Environment storage report.

Figure 5. CEESTX storage allocated control block map

The CEESTX storage used control block elements are described as follows:

Each field is a fullword binary field.
The init-size fields indicate the initial size specified in the runtime option for the storage area.
The incr-size fields indicate the increment size specified in the runtime option for the storage area.
The max-allocated fields indicate the maximum amount of storage allocated for the storage area.

Usage notes

The storage tuning user exit must be written in assembler and must be reentrant. If you write the storage tuning user exit in Language Environment-enabled assembler, you must specify MAIN=NO on the CEEENTRY macro.
The storage tuning user exit must not call any HLL programs.
The storage tuning user exit must not create a Language Environment enclave.
All values provided by the storage tuning user exit that are not valid for initial size and increment size are ignored. For example, a negative increment size is ignored.
The storage tuning user exit should provide storage sizes that are multiples of 8. Any storage size that is not a multiple of 8 will be rounded up to the nearest multiple of 8 bytes.
The STACK location setting cannot be set to ANY when ALL31 is OFF, or it will be ignored.
Only the following CICS commands can be used during the new load module function: GETMAIN, FREEMAIN, ENQUEUE, DEQUEUE, and any command that performs I/O to a VSAM file, a CICS data table, a transient data queue, or a temporary storage queue.
Only the following CICS commands can be used during enclave initialization and enclave termination: GETMAIN, FREEMAIN, LOAD, DELETE, ENQUEUE, DEQUEUE, INQUIRE, SET, and any command that performs I/O to a VSAM file, a CICS data table, a transient data queue, or a temporary storage queue.
CICS considerations: CICS commands can be used in the storage tuning user exit. However, the storage tuning user exit must adhere to the following conventions when using EXEC CICS commands:
- The storage tuning user exit has to use the CICS system EIB (the SYSEIB translator option must be used).
- The CICS commands must use the RESP option.
- Only the following CICS commands can be used during region initialization and region termination: GETMAIN, FREEMAIN, LOAD, DELETE, and any command that performs I/O to a VSAM file, a CICS data table, or a temporary storage queue.
- The storage tuning user exit cannot use any Language Environment services when called for region initialization, new load module, enclave initialization, and region termination.
Upon return from the storage tuning user exit, Language Environment takes no action other than continuing with its processing, as no return codes are defined.
The values from the storage tuning user exit are ignored for those options that are installed as nonoverrideable.
Register conventions for the storage tuning user exit are:
Register 1

Points to a word which contains the address of the storage tuning user exit control block.

Register 12

Points to the CAA.
When the storage tuning user exit is called for enclave initialization and enclave termination, the CAA is fully initialized.

When the storage tuning user exit is called for region initialization, new load module, and region termination, a partially initialized CAA is provided to enable Language Environment stack processing.

Register 13

Points to a dynamic save area (DSA). The exit routine can save the registers here across its processing.

Register 14

Contains the return address.

Register 15

Contains the entry point address upon entry.

AMODE

The storage tuning user exit is called in AMODE(31) and it must return in AMODE(31).
The behavior of the RPTSTG option is not affected by the storage tuning user exit. The storage tuning user exit does not cause a Language Environment storage report to be generated.