REQUEST=OBTAIN

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

,CONID=NO_CONID

,CONID=conid

Use this input parameter to specify the connection identifier that indicates the connection from which the record data entry is being reacquired. If the record data entry designated by ENTRYID is not associated with the connection specified by CONID, the IXLLOCK request will fail. When a record data entry is successfully reacquired, it will become associated with the reacquiring connected user.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a one-byte input field that contains the connection identifier associated with the record data entry to be reacquired.

,CRITICALREQUEST=0

,CRITICALREQUEST=criticalrequest

Use this input parameter to indicate whether monitoring of storage is to be honored for this request. Valid values are 0 (or IxllockCriticalRequestNo) and 1 (or IxllockCriticalRequestYes). The CRITICALREQUEST option only has meaning when MONITORSTORAGE=1 (IxlconnMonitorStorageYes) is also specified on the IXLCONN request.

A value of 0 (IxllockCriticalRequestNo) specifies to monitor storage usage whenever MONITORSTORAGE=1 (IxlconnMonitorStorageYes) is also specified on the IXLCONN request. When the amount of inuse storage reaches a preestablished threshold, the request will be rejected with a return code of IXLRETCODEENVERROR and a reason code of IXLRSNCODERESOURCESCONSTRAINED.

A value of 1 (IxllockCriticalRequestYes) specifies not to monitor storage usage. Preestablished thresholds for the amount of inuse storage will be ignored for this request. Only when dataspace storage for this request becomes exhausted will an abend X'026' be issued by the XES storage manager.

Any other specified value will have the same behavior as specifying a value of 0 (IxllockCriticalRequestNo).

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a one-byte input field that contains the value indicating whether monitoring of storage is to be honored.

,ENTRYCOUNT=entrycount

Use this output parameter to contain the number of record data entries in the structure that are currently in-use upon successful, synchronous completion of the request. This value is analogous to the IXLYAMDSTRL_LSEC field that is returned by the XES Accounting and Measurement service, IXLMG. The value returned in the ENTRYCOUNT field can be used in conjunction with the value indicating the maximum number of record data entries supported by the allocated lock structure to monitor structure capacity and anticipate “structure full” conditions. The maximum number of record data entries allowed is returned in the CONALOCKMAXRECORDELEMENTS field of the Connect answer area. You can also use the IXLMG macro to retrieve the value, which will be returned in the IXLYAMDSTRL_LSEC field of the IXLMG answer area.

