LKCAN - Cancel lock request

General

Application area:	Distributed Lock Manager (DLM); see "Distributed Lock Manager (DLM)"
Macro type:	Type S, MF format 3: C/D/L/M/E form; see "S-type macros"

Macro description

The LKCAN cancels lock requests which have not yet been allocated by the DLM. Lock requests which have been generated by the LKENQ macro and are in the WAITING or CONVERTING queue of the lock are completely canceled. If the lock request is in the GRANTED queue it is terminated with an error code.

Lock requests which are to be converted with the LKCVT macro are not canceled. Only the conversion job is canceled.

The call can be synchronous or asynchronous.

Macro formats and description of operands

LKCAN

MF=C / D / L / M / E

,ACKEVTT=*SYNCH / *TUCONTI / *TUEVENT / <var: enum-of _evttype_s:1>

,ACKNID=0 / <var: int:4>

,LOCKID=0 / <var: int:4>

,LSBADR=<var: pointer>

,USERPAR=0 / <var: int:4>

,PARAM=<var: pointer> / (reg: pointer>)

,PREFIX=N / p

,MACID=LDA / mac

The operands are described in alphabetical order below.

ACKEVTT=
Defines the way in which information about the cancellation is to be returned. There are three methods of control. The specified ID (contingency ID or event ID) is valid for the current cancellation request. Other cancellation requests from other tasks may specify different IDs.

*SYNCH
Synchronous lock request. Return from the macro if the lock request has been canceled or an error condition detected. The cancellation information is delivered in the return code.

*TUCONTI
Contingency process. This value must be specified to obtain confirmation of the cancellation request during contingency processing

*TUEVENT
Eventing. An event variable can be used to obtain the cancellation information. The cancellation information is supplied by calling the SOLSIG macro.

<var:enum-of _evttype_s:1>
Name of the field with the value of the cancellation method.

ACKNID=
For asynchronous lock requests, this operand specifies the contingency ID or the event ID which contains the information that the lock has now been deleted.

<var: int:4>
Default setting is 0.
Contingency ID or event ID.

LOCKID=
Lock ID for the lock request which is to be canceled.

<var: int:4>
Default setting is 0.
Lock ID which has been returned by the LKENQ macro.

LSBADR=
Field with the address of the Lock Status Block. The Lock Status Block contains the return code of the asynchronous call.

<var: pointer>
Name of the field with the address of the Lock Status Block.

MF=
For a general description of the MF operand, its operand values and any subsequent operands (e.g. PREFIX, MACID, and PARAM), see "S-type macros". The valid MF values are given at the start of the macro description under “Macro type” and are included in the macro format.

USERPAR=
The parameter for asynchronous messages which are to be transferred to the contingency process or to the event variable.

<var: int:4>
Default setting is 0. User-defined values.

Return information and error flags (return codes)

Standard header:

+---------------+
|   |   |   |   |
|c|c|b|b|a|a|a|a|
+---------------+

The following return code relating to the execution of the LKCAN macro is transferred in the standard header
(cc=Subcode2, bb=Subcode1, aaaa=Maincode):

X'cc'	X'bb'	X'aaaa'	Meaning
X'00'	X'00'	X'0000'	The macro was executed normally.
X'00'	X'00'	X'0001'	The macro was executed normally. The cancel request has been enqueued. The lock request is canceled asynchronously.
X'00'	X'00'	X'0004'	Cancellation of the lock request was initiated, but the lock is still allocated.
X'00'	X'01'	X'1005'	The Lock Status Block is not accessible.
X'00'	X'01'	X'1006'	The ACKNID type is not the same as that specified in ACKEVTT.
X'00'	X'01'	X'100C'	The specification in the LOCKID operand is invalid.
X'00'	X'01'	X'1014'	The selected function is not allowed for the user.
X'00'	X'01'	X'10FF'	An incorrect parameter, which has no specific return code, was specified.
X'00'	X'20'	X'2001'	An internal error occurred.
X'00'	X'20'	X'2003'	Internal error in connection with the resource block.
X'00'	X'20'	X'2004'	Internal error in connection with a timeout.
X'00'	X'20'	X'2005'	Internal error in connection with the lock request.
X'00'	X'20'	X'2006'	Internal error in connection with XCS.
X'00'	X'82'	X'8004'	The lock has already been dequeued.

Other return codes which, in accordance with conventions, apply to all macros are given in the table “Standard return codes” (Standard header).