Trailing-Edge
-
PDP-10 Archives
-
bb-x130a-sb
-
fact.mem
There are 4 other files named fact.mem in the archive. Click here to see a list.
SPECIFICATION
FACT
A BRIEF DESCRIPTION OF THE CONTENTS OF
FACT.SYS, THE ACCOUNTING SYSTEM RECORDS
FILE.
Date: 13-Dec-72
File: FACT.RNO
Edition: 1
The information in this document is subject to change without notice
and should not be construed as a comitment by Digital Equipment
Corporation. Digital Equipment Corporation assumes no responsibility
for and errors that may appear in this document.
The software described in this document is furnished under a license
and may be used or copied only in accordance with the terms of such
license.
Digital Equipment Corporation assumes no responsibility for the use or
reliability of its software on equipment that is not supplied by
DIGITAL.
Copyright (C) 1972,1979 by Digital Equipment Corporation
The following are trademarks of Digital Equipment Corporation:
DIGITAL DECsystem-10 MASSBUS
DEC DECtape OMNIBUS
PDP DIBOL OS/8
DECUS EDUSYSTEM PHA
UNIBUS FLIP CHIP RSTS
COMPUTER LABS FOCAL RSX
COMTEX INDAC TYPESET-8
DDT LAB-8 TYPESET-10
DECCOMM DECsystem-20 TYPESET-11
FACT Page 2
1.0 INTRODUCTION
The file FACT.SYS and its auxilliaries FACT.X01, FACT.X02, ...,
FACT.X77 contain a transaction record of the activity on a
DECsystem-10 timesharing system. The fact files are written by a
variety of system programs when each user logs on or off the system,
runs batch jobs, uses the I/O spoolers, and at ten-minute intervals
throughout his use of the system.
1.1 Standard Information
Each entry includes an indication of why and when it was written, the
job number to which it refers, the terminal running the job, and the
project, programmer number of the user. In addition, many entries
contain additional information relevant to the particular conditions
under which they were written, such as the name of the program
running, or statistics on useage of sharable resources.
1.2 Use of Auxilliary Files
Ordinarily, all the information described in this document is output
to SYS:FACT.SYS, by appending new entries to the end of the existing
file, or by creating FACT.SYS if it does not exist. If, however,
FACT.SYS should be inaccessable because of LOOKUP or ENTER failures,
or because of being in a file-being-modified state for ten seconds,
each of the programs which writes FACT file information is set up to
give up on FACT.SYS, and start trying to write FACT.X01. If this
fails, FACT.X02 is tried, and so on, counting in octal, to FACT.X77.
If all 64 files are inaccessable, the message
ACCOUNTING SYSTEM FAILURE....
CALL THE OPERATOR.
is printed, and the entry is not written. Note that, because the
condition which makes a file inaccessable may be cleared, FACT.SYS
(for instance) may contain entries both before and after those in
FACT.X01. Programs which depend on chronological order in the FACT
files should merge the auxilliaries with FACT.SYS, sorting on date and
time, before processing.
1.3 Processing Procedures
Because each installation will have different needs for reporting and
sumarizing computing activity, DEC does not attempt to provide general
purpose programs for processing the FACT files. It does, however,
distribute two programs, MONEY and FACTPR which provide examples of
how reporting programs could be written. MONEY is a simple,
supported, reporting program, written in MACRO, whereas FACTPR is an
unsupported conversion program, suitable for use as a pre-processor to
FACT Page 3
a complex reporting system which might be written in COBOL.
2.0 DEC-DEFINED ENTRIES
A 9-bit byte in the first word of each entry identifies the type of
the entry. The values 0, 377, and 777 in this type code are reserved
as markers in the FACT files. Values from 1 to 376 are reserved for
definition by DEC, while 400 to 776 are for customer definition.
2.1 Basic Entry Format
The first three words of every entry are the same, as follows:
Word# Description
----- -----------
0 header -- 4 bytes, as follows:
0-8 type code, which identifies the reason for
writing the entry, and the format of the
entry. If the type code is even (bit 8=0),
the date/time word (2) is in old format, with
12-bit date, and 24-bit time in jiffies. If
the type code is odd (bit 8=1), the date/time
word is in new standard date time format, and
clock rate dependencies are not permitted in
time representations.
9-17 job number to which this entry refers.
Usually, but not always, the job which
created the entry.
18-29 terminal number (as in TTYnnn) to which the
job is attached. CTY is indicated by 7777,
and a detached job by 7776.
30-35 length of the entry in words, including this
header word. If an entry has only the basic
information, this byte is 3.
1 project-programmer number to which this entry refers.
2 date and time at which the entry was created, as
follows:
a. if header bit 8=0, old format:
0-11 date, in system 12-bit format.
12-35 time, in clock ticks since midnight.
b. if header bit 8=1, new format:
FACT Page 4
0-17 days since Nov. 17, 1858
18-35 time, as a fraction of a day
2.2 LOGIN (100), ATTACH (240)
When a user logs in, or attaches his terminal to a detached job, only
the basic information (as described in 2.1) is stored if he is
successful:
Terminal and job numbers
Project, programmer number
Date and time of day
If, however, the attempt is unsuccessful (e.g., he does not know the
password), then 20 is added to the type code, and the password he
tried is recorded as word 3. Further, if the failure is due to a
program's attempt to LOGIN an illegal job on a PTY under its control,
the project programmer number of that job is recorded as word 4.
LOGIN failures, therefore, are recorded as type 120, and ATTACH
failures as 260.
2.3 CHKPNT (200)
At ten-minute intervals throughout the operation of the system,
so-called CHECKPOINT information is recorded about each job in the
system. In systems which use DAEMON, it takes the CHECKPOINT at
intervals controlled by the CHKTIM assembly parameter. Other systems
may use the CHKPNT program to record the same information. In
addition to the basic information listed under 2.1, CHKPNT entries
consist of:
Word# Description
----- -----------
3 job's accumulated run time, in milliseconds.
4 job's integrated time-size product, in kilo-core-ticks.
5 total disk blocks read by and for the job.
6 total disk blocks written by and for the job.
7 name of the program in the low segment, in SIXBIT.
2.4 LOGOUT (140)
When a user logs off the system, the LOGOUT program records final
values of all the CHECKPOINT information (except program name) to
sumarize the job.
FACT Page 5
2.5 SPOOL (250)
Each time the spoolers complete a request, unless assembled with
FACTSW zero, they call DAEMON to write a FACT file entry. The job and
terminal numbers in the header word are those of the spooling program,
but the PPN is that of the user for whom the spool request was
performed. They record the following data in the FACT file, in
addition to the basic information:
Word# Description
----- -----------
3 three bytes:
0-11 queue name in SIXBIT
12-17 station number
18-35 APR serial number
4 runtime used by the spooler for this request, in
jiffies (clock ticks).
5 kilo-core-ticks used by the spooler for this request.
6 disk reads by the spooler for this request.
7 disk writes by the spooler for this request.
8 physical device name of the spooler output device.
9 sequence number of the spool request.
10 quantity of output in same units as output limits for
this queue (e.g., pages, feet, etc.).
2.6 SPACE (160)
When the operator runs the (unsupported) SPACE program to evaluate
disk utilization, he can ask it (with the /FACT switch) to record the
current figures in the FACT file for later use by a billing program.
This information includes, in addition to basic data, status of
various variables in the retrieval information block of the file
directory (UFD RIB) for each user on each file structure. The job and
terminal numbers in the header word refer to those of the SPACE
program, but the PPN is that of the UFD to which the entry refers.
The rest of the entry is:
Word# Description
----- -----------
3 file structure name, in SIXBIT, on which this UFD was
found.
4 UFD status word (.RBSTS) from the UFD RIB.
FACT Page 6
5 first come, first served quota (.RBQTF).
6 logged-out quota (.RBQTO).
7 reserved quota (.RBQTR).
8 blocks presently allocated to this user (.RBUSD).
9 blocks remaining available for first come, first served
allocation on this structure (.DCFCT).
10 one of the following three words, in SIXBIT:
OUT there are no jobs logged in under this ppn.
IN there is at least one job presently logged in
under this ppn.
RECOMP there are no jobs logged in, but the UFD
status word shows the logged-in bit set.
Allocation, therefore, needs to be recomputed
for this user. If the /BATCH switch was
specified, SPACE has submitted a dummy batch
job to force re-computation of allocation,
but this job has not completed when the entry
is written, so word 8 of the entry (.RBUSD)
may be incorrect.
2.7 Restart (370)
Whenever DAEMON is run (usually by the OPSER auto startup file), it
writes a basic entry, indicating that the system was reloaded, so the
processing program can reset itself, figuring that jobs not logged off
in the FACT file were running when the system crashed.
2.8 Shutdown (372)
Unimplemented, but intended to mark a scheduled system shutdown.
FACT Page 7
2.9 Hiatus (377)
Whenever the FACT file is updated, the routine which adds a new entry
checks the last word of the file (as indicated by the file length
returned by LOOKUP) for the end-of-file code (see below). If the
end-of-file indicator is not found, the routine backs up until it
finds a non-zero word or the beginning of the block. Hiatus codes are
then stored in the words backed over, to mark the spot where data may
have been lost.
2.10 End-of-file (777)
The last word in the FACT file should always be the end-of-file code.
2.11 New Entry Types
As development of DECsystem-10 software continues, it is likely that
DEC will add new entry types to the FACT files. Customer programs
which process the file, therefore, should be written to ignore, except
possibly for a warning message, new codes which appear in the file.
This will ensure upward compatability.
3.0 CUSTOMER-DEFINED ENTRIES
Entry types 400 through 776 are reserved for customer definition and
implementation. DEC recommends that the format of the basic
information words be followed in customer-defined entries. Two
mechanisms are available for customers writing FACT file entries. The
.FACT function of the DAEMON UUO is the easiest to use, (documented in
UUOPRV, in the Specifications section of the Software Notebooks) but
users with systems which do not run DAEMON may use the APPEND
subroutine, which may be found in LOGIN, LOGOUT, or DAEMON, for
instance. Note that the FACT file contains privileged information,
and so is accessable only to jobs with JACCT or running under [1,2].
[End of FACT.RNO]