Trailing-Edge
-
PDP-10 Archives
-
decuslib20-06
-
decus/20-158/acct20-user.lpt
There are no other files named acct20-user.lpt in the archive.
ACCT20
DECSYSTEM-20 RESOURCE-USAGE
ACCOUNTING PROGRAM
Version 2.0
USER MANUAL
WRITTEN BY
DAVID TODD
DIRECTOR OF UNIVERSITY COMPUTING
WESLEYAN UNIVERSITY
MIDDLETOWN, CT 06457
1 MAY 1988
Overview ACCT20 User Manual Page 1
Overview
ACCT20 analyzes the TOPS-20 SYSTEM-DATA.BIN files that
contain audit trails of DECSYSTEM-20 usage and produces summary
or detailed reports of usage statistics. The reports that may be
generated include a general summary of use by each directory or
account, a detailed report of all use by a specific directory or
account, a report of usage of printer forms, a report of usage by
category of directory or account, and a list of billable users.
The program is designed primarily to serve as an
end-of-month summary and limited billing program. It is not
designed to efficiently generate bills for every user. Rather,
the underlying philosophy of its development is that only
summaries are needed for most users and that detailed account
trails are needed for only a few users.
The program is designed to provide great flexibility in the
types of charges, rates charged, and types of reports generated.
In order to avoid the need for lengthy command sequences to
generate basic usage reports, most commands assume defaults for
values or source filenames. Report formats are rigidly defined,
which some users might find a disadvantage, but the emphasis in
developing the program was to provide an efficient method for
generating the desired reports at (possibly) the expense of some
generality in the way the information is processed.
ACCT20 reads in charge rates for use of various resources
from user-specified data files. Resources include CPU and
terminal connect time, disk storage allocations and quotas,
printer pages (both NORMAL and special forms), cards read, and
plotter use. ACCT20 permits use of different rates for CPU and
terminal time charges for different shifts of the day (defined by
the administrator) and different charges for internal vs.
external users.
The summary reports generated may be based upon either
directory name or account string. The summary listings include
summaries at each level of the tree-structured directory (or
account-string). For example, usage under CHEM, CHEM.J-JONES,
and CHEM.S-SMITH is summarized under each individual name.
Summary information may be also analyzed according to a
categorization scheme. For example, it may be desirable to
categorize all use under academic accounts under a heading
ACADEMIC, all use under administrative accounts under a heading
Overview ACCT20 User Manual Page 2
ADMINISTRATIVE, and all use under system administration accounts
under the heading SYSTEM. This can be done by creating a file
which contains the categorizations desired and using the
CATEGORIZE command.
Version 2 Release NotesACCT20 User Manual Page 3
Version 2 Release Notes
Version 2 fixes a number of bugs that were reported in
Version 1, implements several new commands (LIST-CATEGORY-TOTALS,
LIST-SUMMARY-TOTALS, and REPROCESS), and includes a new
tree-management system (using height-balanced trees -- see the
program logic manual). The new features were needed for the
routine use we made of ACCT20 here for analyzing computer use,
and they are likely to be valuable for others, too.
This version has been in use at Wesleyan for about four
years (sorry, I just couldn't get around to documenting and
redistributing the system). The following bugs are still known:
- When processing tables from data files (e.g.,
CATEGORIZE), the internal command buffer may overflow.
See the ACCT20 Program Logic Manual for a patch
suggested by Rob Austein to fix this bug.
- Recovery from errors found while processing data files
is still poor.
One minor change in Version 2 is that I converted
documentation to SCRIBE, hence the .MSS files on the tape. I
processed the .MSS file into a .LPT file (printable on a standard
line printer) and a .PS file (printable on a PostScript printer)
for those without SCRIBE licenses.
Unfortunately, I have no time to continue working on the
program (as much fun as it was!), and the only DEC-20 left at
Wesleyan is being phased out. As I have forgotten many of the
details of implementation of ACCT20, I cannot offer to support
it. However, I do invite anyone with improvements or bug fixes
to submit revisions to the DECUS Library, which remains the
repository for the code.
Use ACCT20 User Manual Page 4
Use
ACCT20 runs in native TOPS-20 mode, and command-recognition
features are used heavily. Most commands simply establish
processing conditions or select files which establish charge
rates, etc. Commands that use filenames also have default
filenames so that lengthy command strings are avoided. Two
commands, the PROCESS and REPROCESS commands, actually causes
processing of the system data files from <ACCOUNTS>.
The normal sequence of commands to use ACCT20 on a monthly
basis might be:
- Use the NAME command to establish a name prefix for the
data files used and generated (of the form "MONYY").
- Use the CHARGE command to indicate that some users will
be billed and to give the name of the file that
identifies those users.
- Use the CATEGORIZE command to read a file describing
the categories to which departments or individual usres
should be assigned and to ask that a listing of use by
those categories be generated.
- Use the PRINTER-CHARGES command to establish charge
rates for special forms.
- Use the FORMS command to request a text-file dump of
use of special forms (for other possible analyses by
other programs).
- Use the DUMP command to request a dump of the summary
information as a binary file that can be subsequently
reprocessed -- with other binary summary files for a
year-to-date summary, for example.
- Use the WRITE command to request that the detailed
accounting entries for the billable users be dumped, in
binary, for a subsequent billing run.
- Use the STATISTICS to request a summary of the number
of different types of records processed.
- Use the LIST-CATEGORIES and LIST-SUMMARY commands to
request text-file listings of the category and summary
reports in a format suitable for use with a database
system.
- Use the PROCESS command to initiate processing of the
Use ACCT20 User Manual Page 5
binary accounting files and subsequently generate
requested reports.
- EXIT to close files and exit from ACCT20.
Interactive use is not required, and batch operation may be
preferred. The files which establish rate and categorizations
may be created, then the monthly accounting can be run with a
standard batch control file (usually edited to indicate the month
of the accounting). The file MONTHLY.CTL that is distributed
with the ACCT20 package can serve as a prototype for other users'
batch files to generate summary information. The file BILLER.CTL
can serve as a prototype for other users' batch files to generate
bills for billable users identified in the MONTHLY batch file
run.
ACCT20 is intended to operate with the CLSACT program, also
distributed with the ACCT20 package, which closes the
SYSTEM-DATA.BIN file each day and renames it to a name of the
form 'ddmonyy.BIN', which records the day on which the file was
closed. The processing of this sequence of files by ACCT20 for a
month can be commanded by using a wildcard filename construction,
'*monyy', in the PROCESS command which causes the system data
files to be processed, or by defining a default filename prefix
'monyy' through the NAME command and permitting ACCT20 to use
this default name in the PROCESS command. If the latter method
is used, many of the report files generated will also bear the
name prefix 'monyy', which is helpful on listing banner pages and
on directory listings.
A description of the use of ACCT20 necessarily involves a
description of both the commands ACCT20 takes and the files and
file formats it expects to use, since in most cases its actions
are driven by data files. The following two sections describe
the commands first, then the input and output files.
ACCT20 Commands ACCT20 User Manual Page 6
ACCT20 Commands
The following commands are available in ACCT20. These
descriptions are in the form seen by the interactive user with
command recognition. The items in "()" are guide phrases; the
items in "<>" are to be supplied by the user.
BEGIN (with starting date/time) <date-time>
Sets the starting date/time for records to be
accepted for processing.
CATEGORIZE (using file) <filename>
Use the specified file to determine how the
directories or accounts processed are to be
categorized under broad headings in the
categorized summary report. Default name is
ACCT20.CAT. TTY: is a valid <filename> specifier;
command recognition is in effect at this
subcommand level, too.
CHARGE-RATES (from file) <filename>
Use the specified file to establish charge rates
for various resources. Default name is
ACCT20.CHG. If this command isn't given, or
resources are not specifically given in the CHG
file, the default rate values are taken from the
charge rates predefined in the ACCT20 program
(users beware!). TTY: is a valid <filename>
specifier; command recognition is in effect at
this subcommand level, too.
DEBUG This option enables output of certain detailed
information in cases when errors occur. To get
maximum benefit, the DEBUG assembly switch should
also be set in the MACRO code.
DETAIL (use of resources) <resource> (by user) <username>
This causes the PROCESS command to generate a
report of all entries in the system data files
for the specified user. The <resource> field can
be one of the following:
CPU-USE
ACCT20 Commands ACCT20 User Manual Page 7
DISK-USE
INPUT-SPOOLER
NONE
OUTPUT-SPOOLERS
SYSTEM-USE
TAPE-USE
TTY-USE
SYSTEM-USE includes all entry types; TTY-USE and
CPU-USE include just session records; the others
are self explanatory. The <resource> field is
required. The <username> field is either the
directory name or the account name of the user(s)
(this choice is selected by the REPORT command)
for whom detailed listings are desired. Wildcards
function in this field. If omitted, the
<username> field defaults to '*' (list usage for
all users). The output file name defaults to
<username>.LPT or to ACCT20.LPT if the <username>
field is omitted. See DETAILS file description
below for information about the output file
contents.
DUMP (binary summary to file) <filename>
This causes the internal summary database to be
dumped to the specified file in binary form,
sorted by directory/account name. The default
name for the output file is ACCT20-SUMMARY.BIN
or, if the NAMES command was given before the
DUMP command, the name defaults to
<periodname>-SUMMARY.BIN. The binary file can be
used to provide annual summary information
through the use of the REPROCESS command.
Developers should see the structure of the
internal summary tree nodes and the output
routines in the section titled 'DUMP Command
Processing' of ACCT20.MAC if they wish to use
this file.
ACCT20 Commands ACCT20 User Manual Page 8
END (at starting date/time) <date-time>
Process no entries with date-time stamps later
than the <date-time> specified.
EXIT Exits from ACCT20. This is required for normal
processing termination! The PROCESS command does
not close certain report files after the end of
the last input file under the presumption that
the user may wish to process more than one set of
commands into the same output file. A
CNTL-C-exit from ACCT20 will lose some report
files.
FORMS <usage to be generated>
This requests that all printer output spooler
entries from the input system data files be
listed to an output file in ASCII format for
possible subsequent processing by other programs.
The default name is ACCT20-FORMS.DMI unless the
NAME command was given before the FORMS command,
in which case the name defaults to
<periodname>-FORMS.DMI. The output format is
satisfactory for use with a database system, and
a SYSTEM 1022 database description file included
in the ACCT20 package, FORMS.DMD, can be used to
load the file generated into a database. The
procedures for using the FORMUS.DMC and
FORMTY.DMC report generators are given in the
MONTHLY.CTL batch control file and can be used to
generate year-to-date forms usage reports by
username and by form type. See FORMS OUTPUT FILE
description below for more information on the
contents of this file.
HELP This simply lists the commands with a brief
description of each.
LIST-CATEGORY-TOTAL (to file) <filename>
This lists the category totals to a text file in
a format suitable for loading and processing by a
database system (no page headers!).
LIST-SUMMARY-TOTAL (to file) <filename>
This lists the summary totals to a text file in a
format suitable for loading and processing by a
database system (no page headers!).
ACCT20 Commands ACCT20 User Manual Page 9
NAME (default for file is) <periodname>
This command establishes a default prefix name,
<periodname>, for the files to be processed by
the PROCESS command and for files subsequently
generated by other report-generating commands.
In normal use with the CLSACT program (run with
the daily system backups), the <periodname> field
will have a form such as 'monyy', where 'mon' is
the month of the system data files to be process
and 'yy' is the year of those files, e.g,. AUG81.
The PROCESS command then attempts to process
files <ACCOUNTS>*AUG81.BIN, for example, unless
the filename is explicitly given on the PROCESS
command, and the AUG81 prefix is used for report
files generated, e.g., AUG81-SUMMARY.LST.
NO-MTA-DETAILS Various bugs in the TOPS-20 MOUNTR code cause it
to generate incorrect entries in the system data
files (primarily manifested as using an incorrect
username (directory/account) on a tape usage
record). This seems to now have been corrected by
various SPR's. This switch does not list under
the command-recognition features, but it is
intended to be used if magtape records appear to
be incorrect and it is desired not to bill any
users for magtape usage.
PRINTER-CHARGES (from file) <filename>
This command prepares ACCT20 to account for use
of special printer forms at rates other than the
rate for NORMAL forms (which is specified in the
CHARGES command). Default filename is
ACCT20.PCG. See the description of
PRINTER-CHARGES file for more information.
PROCESS (from file (sequence)) <filename>
This causes the system data files to be processed
and the reports to be generated. Default
filename is SYSTEM-DATA.BIN unless the NAME
command was previously given, in which case the
default filename is '*<periodname>.BIN'.
Wildcards can be used if the filename is
specified. The PROCESS command does not close
certain report files so that the user may PROCESS
more than one set of files or PROCESS one set of
files with several processing conditions into
just one set of output reports. Be sure to use
the EXIT or RESET command for normal termination
of processing.
ACCT20 Commands ACCT20 User Manual Page 10
REPORT (by) <ACCOUNT or DIRECTORY>
Commands ACCT20 to perform its accounting
summaries by matching on account string or on
directory name. Default is DIRECTORY if the
command is not given at all.
REPROCESS (from binary summary file named) <filename>
This processes a summary file into a new internal
summary table, perhaps to be concatenated with
other summary files as in a year-to-date summary,
and also permits a recategorization of usage if
the CATEGORIZE command had been issued before
REPROCESS.
RESET This command closes all open files and resets all
internal tables to zero. Subsequent processing
must again provide charge rates, categorization
schemes, etc., and statistics from prior
processing of system data files are deleted from
internal tables. This command is primarily used
in generation of bills for multiple users with a
single run of ACCT20.
STATISTICS This command is a toggle which requests that
statistics on the performance of ACCT20 be typed
to the user at the end of a PROCESS command.
Statistics provided currently include the number
of different types of entries processed and the
time required to process all entries.
SUMMARIZE (use of resources) <resource> (by) <username>
This commands ACCT20 to generate a summary report
of all use of the specified resources by the
users defined by the <username> string. The
options for the <resources> field are given in
the DETAILS command description. The <username>
field may contain wildcards. It defaults to '*'.
The default filename of the report file is
ACCT20-SUMMARY.LST unless the NAME command was
previously given, in which case the default name
is <periodname>-SUMMARY.LST. See the description
of SUMMARY file for information about the
contents of this file.
WRITE-DETAIL-BINARY (to file) <filename>
This commands ACCT20 to copy to the DETAIL.BIN
file all records in the system data files which
ACCT20 Commands ACCT20 User Manual Page 11
were generated by billable users. The <username>
of billable customers is established in the
CHARGES file. The DETAIL.BIN output file can be
used in subsequent PROCESS commands to generate
DETAIL listings of use by each of the billable
customers, and the reduced size of the DETAIL.BIN
file makes this billing process much less
expensive and time-consuming. The default
filename for the DETAIL.BIN file is
ACCT20-DETAILS.BIN unless the NAME command
specified a <periodname> prefix, in which case
the default filename is <periodname>-DETAILS.BIN.
The file contents are in exactly the same format
as the SYSTEM-DATA.BIN files.
ACCT20 Files ACCT20 User Manual Page 12
ACCT20 Files
There may be many different files involved in a run of
ACCT20. The following summary may help avoid confusion about
their purposes:
SYSTEM-DATA.BIN This file is the one produced by the system with
usage statistics recorded in it. It is the file
into which entries are made by the USAGE JSYS,
and it is the file which is processed into an
ASCII USAGE file by the DEC CHKPNT program.
ACCT20 uses this file directly and does not
process USAGE files and does not require the
CHKPNT program. The CLSACT program supplied with
the ACCT20 package can be used to close the
<ACCOUNTS>SYSTEM-DATA.BIN file each day and
rename it to a file with a name of the form
"nnmonyy.BIN" so that daily binary files can be
kept separately if desired. In this case, there
will be a series of SYSTEM-DATA.BIN files which
must be processed together, and ACCT20 will
accept wildcard filenames for the SYSTEM-DATA.BIN
file to be processed.
CHARGES file Charges for resources may be typed in at the
terminal during a run of ACCT20 or may be entered
in advance into a charges file. The resources for
which ACCT20 is prepared to charge are described
in the following format, used by the ACCT20
CHARGES command processor:
Bill (user) <username> [COMMERCIAL or NON-PROFIT]
Cards-read (is $) <cost in $/card>
Connect-time (is $) <charge> [/HR or /MIN or
/SEC]
Core-occupancy [not supported by DEC]
CPU-time (is $) <charge> [/HR or /MIN or /SEC]
Disk-allocation (in pages/month is $) <charge>
ACCT20 Files ACCT20 User Manual Page 13
Disk-reads (not supported by DEC)
Disk-storage (in pages/month is $) <charge>
Disk-writes (not supported by DEC)
Printer-pages (for printed pages is $) <charge>
Shift (starts at) <time> (and is billed at base
rate times) <ratio>
Structure-mounts (for structure mounts requiring
operator attention is $) <charge>
Structure-usage (for use of operator-mounted
structures is $) <charge> [/HR or
/MIN or /SEC]
Tape-mounts (for tape mounts is $) <charge>
Tape-usage (for tape use is $) <charge> [/HR or
/MIN or /SEC]
Tax (commercial users at percentage rate)
<percentage tax rate> TTY-
characters-in (not supported by
DEC)
TTY-characters-out (not supported by DEC)
Weekend (rates for commercial users is base rate
times) <ratio>
Charges for any or all of these resources may be
set by input from the terminal or from the
CHARGES input file. An example of the file is
included with the ACCT20 package as ACCT20.CHG.
The CHARGES file must end with the command
END-CHARGES; interactive input uses command
prompting. Default values of the charge rates
ACCT20 Files ACCT20 User Manual Page 14
are embedded in the ACCT20.MAC file and may be
changed if a firm rate structure is to be used
for extended periods of time.
The charges file has a default name ACCT20.CHG.
If the CHARGES command is given to ACCT20 but no
file is specified, that file is used as the
source of resource charge information.
Printer charges It is possible to charge different rates for
different types of special forms. The
"PRINTER-PAGES" charge rate associated with the
CHARGES command establishes the rate only for
NORMAL forms. Rates for any special forms are
established by the PRINTER-CHARGES command, which
will accept printer charges from either the
terminal or an input file. The default name of
the file used for PRINTER-CHARGES is ACCT20.PCG.
The entries in the file are of the form formname
price, where the formname must be no more than 6
characters long and the price is in units of
dollars per page, where a page is defined by the
amount of physical medium between successive
top-of-form locations on the VFU associated with
the form. There is no prompting for optional
names for forms, since any form name can be used.
The file must be terminated by PRTEND. The
default filename is ACCT20.PCG; an example of
this file is included in the ACCT20 package.
Categorization file
This optional input file provides the
categorizations of the different users into broad
possible categories, e.g., CHEM* as ACADEMIC and
REGISTRAR* as ADMINISTRATIVE. Entries in the
file are of the form <username> <category
name>, where <username> is the directory or
account name string to be categorized and
<category name> is the name of the category under
which the usage by the specified <username> is to
be categorized. The <username> string may (and
usually will) contain wildcards so that it is
essentially the superior directory name for the
users to be categorized. Each <username> must
map into just one category; many <username>s may
map into a single category. The default file name
for the CATEGORIZE command is ACCT20.CAT; an
example of this file is included in the ACCT20
package. Note that the last entry of the file
must be END-CATEGORIES.
ACCT20 Files ACCT20 User Manual Page 15
DETAILS.BIN This optional output file is written by the first
pass of ACCT20 as it processes the
SYSTEM-DATA.BIN file if the WRITE-DETAIL-BINARY
command had been given. This file contains the
entries of the SYSTEM-DATA.BIN file with
directory names or account strings which match
entries in the BILL subcommand of the CHARGE
command. This file can be read on the second pass
of ACCT20 to generate the detailed listings of
usage.
Details user-name file (ACCT20-BILLED-USERS.TMP)
This file lists the directory or account strings
for which detailed entries in the DETAILS.BIN
binary file were written. This file is written
as a result of the WRITE-DETAIL-BINARY command.
The default filename is ACCT20-BILLED-USERS.TMP,
unless the NAME command was used to specify a
<periodname>, in which case the filename is
<periodname>-BILLED-USERS.TMP.
DETAILS listing files
These output files contain the detailed listings
of usage by directories or accounts selected with
the DETAIL command. The listings include
date/time stamp, username, and a record of the
activity generated by the user(s) specified in
the DETAIL command.
LIST files These files are text files without page headers,
in fixed-field format, suitable for use with a
database system. The information is the same as
that of the SUMMARY and CATEGORIES output files,
but without headers.
SUMMARY listing file
This file contains a summary of use of the system
by all users selected by the <username> field of
the SUMMARIZE command. The summary listings are
given in alphabetical order and contain the
username, summary of timesharing and batch
computer use, printer and plotter output spooler
use, card reader input spooler use, disk use,
tape use, and total value of services rendered.
A grand total is given at the end of the listing.
ACCT20 User Manual Page i
Table of Contents
Overview 1
Version 2 Release Notes 3
Use 4
ACCT20 Commands 6
ACCT20 Files 12