From:	CRDGW2::CRDGW2::MRGATE::"SMTP::CRVAX.SRI.COM::RELAY-INFO-VAX" 19-DEC-1990 16:11:49.89
To:	MRGATE::"ARISIA::EVERHART"
CC:	
Subj:	lkstat - a program to summarise Locks & Resources (LONG)

Received:  by crdgw1.ge.com (5.57/GE 1.80)
	 id AA22253; Wed, 19 Dec 90 15:41:21 EST
Received: From UCBVAX.BERKELEY.EDU by CRVAX.SRI.COM with TCP; Wed, 19 DEC 90 10:27:38 PST
Received: by ucbvax.Berkeley.EDU (5.63/1.42)
	id AA06023; Wed, 19 Dec 90 10:11:46 -0800
Received: from USENET by ucbvax.Berkeley.EDU with netnews
	for info-vax@kl.sri.com (info-vax@kl.sri.com)
	(contact usenet@ucbvax.Berkeley.EDU if you have questions)
Date: 19 Dec 90 10:36:07 GMT
From: mcsun!cernvax!chx400!cgch!fizciba-geigy.ch!bnebga@uunet.uu.net  (Gary Nebbett)
Organization: Ciba-Geigy AG, Basel, Switzerland
Subject: lkstat - a program to summarise Locks & Resources (LONG)
Message-Id: <1990Dec19.112802@fizciba-geigy.ch>
Sender: info-vax-request@kl.sri.com
To: info-vax@kl.sri.com

lkstat is a program which is intended to make the operation of the VMS
distributed lock manager more understandable, and to provide insight into some
of its uses. It summarises the information about locks and resources which can
be obtained from the local node. I think that it is complementary to the SDA
functions - lkstat gives an overview and SDA can be used to investigate the
detail.

Hopefully the source to lkstat should be found in two further postings
titled "SOURCE: lkstat (part n of 2)"

For each resource on the system lkstat reports:

 whether the resource serves as a directory entry
 which node has mastered the resource
 the mode of the most restrictive granted lock (that the local node knows
about)
 the number of sub-resources
 the number of queued locks
 an interpretation of the resource name, including FID->name conversion
(option)

if requested lkstat will also report

 number of locks on resource that are "local" locks
 number of locks on resource that are "process copy" locks
 number of locks on resource that are "master copy" locks
 number of locks on resource that are owned by processes
 number of locks on resource that are owned by the system
 number of locks on each of the three queues (granted, converting, waiting)

By default lkstat only reports on root resources but will list all resources if
requested.

The address of the RSB is also included in the listing to facilitate further
investigation with SDA. Once you have started SDA and read sys$system:sysdef
you can view resources and locks using the following techniques:

SDA> form [address of RSB provided by lkstat]
SDA> form [address of LKB, see *]
SDA> sho lock [LKID found on RHS of LKB$_LKID entry]
SDA> sho reso /lock= [lockid found on RHS of LKB$_LKID entry]


* The address of the LKB is found by looking at the values to the right hand
side of the RSB fields RSB$L_GRQFL, RSB$L_CVTQFL and RSB$L_WTQFL; if these
values differ from the values to the left of the name then they represent an
address 38 (hex) bytes beyond the start of an LKB. So for example if the value
to the right of the symbol RSB$L_GRQFL differs from the value to the left then
the command

SDA> form [value to right of RSB$L_GRQFL] - 38

should display the LKB. If all the queues appear to be empty, you have probably
selected a "directory only" resource.

Note that lkstat needs CMEXEC privilege to read the RSB and LKB structures and
read access to every indexf.sys file on the system to convert file IDs to
names; if you do not request FID to filename translation or do not have the
necessary privilege, lkstat will just report the FID itself.

If a summary is requested, the values for number of locks and number of
resources should closely match the number of these items reported by "monitor
locks". If FID to filename conversion is used, the output should correlate
reasonably well with the output of "show dev /fi" for each mounted disk.

To provide the FID to filename mapping lkstat uses sys$device_scan to locate
all the disk devices on your system - this will only work on VMS V5.2 and
later; for earlier system you could modify the code to locate the disk devices
by some other means. The disk devices are recorded in a fix sized table, which
is currently set to hold 255 entries; this seems very large from my
perspective, but may not be big enough for you - just increase MAXDISKS if this
is a problem.

To keep the length of each report as short as possible, the output widths have
been chosen so that they comfortably hold the typical values that I see; you
may need to increase this if you have many locks on your system.


