.PAGE SIZE 55, 70
.RIGHT MARGIN 70
.FIRST TITLE
.LAYOUT 2, 3
.TITLE How to Measure Terminal Usage on a VAX
.SUBTITLE B.#Z.#Lederman
.PARAGRAPH
I'm writing this in a hurry, so it may be a little crude. If I receive
questions or suggestions I'll try to answer them in the next release,
through DECUServe, CompuServe (tm), etc. I'm afraid I can't spare
much telephone time during the day.
.PARAGRAPH
The VMS System Accounting files contain (essentially) all of the
information you need to measure terminal usage. You do not need any
extra programs to poll lines, count logins, etc. It is, however,
helpful to have the files separated by day. To do this, I run a batch
procedure every night at midnight which re-names the System Accounting
(and PSI accounting) file. It also does automatic backup: I've
commented this out, but have left it (inactive) in the file so you can
see what is going on. I also have a file DAILY__START.COM which is
invoked by SYS$MANAGER:SYSTARTUP.COM, so that every time the system is
re-booted there is a check to see that the automatic backup procedure
is also started.
.PARAGRAPH
Next, it is necessary to convert the accounting file into something
readable. The files have data in a rather peculiar format which most
programming languages can't read directly: therefore, I have written
conversion programs which take care of the problem. The source is in
the library, which you have to assemble and link:
.BLANK
MACRO/OBJ ACC__CONVERT
.BREAK
LINK ACC__CONVERT
.BREAK
COPY ACC__CONVERT.EXT SYS$SYSTEM
.BLANK
If you don't want the image in SYS$SYSTEM you have to edit the file 
ACC__CONVERT.CLD to put in the new directory. You may also want to put 
the help file ACC__CONVERT.HLP in a system or other help library after 
you have read it.
.PARAGRAPH
To convert an accounting file, first define the new command.
.BLANK
SET COMMAND ACC__CONVERT
.BLANK
Then you can convert as many files as you want. I use file names like 
this:
.BLANK
ACC__CONVERT/OUT=ACCFIX.10SEP ACCOUNTING.10SEP
.BREAK
ACC__CONVERT/OUT=ACCFIX.11SEP ACCOUNTING.11SEP
.BREAK
ACC__CONVERT/OUT=ACCFIX.12SEP ACCOUNTING.12SEP
.BLANK
and so on.
.PARAGRAPH
The file MEASURE.DTR contains definitions for the accounting records,
and procedures to extract traffic data. You should set up a dictionary
where you will be using this stuff and say
.BLANK
@MEASURE
.BLANK
within Datatrieve to define what you will need. You will probably want
to set up a directory to hold the data files and reports, and be in
that directory when you invoke the procedures that calculate traffic
usage. Be certain that the file 
.BLANK
MOD.FDL
.BLANK
is in that directory, or is in a directory you can read as it is 
needed later. You may want to change the UIC of the owner as it is 
currently set to my UIC.
.PARAGRAPH
One of the Datatrieve definitions is for the accounting domain, which
looks like this:
.BLANK
DOMAIN ACC USING ACC__RECORD ON DSK7:[ACCOUNTING]ACCFIX.09SEP;
.BLANK
Obviously, you will want to change the disk and directory information,
and the name of the file for the proper date. You can, of course, use
one file name and always use that as the output of ACC__CONVERT, but I
like to keep the old files on hand for a while in case a new question
about system usage comes up. When you use a new file, enter a command
like:
.BLANK
REDEFINE DOMAIN ACC USING ACC__RECORD ON DSK7:[ACCOUNTING]ACCFIX.15SEP;
.BLANK
to change the file name.
.PARAGRAPH
The record definition for this domain contains a lot more information
than is needed just for traffic studies: you may want to take a look
at some of it. Two of them are UIC fields which use the function
FN$FAO to format the UIC into readable data (i.e., instead of a uic
like 200405030 you get [LEDERMAN] or [300,3]. This function does not
come with Datatrieve: it is a user-defined function. It, and many
other functions, are defined in the file 
.BLANK
DTRFND.MAR
.BLANK
which is ADDED to the file DTR$LIBRARY:DTRFND.MAR, and then Datatrieve
is re-linked. [This will be found in the [DTRSIG.FUNCTIONS]
directory.] Instructions are in the Datatrieve documentation and in
ADD__FUNCTION.TXT. If you can't add these functions you will have to
comment out the fields that use them by adding exclamation points at
the beginning of the line like this: 
.BLANK.NO JUSTIFY.NO FILL.TEST PAGE 10
!
! The next two fields require a user-defined function supplied
! on the DTR/4GL SIG Library Collection (also found on the VAX SIG
! Tapes.  It formats the binary UIC into meaningful information.
!
! 20 NUIC COMPUTED BY FN$FAO("!%I",DUIC,"","","","","","","")
!		    EDIT__STRING X(14).
! 20 OUIC COMPUTED BY FN$FAO("!%U",DUIC,"","","","","","","")
!		    EDIT__STRING X(9).
.BLANK.JUSTIFY.FILL
I highly recommend that you make an effort to include this function
as you can easily see how much more useful it is to get the UIC in the
form of [LEDERMAN] rather than a 10 digit decimal number.
.PARAGRAPH
There is a little more initialization which has to be done (once 
only). You have to go into Datatrieve and invoke the procedure
.BLANK
:INITIALIZE__MOD
.BLANK
to create a blank data file MOD.SEQ which is used to initialize a
calculation work domain MOD whenever you calculate traffic. MOD.SEQ
should be in the directory where you will be working. You may want to
protect this file to be read-only for everyone so it doesn't
accidentally get deleted. You can, of course, create a new one with
INITIALIZE__MOD anytime you want to, but it's a bit slow.
.PARAGRAPH
Assuming everything is set up right, and domain ACC points to the 
converted System Accounting data file for the day you want to measure, 
you calculate system usage by invoking the procedure
.BLANK
:FIRST__CALCULATE
.BLANK
which reads the accounting file and puts measurement data into an
intermediate file. There are two things you need to know about this
procedure. First, is uses the Datatrieve function FN$DCL to send out a
DCL command line to create a new empty work file. This function IS
supplied with Datatrieve, but some paranoid system managers take it
out. If your system doesn't have it, you will have to modify a portion
of FIRST__CALCULATE so it looks like this:
.BLANK.NO JUSTIFY.NO FILL.TEST PAGE 15
!
! We have to clear out any old data: this can be slow.
!
READY MOD MODIFY
FOR MOD MODIFY USING BEGIN
    TIME__BUSY = 0
    NUMBER__BUSY = 0
END
!
! If FN$DCL is available, there is a much faster way to create an empty file.
!
!FN$DCL("CONVERT/FDL=MOD MOD.SEQ MOD.DOM")
!FN$DCL("PURGE/NOLOG MOD.DOM")
!READY MOD MODIFY
.BLANK.JUSTIFY.FILL
This will be significantly slower than if FN$DCL is available.
.PARAGRAPH
Next, you have to select the records you want. You could measure all 
Interactive sessions by selecting that packet type, but I have set up 
the procedure to select those sessions that got a "real" terminal: 
this means an Interactive session which did NOT come in over DECnet on 
an RTAnn: type device. On my system, virtual terminals are enabled to 
protect against modem disconnects, and this is true on many other
systems as well, so the procedure should be correct. It presently looks 
like this:
.BLANK.NO JUSTIFY.NO FILL.TEST PAGE 6
! Read the accounting data (use only those records that are relevant:
!   in this case, only "real" terminals, not DECnet remote terminals,
!   and not Batch jobs, etc.
!
FOR ACC WITH TERMINAL STARTING "VT" BEGIN
.BLANK.JUSTIFY.FILL
so it picks up all sessions with devices VTAnn:, etc. You can modify 
this as you need: for example, if you don't have virtual terminals you 
may want to look for terminals starting with "TX", or "T".
.PARAGRAPH
Once this procedure is run, the domain MOD (which stands for Minute Of 
Day as there is one record per minute) has all the data you need for 
an Erlang traffic calculation. You can get a report with the 
procedure
.BLANK
:MOD__ERLANG__REPORT
.BLANK
which prints out the Erlangs of traffic for each clock hour. The 
traffic paper should tell you what to do with this.
.PARAGRAPH
I will be working to improve the detail of analysis of this procedure: 
however, I can tell you from many years experience that you will find 
the traffic data obtained by this method to be within a few percent of 
the correct values. For an initial evaluation of the number of 
communications lines attached to the system it is as accurate as 
anything you will ever need.
.PARAGRAPH
I have noticed one (and only one) deficiency in the information 
recorded by System Accounting, and that is that with virtual terminals 
enabled you no longer have the physical terminal name anywhere. This 
means that if you have two sets of terminals coming in (for example, 
one for users and one for moderators) you can't separate them. I have 
SPRed this deficiency, and don't know when a work-around will be 
available. If, however, you can separate the access in some other
way (for example, the Group number in the UIC is different for 
different classes of users, or the Account field is different, etc.),
then you can use one of the other fields in the accounting record to
select the traffic to be measured.
.PARAGRAPH
Finally, you will notice a few extra definitions sitting around which 
contain the letters PSI: these are obviously for processing Packet
Switching network Interface information. You will find them useful 
should the system ever be connected directly or through PSI Access to a 
packet network.