Parameter Descriptions

The parameter descriptions for IXLLSTM are listed in alphabetical order. Default values are underlined:

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

If the structure was allocated to use secondary keys, the first 32 bytes of ADJDATA will contain the secondary key of the entry.

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=ansarea

Use this input 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.

Not all fields in the answer area are applicable to all request types. Request type descriptions indicate which answer area fields are applicable for successful request completion cases. Return and reason code description indicates which answer area fields are applicable for non-successful completing requests.

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.

,AUTHCOMPARE=NO

,AUTHCOMPARE=YES

Use this input parameter to specify whether the list authority comparison is to be used to determine if entries on the list should be processed.

NO: No list authority comparison is to be performed before processing any of the list entries.
YES: List authority comparison should precede processing of any list entries.

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

,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 parameter to hold data for the request. The BUFSIZE keyword specifies the size of the buffer. For READ_LIST and READ_MULT requests, BUFFER is an output parameter. For MOVE_ENTRYLIST and DELETE_ENTRYLIST requests, BUFFER is an input parameter. For all IXLLSTM request types, the length of the buffer must be a multiple of 4096 bytes between 4096 and 65536 and the buffer must start on a 4096-byte (page) boundary.

Upon successful completion of a READ_LIST or READ_MULT request, the BUFFER area is used for output and contains, starting at offset zero, an array of elements. One array element is returned for each processed entry. The number of elements returned in the BUFFER area is indicated in the answer area. The length of an array element can be determined by its make-up: the structure element size, the number of elements in the entry, an adjunct data size (64 bytes), and the length of list entry controls. (The length and contents of list entry controls is defined by mapping macro IXLYLCTL.)
For READ_LIST and READ_MULT requests, each array element is constructed as follows, dependent on the request options specified:
- When adjunct data is requested, the adjunct data for the first entry processed is returned in the storage area specified by ADJAREA. The adjunct data for all other entries processed is returned in the BUFFER area.
- When list entry controls are requested, the entry controls for the first entry processed are returned in the answer area specified by ANSAREA. The entry controls for all other entries processed are returned in the BUFFER area.
The format of each array element in the BUFFER, therefore, is as follows:
- When TYPE=ENTDATA is specified, entry data for each list entry processed is contained in the buffer.
- When TYPE=ADJDATA is specified, adjunct data for each list entry processed after the first entry is contained in the buffer. (The adjunct data for the first entry processed is returned in ADJAREA.)
- When TYPE=ECONTROLS is specified, list entry controls for each list entry processed after the first entry is contained in the buffer. (The list entry controls for the first entry is returned in ANSAREA.)
- When TYPE=(ENTDATA,ADJDATA) is specified, entry data for the first list entry processed is contained in the buffer, followed by the entry data and then the adjunct data for each additional list entry processed.
- When TYPE=(ENTDATA,ECONTROLS) is specified, entry data for the first list entry processed is contained in the buffer, followed by the list entry controls and then the entry data for each additional list entry processed.
- When TYPE=(ADJDATA,ECONTROLS) is specified, list entry controls followed by adjunct data for each list entry processed after the first is contained in the buffer.
- When TYPE=(ENTDATA,ADJDATA,ECONTROLS) is specified, entry data for the first list entry processed is contained in the buffer, followed by list entry controls, entry data, and adjunct data (in that order) for each additional list entry processed.
For MOVE_ENTRYLIST requests, BUFFER is used for input and should be formatted into 32-byte, 64-byte, or 96-byte elements, where each element is mapped by IXLYMELI and contains the information required to move a list entry. The format and size of an element is determined by the options specified on the MOVE_ENTRYLIST request.
- A 32-byte element is required for any one of the following conditions:
  - The structure does not support keyed entries and VERSCOMPARE=NO is specified.
  - The structure does not support keyed entries and VERSCOMPARE=YES is specified.
  - The structure does support keyed entries and MOVETOKEY=UNCHANGED, MOVETOSKEY=UNCHANGED, and VERSCOMPARE=NO are specified.
  - The structure does support keyed entries and MOVETOKEY=UNCHANGED, MOVETOSKEY=UNCHANGED, and VERSCOMPARE=YES are specified.
  - The structure does support keyed entries and MOVETOKEY=LISTKEY, MOVETOSKEY=UNCHANGED, and VERSCOMPARE=NO are specified.
  - The structure does support keyed entries and MOVETOKEY=LISTKEY, MOVETOSKEY=UNCHANGED, and VERSCOMPARE=YES are specified.
