Purpose

Use this macroinstruction allows an application to request one or more buffers of a given size from the CSM storage pool.

Usage

For the IVTCSM REQUEST=GET_BUFFER macroinstruction, CSM allocates buffers from a pre-existing pool and returns information to the requester needed to address the buffer. This includes the ALET of a buffer that resides in a data space. The value specified on the POOLTOKN parameter must be the same value returned on the RETPTOKN parameter of the IVTCSM REQUEST=CREATE_POOL macroinstruction.

The application has the option of requesting buffers that are guaranteed to be fixed, guaranteed to be pageable, or eligible to be made pageable. A pageable buffer can be obtained and used when fixed buffers are unavailable, and fixed at a later time using the IVTCSM REQUEST=FIX_BUFFER macroinstruction. For data space buffers, the pool token provided on the GET_BUFFER invocation is used to determine whether the returned buffer is backed by 31-bit or 64-bit real storage. If BACK=64 was specified on the CREATE_POOL invocation and the machine supports 64-bit backed storage, then a 64-bit backed buffer is returned. If BACK=31 was specified or taken as the default, or BACK=64 was specified but the machine is not executing in z/Architecture® mode, then a 31-bit backed buffer is returned.

Ownership of the buffers is assigned to the requesting address space by default. This can be overridden by specifying OWNERID. The OWNERID is the ASID of the address space. Ownership of a buffer can be optionally qualified for a given task by specifying TASKID. The TASKID is a TCB address.

A buffer token is returned with each buffer. The buffer token is the means by which this buffer is known to CSM. This token must be used with all other requests to CSM for the associated buffer.

The application can also specify a free routine address that is to receive control when the IVTCSM REQUEST=FREE_BUFFER macroinstruction is issued for the buffer. The default is that the buffers are to be returned to CSM.

The application can also specify that the buffer obtained is to be cleared when it is returned to the pool. This provides for secure data to be cleared after processing is complete.

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.

,BUFLIST=buflist

A required input parameter of an area containing a list of buffer entries. The number of entries in the list is equal to the value specified by the BUFNUM parameter. An entry in the list is mapped by IVTBUFL.

The following field in IVTBUFL is required as input for this request.

• BUFL_VERSION

The following fields in IVTBUFL are returned as output by CSM for this request.

• BUFL_SOURCE
• BUFL_TYPE
• BUFL_TOKEN
• BUFL_ALET (Returned only if the buffer was allocated from a data space.)
• BUFL_ADDR
• BUFL_SIZE

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

,BUFNUM=bufnum

A required input parameter, specifying the number of buffers to be obtained.

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

,BUFTYPE=

A required parameter, specifying whether the buffers are to be guaranteed to be fixed, guaranteed to be pageable or eligible to be made pageable.

,BUFTYPE=PAGEELIG

Indicates that the buffers are eligible to be made pageable.

,BUFTYPE=PAGEABLE

Indicates that the buffers are to be guaranteed to be pageable.

,BUFTYPE=FIXED

Indicates that buffers are to be guaranteed to be fixed.

,CLEAR=

An optional parameter, specifying whether the buffer is to be cleared when returned to the storage pool. The default is CLEAR=NO.

,CLEAR=NO

Specifies that the buffer is not cleared when returned to the buffer pool

,CLEAR=YES

Specifies that the buffer is cleared. Specifying CLEAR=YES does not cause a buffer to be cleared that is returned via a user-specified free routine. However, if CLEAR=YES is specified, the buffer is cleared in the event that it is returned to the storage pool.

,ERRBFLST=errbflst

An optional output parameter containing the number of the last buffer entry that was successfully processed when an error is detected during processing of the macroinstruction.

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

,FREERTN=freertn

An optional input parameter that is to contain the address of an application routine that is to receive control when the buffer is freed. This allows the buffer to be passed to another application or product such as VTAM® and to receive the buffer back when the receiver is finished. The free routine is scheduled for execution in the address space of the original owner of the buffer. See Buffer return exit routine for more information.

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

,GAP=gap

An optional input parameter, specifying the number of bytes used to separate buffer entries. This parameter allows the buffer entries to be in discontiguous storage. If GAP is not specified, buffer entries are contiguous.

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 reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter be coded with the list form of the macro.

MF=E

Specifies to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant 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.

Note: 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.

,OWNERID=ownerid

An optional input parameter, specifying the owner of the buffer being obtained.

To code, specify the RS-type address, or address in register (2)-(12), of a halfword 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

,POOLTOKN=pooltokn

A required input parameter of the token representing this user of this pool. This must be the token provided to the application on the associated IVTCSM REQUEST=CREATE_POOL macroinstruction.

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

,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).

,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).

,TASKID=taskid

An optional input parameter that is to contain the address of a TCB. This further qualifies the ownership of a buffer to a specific task. If TASKID is not specified, the buffer is not associated with a task but is instead associated with the issuing application's ASID.

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

,THREAD=thread

An optional input parameter, specifying a unique identifier that is placed in the CSM trace entry to correlate trace records with the application that is requesting the buffers. It is the CSM user's responsibility to ensure that this value is different from the THREAD value specified by other users of the CSM. One way this can be achieved is by specifying an ECSA control block for THREAD.

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

,UTILRTN=utilrtn

An optional input parameter that is issued from a utility routine. Specify the utility routine caller's address to be placed in the CSM trace entry. If this parameter is omitted, only the address of the CSM request issuer is placed in the CSM trace entry. This parameter is relevant only to the tracing process. It should be specified only if the CSM user requires identification of the caller of a utility routine in the CSM trace entry.

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

,WAIT=

An optional parameter, specifying whether or not the request should wait for buffers to become available. The default is WAIT=NO.

,WAIT=NO

Specifies that this macroinstruction completes without waiting for an available buffer.

,WAIT=YES

Specifies that this macroinstruction does not complete until all buffers become available. If buffers are not available, users are suspended until enough buffers become available to satisfy the request.

,WAIT=EXPAND

Specifies that this macroinstruction waits for pool expansion to complete. If enough buffers are not available to satisfy the request, users are suspended until expansion completes.

Return codes