242 lines
8.4 KiB
Plaintext
242 lines
8.4 KiB
Plaintext
|
|
||
|
|
1 Overview
|
||
|
|
The MUMPS LOCK Utility
|
||
|
|
The GT.M LOCK Utility, LKE, provides a tool for examining and changing
|
||
|
|
the GT.M LOCK environment. In MUMPS, the LOCK command reserves one or
|
||
|
|
more resource names. Only one process at a time can reserve a resource
|
||
|
|
name. No other process sharing the same environment can successfully
|
||
|
|
LOCK that resource name at the same time. MUMPS code commonly uses
|
||
|
|
LOCKs as flags controlling access to global data. Generally a LOCK
|
||
|
|
specifies the same as the name of the global variable that requires
|
||
|
|
protected access. However, this is only a convention. A LOCK argument
|
||
|
|
may contain any subscripted or unsubscripted MUMPS name including a
|
||
|
|
name with no preceding caret (^). Because they have the appearance of
|
||
|
|
local variable names, resource names with no preceding caret (^) are
|
||
|
|
commonly referred to as "local LOCKs."
|
||
|
|
|
||
|
|
The ZALLOCATE and ZDEALLOCATE commands provide an alternative,
|
||
|
|
non-standard, mechanism for managing LOCKs.
|
||
|
|
|
||
|
|
2 Functions
|
||
|
|
Functions
|
||
|
|
The two primary functions of the MUMPS LOCK Utility (LKE) are:
|
||
|
|
|
||
|
|
o SHOW all or specified LOCKs currently active on the system
|
||
|
|
|
||
|
|
o CLEAR all or specified LOCKs currently active on the system
|
||
|
|
|
||
|
|
When debugging a MUMPS application, you may use LKE to identify and
|
||
|
|
clear a possible deadlock situation, i.e., two or more processes
|
||
|
|
have LOCKs and are waiting to add resource names LOCKed by the
|
||
|
|
other(s).
|
||
|
|
|
||
|
|
When used with GT.CM, LKE may display and change information on
|
||
|
|
other nodes of a distributed database system.
|
||
|
|
|
||
|
|
2 LOCK_database
|
||
|
|
MUMPS LOCKs and Global Directories
|
||
|
|
GT.M distributes the LOCK database among the database files
|
||
|
|
identified by the Global Directory (GD). The Global Directory
|
||
|
|
Editor (GDE) creates and maintains Global Directories.
|
||
|
|
|
||
|
|
GT.M maps LOCKs of resource names starting with a caret (^) to the
|
||
|
|
database file used to map variables with the same name. If the
|
||
|
|
Global Directory maps the name A to file A.DAT, GT.M maps all LOCKs
|
||
|
|
on resource name ^A to file A.DAT.
|
||
|
|
|
||
|
|
GT.M maps LOCKs on names not starting with a caret (^) to the
|
||
|
|
region of the database specified with the GDE command LOCK -REGION.
|
||
|
|
By default, GDE creates Global Directories mapping local LOCKs to
|
||
|
|
the region DEFAULT.
|
||
|
|
|
||
|
|
These two factors result in the following:
|
||
|
|
|
||
|
|
o ^ LOCKs automatically intersect for all users of the same data
|
||
|
|
in any database file, because GT.M stores the ^ LOCKs in the
|
||
|
|
same file as the data
|
||
|
|
|
||
|
|
o "local" LOCKs intersect dependent on the Global Directory,
|
||
|
|
because users may access the database through different Global
|
||
|
|
Directories.
|
||
|
|
|
||
|
|
2 Global_Directories
|
||
|
|
Establishing a Global Directory
|
||
|
|
GDE and LKE use the environment variable gtmgbldir to identify
|
||
|
|
which file to use for the Global Directory. gtmgbldir should be
|
||
|
|
defined by individual users in their login files.
|
||
|
|
|
||
|
|
Example
|
||
|
|
|
||
|
|
$ gtmgbldir=prod.gld
|
||
|
|
$ export gtmgbldir
|
||
|
|
|
||
|
|
When a process invokes a GT.M image, GT.M identifies the current
|
||
|
|
Global Directory by the environment variable gtmgbldir. Within
|
||
|
|
MUMPS, SET $zgbldir=expr changes the Global Directory. $zgbldir is
|
||
|
|
an intrinsic special variable. An individual LOCK, ZALLOCATE or
|
||
|
|
ZDEALLOCATE argument may specify a Global Directory with the
|
||
|
|
extended global syntax.
|
||
|
|
|
||
|
|
1 CLEAR
|
||
|
|
C[LEAR]
|
||
|
|
The CLEAR command removes active LOCKs. The format of the CLEAR
|
||
|
|
command is:
|
||
|
|
|
||
|
|
C[LEAR] [-qualifier...]
|
||
|
|
|
||
|
|
The optional CLEAR command qualifiers are:
|
||
|
|
|
||
|
|
-A[LL]
|
||
|
|
-I[NTERACTIVE]
|
||
|
|
-O[UTPUT]=file-spec
|
||
|
|
-P[ID]=pid
|
||
|
|
-R[EGION]=region-name
|
||
|
|
|
||
|
|
By default, CLEAR operates interactively (-INTERACTIVE).
|
||
|
|
|
||
|
|
2 Qualifiers
|
||
|
|
|
||
|
|
-ALL
|
||
|
|
-A[LL]
|
||
|
|
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.
|
||
|
|
|
||
|
|
-INTERACTIVE
|
||
|
|
-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).
|
||
|
|
|
||
|
|
-OUTPUT
|
||
|
|
-OUTPUT=file-spec
|
||
|
|
Directs the reporting of all cleared LOCKs. If you specify an
|
||
|
|
existing file, LKE overwrites that file.
|
||
|
|
|
||
|
|
The -OUTPUT qualifier is compatible with all other qualifiers.
|
||
|
|
|
||
|
|
By default, CLEAR sends its messages to the standard output.
|
||
|
|
|
||
|
|
-PID
|
||
|
|
-/P[ID]=pid
|
||
|
|
Clears all LOCKs associated with the specified process
|
||
|
|
identification number. LKE interprets the PID as a decimal
|
||
|
|
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.
|
||
|
|
|
||
|
|
-REGION
|
||
|
|
-/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).
|
||
|
|
|
||
|
|
1 EXIT
|
||
|
|
E[XIT]
|
||
|
|
The EXIT command ends an LKE session. The format of the EXIT command
|
||
|
|
is:
|
||
|
|
|
||
|
|
E[XIT]
|
||
|
|
|
||
|
|
1 HELP
|
||
|
|
H[ELP]
|
||
|
|
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). Use <RETURN> or <CTRL Z> to return to the LKE prompt.
|
||
|
|
|
||
|
|
Example
|
||
|
|
|
||
|
|
LKE> HELP SHOW
|
||
|
|
|
||
|
|
This command displays help for the SHOW command.
|
||
|
|
|
||
|
|
|
||
|
|
1 SHOW
|
||
|
|
SH[OW]
|
||
|
|
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...]
|
||
|
|
|
||
|
|
By default, SHOW displays -ALL.
|
||
|
|
|
||
|
|
The SHOW command reports active LOCKs. Information displayed about
|
||
|
|
specific LOCKs includes the LOCK resource name and the process
|
||
|
|
identification (PID) of the LOCK owner. The results of a SHOW may be
|
||
|
|
immediately "outdated" by MUMPS LOCK activity.
|
||
|
|
|
||
|
|
2 Qualifiers
|
||
|
|
-ALL
|
||
|
|
-A[LL]
|
||
|
|
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. SHOW
|
||
|
|
-ALL -WAIT displays both -ALL and -WAIT information.
|
||
|
|
|
||
|
|
By default, SHOW displays -ALL.
|
||
|
|
|
||
|
|
-OUTPUT
|
||
|
|
-OUTPUT=file-spec
|
||
|
|
Directs the reporting of the current LOCKs. When you specify a
|
||
|
|
file, LKE overwrites that file.
|
||
|
|
|
||
|
|
The -OUTPUT qualifier is compatible with all other qualifiers.
|
||
|
|
|
||
|
|
By default, SHOW directs all messages to SYS$OUTPUT.
|
||
|
|
|
||
|
|
-PID
|
||
|
|
-P[ID]=process-identification
|
||
|
|
Displays all LOCKs owned by the specified PID.
|
||
|
|
|
||
|
|
The -PID qualifier is compatible with all other qualifiers.
|
||
|
|
|
||
|
|
By default, SHOW displays the LOCKs for all PIDs.
|
||
|
|
|
||
|
|
-REGION
|
||
|
|
-R[EGION]=region-name
|
||
|
|
Displays LOCKs for the specified region.
|
||
|
|
|
||
|
|
The -REGION qualifier is compatible with all other qualifiers.
|
||
|
|
|
||
|
|
By default, SHOW displays the LOCKs for all regions.
|
||
|
|
|
||
|
|
-WAIT
|
||
|
|
-W[AIT]
|
||
|
|
Displays the LOCK resource name and the process state
|
||
|
|
information of all processes waiting for the LOCK to be granted.
|
||
|
|
LKE does not display the owner of the LOCK. SHOW -ALL -WAIT
|
||
|
|
displays both -ALL and -WAIT information.
|
||
|
|
|
||
|
|
1 SPAWN
|
||
|
|
SP[AWN]
|
||
|
|
The SPAWN command creates 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 SPAWN command accepts an optional command string for execution by
|
||
|
|
the spawned sub-process. If the SPAWN has command string parameter,
|
||
|
|
the created sub-process prompts and accepts any legal shell command.
|
||
|
|
To terminate the sub-process use the shell logout command.
|
||
|
|
|
||
|
|
The format of the SPAWN command is:
|
||
|
|
|
||
|
|
SP[AWN]
|
||
|
|
|