- A 64-byte element is required for the following conditions:
  - VERSCOMPARE=BYENTRY or MOVETOKEY=TARGETKEY is specified.
- A 96-byte element is required for the following condition:
  - MOVETOSKEY=TARGETKEY is specified.
For DELETE_ENTRYLIST requests, the BUFFER area is used as input and should be formatted into 12-byte, 16-byte, or 64-byte elements, where each element is mapped by the IXLYDELI macro and contains all the information required to delete a list entry. The format and size of an element is determined by the options specified on the DELETE_ENTRYLIST request.
- A 12-byte element is required for any one of the following conditions:
  - VERSCOMPARE=NO and LISTTYPE=IDLIST are specified.
  - VERSCOMPARE=YES and LISTTYPE=IDLIST are specified.
- A 16-byte element is required for any one of the following conditions:
  - VERSCOMPARE=NO and LISTTYPE=NAMELIST are specified.
  - VERSCOMPARE=YES and LISTTYPE=NAMELIST are specified.
- A 64-byte element is required when VERSCOMPARE=BYENTRY is specified.

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.

,BUFLIST=buflist

Use this output or input parameter to specify a list of buffer addresses to hold data for the request. The set of buffers is used as if it were a single contiguous area.

The format of the list is a set of eight-byte elements. The first four (high-order) bytes of each element are reserved. The second four (low-order) bytes of each element contain the address of a buffer.

There may be from 1 to 16 buffers passed in the list. Each buffer in the list must be the same size and must reside in the same address space or data space. Data is fetched from or stored into the buffers in the order specified.

One of BUFFER or BUFLIST is required for all READ_LIST, READ_MULT, MOVE_ENTRYLIST, and DELETE_ENTRYLIST requests. See the description of the BUFFER keyword for the format of the data contained in the buffers.

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 1 to 16.

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

,DIRECTION=HEADTOTAIL

,DIRECTION=TAILTOHEAD

Use this input parameter to specify the direction of processing for traversing the given list.

HEADTOTAIL: Processing should begin at the designated entry and proceed toward the tail of the list.
TAILTOHEAD: Processing should begin at the designated entry and proceed toward the head of the list.

,ENTRYID=entryid

Use this input parameter to specify the list entry identifier of the entry to be used as the starting point of the READ_LIST or DELETE_LIST request.

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=entrykey

Use this input parameter to either:

Specify the entry key to be used to compare to the entry key of the list entry to determine if the list entry should be processed. For MOVE_ENTRYLIST and DELETE_ENTRYLIST requests, if the condition specified by KEYREQTYPE is not met for the current list entry, then no processing is performed for the current entry and processing either continues with the next entry to be considered or is terminated based on the value specified for MISCOMPARE. For all other IXLLSTM requests, if the condition specified by KEYREQTYPE is not met for the current list entry, then no processing is performed for the current entry and processing continues with the next entry to be considered.
For READ_LIST and DELETE_LIST requests, specify the entry key to be used to partially indicate the starting list entry for the request. If DIRECTION=HEADTOTAIL was specified, the designated starting list entry is the head of the sublist. If DIRECTION=TAILTOHEAD was specified, the designated starting list entry is the tail of the sublist.

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 specify the list entry name of the entry to be used as the starting point of the READ_LIST or DELETE_LIST request.

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.

