• For REQUEST=MONITOR_EVENTQ, whether event queue monitoring is to be started or stopped. Requires that the list structure be allocated in a coupling facility of CFLEVEL=3 or higher.
• For REQUEST=MONITOR_LIST, whether list monitoring is to be started or stopped.
• For REQUEST=MONITOR_KEYRANGE, whether key-range monitoring is to be started or stopped. Requires that the list structure be allocated in a coupling facility of CFLEVEL=9 or higher.
• For REQUEST=MONITOR_SUBLIST, whether sublist monitoring is to be started or stopped. Requires that the list structure be allocated in a coupling facility of CFLEVEL=3 or higher.

START

• For REQUEST=MONITOR_EVENTQ, start event queue monitoring for the connection specified by CONTOKEN for the specified event queue.
• For REQUEST=MONITOR_LIST, start monitoring for the connection specified by CONTOKEN for the list specified by LISTNUM.
• For REQUEST=MONITOR_KEYRANGE, start key-range monitoring for the connection specified by CONTOKEN for the list specified by LISTNUM.
• For REQUEST=MONITOR_SUBLIST, start sublist monitoring for the connection specified by CONTOKEN for the designated sublist.

STOP

• For REQUEST=MONITOR_EVENTQ, stop monitoring the event queue for the connection specified by CONTOKEN.
• For REQUEST=MONITOR_LIST, stop list monitoring for the connection specified by CONTOKEN for the list specified by LISTNUM.
• For REQUEST=MONITOR_KEYRANGE, stop key-range monitoring for the connection specified by CONTOKEN for the list specified by LISTNUM.
• For REQUEST=MONITOR_SUBLIST, stop monitoring of the designated sublist for the connection specified by CONTOKEN.

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

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.

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

31

The entry in BUFLIST is 31 bits in size.

64

The entry in BUFLIST is 64 bits in size.

VIRTUAL

The buffer addresses are virtual storage addresses. The virtual storage can be pageable or nonpageable. See the PAGEABLE parameter for information about managing storage binds when specifying virtual storage addresses.

REAL

The buffer addresses are real storage addresses.

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.

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.

• For READ_LCONTROLS requests, the buffer must be 4096 bytes on a 4096-byte boundary.

  Upon successful completion of a READ_LCONTROLS request, the BUFFER area contains, starting at offset zero, an array of list monitoring information for the specified list and an array of key-range monitoring information for the specified list. The relative position of an array element associates it with a connection identifier. The first array element is associated with a connection identifier of zero, and is reserved. The length and contents of each array element is defined by mapping macro IXLYLMI.

• For DEQ_EVENTQ requests, the buffer must be 4096 bytes on a 4096-byte boundary.

  Upon successful completion of a DEQ_EVENTQ request, the BUFFER area contains, starting at offset zero, an array of event monitor controls that were dequeued from the event queue. The length and contents of each array element is defined by mapping macro IXLYEMC.

• For MONITOR_SUBLISTS requests, the BUFSIZE keyword specifies the size of the buffer. 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.

  For a MONITOR_SUBLISTS request, the BUFFER is used to input an array of entries, each mapped by IXLYMSRI, and each of which contains the information necessary to register as a sublist monitor for one sublist.

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.

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.

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

The buffer address description is an 8-byte element. The first four bytes of the element is reserved space. The second four bytes of the element contains the address of the buffer.

• For READ_LCONTROLS requests, only one buffer may be passed. The buffer must be 4096 bytes in length and must start on a 4096-byte boundary.

  Upon successful completion of a READ_LCONTROLS request, the BUFLIST buffer contains, starting at offset zero, an array of list monitoring information for the specified list and an array of key-range monitoring information for the specified list. The relative position of an array element associates it with a connection identifier. The first array element is associated with a connection identifier of zero, and is reserved. The length and contents of each array element is defined by mapping macro IXLYLMI.

• For DEQ_EVENTQ requests, only one buffer may be passed. The buffer must be 4096 bytes in length on a 4096-byte boundary.

  Upon successful completion of a DEQ_EVENTQ request, the BUFLIST buffer contains, starting at offset zero, an array of event monitor controls that were dequeued from the event queue. The length and contents of each array element is defined by mapping macro IXLYEMC.