There are two main areas where I have used a "more than average" amount of 
guesswork:
 If you have a system where file IDs exceed 65536 or have volume sets then you
 may experience some problems with the FID->name conversion; I think it should
 work but have not been able to test it.

 The establishment of a relationship between volume lock names and device names
 uses the result of lib$getdvi with an item code of DVI$_DEVLOCKNAM. The
 comments in the code detail my uncertainties in this area.


lkstat should be defined something like

$ lks*tat :== $exe$files:lkstat

and used follows:

$ lkstat [-anslo] [filename]

where
 -a : list all resources, otherwise only root resources reported
 -l : examine all LKBs attached to each RSB and produce summary of findings
 -s : produce a summary of total locks, resources, etc
 -n : attempt FID -> name conversion
 -o : send output to file [filename]

The lock database may change whilst lkstat is running (lkstat does not lock the
database against changes); it will report a summary of the errors it
encountered whilst scanning the database. These are not fatal errors and lkstat
will continue to run, but the information presented may not be self-consistent
(eg it might report that there are 10 locks on the system 7 of which are owned
by the system and 2 of which are owned by processes; the 10th lock was dequeued
during the counting process).


lkstat is built by compiling lkstat.c and linking the object against the C
run-time library and sys$system:sys.stb/selective_search. lkstat needs
descriptions of four VMS data structures for which there is no ".h" file
provided with VAXC. I have manually created the information and bundled it in a
single include file. If you have a tool to create .h files automatically, you
might prefer to use those .h files. The entries in sys$share:lib.mlb are:
$lkbdef, $rsbdef, $hm2def, $fh2def.

Copies of volumes 1 and 2 of the VMS Internals and Data Structures Xpress
updates will help you to interpret the output of lkstat. Volume 1, Chapter 10
is on "Lock Management" and Appendix H in Volume 1, (updated in Volume 2) is
"Lock and Resource Use by VMS Components"

The following (perhaps slightly overlong) extract was taken from the output of
$ lkstat -anso x.

The F11B$a locks are File Access Arbitration Locks and summarise the most
restrictive mode of access to the files by processes on this node.

The F11B$q locks are Quota Cache Entry Locks. The value to the right of the
hash is the UIC of the quota entry.

The F11B$v locks are Volume Blocking Locks, used by applications that require
exclusive access to a volume (e.g. anal/disk/repair). They are also parent
locks for F11B$c and F11B$s locks (the slight indentation in the listing is
intended to convey this relationship).

The F11B$c locks are Cache locks for indexf.sys, bitmap.sys and quota.sys.

The F11B$s locks are File Serialization Locks which coordinate shared access to
file headers, etc.

Files with more sophisticated access sharing requirements also have RMS$ File
Locks.

The fields are:

rsb     address of RSB block
fla     flags - D=Directory, O=Only_directory, X=other_unusual_flags_present
sub     number of subresources
cg      mode of most restrictive granted lock
m       access mode of lock
grou    group for non-system-wide locks
node    node on which lock is mastered
name    an interpretation of the resource name

reso    total number of resources on this node
mast    total number of resources mastered on this node
root    total number of root resources (i.e. resources which have no parent)
rmst    total number of root resources mastered on this node
dir     total number of resources that serve as directory entries
diro    total number of resources that serve only as directory entries
lock    total number of locks on this node
lcl     total number of "local" locks on this node
pcpy    total number of "process copy" locks on this node
mcpy    total number of "master copy" locks on this node
sys     total number of system owned locks on this node
proc    total number of process owned locks on this node
chn     maximum chain length in resource hash table encountered

lcl, pcpy, mcpy, sys and proc are only available when lkstat is invoked with
the -l option

reso mast root rmst  dir diro lock  lcl pcpy mcpy  sys proc chn
 699  232  392  131   63   46  993    0    0    0    0    0   9