,EXTRESTOKEN=NO_EXTRESTOKEN

,EXTRESTOKEN=extrestoken

Use this input parameter to specify a name for an extended restart token specifying an appropriate coupling facility indicator for resuming requests that complete prematurely.

An extended restart token is returned in the LAARESTOKEN answer area specified by ANSAREA when the request terminates prematurely. The extended restart token may be specified on a subsequent READ_MULT or DELETE_MULT request to resume the request at an appropriate point.

The RESTOKEN and EXTRESTOKEN keywords are mutually exclusive. Requestors who specify IXLCONN ALLOWAUTO = YES must use the 16–byte extended restart token (EXTRESTOKEN).

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

Note: Specifying an extended restart token of all zeros causes the request to consider all entries as unprocessed. Specifying an extended restart token other than one returned from a previous invocation of the request and not fully inititalized to all zeros will produce unpredictable request results.

,FIRSTELEM=1

,FIRSTELEM=firstelem

Use this input parameter to specify the index of the first array element to be processed for MOVE_ENTRYLIST and DELETE_ENTRYLIST requests.

The value must reference one of the array elements in the buffers specified by BUFLIST or the buffer specified by BUFFER.

An index value of 1 references the first array element in the BUFFER area or the first BUFLIST buffer.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a halfword field that contains the index of the first array element to be processed.

,KEYCOMPARE=NO

,KEYCOMPARE=YES

Use this input parameter to specify whether the key value of an existing keyed list entry is to be compared to determine if this entry should be selected for processing.

NO: Specify this option if no entry key comparison will be performed to determine if this entry should be processed.
YES: Specify this option if entry key comparison is to be performed based on the KEYREQTYPE specified to determine if this entry is selectable for processing.

Note:

KEYCOMPARE is only meaningful for list structures allocated on CFLEVEL=1 or higher.
KEYCOMPARE=YES is ignored if the target structure does not support keyed entries.

,KEYRANGEEND=keyrangeend

Use this input parameter to specify the ending value for the range of keys to be compared to the entry key of the designated list entry.

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

Note: KEYRANGEEND is a required keyword when KEYREQTYPE=RANGE is specified.

,KEYREQTYPE=EQUAL

,KEYREQTYPE=LESSOREQUAL

,KEYREQTYPE=GREATEROREQUAL

,KEYREQTYPE=RANGE

Use this input parameter to specify how an existing keyed list is located and how entry key comparison is to be performed to determine if the list entry is selectable for processing.

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.
RANGE: The entry must have a key within the specified range of values. The ENTRYKEY specified will be used as the beginning of the range of values. KEYRANGEEND will be used as the ending value. A list entry must have an entry key value within the specified entry key range, inclusive, for it to be selectable.

For a READ_LIST or DELETE_LIST request when LOCATOR=KEYPOS:

When no entries on the list meet the requirements of KEYREQTYPE, the request will be failed with a return code X'8' and reason code IXLRSNCODENOENTRY.
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 for the starting list entry. When multiple entries have the same entry key value, DIRECTION is used to resolve whether the first or last entry with the entry key value is selected for the starting list entry.
When LESSOREQUAL, GREATEROREQUAL or RANGE is specified, if multiple entries have an entry key value within the specified range, DIRECTION will be used to resolve whether the first or last entry within the entry key range is selected for the starting list entry.
When KEYREQTYPE=RANGE is specified, KEYRANGEEND=YES is required.

,KEYSCANTYPE=ENTRY

,KEYSCANTYPE=SECONDARY

Use this input parameter to specify which key ordering (entry key ordering or secondary key ordering) will be used to scan for entries on the list.

ENTRY: Entry key ordering will be used for scanning the list.
SECONDARY: Secondary key ordering will be used for scanning the list.

