This file documents the DEC system emulator DECUUO. DECUUO is a TOPS-10 emulator for the I.T.S. monitor. It is loaded in core along with a standard DEC program. It will trap on a DEC MUUO and do the necessary equivalent for I.T.S. In general, DECUUO should be invisible to the emulated program. DECUUO has the capacity to emulate DEC TOPS-10 version 6.02 and the Stanford operating system. 1) HOW TO INVOKE THE DEC EMULATOR. To emulate the program in a particular file, say :DEC To emulate a program which has been dumped out with a emulator bootstrap, just load and start it. Running any of the following programs: D, PC, WL, NODIPS, DPLT, or PCPLT actually runs the emulator, which, on noticing that its JNAME is one of the above, loads and emulates the appropriate program from a file whose name is assembled into the emulator. This is the old-fashioned way of doing what should now be done with the bootstrap. 2) MODE SWITCHES The emulator has several mode switches, that specify these two types of option: (1) What type of system or terminal to emulate, and (2) Auxiliary services to the user. The switches of the first sort are: /DEC emulate the DEC TOPS-10 system. This is the default. /SAIL emulate the Stanford system. /III emulate a Stanford III terminal's display processing. Makes sense only when /SAIL is specified. /META emulate Stanford's CONTROL and META bits on input. On ITS terminals which have that feature, the extra bits are passed right to the emulated program. On other ITS terminals, the characters ^B, ^C and ^F are prefixes meaning CONTROL, META and CONTROL-META. /FN2 emulate an altered DEC or Stanford system which allows both filenames to have six characters, instead of the three that the real DEC system allows. There is no such system in reality, but some programs have been "converted" to ITS by making them read in full-word filenames; they are then emulated with this switch so that the full-word filenames will be handed to ITS. /SDIS Is synonymous with /SAIL/III/META/MAP /PRSV Prevents EXIT 0, from killing the job. This differs from what happens when a program named LINK or LOADER is run (EXIT 0, does not kill a job that has run a loader) in that this switch is saved by the bootstrap while the LINK/LOADER run condition is not. The switches of the second type are: /MAP Map input characters according to the physical correspondence between the Stanford keyboard and the TV keyboard. With this switch set, a TV key in a particular place will have the same effect in the emulator as the key in that same place on the Stanford keyboard would have on the same program running at SAIL, even if those two keys would have unrelated graphics printed on them. This feature is useful with programs which try, at Stanford, to use physically adjacent keys for related functions. /DBUG Stop in DDT after loading the program, before starting it. The PC will be the emulated program's start address. /SYMS Pass the symbol table from the loaded file up to DDT. This is the ITS-style symbol table of an ITS-format binary file, not the DEC-style in-core symbol table which need not be present. See 5) for how to give an in-core symbol table to DDT. When the emulator is invoked by ":DEC", switches should be put after the name of the file, preceded by slashes as shown above. It doesn't work to put switches anywhere but at the end of the command string. When the emulator is loaded by a bootstrap, the switch settings are set according to the bits in a word in the core image. See 4). When the emulator is invoked by running a specially-known program, the emulator knows from a table what switches are appropriate. 3) FEATURE TEST SWITCHES When a feature of the DEC system has no equivalent or is irrelevant under ITS, it may not be clear whether an attempt to use it should be ignored, reported to the user with an error message, or reported to the program as a "This system call not implemented" error. Several parameters, often corresponding to DEC's "feature test switches" which determine which features are implemented, are used to control those choices. Setting one of these parameters to zero requests emulation of a system in which some feature is not implemented; the emulated program's attempts to use it are reported to it as success or failure of the system call, but have no other effect. Setting the parameter nonzero requests emulation of a system in which the feature is implemented; attempts to use the feature will either work properly or cause an error message. For example, FTTMP controls the existence of the TMPCOR UUO. If it is 0, a system that does not have TMPCOR is emulated (which will tell the program the file is not found on reading, and that zero words are free on writing). If it is -1, an attempt to use TMPCOR will cause a "Simulator Deficiency Encountered" error message to be printed. Since most DEC programs that use TMPCOR win by writing a temporary disk file if the TMPCOR fails, the normal setting for this switch is 0. To set these switches, it is necessary to have the emulator's symbols. A full list of them is on page 7 of the source, MC:DECSYS;DECUUO >. 4) THE BOOTSTRAP The emulator bootstrap is a program which lives in the job data area whose purpose is to load in the emulator. The emulator inserts a bootstrap quite frequently into the emulated program; in particular, after doing an F command there will be one. A bootstrap can also be found in DECSYS;DECBOT BIN, so doing $$1L DECSYS;DECBOT BIN will merge a bootstrap in with any program. This will make the starting address point at the bootstrap, so the REAL starting address should be placed in the RH of .JBSA first. The F and D commands take care of that automatically. The switch settings desired for the program should be expressed as bits in the RH of the "switch word", location 56 (octal). Each switch has a corresponding bit which causes it to be set; their names are DECBT, IIIBT, METABT, etc. Normally, there is no need to worry about them, since the F and D commands set the bits according to the switches that are in effect (with the exception of /SYMS and /DBUG; F and D leave the bits for those switches OFF even if the switches were set. That way, you can :DEC a file with /DBUG /SYMS and other switches, then dump out after a D, all to create a new file just like the old one but with the switch bits set to whatever you specified). The /PRSV switch is handled specially; it will be set iff the program name (DEC-style) is LOADER or LINK, or if the switch was explicitly turned on in the command string. If PRSV was set by running the loader, that will not cause it to go into the bootstrap - if it did, it would be hard to load any program without having PRSV set. For the sake of programs that must be run with specific feature-test switch settings, the LH of the switch word, if nonzero, is taken to point at a subroutine to initialize variables. It will be called (with a JSR) when DECUUO is bootstrapped. That subroutine may be patched in with DDT after loading DECUUO with symbols; then a D command may be done to replace the symbols with the program's and prepare to dump. F and D do not change the LH of the switch word. Note, however, that in the long run it is best for the emulator to be made to work properly, so whenever something like this is necessary always report precisely what and why with :BUG DECUUO. 5) SYSTEM COMMANDS To issue a system command, do 45$G and then type the command character, which should be one of S Pass up to DDT the DEC-style in-core symbol table, throwing away any symbols DDT has for this job. F Flush the emulator from core, leaving only the emulated program. Also, insert a bootstrap and set the job's starting address to point to it. The current switch settings are remembered in the bootstrap so that they will be copied into the emulator when it is reloaded. V fill the Vestigial job data area with what it's supposed to contain. After doing this, 400000$,577777$0Y may be done in HACTRN to dump a DEC-format SHR or HGH file. Note however that if there is any data in the low segment, there has to be a DEC-style zero-compressed LOW or SAV file. To make such a file, do 0$,377777$0Y XPN which will make an "expanded file". Then do :DEC SYS:FILEX which runs the DEC FILEX (FILe EXpander) CUSP, and type .SAV=.XPN to it, using appropriate filenames and extensions. Generally, the low segment to a SHR or HGH file is called a LOW file, and a low segment without a high segment is called a SAV file. P Purifies the high segment. Useful if you really think more than one person might ever use the program at once. Does an automatic V (since afterward V is impossible). D prepare for Dumping. Does S, V, P and F (omits the V, P if there's no high segment). R Reenter the program - just like the DEC REENTER command. N No-op - simply finishes up a UUO if necessary. Useful if debugging and you ^Z'd the program while it was doing a UUO. H Help. Types out a help cruft. ? Types out a list of commands. If a system command is issued while the program is executing a emulated UUO, the UUO must be either finished or backed out of. DECUUO knows now how to back only out of TYI wait, so in all other cases it will print "Finishing up a UUO first..." and then complete the UUO before saying "Command: ". DECUUO will complain about any attempt to issue a system commands while an ITS interrupt is being handled, but nothing will have been clobbered. 6) THE DECSYS DIRECTORY When emulated programs refer to the SYS device, they do not access the ITS SYS device, since the ITS system programs are probably not what they want. Instead, they access the directory DECSYS, which is intended to have on it all the files that any DEC system "ought" to have on SYS, such as DDT.REL, JOBDAT.REL, ... Also, bootstrapped ITS binaries of DEC system programs go there so that RUN UUOs referring to SYS will find them, even though their main use may be via ^K. 8) THE INTERFACE BETWEEN THE emulATED PROGRAM AND ITS. A) Up to 5 ^C's are removed from the end of any file read in ASCII or ASCII LINE mode. Trailing nulls are changed to ^C's in the last word of any file written in one of those modes. B) Type-in Conventions: If /META is off, the conventions are that ^O and ^S both complement output-suppression, ^U clears the input buffer, rubout deletes one character, ^C causes a return to HACTRN if read by a TTCALL, but causes EOF on the TTY if the TTY is in use as a device. ^Z (quoted by ^_) is read as ^Z by a TTCALL, but is EOF when the TTY is in use as a device. If /META is on, only rubout has its special meaning. That is because at SAIL, on display terminals, the rest of those functions are generally placed on other characters, some of which could be handled by DECUUO if there is a demand. RESCAN attempts to read JCL, unless the program was run by :DEC ..., since in that case the JCL was intended for DECUUO and would only confuse the emulated program. The JCL, if any, is put into the type-in buffer. C) Conventions dealing with DSK and other directory devices. A null FN2 is allowed on the DEC system. DECUUO translates it into ">". In its normal mode, DECUUO allows one level of SFD to be specified in paths. To find a file in an SFD, DECUUO looks in the ITS directory with the same name (on the specified device). The PPN specified is totally ignored in that case. If there is no SFD spec'd, the PPN is used as the directory name. In that case, the PPN must be the expression, as two right-justified octal halfwords, of the SIXBIT of the directory name (in other words, their standard representations in machine words must be equal). Some newer DEC programs can handle "SIXBIT PPN's", in which case this crock is unnecessary. An ITS UFD may be read in with the file name -FILE- and any extension. An MFD may be read with the file name M-F-D-. D) Job numbers and other jobs. If the emulated program tries to read its job number, its ITS job number is returned. If it tries to refer to a job by number, the job's own number is acceptable. Any other argument which the DEC system would treat as the number of another job will either be held to provoke a deficiency or will return the information that the job does not exist, according to the setting of ZJOBS. E) Device names TTYnn will be translated into Tnn, thus allowing other terminals to be accessed using the same device names as are used on the DEC system. Device MTA is translated into MT0. No other device name (except SYS) is translated. ITS filename translations do work, of course; if just a device name is translated then DECUUO will even manage to report to the emulated program that the translated device name is a logical name, and supply the physical one. F) RUN and GETSEG. The RUN and GETSEG UUOs work using the same algorithm as on the DEC system, looking for files named SHR, HGH, SAV or LOW, with the extension that BIN is also looked up for low segment files, and HBIN is looked at for high segment files. The file format is determined from the file name: SHR or HGH implies a DEC high segment file, SAV or LOW implies a DEC low segment file, anything else is assumed to be an ITS format binary file. It is possible for an ITS binary file loaded expecting it to contain a low segment only, to contain actually two segments; DECUUO will recognize this. However, the file must be a PDUMPed file, so that it will leave a gap between the segments when loaded; otherwise, DECUUO will think it is one long low segment. Because of this, the only reason to have an HBIN file is so that a GETSEG (which tries only SHR, HGH and HBIN) can load it. An HBIN file must not load anything into the low segment part of the address space, or DECUUO will be very confused; this is your responsibility. An ITS binary file that loads into the AC's can also cause trouble. No "real" DEC program loads or dumps ANYTHING below .JBPFI (location 114), and DECUUO assumes this rule will be followed. It is possible to have both a high segment file (SHR, HGH or HBIN), and a "low segment" ITS binary file that really contains both segments, without confusing DECUUO. It will just cause the high segment to be loaded twice by a RUN UUO. The utility of this is that a link TS MUMBLE can be made to the "low segment" file and then the program can be run successfully with either MUMBLE^K or :DEC MUMBLE or a RUN UUO or a GETSEG. 8) DEFICIENCIES IN DECUUO. ("not supported" without qualification means that a "Simulator Deficiency" error message results, at least with the F.T. switches in their normal settings) Update mode I/O is not supported. It is very difficult to do in ITS. Some data modes are not supported (for example, image mode on terminals and paper tape). IONEOU is equivalent to OUTCHR. The Stanford features are far from being completely implemented. Random UUO's and fixes will be implemented for the SAIL stuff as the need arises. High segments that do not start at 400000 (because the low segment is longer than 400000) are not supported. High segments longer than 64K are not supported, but with a little effort that figure could be improved. REMAP is not supported when the low segment is longer than 128K. DDTIN, TMPCOR, TRMOP., TAPOP., and FILOP. are not supported. Since currently emulated software uses TMPCOR and TRMOP., those two will give the error return, unless an F.T. switch is set to act otherwise. Eventually all of these will be implemented, with the possible exception of DDTIN, since it is scheduled to be flushed from the DEC system anyway. All CALLIs connected with the MPX device, the software PI system, the enqueuing facility, and the Interprocessor Communications facility are not supported. Since the enqueueing facility and IPCF involve another job, they return "job non-existant". No attempt is made to handle privileged system calls; normally they return the appropriate failure for being a non-privileged program, but an F.T. switch can make them complain. A few GETTABs are not supported, though many would be easy to handle if there were a demand. Normally, the unsupported ones complain, but an F.T. switch can make them claim not to be implemented in this "monitor". SEEK, DISK., WAIT, UTPCLR, LOCATE, WHERE, WAKE, DAEMON, UNLOK., PAGE., NODE. are no-ops. Either the UUO is meaningless under I.T.S., or its failure is not noticeable by the emulated program. A reasonable DEC program will allow for failure of these UUO's. Turning on UU.AIO, UU.DER, UU.DEL is not supported. UU.AIO complains; the others are normally ignored. 60-cycle clock interrupts (AP.CLK) are not supported. Setting a file's protection or its creation date is not supported, but in the normal mode it will be ignored rather than barfed at. The data mode returned by a LOOKUP or ENTER will be the one in which the channel is initted; there is no way in ITS to remember that information, and unfortunately no way to tell whether the program is being screwed by that lack. ENTERing an SFD will fail with ERLVL% (the maximum SFD nesting level is 0). Setting the additional library (LIB:) for LOOKUPs (with a PATH.) is not supported. Extended LOOKUPs, ENTERs and RENAMEs with arguments in the AC's are not supported. The "universal time/date standard" is not supported. LOOKUPs return zero (or may be set to complain). The GETTABs that return a value in the "universal time/date standard" either fail or cause a "emulator Deficiency" error message, depending on an F.T. switch. Many of the arguments to extended ENTERs and RENAMEs are ignored. The access date is not returned (is always 0). Renaming from one directory to another is not supported. It can't be done on I.T.S. 8) MISCELLANEOUS INFO DECUUO exists in the same ITS job as the emulated program. This makes for greater efficiency than TEN50 had, and also makes it possible to debug the emulated program with ITS DDT instead of DEC DDT. The source for DECUUO is DECSYS;DECUUO > MC: and DECSYS;DECBOT > MC: (the latter by itself assembles the stand-alone bootstrap). When a program is being emulated by means of :DEC , it is possible to reload DECUUO with $L, re-specify the JCL and the $G again. However, that should not be done if there are any breakpoints set in the emulated program, since that process involves reloading the program while DDT thinks breakpoints are "in". If the program has a bootstrap and loads DECUUO, that case is no problem, but a similar problem exists with breakpoints INSIDE of DECUUO.