rsb      fla sub cg lck m grou node   name
808288c0       0 CR   1 K    0 ZEUS25 F11B$aUSERS       [000000]INDEXF.SYS;1
8082df60       0 PR   1 K    0        F11B$aUSERS      
[USERS.BNEBGA.SRC]LKSTAT.EXE;5
80814de0       0 CW   1 K    0        F11B$aUSERS      
[USERS.BNEBGA.A1MAIL$]MAIL.X4M;1
8082bfc0       0 EX   1 K    0        F11B$aUSERS      
[USERS.BNEBGA.TMP]LKSTAT_README.TPU$JOURNAL;1
80804320 D     0 EX   1 K    0        F11B$aUSERS       []TPU$WORK.TPU$WORK;  
808239b0       0 CW   1 K    0 ZEUS22 F11B$aUSERS       [000000]QUOTA.SYS;1
807fdcb0 D     0 PW   1 K    0        F11B$aUSERS       [USERS.BNEBGA]X.;1
807fb0b0       0 PW   1 K    0 ZEUS25 F11B$aUSERS      
[USERS.BNEBGA.DECW]DECW$CALENDAR_FILE.DWC;1
8082ffb0       0 PR   1 K    0        F11B$aUSERS      
[USERS.BNEBGA.A1MAIL$]FK2F0TGK.001;1
8081a1c0       0 PR   1 K    0        F11B$aUSERS      
[USERS.BNEBGA.COM]MYEVE.TPU$SECTION;7
80807c30       0 PW   1 K    0        F11B$qUSERS       #11,23
807f9cc0      40 CR   1 K    0 ZEUS23 F11B$vUSERS       
80826a80       0 NL   1 K    0 ZEUS23  F11B$c[000000]INDEXF.SYS;1
808003e0       0 NL   1 K    0 ZEUS23  F11B$c[000000]BITMAP.SYS;1
80819b90       0 PR   1 K    0 ZEUS23  F11B$c[000000]QUOTA.SYS;1
80817250       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]STRINGS.C;7
80821750       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]WATCH.OBJ;5
808017d0       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]WATCH.EXE;12
8080a830       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]LKSTAT.EXE;5
8082baf0       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]LKSTAT.DMP;1
8081de40       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]SETUP.COM;11
8081fb20       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]LKSTAT.DMP;2
807fed30       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]TAR.C;16
8081a530       0 NL   1 K    0 ZEUS23 
F11B$s[USERS.BNEBGA.TMP]LKSTAT_README.TPU$JOURNAL;1
80832370       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]LKSTAT.README;1
80806840       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]TAP.C;1
80815af0       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]STRINGS.OBJ;6
8080d900       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]WC.EXE;8
80821070       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]PS.DIR;1
808248d0       0 NL   1 K    0 ZEUS23  F11B$s[USERS]BNEBGA.DIR;1
80833a20       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA]COM.DIR;1
80815780       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.COM]CD.COM;24
808047f0       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.COM]CLEAR.COM;1
8081ff40       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]TRACE.C;78
807fe230       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]TRACE.EXE;50
8081eb50       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA]X.;1
8080bee0       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA]SRC.DIR;1
8081a8a0       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]WHOIS.C;57
808137e0       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]SSTRACE.DIR;1
8082b6d0       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]REG.C;2
8082b4c0       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]UNIX2VMS.C;1
80821e30       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA]TMP.DIR;1
80824e50       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]TPIPE.C;6
80810190       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]TPIPE.EXE;7
8080a780       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]STRINGS.EXE;9
80831d40       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]XPRINTSCREEN.C;1
808326e0       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]STRINGS.C;4
808001d0       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]LKSTAT.C;7
808076b0       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]WATCH.C;14
8081d600       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]LKSTAT.H;2
80833290       0 NL   1 K    0 ZEUS23  F11B$s[USERS.BNEBGA.SRC]WC.C;8
8082ee80       7 EX   1 E    0        RMS$USERS       
[USERS.BNEBGA.A1MAIL$]MAIL.X4M;1
808152b0       0 NL   1 E    0         ....
80832b00       0 NL   1 E    0         ....
8081dfa0       2 EX   1 E    0        RMS$USERS       
[USERS.BNEBGA.DECW]DECW$CALENDAR_FILE.DWC;1
80819610       0 EX   1 E    0         ...."...
80806b00       0 NL   1 E    0         !...

reso mast root rmst  dir diro lock  lcl pcpy mcpy  sys proc chn
 699  232  392  131   63   46  993    0    0    0    0    0   9


The following is an extract from
$ lkstat -ls

rsb      fla sub cg lck lcl cpy mst sys prc gra cvt wai m grou node   name
8081f700       2 EX   1   1   0   0   1   0   1   0   0 E    0       
SYS$SYS_ID#10755
80833760 DO    0 NL   0   0   0   0   0   0   0   0   0 E    0 ZEUS23
SYS$SYS_ID#10763

reso mast root rmst  dir diro lock  lcl pcpy mcpy  sys proc chn
 683  215  391  130   62   46  960  157  423  380  762  198   8

Here we see the System ID Lock, which is a locally mastered, system owned lock
granted at EX mode. We are also serving as the directory entry node for another
resource; all we know about this resource is its name, the node that it is
mastered
on node ZEUS23, and that the local node has no interest in this resource.


Regards,
        Gary Nebbett (/pn=gary.nebbett/ou=chcgbs30/@ciba-geigy.ch)