• For MONITOR_SUBLISTS requests, there may be 1 to 16 buffers 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 the buffers in the order specified.

  For MONITOR_SUBLISTS requests, the length of a buffer must be a multiple of 256 bytes between 256 and 4096. Each buffer must start on a 256-byte boundary and must not cross a 4096-byte boundary.

  For a MONITOR_SUBLISTS request, the BUFLIST is used to input an array of entries, each mapped by IXLYMSRI, and each of which contains the information necessary to register as a sublist monitor for one sublist.

  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.

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.

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.

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

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

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an 8-bit field that contains the storage key in the format B'kkkkxxxx', where kkkk is the key and xxxx is ignored.

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

• For REQUEST=MONITOR_EVENTQ, whether XES should drive the connection's list transition exit when the state of the specified user's event queue changes from empty to not-empty.
• For REQUEST=MONITOR_LIST, whether XES should drive the connection's list transition exit when the state of a list changes from empty to not-empty.
• For REQUEST=MONITOR_KEYRANGE, whether XES should drive the connection's list transition exit when the state of the key-range changes from empty to not-empty.

YES

• For REQUEST=MONITOR_EVENTQ, when the state of the user's event queue changes from empty to not-empty, XES will drive the connection's list transition exit.
• For REQUEST=MONITOR_LIST, when the state of a list changes from empty to not-empty, XES will drive the connection's list transition exit.
• For REQUEST=MONITOR_KEYRANGE, when the state of a key-range changes from empty to not-empty, XES will drive the connection's list transition exit.

NO

• For REQUEST=MONITOR_EVENTQ, when the state of the user's event queue changes from empty to not-empty, XES will not drive the connection's list transition exit.
• For REQUEST=MONITOR_LIST, when the state of a list changes from empty to not-empty, XES will not drive the connection's list transition exit.
• For REQUEST=MONITOR_KEYRANGE, when the state of the key-range changes from empty to not-empty, XES will not drive the connection's list transition exit.

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

• For REQUEST=READ_EMCONTROLS, a sublist whose EMCs are to be read.
• For REQUEST=MONITOR_SUBLIST, a sublist whose monitoring is to be started or stopped.

Specify ENTRYKEY only for structures that support keyed entries. The use of ENTRYKEY requires that the list structure be allocated in a coupling facility of CFLEVEL=3 or higher.

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

NO_CHANGE

The key-range currently defined for the list will remain unchanged.

SET

The key-range defined for the list is to be set to the range specified by KEYRANGESTART and KEYRANGEEND.

SET is valid for keyed list structures allocated in a coupling facility of CFLEVEL=9 or higher. SET is ignored and the request processed as if NO_CHANGE were specified when the structure is allocated in a coupling facility of CFLEVEL=8 or lower, or if the structure does not support keyed list entries.

The default key-range start and end key values are initialized to binary zeros for all lists when the structure is allocated.

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-range end key value.

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-range start key value.

NO_CHANGE

The threshold counts will remain unchanged.

DEFINE

The threshold counts that define the empty or not-empty state of a key-range are to be set to the values indicated by KREMPTY and KRNOTEMPTY.

DEFINE is valid for keyed list structures allocated in a coupling facility of CFLEVEL=9 or higher. DEFINE is ignored and the request processed as if NO_CHANGE were specified when the structure is allocated in a coupling facility of CFLEVEL=8 or lower, or if the structure does not support keyed list entries.

A key-range is either in the empty state or the not-empty state. Use a REQUEST=MONITOR_KEYRANGE request to register interest in monitoring transitions between key-range states.

The default key-range empty or not-empty threshold counts are initialized to zero for all lists when the structure is allocated.

A request to define the key-range empty or not-empty threshold counts can timeout. The caller is expected to reissue the request until it completes without timing out.