Note: KEYSCANTYPE=SECONDARY is only valid when the structure is allocated in a coupling facility with CFLEVEL=9 or higher.

,KEYTYPE=ENTRY

,KEYTYPE=SECONDARY

Use this input parameter to specify whether to locate the starting list entry using the entry key or the secondary key.

ENTRY: The entry key will be used to locate the starting list entry.
SECONDARY: The secondary key will be used to locate the starting list entry.

Note: KEYTYPE=SECONDARY is only valid when the structure is allocated in a coupling facility with CFLEVEL=9 or higher.

,LASTELEM=lastelem

Use this input parameter to specify the index of the last array element to be processed for MOVE_ENTRYLIST or DELETE_ENTRYLIST requests.

The specified value must be greater than or equal to the specified FIRSTELEM value, and must specify one of the array elements passed in the BUFFER area or the BUFLIST buffers.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a halfword field that contains the index of the last array element to be processed.

,LISTCOMPARE=NO

,LISTCOMPARE=YES

Use this input parameter to specify whether the list number comparison should be used to determine if list entries should be processed.

LISTCOMPARE=NO: List number comparison should not precede processing of list entries.
LISTCOMPARE=YES: List number comparison should precede processing of list entries.

,LISTKEYAREA=NO

,LISTKEYAREA=listkeyarea

Use this input parameter to specify the address of a virtual storage area in which entry key values will be places when the current list key value has been assigned to list entries.

List key information will be placed in the LISTKEYAREA when the current list key value has been assigned to the list entry and any of the following conditions exists:

The request completes successfully.
The model-dependent timeout has been exceeded.
A list entry does not exist.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 112-area field that contains an array of entry keys.

,LISTKEYINC=NO

,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 result of adding the value specified by LISTKEYINC to the target list key value is greater than the maximum list key value, the system fails the request.

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.

,LISTNUM=NO_LISTNUM

,LISTNUM=listnum

Use this input parameter to specify:

The number of the list on which the starting list entry resides.
The number of the list to be compared to the number of the list on which the entries to be processed reside.

If the list comparison fails, then the IXLLSTM operation is terminated and the list entry controls along with the appropriate return and reason codes are provided.

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

,LISTTYPE=NAMELIST

,LISTTYPE=IDLIST

Use this input parameter to specify whether the first field in each array element in the BUFFER area or BUFLIST buffers for MOVE_ENTRYLIST or DELETE_ENTRYLIST requests contains an entry name or an EntryID.

LISTYPE=NAMELIST: The first field in each array element in the BUFFER area or BUFLIST buffers contains the entry name of the list entry.
LISTYPE=IDLIST: The first field in each array element in the BUFFER area or BUFLIST buffers contains the EntryID of the list entry. The EntryID may be either system generated or user provided.

Note: LISTTYPE=NAMELIST is not allowed for structures that do not support named entries.

,LOCATOR=CURSOR

,LOCATOR=ENTRYID

,LOCATOR=ENTRYNAME

,LOCATOR=UNKEYPOS

,LOCATOR=KEYPOS

Use this input parameter to specify how to locate the first list entry for READ_LIST or DELETE_LIST requests to be processed.

CURSOR: The list cursor is to be used to designate the starting list entry for the request.
ENTRYID: The EntryID should be used to designate the starting list entry for the request. EntryIDs may be either assigned or provided by the user. User provided EntryIDs must be specified if ENTRYTYPE=USER is specified on the IXLCONN request.
ENTRYNAME: The entry name should be used to designate the starting list entry for the request. ENTRYNAME may only be specified for structures that support named entries.
UNKEYPOS: LISTNUM and DIRECTION will be used to designate the starting entry for the request.
KEYPOS: LISTNUM, DIRECTION and the key specified by KEYTYPE will be used to designate the starting entry for the request.

,LOCKCOMP=NO_LOCKCOMP

,LOCKCOMP=lockcomp

