Copyright (c) 1999 Massachusetts Institute of Technology This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. ------------------------------ ITS USETS: This file attempts to maintain up-to-date documentation on all user variables hacked by .USET/.SUSET. Those wonderful souls who update the information in any way (additions, deletions, corrections) should describe their modifications in a brief note to INFO-ITS@AI so that interested parties can correct their copies or conceptions without needing to print or read the entire file again. For example: :QMAIL INFO-ITS@AI I added more details to the .FOO user var ^C If you want to be put on the INFO-ITS mailing list, just say so in a message to it. ------------------------------------------------- Each job running under ITS has a large number of variables associated with it maintained by the system. In order to examine and set these variables, the .USET and .SUSET uuo's are provided. The .USET uuo allows the specification of the job whose variables are to be accessed. The .SUSET uuo always accesses the variables of the job which executes it (SUSET = Self USET). The .USET uuo is used like this: .USET CHNL,SPEC and the .SUSET uuo like this: .SUSET SPEC The ac field CHNL of the USET must be the number of an input/output channel for which a job is open, as either the USR, JOB, or BOJ device. The .USET may modify the variables only if it has modification rights to the job (the job is a JOB device, or is a direct inferior). The contents of the effective address SPEC are of this form: 4.9 0 = read variable, 1 = set variable. 4.8 Block mode (see below). 4.7-3.1 Number of user variable to access. 2.9-2.1 Address of a location within the caller which is to receive the value of the variable, or which contains the new value for the variable. If bit 4.8 is 1, then the word at location SPEC is really an AOBJN pointer to a block of specifications. This is useful for getting several variables at a time easily. The AOBJN pointer is updated as the operation progresses, and so must be in a writable area. Block mode may not be nested. If an illegal specification is given to .USET or .SUSET, the job will receive an illegal operation word 1 interrupt (bit 1.6 of the .PIRQC user variable). The variables are described in this document by the names which DDT knows for them; the first character of each name is a ".". If you open up a location by using one of these names, DDT treats it specially and actually accesses the corresponding variable and not a location in the job's core. When writing .USET's and .SUSET's in MIDAS code, one may use the symbols defined by MIDAS for accessing them. These are the same as the names known to DDT, except that the "." is followed by "R" for reading or "S" for setting. If you open a location containing a SPEC, try typing .R$?? if it is positive, or .S$?? if it is negative; this will use bit typeout mode to print out the spec as it might have been assembled; for example, 400001,,500 .S$?? gives .SVAL,,500 . Examples: To read your own runtime in 4-microsecond ticks into FOO: .SUSET [.RRUNT,,FOO] To set your word 1 interrupt mask: .SUSET [.SMASK,,[%PIDWN\%PIPDL]] ;enable "pdl overflow" and "sys going down" interrupts To read your input/output status word for channel 13 into FOO: .SUSET [.RIOS+13,,FOO] To start a job (your immediate inferior!) open on channel USRC at its location QUUX, with its option bits indicating your readiness to supply JCL: .USET USRC,[.SOPTION,,[%OPCMD,,]] .USET USRC,[.SUPC,,[QUUX]] .USET USRC,[.SUSTP,,[0]] Another way to do the same thing is: MOVE AC,[-3,,USBLOK] .USET USRC,AC . . . USBLOK: .SOPTION,,[%OPCMD,,] .SUPC,,[QUUX] .SUSTP,,[0] FORM OF DESCRIPTIONS: The descriptions of the various variables accessible by .USET and .SUSET are in the following form: The descriptor contains four characters "wx yz". The first two ("wx") refer to the access for .USET; the last two ("yz") to the access for .SUSET. In each case these characters are chosen from these sets: -- May neither read nor set. +- May read but not set. +* May read and set. +? May read, may sometimes set (please read on...) That is, + means may read, * may set, - denies access, while ? says that things are more complicated. .40ADDR +* +* "40" address The right half: Initially 40 octal. Whenever the system references locations "40" through "44" specifically, (e.g. giving the user interrupts, or returning uuo's 50-77), the system really references the 5-word block that .40ADDR points to. Thus, if .40ADDR is set to 500, the system expects location 502 to contain the address of the interrupt routine. This is especially useful to distinguish system-returned uuo's (0 and 50-77) from standard user-mode uuo's (1-37); the latter always trap through location 40, while the former trap through .40ADDR. The various words accessed through .40ADDR are as follows (indexed by "normal" location #): 40 System places a uuo here when it wants to give it to the user. 41 Should contain the address of the uuo handler. If .40ADDR is not indeed 40, this may be a different uuo handler from the one which handles uuo's 1-37. If .40ADDR is actually 40, then unless 41's index and indirect fileds are 0 and its opcode is either 0 or JSR, all system-returned UUOs will cause ILOPR interrupts instead. This is to protect programs that want their hardware user-UUOs to be handled by a PUSHJ from being clobbered when they accidentally execute a meaningless UUO. 42 If the job's %OPINT bit in its .OPTION variable (q.v.) is 0, then this is a JSR to the user's old-style interrupt handler. The three words addressed by the JSR are, in order, the word in which the interrupt bits are placed, the return address for the interrupt, and the first instruction of the handler. If the %OPINT bit is 1, then this is an AOBJN pointer to a vector of 5-word blocks describing the various interrupt handlers and their priorities. See ITS INTRUP for details. 43 If the job's %OPLOK bit is set in its .OPTION variable, then this is the pointer to the list of switches to be reset if the job is killed. 44 If the job's %OPLOK bit is set, this is an AOBJN pointer to a block of critical code region descriptors. See ITS LOCKS for details. The left half: Initially 20 octal. This is the address of a block of 20 octal words which a job's superior may use to hack that job. For compatibility, if LH(.40ADDR) is zero, the default of 20 will be assumed. .ADF1 +* +* ANDCAM into .DF1 Like .DF1 (q.v.) when reading. Performs ANDCAM into .DF1 when writing.  .ADF2 +* +* ANDCAM into .DF2 Like .DF2 (q.v.) when reading. Performs ANDCAM into .DF2 when writing.  .AIFPIR +* +* ANDCAM into .IFPIR Like .IFPIR (q.v.) when reading. Performs ANDCAM into .IFPIR when writing.  .AMASK +* +* ANDCAM into .MASK Like .MASK (q.v.) when reading. Performs ANDCAM into .MASK when writing.  .AMSK2 +* +* ANDCAM into .MSK2 Like .MSK2 (q.v.) when reading. Performs ANDCAM into .MSK2 when writing.  .APIRQC +* +* ANDCAM into .PIRQ Like .PIRQC (q.v.) when reading. Performs ANDCAM into .PIRQC when writing. .APRC +- +- APR CONO 4.9 Procedure is in a disowned tree. 4.7 (BUMRTL) Tree will be gunned if hasn't run for an hour (meaningful only in top level job). Cleared by reowning or attaching. See the DETACH and DISOWN system calls. 4.6 Core request pending for this job. 4.5 User disabled, waiting to be flushed by SYS job. The SYS job will delete the job tree eventually. 4.4-4.1 .BCHN user variable (q.v.). 3.9 In process of deleting or logging out this job. Bit 4.5 will probably be set eventually. 3.5-3.1 Must be zero. 2.9-1.1 CONO'ed to APR whenever job is about to be run. Initially 447. Modified by altering the .MASK user variable.  .BCHN +* +* bad channel number Initially 0. Number of channel most recently in error. Typically after reading this variable one does a .STATUS or a STATUS symbolic system call to get the status word for the channel. This word can then be fed to the ERR device. .BCHN is actually part of the .APRC variable. See also the .IOS variable.  .CNSL +- +- console tty number If the job is in a console-controlled tree, this variable contains the console's number, even if the job doesn't own the console. If the job is in a non-console-controlled tree, .CNSL is -1 if the job is scheduled as part of the system, -2 if the job is scheduled as a disowned job; for a job-device-handler job, .CNSL is the same as it is for the job it is serving.  .DF1 +* +* defer bits, word 1 Initially 0. Defer bits for word 1 interrupts (see .PIRQC and .MASK). If an interrupt bit is set in both .PIRQC and .MASK, but is also set in .DF1, it is temporarily deferred.  .DF2 +* +* defer bits, word 2 Initially 0. Defer bits for word 2 interrupts (see .IFPIR and .MSK2). If an interrupt bit is set in both .IFPIR and .MSK2, but is also set in .DF2, it is temporarily deferred. .EBO1 +- +- KL-10 Ebox counter This is the low-order word of the KL-10 Ebox counter value for the job. It contains garbage on KA-10's. Its location is .EBOX+1, for convenience.  .EBOX +- +- KL-10 Ebox counter This is the high-order word of the KL-10 Ebox counter value for the job. It contains garbage on KA-10's.  .FLS +- -- flush instruction Initially 0. The instruction which is blocking the running of the job. Zero if user not blocked (user can run if .USTP is also zero). (The scheduler tests a job for runnability by first checking the .USTP variable, and if it is zero, then executing the flush instruction. The job is runnable iff the flush instruction skips.)  .FTL1 +- +- Fatal interrupt first word After a fatal interrupt, this variable contains the .PIRQC bits which caused the error. At any other time it contains garbage.  .FTL2 +- +- Fatal interrupt second word After a fatal interrupt, this variable contains the .IFPIR bits which caused the error. At any other time it contains garbage.  .HSNAME +* +* Home System Name This is a word of sixbit like .SNAME (q.v.). It is initialized to be the same as the UNAME on creation of a not-logged-in tree, and when a job is created as an inferior or as a job device, it's .HSNAME is copied from that of it's creator. The LOGIN system call sets it to be the same as the UNAME, although this should be changed to be the XUNAME. This is not used by ITS for anything, but is intended to associate a directory with a specific XUNAME for the sake of init and mail files of people without a directory of the same name as their XUNAME. DDT will soon initialize it by looking up information in the INQUIR database for the particular user.  .IDF1 +* +* IORM into .DF1 Like .DF1 (q.v.) when reading. Performs IORM into .DF1 when writing. .IDF2 +* +* IORM into .DF2 Like .DF2 (q.v.) when reading. Performs IORM into .DF2 when writing.  .IFPIR +* +* inferior procedure and i/o requests (?) Initially 0. This variable contains bits for pending word 2 interrupts. Bit 3.n is the interrupt bit for the n'th job directly inferior to the specified job (see the .INTB user variable). These therefore occupy bits 3.8-3.1. An inferior interrupt bit is set if an a class 1 or untrapped class 2 interrupt occurs in the inferior, or if the inferior is using new-style interrupts (see ITS INTRUP, and the %OPINT bit of the .OPTION user variable) and any unhandled interrupt occurs. Performing a .UCLOSE on an inferior clears the inferior interrupt bit in the .IFPIR variable of the job performing the .UCLOSE. Bit 1.n is the interrupt bit for input/output channel n-1 (actually, these occupy bits 2.7-1.1). Thus bit 1.1 = channel 0, 1.2 = channel 1, 1.3 = channel 2, . . ., bit 2.7 = channel 17. When an input/output interrupt is detected, the system call WHYINT shoud be used to discover the cause (see ITS .CALLS). The following devices can cause channel interrupts: TTY Input: A character was typed which according to the job's TTYST1 and TTYST2 variables (see ITS TTY) should be treated as an interrupt character. If the tty is opened for input on more than one channel, only one channel, if any, receives the interrupt. Output: The **MORE** condition has occurred. See ITS TTY. STY Input: Input is pending (i.e. the corresponding TTY has attempted output). If the STY is open for input on more than one channel, only one channel, if any, receives the interrupt. See ITS TTY. Output: The STY's alter ego is waiting for input, or at least was (it isn't guaranteed not to stop waiting and do something else). STK Input is available. Interrupts occur on all enabled channels. USR A foreign job open on the channel has been killed. If the job went away while the channel was pushed on the I/O pdl, this interrupt will occur when the channel is popped. See the .UCLOSE, .IOPUSH, and .IOPOP uuo's. If the job is the PDP-6, the PDP-6 has requested an interrupt. JOB Various conditions, some programmable. See ITS JOB. BOJ Various conditions, some programmable. See ITS JOB. NET One of the following conditions has occurred: The IMP has gone down. RFC received. After RFC sent, the connection is now open. Input available. Connection closed. Net interrupt received (INR or INS). MSP Message has been sent. .IIFPIR +* +* IORM into .IFPIR Like .IFPIR (q.v.) when reading. Performs IORM into .IFPIR when writing.  .IMASK +* +* IORM into .MASK Like .MASK (q.v.) when reading. Performs IORM into .MASK when writing.  .IMSK2 +* +* IORM into .MSK2 Like .MSK2 (q.v.) when reading. Performs IORM into .MSK2 when writing.  .INTB +- +- interrupt bit Gets the interrupt bit for the procedure. This is the word 2 interrupt bit which the procedure's superior will see when the procedure interrupts its superior. This variable will therefore have exactly one of bits 3.1-3.8 set, and no others. If the procedure is top level (has no superior), then this variable is negative.  .IOC + +- +- input/output channel The variable .IOC+ is the input/output channel word for channel , for n between 0 and 17 octal. Normally zero for a closed channel.  .IOP + +- +- input/output pdl The input/output pdl is a pdl of two-word entries used by the .IOPUSH, .IOPOP, and .IOPDL uuo's. The first word of each pair is the .IOC word for the stacked channel, and the second is the .IOS word. In addition, bits 4.9-4.6 of the .IOS word of each pair contain the channel number which the channel was pushed from (this is used by the .IOPDL uuo). The pdl has eight entries; thus should be between 0 and 17 (0 is the .IOC word for the least recently pushed entry, etc.). .IOS + +- +- input/output status The variable .IOS+ is the input/output status word for channel , for between 0 and 17 octal. Normally zero for a closed channel. This word contains various bits describing the status of the channel. The left half is a set of error codes if non-zero; the .IOS word can be given to the ERR device to obtain an ascii message for the error. The right half contains various bits describing the state of the device. (Internally to ITS, the right half contains an access pointer; the right half bits supplied for .IOS are the same as those generated by the .STATUS uuo or the STATUS symbolic system call.) The various bits in the .IOS word are as follows: 4.9-4.6 Always zero (see the .IOP variable). 4.5-4.1 If non-zero, the number of a non-display input/output error (see table below). 3.9-3.7 If non-zero, the number of an IDS interpreted display input/output error (see table below). 3.6-3.1 If non-zero, the number of a standard error. Set primarily by failing .OPEN's and .FDELE's. These are the same as the error codes returned by failing .CALL's (see table below). 2.9-2.3 Device dependent. 2.2 Buffering capacity empty. 2.1 Buffering capacity full. 1.9-1.7 Mode in which device was opened. 1.9 0 = ascii, 1 = image. 1.8 0 = unit, 1 = block. 1.7 0 = input, 1 = output. 1.6-1.1 ITS internal physical device code (see table below). The error messages indicated by bits 4.5-4.1 are: 1 DEVICE HUNG OR REPORTING NON-DATA ERROR 2 END OF FILE 3 NON-RECOVERABLE DATA ERROR 4 NON-EXISTENT SUB-DEVICE 5 OVER IOPOP 6 OVER IOPUSH 7 USR OP CHNL DOES NOT HAVE USR OPEN 10 CHNL NOT OPEN 11 DEVICE FULL (or directory full) 12 CHNL IN ILLEGAL MODE ON IOT 13 ILLEGAL CHR AFTER CNTRL P ON TTY DISPLAY 14 DIRECTORY FULL 15 DIRECTORY'S ALLOCATION EXHAUSTED The error messages indicated by bits 3.9-3.7 are: 1 IDS ILLEGAL SCOPE MODE 2 IDS SCOPE HUNG 3 MORE THAN 1K SCOPE BUFFER 4 IDS MEM PROTECT 5 IDS ILLEGAL SCOPE OP 6 IDS MEM PROTECT ON PDL PNTR 7 IDS ILLEGAL PARAMETER SET The error messages indicated by bits 3.6-3.1 are: 1 NO SUCH DEVICE 2 WRONG DIRECTION 3 TOO MANY TRANSLATIONS 4 FILE NOT FOUND 5 DIRECTORY FULL 6 DEVICE FULL 7 DEVICE NOT READY 10 DEVICE NOT AVAILABLE 11 ILLEGAL FILE NAME 12 MODE NOT AVAILABLE 13 FILE ALREADY EXISTS 14 BAD CHANNEL NUMBER 15 TOO MANY ARGUMENTS (CALL) 16 PACK NOT MOUNTED 17 DIRECTORY NOT AVAIL 20 NON-EXISTENT DIRECTORY NAME 21 LOCAL DEVICE ONLY 22 SELF-CONTRADICTORY OPEN 23 FILE LOCKED 24 M.F.D. FULL 25 DEVICE NOT ASSIGNABLE TO THIS PROCESSOR 26 DEVICE WRITE-LOCKED 27 LINK DEPTH EXCEEDED 30 TOO FEW ARGUMENTS (CALL) 31 CAN'T MODIFY JOB 32 CAN'T GET THAT ACCESS TO PAGE 33 MEANINGLESS ARGS 34 WRONG TYPE DEVICE 35 NO SUCH JOB 36 VALID CLEAR OR STORED SET 37 NO CORE AVAILABLE 40 NOT TOP LEVEL 41 OTHER END OF PIPELINE GONE OR NOT OPEN 42 JOB GONE OR GOING AWAY 43 ILLEGAL SYSTEM CALL NAME 44 CHANNEL NOT OPEN 45 INPUT BUFFER EMPTY OR OUTPUT BUFFER FULL 46 UNRECOGNIZABLE FILE (LOAD) 47 LINK TO NON-EXISTENT FILE The physical device codes from bits 1.6-1.1 are as follows. Note that, as a half-hearted rule, bit 1.6 indicates that file names are significant, and bit 1.5 indicates a software-implemented device. This list is subject to additions and deletions! CODE SYMBOL DEVICE DESCRIPTION 0 TTY Console input. 1 SNTTY TTY Printing console output. 2 SNTDS TTY Display console output. 3 SNLPD LPT Data Products line printer. 4 SNVID VID Vidisector ??? 5 SNBAT Vidisector ??? 6 SNPLT PLT Calcomp plotter. 7 SNPTP PTP Paper tape punch. 10 SNIMPX IMX Input multiplexor. 11 SNOMPX OMX Output multiplexor. 12 SNPTR PTR Paper tape reader. 13 SN340 DIS DEC 340 display, Ascii output. 14 SN340I IDS Interpreted 340 display. ??? 15 SNMTC MTn Magnetic tape. 16 SNCOD COD Morse code device. 17 SNTAB TAB Tablet. ??? 21 SNNUL NUL Source of zeroes, or output sink. 22 SNJOB JOB Job device. 23 SNBOJ BOJ Inverse of JOB. 24 SNSPY SPY Spy on another console. 25 SNSTY STY Pseudo-teletype. 26 SNNET NET ARPA network. 27 SNLPV LPT Vogue line printer (yech!) 30 SNSTK STK Stanford keyboard. 31 SNMSP MSP Interprocess message protocol. 41 SNUTC UTn Microtape (DECtape). 43 SN2311 DSK 2311 disk drives or equivalent. 60 SNFUSR USR A foreign (not immediately inferior) procedure. 61 SNUSR USR An immediately inferior procedure. 62 SNCLK CLx Various core link devices (x  {AIOU}) 63 SNDIR --- File directory or ERR device. 64 SNPDP USR The PDP-6. .IPIRQC +* +* IORM into .PIRQC Like .PIRQC (q.v.) when reading. Performs IORM into .PIRQC when writing.  .JNAME +* +? job name The name of the job as a word of sixbit characters. The uname-jname pair must be unique to a job (there are some exceptions involving system-created jobs or jobs not logged in). The uname and jname are used as file names when creating or subsequently opening the job on the USR device. See also the .UNAME user variable. The .JNAME variable may be set by a .SUSET only in a top-level job, and then only if the job has no inferiors. Attempting to set a jname to zero causes an illegal operation interrupt (bit 1.6 of the .PIRQC user variable). So does attempting to set it such that the uname-jname pair would no longer be unique. So does attempting to illegally set one's own jname.  .JPC +* +* jump program counter The PC as of the most recent jump instruction, i.e. an instruction which changed the PC by other than 1 or 2. This is actually a register in the paging box when running.  .MARA +* +* MAR (memory address register) address Initially 0. The address for the MAR register in the paging box, which gives a %PIMAR interrupt when the specified operation is performed on the specified address. 3.3 0 = exec mode, 1 = user mode. This is forced to 1 when set with .SUSET or .USET; exec mode is for very obscure system hacks only. 3.2-3.1 0 Never interrupt. 1 Interrupt on instruction fetch. 2 Interrupt on write. 3 Interrupt on any reference. 2.9-2.1 Address for MAR. The MAR does not work well on accumulators. See also the .PIRQC user variable, bit %PIMAR; and ITS INTRUP and ITS USR. .MARPC +* +* MAR program counter The PC as of the instruction that most recently tripped the MAR interrupt, if any. In addition, the indirect bit will be set if that instruction completed successfully (was not aborted by the MAR hit). See the .MARA user variable.  .MASK +* +* word 1 interrupt mask Initially 0. This is a mask for word 1 interrupts which indicates which interrupts the job is prepared to handle. If a class 2 or class 3 word 1 interrupt tries to occur, but the corresponding bit in .MASK is not set, then the interrupt is converted to class 1 or ignored, respectively. The bits in .MASK directly correspond to those in .PIRQC (q.v.). Bits for class 1 interrupts are AND'ed out before setting the .MASK variable.  .MBO1 +- +- KL-10 Mbox counter This is the low-order word of the KL-10 Mbox counter value for the job. On KA-10's, it holds garbage. Its location is .MBOX+1, for convenience.  .MBOX +- +- KL-10 Mbox counter This is the high-order word of the KL-10 Mbox counter value for the job. On KA-10's, it holds garbage.  .MEMT +* +* memory top This variable contains 1 plus the highest legal address in the job (the accessible word with the largest address). Setting this variables is like performing an equivalent .CORE uuo (q.v.): .SUSET [.SMEMT,,[FOO]] is like doing: .CORE _12  .MPVA +- +- memory protect violation address The address which the last instruction to cause a memory protection violation (or a write into read only memory violation) attempted to reference, on KA-10's rounded down to a page boundary. Thus an attempt to reference the non-existent location 317435 would cause .MPVA to be set to 316000 octal on a KA-10, or 317435 on a KL-10. See also the .PIRQC variable. On the KS-10, .MPVA holds the non-existant IO register address after a %PINXI. .MSK2 +* +* word 2 interrupt mask Initially 0. This is a mask for word 2 interrupts which indicates which interrupts the job is prepared to handle. If a class 2 or class 3 word 2 interrupt tries to occur, but the corresponding bit in .MSK2 is not set, then the interrupt is converted to class 1 or ignored, respectively. The bits in .MSK2 directly correspond to those in .IFPIR (q.v.).  .OPC +- +- old program counter The PC just before the last instruction was executed. This corresponds to a register in the paging box. It doesn't exist on KL-10's. .OPTION +* +* option bits Initially 0. The bits in this word correspond to various options as follows: 4.9 %OPTRP Same as the .UTRP user variable. See ITS UUO. 4.8 %OPDET ** This bit is OBSOLETE and NO LONGER EXISTS ** It is documented for historical purposes only. Nowadays, fatal interrupts always cause top-level jobs to be detached. Once upon a time, top-level jobs with consoles would be reloaded instead of detached, unless they had set %OPDET=1. See the DETACH and RELOAD symbolic system calls. 4.7 %OPDEC Uuo's 40, 41, and 47 (that is, .IOT, .OPEN, and .ACCESS) should trap to the user as uuos via the .40ADDR user variable (q.v.). This is useful for programs which wish to interpret DEC TOPS-10 UUO's, since those are the only ones which conflict with ITS UUOs. Luckily, those ITS UUOs are not essential since there are symbolic system calls to do the same things. 4.6 %OPCMD Superior claims it has JCL which it will cheerfully supply in response to the appropriate .BREAK 12, command. 4.5 %OPBRK Superior claims to handle all .BREAK's. 4.4 %OPDDT Superior claims to be DDT. 4.3 %OPINT Job desires new-style (vectored and stacked) interrupts. See also the .40ADDR variable. See ITS INTRUP for information on old- and new-style interrupts. 4.2 %OPOJB Other jobs may open this job as the OJB device, thereby turning it into a JOB device. See ITS JOB. 4.1 %OPLOK Job desires the switch locking and unlocking synchronization feature. See also the .40ADDR variable. See ITS LOCKS for information on locks. 3.9 %OPLIV The job tree of which this is the top-level job is permitted to survive a system shutdown -- it should take care of logging itself out. See the .SHUTDN uuo. Meaningful only for top-level jobs. Primarily useful for system demons which need to survive system death (e.g. the statistics demon PFTHMG DRAGON). 3.8 %OPOPC Job desires that instruction-aborting interrupts such as MPV leave the PC pointing before the instruction that lost, instead of the old convention of leaving it pointing after. The new convention is far better and all new programs should use it. 3.7 %OPLSP Superior claims to be MacLisp. 3.6 %OPLKF Unlock locks on fatal interrupt. When a non-disowned top-level job receives a fatal interrupt, if it has set this bit, its locks will be unlocked by the system job as part of the process of detaching it. See the %OPLOK bit and ITS LOCKS. .PAGAHEAD +* +* page-ahead control Normally zero, this word is set nonzero to enable sequential paging through a part of the address space specified by .PAGRANGE. The right half of .PAGAHEAD is the page-ahead interval width and the left half is the page-behind distance. Each time a page in the designated range is touched for the first time, the next few pages, forming the page-ahead interval begin to swap in, and a page a certain distance behind (specified by the page-behind distance) is swapped out or marked for swap out in the near future. The precise treatment depends on how loaded the system is. Exactly one of the page-ahead interval width and the page-behind distance should be negative. The page-behind distance should be negative, if memory is being used from low addresses to high ones. The page-ahead width should be negative if moving from high addresses to low ones. Example: -2,,4 means on first reference to page n, start reading in pages n+1 through n+4 and possibly swap out page n-2. Page n-1 is not affected until page n+1 is touched. A page-behind distance of 2 means that two consecutive pages are always available. .PAGRANGE +* +* page-ahead range Normally zero, this word is made nonzero together with .PAGAHEAD to enable the sequential paging feature. The two halves of .PAGRANGE are page numbers which specify the region of the address space in which sequential paging should go on. The left half specifies the first page in the sequentially paged region, and the right half specifies the first page after the end of that region. .PICLR +* +* priority interrupt clear Initially -1. If non-zero, the job may take interrupts. If zero, interupts are deferred. This variable is cleared when an old-style interrupt occurs (but not by new-style interupts!), and is set to -1 by the .DISMISS uuo and the DISMIS symbolic system call. Attempts to set this variable will convert the value to -1 or 0 depending on bit 4.9.  .PIRQC +* +* priority interrupt request cruft (?) This word contains bits for pending word 1 interrupts. Setting bits in this causes the corresponding interrupts to attempt to take place, subject to .MASK, .DF1, .PICLR (q.v.), and the %OPINT bit of the .OPTION user variable (see ITS INTRUP). Interrupts are of three classes: 1 Very serious. The job is stopped and its superior interrupted. 2 Semi-serious. The job may request to handle such an interrupt by setting the corresponding bit in .MASK (q.v.); otherwise it is treated as a class 1 interrupt. 3 Trivial. The job receives the interrupt if it has requested to handle it; otherwise the interrupt condition is ignored. (Under the new-style interrupt scheme, a class 3 interrupt may become a class 1 interrupt.) See also the .IFPIR variable for word 2 interrupts. The interrupt bits and their classes are as follows. The character * denotes a class 1 interrupt, and + a class 2 interrupt. 4.9 Must be zero. %PIRLT 4.8 Clock break (see the .REALT uuo). %PIRUN 4.7 Run time interrupt (see the .RTMR user variable). %PINXI 4.6 + Non-Existent IO register A Job in User IOT mode referenced a non-existent IO register on the KS10 Unibus. The PC is left pointing before the guilty instruction. The address of the non-existant register may be found in .MPVA. %PIJST 4.5 Job Status display request. The sequence ^_J was typed on the console owned by this process or some inferior. %PIDCL 4.4 * A defered call was typed while the job had the TTY. %PIATY 4.3 The tty was given back to the job by its superior. Indicates that the screen has probably been written on and its contents have changed unpredictably. %PITTY 4.2 + Attempt to use tty when not possessing it. %PIPAR 4.1 + Parity error. %PIFOV 3.9 Arithmetic floating overflow. %PIWRO 3.8 + Attempt to write into read only memory. See the .MPVA user variable. %PIFET 3.7 + Pure page trap (attempt to fetch an instruction from writable memory when bit 4.2 of the PC set). This feature doesn't exist on KL-10's, instead this interrupt is signalled for "Illegal entry to concealed mode" which you probably can't make happen. (See the KI10 Processor Reference Manual.) See bit 4.2 of the .UPC user variable. %PITRP 3.6 * System uuo to user trap (see the .UTRP user variable). 3.5 Arm tip break 3 (OBSOLETE). 3.4 Arm tip break 2 (OBSOLETE). 3.3 Arm tip break 1 (OBSOLETE). %PIDBG 3.2 System being debugged (occurs when someone uses the .SETLOC or .IFSET uuo to alter SYSDBG and the new contents are non-zero and the old contents non-negative). See also the SSTATU symbolic system call. %PILOS 3.1 + A .LOSE UUO or LOSE system call was executed (their purpose is to signal the superior). %PICLI 2.9 CLI device interrupt. %PIPDL 2.8 Pdl overflow. %PILTP 2.7 Light pen interrupt on 340. Program stop or hit stop on E&S display. %PIMAR 2.6 + MAR interrupt (see the .MARA and .MARPC user variables). %PIMPV 2.5 + Memory protection violation (attempt to reference a page not in the job's page map). See the .MPVA user variable. %PICLK 2.4 Slow clock interrupt (every .5 second). %PI1PR 2.3 * Single intruction proceed interrupt. Used by DDT for ^N commands. %PIBRK 2.2 * Breakpoint interrupt (.BREAK uuo executed). %PIOOB 2.1 + Illegal user address. (OBSOLETE) %PIIOC 1.9 + Input/output channel error (see the .BCHN and .IOS user variables). %PIVAL 1.8 * Value interrupt (.VALUE uuo executed). %PIDWN 1.7 System going down or being revived. See the .SHUTDN, .REVIVE, and .DIETIME uuo's, and the SSTATU symbolic call. %PIILO 1.6 + Illegal instruction operation. %PIDIS 1.5 + Display memory protection violation (340 or E&S). %PIARO 1.4 Arithmetic overflow. %PIB42 1.3 * Bad location 42 (see the .40ADDR user variable, and ITS INTRUP). %PIC.Z 1.2 * ^Z typed when this job had the TTY. %PITYI 1.1 Character enabled for interrupt was typed on TTY. (Semi-obsolete; see the .IFPIR user variable, and ITS TTY.) .PMAP + +- +- page map word This is the page map word for page of the job, for between 0 and 377 octal (256.K = 400 1K pages). The map word read has this form: 4.9 %CBWRT Page is writable. 4.8 %CBRED Page exists (if this bit is zero, then the whole word is zero). 4.7 ??? Page is in core (as opposed to swapped out). 4.6 %CBPUB Page is public (any job can write into it which wants to). 4.2 %CBLOK Page is locked in core (inhibited from swapout) 3.9 %CBSLO Page is in slow memory (Doesn't work; Moon says it never will) 3.8-3.1 Number of times the page is shared. (See the CORTYP symbolic system call, right half of value 4.) 2.9-2.1 Absolute page number, or page number in next sharer in the circular list of sharers. (See CORTYP, value 3.) 1.9-1.1 0 Page is absolute. 777 Page is not shared. Next sharer in circular list of sharers is the job with user index .  .RTMR +* +* runtime timer Initially -1. If non-negative, the amount of run time remaining until the job will receive a word 1 runtime interrupt. (See bit %PIRUN of the .PIRQC variable.) The time is measured in slightly different units on different CPUs. On the KA in 4.069 microsecond units, on the KL in 4 microsecond units, and on the KS in 3.9 microsecond units.  .RUNT +- +- run time Initially 0. This is the run time used so far by the job, measured in units of 4 microseconds.  .SERVER +* +* server job Initially -1. This is the user index of a job that has been given special permission to modify this job, or -1 if there is no such job. This can be used to implement various oddball client/server protocols between jobs. The client job will request some service from the server job and will set his .SERVER variable to the server's user index to allow the service to be performed. If the server job is killed, all of the client jobs will have their .SERVER variables set back to -1. Although it is safe to set .SERVER to -1 using .SUSET or .USET, there can be timing errors if a client loads his .SERVER variable by simply writing the server's user index into it. Specifically, during the time the server's user index is sitting in the client's memory, the server job might be killed and another job started with the same user index. This can be guarded against by handling interrupts on the USR: channel, but this is clumsy. A better method is to use the SSERVE system call. (See .INFO.;ITS .CALLS)  .SNAME +* +* system name This is a word of six sixbit characters which is the default "directory name" for various input/output operations. It is initially the same as the job's .UNAME (q.v.). It can be overridden by supplying the directory name explicitly to a symbolic system call. The other uuo's such as .OPEN and .FDELE always use .SNAME. .SUPPRO +- +- superior This is -1 if the job is top-level, or the user index of the job's superior. See .UIND.  .SV40 +- +- saved 40 The contents of absolute location 40 (i.e., the last uuo that trapped to the system for this job). See also the .UUOH user variable. Note that only uuo's 40-47 are really used for communication with the system. All other uuo's are handed back to the executing job via its .40ADDR user variable (q.v.).  .TR1INS +? +? Trap 1 instruction. This is the instruction to be executed when arithmetic overflow occurs. Op-code 0 is special, and uses its E.A. as interrupt bits to turn on in the RH of .PIRQC. The default contents of .TR1INS are simply %PIARO to set the overflow interrupt. On the KA-10, writing the variable doesn't change it.  .TR2INS +? +? Trap 2 instruction. This is the instruction to be executed when pdl overflow occurs. Op-code 0 is special, and uses its E.A. as interrupt bits to turn on in the RH of .PIRQC. The default contents of .TR2INS are simply %PIPDL to set the pdl overflow interrupt. On the KA-10, writing the variable doesn't change it.  .TTST +- +- saved TTYSTS In a job which does not have the TTY, this variable holds the saved contents of TTYSTS (what would be in TTYSTS if the job were given a TTY). This is primarily useful for examining from DDT. See ITS TTY for a description of the contents of TTYSTS. See also the TTYGET and TTYSET symbolic system calls.  .TTS1 +- +- saved TTYST1 Like .TTST, but for the TTYST1 variable instead of the TTYSTS variable.  .TTS2 +- +- saved TTYST2 Like .TTST, but for the TTYST2 variable rather than the TTYSTS variable. .TTY +* +* random TTY variable This variable indicates the status of the job with respect to the console controlling its job tree. The %TBNVR, %TBINT, %TBWAT, %TBOUT, %TBINF, %TBOIG, and %TBIIN bits are settable. %TBWAT may be set only by the superior. 4.9 %TBNOT Does not have TTY now. 4.8 %TBNVR If 1, an OPEN on the tty will fail rather than hanging, unless %TBWAT is on. 4.7 %TBINT An attempt to use the console without owning it will cause a %PITTY interrupt (LH of the .PIRQC user variable), unless %TBWAT is set to 1. In particular an OPEN on the tty will interrupt instead of failing or hanging. 4.6 %TBWAT If 1, overrides the setting of %TBINT and %TBNVR, and makes the system act as if they were 0. Settable only with .USET. DDT sets this bit when $P'ing a job, so that even if the job loses the tty momentarily it will not get upset. 4.4 %TBDTY If the TTY was taken from the job, then when it gets it back, this bit says that the TTY should stay with the job and not be passed down to an inferior. 4.3 %TBOUT Allow this job to type out, even if it doesn't have the TTY. Some operations, and all input will still require the job to have the TTY. Not effective unless the superior enables it by setting %TBINF in the superior's .TTY var. 4.2 %TBINF Enable this job's inferiors to take advantage of their %TBOUT's. 4.1 %TBOIG Ignore output. Overrides %TBWAT, %TBINT. 3.9 %TBIIN Interrupt on attempt to do input. Overrides %TBWAT. 3.6-3.1 $TBECL Number if echo lines, if the job doesn't currently have the TTY. 2.9-1.1 If the job has the TTY, this is the TTY number. If it doesn't, and doesn't want it, this is the (internal) user number of the immediately inferior job to give the TTY to. .TVCREG +* +* TV console register Initially -1. This variable is placed in the console register when the job is run if it is non-negative. It controls which video buffer memory is used when writing into the job's tty's TV buffer (see the CORBLK symbolic system call). The format of the console register is as follows: 4.9-4.2 ALU function, used when writing into TV memory: VALUE SYMBOL FUNCTION 0 CSETC SETCAM 1 CNOR ANDCBM 2 CANDC ANDCAM 3 CSETZ SETZM 4 CNAND ORCBM 5 CCOMP SETCMM 6 CXOR XORM 7 CANCSD ANDCMM 10 CORCSD ORCAM 11 CEQV EQVM 12 CSAME SETMM/MOVES/JFCL 13 CAND ANDM 14 CSETO SETOM 15 CORSCD ORCMM 16 CIOR IORM 17 CSET SETAM/MOVEM Note that those symbols are not predefined in MIDAS. 4.1-3.3 Video buffer number (video switch input number). See the VIDSW symbolic system call.  .UIND +- +- user index The unique number assigned to the job by the system when the job was created. These numbers typically are between 0 and 77 octal or so (the exact maximum value is a function of the particular incarnation of the system). When a job is killed, its user index is freed for re-use. Most symbolic system calls which require a job to be specified will accept 400000+the user index in lieu of a channel with the job open on it if the call is only to examine the job and not to modify it. The .GUN and DETACH commands require a user index. Jobs 0 and 1 are special in that they always stand for the system itself and for the CORE job, respectively. (The CORE job manages core allocation for the system.) This may have various implications depending on context; for example, when sharing a page with a job via the CORBLK symbolic system call, sharing with job 0 means sharing with an absolute page, and "sharing" with job 1 means getting a fresh page. .UNAME +- +? user name A word of sixbit characters which is the user name of the job. All jobs in a given job tree must all have the same user name. Furthermore, a console-controlled tree may not log in if another console-controlled tree is logged in under the same uname. When a new console-controlled tree is created by typing ^Z on a free console, the uname of the newly created top-level job of the tree is set to "___nnn", where "nnn" is the user index of the newly-created job. A non-disowned non-console controlled job is also given such a uname initially. This may subsequently be changed to something more reasonable by using the LOGIN symbolic system call. The uname of a newly created inferior job is initialized to the uname of its creator. If a disowned job tree is re-owned, the unames of all the jobs in the re-owned job tree are set to the uname of the re-owning job tree. The .UNAME user variable may be set only with a .SUSET, and only by a top level job which has no direct inferiors; furthermore, attempting to set the uname to zero or the left half to -1 causes an illegal operation interrupt (bit 1.6 of the .PIRQC user variable), as does attempting to make the uname-jname pair of the job non-unique. See also the .JNAME user variable. .UPC +* +- user program counter The PC for the job. This word, of course, contains the PC flags in the left half; a job may set these flags for itself only by using JRST 2,@[]. On KA's, the flags in the left half are as follows: (- = .USET may not set; % = peculiar to ITS) %PCARO==400000 Overflow. %PCCR0==200000 Carry 0. %PCCR1==100000 Carry 1. %PCFOV==40000 Floating overflow. %PCFPD==20000 First part of instruction already done. %PCUSR==10000 - User mode. %PCUIO==4000 - User I/O. %PCPUR==2000 % Pure. Instructions may only be fetched from read-only memory. See bit 3.7 of the .PIRQC user variable. This feature is not available on all machines -- beware! %PCSPC==1000 - Unused. (A PDP6 feature) %PC1PR==400 % One proceed. An interrupt will occur at the end of the next instruction. See bit 2.3 of the .PIRQC user variable. Used by DDT for ^N commands. %PCX17==200 % AI KA-10 computer only. Index-off-the-PC hack. When this bit is set, an index field of 17 means index off the PC instead of ac 17. %PCFXU==100 Floating underflow. %PCDIV==40 No divide. 3.5-3.1 Always zero. May not be set non-zero. On KL's the flags are as follows (note the "|" at the front of lines that differ significantly from those for KA's): | %PSPCP==400000 "Previous Context Public" - this applies only in exec mode; in user mode this bit is the same as in KA (%PCARO, Arithmetic overflow). %PSCR0==200000 Carry 0. %PSCR1==100000 Carry 1. %PSFOV==40000 Floating overflow. %PSFPD==20000 First part of instruction already done. %PSUSR==10000 - User mode. %PSUIO==4000 - User I/O. | %PSPUB==2000 "Public Mode" - not used in ITS | %PSINH==1000 Inhibits MAR-breaks and trap3 (one-proceed trap) | for one instruction. | %PSTR2==400 Set by pdl overflow; causes the "trap 2 instruction" | to be executed. That instruction is kept in .TR2INS | %PSTR1==200 Set by arithmetic overflow; causes the | "trap 1 instruction" in .TR1INS to be executed. | Both %PSTR1 and %PSTR2 set generates a one-proceed trap. | %PS1PR==160 % %PSINH+%PSTR2+%PSTR1. Setting those bits | causes a single instruction proceed. %PSFXU==100 Floating underflow. %PSDIV==40 No divide. 3.5-3.1 Always zero. May not be set non-zero. The user mode (4.4) is always set to 1. The user I/O bit (4000, bit 4.3) is set according to whether the job is in .IOTLSR mode. If the .UPC user variable for one job is read by another while the first is running, an exec mode PC may be seen (bit 4.4 = 0); this reflects the fact that the job is in the middle of a system call or something. The .UUOH user variable should then be examined (this is precisely what DDT does for the evaluation of .). .USTP +* -- user stop bits Initially <100000,,>. If this variable is non-zero, the job is being blocked from running for one reason or another. If zero, the .FLS variable controls whether the job may run. The form of the .USTP variable is as follows: 4.9 BCSTOP Job is being moved in core. 4.8 BUCSTP Core job is stopping this job in order to get more core for another job. 4.7 BUSRC User control bit. Only this bit may be modified, and only by the procedure's superior. Any attempt to set the .USTP variable non-zero will set this bit; any attempt to set it to zero will clear this bit. 4.6 BSSTP Set while superior is altering the page map for the job. (Not directly settable by superior.) 2.9-1.1 Count of transient reasons for stopping the job. If non-zero, inhibits relocation of the job by the core job. PEEK displays this variable by printing the high six bits in octal, then a "!", then the rest in octal. This is why one normally sees "10!0" for a stopped job.  .UTRP +* -- user trap switch When non-zero, this switch specifies that all uuo's which trap to the system should, instead of performing their usual actions, should cause a word 1 class 1 interrupt to the job executing the uuo. This allows simulators, etc., to trap all uuo's executed by a job. An attempt to set this variable will use only bit 1.1. This is the same as the %OPTRP bit of the .OPTION user variable.  .UUOH +- +- system uuo PC The program counter as of the last uuo which trapped to absolute location 40 (not location 40 in the job, nor the location specified by .40ADDR!) See also the variable .SV40.  .VAL +* +* value or error code of job .VALUE instructions set this word to the contents of the memory location they address. That is useless. More importantly, .LOSE instructions, and the LOSE system call, set .VAL to ,,, so that the superior can decode the error. .WHO1 +* +* user who-line control word This variable controls the printing of .WHO2 and .WHO3 at the end of the TV who-line (see ITS TV). 4.9 If 1, suppress the who-line entirely when focused on this job. 4.8 Suppress space between halves of .WHO2. 4.7-4.5 Mode for printing left half of .WHO2: 0 Do not print. 1 Date in packed form: 4.9-4.3 Year (mod 100.). 4.2-3.8 Month. 3.7-3.3 Day. 3.2-3.1 Unused. See the RQDATE symbolic system call, but note that here the date is shifted. 2 Time in fortieths of a second, printed in tenths in the form HH:MM:SS.T. 3 Time in half-seconds, printed in the form HH:MM:SS. 4 Octal halfword. 5 Decimal halfword (no . is supplied). 6 Three sixbit characters. 7 Unused. 4.4-4.2 Mode for printing right half of .WHO2. 4.1 Print 3.9-3.3 twice (doubled character). 3.9-3.3 If non-zero, character to print after left half of .WHO2. 3.2 If 1, suppress the space between .WHO2 and .WHO3 printout. 3.1 If 1, suppress the space between halves of .WHO3. 2.9-2.7 Mode for printing left half of .WHO3. 2.6-2.4 Mode for printing right half of .WHO3. 2.3 Print 2.2-1.5 twice. 2.2-1.5 If non-zero, character to print after left half of .WHO3. 1.4-1.1 Unused. That is, if the who-line is printed at all, what appears at the end is these characters: AAAAXX-BBBB=CCCCYY+DDDD where: AAAA is the result of printing the left half of .WHO2. BBBB right half of .WHO2. CCCC left half of .WHO3. DDDD right half of .WHO3. XX one or two characters specified by .WHO1 4.1-3.3. YY one or two characters specified by .WHO1 2.3-1.5. - space, unless .WHO1 4.8 is 1. = space, unless .WHO1 3.2 is 1. + space, unless .WHO1 3.1 is 1. Note that the specifications fall neatly into 8-bit bytes (for the convenience of the PDP-11); hence it is easiest to specify this word using .BYTE 8 in MIDAS. Example: .SUSET [.SWHO1,,[ .BYTE 8 ? 166 ? 0 ? 144 ? 200+", ]] causes .WHO2 to appear as a word of sixbit, and .WHO3 to appear as octal halfword typeout in mmm,,nnn format.  .WHO2 +* +* first user who-line variable See .WHO1 for details.  .WHO3 +* +* second user who-line variable See .WHO1 for details. .XJNAME +* +* "intended" job name. This variable holds what the job's name was "intended" to be, by its creator. Why might the job's name not actually be what it was intended to be? Perhaps because that name was already in use by some other job, and the creator had to find a second choice. For example, when :NEW T in DDT creates a job named T0 because there was already a job named T, the job T0's .XJNAME will be "T". In any case, when using the common technique of having several programs be links to one file, which figures out what name it was invoked under and behaves accordingly, the .XJNAME is the right place to look to find out what behavior the invoker desires. When a job is first created, its .XJNAME is the same as it's .JNAME.  .XUNAME +* +* "real" user name. This variable holds what says who you really are, as opposed to what you are logged in as. It should be a word of sixbit, just like .UNAME. For example, if you are logged in as FOO1 then your XUNAME will probably be FOO, because that's what DDT will normally set it to. However, though the .UNAME may change because of reowning or attaching, the .XUNAME will ot change iunless requested specifically. However, the user may alter DDT's .XUNAME by depositing in ..XUNAME, which works by informing DDT and having DDT tell ITS. Whenever an inferior is created, its .XUNAME is initialized from its superior's.