LKE Commands and Qualifiers
Prev  Chapter 8. M Lock Utility (LKE)  Next
GT.M Administration and Operations Guide > M Lock Utility (LKE) > LKE Commands and Qualifiers

LKE Commands and Qualifiers

The general format of LKE commands is:

command [-qualifier[=qualifier-value]]

LKE accepts command and qualifier abbreviations. The section describing each command provides the minimal abbreviation that can be used for that command, and the command qualifiers, if any. FIS recommends the use of a minimum of four characters for key words in scripts to ensure new keywords do not conflict with older scripts.

Clear

Use the CLEAR command to remove active LOCKs.

[Caution] Caution

FIS recommends restricting the use of the LKE CLEAR facility to debugging environments; removing LOCKs in a production environment typically violates application design assumptions and can cause aberrant process behavior. GT.M automatically removes abandoned LOCKs so it is typically safer to MUPIP STOP a process that is inappropriately hanging on to a LOCK.

The format of the CLEAR command is:

CLE[AR] [-qualifier...]

The optional qualifiers are:

-A[LL] 
-L[OCK] 
-[NO]EXACT
-[NO]I[NTERACTIVE] 
-O[UTPUT]="file-name" 
-P[ID]=pid
-R[EGION]=region-name

By default, CLEAR operates interactively(-INTERACTIVE).

Qualifiers for CLEAR

-A[LL]

Specifies all current LOCKs.

  • -ALL removes all current LOCKs.

  • If used, CLEAR and -REGION qualifier, -ALL removes all LOCKs in that region.

  • Issue a CLEAR - ALL only when there are no active GT.M processes using LOCKs, or when you can predict the effect on the application.

  • By default, CLEAR -ALL operates interactively (-INTERACTIVE).

-[NO]EXACT

Limits the CLEAR command to the exact resource name specified with -LOCK=resource_name. NOEXACT (the default) treats the specified resource name as a prefix and works not only on it, but also on any of its descendants, since their existence effectively LOCK their parent tree.

-L[OCK]=""resource_name""

Unless used with -EXACT, specifies the leading prefix for an implicit wild card search of all locks that start with the resource_name.

  • The resource_name is enclosed in two double quotation marks ("" ""). Because M resource names are formatted the same as global nodes with punctuation characters, in this context they are usually enclosed in sets of double quotation marks with string subscripts enclosed in sets of two double quotations.

  • When used with CLEAR, -LOCK removes the locks that start with resource_name.

  • When used with SHOW,-LOCK provides a precise way to examine the specified lock.

-[NO]I[NTERACTIVE]

Interactively clears one LOCK at a time. LKE displays each current LOCK with the PID of the owner process and prompts for verification that the LOCK should be cleared. LKE retains the LOCK for any response other than Y[ES].

  • By default, CLEAR operates interactively (-INTERACTIVE).

  • To avoid holding a lock resource too long, LKE skips to the next matching LOCK if there is no operator response for several seconds.

  • -NOINTERACTIVE forces the action to take place without user confirmation of each change. Using -NOINTERACTIVE prevents the LKE operator from controlling the LOCK subsystem for potentially long periods of time when many locks are held. To do this, it limits the amount of time it waits for each response.

-O[UTPUT]="file-name"

Directs the reporting of all specified LOCKs to a file.

  • If you specify an existing file, LKE creates a new version and overwrites that file.

  • If file-name has permission issues, OUTPUT reports the cause of the error.

  • The -OUTPUT qualifier is compatible with all other qualifiers.

  • By default, CLEAR sends output messages to stdout.

-P[ID]=pid

Specifies the process identification number that holds a LOCK on a resource name.

  • LKE interprets pid as a decimal number.

  • PID clears LOCKs held by the process with the specified process identification number.

  • Provides a means for directing CLEAR to LOCKs held by a process that is behaving abnormally.

  • The -PID qualifier is compatible with all other qualifiers.

-R[EGION]=region-name

region-namespecifies the region that holds the locked resource names.

  • REGION clears LOCKs mapped by the current global directory to a region specified by the region-name.

  • The -REGION qualifier is compatible with all other qualifiers.

  • By default, CLEAR -REGION= operates interactively (-INTERACTIVE).

Example:

LKE>CLEAR -ALL

This command clears all current LOCKs.

Example:

LKE>clear -pid=2325 -interactive

This command presents all LOCKs held by the process with PID equal to 2325. You can choose whether or not to clear each LOCK.

LKE>clear -reg=areg -interactive

This command produces an output like the following:

AREG ^a Owned by PID= 2083 which is an existing
process Clear lock ?

Type Yes or Y in response to the prompt.

LKE responds with an informational message:

%GTM-S-LCKGONE, Lock removed : ^a

Type Yes or N or No or N until all LOCKs are displayed and acted upon.

