Google
 

Trailing-Edge - PDP-10 Archives - ap-c796e-sb - fact.rno
There is 1 other file named fact.rno in the archive. Click here to see a list.
.TITLE ^^FACT\\
^^SPECIFICATION\\
.BLANK 5
.SPACING 1
.CENTER
^^FACT\\
.BREAK
.LEFT MARGIN 10
.RIGHT MARGIN 50
^^A BRIEF DESCRIPTION OF THE CONTENTS OF ^^FACT.SYS, THE ^ACCOUNTING
^SYSTEM ^RECORDS ^FILE.\\
.BLANK 5
.LEFT MARGIN 20
^DATE:##13-^DEC-72
.BREAK
^FILE:##^^FACT.RNO\\
.BREAK
^EDITION:##1
.BLANK 10
.LEFT MARGIN 0
.RIGHT MARGIN 60
*** ^^COPYRIGHT 1972, ^DIGITAL ^EQUIPMENT ^CORPORATION,
^MAYNARD, ^MASS. 01754\\ ***
.LEFT MARGIN 8
.RIGHT MARGIN 55
.BLANK 4
^THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY ^DIGITAL
^EQUIPMENT ^CORPORATION.
.BLANK 1
^ACTUAL DISTRIBUTION OF THE SOFTWARE DESCRIBED IN THIS DOCUMENT
WILL BE SUBJECT TO TERMS AND CONDITIONS TO BE ANNOUNCED AT SOME
FUTURE DATE BY ^DIGITAL ^EQUIPMENT ^CORPORATION.
.BLANK 1
^^DEC\\ ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF
ITS SOFTWARE IN EQUIPMENT WHICH IS NOT SUPPLIED BY ^^DEC\\.
.LEFT MARGIN 0
.RIGHT MARGIN 60
.PAGE
1.0##^^INTRODUCTION\\
.BLANK 1
^THE FILE ^^FACT.SYS\\ AND ITS AUXILLIARIES ^^FACT.X01, FACT.X02,
 ..., FACT.X77\\ CONTAIN A TRANSACTION RECORD OF THE ACTIVITY
