Purpose

Use this macroinstruction to allow an application to change the pageable state of a buffer.

Usage

An application can use this macroinstruction to make the buffer guaranteed to be pageable or eligible to be paged.

When BUFTYPE=PAGEELIG is specified on this macroinstruction, the buffer is marked as eligible to be paged. The buffer is not physically unfixed unless CSM requires real storage to satisfy another CSM request. This avoids the potential overhead of unnecessary fixing and freeing of storage.

This macroinstruction can be used to avoid consuming real storage for data that is being held in a buffer for possible use at a later time.

When BUFTYPE=PAGEABLE is specified on this macroinstruction, the buffer is marked as guaranteed to be pageable. This macroinstruction be used when a system service requires pageable storage on input. This macroinstruction can be issued for a buffer consisting of only one image. This restriction guarantees that a user of a buffer that has multiple images can successfully issue a FIX_BUFFER request if necessary. Fixing a buffer requires that the entire buffer be fixed, even if the user is interested in only a piece of the buffer.

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 specified by BUFNUM. An entry in the buffer list is mapped by IVTBUFL.

The following fields in IVTBUFL are required as input for this request:

• BUFL_VERSION
• BUFL_TOKEN

The following field in IVTBUFL is returned as output by CSM for this request:

• BUFL_TYPE

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 made pageable or eligible to be paged.

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

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

,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 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 this value 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.

,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

Code this value if 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, 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

Code this value if 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).

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

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

Return codes