LKE> clear -pid=4208 -nointeractive

This command clears the lock held by a process with PID 4208. This command produces an output like the following:

DEFAULT Lock removed : ^A

Note that -NOINTERACTIVE forced the action without asking for a confirmation.

Example:

LKE>clear -lock="^a("b") 
Clear lock ? y 
Lock removed : ^a("b") 
LKE>

This command clears lock ^a("b") in the default region.

Example:

LKE>clear -lock="^a" -nointeractive

This command clears all the locks that start with "^a" in the default region. -NOINTERACTIVE qualifier instructs LKE to clear these locks without further user intervention.

Example:

LKE>clear -lock="^a" -exact -nointeractive

This command clears lock ^a in the default region. -NOINTERACTIVE instructs LKE to clear lock ^a without further user intervention.

Example:

LKE>CLEAR -PID=4109 -LOCK=""^A"" 
Clear lock ? Y
Lock removed : ^A 
LKE>

This command clears LOCK ^A held by process with PID 4109.

CLNup

The CLNUP command initiates a cleanup operation of the lock space to remove any abandoned artifacts left by processes that exited without releasing their LOCKs.

The CLNUP processing also checks for the evidence of any entry that has been misplaced by an "overflow" condition; if it finds any, it attempts to automatically repair it, and, if it cannot, it produces a MLKHASHTABERR warning message. On seeing such a message:

  1. Stop all access to (at least) the affected region(s) to ensure that the database is completely quiescent.

  2. Use MUPIP SET -LOCK_SPACE to set, and, if appropriate raise, the number of pages allocated to the management of M locks associated with the affected region(s) before resuming normal operations.

Note that step 1 is necessary because using MUPIP SET -LOCK_SPACE is a standalone operation even with the current value.

The format of the CLNUP command is:

CLN[UP] [-qualifier...]

The optional qualifiers are:

-A[LL]
-I[NTEG] 
-P[ERIODIC]=n
-R[EGION]=region-name

By default, CLNUP operates on all regions (-ALL).

Qualifiers of CLNUP

-A[LL]

Specifies all regions.

-I[NTEG]

Specifies that LKE should validate the integrity of the lock space and report any issues.

-P[ERIODIC]=n

Specifies that LKE perform a CLNUP every n seconds, which, if you desire active cleanup, is much lighter weight than repeated invocations of LKE from a shell script.

You can stop LKE CLNUP -PERIODIC with MUPIP STOP <pid>.

FIS recommends running LKE CLNUP -PERIODIC=n with a value of n that appears to prevent growth in the elements in the lock space as reported by LKE SHOW over substantial periods of time.

-R[EGION]

Specifies that LKE restricts CLNUP operations to a region.

SHow

Use the SHOW command to get status of the LOCK mechanism and the LOCK database. The format of the SHOW command is:

SH[OW] [-qualifier...]

The optional qualifiers are:

-A[LL]
-L[OCK] 
-[NO]C[RITICAL] 
-O[UTPUT]="file-name"
-P[ID]=pid 
-R[EGION]=region-name 
-W[AIT]

  • By default, SHOW displays -A[LL].

  • The SHOW command reports active LOCKs. Information includes the LOCK resource name and the process identification (PID) of the LOCK owner.

  • All invocations of LKE SHOW include utilization information, in the form of available/total space, about shared subscript data space related to LOCK commands. This information appears as a message of the form: %GTM-I-LOCKSPACEINFO, Region: <region_name>: processes on queue: 0/160; LOCK slots in use: lll/120; SUBSCRIPT slot bytes in use: ssss/5052. Additionally, LKE SHOW also displays a LOCKSPACEUSE message. If the lock space is full, LKE SHOW also displays a LOCKSPACEFULL error.

  • A LOCK command which finds no room in LOCK_SPACE to queue a waiting LOCK, does a slow poll waiting for LOCK_SPACE to become available. If LOCK does not acquire the ownership of the named resource with the specified timeout, it returns control to the application with $TEST=0. If timeout is not specified, the LOCK command continues to do a slow poll till the space becomes available.

  • LOCK commands which find no available lock space send a LOCKSPACEFULL message to the operator log. To prevent flooding the operator log, GT.M suppresses further such messages until the lock space usage drops below 75% full.

  • The results of a SHOW may be immediately "outdated" by M LOCK activity.

  • If the LOCK is owned by a GT.CM server on behalf of a client GT.M process, then LKE SHOW displays the client NODENAME (limited to the first 15 characters) and clientPID. The client PID (CLNTPID) is a decimal value in UNIX.

    For example, %GTM-I-LOCKSPACEUSE, Estimated free lock space: 50% of 40 pages shows the amount of free space along with the number of pages configured for lock space

    [Note] Note

    GT.CM is an RPC-like way of remotely accessing a GT.M database.

-ALL