ON A ^^DEC\\SYSTEM-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.
.BLANK 3
1.1##^STANDARD ^INFORMATION
.BLANK 1
^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.
.BLANK 3
1.2##^USE OF ^AUXILLIARY ^FILES
.BLANK 1
^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
.BLANK 1
.INDENT 10
^^ACCOUNTING SYSTEM FAILURE....
.INDENT 10
CALL THE OPERATOR.\\
.BLANK 1
.BREAK
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.
.TEST PAGE 6
.BLANK 3
.TEST PAGE 5
1.3##^PROCESSING ^PROCEDURES
.BLANK 1
^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 A COMPLEX REPORTING SYSTEM WHICH MIGHT BE WRITTEN IN ^^COBOL\\.
.BLANK 3
2.0##^^DEC-DEFINED ENTRIES\\
.BLANK 1
^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.
.TEST PAGE 7
.BLANK 3
2.1##^BASIC ^ENTRY ^FORMAT
.BLANK 1
^THE FIRST THREE WORDS OF EVERY ENTRY ARE THE SAME, AS FOLLOWS:
.BLANK 1
.LEFT MARGIN 15
.TAB STOPS 15
.INDENT -10
^WORD_#	^DESCRIPTION
.BREAK
.INDENT -10
-----	-----------
.BLANK 1
.INDENT -10
0	HEADER -- 4 BYTES, AS FOLLOWS:
.BLANK 1
.LEFT MARGIN 25
.TAB STOPS 25
.INDENT -10
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.
.BLANK 1
.INDENT -10
9-17	JOB NUMBER TO WHICH THIS ENTRY REFERS.  ^USUALLY, BUT NOT
ALWAYS, THE JOB WHICH CREATED THE ENTRY.
.BLANK 1
.INDENT -10
18-29	TERMINAL NUMBER (AS IN ^^TTY\\NNN) TO WHICH THE JOB IS ATTACHED.
^^CTY\\ IS INDICATED BY 7777, AND A DETACHED JOB BY 7776.
.BLANK 1
.INDENT -10
30-35	LENGTH OF THE ENTRY IN WORDS, INCLUDING THIS HEADER WORD.
^IF AN ENTRY HAS ONLY THE BASIC INFORMATION, THIS BYTE IS 3.
.BLANK 1
.LEFT MARGIN 15
.TAB STOPS 15
.INDENT -10
1	PROJECT-PROGRAMMER NUMBER TO WHICH THIS ENTRY
REFERS.
.BLANK 1
.INDENT -10
2	DATE AND TIME AT WHICH THE ENTRY WAS CREATED, AS FOLLOWS:
.BLANK 1
.LEFT MARGIN 19
.INDENT -4
A.##IF HEADER BIT 8=0, OLD FORMAT:
.BLANK 1
0-11###DATE, IN SYSTEM 12-BIT FORMAT.
.BREAK
12-35##TIME, IN CLOCK TICKS SINCE MIDNIGHT.
.BLANK 1
.INDENT -4
B.##IF HEADER BIT 8=1, NEW FORMAT:
.BLANK 1
0-17###DAYS SINCE ^NOV. 17, 1858
.BREAK
18-35##TIME, AS A FRACTION OF A DAY
.LEFT MARGIN 0
.BLANK 3
2.2##^^LOGIN (100), ATTACH (240)\\
.BLANK 1
^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:
.BLANK 1
.INDENT 10
^TERMINAL AND JOB NUMBERS
.INDENT 10
^PROJECT, PROGRAMMER NUMBER
.INDENT 10
^DATE AND TIME OF DAY
.BLANK 1
^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.
.BLANK 3
.TEST PAGE 10
2.3##^^CHKPNT (200)\\
.BLANK 1
^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:
.BLANK 1
.LEFT MARGIN 15
.TAB STOPS 15
.INDENT -10
^WORD_#	^DESCRIPTION
.BREAK
.INDENT -10
-----	-----------
.BLANK 1
.INDENT -10
3	JOB'S ACCUMULATED RUN TIME, IN MILLISECONDS.
.BLANK 1
.INDENT -10
4	JOB'S INTEGRATED TIME-SIZE PRODUCT, IN KILO-CORE-TICKS.
.BLANK 1
.INDENT -10
5	TOTAL DISK BLOCKS READ BY AND FOR THE JOB.
.BLANK 1
.INDENT -10
6	TOTAL DISK BLOCKS WRITTEN BY AND FOR THE JOB.
.BLANK 1
.INDENT -10
7	NAME OF THE PROGRAM IN THE LOW SEGMENT, IN ^^SIXBIT\\.
.LEFT MARGIN 0
.BLANK 3
2.4##^^LOGOUT (140)\\
.BLANK 1
^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.
.BLANK 3
2.5##^^SPOOL\\ (250)
.BLANK 1
^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:
.BLANK 1
.LEFT MARGIN 15
.TAB STOPS 15
.INDENT -10
^WORD_#	^DESCRIPTION
.BREAK
.INDENT -10
-----	-----------
.BLANK 1
.INDENT -10
3	THREE BYTES:
.BLANK 1
0-11###QUEUE NAME IN ^^SIXBIT\\
.BREAK
12-17##STATION NUMBER
.BREAK
18-35##^^APR\\ SERIAL NUMBER
.BLANK 1
.INDENT -10
4	RUNTIME USED BY THE SPOOLER FOR THIS REQUEST, IN JIFFIES (CLOCK TICKS).
.BLANK 1
.INDENT -10
5	KILO-CORE-TICKS USED BY THE SPOOLER FOR THIS REQUEST.
.BLANK 1
.INDENT -10
6	DISK READS BY THE SPOOLER FOR THIS REQUEST.
.BLANK 1
.INDENT -10
7	DISK WRITES BY THE SPOOLER FOR THIS REQUEST.
.BLANK 1
.INDENT -10
8	PHYSICAL DEVICE NAME OF THE SPOOLER OUTPUT DEVICE.
.BLANK 1
.INDENT -10
9	SEQUENCE NUMBER OF THE SPOOL REQUEST.
.BLANK 1
.INDENT -10
10	QUANTITY OF OUTPUT IN SAME UNITS AS OUTPUT
LIMITS FOR THIS QUEUE (E.G., PAGES, FEET, ETC.).
.LEFT MARGIN 0
.BLANK 3
2.6##^^SPACE\\ (160)
.BLANK 1
^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:
.BLANK 1
.LEFT MARGIN 15
.TAB STOPS 15
.INDENT -10
^WORD_#	^DESCRIPTION
.BREAK
.INDENT -10
-----	-----------
.BLANK 1
.INDENT -10
3	FILE STRUCTURE NAME, IN ^^SIXBIT\\, ON WHICH THIS ^^UFD\\ WAS
FOUND.
.BLANK 1
.INDENT -10
4	^^UFD\\ STATUS WORD (^^.RBSTS\\) FROM THE ^^UFD RIB\\.
.BLANK 1
.INDENT -10
5	FIRST COME, FIRST SERVED QUOTA (^^.RBQTF\\).
.BLANK 1
.INDENT -10
6	LOGGED-OUT QUOTA (^^.RBQTO\\).
.BLANK 1
.INDENT -10
7	RESERVED QUOTA (^^.RBQTR\\).
.BLANK 1
.INDENT -10
8	BLOCKS PRESENTLY ALLOCATED TO THIS USER (^^.RBUSD\\).
.BLANK 1
.INDENT -10
9	BLOCKS REMAINING AVAILABLE FOR FIRST COME, FIRST SERVED
ALLOCATION ON THIS STRUCTURE (^^.DCFCT\\).
.BLANK 1
.INDENT -10
10	ONE OF THE FOLLOWING THREE WORDS, IN ^^SIXBIT\\:
.TAB STOPS 25
.LEFT MARGIN 25
.BLANK 1
.INDENT -10
^^OUT\\	THERE ARE NO JOBS LOGGED IN UNDER THIS PPN.
.BLANK 1
.INDENT -10
^^IN\\	THERE IS AT LEAST ONE JOB PRESENTLY LOGGED IN UNDER THIS PPN.
.BLANK 1
.INDENT -10
^^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.
.LEFT MARGIN 0
.BLANK 3
2.7##^RESTART (370)
.BLANK 1
^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.
.BLANK 3
2.8##^SHUTDOWN (372)
.BLANK 1
^UNIMPLEMENTED, BUT INTENDED TO MARK A SCHEDULED SYSTEM SHUTDOWN.
.BLANK 3
.TEST PAGE 20
2.9##^HIATUS (377)
.BLANK 1
^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.
.BLANK 3
2.10##^END-OF-FILE (777)
.BLANK 1
^THE LAST WORD IN THE ^^FACT\\ FILE SHOULD ALWAYS BE THE END-OF-FILE
CODE.
.BLANK 3
2.11##^NEW ^ENTRY ^TYPES
.BLANK 1
^AS DEVELOPMENT OF ^^DEC\\SYSTEM-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.
.BLANK 3
3.0##^^CUSTOMER-DEFINED ENTRIES\\
.BLANK 1
^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, \O\R 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].
.BLANK 4
[^END OF ^^FACT.RNO\\]