Copyright 1989-2016 by Kevin G. Barkes

All rights reserved. This article may be duplicated or
redistributed provided no alterations of any kind are
made to this file.

This edition of DCL Dialogue is sponsored by Networking
Dynamics, developers and marketers of productivity software
for OpenVMS systems. Contact our website
www.networkingdynamics.com to download free demos of
our software and see how you will save time, money and
raise productivity! Be sure to mention DCL Dialogue!


DCL DIALOGUE

Originally published September, 1989

By Kevin G. Barkes


Raiders of the Global Symbols


While DCL can return a wealth of system data through calls
to its lexical functions, some information cannot be easily
obtained by such straightforward methods.

Sometimes it would be convenient to be able to look directly
at a specific location in the VAX's memory and perform the
DCL equivalent of BASIC's PEEK command. Fortunately, DCL
does provide this capability, through the EXAMINE command
and the F$FAO lexical function.

The tricks are knowing where to look in memory to obtain
this data and how to extract it in a usable form.


RAND-McNALLY ala VMS

Unless you inadvertently deleted it in a space-saving
crusade, the SYS$SYSTEM directory on your VAX should contain
a rather large file named SYS.MAP.

When the VMS system image is linked, the virtual addresses
of each global symbol in SYS.OBJ is written to SYS.MAP. In
addition to a listing of addresses, the file also contains
cross-references to all entities which set up or reference
each global symbol.

If you're not a VMS internals guru, looking at SYS.MAP can
be a frustrating experience. Some symbol names are fairly
familiar; others are indecipherable.

There are "Rosetta Stones" available to translate these
hieroglyphics. Perhaps the best is "Version 4.4, VAX/VMS
Internals and Data Structures" and its Version 5.0 addendum,
available from Digital Press. These rather hefty tomes
provide keen insight into the operation of VMS, and also
have a rather extensive listing of SYS.MAP's global symbols
and their meanings.

A somewhat more approachable introduction to VMS innards is
currently appearing in the DEC Pro's sister magazine, the
VAX Professional. "The Hitchhiker's Guide to VMS", a
recently-initiated series written by internals wizard Bruce
Ellis, provides a user-friendly overture to VMS' dark
secrets.

IN ENGLISH, PLEASE

Let's say you're writing a system management-related command
procedure and you need to know the amount of available
memory on the free page list.

You could direct the output of the SHOW MEMORY command to a
disk file, read it back in, and extract the required value. 
You prefer to directly extract the information from memory.

By studying SYS.MAP and the VMS internals book, you discover
the global symbol SCH$GL_FREECNT contains this information. 
SYS.MAP shows the address of the symbol to be %X80004018. 
(Note: This is for VMS Version 5.1-1; addresses vary for
different versions of the operating system.)

You issue the command:

$ EXAMINE/DECIMAL %X80004018

and the system responds with

80004018:  0000004535

The /DECIMAL qualifier to EXAMINE converts the contents of
the memory location to a decimal value, which shows there
are 4,535 pages of memory on the free page list.

Great, but we can't get the value from EXAMINE directly into
the procedure command stream.

While not documented in the DCL Dictionary, the F$FAO
lexical function can also examine memory locations using the
!AD directive. (For full information about $FAO's
capabilities, look in the System Services documentation.)

So, we enter:

$ WRITE SYS$OUTPUT F$FAO("!AD",4,%X80004018)

and the VAX responds with unintelligible gibberish.

The problem is F$FAO returned the value as a string not
precisely within the bounds of the ASCII character set.

Consider the following:

$ TEST[0,4] = 65
$ WRITE SYS$OUTPUT TEST
A

Here we've placed the value 65 into the symbol TEST. When
we write out the symbol, we get the upper case letter A,
which is ASCII code 65 decimal.

Obviously, we need to do more conversion. This is easily
performed with the F$CVUI lexical function, which extracts
bit fields from character string data and converts the
extracted value into an unsigned integer.

When we try our simple example, we get:

$ WRITE SYS$OUTPUT F$CVUI(0,16,TEST)
65

And when we plug in the "peek" from SCH$GL_FREECNT,

$ WRITE SYS$OUTPUT -
F$CVUI(0,16,-
F$FAO("!AD",4,%X80004018))
4535

A few caveats are in order. Remember the size of the free
page list varies constantly. When you look at it using the
lexical call, then compare it with a SHOW MEMORY command,
the values will be different because your process is running
the SHOW program which, of course, uses more memory than the
lexical call. And unless you have your VAX all to yourself,
other processes will also continuously affect memory
utilization.

If you include these "peeks" in your command files, be aware
that changes in VMS versions result in shifts in the
addresses of the global symbols. When you install a new
version of the operating system, you may have to update all
the command files containing global symbol references.

And when you send your buddy on 4.7 a tape of your nifty
procedure written under 5.whatever, he's going to seriously
doubt your sanity.

Table 1 contains a few interesting symbols which are
especially useful in writing system management-oriented
procedures. The values of virtually all SYSGEN parameters
are accessible in this manner and their use is limited only
by the procedure writer's imagination.

Rummaging through SYS.MAP and the internals book can be
quite entertaining, and finding symbols with a useful DCL
application particularly rewarding. Grab your Stetson, whip,
and do some exciting VMS archaeology.

---------------
TABLE 1.

                     VMS 5.1-1
SYMBOL                 Address       Description

SYS$GW_BJOBCNT       %X800044C4     Current number of batch jobs.
SYS$GW_BJOBLIM       %X800082E0     (SYSGEN) Batch job limit.
SYS$GW_IJOBCNT       %X800044C0     Current number of interactive 
SYS$GW_IJOBLIM       %X800082DE     (SYSGEN) Interactive user limit.
SYS$GW_NJOBCNT       %X800044C2     Current number of network jobs.
SYS$GW_NJOBLIM       %X800082E2     (SYSGEN) Network job limit.
SCH$GL_FREECNT       %X80004018     Current number of free pages.

Examples of information available by direct memory examination.
-------------


----------

Kevin G. Barkes is an independent consultant. He publishes
the KGB Report newsletter, operates the www.kgbreport.com website,
lurks on comp.os.vms, and can be reached at kgbarkes@gmail.com.