Use this input parameter to specify a connection identifier to be verified as the current lock owner as a prerequisite to successful completion of this request.

When LOCKCOMP is specified the locking operation is always considered to be a conditional operation. That is, if the request experiences lock contention the request will be ended with no resultant change to the structure, and appropriate return and reason codes are provided in the ANSAREA. The connection identifier is available from the IXLCONN answer area.

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.

,LOCKINDEX=NO_LOCKINDEX

,LOCKCOMP=lockindex

Use this input parameter to specify the index of the lock to be operated on within the lock table for the list structure.

When specified, the designated lock will be operated on as specified by the LOCKOPER keyword. The specified value must fall within the range 0 to the number of lock table entries minus one, inclusive.

LOCKINDEX is mutually exclusive with MODE=ASYNCNORESPONSE.

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

,LOCKOPER=NOTHELD

,LOCKOPER=HELDBY

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

NOTHELD: The state of the lock must be such that the lock is not held for the duration of the requested list entry operation. The lock state remains unchanged as a result of this option.
When NOTHELD is specified, the locking operation is always considered to be a conditional operation. That is, if the specified lock is held then the entire IXLLSTM operation will be ended with no resultant change to the structure, and appropriate return and reason codes are provided in the ANSAREA.
HELDBY: When LOCKCOMP is not specified, the list operation is to be performed only if the lock is currently held by the connection specified by CONTOKEN.
When LOCKCOMP is specified, the list operation is to be performed only if the lock is currently 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.

,MISCOMPARE=CONTINUE

,MISCOMPARE=HALT

For MOVE_ENTRYLIST and DELETE_ENTRYLIST requests, use this input parameter to specify whether processing should continue to the next entry or halt when any of the version number, list number or key comparisons are not successful.

CONTINUE: Processing should continue to the next entry if any of the version number, list number or key comparisons, when specified, are not successful.
HALT: If a version number, list number or key comparison is specified but is not successful, processing for the command is stopped. List entry controls and the appropriate return and reason codes will be returned in the ANSAREA.

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

SYNCSUSPEND: The request will be performed synchronously. Control is not returned to the caller until request processing is complete and the final disposition determined.
If necessary the caller will be suspended until the request completes. To use this option, your program must be enabled for I/O and external interrupts.
SYNCECB: The request will be attempted synchronously. If the request cannot be completed synchronously, control is returned to the caller prior to the completion of the request, and the ECB specified by REQECB is posted when the request has completed.
When MODE=SYNECB is specified and the request does not complete synchronously, latent XES binds to the storage locations specified by BUFFER, BUFLIST, LISTKEYAREA, ADJAREA, and ANSAREA persist until the REQECB ECB is posted.
SYNCEXIT: The request will be attempted synchronously. If the request cannot be completed synchronously, control is returned to the caller prior to completion of the request. When the request completes, the connection's Complete exit will be called.
When the request does not complete synchronously, latent XES binds to the storage locations specified by BUFFER, BUFLIST, ADJAREA, LISTKEYAREA, and ANSAREA persist until the connection's Complete exit is called.
SYNCTOKEN: The request will be attempted synchronously. If the request cannot be completed synchronously, control is returned to the caller prior to completion of the request and a token that uniquely identifies the request is returned.
When the request does not complete synchronously, latent XES binds to the storage locations specified by BUFFER, BUFLIST, ADJAREA, LISTKEYAREA, and ANSAREA persist until a subsequent corresponding IXLFCOMP request indicates completion of the original request.
ASYNCECB: The request is to be initiated and control is to be returned to the caller prior to completion of the request. When the request completes, the ECB specified by REQECB will be posted.
The latent XES binds to the storage locations specified by BUFFER, BUFLIST, LISTKEYAREA, ADJAREA, and ANSAREA persist until the REQECB ECB is posted.
ASYNCEXIT: The request is to be initiated and control is to be returned to the caller prior to completion of the request. When the request completes, the connection's Complete exit will be called.
The latent XES binds to the storage locations specified by BUFFER, BUFLIST, LISTKEYAREA, ADJAREA, and ANSAREA persist until the connection's Complete exit is called.
ASYNCTOKEN: The request is to be initiated, a token generated that uniquely identifies the request on this system, and control returned to the caller prior to completion of the requested operation.
The latent XES binds to the storage locations specified by BUFFER, BUFLIST, LISTKEYAREA, ADJAREA, and ANSAREA persist until a subsequent corresponding IXLFCOMP request indicates completion of the original request.
ASYNCNORESPONSE: The request is to be initiated and control returned to the caller prior to completion of the requested operation. No asynchronous request token is returned; hence no external mechanism exists to force completion of the request.
MODE=ASYNCNORESPONSE is mutually exclusive with LOCKINDEX, BUFFER, and BUFLIST. Any request that does not perform a locking operation and does not use a BUFFER area or BUFLIST buffers may specify MODE=ASYNCNORESPONSE.

