Add documentation.

README.md

@@ -10,6 +10,10 @@ the PDP-10 computer family.  It was written by hackers at MIT in the
 1960s.  The MIT site was shut down in 1990, but enthusiasts continue
 to operate ITS systems to this day.
 
+### Documentation
+
+See the [`doc` subdirectory](doc) for documentation.
+
 ### Building it from scratch
 
 This repository contains source code, tools, and scripts to build ITS

doc/README.md

@@ -0,0 +1,7 @@
+## Documentation
+
+- ITS: [primer](_info_/its.primer), [building](kshack/build.doc)
+- DDT: [manual](info/ddt.33), [commands](_info_/ddtord.1462),
+  [colon commands](_info_/ddt.:cmnds)
+- MIDAS: [manual](info/midas.25)
+- DUMP: [manual](_info_/dump.info), [format](sysdoc/dump.format)

doc/_info_/ddt.:cmnds

@@ -0,0 +1,141 @@
+This is the file .INFO.;DDT :CMNDS, printed out by ":?<CR>" in DDT.
+<The commands explictly listed here are part of DDT, not separate programs>
+
+:6TYPE		type Q as a word of sixbit
+:6TYPE <word>	type <word> as a word of sixbit
+:8TYPE		type Q as a word of 8-bit ascii
+:8TYPE <word>	type <word> as a word of 8-bit ascii
+:ALARM	<time of day> alarm clock.  <time> looks like HH:MM or .+HH:MM
+:ALSO		conditional if previous conditional succeeded
+:ASSIGN	<tape#>	assign DECtape
+:ATB	<addr>	raid-display inverse rate of change of C(<addr>)
+:ATTACH		make current inferior replace DDT as top level
+:CHUNAME <new uname> change UNAME (log out and in again)
+:CLEAR		clear screen []
+:CONTINUE	continue program, giving job TTY [P]
+:COPY	<old file>,<new file> copy file, preserving date & FN2 []
+:COPYN	<old file>,<new file> copy file
+:CORBLK <type>,<addr>	change status of page at <addr> to <type>
+:CORPRT		do :CORTYP for each existing page in the current job
+:CORTYP <addr>	print status of page at <addr>
+:CWD	<dir>	change working directory []
+:DATPRT		print Q as a date
+:DATWRD <date>	value is the disk-date format date word for <date>
+:DDTMODE	leave MONIT mode
+:DDTSYM	<sym>	return value of symbol in DDT's symbol table
+:DELETE	<file>	delete file []
+:DESIGN	<tape#>	deassign DECtape
+:DETACH		detach your tree from your TTY
+:DISOWN		disown current job []
+:ELSE		conditional if previous conditional failed
+:ERR	<channel# or channel status (opt)> interpret system error code
+:EXISTS	<file>	value is 0 iff file exists
+:FJOB	<jname>	select <jname> for examination as foreign job, no reowning 
+:FJOB	<uname> <jname> -- select someone else's job, no reowning
+:FLAP	<tape#>	flap (dismount) DECtape
+:FORGET		hide a job from DDT without killing it
+:GAG	<flag>	control receipt of :SENDS (nonzero := accept :SENDS)
+:GENJOB		rename current job to a generated unique name
+:GO	<start addr (opt)> start inferior [G]
+:GZP	<start addr (opt)> start job without TTY [G]
+:HELP		print out basic information
+:ICHAN <chan>	print out the filename and mode of channel <chan>
+		in current job.
+:IF	<condition> <argument> conditional
+:INFLS		flush interrupted valret strings and xfiles
+:INPOP		pop out of current input source
+:INPUSH		read input from TTY within valret or xfile
+:INTEST		execute init file, etc.
+:INTPRT		print Q as interrupt bits
+:IOPEN  <chan>,<mode>,<file> -- open <file> in current job on
+				  <chan> in <mode>
+:JCL	<line>	set job command string
+:JCLPRT		print the current job's command string
+:JOB	<jname>	create or select job [J]
+:JOBP	<jname>	like :JOB but return 0 if successful, else nonzero
+:JUMP	<tag>	transfer control in xfile
+:KILL		kill current job [.]
+:LFILE		print filenames of last file loaded
+:LINK	<link name>,<linked-to> create link; won't clobber an existing file
+:LINKF	<link name>,<linked-to> create link;, like :LINK, for those with
+		:LINK turned off.
+:LINKN	<link name>,<linked-to> create link; willing to replace existing file
+		:LINK and :LINKN do NOT communicate with other users, they
+		create entries in the file system.
+:LISTB		list this job's breakpoints
+:LISTF	<fdir>	list files []
+:LISTJ		list jobs [V]
+:LISTP		list block structure of the job's symbol table
+:LISTS		list job's symbols
+:LISTU		list undefined symbol references
+:LJCL	<string>^C Give the current job a multi-line command string
+:LOAD	<file>	load file into core [L]
+:LOGIN	<name>	log in (name is 6 characters or less) [U]
+:LOGOUT		log off [U]
+:LRUN <pgm><jcl>^C run <pgm> with multi-line JCL
+:MAILNT <-2, -1, 0, 1, 2> sets mail notification mode (see documentation)
+:MASSACRE	kills all your jobs
+:MONMODE	enter MONIT mode
+:MORE		give user a chance to flush further valret or xfile commands
+:MOVE	<old file>,<new file>  move file from old location to new
+:MSGS	<kwd1>,<kwd2>... print messages made since last :MSGS
+:NEW	<prgm>	invoke <prgm>.  If already using <prgm>, make a second copy
+:NEWTTY		tells DDT to see what kind of TTY it has
+:NFDIR	<dir1>,<dir2>... add file directories to search list
+:NOMSG	<flag>	control unsolicited typeouts (0 := inhibit them)
+:OFDIR	<dir1>,<dir2>... remove list of file directories
+:OLOAD	<file>	load file made by old STINK
+:OSEND		same as :SEND but not affected by ..SNDFLG
+:OUTTEST	perform actions normally associated with logging out
+:PDUMP	<file>	dump page map of job in file
+:PDUMPI <file>,<sfile>	dump page map of job in <file> and write indirect
+		symbol table pointer to <sfile>
+:PMDATE		print :MSGS date (date of first message to print)
+:PRGM		print current block name & level
+:PRINT	<file>	print file []
+:PRMAIL	<user (opt)> print another user's or your mail
+:PRSEND <user (opt)> print another user's or your SENDS file [
]
+:PROCED		same as :PROCEED
+:PROCEED	proceed job, leave TTY with DDT []
+:RAIDFLUSH	turn off all raid registers of current job
+:RAIDRP <#sec>	loop redisplaying raid regs every <#sec> seconds
+:RATE	<addr>	raid-display rate of change of C(<addr>)
+:REAP	<file>	set file's reference date to long ago, so it will be reaped
+:RENAME	<oldname>,<newname> rename file []
+:RETRY	<prgm>	invoke <prgm>, clobbering any old copy
+:RUN	<prgm>	invoke <prgm> (which may be DDT command, with TTY on)
+:SELF		Select DDT as current job
+:SEND	<user><msg>^C send message.  :SEND <user>@<host> also works
+:SFAUTHOR <file>,<author name> set author's name of file
+:SFDATE	<file>,<date> set file's creation date
+:SFDUMP <file>,<0 or 1> set file's dumped-on-tape bit
+:SFREAP <file>,<0 or 1> set file's don't-reap bit
+:SHOUT	<msg>^C	send message to all logged-in users.  Not for casual use.
+:SL	<file>	same as :SYMLOD (load symbols only, don't clobber core)
+:SLEEP	<n>	sleep <n> 30'ths of a second
+:SLIST		Same as :LISTS
+:SMDATE <date>	Set the earliest date for printing :MSGS messages
+:SNARF	<jname>	snarf specified job from inferior.  Good for recovering
+		jobs from dead HACTROs
+:SSTATUS	type system status
+:START  <address> start inferior [<address>G].
+:SYMLOD	<file>	load symbols only (don't clobber core)
+:SYMADD	<file>	load syms only, keeping existing syms
+:SYMTYPE <symbol> returns 0 if undefined, <0 if half-killed, else >0
+:TAG	<tag>	make place for :JUMP to jump to in xfile
+:TERPRI		print a CRLF, IFF not at beginning of the line
+:TPL	<file>	queue request to list file on LPT
+:TPLN	<file>	same but works if file not created yet
+:UINIT	<tape#>	clear DECtape directory
+:UJOB	<uname> <jname>	selects someone else's job for examination
+:UNPURE	<addr>	unpurify page containing <addr>
+:V		turn on console output [like  but not instantaneous]
+:VERSION	type version numbers of ITS and DDT
+:VK		:V then crlf and * (":V kerchink")
+:VP		turn on console output and continue job [P]
+:WALBEG	<file>	open script ("wallpaper") file
+:WALEND		close script file
+:WALLP		same as :WALBEG
+:XFILE	<file>	execute file as DDT commands
+:?		list all : commands
+:<prgm>	<optional JCL> invoke program, passing JCL if present

doc/_info_/dump.info

@@ -0,0 +1,366 @@
+-*- Text -*-				This is the file AI:.INFO.;DUMP INFO
+
+HOW TO USE THE MACRO-TAPE DUMP AND LOAD PROGRAM: 
+
+AFTER STARTING DUMP, OBSERVE THE PROMPT CHARACTER "_". 
+TYPE "DUMP F" TO DO A FULL DUMP.
+TYPE "DUMP I" TO DO AN INCREMENTAL DUMP.
+TO DUMP ONLY ONE DIRECTORY, LET'S SAY FOO;, TYPE "DUMP".
+WHEN THE PROGRAM SAYS "FILE =", TYPE "FOO;" FOLLOWED BY AN ALTMODE.
+
+
+WHEN TYPING COMMANDS AT IT, "RUBOUT" WILL FLUSH AND ECHO THE LAST CHARACTER
+UNTIL THE BEGINNING OF THE SYLLABLE.
+TYPE CONTROL-G IF YOU WANT THE PROGRAM
+TO IMMEDIATELY STOP WHAT IT IS DOING AND WAIT FOR
+FURTHER INSTRUCTIONS.
+
+
+THE COMMANDS ARE(FOLLOWED BY SPACE OR CR):
+
+HELP	LISTS COMMANDS AVAILABLE
+REWIND	REWIND TAPE
+TAPED	CREATES A TAPE DIRECTORY ON THE DISK FOR
+	THE CURRENTLY MOUNTED TAPE.  IT ASKS YOU IF YOU ARE SURE, IF
+	A DIRECTORY ALREADY EXISTS FOR THE MOUNTED TAPE.
+	ALL TAPE DIRECTORIES ON THE DISK
+	ARE ON THE DISK DIRECTORIES .TAPE0 AND .TAPE1.
+EOT	GO TO END OF TAPE (SO "DUMP" WILL APPEND NEW FILES RATHER 
+	THAN OVERWRITE THE OLD ONES) 
+SPACE <N>	SPACE FORWARD <N> FILES
+LSPACE	SPACE FORWARD THROUGH FILES, LISTING NAMES OF EACH, 
+	WAITS FOR CHARACTER EACH TIME, RUBOUT WILL TERMINATE.
+LIST 	LIST ALL FILES FROM CURRENT POINT ON TAPE (ASK FOR 
+	LISTING DEVICE TO USE BY TYPING "LIST=").
+MFD	SIMILAR TO ABOVE, BUT LISTS OUT MASTER FILE DIRECTORY.
+LISTF <DEV>:	SIMILAR TO ABOVE BUT LIST FILES ON DEVICE <DEV>.
+TAPE	LIST INFORMATION AVAILABLE ON DISK ABOUT
+	THE STATUS OF A PARTICULAR TAPE.(ASKS TAPE NO=, TYPES INFO ON TTY)
+TAPES	LISTS ABOVE INFO FOR ALL TAPES , ASKS LIST=
+TAPSET	DOES A TAPE THEN ALLOWS THE INFO TO BE RESET
+TLIST	LIST NAMES OF FILES ON A TAPE DIRECTORY SAVED ON DISK.
+	ASKS TAPE NO= AND LIST=
+FIND	FIND WHAT TAPES PARTICULAR FILES ARE DUMPED ON(SEE BELOW).
+LOAD	LOAD FILES FROM MAGNETIC TAPE (SEE BELOW).
+DUMP	DUMP FILES ONTO MAGNETIC TAPE (SEE BELOW).
+CDUMP	SAME AS "DUMP F", BUT CONTINUE FROM INTERRUPTION,
+	SUCH AS SYSTEM LOSSAGE OR RELOAD. 
+
+
+THE DUMP AND LOAD COMMANDS MUST BE FOLLOWED
+BY A CARRIAGE RETURN WHICH MAY BE PRECEDED BY VARIOUS
+SWITCHES, EACH OF WHICH MUST BE PRECEDED BY A SPACE.
+
+
+THE SWITCHES HAVE THE FOLLOWING MEANING:
+
+INCREM (OR I)	DUMP ONLY FILES WHOSE .DMPCH HAS NOT BEEN SET 
+		(I.E. HAVE NOT BEEN PREVIOUSLY DUMPED)
+MERGE (OR M)	LOAD ONLY THOSE FILES WHICH DO NOT ALREADY EXIST.
+EXPERM (OR E)	DO NOT SET .DMPCH FOR THE FILES BEING DUMPED, 
+		SINCE THIS IS ONLY AN EXPERIMENTAL DUMP.
+CARE (OR C)	DO NOT LOAD FILES WHICH ALREADY EXIST ON DISK 
+		AND DO NOT HAVE THEIR .DMPCH SET (I.E. PROBABLY CREATED NEW 
+		SINCE THE VERSION ON TAPE WAS CREATED).
+LIST (OR L)	LIST USERS WHEN DOING A FULL DUMP, LIST FILES 
+		WHEN DOING A DUMP OF ONE USER - SIMILARLY FOR LOADING 
+		(ASK WHAT LISTING DEVICE TO USE BY TYPING "LIST=").
+ARCHIVE (OR A)	MARK THIS SET OF TAPES ON DISK AS A ARCHIVE.
+		ATTEMPTED DUMPS ON THESE TAPES WILL SAY
+		THAT TAPE IS AN ARCHIVE. ARE YOU SURE?
+FULL (OR F)	DUMP THE WHOLE WORLD (ALL FILES)
+		EQUIVALENT TO DSK:*;* *(SEE BELOW)
+
+
+IF YOU JUST TYPE "DUMP FULL", THE PROGRAM GOES AHEAD AND
+IMMEDIATELY DUMPS EVERY FILE FROM THE DISKS ONTO MAGNETIC
+TAPE.  IF THE F SWITCH IS NOT SPECIFIED, OR YOU TYPE
+"LOAD" OR "FIND", THE PROGRAM TYPES "FILE=" AND WAITS FOR
+A FILE SPECIFICATION LINE FOLLOWED BY A CARRIAGE RETURN OR
+AN ALTMODE.  IT THEN TYPES "FILE=" AGAIN UNLESS YOU TYPED
+ONLY A CARRIAGE RETURN FOR THE LAST FILE SPECIFICATION
+LINE, OR YOU TERMINATED THE LAST LINE WITH AN ALTMODE OR
+YOUR LAST LINE IMPLIED THE WHOLE WORLD (*;* *), IN WHICH
+CASE THE PROGRAM RETURNS TO THE CALLING ROUTINE.  (LOAD,
+DUMP, OR FIND).  A FULL FILE SPECIFICATION LINE IS OF THE
+FORM "DEV:USR;FN1 FN2_DEV:USR;FN1 FN2".  FOR EXPLANITARY
+PURPOSES, LET'S CALL THE SPECS BEFORE THE "_" "TO" ARGS
+AND THE ONES TO THE RIGHT OF THE "_" "FROM" ARGS.  ANY
+UNSPECIFIED ARG IN A SPECIFICATION LINE IS GIVEN THE VALUE
+OF SOME DEFAULT FOR THAT ARG.  THE DEFAULT FOR "FROM"
+DEVICE SPECIFICATION IS DSK:.  THE INITIAL DEFAULT FOR
+"FROM" SNAME IS YOUR USER NAME.(WHAT YOU LOGGED IN AS.)
+THE INITIAL DEFAULT FOR "FROM" FN1 AND FN2 IS "*".  THE
+DEFAULT FOR "FROM" SNAME, FN1, AND FN2 IS HENCEFORTH THE
+"FROM" SPEC FROM THE LAST SPECIFICATION LINE.  "TO" ARGS
+ALWAYS DEFAULT TO THE CORRESPONDING "FROM" ARG OF THE SAME
+SPEC LINE.  A SPECIFICATION "*" HAS SPECIAL MEANINGS AS
+DESCRIBED BELOW.  TO REALLY CAUSE A SPECIFICATION TO BE AN
+ASTERISK, PRECEDE IT WITH A CONTROL-Q.  AFTER DOING THIS,
+YOU SHOULD SEE ON YOUR TERMINAL "^Q*".  THE CHARACTERS
+BACKARROW"_", SEMI-COLON";", COLON":", AND SPACE" " MUST
+ALSO BE PRECEDED BY A CONTROL-Q, IF THEY ARE USED AS PART
+OF A SPECIFICATION.
+
+IF THE "_" IS NOT TYPED AT ALL, ALL THE ARGS OF THE SPEC
+LINE ARE ASSUMED TO BE "FROM" ARGS.
+
+THE DUMP COMMAND IGNORES ALL "TO" ARGS.  IT DUMPS ALL THE
+FILES THAT MATCH ANY OF THE SPEC LINES.  AN "*" AS AN ARG
+IN A SPEC LINE CAUSES ANYTHING TO BE MATCHED TO IT.  FOR
+INSTANCE "*;" MEANS ANY DIRECTORY.
+
+EXAMPLES OF DUMP:
+TO DO AN INCREMENTAL DUMP, YOUR TTY SCREEN OR PAPER
+MIGHT LOOK LIKE THIS:
+
+_DUMP I
+TAPE NO=105
+
+_
+
+
+THE PROGRAM ONLY ASKS FOR A TAPE NO IF IT DOESN'T ALREADY
+KNOW IT.
+
+TO DUMP THE FILE CALLED "RANDOM CRUD" FROM YOUR DIRECTORY
+AND ALL OF THE FILES FROM FOO'S DIRECTORY, IT MAY LOOK
+LIKE THIS:
+
+_DUMP
+FILE= RANDOM CRUD
+FILE=FOO;* *
+FILE=
+
+_
+
+TO DO A FULL DUMP, IT MIGHT LOOK LIKE THIS:
+
+_DUMP F
+TAPE NO=239
+
+_
+
+NOTE THAT A SPEC LINE IN A NON-FULL DUMP SAYING *;* *
+CAUSES THE WHOLE WORLD TO BE DUMPED AS THOUGH YOU HAD USED
+THE FULL SWITCH.
+
+
+TO RESTART A FULL DUMP AFTER SOME ACCIDENT SUCH AS SYSTEM
+CRASH, TYPE CDUMP <SWITCHES><RETURN>.  THE PROGRAM TRIES
+TO INTELLIGENTLY CONTINUE DUMPING FROM WHERE IT LEFT OFF.
+IF IT NEEDS SOME INFORMATION, IT WILL ASK YOU FOR IT.
+
+
+THE LOAD COMMAND SEARCHES THROUGH THE CURRENT TAPE FOR
+FILES MATCHING ANY OF THE SPECIFICATION "FROM" SPECS.  IF
+IT FINDS A MATCH, IT LOADS IT INTO THE "TO" SPEC OF THE
+LINE THAT WAS SUCCESSFULLY MATCHED.  THE CHARACTER "*" IN
+A FROM SPEC MEANS MATCH TO ANYTHING, AND AN "*" IN A "TO"
+SPEC GETS REPLACED WITH THE CORRESPONDING "FROM" ARG READ
+FROM THE TAPE ITSELF.  IN OTHER WORDS, IF THE FILE ON THE
+TAPE IS "HUR;TICTAC 9", THEN IT COULD MATCH THE SPEC LINE
+"FOO;* 9_HUR;TICTAC *" WHICH WOULD CAUSE THE PROGRAM TO
+TAKE THE FILE "TICTAC 9" FROM THE TAPE AND SAVE IT ON THE
+DISK ON DIRECTORY "FOO" WITH THE NAME "TICTAC 9".  SOME
+EXAMPLES SHOULD CLEAR IT ALL UP:
+
+
+_LOAD
+FILE=FOO;
+FILE=
+
+_
+
+THE ABOVE IS HOW YOUR TTY SCREEN OR PAPER MIGHT LOOK IF
+YOU TOLD THE DUMP PROGRAM TO RESTORE DIRECTORY "FOO"
+COMPLETELY FROM TAPE.
+
+TO LOAD A FILE INTO DIRECTORY "FOO" THAT IS STORED ON TAPE
+AS "SHRDLU;MOBY DUMP", YOUR PAPER OR SCREEN MAY LOOK LIKE
+THIS:
+
+_LOAD
+FILE=FOO;_SHRDLU;MOBY DUMP$
+
+_
+
+TO LOAD A BUNCH OF ARBITRARY FILES, THE APPEARANCE MIGHT BE:
+
+_LOAD
+FILE=HAL;ROBOT *
+FILE=FOO;THIS ONE
+FILE=*;HACK
+FILE=
+
+_
+
+THAT LAST SPECIFICATION LINE MEANS TO LOAD ANY FILES ON
+THE CURRENT TAPE THAT HAVE THE FIRST NAME OF "HACK".
+OBSERVE THAT BY THE DEFAULT RULES GIVEN ABOVE, IF THERE IS
+NO "_" IN A SPEC LINE FOR THE LOAD COMMAND, FILES THAT
+MATCH THAT SPEC GET LOADED INTO THE SAME DIRECTORY THEY
+WERE DUMPED FROM.
+
+THE FOLLOWING IS HOW TO LOAD THE WHOLE WORLD FROM THE
+CURRENT TAPE WITHOUT FEAR OF DELETING ANY EXISTING FILES
+FROM THE DISKS THAT HAVEN'T YET BEEN DUMPED:
+
+_LOAD CARE
+FILE=*;* *
+FILE=
+
+_
+
+THE FIND COMMAND TRIES ALSO TO MATCH "FROM" ARGS, BUT IT
+SEARCHES THE FILES ON DIRECTORIES ".TAPE0" AND ".TAPE1" FOR
+THE FILE NAMES OF FILES THAT HAVE BEEN DUMPED.
+IF THE FIND COMMAND FINDS A MATCH, IT TELLS YOU THE TAPE #,
+USER NAME, FILE NAME, AND CREATION DATE AND TIME.
+
+EVERY TAPE THAT IS WRITTEN ON WITH THE DUMP PROGRAM HAS A
+CORRESPONDING DIRECTORY FOR IT STORED ON THE DISK.  THE
+DIRECTORY IS A FILE NAMED "TAPE NNN" WHERE "NNN" IS THE
+TAPE NO OF THE TAPE.  THE DISK DIRECTORY ON WHICH THIS
+DIRECTORY MAY BE FOUND IS ".TAPE0;" FOR EVEN NUMBERED
+TAPES, AND ".TAPE1;" FOR ODD NUMBERED TAPES.
+
+THE FIRST WORD IN A TAPE DIRECTORY IS -N,,0.  N IS THE
+NUMBER OF WORDS IN THE TAPE HEADER INCLUDING THIS FIRST
+WORD.  CURRENTLY N IS 4, AND THE NEXT WORD HAS THE TAPE NO
+(NUMBER) IN THE LEFT HALF AND THE REEL NUMBER IN THE RIGHT
+HALF.  THE NEXT TWO WORDS HOLD THE SIXBIT DATE OF CREATION
+OF THE TAPE, AND A NUMBER DESIGNATING WHAT TYPE OF DUMP
+THIS TAPE IS.  0 MEANS RANDOM, -1 MEANS FULL, AND 1 MEANS
+INCREMENTAL.
+
+THE NEXT WORD IS -N,,0 WHERE N, CURRENTLY 5, TELLS THE
+NUMBER OF WORDS IN EACH FILE BLOCK.  THE REST OF THE
+DIRECTORY IS FILE BLOCKS.  EACH FILE BLOCK TELLS
+INFORMATION ABOUT ONE FILE DUMPED FROM A DISK ONTO THIS
+TAPE.  CURRENTLY, THE 5 WORD BLOCK SPECIFIES IN THE
+FOLLOWING ORDER, DIRECTORY FILE WAS DUMPED FROM, FIRST
+FILE NAME, SECOND FILE NAME, DISK PACK NUMBER FILE CAME
+FROM, AND COMPACT DATE AND TIME OF CREATION FOR THE FILE.
+
+
+THE FORMAT OF DATA ON THE TAPE IS IDENTICAL TO THE FORMAT
+OF THE DIRECTORY DESCRIBED ABOVE, EXCEPT FOR THE FOLLOWING
+THINGS:  THE FILE ITSELF IS WRITTEN ON THE TAPE AFTER THE
+FILE BLOCK.  EACH FILE IS FOLLOWED BY A SYSTEM "END OF
+FILE" MARK ON THE TAPE.  THE WORD -N,,0 THAT PRECEDES THE
+FIRST FILE BLOCK IN THE DIRECTORY PRECEDES EVERY FILE
+BLOCK ON THE TAPE.  IF A FILE BEING DUMPED IS ACTUALLY
+ONLY A LINK TO ANOTHER FILE ON THE DISK, THE WORD USUALLY
+HOLDING THE PACK NUMBER IS USED TO HOLD THE DIRECTORY NAME
+OF THE DIRECTORY CONTAINING THE FILE THAT THIS ONE IS
+LINKED TO.  FOR LINKS, THE ACTUAL FILE CONTENTS ON THE
+TAPE IS ONLY A SPECIFICATION AS TO WHICH FILE THIS FILE IS
+LINKED TO.
+
+A CRUDE COMPARE OPERATION IS POSSIBLE BY USING THE FOLLOWING COMMAND:
+LCHECK	WILL LIST OUT A LOT OF INFORMATION ABOUT THE FILES ON 
+	MACRO-TAPE WHILE COMPARING THEM WITH SIMILARLY NAMED FILES 
+	ON DISK (WILL ASK FOR LISTING DEVICE BY TYPING "LIST=").
+CHECK	SIMILAR BUT ONLY LISTS FILES IT HAD PROBLEMS WITH.
+
+
+
+ERROR COMMENTS:
+
+WHEN OPENING A CERTAIN FILES DOES NOT WIN THE PROGRAM WILL 
+TYPE THE APPROPRIATE (FILE NAME AND) REASON, THIS IS ALSO TRUE OF VARIOUS 
+I/O ERRORS. AT TIMES THE PROGRAM MAY GET CONFUSED 
+AND TYPE ONE OF THE FOLLOWING:
+
+<N> RANDOM INTERRUPT	UN-ENABLED INTERRUPT <N> HAPPENED.
+<N> INTERRUPT FROM RANDOM DEVICE <MESSAGE>	INTERRUPT FROM 
+	DEVICE <N> (OTHER THAN MACRO-TAPE), STATUS AS IN <MESSAGE>.
+INTERRUPT ON MAG TAPE WHEN NOT DUMPING <MESSAGE>	INTERRUPT 
+	FROM MACRO-TAPE WHILE IN OPERATION OTHER THAN DUMP. STATUS 
+	AS IN <MESSAGE>.
+<N> INTERRUPT ON OUTPUT NOT END OF TAPE <MESSAGE>	INTERRUPT 
+	<N> HAPPENED ON MAG-TAPE OUTPUT.
+OTHER ERROR COMMENTS EXPLAIN THEMSELVES.
+
+ 
+CAPACITY:
+
+AT 800 BPI A 2400 FOOT TAPE COULD HOLD 3840. BLOCKS (1024. WORDS EACH)
+IF THE WHOLE TAPE WAS ONE RECORD. ASSUMING ONE INCH INTERRECORD GAPS,
+RECORDS OF SIZE 1024. WORDS, BUT STILL ONLY ONE FILE, THIS IS REDUCED
+TO 3400. BLOCKS. IN PRACTICE ONE GETS ONLY ABOUT 2500. BLOCKS ON ONE
+REEL (REST OF SPACE TAKEN UP BY HEADERS, INTERRECORD GAPS AND FILE MARKS). 
+
+These are the DUMP commands and options and their
+self-documentation as of 9/2/81:
+
+
+_?
+FIND    Find what tape a particular file is on
+OFIND   FIND command using a tape for info
+DUMP    Dump files
+LOAD    Load files
+RELOAD  Load files, modify dir ctory from tape copy
+CLOAD   Continue previous LOAD RELOAD operation
+CDUMP   Continue full dump
+REWIND  Rewind mag tape
+UNLOAD  Rewind/unload
+EOT     Go to end of tape
+SPACE   Space forward n files
+LSPACE  Space forward and list files, hit <space> after each
+LIST    List files on tape
+MFD     List MFD from disk
+LISTF   List a file directory from disk
+HELP    Type out commands
+CHECK   Check files on tape against disk
+LCHECK  Check files and list them
+ICHECK  Check files on incremental dump, update dump-check bits
+TAPED   Generate tape directory from mounted tape
+TAPES   List all saved tape info
+TAPE    List saved info about one tape
+TAPSET  Set tape info for one tape
+TLIST   List files on a tape (from tape directory stored on disk)
+GFR     Grim File Reaper (Don't use this, please)
+QUIT    return to DDT
+ERRSTS  Print tape control status as of last error
+ALLOC   Examine or change directory allocation
+LSTALC  List all directories with allocations
+PTDIR   Print directories from tape
+
+
+_dump ?
+INCREM, I   Do an Incremental Dump
+FULL, F     Do a Complete dump
+LIST, L     Generate a listing of files loaded or dumped
+MERGE, M    Don't load over existing file with the same name
+CARE, C     Don't load over files not yet backed up
+EXPERI, E   Don't set has-been backed-up bits
+SORRY, S    Go ahead and load over files with newer creation dates
+NOASK       Don't ask whether a file should be loaded over, assume "no"
+DATE        Dump only files with creation date greater or equal specified
+DATES       Dump only files with creation date between two dates specified
+ARCHIV, A   Declare this dump tape to be Archival.
+REAP, R     Do a reap after dumping (don't use this, please)
+DECIDE, D   (Supposedly controls tape number assignment)
+NO          Don't check incremental dump (one pass instead of two)
+
+
+_gfr ?
+H       MAKE HISTOGRAM OF BLOCKS FREED VERSUS DATE
+L       LIST HISTOGRAM AND/OR FILES REAPED
+DUMP    DUMP REAPED FILES ONTO TAPE
+DELETE  DELETE REAPED FILES (AFTER DUMPING)
+TO dev  DUMP TO DISK DEVICE dev  (E.G. SECOND) INSTEAD OF TAPE
+DATE    ENTER DATE OF OLDEST FILE TO RETAIN
+BLOCKS  ENTER NUMBER OF BLOCKS TO BE OBTAINED
+CREATE  USE CREATION DATE INSTEAD OF REFERENCE DATE
+QUOTA   ENFORCE DIRECTORY QUOTAS
+ALLOC   REAP ALLOCATED DIRS TOO
+EVERY   ALLOW NO SPECIAL DIRECTORIES (DON'T USE THIS, PLEASE!)
+FROM dev REAP OFF OF DEVICE dev (E.G. SECOND) AS WELL AS MAIN DISK.
+ONLY    REAP ONLY FROM SPECIFIED DEVICE, NOT MAIN DISK.
+DISK    DUMP TO SECONDARY DISK INSTEAD OF TAPE
+        (THIS IS AN OBSOLETE FORM FOR "TO SECOND")
+SECOND  REAP SECONDARY DISK ALSO
+        (THIS IS AN OBSOLETE FORM FOR "FROM SECOND")

doc/sysdoc/dump.format

@@ -0,0 +1,49 @@
+-*- Text -*-			This is the file AI:SYSDOC;DUMP FORMAT
+
+This file attempts to document the format of DUMP tapes.
+It probably contains inaccuracies.
+
+Each tape record contains 1,024 36-bit words in "core dump" format;
+thus on 7-track tape each 36-bit word takes 6 tape frames.  Data
+formats are standard pdp-10 data formats such as sixbit (6 characters
+per word), 7-bit ascii (5 characters per word, left-justified),
+halfwords, and so forth.
+
+Each file dumped to tape consists of a header, then the 36-bit data of
+the file, and ends with an end-of-file mark.  The last record in a file
+will generally be shorter than 1,024 words, depending on the length
+of the file.  There is no padding, other than the usual control-C's
+padding a text file out to a word boundary.  The tape ends with a
+double end-of-file mark.
+
+The first file on the tape is preceded by a tape header in front
+of the file header, with no end-of-file mark in between.
+
+Each type of header starts with a 36-bit word whose left half is minus
+the number of words in the header, including this word.  The right
+half of this word is zero.
+
+Tape header:
+	-LTHBLK,,0
+	tape number,,reel number
+	tape creation date in sixbit
+	type of tape (0 random, >0 full dump, <0 incremental dump)
+
+File header:
+	-LHBLK,,0
+	directory name in sixbit
+	first file name in sixbit
+	second file name in sixbit
+	disk pack number where file was
+	creation date of file (same format as in ITS directory)
+
+If the file is really a link, then the left half of the
+pack number is non-zero and the data of the file consists of
+three words, containing the sixbit file name the link points to.
+
+In addition to files, directories also appear on some dump tapes.  The
+master file directory has name M.F.D. (FILE) and a user file directory
+has name .FILE. (DIR).  The data for the master directory is an exact
+binary copy of the directory as stored on disk.  The data for a user
+directory is almost an exact binary copy except that unused space
+between the descriptor area and the name area is squished out.