USER MANUAL FOR MUSS11 B. GILMORE JUNE 1975
CONTENTS TITLE PAGE General features 3 Compiling a program. 4 Running a program. 5 External routines. 6 Input and output to terminals 7 Running PAL11F programs. 8 Operator control of the system. 9 Device handlers. 13 UTILITY PROGRAMS Editor. 15 File transfer program. 16 File Name program 18 Archive program. 20 EXTERNAL ROUTINE LIBRARY WAIT 22 NAME 22 DEFN 22 WRIT 22 COM 23 DA 23 FIDENT 24 RENAME 24
GENERAL FEATURES OF MUSS11 Muss11 is a system designed to allow multi programming and multi user access to PDP11S without memory management. It is a general purpose system that has the capability of running in a real-time environment. Although it will run on any member of the PDP11 family, it will not take advantage of the memory management/protection features of the larger machines. A disc, or other form of mass storage, is desirable, but is not a necessity. The system will multi-program up to 128 separate programs, running on one, or a number of terminals. All programs are core resident and may run at one of eight priorities - corresponding to the eight machine priorities, although for normal programs, only the bottom four are used. As a rule programs are written in IMP, but PAL11F programs can be run with certain restrictions (the restrictions are listed later). When the system is running, the highest priority program able to run is given the CPU. If there are several programs of equal priority able to run, they are time sliced at not more than 20 milliseconds each. The priority structure ensures that the system can be used in a real-time environment when very fast responses to interrupts are required. A program may dynamically change its priority up or down in time critical areas to ensure response. Sections of code on the system may be shared between users, thereby cutting down on the total amount of core required. For example, several users may use the editor, each having his own private storage but sharing one copy of the editor code. An ASSEMBLER (to stand-alone PAL11F standards) is available for systems with at least 16k words of store, and it is hoped to provide an IMP compiler on systems with 28k words within the next few months. Alternativly programs can be written, compiled and assembled on EMAS, then the binary is loaded on the system.
COMPILING AN IMP PROGRAM The Imp program should be compiled and assembled on EMAS (for full details of the language and how to run it see documentation by K. Yarwood ERCC (ext. 2636) - for the assembler see B. Gilmore ERCC (ext. 2636). 1) A program requires a short header to inform the system of its starting address, priority, name etc. The format is (as added into the IMP program):- *ENDCO ; !This is the overall length of the code *.ASCII /xxxx/; !4 character program name *0 ; !'subsystem' number (0 is default) *MAIN+10 ; !starting address (MAIN is a label ; ! defined by the compiler) *40 ; !priority to run at:- ! 0 - Priority level 0 ! 40 - Priority level 1 ! 100 - Priority level 2 ! 140 - Priority level 3 *0 ; !descriptor length (0 is default) *2000 ; !stack length ( = space for arrays + 1000 octal) e.g. *ENDCO *.ASCII /SORT/ *0,MAIN+10,40,0,2000 2) A control statement is required to force the compiler to 1) Produce POSITION INDEPENDANT CODE (%CONTROL 8) 2) Special code for MUSS11 (%CONTROL 8192). This control value effects the code dumped for EXTERNALS, REALS and STRINGS. This should be put before the %BEGIN %CONTROL 8200 %BEGIN The %CONTROL statement may be expressed in either octal or Hex in the standard format, e.g. %CONTROL 8200 may be written %CONTROL 0'20010' or %CONTROL X'2008'. The standard bits for setting checks on or off may also be used, for a full list see Appendix one. The more useful ones are:- 1) Line number updating (%CONTROL 1) 2) Array bound checking (%CONTROL 4). Summary: use %CONTROL 0'20015' for checks ON
%CONTROL 0'20010' for checks OFF The header for an external routine/fn/map is different and is explained in the section 'using external routines'. RUNNING THE PROGRAM The Binary output from the assembler may be 1) punched on tape, 2) punched on cards or 3) sent to the relevant remote. For tape and cards, the program 'BINY' is used to load the tape/cards to the disc, 'TRANY' is used when a file comes off the line. These two programs are discribed in the section of utility programs. The file on disc is then 'RUN' - by using the operator command 'RU' in 'OIT' (see command A1 under operator commands). This command instructs the loader to load the file into core, then to set up a system descripter (PSECT) and tell the system to enter it. The 'sub-system' will then grab space for the programs stack, setting up its 'R1' and its 'SP' and then entering the program at the starting address and priority described in the header. If the program executes correctly (or has a standard IMP fault) then the message 'STOPPED AT LINE x MIN STK xxxxxx' is output and the program is completely purged from core. (The message 'MIN STK xxxxx' refers to the minum stack the program had while it is executing - this is tied up with the parameter specified on the header). On the other hand if the program causes an address error or an illegal instruction, then :- XXXX TASK ERROR! is output. The program in this case is not purged from core, allow the cause of the fault to be determined, and so must be allowed to go by giving the command 'PU XXXX' (see operators command A7). (XXXX is its program name).
Using External Routines 1) PRINT and READF (real read), if required, should be declared as external routine at the top of the program. %EXTERNALROUTINESPEC PRINT(%REAL X, %INTEGER A,B) %EXTERNALROUTINESPEC READF(%REALNAME X) 2) To create a new external routine file. 1) only one external routine per file is allowed. 2) compile with normal control options. 3) use the following header (example uses %EXTERNALROUTINE ABCDEF) *ENDCO-. *.ASCII /ABCD/ 0,ABCDEF,<PRIORITY>,0 ( or 0,16,40,0) %CONTROL X'2008' %EXTERNALROUTINE ABCDEF(%INTEGER A,B,C) %END %ENDOFFILE 3) The routine should be put in a file named ABCDYY (if the name is less than 4 characters then pad out with Y's e.g. AYYYYY).
INPUT AND OUTPUT TO TERMINALS In general on MUSS11 all input/output is line orientated, ie a program receives an entire line of input at once, and nothing is actually output until the program issues a newline (or SELECT OUTPUT). However as the PDP11 version of the IMP compiler does not cater for PROMPS in the EMAS sense, the general effect can be obtained by using 'PRINTSYMBOL(0)'. PRINTSYMBOL(0) executed by a program will immediately send the current line to the output device - without a terminating newline. The zero character is not printed. For example, if %PRINTTEXT'DATA:'; PRINTSYMBOL(0) is used in a program outputting to the teletype, it will output the 'DATA:', leaving the carriage positioned past it; the user can then type a reply on the same line. However it will not repeat itself if the user types a newline and the program still requires data. The program MUST re-issue the message. It is perfectly reasonable to have two or more programs outputting to the same teletype. Complete lines from each program will be generated and will appear on the device, the lines alternating between each program. There is a problem however, in having two programs simultaneously inputting from one terminal. It will work, BUT one line of input will go alternately to each program and it will not always be possible to determine which program will get the next line of input.
RUNNING PAL11F PROGRAMS PAL11F programs may be run on the system if they conform to the following rules:- 1) They must be position independant. 2) The I/O must conform to MUSS11 I/O. For example, the TELETYPE must not be accessed directly, it can only be used by issuing the relevant SVC. 3) In most cases, because of the differences in I/O, a program written to run under DOS will not run under MUSS11 without a major re-write (as is the case in switching between DEC systems). If starting from the beginning, it will usually be easier to imbed the program in an IMP looking header (in assembler). In this manner it will be fairly easy to use the I/O facilities of IMP itself, while still allowing a fairly free use of ASSEMBLER. For further details please contact B. Gilmore.
OPERATOR CONTROL OF THE SYSTEM An operator can control the system by typing the sequence 'CTRL+R' (denoted as ^R) (which echoes OIT:) and a command. Notes: 1) only the first two characters of the command word need to be typed. 2) all parameters should be separated by at least one space. 3) the sequence is terminated by a CR. 4) a program's identifier may be used instead of its name. Commands:- A) Program control 1) RU(N) <filename> run a program 2) SU(SPEND) <prog name> suspend a program (when it is next awake) 3) CO(NTINUE) <prog name> allow a program to continue 4) KI(LL) <prog name> kill a program 5) LO(AD) <file name> load a program into core 6) ST(ART) <prog name> start up a previously loaded program 7) PU(RGE) <prog name> Remove a program from core after it has crashed. B) System information 1) PS(ECTS) list all the programs in the system 2) DU(MP) <from(octal)> <to(octal)> dump out an area of core 3) EX(AMINE) <prog name> dump out a program psect 4) MO(DIFY) <octal> examine a core location 5) NE(XT) examine the next core location 6) RE(PEAT) examine the location again 7) SC <word> <contents> Set a word in the communication area. C) Card reader control 1) CR ASC tell the card reader to read in ASCII mode 2) CR BIN tell the card reader to read in binary mode 3) CR EOT marks the end of a pack of cards.
DETAILED DESCRIPTION OF THE COMMANDS. A1) RUN <filename> The loader attempts to load the named file, create a descriptor for it (called a PSECT) and start it executing. 1) if the file does not exist (or the file is not in the correct format) then the message 'EOF!' is put out. 2) If it loads correctly, then the program name, address of the file and its system number is output:- PROG <address> <identifier> 3) If the loader is busy the 'OIT' types NO! 4) If there is no core the 'OIT' types 'NO CORE!' A2) SUSPEND <progname> A program may be temporarily halted in its execution to allow 1) the debugging program to be run 2) to wait for an operator to put a special (i.e. non-system) device on line. 3) before a program is killed. This command does not take effect until the program next has a chance to get the CPU. A3) CONTINUE <progname> This command is the converse of the suspend command, allowing the program to continue its execution. There are two main occasions this is used 1) after a 'SUSPEND' has been done 2) after a program/system test has issued the 'WAIT' SVC to wait for some operator action e.g. after cards have been put in the hopper, 'CO CR' is typed, or if the line printer was off-line - 'CO LP' is typed after it is put on-line. A4) KILL <prog name> A program may be aborted by Killing it. The following sequence must be followed.
1) SU <prog> to get it to the 'wait state' 2) KI <prog> instruct the supervisor to kill it - the message:- n termination req. STOPPED AT LINE n MIN STK x is output and the program is removed from core A5) LOAD <file name> The command does the local phase of the 'Run' command. the loader replies: PROG <address> The error messages are as in run. This command may be used to load an external routine in order to put patches in the file before running the main program. A6) START <progname> This command is used to start up a previously loaded program, the loader outputs <identifier> A7) PURGE <progname> This command is used to remove a program from core after it has aborted with an address error or similar fault. B1) PSECTS This command lists the programs and system tasks in the format:- name address state name address state etc. B2) DUMP <from> <to> Areas of core (or device registers) may be dumped out, dumping always starts from a 20 byte boundary. If an illegal address is specified the 'OUCH!' is output. A dump can be stopped by hitting ESC.
B3) EXAMINE <prog name> The descriptor (PSECT) of a program (its state, prompts system variable, I/O definitions etc.) is dumped out. B4) MODIFY <address> A location (given in octal) may be examined and/or modified by using this command e.g. (system response is underlined) M0 1000 (CR) 001000 : 000001 : ^R 123456 (CR) > ^ If the location is not to be modified then the number is left out. Typing a dot will then examine the next location, the '>' will use the contents as the address for examine and ^ will go to the previous address. B5) NEXT This examines the next location, responses are the same as for examine. B6) REPEAT This repeats the last location. B7) Set Communication word. This command sets the word 'word' in the communication area to 'cont'. See EXTERNAL INTEGER MAP COM for details of its use. Card Reader Commands C1) CR ASC This command switches the mode of sending cards to ASCII (which is the default), it will take effect on the next card read. C2) CR BIN Is similar to CR ASC but switches the mode to binary. C3) CR EOF This command tells the card reader handler to signal an 'end-of-file' to
the program reading from it.
DEVICE HANDLERS 1) LINE PRINTER The system task which handles the line printer will assume it is on-line and ready. If it is not, or the printer stops (out of paper etc.) then the message:- LP OFFLINE! is output on the main teletype. The line printer should be put on-line, or fixed, then:- ^R CO LP (See operator command A3) is typed on any console. The message:- LP TASK ERROR! will appear if the device registers are removed or changed or if there is an error in the handler (rare!). 2) PAPER TAPE READER On IPL (initial program load), the tape reader will attempt to start up, the message:- PR OFFLINE! will be output if there is no tape (normal condition). This message is also output when the reader reaches the end of a tape. When a tape is to be read, it is put in the reader and ' ^R CO PR' is typed on any console. The reader should read a section of tape and will then be ready for use. 'PR TASK ERROR!' will be output for similar reasons as above. Note: an 'EOF' is assumed at the end of each tape. 3) CARD READER This is similar to the paper tape reader with the difference in the End-of-file handling as described in operator commands C1, C2 and C3.
4) DISC AND DEC TAPE The messages:- DK OFFLINE! DF OFFLINE! DT OFFLINE! - are output if the relevant device is off line, or if there is a read/write error on a transfer.
UTILITY PROGRAMS A) EDITOR OBJECT FILE: EDITY This editor is a PDP11 version of the COMPATIBLE CONTEXT EDITOR which runs on EMAS, PDP15S and PDP8S. OPERATING PROCEDURE: When started, the editor prompts with:- EDIT VN.M # The user responds by typing the input and output file names in the form OUTPUT FILE NAME < INPUT FILE NAME or OUTPUT FILE NAME 1) If the input file does not exist, or is not specified, then a new file is created. 2) A temporary file is created, so, at the end of the editing session the 'old' output file is destroyed and the temporary file is renamed. 3) To edit a file to itself, the form FILE NAME < FILE NAME is used. 4) Editing commands are as in H. Dewar's 'Compatible Context Editor' with the following differences:- A) '%T' will close all the files then restart the EDITOR. B) The EDITOR operates with a 'window' of the file held in core, this will normally be transparent to the user, the command 'M-0' is an exception as it can only move to the top of the 'window'. C) No secondary stream is implemented.
B) FILE TRANSFER PROGRAM OBJECT FILE: TRANY This IMP program is a general file/file and file/peripheral transfer program, including transfers to and from a synchronous communications line in IMP 2780 protocol. OPERATING PROCEDURES: When TRAN is ready to accept a command it prompts:- TRAN: The format for the response is:- FILE/DEV < FILE/DEV,FILE/DEV or DIRECTIVE Where FILE/DEV is FILE NAME or DEVICE NAME A file name is defined as a group of alphanumeric characters with a length of one to six characters. 'DEVICE NAME' is defined as:- KB: (keyboard input) or TT: (teletype output) or LP: (line printer) or PR: (paper tape reader) or CR: (card reader) or RJ: (symchronous line) The following are legal directives: ST: - Stop TRAN. SI: - Force a signon to the remote machine. NS: - Start without a signon. EF: - Force an end-of-file to the remote machine. BI: - Do the transfer in BINARY mode. If a command is typed incorrectly, the message 'FORMAT?' is output and the prompt is re-issued. Using the form 'FILE/DEV,FILE/DEV' causes a concatenation of the two input streams into the output file or device. SYNCHRONOUS LINE HANDLING
1) TRAN will normally sign-on automatically when the first reference to 'RJ:' is made, the message 'SIGNED ON' is output, then it obeys the request. 2) A number of files may be sent down the line without an end-of-file being sent. An end-of-file is automatically sent on a change of mode to receiving, or may be done explicitly by the directive 'EF:'. 3) In receive mode, non-transparent files (i.e. listing file etc.) are assumed. If a binary file is recieved then TRAN will ignore the current command and request a file name to write the binary file to. 4) A file called 'signof' should be transmitted to close down the link.
C) THE FILE LISTING PROGRAM: FLIST This program can be used to perform the following functions: 1. List the disc file directory a) unordered b) ordered alphabetically 2. Destroy files 3. Rename files 4. Search for the existence of specific files or groups of files COMMANDS When the program expects a command the symbol '>' is output E.g. >A Command Description A : Give an alphabetic listing of the file directory F : Gives an unordered listing of the file directory L : Look for a file or group of files. Fails if not found D : Destroy a file or group of files. Fails if no file or group of files. R : Rename a file. Fails if new file name exists B : List size of a file or group of files. To get a group of files we use the 'wild' character '?' to stand for any other character. If it is the last character input then it is propagated right i.e. 'F?' is expanded to 'F?????' EXAMPLES >L MASK:PRT001 Checks if file PRT001 exists >L MASK:P? Lists all files beginning with P
>L MASK:P?T? Lists all files beinning with P and third letter is an R >D NAME:PRT001 PRT001?:Y If a 'Y' is input then file is destroyed otherwise not. >D NAME:PRT? PRT001?N PRT003?Y Destroys file 'PRT003' but not 'PRT001' or 'PRT004' PRT004?N > >R OLD FILE:TEMP Re-name file 'TEMP' to 'FLIST' NEW FILE:FLIST
D) ARCHIVE PROGRAM OBJECT FILE: ARCHY This program reads and writes files to DECTAPE in a format compatible to the 'local' format used on the ERCC PDP15 and the PHYSICS DEPT. 11/45. OPERATING PROCEDURE Archive indicates readyness to accept a command by typing:- 'ARCH?' The user should mount a DECTAPE on unit 0 before issuing the first command. The user by typing the appropriate command on the keyboard may:- a) Zero a DECTAPE. b) Print out the directory of a tape. c) Archive a file to DECTAPE d) Restore a file to disc from DECTAPE. e) Delete a file on the DECTAPE f) Stop the program A command consists of:- DIRECTIVE (cr) or DIRECTIVE (space) FILENAMES (cr) A DIRECTIVE consists of the first two letters of the command verb. FILENAMES is one or more file names seperated by commas. COMMAND DESCRIPTION a) ZERO a dectape FORMAT: ZE (cr) This command will delete all the files on a DECTAPE, reclaiming the space. It must be used when a DECTAPE is used for the first time. b) DIRECTORY FORMAT: DI (cr) This command generates a listing of the DECTAPE directory on the teletype in the form:- FILE NAME xx nnnnnn mmmmmm
Where 'xx' is the LENGTH of the file, 'nnnnnn' is the first block the file occupies and 'mmmmmm' is the last block. c) ARCHIVE FORMAT: AR (space) FILENAMES (cr) The file(s) is written out to the DECTAPE 1) If the file does not exist (on the disc), the message 'FILE DOES NOT EXIST' is output. 2) If it is already archived on the DECTAPE the message 'FILE ALREADY ARCHIVED' is output. 3) If the DECTAPE is full, then 'DEC TAPE FULL' is output. d) RESTORE FORMAT: RE (space) FILENAMES (cr) The file(s) is written from the DECTAPE on to the disc (with the same name). 1) If the file exists on the disc, it is overwritten. 2) If the file can't be found on the DECTAPE, the message 'FILE NOT ON ARCHIVE' is output. e) DELETE FORMAT: DE (space) FILENAMES (cr) The file on DECTAPE is destroyed The message 'FILE DOES NOT EXIST' is output if the file can't be found. Note: This command frees the directory entry, but does not reclaim the file space on the tape unless it was the last file to be put on the tape. f) STOP FORMAT: ST (cr) The program terminates
EXTERNAL ROUTINES AVAILABLE UNDER MUSS11 A %SPEC must be given for each routine. 1) %EXTERNALROUTINESPEC WAIT(%INTEGER ticks) This routine suspends the program for the given number of ticks (1 tick = 1/50 sec). If ticks=0 then it is suspended until the operator releases it with 'CO PROG'. 2) %EXTERNALROUTINESPEC NAME(%BYTEINTEGERARRAYNAME KEY) This routine reads in a file name from the currently selected input stream [up to 6 chars - '0'-'9' and 'A'-'Z']. The array should be declared in the form %BYTEINTEGERARRAY KEY (-1:9) [an immediate return is made if KEY(1)=99]. 3) %EXTERNALROUTINESPEC DEFN(%BYTEINTEGERARRAYNAME BUFFER, NAME, %INTEGER STREAM) This routine sets up a STREAM or SQFILE definition. %BYTEINTEGERARRAY BUFFER(0:530) is for the internal use of the stream/SQfile %BYTEINTEGERARRAY NAME (1:6) is a file name (see %ROUTINE NAME) STREAM is the required stream. This routine should be called prior to using a disc file e.g. DEFN(BUFF, KEY, 2) SELECT OUTPUT(2) WRITE(I,5) etc. 4) %EXTERNALROUTINESPEC WRIT(%INTEGER X) This routine writes a positive integer on the current output stream with no leading space.
5) %EXTERNAL %INTEGER %MAP %SPEC COM(%INTEGER ELEMENT NO) Within the supervisor there is a communication area to allow programs to pass information to each other and to control the running of certain 'automatic' programs. The area is 21 words long - designated as 0:24 (octal). The MAP COM allows values to be set into the elements of the area, and be retrieved from it. Although the exact use of each word will be different in each system, the following words are reserved:- word 1: - used for cpu timing (by the program CPU) (octal) 2: - ditto 3: - holds the day (if set by SETIM) 4: - holds the month (ditto) 5: - holds the year (ditto) 21: - used by ACARD, the card reader spooling program. 22: - used by APLOT, the plotter spooling program 23: - used by ALIST, the line printer spooling program 24: - used by A2780, the 2780-emulator spooling program. The MAP may be used in a number of ways, for example:- %INTEGER I I = COM(10); ! read the value of word 10 COM(10) = 2; ! set word 10 to 2 or %INTEGERNAME COMWORD; %INTEGER I COMWORD == COM(10); ! point COMWORD at word 10 I = COMWORD; COMWORD = 2; ! get, then set word 10 6) %EXTERNAL %ROUTINE %SPEC DA(%INTEGER MODE, BLOCK, ADDRESS) This routine is used to read or write blocks to the DISC or DECTAPE. mode = 0 - READ a block from the DISC. = 1 - WRITE a block to the DISC. = 2 - READ a block from DECTAPE. = 3 - WRITE a block to DECTAPE. BLOCK - device block number. ADDRESS - address of 256 word buffer. The routine may also be called with '%INTEGERNAME ADDRESS', for example:- %INTEGERARRAY A(0:255) DA(0, 500, A(0)) Which will READ block 500 into A.
6) %EXTERNAL %ROUTINE %SPEC FIDENT(%INTEGER TYPE, %C %BYTEINTEGERARRAYNAME KEY) This routine provides information about groups of file names. It is used when it is necessary to automatically allocate file names of a given form, or when groups of file names are being processed. The first four letters of each DISC file are matched against the four letters provided by the caller in KEY(1), KEY(2), KEY(3) and KEY(4). The final two letters of a matching file are then treated as a number, files in the range 0 to 40 are used, the actual use depending on TYPE. TYPE = 0 - returns the name of the first existing file type = 1 - returns the next free file name. The resultant file name is passed back in KEY(1) - KEY(6). An error return (KEY(0)=-1) is made if 1) there is no file (TYPE=0) or 2) no free file name exists (TYPE=1). For example - all files of the type 'PRITXX' can be obtained by a program, one at a time by calling FIDENT(0, A) where A(1) to A(4) are set to 'PRIT'. It should be noted that each file should be 'renamed' or 'destroyed' after use or FIDENT will pick it up again when recalled. The ARRAY should be declared at least (0:6), or if RENAME is going to be called then (-1:6). 7) %EXTERNAL %INTEGER %FN %SPEC RENAME(%BYTEINTEGERARRAYNAME FROM, TO) This function renames the file.'from' to the file 'TO'. The result is zero if the rename succeeds, non-zero if 'FROM' doesn't exist or 'TO' does exist. The ARRAYS should be declared :- %BYTEINTEGERARRAY <name> (-1:6) The first two elements are used by 'RENAME', the file name is in elements one to six.