• For REQUEST=READ_EQCONTROLS, whether to return information about the event queue for state transitions of sublists identified by list entry key or to return information about the event queue for state transitions of sublists identified by secondary key.
• For REQUEST=DEQ_EVENTQ, whether to dequeue EMCs for state transitions of sublists identified by list entry key or to dequeue EMCs for state transitions of sublists identified by secondary key.
• For REQUEST=MONITOR_EVENTQ, whether to monitor the event queue for state transitions of sublists identified by list entry key or to monitor the event queue for state transitions of sublists identified by secondary key.

ENTRY

• For REQUEST=READ_EQCONTROLS, return information about the event queue for state transitions of sublists identified by list entry key.
• For REQUEST=DEQ_EVENTQ, dequeue the EMCs for state transitions of sublists identified by list entry.
• For REQUEST=MONITOR_EVENTQ, monitor the event queue for state transitions of sublists identified by list entry key.

KEYTYPE=ENTRY is valid only when the structure is allocated in a coupling facility of CFLEVEL=3 or higher.

SECONDARY

• For REQUEST=READ_EQCONTROLS, return information about the event queue for state transitions of sublists identified by secondary key.
• For REQUEST=DEQ_EVENTQ, dequeue the EMCs for state transitions of sublists identified by secondary key.
• For REQUEST=MONITOR_EVENTQ, monitor the event queue for state transitions of sublists identified by secondary key.

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

A key-range is in the empty state if the number of list entries in the key-range is either less than or equal to the KREMPTY threshold or zero. Upon completion of the key-range state definition, the key-range is also considered to be in the empty state if the number of list entries in the key-range is less than or equal to the KRNOTEMPTY threshold. Once the key-range state becomes empty, it remains empty until the number of list entries in the key-range becomes greater than the KRNOTEMPTY threshold.

The KREMPTY keyword is valid only for a keyed list structure allocated in a coupling facility of CFLEVEL=9 or higher.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword field that contains the key-range empty threshold count to be associated with the list.

A key-range is in the not-empty state if the number of list entries in the key-range is greater than the KRNOTEMPTY threshold. Once the key-range state is not-empty, it remains not-empty until the number of list entries in the key-range either becomes less than or equal to the KREMPTY threshold or becomes zero.

The KRNOTEMPTY keyword is valid only for a keyed list structure allocated in a coupling facility of CFLEVEL=9 or higher.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword field that contains the key-range not-empty threshold to be associated with the list.

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

A list is in the empty state if the number of list entries on the list is either zero or less than or equal to the LISTEMPTY threshold.

The LISTEMPTY keyword is valid only for a list structure allocated in a coupling facility of CFLEVEL=9 or higher.

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

If LISTKEY is not specified, the list key for the designated list will remain unchanged. LISTKEY is ignored when the structure does not support keyed entries.

The LISTKEY keyword is only meaningful for list structures allocated in a coupling facility of CFLEVEL=1 or higher.

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

When an IXLALTER is processed for a list structure, if the list limit for a list is equal to the default value then it will be automatically adjusted to the new number of entries or elements. If a list limit is not equal to the default value then the alter process will not adjust it and it is the responsibility of the user, if desired, to set a new limit taking into account the current entry and element counts for the altered structure.

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

A list is in the not-empty state if the number of list entries on the list is greater than the LISTNOTEMPTY threshold.

The LISTNOTEMPTY keyword is valid only for a list structure allocated in a coupling facility of CFLEVEL=9 or higher.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword field that contains the list not-empty threshold count.

• For REQUEST=READ_LCONTROLS, the number of the list to be processed.
• For REQUEST=WRITE_LCONTROLS, the number of the list to be processed.
• For REQUEST=READ_EMCONTROLS, the partial designation of the sublist to be processed.

  LISTNUM is used in conjunction with either ENTRYKEY or SECONDARYKEY to designate a sublist for which the user's event monitor controls are to be read.

• For REQUEST=MONITOR_LIST, the number of the list to be monitored.
• For REQUEST=MONITOR_KEYRANGE, the number of the list whose key-range is to be monitored.
• For REQUEST=MONITOR_SUBLIST, the partial designation of the sublist to be processed.

  LISTNUM may be used in conjunction with ENTRYKEY or SECONDARYKEY to designate a sublist for which the user wishes to start or stop sublist monitoring.

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

