• If changed data is written to the cache, the total number of entries containing either changed or locked-for-cast-out data, that are assigned to the storage class to which the entry was written, is returned (field CAATOTCHANGED).
• If changed data is written to the cache, the total number of data items assigned to the cast-out class to which data was just written is returned (field CAACOCOUNT).

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 information returned from the request may be stored.

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

31

The entry in BUFLIST is 31 bits in size.

64

The entry in BUFLIST is 64 bits in size.

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.

Note that for WRITE_DATALIST requests, real storage addresses cannot be used.

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.

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 data to be written to the entry in the structure.

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 specifications for the BUFADDRTYPE and BUFADDRSIZE keywords. However, pageable high shared virtual storage areas (above 2GB) may not be used.

For WRITE_DATALIST requests, the first buffer pointed to by the first element in the BUFLIST can contain up to 16 WOBs; the remainder of the buffers in BUFLIST can contain data to be written to the entries specified by the WOBs. The first buffer must reside in 31-bit virtual storage. All other buffers pointed to by BUFLIST can reside in either 31-bit or 64-bit virtual storage. Real storage addresses cannot be used for any buffers in BUFLIST.

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 storage area that contains a list of buffer addresses.

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

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.

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.

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.

A value of 0 implies that there is no actual data being passed in the storage area specified by BUFFER or BUFLIST. When this occurs, all WOBs have to specify an ELEMNUM of 0 to indicate that no data is being passed in to go with those WOBs. If any WOB specifies an ELEMNUM other than 0, the request will fail with return code IXLRETCODEPARMERROR, reason code IXLRSNCODEBADELEMNUM.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a halfword field that contains the offset into the data block.

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

LOCALREGCNTL=YES is only meaningful when write operations are issued to cache structures allocated in a coupling facility that supports write suppression based on local cache registration. If the cache structure is allocated in a coupling facility that does not support write suppression based on local cache registration, the write operations will be performed as if LOCALREGCNTL=NO was specified.

NO

The write operations will be performed normally without write suppression.

If a write operation is suppressed due to assignment suppression, the data is not written, the index of the write-operation block that failed, and the offset in the data block of the data area for the write-operation block being processed is returned in the ANSAREA. The WRITE_DATALIST request fails with a return code IXLRETCODEPARMERROR, reason code IXLRSNCODENOENTRY. All prior write-operation blocks were processed.

YES

Suppress the write operations when the user's connection (local cache) is the only registered interest in a data item and the data entry for the data item does not contain cached subsystem data. When the write operation is suppressed, no data is written to the cache structure.

The CAAWRITESUPPRESSVECTOR in the ANSAREA indicates whether write-operation block write requests were suppressed during the WRITE_DATALIST request. Each bit represents a corresponding write-operation block in the storage area specified by BUFFER or BUFLIST for the WRITE_DATALIST request that specified LOCALREGCNTL=YES. The CAAWRITESUPPRESSEDVECTOR should be processed whenever the WRITE_DATALIST request completes with a return code of IXLRETCODEOK or the return and reason code indicates that the WRITE_DATALIST request completed prematurely and all the write operations prior to the premature completion were processed.

When the subsystem data is not written to the cache structure, the local cache buffer contains the only valid copy of the subsystem data. Hardening of the subsystem data to permanent storage should be performed to ensure availability and successful recovery of data in the event of a failure.

The assignment suppression control indicator and change control indicator must be set in each write-operation block when LOCALREGCNTL=YES is specified.

When issuing a WRITE_DATALIST request using LOCALREGCNTL=YES to write data to a cache structure that is in user-managed duplex mode, the following programming technique should be followed:

• When using registration, assignment or write suppression protocols in the primary structure of a user-managed duplexed structure, unconditional writes of changed data to the secondary structure specifying LOCALREGCNTL=NO on the WRITE_DATALIST request and WOB_ASC = '0'b in each write-operation block should be performed after successful write operations to the primary structure. If write operations to the primary structure resulted in the writes being suppressed, then those write operations should not be issued to the secondary structure.

  The storage area specified by BUFFER or BUFLIST that contains the write-operation blocks should be updated to remove write-operation blocks and corresponding data areas for write operations to the primary structure that were suppressed due to assignment suppression or write suppression conditions. The CaaWriteSuppressVector in the ANSAREA indicates which, if any, write-operation block write requests were suppressed. Each bit represents a corresponding write-operation block in the storage area specified by BUFFER or BUFLIST for the WRITE_DATALIST request that specified LOCALREGCNTL=YES.

  The WRITE_DATALIST request should be issued to the secondary structure with the updated BUFFER or BUFLIST and LOCALREGCNTL=NO so that write suppression is ignored.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an 192-byte area to contain the write-operation response block data.