1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654
|
1 Introduction
Introduction
The M Lock Utility (LKE) is a tool for examining and changing the GT.M
LOCK environment. For a description of M LOCKs, refer to the LOCKs section
in the General Language Features of M chapter and the description of the
LOCK command in the Commands chapter of the Programmers Guide.
The two primary functions of the M Lock Utility (LKE) are:
1. SHOW all or specified LOCKs currently active
2. CLEAR all or specified LOCKs currently active
When debugging an M application, you may use LKE to identify a possible
deadlock situation, that is, two or more processes have LOCKs and are
waiting to add resource names LOCKed by the other(s).
Process 1 Process 2
LOCK A
LOCK B
LOCK +A
LOCK +B
Process 1 has A LOCKed and attempts to LOCK B. Process 2 has B LOCKed and
attempts to LOCK A. Because these processes do not release their current
LOCKs before adding additional LOCKs, nor do they provide a timeout to
detect the problem, they are deadlocked. Neither process can proceed
normally. You can use LKE to release one of the LOCKs so both processes
may execute. However, because releasing a LOCK may cause the process to
violate its design assumptions, terminating one process is generally a
safer way to break the deadlock.
**Note**
When a process leaves M, GT.M normally releases any LOCKs or ZALLOCATEs
held by that process. If a GT.M process terminates abnormally, or if the
system "crashes" while a GT.M process is active, GT.M cannot perform
normal clean-up. However, as soon as any other process waits several
seconds for a LOCK owned by a process that no longer exists, GT.M
automatically clears the "orphaned" LOCK.
2 Invoke
Invoke
GT.M installation procedure places the LKE utility package in a directory
specified by the environment variable gtm_dist.
LKE requires that the environment variable gtmgbldir be defined.
Invoke LKE using the following command at the shell prompt. If this does
not work, consult your system manager to investigate setup and file access
issues.
$gtm_dist/lke LKE>
**Important**
Always run LKE on the node where the lock is held.
When LKE is ready to accept commands, it displays the LKE> prompt. To
leave LKE, enter the EXIT command at the LKE> prompt.
When additional information is entered on the command line after the LKE
command, LKE processes the additional information as its command.
$gtm_dist/lke show -all
This command displays all current LOCKs and then returns to the shell
prompt.
If your LKE argument contains quotes, precede each quote in the argument
by a back-slash (\) or enclose the entire argument in a set of quotes
(matching single or double). Apply this convention only for those LKE
commands that you run from the shell.
$gtm_dist/lke show -lock="^Account(\"Name\")"
$gtm_dist/lke show -lock='^Account("Name")'
Both these commands display the status of LOCK ^Account("Name") in the
default region.
1 Commands
Commands
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.
2 Clear
Clear
Use the CLEAR command to remove active LOCKs.
**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]C[RIT]
-[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.
o -ALL removes all current LOCKs.
o If used, CLEAR and -REGION qualifier, -ALL removes all LOCKs in that
region.
o 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.
o By default, CLEAR -ALL operates interactively (-INTERACTIVE).
-[NO]C[RIT]
Allows LKE CLEAR to work even if another process is holding a critical
section.
**Caution**
This can damage current LOCKs and the LOCK mechanism. It is intended for
use only under the direction of FIS.
By default LKE operates in CRIT mode and ensures a consistent view of
LOCKs by using the database critical section(s).
-[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.
o 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.
o When used with CLEAR, -LOCK removes the locks that start with
resource_name.
o 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].
o By default, CLEAR operates interactively (-INTERACTIVE).
o To avoid holding a lock resource too long, LKE skips to the next
matching LOCK if there is no operator response for several seconds.
o -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.
o If you specify an existing file, LKE creates a new version and
overwrites that file.
o If file-name has permission issues, OUTPUT reports the cause of the
error.
o The -OUTPUT qualifier is compatible with all other qualifiers.
o By default, CLEAR sends output messages to stdout.
-P[ID]=pid
Specifies the process identification number that holds a LOCK on a
resource name.
o LKE interprets pid as a decimal number.
o PID clears LOCKs held by the process with the specified process
identification number.
o Provides a means for directing CLEAR to LOCKs held by a process that
is behaving abnormally.
o The -PID qualifier is compatible with all other qualifiers.
-R[EGION]=region-name
region-namespecifies the region that holds the locked resource names.
o REGION clears LOCKs mapped by the current global directory to a region
specified by the region-name.
o The -REGION qualifier is compatible with all other qualifiers.
o 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.
2 CLNup
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.
2 SHow
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]
o By default, SHOW displays -A[LL].
o The SHOW command reports active LOCKs. Information includes the LOCK
resource name and the process identification (PID) of the LOCK owner.
o 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.
o 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.
o 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.
o The results of a SHOW may be immediately "outdated" by M LOCK
activity.
o 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**
GT.CM is an RPC-like way of remotely accessing a GT.M database.
-ALL
Specifies all current LOCKs.
o -ALL displays all current LOCKs in all regions and information about
the state of processes owning these LOCKs.
o The -ALL qualifier is compatible with all other qualifiers.
o When -ALL is combined with -PID or -REGION, the most restrictive
qualifier prevails.
o SHOW -ALL and -WAIT displays both -ALL and -WAIT information.
-L[OCK]=resource_name
resource_name specifies a single lock.
o 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.
o When used with the CLEAR command, the LOCK qualifier removes the
specified lock.
o 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.
o By default LKE operates in CRIT mode and ensures a consistent view of
LOCKs by using the database critical section(s).
o -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.
o If you specify an existing file, LKE creates a new version and
overwrites that file.
o The -OUTPUT qualifier is compatible with all other qualifiers.
o 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.
o LKE interprets pid as a decimal number.
o PID displays all LOCKs owned by the specified process identification
number.
o The -PID qualifier is compatible with all other qualifiers; the most
restrictive of the qualifiers prevails.
o By default, SHOW displays the LOCKs for all PIDs.
-R[EGION]=region-name
Specifies the region that holds the locked resource names.
o The REGION qualifier displays LOCKs of that specified region.
o The REGION qualifier is compatible with all other qualifiers; the most
restrictive of the qualifiers prevails.
o 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.
o SHOW -WAIT does not display the owner of the LOCK.
o SHOW -ALL -WAIT displays both -ALL and -WAIT information.
o 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
2 Exit
Exit
The EXIT command ends an LKE session. The format of the EXIT command is:
E[XIT]
2 Help
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.
2 SPawn
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.
1 Summary
Summary
+-------------------------------------------------------------------+
| COMMAND | QUALIFIER | COMMENTS |
|---------+---------------------+-----------------------------------|
| | -ALL | |
| | -L[OCK] | |
| | -[NO]CRIT | |
| | -[NO]EXACT | |
| C[LEAR] | | Use CLEAR with care and planning. |
| | -[NO]I[NTERACTIVE] | |
| | -O[UTPUT]=file-name | |
| | -P[ID]=pid | |
| | -R[EGION]=name | |
|---------+---------------------+-----------------------------------|
| E[XIT] | none | - |
|---------+---------------------+-----------------------------------|
| H[ELP] | [option] | - |
|---------+---------------------+-----------------------------------|
| | -ALL | |
| | -L[OCK] | |
| | -[NO]CRIT | |
| | -N[OINTERACTIVE] | |
| SH[OW] | | - |
| | -O[UTPUT]=file-name | |
| | -P[ID]=pid | |
| | -R[EGION]=name | |
| | -W[AIT] | |
|---------+---------------------+-----------------------------------|
| SP[AWN] | none | shellcommand |
+-------------------------------------------------------------------+
1 Copyright
Copyright
Copyright 2018
Fidelity National Information Services, Inc. and/or its subsidiaries. All
rights reserved.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or any
later version published by the Free Software Foundation; with no Invariant
Sections, no Front-Cover Texts and no Back-Cover Texts.
GT.M(TM) is a trademark of Fidelity National Information Services, Inc.
Other trademarks are the property of their respective owners.
This document contains a description of GT.M and the operating
instructions pertaining to the various functions that comprise the system.
This document does not contain any commitment of FIS. FIS believes the
information in this publication is accurate as of its publication date;
such information is subject to change without notice. FIS is not
responsible for any errors or defects.
**Note**
This help file is a concise representation of revision V6.3-006 of the
UNIX Administration and Operations Guide. To obtain a copy of the current
revision, go to www.fis-gtm.com and then click on the User Documentation
tab.
|