ACCT20 ACCT20 ACCT20 DECSYSTEM-20 RESOURCE-USAGE DECSYSTEM-20 RESOURCE-USAGE DECSYSTEM-20 RESOURCE-USAGE ACCOUNTING PROGRAM ACCOUNTING PROGRAM ACCOUNTING PROGRAM _______ _ _ _______ _ _ _______ _ _ Version 2.0 Version 2.0 Version 2.0 USER MANUAL USER MANUAL USER MANUAL WRITTEN BY WRITTEN BY WRITTEN BY DAVID TODD DAVID TODD DAVID TODD DIRECTOR OF UNIVERSITY COMPUTING DIRECTOR OF UNIVERSITY COMPUTING DIRECTOR OF UNIVERSITY COMPUTING WESLEYAN UNIVERSITY WESLEYAN UNIVERSITY WESLEYAN UNIVERSITY MIDDLETOWN, CT 06457 MIDDLETOWN, CT 06457 MIDDLETOWN, CT 06457 1 MAY 1988 1 MAY 1988 1 MAY 1988 Overview ACCT20 User Manual Page 1 Overview ACCT20 User Manual Page 1 Overview ACCT20 User Manual Page 1 Overview Overview 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 Overview ACCT20 User Manual Page 2 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 NotesACCT20 User Manual Page 3 Version 2 Release NotesACCT20 User Manual Page 3 Version 2 Release Notes Version 2 Release Notes 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 User Manual Page 4 Use ACCT20 User Manual Page 4 Use Use 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 . 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 Use ACCT20 User Manual Page 5 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 ACCT20 User Manual Page 6 ACCT20 Commands ACCT20 User Manual Page 6 ACCT20 Commands ACCT20 Commands 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) Sets the starting date/time for records to be accepted for processing. CATEGORIZE (using file) 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 specifier; command recognition is in effect at this subcommand level, too. CHARGE-RATES (from file) 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 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) (by user) This causes the PROCESS command to generate a report of all entries in the system data files for the specified user. The field can be one of the following: CPU-USE ACCT20 Commands ACCT20 User Manual Page 7 ACCT20 Commands ACCT20 User Manual Page 7 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 field is required. The 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 field defaults to '*' (list usage for all users). The output file name defaults to ________ ________ .LPT or to ACCT20.LPT if the field is omitted. See DETAILS file description below for information about the output file contents. DUMP (binary summary to file) 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 __________ -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 ACCT20 Commands ACCT20 User Manual Page 8 ACCT20 Commands ACCT20 User Manual Page 8 END (at starting date/time) Process no entries with date-time stamps later than the 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 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 __________ -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) 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) 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 ACCT20 Commands ACCT20 User Manual Page 9 ACCT20 Commands ACCT20 User Manual Page 9 NAME (default for file is) This command establishes a default prefix name, , 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 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 *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) 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)) 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 '*.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 ACCT20 Commands ACCT20 User Manual Page 10 ACCT20 Commands ACCT20 User Manual Page 10 REPORT (by) 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) 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) (by) This commands ACCT20 to generate a summary report of all use of the specified resources by the ________ users defined by the string. The _________ options for the field are given in ________ the DETAILS command description. The 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 -SUMMARY.LST. See the description of SUMMARY file for information about the contents of this file. WRITE-DETAIL-BINARY (to file) 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 ACCT20 Commands ACCT20 User Manual Page 11 ACCT20 Commands ACCT20 User Manual Page 11 ________ were generated by billable users. The 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 prefix, in which case __________ the default filename is -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 ACCT20 User Manual Page 12 ACCT20 Files ACCT20 User Manual Page 12 ACCT20 Files ACCT20 Files 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 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) [COMMERCIAL or NON-PROFIT] Cards-read (is $) Connect-time (is $) [/HR or /MIN or /SEC] Core-occupancy [not supported by DEC] CPU-time (is $) [/HR or /MIN or /SEC] Disk-allocation (in pages/month is $) ACCT20 Files ACCT20 User Manual Page 13 ACCT20 Files ACCT20 User Manual Page 13 ACCT20 Files ACCT20 User Manual Page 13 Disk-reads (not supported by DEC) Disk-storage (in pages/month is $) Disk-writes (not supported by DEC) Printer-pages (for printed pages is $) Shift (starts at)