Parameter Descriptions

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

REQUEST=MOVE

Use this input parameter to move an entry.

,ADJAREA=NO_ADJAREA

,ADJAREA=adjarea

Use this input parameter to specify a storage area to contain the adjunct data that is read from or written to an entry.

Specify ADJAREA only for structures that support adjunct data. (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 area that contains or will contain the adjunct data.

,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 mapping macro IXLYLAA.

On a successful completion (for a synchronous request: RC=0, for an asynchronous request: ECB is posted, IXLFCOMP indicates completion, or your complete exit ran) of the request, the following information is returned to the answer area:

List entry controls of the existing or new entry (field LAALCTL).
The number of list entries or elements residing on the list (field LAALISTCNT).
The total number of allocated entries in the structure (field LAATOTALCNT).
The total number of allocated elements in the structure (field LAATOTALELECNT).

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

,ANSLEN=anslen

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

Check the prologue of the IXLYLAA mapping macro for the minimum required size of the answer area, or use the length field (LAA_LEN) in the LAA.

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

,AUTHCOMP=NO_AUTHCOMP

,AUTHCOMP=authcomp

Use this input parameter to specify a value to be compared to the list authority value of the list specified by LISTNUM. You must supply the LISTNUM parameter.

If the comparison does not meet the condition specified by the AUTHCOMPTYPE parameter (EQUAL or LESSOREQUAL), the request fails.

Note: The AUTHCOMP parameter is valid only for list structures allocated in a coupling facility with CFLEVEL=1 or higher.

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

,AUTHCOMPTYPE=EQUAL

,AUTHCOMPTYPE=LESSOREQUAL

Use this input parameter to specify how the list authority comparison is to be performed.

EQUAL: The list authority for the list specified by LISTNUM must be equal to the value specified for AUTHCOMP.
LESSOREQUAL: The list authority for the list specified by LISTNUM must be less than or equal to the value specified for AUTHCOMP.

Note: The AUTHCOMPTYPE parameter is valid only for list structures allocated in a coupling facility with CFLEVEL=1 or higher.

,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 or input parameter to hold entry data to be read from or written to the designated entry. The purpose of the BUFFER area depends on the DATAOPER value you specify:

If you specify DATAOPER=READ, the buffers hold output data—entry data that was read from an existing entry.
If you specify DATAOPER=WRITE, the buffers hold input data—entry data to be written to an existing or new entry.

You can define the buffer size to be a total size of up to 65536 bytes. Depending on the size you select, the following restrictions apply:

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

See the BUFSIZE parameter description for defining the size of the buffer.

Note: You cannot code BUFFER with MODE=ASYNCNORESPONSE.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an area (with a length of BUFSIZE) that contains the entry data.

,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 or input parameter to specify a list of buffers to hold entry data to be read from or written to the designated entry. The purpose of the BUFLIST buffers depend on the DATAOPER value you specify:

If you specify DATAOPER=READ, the buffers hold output data—entry data that was read from an existing entry.
If you specify DATAOPER=WRITE, the buffers hold input data—entry data to be written to an existing or new entry.

BUFLIST specifies a 128-byte storage area that consists of a list of 0 to 16 buffer addresses.

The 128-byte storage area must:

Consist of 0 to 16 elements.
Each element must consist of an 8-byte field in which:
- The left (high-order) four bytes are reserved and
- The right (low-order) four bytes contain the address of a buffer.

The BUFLIST buffers must:

Reside in either 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. (List services treats BUFLIST buffers as a single, contiguous buffer, even if the buffers are not contiguous.)

See the BUFNUM and BUFINCRNUM parameter descriptions for defining the number and size of buffers.

Note: You cannot code BUFLIST with MODE=ASYNCNORESPONSE.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 128-byte area that contains the 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 or written to the list entry.

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

,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. The connect token uniquely identifies your connection to the list structure, and must be specified on each IXLLIST invocation.

The connect token is available in the IXLCONN answer area mapped by IXLYCONA.

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.

,CURSORUPDTYPE=NEXT

,CURSORUPDTYPE=NEXTCOND

,CURSORUPDTYPE=CURRENT

,CURSORUPDTYPE=CURRENTCOND

Use this input parameter to specify how the list cursor is to be updated when UPDATECURSOR=YES is specified.

Note: The NEXTCOND, CURRENT, and CURRENTCOND values are valid only for list structures allocated in a coupling facility with CFLEVEL=1 or higher.

CURSORUPDTYPE=NEXT

Update the list cursor to point to the list entry before or after the target entry.

For MOVE requests that specify DATAOPER=WRITE and ENTRYTYPE=ANY and that result in the creation of a new entry, the cursor for the list specified by MOVETOLIST is updated. The direction of the cursor update depends on the value specified for MOVETOPOS.
For all other requests, the cursor for the source list is updated. The direction of the cursor update depends on the value specified for LISTPOS or LISTDIR.

CURSORUPDTYPE=NEXTCOND

Update the list cursor to point to the list entry before or after the target entry only if the cursor points to the target list entry, and that list entry is moved or deleted.

Set the list cursor direction with SETCURSOR on a WRITE_LCONTROLS request.

The list cursor will be reset to binary zeros if either:

The entry is the last entry on the list and the list cursor direction is set to a head-to-tail direction.
The entry is the first entry on the list and the list cursor is set to a tail-to-head direction.

CURSORUPDTYPE=CURRENT

Set the list cursor to point to the list entry processed for the request.

If the list entry is deleted or moved to another list, then the list cursor will be reset to binary zeros.

CURSORUPDTYPE=CURRENTCOND

Set the list cursor to point to the list entry processed only if the list cursor value currently is zero and the target list entry is not deleted or moved to another list.

If the list entry is deleted or moved to another list, then the list cursor will remain binary zeros.

,DATAOPER=NONE

,DATAOPER=READ

,DATAOPER=WRITE

Use this input parameter to specify an operation to be performed on the designated entry.

NONE

The existing entry is moved; no additional operation is performed.

READ

The existing entry is moved, and its entry data and/or adjunct data is read:

If you specified BUFFER or BUFLIST, the entry data is read into whichever buffer area you have specified.
If you specified ADJAREA, the adjunct data is read into the adjunct area.

WRITE

The existing entry is moved, and its entry data and/or adjunct data is updated. If this request creates a new entry, the entry data and/or adjunct data is written to the new entry:

If you specified BUFFER or BUFLIST, the entry data is written to the existing or new entry.
If you specified ADJAREA, the adjunct data is written to the existing or new entry.

,ELEMNUM=elemnum

Use this input parameter to specify the number of elements to be allocated to the existing or new data entry. Valid ELEMNUM values are from zero to the MAXELEMNUM value that was specified on the IXLCONN macro.

Considerations for specifying ELEMNUM are:

If this request creates a new entry, the number of elements is set to the ELEMNUM value.
If the entry already exists, the number of elements is updated to the ELEMNUM value specified.

Note: If the data from the buffers exceeds the amount of space in the elements, the data will be truncated. If the data from the buffers is less than the amount of space in the elements, the remaining space will be padded with binary zeros.

If you specify an ELEMNUM value of zero:

No entry data will be written to the new entry.
Any entry data in the existing entry will be deleted.

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

,ENTRYID=entryid

Use this input parameter to designate the entry identifier of an existing entry to be moved. ENTRYID applies only to locating an existing entry; it does not determine the identifier of a new entry should one be created.

If an entry with this identifier does not exist (and ENTRYTYPE=ANY is specified), a new entry is created on the MOVETOLIST list with a unique entry identifier assigned by list services. (The entry identifier you specify will be ignored.)

When ENTRYID is specified with ENTRYNAME, ENTRYKEY, or LISTPOS, list services uses only ENTRYID to determine if the entry already exists.

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

,ENTRYKEY=NO_ENTRYKEY

,ENTRYKEY=entrykey

Use this input parameter to either:

Designate the entry key of an existing entry to be moved.
Assign an entry key to a new entry to be created, if MOVETOKEY is not specified. If MOVETOKEY is specified, the MOVETOKEY key is assigned to the new entry.

The existing entry must reside on the LISTNUM list. The existing entry will be placed on the MOVETOLIST list. If a new entry is created it will be placed on the MOVETOLIST list.

If DATAOPER=NONE or DATAOPER=READ is specified, the specified entry key designates an existing entry.

If DATAOPER=WRITE is specified, the specified entry key designates an existing entry or can be assigned to a new entry. See z/OS MVS Programming: Sysplex Services Guide for information about how entry keys are assigned to existing or created entries.

Specify ENTRYKEY only for structures that support keyed entries.

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

,ENTRYNAME=entryname

Use this input parameter to either:

Designate an existing entry to be moved.
Assign an entry name to a new entry to be created.

Both existing and new entries will be placed on the MOVETOLIST list.

If DATAOPER=NONE or DATAOPER=READ, the specified entry name designates an existing entry.

If DATAOPER=WRITE is specified, whether the specified entry name designates an existing entry or is assigned to a new entry depends on the following:

If either of the following is true, the specified entry name designates an existing entry:
- ENTRYTYPE=OLD, and the entry already exists.
- ENTRYTYPE=ANY, neither ENTRYID nor LOCBYCURSOR is also specified, and the entry already exists.
- If ENTRYTYPE=ANY and the entry does not already exist, a new entry is created with the ENTRYNAME name assigned to it.

Specify ENTRYNAME only for structures that support named entries. Each entry name is unique within the structure.

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

,ENTRYTYPE=ANY

,ENTRYTYPE=OLD

Use this input parameter to specify whether you want to either:

Update an existing entry or create a new entry
Update an existing entry

ANY: Either update an existing entry or create a new entry. If the entry exists, its data is replaced with the new data. If the entry does not exist, one will be created with the new data.
OLD: Update an existing entry. The entry must already exist, or the request fails.

,KEYREQTYPE=EQUAL

,KEYREQTYPE=LESSOREQUAL

,KEYREQTYPE=GREATEROREQUAL

Use this input parameter to specify how, if at all, the entry key of the existing entry to be moved can differ from the entry key specified by ENTRYKEY. KEYREQTYPE applies only to locating an existing entry; it does not determine the key of a new entry should one be created.

EQUAL: The entry must have a key that equals the ENTRYKEY key.
LESSOREQUAL: The entry must have a key that is less than or equal to the ENTRYKEY key.
GREATEROREQUAL: The entry must have a key that is greater than or equal to the ENTRYKEY key.

Note:

When no entries on the list meet the requirements of the KEYREQTYPE, and a new entry cannot be created (TYPE=OLD was specified), the request will be failed with a return code X'8' and reason code IXLRSNCODENOENTRY, or a new list entry will be allocated, depending on the other options specified.
When LESSOREQUAL or GREATEROREQUAL are specified, if no entries on the list have an entry key value equal to the specified value, but entries exist with an entry key value greater than (if GREATEROREQUAL was specified), or less than (if LESSOREQUAL was specified) the entry key value specified, then the entry with an entry key value closest to the value specified will be selected. When multiple entries have the same entry key value, LISTPOS is used to resolve whether the first or last entry with the entry key value is selected.

,LISTDIR=TOTAIL

,LISTDIR=TOHEAD

Use this input parameter with UPDATECURSOR to specify the direction in which the list cursor is moved as a result of this request. See the UPDATECURSOR parameter for a full description of LISTDIR.

,LISTKEYINC=NO_LISTKEYINC

,LISTKEYINC=listkeyinc

Use this input parameter to specify a value to be added to the list key after the entry key is set to the list key value. If the entry key is not set to the list key value, the list key value will not be changed. If the result of adding the value specified by LISTKEYINC to the list key value is greater than the maximum list key value, the system fails the request.

Note: The LISTKEYINC parameter is valid only for list structures allocated in a coupling facility with CFLEVEL=1 or higher.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the fullword field that contains the value to be added to the list key after the entry key is set to the list key value.

,LISTKEYTYPE=NOLISTKEY

,LISTKEYTYPE=MOVE

,LISTKEYTYPE=ANY

Use this input parameter to specify when the designated entry key is to be set to the current list key value. You can set the entry key to the current list key value when you move the entry.

(Set the list key and maximum list key values with a WRITE_LCONTROLS request.)

Note: The LISTKEYTYPE parameter is valid only for list structures allocated in a coupling facility with CFLEVEL=1.

LISTKEYTYPE=NOLISTKEY: Do not set the entry key for the target list entry to the current list key value. If the list entry is moved and the list structure supports entries with keys, then the other parameters specified (such as ENTRYKEY) will determine the resultant entry key value.
LISTKEYTYPE=MOVE: Set the entry key for the designated list entry to the current list key value if the entry is moved by this request.
LISTKEYTYPE=ANY: Set the entry key for the designated list entry to the current list key value if the entry is moved or created by this request. (This parameter also applies when you WRITE an entry.)

,LISTNUM=NO_LISTNUM

,LISTNUM=listnum

Use this input parameter to specify the number of the list on which the entry to be moved currently resides. Use LISTNUM in the following ways:

With LISTDIR and/or ENTRYKEY to designate an existing entry to be moved.
With ENTRYID or ENTRYNAME to:
- Check if the entry exists on the list (when ENTRYTYPE=ANY) before proceeding with the request.
- Confirm that the entry exists on the list (when ENTRYTYPE=OLD) before proceeding with the request.
With LOCBYCURSOR to designate an existing entry to be moved.

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

,LISTPOS=HEAD

,LISTPOS=TAIL

Use this input parameter with LISTNUM to designate the existing entry to be moved. LISTPOS applies only to locating an existing entry; it does not determine where a new entry would be placed should one be created. (See the MOVETOPOS parameter for a description of where a new entry is placed.)

LISTPOS designates the entry at the HEAD or the TAIL of a list or sublist:

If you specify ENTRYKEY to designate the entry and the list contains a sublist of one or more entries with the same key (or that satisfies the KEYREQTYPE criteria), then:
- LISTPOS=HEAD designates the entry at the head of the sublist.
- LISTPOS=TAIL designates the entry at the tail of the sublist.
If you do not specify ENTRYKEY to designate the entry:
- LISTPOS=HEAD designates the entry at the head of the list.
- LISTPOS=TAIL designates the entry at the tail of the list.

,LOCBYCURSOR

Use this input parameter to designate an existing entry to be moved. The designated entry is the entry to which the LISTNUM list cursor is pointing.

Be aware that the list cursor could have been reset to zeros by a previous request that, for instance, deleted or moved the entry to which the list cursor points, or updated the list cursor after the last entry on the list had been processed. See z/OS MVS Programming: Sysplex Services Guide for more information about using the list cursor.

,LOCKCOMP=NO_LOCKCOMP

,LOCKCOMP=lockcomp

This parameter has slightly different meanings based on the value specified for the LOCKOPER parameter. Generally, this input parameter specifies a connection identifier to be verified as the owner of the lock specified by LOCKINDEX. This verification is a prerequisite to the successful completion of the request.

When LOCKCOMP is specified, the completion of the request is conditional on there being no contention for the lock. If contention exists, the request will fail.

The connection identifier is available from the IXLCONN answer area, mapped by IXLYCONA, in field CONACONID.

The effect of LOCKCOMP is based on the LOCKOPER value specified. See the description under LOCKOPER to see how each request is affected by this parameter.

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

,LOCKDATA=NO_LOCKDATA

,LOCKDATA=lockdata

Use this input parameter to specify information that is to be passed to your notify exit when another user requests the LOCKINDEX lock after you have obtained the lock using LOCKOPER=SET. This user-defined information will be passed to your notify exit when the other user issues a request specifying either one of the following:

LOCKOPER=SET
LOCKOPER=NOTHELD with LOCKMODE=UNCOND

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

,LOCKINDEX=NO_LOCKINDEX

,LOCKINDEX=lockindex

Use this input parameter to specify the index of the lock to be operated on as specified by LOCKOPER. The lock indexes begin with zero.

Note: You cannot code LOCKINDEX with MODE=ASYNCNORESPONSE.

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

,LOCKMODE=UNCOND

,LOCKMODE=COND

Use this input parameter to specify how contention for the lock specified by LOCKINDEX should be handled if your request causes lock contention.

UNCOND

If the specified lock is held by another user, your request is either:

Suspended until the lock becomes available (if MODE=SYNCSUSPEND is specified).
Performed asynchronously with notification to you when the request completes (if any MODE value other than SYNCSUSPEND is specified).

COND

The lock operation will be performed conditionally; that is, only if there is no contention for the lock. If the specified lock is held by another user, the request will be terminated with no change to the structure, and return and reason codes describing the termination are returned to the caller.

,LOCKOPER=SET

,LOCKOPER=RESET

,LOCKOPER=NOTHELD

,LOCKOPER=HELDBY

Use this input parameter to specify the type of operation to be performed on the lock specified by LOCKINDEX.

SET

Set the lock.

When LOCKCOMP is not specified, your connection gets the lock, providing no other connection holds the lock. If another connection holds the lock, the request either continues once the lock is released or fails, depending on the LOCKMODE value you specify.
When LOCKCOMP is specified, if the connection specified by LOCKCOMP holds the lock, the lock will be transferred to your connection.

RESET

Reset the lock.

When LOCKCOMP is not specified, the lock will be released if it is held by your connection.
When LOCKCOMP is specified, the lock will be released if it is held by the connection specified by LOCKCOMP.

NOTHELD

The request is performed only if the lock is not held by any connection. This option also ensures that the lock remains free for the duration of the request. If another connection holds the lock, your task is suspended until the lock is released or your request fails, depending on the LOCKMODE value you specify. See the LOCKMODE description for how to handle possible lock contention.

HELDBY

Processing is determined by which connector is holding the lock.

When LOCKCOMP is not specified, the request is performed only if your connection holds the lock.
When LOCKCOMP is specified, the request is performed only if the lock is held by the connection specified by LOCKCOMP.

,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

,MODE=ASYNCNORESPONSE

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

MODE=SYNCSUSPEND: The request is suspended until it can complete synchronously. To use this option, your program must be enabled for I/O and external interrupts.
MODE=SYNCECB: The request processes synchronously if possible. If the request processes asynchronously, the ECB specified by REQECB is posted when the request completes.
MODE=SYNCEXIT: The request processes synchronously if possible. If the request processes asynchronously, your complete exit is given control when the request completes.
MODE=SYNCTOKEN: The request processes synchronously if possible. If the request processes asynchronously, an asynchronous request token is returned in the area specified by REQTOKEN on invocation of the request. 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.
MODE=ASYNCECB: The request processes asynchronously. The ECB specified by REQECB is posted when the request completes.
MODE=ASYNCEXIT: The request processes asynchronously. Your complete exit is given control when the request completes.
MODE=ASYNCTOKEN: The request processes asynchronously. An asynchronous request token is returned in the area specified by REQTOKEN upon invocation of the request. 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.
MODE=ASYNCNORESPONSE: The request processes asynchronously. No notification of request completion is provided. The answer area (ANSAREA) fields will not contain valid information when this mode is specified.

Note: You cannot code MODE=ASYNCNORESPONSE with LOCKINDEX, BUFFER, or BUFLIST.

,MOVETOKEY=NO_MOVETOKEY

,MOVETOKEY=movetokey

Use this input parameter to assign a new key, and hence the position on the MOVETOLIST, for the existing entry being moved or the new entry being created. In the case of an existing entry, the existing entry's key will be updated to the MOVETOKEY key value. If MOVETOKEY is not specified, ENTRYKEY defines the key to use for the entry.

Note:

If there is a sublist of one or more entries with a matching key on the list then the target position is the head or tail of the sublist, as specified by the MOVETOPOS parameter.
If none of the list entries have a matching key, and MOVETOKEY is neither the greatest nor least among the list entry keys, then the target position is according to the appropriate key sequence for the list.

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

,MOVETOLIST=movetolist

Use this input parameter to specify the number of the target list where the existing entry being moved or the new entry being created will be placed.

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

,MOVETOPOS=HEAD

,MOVETOPOS=TAIL

Use this input parameter to specify the position where the existing or new entry will be placed on the MOVETOLIST.

HEAD

The entry is placed at the head of the list when:
- Keyed entries are not supported.
- Keyed entries are supported, a new entry is being created, and neither MOVETOKEY nor ENTRYKEY are specified.
The entry is placed at the head of the sublist of identically keyed entries when keyed entries are supported and one or more entries with the same key already exists on the MOVETOLIST list.

TAIL

The entry is placed at the tail of the list when:
- Keyed entries are not supported.
- Keyed entries are supported, a new entry is being created, and neither MOVETOKEY nor ENTRYKEY are specified.
The entry is placed at the tail of the sublist of identically keyed entries when keyed entries are supported and one or more entries with the same key already exists on the MOVETOLIST list.

,NEWAUTH=NO_NEWAUTH

,NEWAUTH=newauth

Use this input parameter to specify a list authority value for the list specified by LISTNUM. If NEWAUTH is omitted, the list authority for the designated list is unchanged.

When the structure is allocated, the authority value for each list is initialized to binary zeros.

Note: The NEWAUTH parameter is valid only for list structures allocated in a coupling facility with CFLEVEL=1 or higher, except on WRITE_LCONTROLS requests.

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

,NEWVERS=newvers

Use this input parameter with VERSUPDATE=SET to specify a version number to either replace the version number of the existing entry, or initialize the version number of a new entry.

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

,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 IXLLIST Version Support for a description of the options available with the PLISTVER macro.

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

,UPDATECURSOR=NO

,UPDATECURSOR=YES

Use this input parameter to specify whether the MOVETOLIST list cursor is to be updated to point to another entry on the list.

NO

The list cursor is not updated.

YES

The list cursor is updated to point to the entry that is adjacent to the new or moved entry.

If LISTDIR=TOHEAD, the list cursor will point to the adjacent entry that is closest to the head of the list.
If LISTDIR=TOTAIL, the list cursor will point to the adjacent entry that is closest to the tail of the list.

The list cursor is set to binary zeros if its new position would be before the first entry or after the last.

Note: UPDATECURSOR may not be specified when DATAOPER=WRITE and ENTRYTYPE=ANY are specified

,VERSCOMP=NO_VERSCOMP

,VERSCOMP=verscomp

Use this input parameter to specify a version number to be compared to the version number of the existing entry. If this request creates a new entry, the VERSCOMP specification is ignored.

The existing entry is moved only if its version number meets the condition specified by the VERSCOMPTYPE parameter. If the entry does not have the specified version number, the request is terminated with no change to the structure.

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

,VERSCOMPTYPE=EQUAL

,VERSCOMPTYPE=LESSOREQUAL

Use this input parameter to specify how a list entry version number comparison as specified by VERSCOMP is to be performed.

Note: The VERSCOMPTYPE parameter is valid only for list structures allocated in a coupling facility with CFLEVEL=1 or higher.

VERSCOMPTYPE=EQUAL: The version number for the list entry must be equal to the value specified for VERSCOMP.
VERSCOMPTYPE=LESSOREQUAL: The version number for the list entry must be less than or equal to the value specified for VERSCOMP.

,VERSUPDATE=NONE

,VERSUPDATE=INC

,VERSUPDATE=DEC

,VERSUPDATE=SET

Use this input parameter to specify how the entry version number of the moved entry will be updated, or for those cases where a new entry is created, initialized.

VERSUPDATE=NONE: The existing entry's version number is not updated. The new entry's version number is set to binary zeros.
VERSUPDATE=INC: The existing entry's version number is increased by one. The new entry's version number is set to binary zeros, except for the low-order bit, which is set to one.
VERSUPDATE=DEC: The existing entry's version number is decreased by one. The new entry's version number is set to all binary ones.
VERSUPDATE=SET: Both the existing and the new entry's version number is set to the value specified by NEWVERS.