Specifies all current LOCKs.

  • -ALL displays all current LOCKs in all regions and information about the state of processes owning these LOCKs.

  • The -ALL qualifier is compatible with all other qualifiers.

  • When -ALL is combined with -PID or -REGION, the most restrictive qualifier prevails.

  • SHOW -ALL and -WAIT displays both -ALL and -WAIT information.

-L[OCK]=resource_name

resource_name specifies a single lock.

  • The resource_name is enclosed in double quotation marks ("" ""). Because M resource names are formatted the same as global nodes with punctuation characters, in this context they are usually enclosed in sets of double quotation marks with string subscripts enclosed in sets of two double quotations.

  • When used with the CLEAR command, the LOCK qualifier removes the specified lock.

  • When used with the SHOW command, the LOCK qualifier provides a precise way to examine the specified lock and any descendant LOCKed resources.

-[NO]C[RITICAL]

Allows the SHOW command to work even if another process is holding a critical section.

  • By default LKE operates in CRIT mode and ensures a consistent view of LOCKs by using the database critical section(s).

  • -NOCRIT displays the PID of any process currently holding the LOCK critical section.

-O[UTPUT]="file-name"

Directs the reporting of all specified LOCKs to a file.

  • If you specify an existing file, LKE creates a new version and overwrites that file.

  • The -OUTPUT qualifier is compatible with all other qualifiers.

  • By default, the SHOW command send output messages to stdout.

-P[ID]=pid

Specifies the process identification number that holds a LOCK on a resource name.

  • LKE interprets pid as a decimal number.

  • PID displays all LOCKs owned by the specified process identification number.

  • The -PID qualifier is compatible with all other qualifiers; the most restrictive of the qualifiers prevails.

  • By default, SHOW displays the LOCKs for all PIDs.

-R[EGION]=region-name

Specifies the region that holds the locked resource names.

  • The REGION qualifier displays LOCKs of that specified region.

  • The REGION qualifier is compatible with all other qualifiers; the most restrictive of the qualifiers prevails.

  • By default, SHOW displays the LOCKs for all regions.

-W[AIT]

Displays the LOCK resource name and the process state information of all processes waiting for the LOCK to be granted.

  • SHOW -WAIT does not display the owner of the LOCK.

  • SHOW -ALL -WAIT displays both -ALL and -WAIT information.

  • When a process abandons a "wait" request, that request may continue to appear in LKE SHOW -WAIT displays. This appearance is harmless, and is automatically eliminated if the GT.M lock management requires the space which it occupies.

Use the following procedure to display all LOCKs active in the database(s) defined by the current global directory.

LKE> SHOW -ALL -WAIT

This produces an output like the following:

No locks were found in DEFAULT 
AREG 
^a Owned by PID=2080 which is an existing process 
BREG 
^b(2) Owned by PID= 2089 which is a nonexistent process 
No locks were found in CREG

Example:

LKE>SHOW -ALL

This command displays all LOCKs mapped to all regions of the current global directory. It produces an output like the following:

DEFAULT
^A Owned by PID= 5052 which is an existing process
^B Owned by PID= 5052 which is an existing process
%GTM-I-LOCKSPACEUSE, Estimated free lock space: 99% of 40 pages

Example:

LKE>show -lock="^a"(""b"")"

This command shows lock ^a("b") in the default region.

Example:

LKE>SHOW -CRIT

This command displays all the applicable locks held by a process that is holding a critical section.

Example:

LKE>show -all -output="abc.lk"

This command create a new file called abc.lk that contains the output of the SHOW -ALL command.

Example:

LKE>show -pid=4109

This command displays all locks held by process with PID 4109 and the total lock space usage.

Example:

LKE>show -region=DEFAULT -lock=""^A""

This command displays the lock on ^A in the region DEFAULT. It produces an output like the following:

DEFAULT
^A Owned by PID= 5052 which is an existing process
%GTM-I-LOCKSPACEUSE, Estimated free lock space: 99% of 40 pages

Exit

The EXIT command ends an LKE session. The format of the EXIT command is:

E[XIT]

Help

The HELP command explains LKE commands. The format of the HELP command is:

H[ELP] [options...]

Enter the LKE command for which you want information at the Topic prompt(s) and then press RETURN or <CTRL-Z> to return to the LKE prompt.

Example:

LKE> HELP SHOW

This command displays help for the SHOW command.

SPawn

Use the SPAWN command to create a sub-process for access to the shell without terminating the current LKE environment. Use the SPAWN command to suspend a session and issue shell commands such as ls or printenv.

The format of the SPAWN command is:

SP[AWN]

The SPAWN command has no qualifiers.

Example:

LKE>spawn

This command creates a sub-process for access to the current shell without terminating the current LKE environment. Type exit to return to LKE.

Prev  Up  Next
Introduction  Home  Summary