NO_CHANGE

The threshold counts will remain unchanged.

DEFINE

The threshold counts are to be set to the values indicated by LISTEMPTY and LISTNOTEMPTY.

Upon completion of the definition of the list empty or not-empty thresholds, the list state may change. If the number of list entries is less than the new list empty thresholds, the list state is empty. If the number of list entries is greater than the new list not-empty threshold, the list state is not-empty. When the number of list entries is greater than or equal to the new list empty threshold and less than or equal to the new list not-empty threshold, the list state remains unchanged.

DEFINE is valid for coupling facilities of CFLEVEL=9 or higher. DEFINE is ignored and the request processed as if NO_CHANGE were specified when the structure is allocated in a coupling facility of CFLEVEL=8 or lower.

A list is either in the empty state or the not-empty state. Use a REQUEST=MONITOR_LIST request to register interest in monitoring transitions between list states.

The default list empty or not-empty threshold counts are initialized to zero for all lists when the structure is allocated. For structures allocated in a coupling facility of CFLEVEL=8 or lower, the list-empty and list-not-empty threshold counts are always zero.

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 of the LOCKOPER values 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.

• An IXLLSTC LOCK request specifying LOCKOPER=SET with LOCKMODE=UNCOND
• An IXLLSTE request specifying LOCKOPER=SET with LOCKMODE=UNCOND
• An IXLLSTM request specifying LOCKOPER=NOTHELD

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

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.

UNCOND

The lock operation will be performed unconditionally. If the specified lock is held, the IXLLSTC request will be held up until the operation can be processed.

• If MODE=SYNCSUSPEND is specified, the caller is suspended until the lock becomes available.
• If any MODE value other than SYNCSUSPEND is specified, the request is processed asynchronously and the caller is notified by the means indicated on the MODE keyword.

COND

The lock operation is performed conditionally. If the lock is held, the IXLLSTC request is terminated with no resultant change to the structure, and indicative return and reason codes are returned to the caller.

SET

• When LOCKCOMP is not specified, requests ownership of the lock for the connection specified by CONTOKEN.
• When LOCKCOMP is specified, requests that ownership of the lock be transferred from the connection specified by LOCKCOMP to the connection specified by CONTOKEN. Any outstanding requests awaiting contention resolution on this lock are ignored.

RESET

• When LOCKCOMP is not specified, requests that ownership of the lock be released if held by the connection specified by CONTOKEN.
• When LOCKCOMP is specified, requests that ownership of the lock be released if it is held by the connection specified by LOCKCOMP.

The RESET operation will always be done unconditionally when LOCKCOMP is not specified and conditionally when LOCKCOMP is specified.

TEST

• When LOCKCOMP is not specified, requests that the lock be tested to see if it is owned by the connection specified by CONTOKEN.
• When LOCKCOMP is specified, requests that the lock be tested to see if it is owned by the LOCKCOMP connection.

In both cases return code X'0' indicates that the lock was held and return code X'4' indicates that the lock is either not held or is held by a different connection.

The lock state remains unchanged as a result of this option.

READNEXT

• When LOCKCOMP is not specified, requests that the lock index and connection ID of the owner of the next owned lock starting at the lock index specified by LOCKINDEX be returned.
• When LOCKCOMP is specified, requests that the lock index of the next lock owned by the LOCKCOMP connection, starting at the lock index specified by LOCKINDEX, be returned.

The lock state remains unchanged as a result of this option.

A request specifying LOCKOPER=READNEXT may complete prematurely if coupling facility model-dependent timeout criteria is exceeded. In this event, indicative return and reason codes are provided, and the index of the next lock to be processed is returned in the answer area specified by ANSAREA. This lock index can be specified on a subsequent LOCKOPER=READNEXT request to resume processing with the appropriate lock entry.

If MAXLISTKEY is not specified, the maximum list key for the designated list will remain unchanged. MAXLISTKEY is ignored when the structure does not support keyed entries.

The MAXLISTKEY keyword is only meaningful for list structures allocated in a coupling facility of CFLEVEL=1 or higher.

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

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.

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. The caller must be executing in an enabled state to use this option.

