Parameter Descriptions

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

REQUEST=LOCK

Use this input parameter to specify that the LOCKINDEX lock be operated on as specified by the LOCKOPER parameter.

,ANSAREA=NO_ANSAREA

,ANSAREA=ansarea

Use this output parameter to specify an answer area to contain information returned from the request. The format of the answer area is described by mapping macro IXLYLAA. Upon successful completion of a request for LOCKOPER=READNEXT request, the answer area contains the connection ID of the connection holding the lock (field LAACONID) and the index of the lock found for a request (field LAALOCKINDEX). For a request with LOCKOPER=TEST, the answer area contains the connection ID of the connection holding the lock (field LAACONID). IXLYLAA fields for this request.

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

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

,CONTOKEN=contoken

Use this input parameter to specify the connect token that was returned by the IXLCONN service. The connect token uniquely identifies your connection to the list structure, and must be specified on each IXLLIST invocation.

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

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

,LOCKCOMP=NO_LOCKCOMP

,LOCKCOMP=lockcomp

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

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

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

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

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

,LOCKDATA=NO_LOCKDATA

,LOCKDATA=lockdata

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

LOCKOPER=SET
LOCKOPER=NOTHELD with LOCKMODE=UNCOND

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

,LOCKINDEX=lockindex

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

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

,LOCKMODE=UNCOND

,LOCKMODE=COND

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

UNCOND

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

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

COND

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

,LOCKOPER=SET

,LOCKOPER=RESET

,LOCKOPER=TEST

,LOCKOPER=READNEXT

Use this input parameter to specify the type of operation to be performed on the lock specified by LOCKINDEX, or for READNEXT, beginning with the lock specified by LOCKINDEX.

LOCKOPER=SET

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

LOCKOPER=RESET

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

LOCKOPER=TEST

When LOCKCOMP is not specified, the lock is tested to check if it is held by your connection.
When LOCKCOMP is also specified, the lock is tested to check if it is held by the connection specified by LOCKCOMP.

If the system returns a return code of zero, the lock was held by the specified user. If the system returns a return code of X'4' and a reason code of IXLRSNCODELOCKNOTHELD, IXLRSNCODELOCKCOND, or IXLRSNCODELOCKHELDBYSYS, the lock is either not held or is held by a user other than the specified user.

LOCKOPER=READNEXT

This option scans the lock table, beginning with the lock index specified by LOCKINDEX, and returns to the answer area information as follows:

When LOCKCOMP is not specified, the lock index of the next held lock, and the connection identifier of the owner of that lock, is returned.
When LOCKCOMP is specified, the lock index of the next lock held by the LOCKCOMP connection is returned.

The request might end prematurely because it exceeded the coupling facility model-dependent time-out criteria. If this happens, the index of the next lock to be processed by the request is returned in the answer area (LAALOCKINDEX). This returned lock index can be specified for LOCKINDEX on another IXLLIST REQUEST=LOCK request to resume processing of the lock table. Except for LOCKINDEX, the same parameters and values should be specified on the resumed request as on the previous request.

,MF=S

,MF=(L,mfctrl)

,MF=(L,mfctrl,mfattr)

,MF=(L,mfctrl,0D)

,MF=(E,mfctrl)

,MF=(E,mfctrl,COMPLETE)

Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service.

Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be coded with the list form of the macro.

Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.

,mfctrl: Use this output parameter to specify a storage area to contain the parameters.
To Code: Specify the RS-type name or address (using a register from 2 to 12) of the parameter list.
,mfattr: Use this input parameter to specify the name of a 1- to 60-character string that can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code mfattr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE: Use this input parameter to require that the system check for required parameters and supply defaults for omitted optional parameters.
Note: In the macro expansion you might see some defaults for optional parameters that are not documented here. The ones that are not documented do not have any effect on the macro. For example, if SMILE=var were an optional parameter and the default is SMILE=NO_SMILE then it would not be documented. However, if the default was SMILE=:-), then it would be documented because a value would be the default.

,MODE=SYNCSUSPEND

,MODE=SYNCECB

,MODE=SYNCEXIT

,MODE=SYNCTOKEN

,MODE=ASYNCECB

,MODE=ASYNCEXIT

,MODE=ASYNCTOKEN

Use this input parameter to specify whether the request is to be performed synchronously or asynchronously. MODE can also be used to specify how your program can be notified of request completion.

MODE=SYNCSUSPEND: The request is performed synchronously. If necessary, the caller is suspended. Control is returned to the caller when the request completes. The caller must be in an enabled state to use this option.
MODE=SYNCECB: The request attempts synchronous processing. If the request cannot be completed synchronously, control is returned to the caller before the request completes, and the ECB specified by REQECB is posted when the request completes.
MODE=SYNCEXIT: The request attempts synchronous processing. If the request cannot be completed synchronously, control is returned to the caller before the request completes, and the connection's complete exit is called when the request completes.
MODE=SYNCTOKEN: The request attempts synchronous processing. If the request cannot be completed synchronously, control is returned to the caller before the request completes, and a token that uniquely identifies the request is returned in the area specified by REQTOKEN. The token is required to force completion of the request. See the REQTOKEN parameter description for a complete explanation of the request token.
Note: ANSAREA is a required parameter when MODE=SYNCTOKEN is specified.
MODE=ASYNCECB: Control is returned to the caller before the request completes. The ECB specified by REQECB is posted when the request completes.
MODE=ASYNCEXIT: Control is returned to the caller before the request completes. The connection's complete exit is called when the request completes.
MODE=ASYNCTOKEN: Control is returned to the caller before the request completes. A token that uniquely identifies the request is returned to the area specified by REQTOKEN. The token is required to force completion of the request. See the REQTOKEN parameter description for a complete explanation of the request token.
Note: ANSAREA is a required parameter when MODE=ASYNCTOKEN is specified.

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

,REQDATA=NO_REQDATA

,REQDATA=reqdata

Use this input parameter with MODE=SYNCEXIT or MODE=ASYNCEXIT to pass any data you choose to the complete exit. The exit will get control only if the request is processed asynchronously.

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

,REQECB=reqecb

Use this output parameter with either MODE=SYNCECB or MODE=ASYNCECB to specify the address of an ECB, which is to be posted when the request completes if the request was processed asynchronously.

Before coding REQECB, you must ensure that:

You initialize the ECB before you issue the request.
The ECB resides in either common storage or the home address space where IXLCONN was issued.
Any tasks that wait for the ECB to be posted reside in the home address space where IXLCONN was issued.

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

,REQID=NO_REQID

,REQID=reqid

Use this input parameter to specify a user-defined request identifier to be associated with the request. You can specify this request identifier on the IXLPURGE macro to cancel a request that has not yet been processed.

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

,REQTOKEN=reqtoken

Use this output parameter with either MODE=SYNCTOKEN or MODE=ASYNCTOKEN to specify the address of a storage area to receive the request token that is returned when the request will be processed asynchronously. This token, which uniquely identifies the request, must be used as input to the IXLFCOMP macro, which you use to determine if the request has completed.

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

,RETCODE=retcode

Use this output parameter to specify a field to contain the return code. (The return code is also returned in register 15.)

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

,RSNCODE=rsncode

Use this output parameter to specify a field to contain the reason code returned, if applicable. (The reason code is also returned in register 0.)

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