,MOVETOKEY=UNCHANGED

,MOVETOKEY=TARGETKEY

,MOVETOKEY=LISTKEY

Use this input parameter to specify on a MOVE_ENTRYLIST request how the key is to be assigned to the list entry when it is moved to the MOVETOLIST. MOVETOKEY may only be specified for structures that support keyed entries.

UNCHANGED: The current entry key value assigned to the list entry will remain unchanged.
TARGETKEY: The TARGET_KEY provided in the array element in the BUFFER or the BUFLIST buffer will be assigned to the list entry when it is moved to the target list.
LISTKEY: The current list key value will be assigned to the list entry when it is moved to the target list.

,MOVETOSKEY=UNCHANGED

,MOVETOSKEY=TARGETKEY

Use this input parameter on MOVE_ENTRYLIST requests to specify how the secondary key is to be assigned to the list entry when it is moved to the MOVELIST.

UNCHANGED: The current secondary key entry value assigned to the list entry will remain unchanged.
TARGETKEY: The TARGET_SKEY provided in the array element in the BUFFER or the BUFLIST buffers will be assigned to the list entry when it is moved to the target list.

Note: MOVETOSKEY can only be specified for structures that support secondary keyed entries.

,PAGEABLE=YES

,PAGEABLE=NO

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

YES

Specify this option to indicate that the BUFFER or BUFLIST buffers reside in pageable virtual storage.

This includes 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.) It does not include implicitly non-pageable storage (such as is obtained from non-pageable subpools).

The system takes responsibility for managing binds to central storage for the duration of the 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.

NO

Specify this option to indicate that the BUFFER or BUFLIST buffers reside in non-pageable virtual storage.

This includes implicitly non-pageable storage areas. If the virtual storage may potentially become pageable, the invoker is responsible for ensuring the virtual storage remains non-pageable for the duration of the 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 list request.)

If MODE=ASYNCTOKEN is specified or MODE=SYNCTOKEN is specified and the request does not complete synchronously, the storage must remain non-pageable until completion of the corresponding IXLFCOMP request. If MODE=ASYNCEXIT is specified or MODE=SYNCEXIT is specified and the request does not complete synchronously, the storage must remain non-pageable until the complete exit is driven for the request. If MODE=ASYNCECB is specified or MODE=SYNCECB is specified and the request does not complete synchronously, the storage must remain non-pageable until the specified ECB is posted for the request.

The system takes responsibility for managing binds to central storage for the duration of the 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 a list 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.

,REQUEST=READ_LIST

,REQUEST=DELETE_LIST

,REQUEST=READ_MULT

,REQUEST=DELETE_MULT

,REQUEST=MOVE_ENTRYLIST

,REQUEST=DELETE_ENTRYLIST

Use this input parameter to specify the type of operation to be performed on the structure.