SYNCECB

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 the ECB specified by REQECB is posted when the request has completed.

If the request does not complete synchronously, latent XES binds to the storage locations specified by BUFFER, BUFLIST, MOSVECTOR, 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.

If the request does not complete synchronously, latent XES binds to the storage locations specified by BUFFER, BUFLIST, MOSVECTOR, 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. This token must be specified on a subsequent invocation of IXLFCOMP to force completion of the request and determine its final disposition.

If the request does not complete synchronously, latent XES binds to the storage locations specified by BUFFER, BUFLIST, MOSVECTOR, and ANSAREA persist until a subsequent corresponding IXLFCOMP request indicates completion of the original request.

SYNCECB

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.

Latent XES binds to the storage locations specified by BUFFER, BUFLIST, MOSVECTOR, 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.

Latent XES binds to the storage locations specified by BUFFER, BUFLIST, MOSVECTOR, 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 token must be specified on a subsequent invocation of IXLFCOMP to force completion of the request and determine its final disposition.

Latent XES binds to the storage locations specified by BUFFER, BUFLIST, MOSVECTOR, 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 LOCK, READ_LCONTROLS, DEQ_EVENTQ, and MONITOR_SUBLISTS requests. It is also mutually exclusive with REQUEST=MONITOR_LIST and REQUEST=MONITOR_KEYRANGE when ACTION=START is specified. Any other request can specify MODE=ASYNCNORESPONSE.

The MOSVECTOR bits correspond one-to-one with the IXLYMSRI entries that were passed as input in the BUFFER or BUFLIST. Only the bits corresponding to the IXLYMSRI entries that were actually processed on the current request (that is, between STARTINDEX and ENDINDEX for a request that completed successfully, or between STARTINDEX and the returned index of the first unprocessed entry minus one for premature completion cases) will contain valid monitored object state information for the sublists designated by the corresponding IXLYMSRI entries. Bits in the MOSVECTOR that lie outside the valid range are not meaningful.

When a bit in the valid range is on, the sublist designated by the corresponding IXLYMSRI entry was not-empty at the time the request was processed. When a bit in the valid range is off, the sublist designated by the corresponding IXLYMSRI entry was empty at the time the request was processed.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 128-byte field that contains a 1-origin bit string in which each bit represents the monitored object state of a particular 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 list authority value.

FIRST

Queue the EMC to the registered user's event queue when the monitored sublist transitions from empty to not-empty.

EVERY

Queue the EMC to the registered user's event queue whenever a list entry is queued to the monitored sublist.

NOTIFICATION=EVERY is valid only when the structure is allocated in a coupling facility of CFLEVEL=9 or higher.

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.

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

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 4-byte field that contains the address of the ECB to be posted when the request completes. The ECB must be aligned on a fullword boundary.

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

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 16-byte field where the system will put the request token.

LOCK

The lock entry designated by LOCKINDEX is to be operated on as specified by the LOCKOPER keyword. This request type may only be specified for structures that contain a lock table.

REQUEST=LOCK is mutually exclusive with MODE=ASYNCNORESPONSE.

READ_LCONTROLS

Read the control information for the list specified by the LISTNUM keyword. The information returned in the answer area specified by ANSAREA consists of the list controls as mapped by the IXLYLAA macro. In addition, the list monitoring information and key-range monitoring information for the list, as mapped by the IXLYLMI macro, is returned in the storage specified by BUFFER or the buffers specified by BUFLIST.

REQUEST=READ_LCONTROLS is mutually exclusive with MODE=ASYNCNORESPONSE.

WRITE_LCONTROLS

Update one or more of the list controls for the list specified by LISTNUM. The list controls that can be updated include:

