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.


                   DECSYSTEM-20 RESOURCE-USAGE
                       ACCOUNTING PROGRAM

                           Version 2.0

                           USER MANUAL

                           WRITTEN BY
                           DAVID TODD
                       WESLEYAN UNIVERSITY
                      MIDDLETOWN, CT  06457
                           1 MAY 1988
Overview               ACCT20 User Manual                  Page 1


     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
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


     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

   - 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

     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:  

ACCT20 Commands        ACCT20 User Manual                  Page 7








                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

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

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

                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

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

                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

                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

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

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