Parameter Descriptions

The parameter descriptions for REQUEST=REG_NAMELIST are listed in alphabetical order. Default values are underlined:

REQUEST=REG_NAMELIST

Use this input parameter to specify that you want to register interest in a list of data items. Each data item is represented by a registration block, mapped by the IXLYCRRB macro, stored in the area specified by BUFFER.

,ANSAREA=NO_ANSAREA

,ANSAREA=ansarea

Use this output parameter to specify an answer area to contain information returned from the request. The format of the answer area is described by the IXLYCAA mapping macro.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an area (with a length of ANSLEN) where the answer area information returned from the request will be stored.

,ANSLEN=anslen

Use this input parameter to specify the size of the storage area specified by ANSAREA.

Use either CAALEVEL0LEN or CAALEVEL1LEN of the IXLYCAA mapping macro to determine the minimum size of the answer area. The answer area length must be at least large enough to accomodate the level of the IXLYCAA mapping appropriate to the requested function. When the value of PLISTVER is 0 — 3, the minimum answer area length is CAALEVEL0LEN; when the value of PLISTVER is 4 — 6, the minimum answer area length is CAALEVEL1LEN.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 2-byte field that contains the length of the answer area (ANSAREA).

,BUFFER=buffer

Use this input parameter to specify a buffer area to contain an array of from 1 to 32 registration blocks that define the data items that are to be registered. The BUFFER area must be addressable from your primary address space or from your PASN access list.

The format of the registration block is described by mapping macro IXLYCRRB.

Only 31-bit addressable virtual storage areas (below 2GB) are supported by the BUFFER specification.

You can define the buffer size to be a total of up to 65536 bytes, but it should not be larger than what you actually require to hold the maximum number of registration blocks, subject to the other buffer length requirements stated below.

Other requirements depend on the size you select:

If you specify a buffer size of less than or equal to 4096 bytes, you must ensure that the buffer:
- Is 256, 512, 1024, 2048, or 4096 bytes.
- Starts on a 256-byte boundary.
- Does not cross a 4096-byte boundary.
- Does not start below storage address 512.
If you specify a buffer size of greater than 4096 bytes, you must ensure that the buffer:
- Is a multiple of 4096 bytes.
- Is less than or equal to 65536 bytes.
- Starts on a 4096-byte boundary.
- Does not start below storage address 512.

See the BUFSIZE parameter description for defining the size of the buffer. See z/OS MVS Programming: Sysplex Services Guide for more information on buffers.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an area (with a length of BUFSIZE) to contain the registration blocks.

,BUFSIZE=bufsize

Use this input parameter to specify the size of the BUFFER area. See the BUFFER parameter description for valid buffer sizes.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword field that contains the size of the buffer (BUFFER) in bytes.

,BUFSTGKEY=CALLERS_KEY

,BUFSTGKEY=bufstgkey

Use this input parameter to specify a storage key that you define and use when referencing the buffer specified by BUFFER.

If you do not specify BUFSTGKEY, or if you specify BUFSTGKEY=CALLERS_KEY, all references to the buffer are in the caller's PSW key.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 1-byte field that contains the storage key in the format kkkkxxxx, where kkkk is the key and xxxx is ignored.

,CONTOKEN=contoken

Use this input parameter to specify the connect token that was returned by the IXLCONN service in the IXLCONN answer area, mapped by IXLYCONA. The connect token uniquely identifies your connection to the cache structure, and must be specified on each IXLCACHE invocation.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 16-byte field that contains the connect token.

,ENDINDEX=endindex

Use this input parameter to specify the ending index for registration block processing. The index value must be greater than or equal to the value specified for STARTINDEX. Valid values are 1 - 32.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 2-byte field containing the ending index value.

,MF=S

,MF=(L,mfctrl)

,MF=(L,mfctrl,mfattr)

,MF=(L,mfctrl,0D)

,MF=(E,mfctrl)

,MF=(E,mfctrl,COMPLETE)

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

Use MF=L to specify 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 can be coded with the list form of the macro.

Use MF=E 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 stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.

,mfctrl: Use this output parameter to specify a storage area to contain the parameters.
To Code: Specify the RS-type name or address (using a register from 2 to 12) of the parameter list.
,mfattr: Use this input parameter to specify the name of a 1- to 60-character string that can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code mfattr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE: Use this input parameter to require that the system check for required parameters and supply defaults for omitted optional parameters.
Note: In the macro expansion you might see some defaults for optional parameters that are not documented here. The ones that are not documented do not have any effect on the macro. For example, if SMILE=var were an optional parameter and the default is SMILE=NO_SMILE then it would not be documented. However, if the default was SMILE=:-), then it would be documented because a value would be the default.

,MODE=SYNCSUSPEND

,MODE=SYNCECB

,MODE=SYNCEXIT

,MODE=SYNCTOKEN

,MODE=ASYNCECB

,MODE=ASYNCEXIT

,MODE=ASYNCTOKEN

