Parameter Descriptions

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

REQUEST=CASTOUT_DATA

Use this input parameter to:

Specify that a cast-out lock be obtained for the data item identified by NAME, and that the named data item be read into the storage areas specified BUFFER or BUFLIST and/or ADJAREA.
Optionally register interest in the data item (Specify REGUSER=YES also).

,ADJAREA=NO_ADJAREA

,ADJAREA=adjarea

Use this output parameter to specify a storage area to contain the adjunct data that was read from the designated entry.

If the structure supports adjunct data and ADJAREA is not specified, or if ADJAREA=NO_ADJAREA is specified, then no adjunct data is returned.

If the structure does not support adjunct data and ADJAREA is specified, then no adjunct data is returned, and the request will complete with a return code X'4' and a reason code of IXLRSNCODENOADJUNCTDATA.

If the structure supports adjunct data and ADJAREA is specified, but there is no data and adjunct associated with the entry, then:

For READ_DATA requests, the request completes with return code X'4' and reason code IXLRSNCODENOREADDATA.
For CASTOUT_DATA requests, the request completes with return code X'8' and reason code IXLRSNCODECOUNCHANGED.

(Adjunct areas for a structure are established through the IXLCONN macro.)

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 64-byte virtual storage area that the adjunct data will be read into.

,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. On a successful completion of the request, the following information is returned in the answer area:

The parity of the returned data item (field CAAPARITY).
If REGUSER=YES is specified and the request replaced a previously specified local cache vector index for the entry, the replaced index is returned (fields CAAINVLCVI and CAAINVLCVINUM).
If BUFFER or BUFLIST is specified, the number of elements in the retrieved entry is returned (field CAAELEMNUM).

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

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

,BUFADDRSIZE=31

,BUFADDRSIZE=64

Use this input parameter to specify whether a 31-bit or a 64-bit address is specified by a BUFLIST entry.

31: The entry in BUFLIST is 31 bits in size.
64: The entry in BUFLIST is 64 bits in size.

,BUFADDRTYPE=VIRTUAL

,BUFADDRTYPE=REAL

Use this input parameter to specify whether the buffer addresses specified in the BUFLIST list are virtual storage or real storage addresses.

VIRTUAL: The buffer addresses are virtual storage addresses. The virtual storage can be pageable or nonpageable. See the PAGEABLE parameter for information about managing storage binds when specifying virtual storage addresses.
REAL: The buffer addresses are real storage addresses.
It is the caller's responsibility to manage the binds between the data buffer virtual storage and the real storage addresses provided. The caller must ensure that the data buffer virtual storage remains bound to the real storage addresses provided until the request completes.

,BUFALET=NO_BUFALET

,BUFALET=bufalet

Use this input parameter to specify an access list entry token (ALET) to be used in referencing all of the buffers specified by BUFLIST.

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

,BUFFER=buffer

Use this output parameter to specify a buffer area to hold the entry data that is cast out from the cache structure. Only 31-bit addressable storage areas (below 2GB) are supported by the BUFFER specification. High virtual storage areas (above 2GB) can only be specified via the BUFLIST specification.

You can define the buffer size to be a total of up to 65536 bytes. 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 receive the entry requested.

,BUFINCRNUM=bufincrnum

Use this input parameter to specify the number of 256-byte segments comprising each buffer in the BUFLIST list.

Valid BUFINCRNUM values are 1,2,4,8, or 16, which correspond to BUFLIST buffer sizes of 256, 512, 1024, 2048, and 4096 bytes respectively.

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

BUFLIST=buflist

Use this output parameter to specify a list of buffers to hold the entry data that is cast out of the cache structure. BUFLIST specifies a 128-byte storage area that consists of a list of 0 to 16 buffer addresses.

Either 31-bit addressable (below 2GB) or 64-bit addressable (above 2GB) real or virtual storage areas are supported for the BUFLIST specification, depending on the specification for the BUFADDRTYPE and BUFFADDRSIZE keywords. However, pageable high shared virtual storage areas (above 2GB) may not be used.

The format of the list is a set of 8-byte elements. The BUFADDRSIZE keyword denotes whether four or eight bytes of the element are used.

If BUFADDRSIZE=31 is specified, then the first four bytes of each element are reserved space and the last four bytes contain the address of the buffer.
If BUFADDRSIZE=64 is specified, then the full eight bytes specify the address of the buffer.

The BUFLIST buffers must:

Reside in the same address space or data space.
Be the same size: either 256, 512, 1024, 2048, or 4096 bytes.
Start on a 256-byte boundary and not cross a 4096-byte boundary.
Note: The buffers do not have to be contiguous in storage. XES treats BUFLIST buffers as a single buffer even if the buffers are not contiguous.

See the BUFNUM and BUFINCRNUM keyword descriptions for specifying the number and size of buffers.

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 a 128-byte field that contains a list of buffer addresses.

,BUFNUM=bufnum

