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 LKCVT macro converts an existing lock request. The lock must have been generated with the LKENQ macro and a lock ID must have been returned.
This lock ID (LOCKID) must be specified when the LKCVT macro is called. The user's lock request is identified by the lock ID.
The lock request is placed in the CONVERTING queue of the lock. If the lock can be allocated it is placed in the GRANTED queue. The LKCVT macro was executed successfully.
The lock request can be synchronous or asynchronous.
If it is asynchronous, the lock is allocated as soon as possible. The selected eventing is started and the allocation is notified to the calling program.
During allocation (conversion from a weaker to a stronger lock (LVBCTL=*MOVE).
During release (conversion from PW or EX mode to a weaker lock protection), the user can specify that the Lock Value Block is to be changed (LVBCTL=*MOVE).
Macro formats and description of operands
LKCVT |
MF=C / D / L / M / E ,ASYNCTL=*SYNCH / *ASYNCH / <var: enum-of _asyncctl_s:1> ,CONTROL=*STD / *EXPRESS / <var: enum-of _ctltype_s:1> ,GRANTID=0 / <var: int:4> ,GRTEVTT=*SYNCH / *TUCONTI / *TUEVENT / <var: enum-of _evttype_s:1> ,HOLDTIM=*INFINITE / *SYSTEM / <var: int:2> / <integer 0..32767> ,LCKMODE=*NU / *CR / *CW / *PR / *PW / *EX / <var: enum-of _lckmode_s:1> ,LOCKID=0 / <var: int:4> ,LSBADR=<var: pointer> ,LVBCTL=*IGNORE / *MOVE / <var: enum-of _lvbctl_s:1> |
LKCVT (cont.) |
,RELEVTT=*NO / *TUCONTI / *TUEVENT / <var: enum-of _evttype_s:1> ,RELID=0 / <var: int:4> ,STATUS=*UNCHANGE / *RESET / *INVALIDATE / <var: enum-of _status_s:1> ,USERPAR=0 / <var: int:4> ,WAITTIM=*STD / *INFINITE / <var: int:2> / <integer 0..32767> ,WAITTYP=*TIME / *IMMEDIATE / <var: enum-of _timetype_s:1> ,PARAM=<var: pointer> / (reg: pointer>) ,PREFIX=N / p ,MACID=LDC / mac |
The operands are described in alphabetical order below.
ASYNCTL=
Allocation control for an asynchronous lock request. If the lock request can be allocated immediately, a contingency process or an event signal can be suppressed.
*SYNCH
If the lock request can be allocated immediately, a contingency process or an event signal is suppressed.
*ASYNCH
Even if the lock request can be allocated immediately, a contingency process or an event signal is generated.
<var: enum-of _asyncctl_s:1>
Name of the field with the allocation control of the asynchronous lock request at the time of execution.
CONTROL=
Specifies the control options for the conversion request.
*STD
Standard control of conversion request.
*EXPRESS
This conversion request is to be executed before other conversion requests. This operand value should only be specified if the converted lock mode is released again very quickly.
<var: enum-of _ctltype_s:1>
Name of the field with the value which has been defined by the user.
GRANTID=
ID for the lock allocation. Specifies, for asynchronous lock requests, which contingency ID or event ID is to be assigned to the information that the lock has now been allocated.
<var: int:4>
Default setting is 0.
The contingency ID or event ID.
GRTEVTT=
Describes the way in which information about the lock allocation is to be returned. There are three methods of control: one synchronous and two asynchronous. The specified ID (contingency ID or event ID) is valid for the current lock request. Other lock requests from other tasks may specify different IDs.
*SYNCH
Synchronous lock request. Return from the macro if the lock has been allocated or an error condition detected. The allocation information is delivered in the return code.
*TUCONTI
Contingency process. This value must be specified to obtain confirmation of the allocation request during contingency processing. The user is notified of incompatible allocation requests which have been enqueued by other users. The release contingency is started if the lock is in an incompatible lock mode.
*TUEVENT
Eventing. An event variable can be used to obtain allocation information. The allocation information is supplied by calling the SOLSIG macro. Incompatible allocation requests from other tasks are notified via the same event variable.
<var:enum-of _evttype_s:1>
Name of the field with the allocation event type at the time of execution
HOLDTIM=
The hold time is the time that the lock holder wants to hold the lock. When the hold time has expired, a release event is generated by the DLM so that the lock holder can weaken or release its lock request.
This can only be specified together with the RELEVTT operand.
*INFINITE
No hold time limit.
*SYSTEM
Hold time defined by the operating system.
<var: int:2>
Hold time defined by the user in seconds.
<integer 0..32767>
Direct specification of hold time in seconds.
LCKMODE=
Specifies the requested lock mode.
*NU
The lock is in Null Mode and is always allocated. It is compatible with all other lock requests. However, access to the resource is not allowed.
*CR
The lock is in Concurrent-Read Mode. Other locks are permitted only in Null Mode, Concurrent-Read Mode, Concurrent-Write Mode, Protected-Read Mode, and in Protected-Write Mode. The lock holder is granted unprotected read access to the resource.
*CW
The lock is in Concurrent-Write Mode. Other locks are permitted only in Null Mode, Concurrent-Write Mode, or in Concurrent-Read Mode. The lock holder is granted unprotected write access to the resource.
*PR
The lock is in Protected-Read Mode. Other locks are permitted only in Null Mode, Concurrent-Read Mode, or in Protected-Read Mode. The lock holder is granted protected read access to the resource.
*PW
The lock is in Protected-Write Mode. Other locks are permitted only in Null Mode and in Concurrent-Read Mode. The lock holder is granted protected write access to the resource.
*EX
The lock is in Exclusive Mode. Other locks are permitted only in Null Mode. Only the lock holder may access the resource.
<var: enum-of _lckmode_s:1>
Name of the field with the lock mode.
LOCKID=
Lock ID of the lock which is to be converted.
<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 Lock Value Block.
<var: pointer>
Name of the field with the address of the Lock Status Block.
LVBCTL=
Control of the Lock Value Block.
*IGNORE
The Lock Value Block is not used.
*MOVE
Read or write the Lock Value Block. The Lock Value Block can be read if the lock is allocated. It can be written if the lock is in PW or EX Mode.
<var: enum-of _lvbctl_s:1>
Name of the field with the control of the Lock Value Block at the time of execution.
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.
A PREFIX can be specified in the C form, D form or M form of the macro and additionally a MACID in the C form or M form.
RELEVTT=
Defines the way in which information about the lock release is to be returned. There are two asynchronous methods of control. The specified ID (contingency ID or event ID) is valid for the current lock request.
*NO
No information about other incompatible lock requests concerning this lock is output. This can lead to deadlock problems if the lock is not released. If the hold time specified for the lock has expired, the lock holder for this lock request is terminated without further notification.
*TUCONTI
Contingency process. This value must be specified to obtain confirmation of the release request during contingency processing. The user is notified of incompatible allocation requests which have been enqueued by other users. The release contingency is started if the lock is in an incompatible lock mode.
*TUEVENT
Eventing. An event variable can be used to obtain the release information. The allocation information is supplied by calling the SOLSIG macro. Incompatible allocation requests from other tasks are notified via the same event variable.
<var:enum-of _evttype_s:1>
Name of the field with the release-event type at the time of execution.
RELID=
ID for the lock release. Specifies which contingency ID or event ID is to be assigned to the information that the lock request is blocking another lock request from a different user.
<var: int:4>
Default setting is 0.
The contingency ID or event ID.
STATUS=
Lock status change parameter. Specifies whether the lock status is validated when a lock is released in PW or EX Mode.
*UNCHANGE
The lock status is not changed while a lock is released in PW or EX Mode.
*RESET
The lock status is reset to VALID while a lock is released in PW or EX mode.
*INVALIDATE
The lock status is set to INVALID while a lock is released in PW or EX mode.
<var: enum-of _status_s:1>
Name of the field with the lock status change parameter at the time of execution.
USERPAR=
The parameter for asynchronous messages which are to be transferred to the contingency process or to eventing.
<var: int:4>
Default setting is 0.
User-defined values.
WAITTIM=
The wait time is the length of time it will take until the lock is allocated.
*STD
Standard wait time. If WAITTYP=*IMMEDIATE is specified the lock is allocated immediately or the job is terminated. If job processing is delayed (cluster, network) the wait time is 600 seconds.
*INFINITE
The lock request never exceeds the time limit. The lock request waits until the lock is assigned or a deadlock situation is identified.
<var: int:2>
Wait time defined by the user in seconds.
<integer 0..32767>
Direct specification of wait time in seconds.
WAITTYP
Specifies the wait time type for waiting lock requests.
*TIME
The wait time value is specified via the WAITTIM operand.
*IMMEDIATE
Immediate lock request. The lock request is not enqueued if it cannot be allocated immediately. The value for the timeout can be specified via the WAITTIM operand. This value is used if the handling of the lock request leads to a DLM-internal wait status. This may occur, for example, if a network connection is no longer available after the lock request has been sent to a different node for processing, with the result that the necessary response is never transferred from that other node. To prevent this, the user can specify a wait time via the WAITTIM operand.
<var: enum-of _timetype_s:1>
User-defined values.
Return information and error flags
Standard header:
+---------------+ | | | | | |c|c|b|b|a|a|a|a| +---------------+
The following return code relating to the execution of the LKCVT 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. The lock request was converted to a |
X'00' | X'00' | X'0001' | The macro was executed normally. The lock request has been enqueued; |
X'00' | X'00' | X'0002' | The macro was executed. The lock was allocated in the specified lock |
X'00' | X'01' | X'1005' | The Lock Status Block is not available. |
X'00' | X'01' | X'1006' | The GRANTID type is not the same as that specified in GRTTYPE. |
X'00' | X'01' | X'1007' | The RELID type is not the same as that specified in RELTYPE. |
X'00' | X'01' | X'1008' | Invalid combination of GRTEVTT and RELEVTT. |
X'00' | X'01' | X'1009' | The specification in the WAITTIM operand is invalid. |
X'00' | X'01' | X'100A' | The specification in the HOLDTIM operand is invalid |
X'00' | X'01' | X'100C' | The specification in the LOCKID operand is invalid. |
X'00' | X'01' | X'1015' | The specification in the LCKMODE operand is invalid. |
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'40' | X'4001' | A deadlock was detected. |
X'00' | X'40' | X'4003' | The previous lock request has not yet been terminated. |
X'00' | X'82' | X'8002' | Timeout. |
X'00' | X'82' | X'8004' | The lock has already been dequeued. |
X'00' | X'82' | X'8005' | The lock has already been canceled. |
X'00' | X'82' | X'8006' | Immediate lock requests are not possible due to the existence of |
Other return codes which, in accordance with conventions, apply to all macros are given in the table “Standard return codes” (Standard header).