READ_LIST: Use READ_LIST to request that a list scan process be performed such that entries meeting a specified set of criteria will be read. The entry data, adjunct data, list entry controls, or any combination of these for the selected entries on the list might be read into the buffer storage area specified for the request (designated by BUFFER or BUFLIST).
DELETE_LIST: Use DELETE_LIST to request that a list scan process be performed such that entries meeting a specified set of criteria will be removed from the list on which they reside and returned to the pool of free entries for reuse.
READ_MULT: Use READ_MULT to request that the entry data, the associated adjunct data, or the list entry controls for all allocated entries that meet the criteria specified be read into the storage area specified by BUFFER or the buffers specified by BUFLIST.
DELETE_MULT: Use DELETE_MULT to request that all entries that meet the specified criteria be removed from whatever list they reside on and returned to the pool of free entries for reuse.
MOVE_ENTRYLIST: Use MOVE_ENTRYLIST to request that all specified entries be moved from the current source location to a designated target location. The entries to be moved are found in the list of formatted elements in the storage area specified by BUFFER or the buffers specified by BUFLIST.
DELETE_ENTRYLIST: DELETE_ENTRYLIST is used to request that all specified entries be removed from whichever list they reside on and returned to the pool of free entries for reuse. The entries to be deleted are found in the list of formatted elements in the storage area specified by BUFFER or the buffers specified by BUFLIST.

,RESTOKEN=NO_RESTOKEN

,RESTOKEN=restoken

Use this input parameter to specify a name for a restart token specifying an appropriate coupling facility indicator for resuming requests the complete prematurely.

A restart token is returned in the LAARESTOKEN answer area specified by ANSAREA when the request terminates prematurely. The restart token may be specified on a subsequent READ_MULT or DELETE_MULT request to resume the request at an appropriate point.

The RESTOKEN and EXTRESTOKEN keywords are mutually exclusive. Requestors who specify IXLCONN ALLOWAUTO = YES must use the 16–byte extended restart token (EXTRESTOKEN).

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

Note: Specifying a restart token of all zeros causes the request to consider all entries as unprocessed. Specifying a restart token other than one returned from a previous invocation of the request and not fully inititalized to all zeros will produce unpredictable request results.

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

,SECONDARYKEY=xsecondarykey

Use this input parameter to either:

Specify the secondary key value to be compared to the secondary key of the list entry to determine if the list entry should be processed. For MOVE_ENTRYLIST and DELETE_ENTRYLIST requests, if the condition specified by SKEYREQTYPE is not met for the current list entry, then no processing is performed for the current entry and processing either continues with the next entry to be considered or is terminated based on the value specified for MISCOMPARE. For all other request types, if the condition specified by SKEYREQTYPE is not met for the current list entry, then no processing is performed for the current entry and processing continues with the next entry to be considered.
Specify the secondary key to be used to partially indicate the starting list entry for the request for READ_LIST and DELETE_LIST requests. If DIRECTION=HEADTOTAIL was specified, the designated starting list entry is the head of the sublist. If DIRECTION=TAILTOHEAD was specified, the designated starting list enty is the tail of the sublist.

For a READ_LIST or DELETE_LIST request when LOCATOR=KEYPOS:

When no entries on the list meet the requirements of SKEYREQTYPE, the request will be failed with a return code X'8' and reason code IXLRSNCODENOENTRY.
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 for the starting list entry. When multiple entries have the same entry key value, DIRECTION is used to resolve whether the first or last entry with the entry key value is selected for the starting list entry.
When LESSOREQUAL, GREATEROREQUAL or RANGE is specified, if multiple entries have an entry key value within the specified range, DIRECTION will be used to resolve whether the first or last entry within the entry key range is selected for the starting list entry.
When KEYREQTYPE=RANGE is specified, KEYRANGEEND=YES is required.

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

Note: SECONDARYKEY is required if SKEYCOMPARE=YES.

,SKEYCOMPARE=NO