• List authority (NEWAUTH)
• List limit bounding the number of entries or elements that may reside on the list (LISTLIMIT)
• List descriptor (LISTDESC)
• List key (LISTKEY)
• Maximum list key (MAXLISTKEY)
• List cursor and list cursor direction (SETCURSOR)
• Key-range start and end values (KEYRANGESTART and KEYRANGEEND)
• Key-range empty and key-range not-empty threshold counts (KREMPTY and KRNOTEMPTY)
• List empty and list not-empty threshold counts (LISTEMPTY and LISTNOTEMPTY

READ_EQCONTROLS

Read event queue control information for the requesting user's event queue. Event queue processing is used in conjunction with sublist monitoring and requires that the list structure be allocated in a coupling facility of CFLEVEL=3 or higher. For list structures allocated in a coupling facility of CFLEVEL=9 or higher, a sublist can be identified either by entry key or by secondary key. Event monitor controls (EMCs) for sublists identified by entry key are queued to a different event queue than EMCs for sublists identified by secondary key. The different event queues can be monitored independently. The KEYTYPE keyword designates which event queue is the subject of the READ_EQCONTROLS request.

Information returned in the answer area specified by ANSAREA consists of the following:

• The total number of event monitor controls (EMCs) currently on the event queue
• The number of times that the event queue has transitioned from the empty to the non-empty state
• The vector index number that is being used to monitor the event queue
• An indication of whether or not the user's list transition exit is to be driven when the event queue transitions from the empty to the not-empty state
• An indication of whether the EMCs are for sublists identified by entry key or for sublists identified by secondary key.

READ_EMCONTROLS

Read the EMC control information for the requesting user's registered interest in monitoring a particular sublist designated by the LISTNUM keyword and either ENTRYKEY or SECONDARYKEY.

• For entry keys, this request type is valid only when the structure is allocated in a coupling facility of CFLEVEL=3 or higher. The structure must support keyed list entries (REFOPTION=KEY must be specified on the IXLCONN request when the structure is allocated).
• For secondary keys, this request type is valid only when the structure is allocated in a coupling facility of CFLEVEL=9 or higher. The structure must support secondary keys (KEYTYPE=SECONDARY must be specified on the IXLCONN request when the structure is allocated).

Information returned in the answer area specified by ANSAREA includes the following:

• The user notification controls (UNC)
• The list number and entry key or secondary key of the sublist with which the event monitor control information is associated
• An indication of whether or not the EMC is currently queued to the user's event queue
• An indication of whether the EMCs are for sublists identified by entry key or for sublists identified by secondary key
• An indication of whether the EMC is queued to the event queue for only the first list entry added to the sublist or for every list entry added to the sublist.

DEQ_EVENTQ

Dequeue the event monitor controls from an event queue. The sublist associated with the event queue can be identified either by list entry key or by secondary key. Identification by list entry key requires that the list structure be allocated in a coupling facility of CFLEVEL=3 or higher; identification by secondary key requires that the list structure be allocated in a coupling facility of CFLEVEL=9 or higher. If the structure is allocated with secondary keys, there are two event queues that can be monitored. The KEYTYPE keyword designates which event queue is the subject of the DEQ_EVENTQ request.

The contents of the dequeued EMCs are returned in the specified BUFFER or BUFLIST area. Each individual EMC is mapped by the IXLYEMC macro. Note that neither the EMCs nor the sublist monitoring interest which they represent is deleted by this request. Sublist monitoring remains active until it is stopped by a subsequent MONITOR_SUBLIST ACTION=STOP request.

This request type is valid only when the structure is allocated in a coupling facility of CFLEVEL=3 or higher (for entry keys) or CFLEVEL=9 or higher (for secondary keys).

The DEQ_EVENTQ request may complete prematurely, that is, without having dequeued all of the EMCs from an event queue. In such a case, the user is expected to process the EMCs that were returned on the current request and then re-issue the DEQ_EVENTQ request to continue the process of dequeueing the remaining EMCs from the event queue.

Information returned in the answer area specified by ANSAREA consists of the number of EMCs that were returned and the number of EMCs that still remain on the user's event queue.

REQUEST=DEQ_EVENTQ is mutually exclusive with MODE=ASYNCNORESPONSE.

MONITOR_EVENTQ

Start or stop list notification vector monitoring of an event queue for a requesting user.

This request type is valid only when the structure is allocated in a coupling facility of CFLEVEL=3 or higher. The user must have a local vector associated with the connection to the structure, and the structure must support keyed list entries. If the structure is allocated in a coupling facility of CFLEVEL=9 or higher and is allocated with secondary keys, there are two event queues that can be monitored. The KEYTYPE keyword designates which event queue is the subject of the MONITOR_EVENTQ request.

While event queue monitoring is in effect for an event queue, the IXLVECTR service can be used to determine whether the event queue contains any event monitor controls (EMCs). These EMCs represent not-empty sublists in which the user has registered sublist monitoring interest. (See IXLVECTR — Check or Modify Local Cache Vector or List Notification Vector.) Use event queue monitoring in conjunction with sublist monitoring (MONITOR_SUBLIST or MONITOR_SUBLISTS) to process state transitions for monitored sublists. Use the DEQ_EVENTQ request to dequeue queued EMCs from an event queue and to read the contents of the EMCs.

If a list notification vector index is in use for monitoring, a request to stop monitoring should be performed before using the same vector index to start another monitor. If event queue monitoring is in effect, a request to start monitoring the same event queue with a different VECTORINDEX or DRIVEEXIT specification will cause the old specifications to be immediately replaced by the new specifications. It is not necessary to stop event queue monitoring before requesting to start monitoring the same event queue using the new specifications. However, because the replaced vector index is no longer being used to monitor an event queue, it may be reassigned for other uses (for example, to monitor a list).

When event queue monitoring is stopped, the state of the vector index that was previously being used to monitor the event queue is not defined. However, because the vector index is no longer being used to monitor the event queue, it may be reassigned for other uses (for example, to monitor a list).

MONITOR_LIST

Start or stop monitoring the list specified by LISTNUM.

While list monitoring is in effect for a list, the IXLVECTR service can be used to determine whether the list is considered empty or not-empty according to the thresholds established with a WRITE_LCONTROLS request.

The IXLVECTR service can also be used to alter the size of the list notification vector, and thus changed the number of lists, key-ranges, or event queues that can be monitored concurrently. (See IXLVECTR — Check or Modify Local Cache Vector or List Notification Vector.)

If a list notification vector index is in use for monitoring, a request to stop monitoring should be performed before using the same vector index to start another monitor. If a vector index is in use for monitoring a list, a request to start list monitoring for the same list with a different vector index will cause the vector index in use for the list to be replaced by the new vector index. In this case, it is not necessary to stop monitoring using the old index before requesting to start monitoring using the new index.

REQUEST=MONITOR_LIST with ACTION=START is mutually exclusive with MODE=ASYNCNORESPONSE.

REQUEST=WRITE_LCONTROLS can be used to set the empty or not-empty threshold counts that are used to define the empty or not-empty state of a list for list monitoring.

MONITOR_KEYRANGE

Start or stop key-range monitoring of the list specified by LISTNUM. This request type is valid only for keyed list structures allocated in a coupling facility of CFLEVEL=9 or higher.

While key-range monitoring is in effect for a list, the IXLVECTR service can be used to determine whether the key-range is considered empty or not-empty according to the thresholds established with a WRITE_LCONTROLS request that specifies KEYRANGESTATE=DEFINE.

The IXLVECTR service can also be used to alter the size of the list notification vector, and thus change the number of lists, key-ranges, or event queues that can be monitored concurrently. (See IXLVECTR — Check or Modify Local Cache Vector or List Notification Vector.)

If a list notification vector index is in use for monitoring, a request to stop monitoring should be performed before using the same vector index to start another monitor. If a vector index is in use for monitoring a key-range, a request to start key-range monitoring of the same list with a different vector index will cause the vector index in use for the key-range to be replaced by the new vector index. In this case, it is not necessary to stop monitoring using the old index before equesting to start monitoring using the new index.

Only one key-range can be monitored per list. REQUEST=WRITE_LCONTROLS can be used to set the starting and ending key-range values, and the empty or not-empty threshold counts that define the empty or not-empty state of a key-range for key-range monitoring.

REQUEST=MONITOR_KEYRANGE with ACTION=START is mutually exclusive with MODE=ASYNCNORESPONSE.

A request to start monitoring a key-range for a list can timeout if definition of the key-range is not complete (see REQUEST=WRITE_LCONTROLS with KEYRANGESTATE=DEFINE). The caller is expected to reissue the request until it completes without timing out.

MONITOR_SUBLIST

Start or stop monitoring a sublist designated by a list number and either an entry key or secondary key within the list structure.

A request to monitor a keyed sublist is valid only when the structure is allocated in a coupling facility of CFLEVEL=3 or higher. The user must have a local vector associated with the connection to the structure, and the structure must support keyed list entries (REFOPTION=KEY must be specified on IXLCONN when the structure is allocated).

A request to monitor a secondary keyed sublist is valid only when the structure is allocated in a coupling facility of CFLEVEL=9 or higher. The user must have a local vector associated with the connection to the structure, and the structure must support secondary keys (KEYTYPE=SECONDARY must be specified on IXLCONN when the structure is allocated).

MONITOR_SUBLISTS

Start monitoring a set of sublists designated by list number and either entry key or secondary key in a list structure. MONITOR_SUBLISTS cannot be used to stop sublist monitoring.

A request to monitor a sublist identified by a list entry key is valid only when the structure is allocated in a coupling facility of CFLEVEL=3 or higher. A request to monitor a sublist identified by a secondary key is valid only when the structure is allocated in a coupling facility of CFLEVEL=9 or higher and the structure supports secondary keys. In both cases, the user must have a local vector associated with the connection to the structure, and the structure must support keyed list entries.

REQUEST=MONITOR_SUBLISTS is mutually exclusive with MODE=ASYNCNORESPONSE.

READ_STRCOUNTS

Request the information on the maximum and in-use counts be returned.

Information returned in the answer area specified by ANSAREA mapped by LAARSTC in the IXLYLAA consists of the following:

• The current in-use number of elements and maximum number of elements defined for the structure if data elements are defined for the structure.
• The current in-use number of entries and the maximum number of entries defined for the structure.
• The current in-use number of event monitor controls and the total number of event monitor controls defined for the structure if event monitor controls are supported by the structure.
• The number of lock entries defined for the structure if the structure is defined as a serialized list structure.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 4-byte field that will contain the return code when the request has completed.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 4-byte field that will contain the reason code (if any) when the request has completed.

• For REQUEST=READ_EMCONTROLS, a sublist whose EMCs are to be read.
• For REQUEST=MONITOR_SUBLIST, a sublist whose monitoring is to be started or stopped.

SECONDARYKEY is valid only for structures that are allocated in a coupling facility of CFLEVEL=9 or higher. The structure must support secondary keys.

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

The list cursor direction is only used when an IXLLSTE invocation specifies UPDATECURSOR=YES with CURSORUPDATETYPE=NEXTCOND.

The SETCURSOR keyword is only meaningful for list structures allocated in a coupling facility of CFLEVEL=1 or higher.

NO_SETCURSOR

The list cursor and the list cursor direction will remain unchanged.

HEAD

The list cursor is to be set to the entry identifier for the first entry on the list and the list cursor direction is to be set in a head-to-tail direction. If the list is empty, the list cursor will be reset to binary zeros.

TAIL

The list cursor is to be set to the entry identifier for the last entry on the list and the list cursor direction is to be set in a tail-to-head direction. If the list is empty, the list cursor will be reset to binary zeros.

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

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

• For REQUEST=MONITOR_EVENTQ, specify the vector index to be associated with the monitored event queue. If the request completes successfully, this local vector index in the vector for the connection specified by CONTOKEN will subsequently reflect the empty or not-empty state of the user's event queue.
• For REQUEST=MONITOR_LIST, specify the vector index that is to reflect the empty or not-empty state of the monitored list. If the request completes successfully, this local notification vector index in the vector for the connection specified by CONTOKEN will subsequently reflect the empty or not-empty state of the monitored list.
• For REQUEST=MONITOR_KEYRANGE, specify the vector index that is to reflect the empty or not-empty state of the monitored key-range. If the request completes successfully, this local notification vector index in the vector for the connection specified by CONTOKEN will subsequently reflect the empty or not-empty state of the monitored key-range.

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