Using Real Versus Virtual Storage

The IXLLIST service allows you to designate the data buffer storage in three different ways:

By real storage address
By pageable virtual storage address (including pageable subpools, disabled-reference (DREF) subpools, and page-fixed storage that might not remain page-fixed in a particular real storage location until the completion of the request)
By nonpageable virtual storage address (including fixed subpools and storage that might not remain page-fixed in a particular real storage location until the completion of the request)

(For information about whether a subpool is pageable, fixed, or DREF storage, see z/OS MVS Programming: Authorized Assembler Services Guide.

Specifying the PAGEABLE parameter with BUFFER and BUFLIST is a way to identify to the system whether the storage area you pass is in pageable or potentially pageable storage.

Real storage address

When data buffer storage is designated by real address, XES takes no responsibility for its ownership or its attributes. The IXLLIST invoker is entirely responsible for management of the storage binds.

For example, suppose a swappable connector

Obtains a pageable virtual storage buffer in storage associated with the connector's address space
Pagefixes the storage
Loads the real address of the buffer storage
Passes those real storage addressses to XES on a request

If the connector's address space were to be swapped out at some point after loading the real addresses, the system could free and then reassign the real storage frames backing the data buffer. (Page-fixed storage does not remain fixed in real storage when the owning address space is swapped out.) Then, if those real addresses were subsequently used to transfer data to or from the coupling facility, the results would be unpredictable because XES is unaware that the bind between the real addresses and the data buffer virtual storage has been broken.

To summarize: When data buffer storage is passed by real address, it is the caller's responsibility to manage the binds between the data buffer virtual storage and the real storage addresses provided to the coupling facility. The caller must ensure that the data buffer virtual storage remains bound to the real storage addresses provided until the request completes.

Pageable virtual storage address

When data buffer storage is designated by pageable virtual storage address (PAGEABLE=YES on the IXLLIST request), XES takes full responsibility for the ownership and its attributes regardless of what address space owns the storage. XES performs the required page fixing to fix the buffer in real storage while the IXLLIST request transfers data to or from the coupling facility. XES establishes the storage binds between the data buffer virtual storage and the real storage backing it and then releases those binds when the data transfer is complete.

If the storage-owning address space were to be swapped out while the XES-established storage binds exist, XES does not allow the swap-out to complete until those storage binds have been broken. The following three scenarios describe actions taken by XES at the time of the swap-out:

Coupling facility data transfer has not yet been initiated.
XES breaks the real storage binds associated with the request. When the address space is swapped-in again, XES re-establishes the storage binds for the request by once again fixing the data buffer virtual storage in real storage (which most likely is a different real storage location than the data buffer previously occupied). XES subsequently uses these real storage addresses for the coupling facility data transfer.
Coupling facility data transfer is actively in progress.
XES delays the swap-out until the coupling facility data transfer completes. When the address space is swapped-in again, the data transfer for the request is complete and there is no need to re-establish the storage binds for the request.
Coupling facility data transfer has completed.
XES breaks the real storage binds associated with the request (or, the storage binds might already have been broken, depending on when the swap-out occurred). When the address space is swapped-in again, the data transfer for the request is complete and there is no need to re-establish storage binds for the request.

To summarize: When data buffer storage is passed by pageable virtual storage address, XES is responsible for managing the binds between the data buffer virtual storage and the real storage used to transfer data to or from the coupling facility.

Nonpageable virtual storage address

When data buffer storage is designated by non-pageable virtual storage address (PAGEABLE=NO on the IXLLIST request), XES takes full responsibility for the ownership and its attributes if and only if the storage is owned by the requestor's or connector's address space. XES establishes the storage binds between the data buffer virtual storage and the real storage backing it and then releases those binds when the data transfer associated with the request is complete.

If the storage-owning address space (the requestor's or connector's address space) were to be swapped out while the XES-established storage binds exist, XES does not allow the swap-out to complete until those storage binds have been broken. The following three scenarios describe actions taken by XES at the time of the swap-out:

Coupling facility data transfer has not yet been initiated.
XES breaks the real storage binds associated with the request. When the address space is swapped-in again, XES re-establishes the storage binds for the request (which most likely is a different real storage location than the data buffer previously occupied). XES subsequently uses these real storage addresses for the coupling facility data transfer.
Coupling facility data transfer is actively in progress.
XES delays the swap-out until the coupling facility data transfer completes. When the address space is swapped-in again, the data transfer for the request is complete and there is no need to re-establish the storage binds for the request.
Coupling facility data transfer has completed.
XES breaks the real storage binds associated with the request (or, the storage binds might already have been broken, depending on when the swap-out occurred). When the address space is swapped-in again, the data transfer for the request is complete and there is no need to re-establish storage binds for the request.

To summarize: When data buffer storage is passed by nonpageable virtual storage address, XES is responsible for managing the binds between the data buffer virtual storage and the real storage used to transfer data to or from the coupling facility if and only if the storage is owned by the requestor's or connector's address space.

Note:

If you specify PAGEABLE=NO and your request is processed synchronously, you can free storage when you receive control back from IXLLIST and check the return code to verify that your request was performed synchronously.
Table 1 shows how long you must keep storage areas fixed for each processing mode if you specify PAGEABLE=NO and the system processes the request asynchronously.

Table 1. When Storage Areas Passed to IXLLIST Can Be Made Pageable
MODE Value	When Storage Can Be Made Pageable
ASYNCECB or SYNCECB	After ECB is posted
ASYNCTOKEN or SYNCTOKEN	When your program regains control from the IXLFCOMP service and the request has completed
SYNCEXIT	When your completion exit receives control