,SKEYCOMPARE=YES

Use this input parameter to specify whether the secondary key value of an existing keyed list entry should be compared to the SKEYREQTYPE to determine if this entry should be selected for processing.

NO: Specify this value if no secondary key comparison will be performed to determine if this entry should be processed.
YES: Specify this option if secondary key comparison is to be performed based on the SKEYREQTYPE to determine if this entry is to be selected for processing.

Note: SKEYCOMPARE=YES is ignored if the target structure was not allocated with secondary keys.

,SKEYRANGEEND=skeyrangeend

Use this input parameter to specify the ending value for the range of keys to be compared to the secondary key of the designated list entry.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the 32 character field that contains the secondary key range ending value.

Note: SKEYRANGEEND must be specified when SKEYREQTYPE=RANGE.

,SKEYREQTYPE=EQUAL

,SKEYREQTYPE=LESSOREQUAL

,SKEYREQTYPE=GREATEROREQUAL

,SKEYREQTYPE=RANGE

Use this input parameter to specify how an existing keyed list entry is located and how key comparison is to be performed to determine if the list entry is selectable for processing.

EQUAL: The entry must have a key that equals the SECONDARYKEY key.
LESSOREQUAL: The entry must have a key that is less than or equal to the SECONDARYKEY key.
GREATEROREQUAL: The entry must have a key that is greater than or equal to the SECONDARYKEY key.
RANGE: The entry must have a key within the specified range of values. The SECONDARYKEY specified will be used as the beginning of the range of values. SKEYRANGEEND will be used as the ending value. A list entry must have an secondary key value within the specified entry key range, inclusive, for it to be selectable.

Note:

When no entries on the list meet the requirements of the SKEYREQTYPE, and a new entry cannot be created, the request will be failed, and the appropriate return and reason codes are provided to the invoker.
When LESSOREQUAL or GREATEROREQUAL are specified, if no entries on the list have a secondary key value equal to the specified value, but entries exist with a secondary key value greater than (if GREATEROREQUAL was specified), or less than (if LESSOREQUAL was specified) the entry key value specified, then the entry with a secondary key value closest to the value specified will be selected. When multiple entries have the same secondary key value, LISTPOS is used to resolve whether the first or last entry with the secondary key value is selected.
When LESSOREQUAL, GREATEROREQUAL or RANGE is specified, if multiple entries have a secondary key value within the specified range, DIRECTION will be used to resolve whether the first or last entry within the secondary key range is selected.
When SKEYREQTYPE=RANGE is specified, KEYRANGEEND=YES is required.

,TYPE=ENTDATA

,TYPE=ADJDATA

,TYPE=ECONTROLS

Use this group of required input(s) to specify the type of information to be read. Any combination of ENTDATA, ADJDATA and ECONTROLS may be specified.

ENTDATA: Use ENTDATA to indicate that entry data is to be read.
ADJDATA: Use ADJDATA to indicate that adjunct data is to be read.
ECONTROLS: Use ECONTROLS to indicate that list entry control information is to be read.

Note:

ADJDATA is only functional for structures that support adjunct data.
For structures that are allocated with secondary keys, the first 32 bytes of the adjunct data will contain the secondary key information.
For structures allocated with secondary keys, the secondary key is not read by TYPE=ECONTROLS. The secondary key is read by TYPE=ADJDATA.

,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 processed only if its version number meets the condition specified by the VERSCOMPTYPE parameter. If the condition specified by VERSCOMPTYPE is not met for the current list entry, then no processing is performed for the current list entry and processing continues with the next entry to be considered.

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.

,VERSCOMPARE=NO

,VERSCOMPARE=YES

Use this input parameter to specify if the version number is to be compared to the version number of the existing entry.

VERSCOMPARE=NO: No version comparison should be performed to determine if each list entry should be processed.
VERSCOMPARE=YES: Version number comparison should precede processing of each list entry.

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