File: lke.hlp

package info (click to toggle)
fis-gtm 6.3-007-1
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 36,284 kB
  • sloc: ansic: 328,861; asm: 5,182; csh: 5,102; sh: 1,918; awk: 291; makefile: 69; sed: 13
file content (654 lines) | stat: -rw-r--r-- 22,860 bytes parent folder | download
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.