The format for 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.
The CLEAR command removes active LOCKs. The format of the CLEAR command is:
C[LEAR] [/qualifier...]
LKE> CLEAR/PID=232005FB /INTERACTIVE
This command presents all LOCKs held by the process with a PID equal to 232005FB. You can choose whether or not to clear each LOCK.
The optional CLEAR command qualifiers are:
/A[LL]
/L[OCK]
/[NO]C[RIT]
/[NO]I[NTERACTIVE]
/O[UTPUT]=file-spec
/P[ID]=process id
/R[EGION]=region-name
By default, CLEAR operates interactively (/INTERACTIVE).
/ALL
Specifies the removal of all current LOCKs. If used with the /REGION qualifier, / ALL removes all LOCKs in the 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.
The /ALL qualifier is incompatible with the /INTERACTIVE qualifier.
/I[NTERACTIVE]
Clears one LOCK at a time interactively. 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].
The /INTERACTIVE qualifier is incompatible with the /ALL qualifier.
By default, CLEAR operates interactively (/INTERACTIVE).
/L[OCK]=PID and region
Allows you to specify 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.
clear /lock="^a"(""b"")"
This command clears lock ^a("b") in the default region.
clear /lock="^a" /nointeractive
This command clears lock ^a in the default region. The addition of the NOINTERACTIVE qualifier instructs LKE to clear the lock without further user intervention.
/[NO]C[RIT]
Allows LKE CLEAR to work even if another process is holding a critical section. This can damage current LOCKs and the LOCK mechanism. It is intended for use only under the direction of Fidelity.
/[NO]I[NTERACTIVE]
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.
/O[UTPUT]=file-spec
Directs the reporting of all cleared LOCKs to a file. If you specify an existing file, LKE creates a new version of overwrites that file.
The /OUTPUT qualifier is compatible with all other qualifiers.
By default, CLEAR sends its messages to SYS$OUTPUT.
/P[ID]=process-id
Clears all LOCKs held by the process with the specified process identification number. LKE interprets the PID as a hexadecimal number. This command 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
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).
Use one of the following procedures to CLEAR (release or unlock) all LOCKs or a specific LOCK on the system.
To clear all LOCKs:
Invoke the M LOCK Utility (LKE).
$ LKEEnter the CLEAR command with the /ALL option at the LKE> prompt.
LKE> CELAR /ALL![[Note]](images/note.jpg)
Use CLEAR /ALL with caution.
To clear individual LOCKs in a specific region:
Invoke the M Lock Utility (LKE)
$ LKEEnter the CLEAR command with the /REGION and /INTERACTIVE options at the LKE> prompt.
LKE> CLEAR/REG=AREG/INTERACTIVEInformation similar to the following displays:
AREG ^a Owned by PID= 208350E3 which is CUR Clear lock ?Type Yes or Y in response to the prompt.
LKE responds with an informational message:
%GTM-S-LCKGONE, Lock removed : ^aRepeat Step 3 until all LOCKs are displayed and acted upon.
The HELP command explains LKE commands. The format of the HELP command is:
H[ELP] [options...]
The HELP command uses similar conventions to the OpenVMS help facility. Enter the LKE command for which you want information at the Topic prompt(s). Press <RETURN> or <CTRL-Z> to return to the LKE prompt.
LKE> HELP SHOW
This command displays help for the SHOW command.
The SHOW command provides a status report on the LOCK mechanism and the LOCK database. The format of the SHOW command is:
SH[OW] [/qualifier...]
LKE> SHOW /ALL
This command displays all LOCKs mapped to all regions of the current Global Directory.
The optional qualifiers are:
/A[LL]
/L[OCK]
/[NO]C[RIT]
/O[UTPUT]=file-spec
/P[ID]=process id
/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. The OpenVMS privileges of the LKE process determine whether LKE can display the state of any other process. Since the SHOW command is a snapshot, and the LOCKs in a running GT.M application constantly fluctuate, the results of a SHOW may become outdated immediately.
/ALL
Specifies a display of 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 other qualifier prevails. SHOW / ALL and /WAIT displays both /ALL and / WAIT information.
/LOCK=PID and region
Allows you to specify a single lock. This provides a precise way to examine specific locks. The resource_name is enclosed in double quotations. 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 quotations with string subscripts enclosed in sets of two double quotations.
show -lock="^a"(""b"")"
This command shows lock ^a("b") in the default region.
/[NO]C[RIT]
Allows LKE SHOW to work even if another process is holding a critical section. Use this qualifier only when normal operation is unsuccessful, as NOCRIT may cause LKE to report incomplete or inconsistent information.
/O[UTPUT]=file-spec
Directs the reporting of the current LOCKs. When you specify an existing file, LKE overwrites that file.
By default, SHOW directs all messages to SYS$OUTPUT.
/P[ID]=process-identification
Displays all LOCKs owned by the specified process identification number (PID).
By default, SHOW displays the LOCKs for all PIDs.
/R[EGION]=region-name
Displays LOCKs for the specified region.
The emphasis>/REGION qualifier is compatible with all other qualifiers.
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. For information on displaying specific LOCKs, refer to the section on the SHOW command and its qualifiers.
LKE> SHOW /ALL /WAIT
Information similar to the following displays:
%GTM-I-NOLOCKIN, No locks were found in $DEFAULT
AREG
^a Owned by PID= 208000E3 which is HIB
BREG
^b(2) Owned by PID= 208978F2 a nonexistent process
^b(1) Owned by PID= 309800G3 which is CUR
Request PID= 20400630 which is HIB
%GTM-I-NOLOCKIN, No locks were found in CREG
SHOW displays the region and resource name of the LOCK as well as the process identification number (PID) and status of the process that holds the LOCK. For more information, refer to the subsequent section "OpenVMS Process Status Codes." LKE examines all REGIONs listed in the Global Directory.
If there are no LOCKs in a particular REGION, LKE displays an informational message.
When you use the SHOW command to display all LOCKs on the system, LKE also displays the status of the process that owns the LOCK.
^a Owned by PID= 209874F2 which is CUR
The most common OpenVMS process status codes and their meanings are described below.
|
CUR |
OpenVMS process status indicating that the LOCK is held by a "current" process. |
|
COM |
OpenVMS process status indicating that the LOCK is held by a process ready to use the processor. |
|
HIB |
OpenVMS process status indicating that the LOCK is held by a process in "hibernation" (that is, waiting for time to pass). Such a process may be waiting to LOCK a resource name presently LOCKed by another process. |
|
LEF |
OpenVMS process status indicating that the LOCK is held by a process waiting for an asynchronous event (local event flag). A process waiting for terminal input waits in a LEF state. |
|
A nonexistent process |
The process that set the LOCK no longer exists. |
|
A process on a remote node |
The LOCK exists on a remote node so the system is unable to determine its exact status. |
|
A GT.CM server |
The LOCK was set on behalf of a process on another node via the GT.CM software. |
|
No privilege |
You do not have the OpenVMS privilege required to view the status. |
For additional information on these and other OpenVMS process status categories, refer to the OpenVMS System Management Utilities Reference Manual.
The SPAWN command creates a sub-process for access to OpenVMS CLI (usually DCL) without terminating the current LKE environment. Use the SPAWN command to suspend a session and issue DCL commands such as DIRECTORY or SHOW LOGICAL.
The format of the SPAWN command is:
SP[AWN] [DCL command]
The SPAWN command has no qualifiers.
LKE> SPAWN "DIR *.DAT"
This command invokes an OpenVMS directory listing of all files in the current default directory with a .DAT extension. The sub-process terminates when the directory listing completes.