Use this input parameter to specify the number of buffers in the BUFLIST list. Valid BUFNUM values are from 0 to 16. A value of zero indicates that no data is to be read into the buffers.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 1-byte field that contains the number of buffers (0 to 16) in the list (BUFLIST).

,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 buffers specified by BUFLIST or the buffer specified by BUFFER.

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

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an 8-bit field that contains the storage key in the format B'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.

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

,NAME=name

Use this input parameter to specify the name of the data item to be cast-out and for which the cast-out lock will be obtained.

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

,OLDNAME=NO_OLDNAME

,OLDNAME=oldname

Use this input parameter to specify the name of the data item for which your interest should be deregistered.

For structures allocated in a coupling facility of CFLEVEL=4 or lower, you must also specify the name of the data item for which interest is to be registered after the interest is deregistered in OLDNAME. Identify the data item to which interest is to be registered with NAME. The VECTORINDEX currently associated with the entry specified by OLDNAME will be reassigned to the name of the data item specified by NAME.
For structures allocated in a coupling facility of CFLEVEL=5 or higher, you can specify that interest in the name of the data item specified by OLDNAME is to be deregistered without registering interest in the entry specified by NAME.

In either case, whenever deregistration of interest is requested, VECTORINDEX must be specified.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 16-byte field that contains the name of the old data item that was associated with VECTORINDEX.

,PAGEABLE=YES

,PAGEABLE=NO

Use this input parameter to identify whether the storage areas specified by BUFFER or BUFLIST are in pageable or potentially pageable storage.

YES

Specify this option to indicate that the BUFFER or BUFLIST buffers reside in pageable virtual storage. XES performs the required page fixing to fix the buffers in real storage while the cache or list request transfers data to or from the coupling facility.

This includes storage obtained from pageable subpools, disabled reference (DREF) storage, and may include storage that has the potential to become pageable during the processing of a request. (An example is address space storage owned by any swappable address space, for which a PGSER FIX has been successfully processed, but for which the owning address space gets swapped during processing of a cache or list request.) This does not include implicitly non-pageable storage (for example, storage obtained from non-pageable subpools).

The system takes responsibility for managing binds to central storage for the duration of the cache or list request, regardless of what address space owns the storage or whether the storage-owning address space is swappable or nonswappable. The storage can be owned by any address space.

High shared virtual storage areas (above 2GB) may not be used.

NO

Specify this option to indicate that the BUFFER or BUFLIST buffers reside in non-pageable virtual storage. XES does not page fix the buffers in real storage.

This includes implicitly non-pageable storage areas (for example, storage obtained from non-pageable subpools), and may include storage that has the potential to become pageable during the processing of a request (An example is address space storage owned by any swappable address space, for which a PGSER FIX has been successfully processed, but for which the owning address space gets swapped-out during processing of a cache or list request.)

The system takes responsibility for managing binds to central storage for the duration of the cache or list request, if and only if the non-pageable storage is owned by either the requestor's address space or the connector's address space. If the storage is owned by any other address space, then the invoker is responsible for ensuring that the virtual storage remains non-pageable for the duration of the request (including the case in which the storage is owned by a swappable address space that is swapped during processing of an IXLCACHE or IXLLIST request). Subject to this consideration, the storage can be owned by any address space. See z/OS MVS Programming: Sysplex Services Guide.

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

,PROCESSID=NO_PROCESSID

,PROCESSID=processid

Use this input parameter to specify a user-defined process identifier to be compared with the cast-out lock along with the connection identifier.

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

,REGUSER=NO

,REGUSER=YES

Use this input parameter to specify whether the request should register (or update) interest in the data item to be cast-out.

NO: Connection interest in the data item will not be registered.
For structures allocated in a coupling facility with CFLEVEL=5 or higher, OLDNAME may be specified to deregister any outstanding interest for the specified local cache vector index for a different entry. If OLDNAME is specified, then VECTORINDEX is required.
YES: Connection interest in the data item will be registered for the connection specified by CONTOKEN. If interest is already registered, the vector index specified by VECTORINDEX replaces any previously specified index for the data item.
Specify OLDNAME to deregister any outstanding interest for the specified vector index for a different entry.

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

,VECTORINDEX=vectorindex

Use this input parameter to specify an index into your local cache vector to be associated with the data item specified by NAME, to be disassociated with the data item specified by OLDNAME, or both. The vector index identifies a vector entry that cache services will use to indicate both your interest in the data item and the validity of the copy of the data item in your local cache buffer.

If the vector index you specify is already associated with another data item, you must disassociate the vector index from the old name by specifying OLDNAME before the vector index can be associated with the data item specified by NAME.

On CASTOUT_DATA requests, for structures allocated in a coupling facility of CFLEVEL=5 or higher, VECTORINDEX is required when REGUSER=YES or OLDNAME is specified. For structures allocated in a coupling facility of CFLEVEL=4 or lower, VECTORINDEX is required when REGUSER=YES is specified.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 4-byte field that contains the vector index for NAME or OLDNAME.