Use this input parameter to specify:

Whether the request is to be performed synchronously or asynchronously
How you wish to be notified of request completion if the request is processed asynchronously.

See z/OS MVS Programming: Sysplex Services Guide for more information on understanding synchronous and asynchronous cache operations.

SYNCSUSPEND: The request processes synchronously. If necessary, the request is suspended until it can complete synchronously. To use this option, your program must be enabled for I/O and external interrupts.
SYNCECB: The request processes synchronously if possible. If the request processes asynchronously, the ECB specified by REQECB is posted when the request completes.
SYNCEXIT: The request processes synchronously if possible. If the request processes asynchronously, your complete exit is given control when the request completes.
SYNCTOKEN: The request processes synchronously if possible. If the request processes asynchronously, an asynchronous request token is returned to the area specified by REQTOKEN. Use the returned request token on the IXLFCOMP macro to determine whether your request has completed.
Note: ANSAREA is a required parameter when MODE=SYNCTOKEN is specified.
ASYNCECB: The request processes asynchronously. The ECB specified by REQECB is posted when the request completes.
ASYNCEXIT: The request processes asynchronously. Your complete exit is given control when the request completes.
ASYNCTOKEN: The request processes asynchronously. An asynchronous request token is returned to the area specified by REQTOKEN. Use the returned request token on the IXLFCOMP macro to determine whether your request has completed.
Note: ANSAREA is a required parameter when MODE=ASYNCTOKEN is specified.

,NSBAREA=nsbarea

Use this output parameter to specify a storage area to contain name state information after the system has processed the registration blocks specified in the BUFFER area. The NSBAREA area must be addressable from your primary address space or from your PASN access list.

The format of the NSBAREA area is described by mapping macro IXLYNSB.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 256-byte area to contain the name state information.

,PAGEABLE=YES

,PAGEABLE=NO

Use this input parameter to identify whether the storage area specified by BUFFER is in pageable or potentially pageable storage, and, if the area could become pageable, designate responsibility for ensuring that the area remains page-fixed for the duration of the request.

PAGEABLE=YES

Specify this option when you are using any one of the following types of storage and you want the system to ensure that the storage becomes or remains page-fixed for the duration of the request:

Pageable storage
Disabled reference (DREF) storage
Page-fixed storage that could become pageable before the request completes processing.

PAGEABLE=NO

Specify this option when using any one of the following types of storage:

Fixed storage
Page-fixed storage that you will ensure remains page-fixed for the duration of the request

If you specify PAGEABLE=NO and the request processes asynchronously, you must keep the storage fixed until you are sure the request has completed. (The MODE value specified determines how you are notified of request completion.) See z/OS MVS Programming: Sysplex Services Guide for these guidelines.

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=plistver

Use this input parameter to specify the version of the macro. See Understanding IXLCACHE Version Support for a description of the options available with PLISTVER.

,REQDATA=NO_REQDATA

,REQDATA=reqdata

Use this input parameter with MODE=SYNCEXIT or MODE=ASYNCEXIT to pass any data you choose to the complete exit. The exit will get control only if the request is processed asynchronously.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an 8-byte field that contains the data to be passed to the complete exit.

,REQECB=reqecb

Use this output parameter with either MODE=SYNCECB or MODE=ASYNCECB to specify the address of an ECB, which is to be posted when the request completes if the request was processed asynchronously.

Before coding REQECB, you must ensure that:

You initialize the ECB before you issue the request.
The ECB resides in either common storage or the home address space where IXLCONN was issued.
Any tasks that wait for the ECB to be posted reside in the home address space where IXLCONN was issued.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 4-byte field that contains the address of the ECB to be posted when the request completes. The ECB must be aligned on a fullword boundary.

,REQID=NO_REQID

,REQID=reqid

Use this input parameter to specify a user-defined request identifier to be associated with the request. You can specify this request identifier on the IXLPURGE macro to cancel a request that has not yet been processed.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an 8-byte field that contains the user-defined request identifier.

,REQTOKEN=reqtoken

Use this output parameter with either MODE=SYNCTOKEN or MODE=ASYNCTOKEN to specify the address of a storage area to receive the request token that is returned when the request will be processed asynchronously. This token, which uniquely identifies the request, must be used as input to the IXLFCOMP macro, which you use to determine if the request has completed.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 16-byte field where the system will put the request token.

,RETCODE=retcode

Use this output parameter to specify a field to contain the return code. (The return code is also returned in register 15.)

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 4-byte field that will contain the return code when the request has completed.

,RSNCODE=rsncode

Use this output parameter to specify a field to contain the reason code returned, if applicable. (The reason code is also returned in register 0.)

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 4-byte field that will contain the reason code (if any) when the request has completed.

,STARTINDEX=startindex

Use this input parameter to specify the starting index for registration block processing. Valid STARTINDEX values are from 1 to the value of ENDINDEX. The first registration block has index number 1.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 2-byte field containing the starting index value.