Note that if the request is unsuccessful or being processed asynchronously (in which case the results are presented to the user's complete exit), the contents of ENTRYCOUNT are not valid.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword output field to contain the number of record data entries in the structure that are currently in-use.

,ENTRYID=entryid

Use this input/output parameter to specify the unique identifier assigned to the record data entry.

When RDATA=WRITE, ENTRYID is an output parameter to contain the unique identifier assigned to the record data entry upon successful, synchronous request completion. If the request is unsuccessful or being processed asynchronously (in which case the results are presented to the user's complete exit), the contents of ENTRYID are not valid.
When RDATA=REACQUIRE, ENTRYID is an input parameter to contain the unique identifier of the record data entry to be reacquired. The entry with this identifier must already exist.

ENTRYID is a required keyword when RDATA=REACQUIRE or RDATA=WRITE is specified.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 12-character input/output field to contain the unique identifier assigned to the record data entry.

,HASHVAL=hashval

Use this input parameter to specify a hash value associated with the resource name. The hash value along with the resource name serves to fully qualify an IXLLOCK resource. The method of producing the hash value is completely at the discretion of the connected user. Typically, the value provided for this keyword is the output of a user-defined hashing algorithm that receives a resource name as input.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an input fullword field that contains a hash value associated with the resource name.

,LOCKDATA=ALL_ZEROES

,LOCKDATA=lockdata

Use this input parameter to specify user-defined data to be associated with this resource. The contents of LOCKDATA are at the discretion of the user and have no meaning to the system. The associated LOCKDATA is presented to this connected user's complete exit if the OBTAIN request is processed asynchronously. The LOCKDATA is also presented to the complete and notify exits to inform the user of subsequent updates (such as the completion of requests to alter this resource) and status regarding the owned resource.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an eight-character input field that contains connected user-defined data to be associated with this resource.

,MODE=SYNCSUSPEND

,MODE=SYNCEXIT

,MODE=SYNCFAIL

,MODE=VALUE

Use this input parameter to specify how the request should be processed if it is not able to be serviced immediately. If the request is able to be processed immediately, the MODE keyword is ignored and control is returned to the caller with all information regarding the completed request.

SYNCSUSPEND

Indicates that the OBTAIN request is to be handled synchronously. The caller receives control back only when the request is complete. If necessary, the caller is suspended until the request is complete.

SYNCEXIT

Indicates that the OBTAIN request is to be handled asynchronously. Return and reason codes are returned to the caller indicating that the request will be processed in this manner. Request completion is reported through the connected user's complete exit. The user-specified complete exit might be given control before control returns to the next sequential instruction after the connected user's IXLLOCK request.

SYNCFAIL

Indicates that the OBTAIN request is to be cancelled if it cannot be processed without delay. Return and reason codes are returned to the caller indicating that the request has been cancelled.

SYNCFAILDELAY=0,SYNCFAILDELAY=syncfaildelayvalue

When you specify MODE=SYNCFAIL, use this optional keyword to handle delays for XES latch serialization when the XES normal latch is being held.

0 indicates that the delay is to be cancelled and is the default; the return and reason code provide information.

syncfaildelayvalue specifies the value represented in IXLYCON, to control which delays to tolerate by the MODE=SYNCFAIL request. This option is ignored for all other types of requests.

The valid IXLYCON constants for IXLLOCK requests are:

IXLSYNCFAILDELAYFORLATCHNO, which specifies that if the request encounters delays for internal XES serialization, it is cancelled with the IxlRetCodeEnvError return code and IxlRsnCodeNoDelay reason code.
IXLSYNCFAILDELAYFORLATCHYES , which specifies that if the request encounters delays for normal internal XES serialization, it is NOT cancelled with the IxlRetCodeEnvError return code and IxlRsnCodeNoDelay reason code. Note that this does not include serialization on behalf of serialized connection recovery processing.

Note that IXLCONN ALLOWAUTO=YES, SUSPEND=YES behavior is not changed as part of the SYNCFAILDELAY specification. If the system receives an IXLLOCK OBTAIN or ALTER SYNCFAIL request while the target structure is delayed because of system-managed rebuild processing, the request is not deferred regardless of SYNCFAILDELAY. The system will fail the request with the IxlRsnCodeNoDelay reason code.

If you specify a value other than one of the valid IXLYCON constants for an IXLLOCK request, the request fails with reason code IxlRsnCodeBadSyncFailDelay

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a one-byte input field that contains a value that indicates the desired SyncFailDelay behavior for the request to be processed.

VALUE

Indicates that the contents of MODEVAL are to be used to specify how the request is to be processed if it cannot be serviced immediately.

,MODEVAL=modeval

Use this input parameter to specify the value, as represented in IXLYCON, of the desired mode in which the request is to be processed.

The valid IXLYCON constants for an OBTAIN request are:

IXLMODESYNCSUSPEND
IXLMODESYNCEXIT
IXLMODESYNCFAIL

If you specify a value other than one of the IXLYCON constants that is valid for an OBTAIN request, the IXLLOCK request fails with reason code IXLRSNCODEBADMODEVAL.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a one-byte input field that contains a value indicating the desired mode in which the request is to be processed.

SYNCFAILDELAY=0,SYNCFAILDELAY=syncfaildelayvalue

When you specify MODE=VALUE,MODEVAL=modeval, use this optional keyword to handle delays for XES latch serialization when the XES normal latch is being held.

0 indicates that the delay is to be cancelled and is the default; the return and reason code provide information.

syncfaildelayvalue specifies the value represented in IXLYCON, to control which delays to tolerate by the MODE=VALUE,MODEVAL=modevalL request. This option is ignored for all other types of requests.

The valid IXLYCON constants for IXLLOCK requests are:

IXLSYNCFAILDELAYFORLATCHNO, which specifies that if the request encounters delays for internal XES serialization, it is cancelled with the IxlRetCodeEnvError return code and IxlRsnCodeNoDelay reason code.
IXLSYNCFAILDELAYFORLATCHYES , which specifies that if the request encounters delays for normal internal XES serialization, it is NOT cancelled with the IxlRetCodeEnvError return code and IxlRsnCodeNoDelay reason code. Note that this does not include serialization on behalf of serialized connection recovery processing.

If you specify a value other than one of the valid IXLYCON constants for an IXLLOCK request, the request fails with reason code IxlRsnCodeBadSyncFailDelay

,RDATA=NORDATA

,RDATA=WRITE

,RDATA=REACQUIRE

Use this input parameter to specify the record data operation, if any, that is to be performed as part of obtaining the specified resource.

NORDATA

Indicates that no record data entry is to be allocated and associated with the specified resource.

WRITE

Indicates that a record data entry is to be allocated and to be associated with the owned resource.

REACQUIRE

Indicates that a record data entry identified by ENTRYID is to be reacquired.

The use of the REACQUIRE option is intended to aid in recovery of resources during recovery scenarios. For example,

Upon reconnecting, a previously failed-persistent connected user of locking services can re-obtain resources that were held by its previous instance and reacquire the existing record data entries to be associated with the new instances of ownership. The user could potentially use the UPDATERDATA suboption to update the contents of the reacquired record data entries to reflect updated state information.
A connected user of locking services fails such that the related surviving users wish to recover the resources held by the failing user. The survivors may wish to obtain the specified resources while reacquiring the associated record data entries from the failed connector. The surviving connectors could potentially exploit the CONID suboption to coordinate their processing.

,RDATAVAL=rdataval

Use this input/output parameter to specify the user-defined data to be written to the record data entry.

RDATAVAL is a required parameter when RDATA=WRITE is specified. The entry identifier of the record data entry is returned to the connected user in the ENTRYID field.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 64-character input/output field that contains user-defined data to be written to the record data entry. The contents of RDATAVAL are at the discretion of the connected user and have no meaning to the system. The contention exit may modify the value that is to be written to the record data entry as part of granting the request.

If completion of the OBTAIN request is presented to the user synchronously, the input variable will contain the resultant record data value.

,RNAME=rname

Use this input parameter to specify the resource name for which the request is to be processed. The resource name and length along with the hash value serve to fully qualify an IXLLOCK request.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the character input field that contains the resource name for which the request is being processed.

,RNAMELEN=NO_RNAMELEN

,RNAMELEN=rnamelen

Use this input parameter to specify the length of the resource name identified by RNAME. The resource name length attribute is established on the IXLCONN invocation. The resource name and length along with the hash value serve to fully qualify an IXLLOCK request.

RNAMELEN is valid only when variable-length resource names are in effect for the lock structure. The value you specify for RNAMELEN must be between 1 and 300 inclusive.

If you specify RNAMELEN for a lock structure that does not have the variable-length name attribute, the system rejects the request with reason code IXLRSNCODENOVARRNAME.
If you specify a value for RNAMELEN that is different from the actual length of RNAME, the system uses the RNAMELEN value as the length of RNAME.
If you do not specify RNAMELEN, the length of the resource name defaults to 64 bytes.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword input field that contains the resource name length of the resource identified by RNAME.

,STATE=SHR

,STATE=EXCL

,STATE=VALUE

Use this input parameter to specify the state in which the connected user is requesting to own the resource.

Note that the OBTAIN request may be granted by the contention exit with a STATE different from what was requested. If a user's protocol is exploiting the capability for the contention exit to grant requests with a STATE different than requested, it is recommended that STATE=VALUE be specified for this option to ensure that an output variable will be available to contain the resultant state when request completion is reported synchronously.

SHR: Specifies a shared state.
EXCL: Specifies an exclusive state.
VALUE: Specifies that the contents of STATEVAL are to be used to identify the ownership state.

,STATEVAL=stateval

Use this input/output parameter to specify the value, as represented in IXLYCON, of the desired ownership state.

Note that if a value other than the IXLYCON constants for shared or exclusive is specified, the resource will be requested in the default STATE of share.

Upon successful, synchronous request completion, the input variable will contain the state in which ownership of the resource was granted.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a one-byte input field that contains a value indicating the desired ownership state.

,UDATAVAL=ALL_ZEROES

,UDATAVAL=udataval

Use this input/output parameter to specify user-defined data to be associated with the resource. The contents of UDATAVAL are at the discretion of the connected user and have no meaning to the system. UDATAVAL is presented to the complete, notify, and contention exits when driven.

Note that the contents of UDATAVAL may be modified by the contention exit as part of granting or denying the request. The contents of UDATAVAL have no meaning to the system.

If request completion is reported to the connected user synchronously, UDATAVAL, if specified, will contain the resultant user data value.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 64-character input/output field that contains user-defined data to be associated with the resource.

,UPDATERDATA=NO

,UPDATERDATA=YES

Use this input parameter to specify whether or not to update the contents of the record data entry at the time it is reacquired.

NO: Indicates that the data in the record data entry is not to be updated.
YES: Indicates that the data in the record data entry is to be updated with the data specified by RDATAVAL.
RDATAVAL is a required keyword when UPDATERDATA=YES is specified.