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 LKINF macro provides information on which locks are already being used. Several search filters can be activated to narrow the selection. The locks are identified by their lock names. The lock names may be fully or partially qualified names. If you specify partially qualified lock names, then, under certain circumstances, access may be very slow since the entire DLM database has to be searched for hits.
Macro formats and description of operands
LKINF |
MF=C / D / L / M / E ,CONTROL=list-poss(3): *LOCKED / *LOCKED_BY_ME / *LCKMODE ,LCKMODE=*NU / *CR / *CW / *PR / *PW / *EX / <var: enum-of _lckmode_s:1> ,NAMEADR=<var: pointer> ,NAMELEN=0 / <integer 0..48> / <var: int:2> ,NAMRNGE=*OWNSYSTEM / *CLUSTER / <var: enum-of _namerange_s:1> ,SCOPE=*NAMESPACEID / *USERID / *GROUPID / <var: emun-of_scope_s:1> ,NAMTYPE=*FULL / *PARTIAL / <var: enum-of _nametype_s:1> ,PARAM=<var: pointer> / (reg: pointer>) ,PREFIX=N / p ,MACID=LDI / mac |
The operands are described in alphabetical order below.
CONTROL=
The search filter controls which data is to be returned.
list-poss(3):
A list containing a maximum of four elements can be formed from the following values.
*LOCKED
Only information about locks with a lock mode not equal to zero is returned.
*LOCKED_BY_ME
Only information about locks which the user is maintaining in a lock mode not equal to zero is returned. The user is identified by his or her lock ID (LOCKID).
*LCKMODE
Only information relating to the specified lock mode is returned.
LCKMODE=
Specifies the requested lock mode. Is only evaluated if the operand CONTROL=*LCKMODE is also specified.
*NU
The lock is in Null Mode and is always allocated. It is compatible with all other lock requests. 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.
Note
The LCKMODE and CONTROL operands may not be specified together. The lock mode may only be specified directly via the LCKMODE operand or indirectly via the CONTROL operand.
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.
NAMEADR=
Field with the address of the lock name.
<var: pointer>
Name of the field with the address of the lock name.
NAMELEN=
Default setting is 0.
Specifies the length of the lock name.
<integer 0..48>
Direct specification of the length of the lock name at the time of transfer.
<var: int:2>
Name of the field with the length of the lock name at the time of execution.
NAMRNGE=
Specifies the range within which the lock name is valid.
*OWNSYSTEM
The specified lock name is valid on the local system only.
*CLUSTER
The specified lock name is valid for the whole cluster.
<var: enum-of _namerange_s:1>
Name of the field with the range in which the lock name is valid.
NAMTYPE=
Specifies whether the character string for the name is a fully or partially qualified lock name.
*FULL
The specified lock name is a fully qualified lock name.
*PARTIAL
The specified lock name is a partially qualified lock name.
<var: enum-of _nametype_s:1>
Name of the field with the lock name type.
SCOPE=
Determines the local scope of the lock name
*NAMESPACEID
Preset value: the specified lock name is used as the internal lock name. The first part (8 bytes) of the specified lock name implicitly forms the local scope. The local scope must be a character string. The valid characters are the letters “A..Z”, “a..z”; the digits “0..9” and the special characters “@” and “#”. The maximum length of the specified lock name is 48 characters.
*USERID
The user ID to which the calling task belongs is used to form the internal lock name. The DLM determines the user ID and places it at the start of the lock name. The first part of the specified lock name is not interpreted as the local scope. The maximum length of the specified lock name is reduced to 40 characters.
If the operand SCOPE=*USERID is specified, an application's locks can be easily protected against access by another application. The applications simply have to be started under different user IDs.
*GROUPID
The user group to which the calling task belongs is used to form the internal lock name. The DLM determines the user group and places it at the start of the lock name. The first part of the specified lock name is not interpreted as the local scope. The maximum length of the specified lock name is reduced to 40 characters.
The operand SCOPE=*GROUPID may only be specified if the software product
SECOS has been purchased and is operational as otherwise the LKENQ call results in an error.
<var: enum-of _scope_s:1>
Name of the field with the local scope of the lock name at runtime.
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 LKINF 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. At least one corresponding lock was |
X'cc' | X'bb' | X'aaaa' | Meaning |
X'01' | X'00' | X'0000' | The macro was executed but no corresponding lock was found. |
X'02' | X'00' | X'0000' | The macro was executed and corresponding locks were found but not all |
X'00' | X'01' | X'1001' | The lock name is too long. |
X'00' | X'01' | X'1002' | The address of the lock name is not available. |
X'00' | X'01' | X'1003' | The specified lock name is not permissible. |
X'00' | X'01' | X'1004' | The specified name space is invalid. |
X'00' | X'01' | X'100F' | The search filter is not permissible. |
X'00' | X'01' | X'1015' | The specification in the LCKMODE operand is invalid. |
X'00' | X'01' | X'1016' | The specification in the NAMTYPE operand is invalid. |
X'00' | X'01' | X'1017' | The specification in the NAMRNGE operand is invalid. |
X'00' | X'01' | X'10FF' | An incorrect parameter, which has no specific return code, was |
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. |
Other return codes which, in accordance with conventions, apply to all macros are given in the table “Standard return codes” (Standard header).