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 or 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]