USER MANUAL FOR DEIMOS B. GILMORE AUGUST 1976
CONTENTS TITLE PAGE General features 3 System commands. 4 The EDITOR. 7 The IMP compiler. 8 The LINKER. 9 Library manipulation. 11 The debugging program. 12
general features (this section has not been written yet)
SYSTEM COMMANDS All commands given to the system are interpreted by the command language interpreter (CLI). The CLI indicates its readiness to accept a command by typing the prompt '>' and '<' overlaid. If a program is running, the CLI can be invoked by typing <escape>, the command prompt should then appear. The input to the CLI has two forms, either:- A) A FILE NAME, followed by 'stream definitions' or B) A COMMAND VERB, possibly followed by parameters a) a file name If a FILE NAME is specified, that file is loaded and the program contained in it is entered. If the file does not exist, or does not contain a program, the message '*NO FRED', where FRED is the name of the file, is output and the command prompt is re-issued. The 'stream definitions' are input in the form:- <input 1>,<input 2>,<input 3>/<output 1>,<output 2>,<output 3> <input 1> etc, each represent a 'stream definition'. A 'stream definition' is of the form:- .TT - which is either input or output from a terminal. .LP - output to a line printer <any other devices on the system, specified in the same way.> <a FILE DEFINITION> A FILE DEFINITION is in the form:- <unit number>.<file name>(<file system number>) The <unit number>, currently, is either '0' or '1' and refers to the physical disc drive. If neither is specified, '0' is assumed. The <file name> consists of an alphanumeric string, which must be preceeded by a letter, of up to 6 characters in length The <file system number> is the file system that the file comes from, or is created in. If none is specified, the users own is used (see the command LOGON) eg FRED - the file called FRED on unit 0 in the users file system. 0.FRED - the same. 1.FRED - The file FRED is taken from disc unit one. FRED(0) - the file FRED from file sys. zero (the systems own one) 1.FRED(25)- the file FRED from disc unit one and file system 25 (octal). .TT - the terminal, input if on the left hand side, output if on the right hand side. The stream definitions are linked into the input and output streams available to an IMP program, for example, if the program FRED is run with the following command:- FRED F1,F2/O1,O2,.TT then input stream one, used by calling 'SELECT INPUT(1)' is mapped to the
file 'F1'. A 'SELECT OUTPUT(2)' will send output to the file O2', and 'SELECT OUTPUT(3)' will send the output to the terminal. If a field is left blank, as with <input 3> in the above example, the stream is mapped to 'NULL' - which causes an 'end of file' signal on input and on output, all the output is thrown away. Input stream zero and output stream zero are always mapped to the users terminal. FURTHER EXAMPLES PROG .TT - uses one input stream '.TT', no output stream (apart from zero) is defined. PROG FILE - will read from a file called FILE on stream one. PROG /FILE - no input streams defined (apart from zero), will write to a file called FILE after a 'SELECT OUTPUT(1)'. PROG FILE/FILE - this will read data from a file called FILE and create an output file called file NOTE: When a program does the first 'SELECT OUTPUT(N)', where a file is mapped to that stream, the system will create a temporary file (FILE# in the previous example). When the program stops, or calls 'CLOSE OUTPUT', the original file (FILE) is destroyed and the temporary file (FILE#) RENAMED to that name (FILE). b) a command verb There are currently six available system commands, they are:- a) LOGON - used to 'logon' to a file system. b) TASKS - List the running programs on the system. c) HOLD - Stop a task executing. d) FREE - Release a 'HELD' task. e) KILL - Stop a program in a controlled manner. f) PURGE - Immediately remove a task from the system. a) logon This command is called in the form: LOGON nn where 'nn' is a two digit octal number, representing the users file system number.
b) tasks This command has no parameters, it lists out the tasks on the system in the form:- <task name> <task number> <task state> The states of a task are as follows:- STATE MEANING 000001 Task is in the WAIT state. 000002 Task has executed a 'POFF'. 000010 Task is on a CPU QUEUE awaiting execution. 000020 The task is in the 'RUN' state. 000200 The task has been 'HELD'. c) hold This command is called in the form: HOLD xxxx where 'xxxx' represents the name of a task running on the system. If the task is currently executing, it is suspended. If the task is waiting for a message, it will be suspended when it next requests the CPU. d) free This command is the converse of HOLD and is called: FREE xxxx it places the task 'xxxx' back on the CPU. e) kill This command is called in the form: KILL xxxx it has the effect of sending the task called 'xxxx' a message to stop, the task should then stop in a controlled manner tidying up all its streams. f) purge This command is called in the form: PURGE xxxx it has an immediate effect, completely removing the task from the system, no attempt is made to tidy the open streams. This command should not normally be used to stop a program, but MUST be used to clear a program from the system that has crashed with an 'ADDRESS ERROR' or a 'SEG FAULT'. NOTE: If a program is still running, HOLD must be called before either KILL or PURGE is used.
THE EDITOR The EDITOR is a PDP11 version of the COMPATIBLE CONTEXT EDITOR. For general information on the Editor, see the USER GUIDE of the COMPATIBLE CONTEXT EDITOR by H Dewar. The command for calling the Editor has three possible forms as illustrated below: E /TEST - to produce a new file called TEST. E TEST - to edit an existing file called TEST E TEST/TEST2 - to produce a new file called TEST2 from an existing file called TEST. NOTES 1) The Editor prompts '>' when it is ready to accept a command and ':' when it expects a line of input (COMMAND: GET). 2) This version of the Editor uses a 'window' of the file, this will not normally be apparent, but it does mean that the command 'M-*' will not necessarily return right to the top of the file.
RUNNING THE IMP COMPILER The IMP compiler is a three pass compiler to which a fourth pass, a LINKING phase, is automatically called for %BEGIN .. %ENDOFPROGRAM programs There are four main ways of calling it:- IMP A/B - which compiles source file 'A' to object 'B' IMP A/,L - which only does one pass and creates a listing file 'L' (note: 'L' can be either a filename, '.TT' or '.LP'). IMP A/B,L - which creates both an object file and a listing file. IMP A,.TT/B - this form is used to change the LINKER defaults, for more details of the defaults, see the section on the LINKER. NOTES 1) At present, the program 'IMPX' must be run to avoid the linking phase for %EXTERNALROUTINE files. In this case, the file 'B' above is the compilers third pass output. 2) The test compiler is accessed by running the program 'NIMP'. 3) The first pass automatically uses a file of '%SPECS' called 'PRIMS' which is taken from the system file system. 4) The first pass creates a temporary output file 'O' for use with the econd pass. The second pass creates 'O2' and 'O3' and the third pass 'OY'. 5) The output from the third pass 'OY' is useful. It can be used as input to the programs 'RECODE' and 'VIEW' if it is necessary to de-compile the compiler output. If the linker is to be run as a seperate 4th pass, the file 'OY' is used as its input.
THE LINKER The LINKER is normally run automatically as a fourth pass to the IMP compiler. It is run individually by typing one of the two following forms of command to the COMMAND LANGUAGE INTERPRETER. LINK A/B or LINK A,.TT/B Both of the above commands take the file 'A', which must be the output from the third pass of the compiler and create a runnable file 'B'. The second form of the command overrides the standard LINKER defaults, the LINKER prompts for the new data as follows (defaults in brackets):- NAME: - up to 4 characters are typed in as the TASK NAME for the program (the first four characters of the object file name are used). STACK: - the desired stack size (in octal bytes), excluding the GLA (default: 14000). STREAMS: - the max number of input and output streams that the program is going to use, excluding INPUT and OUTPUT (0) (default: 3). If a program has external references in it, the LINKER will first attempt to satisfy then using 'LIB000' in the users file system. If there are still unsatisfied references, the LINKER will look at 'LIB000' in file system zero (the system file system). For more information on LIBRARIES, see the section on them. A sample LINKER output map is given below:- CODE: 040000 GLA: 140020 XREF:PON POFF PONOFF MAPVIRT XDEF: 040000 #GO FILE:SHARED CODE: 046506 GLA: 140752 XREF: 004000 RUN XDEF: 022656 PON XDEF: 022700 POFF XDEF: 022736 MAPVIRT XDEF: 023006 MAPABS TOTALS: CODE = 006506 GLA/STACK = 002016 The TASK NAME of the program (DBUG) is printed along with the base address for its code (040000) and its GLA (140020). The 'XREF' refers to 'external references' from that section of code (in this case they are all declared by the system). The 'XDEF' is an 'external definition', in this case '#GO' which is the entry point for the main program. The 'FILE:' indicates that the LINKER has loaded an object file , it specifies its name (SHARED) and the start address of its code (046506) and GLA (140752) sections. The list beneath that is the 'external definitions', in this case entry points that the file contains. The last line gives the overall code length of the program (006506) and the total size of the GLA and the declared stack.
If any references are left undeclared, the LINKER will list them along with an 'UNDEFINED REFERENCE' message. If the LINKER attempts to load a file that contains an entry point that has already been loaded, the message '*DOUBLE DEF' is output and the LINKER stops.
LIBRARY MANIPULATION When the LINKER finds an EXTERNAL REFERENCE in a program file it will attempt to satisfy the reference by:- 1) Searching the library 'LIB000' in the USER file system, loading object files as necessary, then 2) Searching the library 'LIB000' in the SYSTEM file system (zero). There are three programs currently available to the user to manipulate libraries, they are:- 1) NEWLIB - creates a new library file. 2) INSERT - Inserts the entries of an object file into a library. 3) INDEX - lists the contents of a library. NOTE: Each of the programs will manipulate libraries other than 'LIB000', but at present the LINKER will not link them. 1) newlib The command for using NEWLIB is as follows:- NEWLIB /LIB This command will create a new library file 'LIB', if it already exists the old copy is destroyrd. 2) insert There are two main forms of this command as follows: INSERT TESTY,LIB/LIB and INSERT TESTY,LIB/LIB2 The first command will add the entries of the file called TESTY into the library called LIB. The second command will add the contents of the file called TESTY into the library called LIB, creating a new library called LIB2. 3) index The form of this command is as follows:- INDEX LIB This command will print out all the entries in the library file 'LIB'
DEBUGGING PROGRAM OBJECT: DBUG This program is used as an aid to debugging programs, it will mormally be 'linked' to a running program on the system using the command 'T' (for details see later), all accesses to locations will then be made in that programs virtual memory. It may be used to:- 1) SET and CLEAR breakpoints 2) Dump out the PSECT, REGISTERS and/or the IMP STACK. 3) EXAMINE and CHANGE locations in core. 4) DUMP general areas of core. DEBUG indicates its readiness to accept commands by typing 'DEBUG:'. The following commands may be used. T - Set Task number of program to be debugged. B - Set breakpoint. C - Clear breakpoint. N - Set a new program code base. R - Dump the REGISTERS. P - Dump the PSECT. I - Dump the IMP stack. A - Do 'P', 'R', and 'I'. D - Dump an area of core. O - Change the output device. W - WAIT DEBUG. S - Stop DEBUG. ? - Print options. In addition to these commands, there is an implied command, activated by typing an octal digit, that enters the location examination/change part of DEBUG. A detailed description of each command follows. T - SET TASK NUMBER The prompt 'TASK ID:' is output and the (octal) ID of the program to be debugged should be entered. The TASK ID of a running program may be obtained by typing the command 'TASKS' to the command language interpreter. NOTE: Only the commands 'T', 'N', 'O', 'S' and 'W' may be used before 'T' is used for the first time.
B - SET BREAKPOINT The prompt 'ADDR:' is output, the reply is the RELATIVE address (wrt the start of the program) of the desired breakpoint. Debug will remember the contents and place a 'BR ' in the location. This will cause the program to loop when it executes that instruction. Debug replies: BP: n ADDR: n2 CONT= n3 - where 'n' is the breakpoint number (between 0 and 20), 'n2' is the virtual address, and 'n3' the original contents. The message 'BP TABLE FULL' is output if more than 21 breakpoints are used. See the command 'N' for setting breakpoints in external routines. C - CLEAR BREAKPOINTS Prompts 'NO?'. The breakpoint number should be typed. 'A' or '-1' is typed if ALL the breakpoints are to be cleared. If the specific breakpoint has not been set, the message '?' is output. The original contents are replaced. N - SET A NEW PROGRAM CODE BASE Prompts 'NEW PROGRAM CODE:'. Reply giving the new address. This command is useful for programs using external routines. To set a breakpoint in an external routine, the code base is set to that of the external routine, as printed out by the LINKER, and the relative address specified. This does not effect any previously set breakpoints. R - PRINT REGISTERS. This command prints the registers of the nominated task. The LOCAL NAME BASE (LNB) for the outer level is also printed.
P - PRINT THE PSECT The PSECT (own system variables) of the nominated task is printed. The command :- 1) Prints the name of the task 2) Prints the state of the task. 3) Indicates whether there are messages queued. 4) Calls 'REGISTERS' to dump the registers out. 5) Prints the contents of the segmentation registers in the form:- <REGISTER NUMBER> <ADDRESS> <LENGTH> <ACCESS> I - PRINT THE IMP STACK The entire IMP STACK is printed on the output device. NOTE: The GLA of the program is held at the low address end of the stack, the IMP stack (ie the SP stack) starts at the high address end and works towards the low address end. is not the same as the start of the stack. A - PRINT ALL The command executes a print psect (P), print registers (R) and the IMP stack (I). This command is useful for dumping all the relevant information about a program onto the line printer (see command 'O'). D - DUMP AN AREA OF CORE Prompts 'FROM:' and 'LENGTH:'. Both numbers should be typed in octal and the area of core from 'FROM' to 'FROM+LENGTH' is output. NOTE: 1) On all the dumps 'ZEROES' is ouput if one or more entire line contains zero. 2) An ISO equivalent is printed on the RHS of the dump. O - CHANGE THE OUTPUT DEVICE Prompts 'STREAM:'. The reply is used in the form 'SELECT OUTPUT(N)' for the output of commands R,P,I,A and D. By calling 'DBUG' in the form:- DBUG /L or DBUG /.LP etc the output may be directed to the file 'L' or to the line printer.
W - WAIT DEBUG This command is used to suspend DEBUG if it is necessary to input to a program on the same teletype. It is restarted by (ESCAPE) FREE DBUG S - STOP DEBUG Debug halts. Note: all breakpoints are cleared. IMPLIED COMMAND TO EXAMINE/CHANGE CORE ADDRESSES This command accepts the following instructions:- Note 'N' and 'M' represent numbers input in octal. N : prints contents of N. N+C : prints contents of (N+ program base). N+I : prints contents of (N+ IMP STK base). N+RM : prints contents of (N+REGISTER M) N(+ options)=m : puts M into N eg: DEBUG:100 (cr) - will print contents of locn 100. DEBUG:100+R5 (cr) - will print contents of 100 on from reg. 5. DEBUG:100+R5=200 (cr) - ditto, except plants 200. NOTES An '*N' at the end of the command will cause the following 'N' locations to be dumped out ('N' may be negative). '+' or '+=M' may be entered as a new command, this takes the last location used and steps it up by 2 (-2 if '-' is used).