Purpose

Use this macroinstruction to allow the user to register as a user of a storage pool of buffers residing in ECSA or in a data space.

The structures to maintain the storage pools are created in response to the first CREATE_POOL request by a user of CSM. For storage pools requesting a data space as the storage type, a data space is created on the first request for a pool of this type. Multiple storage pools can exist per data space. Data space storage pools are further qualified as 31-bit backed (when fixed, the real storage frame containing the page is below the 2-gigabyte real storage bar) or 64-bit backed (when fixed, the real storage frame containing the page can be on or above the 2-gigabyte real storage bar). If a 64-bit backed pool is requested and cannot be created because the machine is not executing in z/Architecture® mode, the request is converted to a 31-bit backed request for the corresponding pool size.

On the create request, the caller specifies the size of the buffers in the pool to be created (4096, 16384, 32768, 61440, and 184320), and for dataspace pools, whether or not the pool is 31-bit backed or 64-bit backed. Only one pool of a given size exists per storage type. Requests by other callers for a pool of the same characteristics share the existing pool. The EXPBUF, INITBUF, and MINFREE values for each pool are each set to the largest value specified by any single user sharing a pool. Therefore, these values can also be adjusted downward when a user discontinues sharing a pool (that is, the user issues a DELETE_POOL request).

Usage

This macroinstruction should be used by an application if it subsequently requests buffers from CSM.

Environment

This macroinstruction must be issued in task mode; it is not allowed in cross memory mode.

Parameters

name

An optional symbol, starting in column 1, that is the name on the IVTCSM macro invocation. The name must conform to the rules for an ordinary assembler language symbol.

,BACK=location

An optional parameter that applies to BUFSOURCE=DSPACE. Specifies whether or not the data space storage, when fixed, can be backed above the 2-gigabyte real storage bar. BACK=31 forces the storage to be backed below the 2-gigabyte bar and BACK=64 allows the storage to be backed on or above the 2-gigabyte bar. BACK=31 is the default. If a 64-bit backed pool is requested and cannot be created because the machine is not executing in z/Architecture mode, the request is converted to a 31-bit backed request for the corresponding pool size.

,BUFSIZE=bufsize

A required input parameter, specifying the size of the buffers in the pool to be created. Valid pool sizes are 4096, 16384, 32768, 61440, and 184320. All other values specified on this parameter are rounded up to the next valid pool size. However, if BUFSIZE is greater than 184320, the CREATE_POOL request is rejected.

To code, specify the RS-type address, or address in register (2)-(12), of a fullword field.

,BUFSOURC=

A required parameter, specifying the source of the storage from which the buffers are to be allocated.

,BUFSOURC=DSPACE

Indicates that the storage pool is to be created in data space.

,BUFSOURC=ECSA

Indicates that the storage pool is to be created in ECSA.

,DS_INFO=ds_info

An optional output parameter that contains the address of an area containing the information required to dump CSM data spaces mapped by IVTDATSP.

To code, specify the RS-type address, or address in register (2)-(12), of a pointer field.

,EXPBUF=expbuf

A required input parameter, specifying the number of buffers by which the pool is expanded when the number of free buffers falls below the value for MINFREE or when a GET_BUFFER request needs to be satisfied.

Valid ranges for EXPBUF are listed in Table 1. If a value outside of a range is specified, then CSM uses a default value. The default values for EXPBUF are also listed in Table 1.

Table 1. Default values for EXPBUF

Pool size	Valid range	Default
4096	1 - 256	16
16384	1 - 256	8
32768	1 - 128	4
61440	1 - 68	4
184320	1 - 22	2

To code, specify the RS-type address, or address in register (2)-(12), of a fullword field.

,INITBUF=initbuf

A required input parameter, specifying the initial number of buffers to be created in the storage pool. If 0 is specified, the base pool is created only to represent the requester as a user of the pool. In this case, the pool is expanded on the first GET_BUFFER macroinstruction based on the specification for EXPBUF.

Guideline: The pool does not contract if the number of buffers currently available is below a certain value. The value is determined as the higher of INITBUF or MINFREE+(2*EXPBUF).

Valid values for INITBUF are in the range 0 - 9999. If a value outside of this range is specified, then CSM uses a default value. The default values for INITBUF are listed Table 2.

Table 2. Default values for INITBUF

Pool size	Default
4096	64
16384	32
32768	16
61440	16
184320	2

To code, specify the RS-type address, or address in register (2)-(12), of a fullword field.

,MF=

An optional input parameter that specifies the macro form.

MF=S

Specifies the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.

MF=L

Specifies the list form of the macro. Use the list form together with the execute form of the macro for applications that require re-entrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be coded with the list form of the macro.

MF=E

Specifies the execute form of the macro. Use the execute form together with the list form of the macro for applications that require re-entrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.

MF=M

Use together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.

,list addr

The name of a storage area to contain the parameters. For MF=S, MF=E, and MF=M, this can be an RS-type address or an address in register (1)-(12).

,attr

An optional input string 1 - 60 characters in length that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.

,COMPLETE

Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.

,NOCHECK

Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.

Guidelines: Use the modify and execute forms of IVTCSM in the following order:

1. Use IVTCSM ...MF=(M,list-addr,COMPLETE) specifying appropriate parameters, including all required ones.
2. Use IVTCSM ...MF=(M,list-addr,NOCHECK), specifying the parameters that you want to change.
3. Use IVTCSM ...MF=(E,list-addr,NOCHECK), to execute the macro.

,MINFREE=minfree

A required input parameter, specifying the minimum number of buffers to be free in the pool at any time. The storage pool is expanded if the number of free buffers falls below this limit.

Valid values for MINFREE are in the range 0 - 9999. If a value outside of this range is specified, then CSM uses a default value. The default values for MINFREE are listed in Table 3.

Table 3. Default values for MINFREE

Pool size	Default
4096	8
16384	4
32768	2
61440	2
184320	1

To code, specify the RS-type address, or address in register (2)-(12), of a fullword field.

,PLISTVER=

An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are:

IMPLIED_VERSION

The lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.

MAX

Specify when you want the parameter list to be the largest size currently possible. This size might increase from release to release and affect the amount of storage that your program needs.

If you can tolerate the size change, you should always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form; in this way, MAX ensures that the parameter list does not overwrite nearby storage.

0

Specify when you use the currently available parameters.

To code, specify one of the following values:

• IMPLIED_VERSION
• MAX
• A decimal value of 0

,RETCODE=retcode

An optional output parameter into which the return code is to be copied from GPR 15.

To code, specify the RS-type address of a fullword field, or register (2)-(12).

,RETPTOKN=retptokn

An optional output parameter of an area in which the application is to receive a token representing this user of this pool. This token must be supplied as input on the IVTCSM REQUEST=DELETE_POOL and IVTCSM REQUEST=GET_BUFFER macroinstructions, with the POOLTOKN parameter associated with this pool.

To code, specify the RS-type address, or address in register (2)-(12), of a 10-character field.

,RSNCODE=rsncode

An optional output parameter into which the reason code is to be copied from GPR 0.

To code, specify the RS-type address of a fullword field, or register (2)-(12).

,STATAREA=statarea

An optional output parameter that contains the address an area containing the resource statistics mapped by IVTSTATA.

To code, specify the RS-type address, or address in register (2)-(12), of a pointer field.

Return codes