====== Enter HACTRN ======

__**or "Survival DDT"**__

To work in ITS, a knowledge of DDT is essential. I found some good documentation on DDT monitor mode commands that I'll try to whip into another tutorial.

Source: [[http://www.sigfs.org/its-reference/its-reference-1.5.html|D. Eastlake, R. Greenblatt, J. Holloway, T. Knight, S. Nelson. ITS 1.5 Reference Manual. Massachusetts Institute of Technology Artificial Intelligence Laboratory. July 1969. <http://www.sigfs.org/its-reference/its-reference-1.5.html> accessed 4 June 2010.]]

Other references:

  * [[http://victor.se/bjorn/its/ddt.html|DDT Primer and Reference Manual. Victor.se. <http://victor.se/bjorn/its/ddt.html> accessed 4 June 2010.]] HTML version of ITS files "INFO;DDT >" and "INFO;DDT ORDER".
  * [[http://victor.se/bjorn/its/luser.php|A Luser's Guide to ITS. Björn Victor. Victor.se. 24 November 2009. <http://victor.se/bjorn/its/luser.php> accessed 4 June 2010.]]


<code>
Chapter 7 
DDT
See also section 0.4.1. 


7.1  Introduction
DDT is a general purpose machine language debugging program that has been extensively modified to act as a supervisory procedure in ITS. It is automatically loaded by ITS [Sec 1.1.1] when a user informs ITS of his presence at an idle teletype. All further requests of the system by the user, until he logs out, are by means of trapping instructions [Sec 1.2] executed for the user, possibly as a result of characters he types in, by DDT or procedures inferior [Sec 5.1] to and under the control of DDT. The current binary of DDT exists as the file "@ HACTRN" on device SYS [Sec 3.1.3]. For historic reasons, a top level DDT is known as a HACTRN (pronounced hack-tran). 

The initial command structure of DDT provided single character debugging commands of limited mnemonicity. This structure was badly strained by the introduction of time-shared related commands. Then a new set of multi-letter commands was introduced. This set was expanded with the thought of providing all the most frequently used commands that did not relate to machine language debugging. Since a beginning or transient user might wish to use only these mnemonic commands, a mode switch was added to DDT. There is a "monitor mode" in which only the multi-letter commands are available besides a few interrupt level commands that are unaffected by mode. In "DDT mode" all of the single character debugging commands are also available. 

Section 7.2 below gives more information on monitor mode and describes almost all monitor mode commands. Section 7.3 describes the few interrupt mode commands in HACTRN and section 7.4 explains how DDT tells the user about error conditions. The information in these three sections should be more than enough to enable extensive use of ITS, particularly the conversational and interpretive programs avaiable under it (such as TECO, LISP and STRING). 

The remaining section (7.5) gives information on finding out about DDT mode commands. These would be important to someone developing a machine language program. 


7.1.1  When DDT Starts
When a new copy of DDT is started, it types out certain useful information. If output is to a GE Datanet 760 console, it first clears the screen. Then it types out "DDT.xxx." where xxx is the version number of the DDT so that bugs can be correctly matched to version. Then, if ITS is in the system going down mode [Sec 6.5.2], a message indicating its remaining life span is output. Finally, if a file named "SYSTEM MAIL" is found on device SYS [Sec 3.1.3], it is typed out. 


7.2  Monitor Mode Commands
When in monitor mode [Sec 7.1], DDT indicates its readiness to accept a command by typing out a ":". At this point the user can type a series of letters followed by a break character (normally space or carriage return). DDT looks up this symbol (or its first six letters if longer) in a table of monitor mode commands. A user may also type a comment that will be ignored by DDT in or before this string by beginning and ending it with an "$" (alt.-mode). No "$"s may be embedded in the comment. If the symbol is found, control is transferred to a routine associated with it which may perform immediate actions or wait for more information to be typed by the user. At any time during the typing of a command, the user can abort and start over by typing a rubout. 

If the string (say "llll") after the ":" is not found in DDT's command table, it looks for a file called "TS llll" on device SYS [Sec 3.1.3]. If not found an error comment [Sec 7.4] to that effect is output. If found, an inferior procedure is created, this file loaded into the inferior core image, and it is then started. The effect is as though the following [Sec 7.2] were typed: 


:JOB llll 
:LOAD SYS: TS llll 



except that symbols for the program are not loaded into DDT from the file and the normal effects of :LOAD on the current file and device names in DDT is absent. 


7.2.1  Logging In and Out
:LOGIN uname 

This command takes as its argument the "uname" that the user wishes to log in with [Sec 6.2]. A "?" will be typed out and the command will be ineffective if someone is already logged in with that name. For ease in accessing his disk files, a user should use a consistent UNAME. 

At the time the user logs in, DDT looks for a file names "uname MAIL" on device COM [Sec 3.1.3]. If not found, no action is taken by DDT. If found, DDT types it out, deletes the file "uname OMAIL", if any, on device COM, and renames the "uname MAIL" file as "uname OMAIL". 


:LOGOUT 

This command expunges all of the user's procedures from the system including the user's HACTRN [Sec 6.1]. The teletype the user was typing on will become free and a message to that effect will be typed out on it by the system job [Sec 6.5]. DDT also deletes the file "uname OMAIL" on device COM at this time (where "uname) is the name the user logged in as). 


7.2.2  Inter User Communication
:MAIL uname string...C 

This command takes as its first argument the user name of someone who uses ITS and as its second argument a string terminated by a "C". The command prefixes the string to the file "uname MAIL" on device COM [Sec 3.1.3] if such a file exists. If no such file exists, one is created with the string as its contents. This file is presented to the specified user when he logs in [Sec 7.2.1]. The user can rubout individual characters while typing the string or cancel the command by typing enough rubouts. 


:BUG string...C 

This command is intended for use in reporting bugs in systems software. It is identical to ":MAIL SYS string...C". 


:SEND uname string...C 

This command takes arguments like :MAIL above but attempts to send the message string supplied to the user specified in a direct manner so that, if he is logged in, his HACTRN will type the string out on his console. If he is not logged in, DDT will type out "(MAIL)" and perform the actions specified under :MAIL above. 


:GAG number 

This command enables a user to gag messages that other users may attempt to send the him with :SEND (above). It takes a numeric argument that is bit decoded as per the table below. 


Bit Source 
1.1 Other user's inferiors. 
1.2 Other user's HACTRN's. 
1.3 Your inferiors. 
1.4 Your HACTRN (yourself). 



If a bit is on it inhibits messages from the source listed. If off, messages are not inhibited. The initial state is :GAG 1. 

The current implementation gives no way to tell if a message sent was gagged by the intended receiver. 


7.2.3  Inferior Procedures
:JOB {jname} 

This command may be followed by an optional job name [Sec 5.1]. If there is an inferior procedure with this JNAME it will be selected by HACTRN as its "current job" (possibly attaching a disowned tree [Sec 5.1.2]). Many commands in DDT affect the current job only as this changes infrequently and one would not want to respecify it with each command. If there is no inferior with the specified name, one will be created [Sec 5.1.1] and selected as the current job. 

The job names SYS and PDP10 are special. The first allows the user limited access to absolute core. The second allows full access to the core image of the PDP-10 [Sec 3.4.2.1] to one user. 

If no argument is supplied to :JOB it attempts to select some job different from the current one and types out "jname$J" to inform the user it has selected job "jname". If there is no current or other job, nothing it typed out. If the current job is the only inferior of HACTRN it will be reselected. If other inferiors exist one is selected in such a way that all inferiors are cycled through by successive :JOB's with no argument. 


:KILL 

This command obliterates [Sec 5.2.1] the current job and all its inferiors if it is an immediate inferior. If not an immediate inferior the variable space for it in HACTRN is reclaimed and logical pointers to it obliterated. In either case a :JOB with no argument is then simulated to minimize the time during which there is no current job. 


:LISTJ 

This command lists all of the inferiors of which HACTRN is aware. An "*" is printed before the current job, if any. After each job will be a character indicating its state as follows: 


Character Status 
- Just created or loaded. 
R Running. 
P Procedable from random interrupt. 
Bn Procedable from breakpoint n [Sec 7.5]. 
W Interrupt/message to HACTRN pending. 



After this letter is the user index of the procedure (see section 8.2, mode N). An example of :LISTJ output appears in Appendix G. 


:DISOWN 

This command disowns [Sec 5.2.2] the current job, deselecting it, expunging all information about it in HACTRN, and simulating a :JOB with no argument. 


:LOAD {file specification} 

This command attempts to load a file into the current job. HACTRN has a current device, system name [Sec 2.2.3], and pair of file names which it will use if nothing is specified after a command taking a file argument. This current file is initially device DSK, file name "@ BIN", and the system name the user logged in as [Sec 7.2.1]. Various fields can appear in the file specification distinguished by their terminating character. A "dev:" field sets the device to "dev". An "sname;" sets the system name to "sname". A field terminated by a space or carriage return (the later indicating the end of the file specification) is treated differently depending on how many of this type of field have been seen. The first, if any, such becomes the first file name. The second, if any, becomes the second file name. A third, if supplied, becomes the device name (as if followed by a ":") and indicates the end of the file specification. 


:DUMP {file specification} 

This command dumps the current job as a file optionally specified as in :LOAD above. 


:START {number} 

This command starts the current job, giving it control of the user's console [Sec 3.2.1.1]. If no argument is supplied it is started at the last place it was started with a :START. if not :START'ed before then at the assembled-in starting address that was read in as the program was loaded. If no starting address was supplied a "?" is typed out. 

If a numeric argument is supplied, the job is started at the specified address which is stored away for future :START's without argument. 


:CONFIX{UE} 

This restarts the current job if it is stopped and gives it control of the user's console. It can be used to continue after returning to HACTRN with a "Z" [Sec 1.1.2]. 


:PROCED 

This command restarts the current job if it is stopped but leaves HACTRN in control of the user's console. Using this command the user can easily get several inferiors running at the same time. 


7.2.4  Files and Input-Output
:PRINT {file specification} 

This command treats a file as ASCII characters and prints it out. It accepts an optional file specification as described under :LOAD [Sec 7.2.3] above. 


:DELETE {file specification} 

This command deletes [Sec 2.4] a file. It takes an optional file specification as described under :LOAD [Sec 7.2.3] above. 


:LISTF {device name} 

This command lists the files on HACTRN's current device or the device specified as an argument [Sec 2.2.1]. 


:FLAP number 

This command must be followed by the number of a DEC tape drive. It causes the tape on the specified drive to by physically demounted and its directory to be excised from ITS [Sec 3.1.2.1]. 


:LINK {file name pair} sname; fnam1 fnam2 

This command creates a link [Sec 3.1.1.1] under HACTRN's current system name to the file "fname1 fname2" under system name "sname". The link's file name is also "fnam1 fnam2" unless the optional file names shown above are supplied. 


7.2.5  The "Control-P" Feature
DDT has a feature which is designed to reduce the need to repeatedly type the same or very similar file names at different systems programs. For historic reasons this is called a "Control-P" feature. This feature is implemented using a block of four locations in DDT. These are deposited in the core image of a newly loaded inferior by the execution of certain DDT mode [Sec 7.5] commands and certain of the commands explained below. The locations set in an inferior and their significance are as follows: 


Location Significance 
50 First file name. 
51 New second file name. 
52 Current second file name. 
53 Old second file name. 




:CR 

This command reads in a file name as for :LOAD [Sec 7.2.3]. It puts the first file name read in the DDT word to be deposited in location 50. It puts the second file name in the DDT word to be deposited in location 52 and the second file name incremented in the word to be deposited in location 51. It clears the word to be deposited in 53 and finally loads, deposits in 50 through 53, and starts a copy of TECO, the normal ITS editing program, as for a :TECO [Sec 7.2] except for the depositing in 50 through 53. 


:ED 

This command increments the file name in the location to be put in 51 and then puts the incremented file name back after moving what was there into the location to be put in 52 and similarly moving that word into the location to be put into 53. it then loads, deposits in, and starts a copy of TECO, the normal ITS editor, as for a :TECO [Sec 7.2] except for the depositing in 50 through 53. 


:ST 

This command simply reads a file name and does the same thing with it as :CR (described above) except it does not load or start a TECO. 


7.2.6  Miscellaneous
:? 

This command lists all important monitor mode commands with a short explanation of each. An example is shown in Appendix G. 


:DDT 

This command switches HACTRN to DDT mode [Sec 7.1]. 


:MON 

This command switches HACTRN to monitor mode [Sec 7.1]. 


:XFILE {file specification} 

This command reads the file, optionally specified as for :LOAD [Sec 7.2.3] above, and, treating it as ASCII, executes it as HACTRN commands. 


:SYNLOD 

Mostly useful in conjunction with DDT mode [Sec 7.5] commands, this command loads symbols only for the current job. It takes an optional file specification as for :LOAD [Sec 7.2.3] above. 


:ERR 

Mostly useful in conjunction with DDT mode [Sec 7.5] commands, this command interprets the last quantity typed out by HACTRN as a .STATUS [Sec 2.5] word using the ERR device [Sec 3.4.4]. 


7.3  Interrupt Level and Context Tree Commands
There are six single character commands to HACTRN that are interpreted at its interrupt level or at its top level in a manner independent of and not affecting the context in which they occur. They are presented in alphabetic order below. Two provide the user with the ability to "silence" any particular output of his HACTRN and abort it from a hung state. The remaining four control where HACTRN's output goes. 


Character Effect 
B Attempts to seize the line printer [Sec 3.2.2]. If successful, causes HACTRN output 
 to be printed. 
E Releases the line printer [Sec 3.2.2] and stops HACTRN output from being printed. 
G Interpreted at the interrupt level, this command causes HACTRN to abort from 
 whatever it is doing, type out "QUIT?", and wait for new commands. This command 
 should only be used when necessary (ie HACTRN seems to be permanently hung 
 up) as there is almost no protection from interrupting out of embarrasing places where 
 variables are out of phase, etc. All buffered type in and out is also reset [Sec 2.7.2]. 
S This character is interpreted at both interrupt and top level. It inhibits HACTRN output, 
 also doing a type out reset [Sec 2.7.2], between these two interpretations. Thus "S" 
 is a much less drastic step than "G" (above) to be used when the only trouble is that 
 HACTRN is being somewhat long winded. It re-enables output when HACTRN gets 
 around to it at the top level. 
V This command causes HACTRN output to be typed. It is the initial state. 
W This command stops HACTRN output from being typed. 



7.4  Error Comments
DDT used to have two error comments, "U" and "?". The first of these is typed out when an undefined symbol is evaluated, usually when it is terminated by a non-symbol-constituent. The second was typed out for all other errors. it has been significantly augmented. 

Errors in attempting to open, rename, or delete a file are indicated by the comment produced by the ERR device [Sec 3.4.4] followed by the symbolic name of the device and a question mark. In the case of an input-output error interrupt from an .IOT or .OPER, a special check is made to see if the error is device full on the input-output channel on which dumps are written. If so, the partial dump is deleted and an appropriate message output. Otherwise, the following error comment is output. 

n, m, p, IOC? 

where n is the error number, m the input-output channel on which it occurred, and p the location of the offending .IOT or .OPER. For other errors indicated by interrupts the following is output: 

n, p, INT? 

where n is a number with the interrupt bits on and p is the location interrupted from. 

Other error comment listed in the following table: 


Output Meaning 
NML? Interrupt from unknown inferior. 
TMJ? Attempt to have too many inferiors. 
CKS? Checksum error on load. 
EOF? Unexpected end-of-file on read. 
CFT? Unable to assign console to inferior. 
COR? Can't get more core. 
JOB? No current job. 
UNF? DEC tape unflappable. 
DSK? Disown failed. 
TMS? Too many undefined symbols. 
ILUUC? Illegal UUO executed in DDT. 
LOGIN? You are not logged in. 





7.5  DDT Mode Commands
Monitor mode commands may also be used in DDT mode. It is simply necessary for the user to type the initial ":". For further information on DDT mode commands, references 2, 7 and 8 of this memo are recommended. Also one might try next year's edition of this memo. 


</code>

{{tag>its ddt tutorial}}
Category: [[its:]]

~~LINKBACK~~
~~DISCUSSION~~