REQUEST=ALTER

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

,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 refected 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 output parameter to specify the unique identifier assigned to the record data entry upon successful, synchronous request completion. If a new record data entry was allocated by this request, the identifier indicates the newly allocated entry. If the request resulted in the update of an existing record data entry that had been associated with this resource through a previous OBTAIN or ALTER request, the identifier indicates the updated entry. 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.

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

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 12-character 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.

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

SYNCEXIT

Indicates that the ALTER 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 may be given control before control returns to the next sequential instruction after the connected user's IXLLOCK request.

SYNCFAIL

Indicates that the ALTER 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 ALTER request are:

IXLMODESYNCSUSPEND
IXLMODESYNCEXIT
IXLMODESYNCFAIL

If you specify a value other than one of the IXLYCON constants that is valid for an ALTER 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=modeval 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=UNCHANGED

,RDATA=DELETE

,RDATA=WRITE

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

Note that specification of the WRITE or DELETE options will result in a parameter error if the lock structure indicated by the input CONTOKEN does not provide recording capabilities.

UNCHANGED: Indicates that the record data entry associated with this resource, if any, is not to be changed.
DELETE: Indicates that the record data entry associated with this resource is to be deleted. If no record data entry is currently allocated and associated with this resource, then this keyword is ignored.
WRITE: Indicates that the record data entry identified by ENTRYID is to be updated with the data specified by the RDATAVAL keyword. If a record data entry is currently associated with the resource, its contents will be updated. Otherwise, a new entry will be allocated.

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