OS8 Support - PS8 Computing

Go to content

OS8 Support


OS/8 SOFTWARE SUPPORT MANUAL  (Version 3)  DISCLAIMER This document file was created by scanning  the original  document and then editing the scanned text.  As much as possible, the original  text format was restored.  Some format changes were made to insure this  document  would  print  on current laser printers using 60 lines per page. The  original  spelling and  grammar  has been preserved. 1-Sep-1996 OS/8 SOFTWARE SUPPORT MANUAL  (Version 3)       DEC-S8-OSSMB-A-D    -------------------------------------------------------    | Order additional copies as directed on the Software |    | Information page at the back of this document.      |    -------------------------------------------------------    digital equipment corporation * maynard, massachusetts       First Printing, January 1973 Revised, June 1974     The information in this document is subject to change without notice     and should not be construed as a commitment by Digital Equipment     Corporation.  Digital Equipment Corporation assumes no responsibility     for any errors that may appear in this manual.     The software described in this document is furnished to the purchaser     under a license for use on a single computer system and can be copied     (with inclusion of DIGITAL's copyright notice) only for use in such     system, except as may otherwise be provided in writing by DIGITAL.     Digital Equipment Corporation assumes no responsibility for the use     or reliability of its software on equipment that is not supplied by     DIGITAL. Copyright (C) 1973, 1974 by Digital Equipment Corporation     The HOW TO OBTAIN SOFTWARE INFORMATION page, located at the back of     this document, explains the various services available to DIGITAL     software users.     The postage prepaid READER'S COMMENTS form on the last page of this     document requests the user's critical evaluation to assist us in     preparing future documentation.     The following are trademarks of Digital Equipment Corporation:       CDP              DIGITAL          INDAC            PS/8       COMPUTER LAB     DNC              KA10             QUICKPOINT       COMSYST          EDGRIN           LAB-8            RAD-8       COMTEX           EDUSYSTEM        LAB-8/e          RSTS       DDT              FLIP CHIP        LAB-K            RSX       DEC              FOCAL            OMNIBUS          RTM       DECCOMM          GLC-8            05/8             RT-ll       DECTAPE          IDAC             PDP              SABR       DIBOL            IDACS            PHA              TYPESET 8  UNIBUS    PREFACE     The 8K Operating  System  (OS/8)  is  an  extremely  powerful  program     development  system.   OS/8 greatly expands the capabilities of any 8K     PDP-8, 8/I, 8/L, 8/E, or PDP-12 computer having the necessary disk or     DECtape  storage. Use  of  OS/8, is described in detail in the OS/8     HANDBOOK (DEC-S8-OSHBA-A-D).     This manual covers a wide range of advanced topics pertinent  to the     experienced  user. In Chapter 1 the various basic system concepts are     described and terms are defined.  Chapter 2 explains  the process by     which  user  programs  call  upon the  system  for the performance of     important operations including loading device  handlers,  opening and     closing  files,  and chaining to other programs.  Chapter 3 covers the     functions of the Command Decoder and  the means  by  which  the  user     program  can  employ  its services.   Chapter  4 explains the use and     operation of the device handlers in  detail.   Chapter  5 covers the     details  of  "custom  tailoring"  a  system,  including how to write a     device handler for a non-standard device.     Technical information, intended to enhance the information in the OS/8     HANDBOOK, as  well  as  this  manual, can be found in the Appendices.     Appendix A details the OS/8 directory  structure  and  gives  standard     file  format.  Appendix B describes the system data base and gives the     layouts of the system areas.  Appendix C  gives  a complete  list of     system  error  messages. Appendix D illustrates some useful advanced     techniques and programming "tricks" for  use  with the  OS/8  system.     Appendix  E  is  a complete list of the standard ASCII character codes     meaningful to OS/8. Finally, Appendix F describes a set of generalized     I/O routines for use under the OS/8 system.      iii   CONTENTS       Page     CHAPTER 1       OS/8 CONCEPTS AND TERMINOLOGY       1-1     1.1       SOFTWARE COMPONENTS OF OS/8       1-1     1.2       FILES       1-2     1.2.1     File Names and Extensions       1-2     1.2.2     File Structured Devices       1-2     1.2.3     File Types       1-3     1.2.4     File Directories and Additional       Information Words       1-3     1.3       CORE CONTROL BLOCK       1-4     1.3.1     Program Starting Address       1-5     1.3.2     Job Status Word       1-5     1.3.3     Software Core Size       1-6     1.4       DEVICE NAMES AND DEVICE NUMBERS       1-6     1.5       THE DEVICE AND FILENAME PSEUDO-OPS       1-7     CHAPTER 2       USER SERVICE ROUTINE       2-1     2.1       CALLING THE USR       2-1     2.1.1     Standard USR Call       2-1     2.1.2     Direct and Indirect Calling Sequence       2-2     2.2       SUMMARY OF USR FUNCTIONS       2-3     2.2.1     FETCH Device Handler       2-4     2.2.2     LOOKUP Permanent File       2-6     2.2.3     ENTER Output (Tentative) File       2-7     2.2.4     The CLOSE Function       2-8     2.2.5     Call Command Decoder (DECODE)       2-10     2.2.6     CHAIN Function       2-10     2.2.7     Signal User Error       2-12     2.2.8     Lock USR in Core (USRIN)       2-13     2.2.9     Dismiss USR from Core (USROUT)       2-13     2.2.10    Ascertain Device Information (INQUIRE)       2-14     2.2.11    RESET System Tables       2-15     CHAPTER 3       THE COMMAND DECODER       3-1     3.1       COMMAND DECODER CONVENTION       3-1     3.2       COMMAND DECODER ERROR MESSAGES       3-3     3.3       CALLING THE COMMAND DECODER       3-3     3.4       COMMAND DECODER TABLES       3-4     3.4.1     Output Files       3-5     3.4.2     Input Files       3-5     3.4.3     Command Decoder Option Table       3-6     3.4.4     Example       3-7      iv      Page     3.5       SPECIAL MODE OF THE COMMAND DECODER       3-10     3.5.1     Calling the Command Decoder Special Mode       3-10     3.5.2     Operation of the Command Decoder in Special       Mode       3-10     3.6       CCL AND THE COMMAND DECODER       3-11     3.7       USEFUL LOCATIONS IN BATCH       3-11     3.8       CCL TABLES       3-12     CHAPTER 4       USING DEVICE HANDLERS       4-1     4.1       CALLING DEVICE HANDLERS       4-1     4.2       DEVICE DEPENDENT OPERATIONS       4-4     4.2.1     Teletype (TTY)       4-4     4.2.2     High-Speed Paper Tape Reader (PTR)       4-4     4.2.3     High-Speed Paper Tape Punch (PTP)       4-5     4.2.4     Line Printer (LPT)       4-5     4.2.5     Cassettes       4-7     4.2.6     Card Reader (CDR)       4-8     4.2.7     TM8E Handler       4-8     4.2.8     File Structured Devices       4-12     4.2.9     TD8E DECtape       4-12     4.2.10    KL8E Teletype Handler       4-13     CHAPTER 5       RECONFIGURING THE OS/8 SYSTEM       5-1     5.1       WRITING DEVICE HANDLERS       5-1     5.2       INSERTING DEVICE HANDLERS INTO OS/8       5-5     APPENDIX A       OS/8 FILE STRUCTURES       A-1     A.1       FILE DIRECTORIES       A-1     A.1.1     Directory Entries       A-2     A.1.2     Number and Size of 05/8 Files       A-3     A.1.3     Sample Directory       A-3     A.2       FILE FORMATS       A-4     A.2.1     ASCII and Binary Files       A-4     A.2.2     Core Image (.SV format) Files       A-5     A.2.3     Relocatable FORTRAN Library File       A-8     APPENDIX B       DETAILED LAYOUT OF THE SYSTEM       B-1     B.1       LAYOUT OF THE SYSTEM DEVICE       B-1     B.2       LAYOUT OF THE OS/8 RESIDENT PROGRAM       B-3     B.3       SYSTEM DEVICE TABLES       B-5     B.3.1     Permanent Device Name Table       B-5       v      Page     B.3.2     User Device Name Table       B-6     B.3.3     Device Handler Residency Table       B-6     B.3.4     Device Handler Information Table       B-6     B.3.5     Device Control Word Table       B-7     B.3.6     Device Length Table       B-8     APPENDIX C       SYSTEM ERROR CONDITIONS AND MESSAGES       C-1     C.1       SYSTEM HALTS       C-1     C.2       USR ERRORS       C-2     C.3       KEYBOARD MONITOR ERRORS       C-3     C.4       CCL ERROR MESSAGES       C-4     C.5       COMMAND DECODER ERRORS       C-7     APPENDIX D       PROGRAMMING NOTES       D-1     D.1       THE DEFAULT FILE STORAGE DEVICE, DSK       D-1     D.2       MODIFICATION TO CARD READER HANDLER       D-2     D.3       SUPPRESSION OF CARRIAGE RETURN/LINE FEED       IN FORTRAN       D-4     D.4       ACCESSING THE SYSTEM DATE IN A FORTRAN       PROGRAM       D-4     D.5       DETERMINING CORE SIZE ON PDP-8 FAMILY       COMPUTERS       D-5     D.6       USING PRTC12-F TO CONVERT OS/8 DECTAPES       TO OS/12 LINCTAPES       D-6     D.7       NOTES ON LOADING DEVICE HANDLERS       D-7     D.7.1     Problem with Multiple Input Files       D-7     D.7.2     Dynamically Loading Device Handlers       D-8     D.8       AVAILABLE LOCATIONS IN THE USR AREA       D-9     D.9       ACCESSING ADDITIONAL INFORMATION WORDS       IN OS/8       D-9     D.9.1     After a LOOKUP or ENTER       D-9     D.9.2     After a CLOSE       D-10     D.9.3     Rewriting the Current Directory Segment       D-10     D.10      SABR PROGRAMMING NOTES       D-11     D.10.1    Optimizing SABR Code       D-11     D.10.2    Calling the USR and Device Handlers from       SABR Code       D-13      vi      Page     APPENDIX E       CHARACTER CODES AND CONVENTIONS       E-1     APPENDIX F       OS/8 INPUT/OUTPUT ROUTINES       F-1     F.1       GENERAL DESCRIPTION       F-1     F.2       SUBROUTINE FUNCTIONS       F-1     F.3       SUBROUTINE PARAMETERS       F-3     F.3.1     Example       F-4     F.3.2     Subroutine Listing       F-5     INDEX       I-1      vii   CHAPTER 1 OS/8 CONCEPTS AND TERMINOLOGY     Before examining the details of the OS/8  system, the  reader  should     first  be familiar  with the simpler techniques and terms used within     the framework of the OS/8 system. The material in this chapter, along     with that contained in the OS/8 HANDBOOK, provides the tools needed to     pursue the later chapters.     1.1  SOFTWARE COMPONENTS OF OS/8     There are four main components of the OS/8 system:  1.  The Keyboard Monitor performs commands specified by the  user      at  the keyboard console. The nine Keyboard Monitor commands      (ASSIGN, DEASSIGN, GET, SAVE, ODT, RUN, R, START, and  DATE)      are explained in Chapter 1 of the OS/8 HANDBOOK.      User programs can exit to the Keyboard Monitor by executing a      JMP  to  location 7600  in field 0. All JMPs to 7600 must be      made with the  DATA  FIELD  set  to  zero.   This saves the      contents of  locations 0000 to 1777 in field 0 and loads the      Keyboard Monitor which could be called by a JMP  to  location      7605 in field 0. In this latter case the contents of core are      not saved, which conserves some time.      Existing system programs, device handlers,  and  the  Command      Decoder  test  for the CTRL/C character in the terminal input      buffer and, on finding  this  character, abort  the  current      operation and perform a JMP to 7600 in field 0. Thus, typing      CTRL/C is the conventional method of  calling  the  Keyboard      Monitor from the console.  2.  Device handlers, which are  subroutines  for  performing all      device-oriented  input/output  operations, can be utilized by      any  program.   These  subroutines  have standard   calling      sequences and  "mask"  from  the user  program the special      characteristics of the  I/O  device.   In this  way,  device      independent  I/O is  achieved. A  detailed  description of      device handlers is found in Chapter 4.  3.  The User Service Routine (USR)  is  to  a program  what the      Keyboard Monitor is to the user.  For example, programs can      request the  USR to  fetch  device  handlers,  perform  file      operations  on  any device, chain to another program, or call      the Command Decoder.  A full description of the USR functions      is found in Chapter 2.      1-1 OS/8 CONCEPTS AND TERMINOLOGY  4.  The Command Decoder interprets a command line  typed  by the      user  to indicate input and output files and various options.      The command line format is described in detail in Chapter  1      of the OS/8 HANDBOOK.  The Command Decoder removes the burden      of this repetitive operation from the user's program.  A full      description  of  the  Command  Decoder's function is found in      Chapter 3.  5.  Two other components, ABSLDR and ODT, are not logically  part      of  the  OS/8  system.  However, in the sources and listings,      ABSLDR is combined with the Keyboard Monitor and USR.  ODT is      combined with the command decoder.     1.2 FILES     Files are basic units of the OS/8 system, and a thorough understanding     of file  structure is required for its use.  A file is any collection     of data to be  treated  as a  unit.   The format of  this  data is     unimportant;   for example,  OS/8 can  manipulate  several  standard     formats, including ASCII files, binary files, and core  image  files.     The  important  consideration  is that  the  data forms a single unit     within the system.     1.2.1 File Names and Extensions     An individual file is identified by its file name and extension. The     file  name consists  of up to six alphanumeric characters, optionally     followed by a two character extension.  The extension is often used to     clarify the format of the data within the file.  For example, an ASCII     file used as input to PAL8 might be given a PA extension, while a core     image file has a SV extension.     1.2.2 File Structured Devices     Devices that can be logically divided into a number of 256-word blocks     and  have the  ability  to  read and write from any desired block are     called  file  structured  devices.  Disks and  DECtapes are   file     structured devices while a paper tape reader or terminal is not.     Cassettes and magnetic tapes form an intermediate case.  They  may be     treated  directly as non-file structured devices, or the program MCPIP     may appear to be file structured.     The system device (SYS) in any OS/8 system is always file structured,     as is the default storage device, DSK.     All OS/8 file structured devices must be logically divided into  these     256-word  blocks. Hence, 256  words is considered the standard OS/8      1-2 OS/8 CONCEPTS AND TERMINOLOGY     block size.  Some devices,  like RK8,  DECtape, and  LINCtape, are     physically divided  into blocks. These physical blocks should not be     confused with the logical 256-word blocks. For example, DECtapes must     be formatted  with standard 129-word physical blocks.  A logical OS/8     block consists of the first 128  words  of two  consecutive  physical     DECtape  blocks.  The 129th word of every DECtape block is not used by     OS/8. Similarly, LINCtapes are formatted with 129 (or 128) words per     block but never 256, as this format is unacceptable to OS/8.     A given OS/8 file consists of one or more sequential  blocks  of 256     words  each  (consecutively numbered). A minimum of one block per file     is required, although a single file could occupy all of the blocks on     a device.     1.2.3  File Types     Three different types of files exist in the OS/8 system:  1.  An "empty file" is a contiguous area of unused blocks.  Empty      files are created when permanent files are deleted.  2.  A "tentative file" is a file that is open to  accept  output      and  has not yet been closed.  Only one tentative file can be      open on any single device at one time.  3.  A "permanent file" is a file that has been given a fixed size      and  is  no  longer  expandable. A  tentative  file becomes      permanent when it is closed.     To further understand file types, consider what occurs when a file is     created. Normally, the User Service Routine, in creating a tentative     file, first locates the largest empty file available  and creates  a     tentative file in that space.  This establishes the maximum space into     which the file can expand. The user program then writes data into the     tentative file.  At the end of the data, the program calls the USR to     close the tentative file, making it a permanent file.  The USR does so     and  allocates whatever space remains on the end of the tentative file     to a new, smaller, empty file.     1.2.4  File Directories and Additional Information Words     To maintain records of the files on a device, OS/8 allocates blocks  1     through  6 of  each  file structured  device  as the file directory.     Entries in this directory inform the system of  the  name, size, and     location  of  each file, including all empty files and the tentative     file, if one exists.  For a detailed description of the entries in the     file directory, see Appendix A.     Each entry in a directory can, optionally, have  extra  storage  words     called   Additional  Information  Words. The  number  of Additional      1-3 OS/8 CONCEPTS AND TERMINOLOGY     Information Words is determined at the time the directory is initially     created  (normally by using the /S or /Z features of PIP; see Chapter     1 of the OS/8 HANDBOOK.     Whenever Additional Information Words are used, the first one for each     file  entry  is used to store the value of the System Date Word at the     time the file was created. OS/8 automatically uses one extra word per     entry  for the  date.   This value is set by executing a DATE command     (see Chapter 1 of the OS/8 HANDBOOK) which codes the current date into     memory location 07666 in the following format: 0 3 4   8 9     11       +---------+----------+----------+       | |    |       |       +---------+----------+----------+  MONTH     DAY      YEAR-1970 (1-14(8))  (1-37(8)) (0-7)     A date word of 0 implies that no DATE command has been executed  since     the system initialization.     The values of  Additional Information  Words  beyond  the first are     user-defined.   See  Appendix  D for further information on Additional     Information Words.     1.3  CORE CONTROL BLOCK     Associated with each core image file (SV file)  is a  block  of  data     called  the  Core Control Block.  The Core Control Block is a table of     information containing the program's starting address, areas  of  core     into  which  the program is loaded, and the program's Job Status Word.     The Core Control Block is created at the time the program is loaded by     ABSLDR  or other means  and  is written onto the SV file by the SAVE     operation. More information on the Core Control Block can be found in     the  description  of  core image files  in  section A.2.2. Note that     specifying arguments to the SAVE command as described in Chapter 1 of     the OS/8 HANDBOOK, can alter the contents of the target program's Core     Control Block.     When a program is loaded, the starting address and Job Status Word are     read  from the Core Control Block and saved in core.  The Core Control     Block itself is saved in the last 200 (octal) words of block 37 on the     system  device  unless  the program was loaded with the R (rather than     GET or RUN) command.      1-4 OS/8 CONCEPTS AND TERMINOLOGY     1.3.1  Program Starting Address     The current starting address (used by the START command) is stored in     two words at locations 07744 and 07745. The format of these words is: LOCATION CONTENTS NOTES ________ ________ _____   07744   62n3      n is the field in      which to start.   07745   nnnn      Starting address of      the program.     1.3.2  Job Status Word     The  Job  Status  Word  contains  certain flags  that   affect   OS/8     operations,  such as  whether  to save  core when loading the USR or     Command Decoder.  The Job Status Word for the  program  currently in     core   is saved at  location  07746  and  contains  the  following     information:       Bit Condition   Meaning       _____________   _______       Bit 0 = 1   File does not load into locations 00000   to 01777.       Bit 1 = 1   File does not load into locations 00000   to 01777.       Bit 2 = 1   Program must be reloaded before it can   be restarted.       Bit 3 = 1   Program does not destroy the contents of   the highest existing memory field, an   optimization for the Batch system.       Bits 4 thru 9   Reserved for future use.       Bit 10 = 1   Locations 00000 to 01777 need not be   saved when calling the Command Decoder.       Bit 11 = 1   Locations 10000 to 11777 need not be   saved when calling the USR.     When bit 2 of the Job Status Word is 1, any attempt to perform a START     (without an explicit address) results in a       NO!!     error message being printed.  As this bit is always zero in  the  Core     Control Block, the user program is expected to internally set this bit     (in location 7746) if a program is not  restartable.   This  could be      1-5 OS/8 CONCEPTS AND TERMINOLOGY     done as follows:    CDF 0    TAD I (7746    /LOAD JOB STATUS WORD    AND (6777    TAD (1000    DCA I (7746    /JOB IS NOT RESTARTABLE     The Job Status Word can be updated from the user's program or with the     ABSLDR /P option, thus providing optimization of tape (disk) motion.     More information on the  Core  Control  Block  can be  found  in the     description of Core Image (SV) files found in Appendix A.     Bit 3 of the JSW (Job Status Word) is used as an optimization for the     Batch  operating  system. If  a program can never cause the highest     existing memory field to be altered, this bit  should  be set. For     example,  EDIT,  PIP,  FORT,  and SABR can never use memory above 8K.     Thus, they should set bit 3 of the JSW. Programs  such as  ABSLDR,     LOADER,  PAL8 and CREF can alter all of core.  They should perhaps not     have bit 3 on.  Note that the more core that exists, the more unlikely     it is  that a program will destroy upper core.  Thus, on 28K systems,     only the largest FORTRAN programs can alter field 6 and,  in  general,     bit 3 should be set.     1.3.3  Software Core Size     Location 07777 contains the software  core size  in  bits 6-8.  This     represents the highest memory field available for use by OS/8. If bits     6-8 contain 0, all of the available memory is used.  Most OS/8  cusps     interrogate  this word to determine how much memory is available. The     other bits of this location are reserved for use by BATCH and  should     not be touched by user programs.     1.4  DEVICE NAMES AND DEVICE NUMBERS     The OS/8 system can accommodate up to 15 separate devices. In Chapter     1 of  the OS/8  HANDBOOK the reader is introduced to the concept of     device names.  Briefly, each device on the system is  recognized by     either  a permanent device name (such as PTR or DTAl) which is created     when the system is built, or a user-defined device name determined by     an ASSIGN command.   The system insures that the user-defined device     name takes precedence.  For example,       .ASSIGN DSK DTA4     causes all future references to DTA4 to address the device DSK.     In calling the User Service Routine, a  device  can  be  alternatively     recognized by a device number.  Each device on the system has a unique     predefined number in the range 1 to 17 (octal) assigned  at  the  time      1-6 OS/8 CONCEPTS AND TERMINOLOGY     the  system  is  generated.   Thus,  user programs have the choice of     referring to a device by either name or number.  Referencing a  device     by name  is  preferable, as it maintains device independence for the     program.     Accessing devices by number should be done only when  the appropriate     number  has been obtained from a USR INQUIRE CALL. Except for SYS and     DSK, the 05/8 peripherals do not have fixed numbers;  instead,  device     numbers  vary  whenever BUILD is used to modify a system. Thus, it is     suggested that reference by name be used whenever possible.     To determine whether a  device  name  is  recognized  in  the  system,     attempt  to  ASSIGN  that device.  For example, to determine whether     LINCtape handlers are called LTA or DTA, perform:       .DEASSIGN       .AS LTA0     If the system responds with a dot (.), LTA0 does indeed exist.  If the     system responds with:       LTA0 NOT AVAILABLE     no device named LTA0 is present.     1.5  THE DEVICE AND FILENAME PSEUDO-OPS     Several of the USR functions  take device names or  file  names as     arguments.  To  simplify the task of generating these arguments, the     DEVICE and FILENAME pseudo-ops have been added to the PAL8 Assembler.     A device name  consists of  a  two  word  block,  containing   four     alphanumeric  characters  in  six-bit  ASCII  format.  A block in this     format can be created by the DEVICE pseudo-op as follows:       DEVICE DTA1     generates the following two words:       0424       0161     similarly, the FILENAME pseudo-op creates a four word block, the first     three  words  of  which  contain  the file name and the fourth word of     which contains the file extension. For example:       FILENAME PIP.SV     generates the following four words:      1-7 OS/8 CONCEPTS AND TERMINOLOGY       2011       2000       0000       2326     Note that positions for characters 4 through 6 are filled with zeros.     The DEVICE and  FILENAME  pseudo-ops  are used  in  examples  in the     following chapters.      1-8   CHAPTER 2     USER SERVICE ROUTINE     The User Service Routine, or USR, is a collection of subroutines which     perform  the  operations  of opening and closing files, loading device     handlers, program chaining, and calling the Command Decoder.  The USR     provides  these  functions not only for the system itself, but for all     programs running under the OS/8 system.     2.1  CALLING THE USR     Performing any USR function is as simple as giving a JMS  followed by     the  proper  arguments.   Calls to the USR take a standardized calling     sequence. This standard call should be studied before progressing to     the operation of the various USR functions.     2.1.1  Standard USR Call     In the remainder of this chapter, the following  calling  sequence is     referenced:       TAD VAL   The contents of the AC is applicable in   some cases only.       CDF N   Where N is  the  value  of  the  current   program field multiplied by 10 (octal).       CIF 10       JMS I (USR   Where USR is either 7700 or 0200,  (see   section 2.1.2).       FUNCTION   This word contains an integer from 1 to   13 (octal)   indicating which USR   operation is to be performed.       ARG(l)   The number and meaning of these argument   words  varies  with the  particular USR   function to be performed.       error return   When applicable,  this  is the  return   address for all errors.       normal return   The operation was successful.  The AC is   cleared  and the  data  field is set to   current field.      2-1     USER SERVICE ROUTINE     This calling sequence can change from  function to  function. For     example,  some functions take no value in the AC and others have fewer     or greater  numbers  of  arguments.   Nonetheless,  this format is     generally followed.     The value of  the data  field  preceding the  JMS  to  the  USR is     exceedingly  important.   The  data  field MUST be set to the current     field, and the instruction field MUST be set to 1. Note that a CDF is     not  explicitly required if the data field is already correct.  When a     doubt exists as to the data field setting, an explicit CDF should be     executed.     There are three other restrictions which apply to all  USR calls, as     follows:  1.  The USR can never be called from any  address  between  10000      and 11777. Attempting to do so results in the:   MONITOR ERROR 4 AT xxxxx  (ILLEGAL USR CALL)      message and termination of program execution.  The  value of      xxxxx  is the  address  of the calling sequence (in all such      MONITOR ERROR messages).  2.  Several USR calls take address pointers as arguments.   These      pointers always refer to data in the same memory field as the      call.  3.  When calling the USR from field  1,  these  address  pointers      must  never  refer  to  data  that  lies in the area 10000 to      11777.     2.1.2  Direct and Indirect Calling Sequence     A user program can call the USR in two ways.  First, by  performing  a     JMS to location 17700 In this case, locations 10000 to 11777 are saved     on a special area on the system device, and the  USR  is  then  loaded     into  10000  to  11777. When the USR operation is completed, locations     10000 to 11777 are restored to their previous values.      NOTE    By setting bit 11 of the Job Status Word    to a  1, the user can avoid this saving    and restoring of  core  when  preserving    core is unnecessary.     Alternatively, a program can opt to keep the USR permanently  resident     in core  at locations 10000 to 11777 by using the USRIN function (see     section 2.2.8). Once the USR has been brought into core,  a  USR  call     can  be  made  by performing a JMS to location 10200. This is the most     efficient way of calling the  USR.  When USR  operations have  been      2-2     USER SERVICE ROUTINE     completed, the  program  restores locations  10000 to 11777 to their     initial state by executing the  USROUT  function, if  necessary  (see     section 2.2.9).     2.2  Summary of USR Functions  Function    Code Name Operation  ________ ____ _________    1 FETCH   Loads  a  device  handler   into   core.   Returns   the   entry   address  of the   handler.    2 LOOKUP   Searches  the  file directory  on any   device  to  locate a specified permanent   file.    3 ENTER   Creates and opens for output a tentative   file on a specified device.    4 CLOSE   Closes the currently open tentative file   on  the  specified  device and becomes a   permanent  file.   Also,  any   previous   permanent  file  with the same file name   and extension is deleted.    5 DECODE   Calls the Command Decoder.  The function   of  the  Command Decoder is described in   Chapter 3.    6 CHAIN   Loads a specified core image file  from   the system device and starts it.    7 ERROR   Prints an error message of the form USER   ERROR n AT LOCATION xxxxx.   10 USRIN   Loads the  USR  into core. Subsequent   calls to the USR are by an effective JMS   to location 10200.   11 USROUT   Dismisses the USR from core and restores   the previous contents of locations 10000   to 11777.   12 INQUIRE   Ascertains whether a given device exists   and, if  so,  whether its handler is in   core.   13 RESET   Resets system tables to  their  initial   cleared state.   14-17   Not currently   used,   these   request   numbers are reserved for future use.      2-3     USER SERVICE ROUTINE     An attempt to call the USR with a code greater than  13  (octal)  will     currently cause  a  Monitor  Error  4  message  to be printed and the     program to be aborted.     2.2.1  FETCH Device Handler  Function Code = 1     Device handlers must be loaded into core so as to be available to the     USR  and  user  program  for  I/O operations  on that device.  Before     performing a LOOKUP, ENTER, or  CLOSE  function  on  any  device, the     handler for that device must be loaded by FETCH.     The FETCH function takes two distinct forms:  1.  Load a device handler corresponding to a given device name.  2.  Load a device handler corresponding to a given device number.     First, the following is an example of loading a handler by name  from     memory field 0:       CLA      /AC MUST BE CLEAR       CDF 0      /DF = CURRENT FIELD       CIF 10      /IF = 1       JMS I (USR       1      /FUNCTION CODE = 1       DEVICE DTA3    /GENERATES TWO WORDS: ARG(1)      /AND ARG(2)       6001      /ARG(3)       JMP ERR      /ERROR RETURN       .      /NORMAL RETURN       .       .     ARG(1) and ARG(2) contain the device name in standard format.  If the     normal  return  is taken, ARG(2) is  changed  to  the device number     corresponding to the device loaded.   ARG(3)  contains  the  following     information:      Bits 0 to 4 contain the page number into which the handler is      loaded.      Bit 11 is 0 if the user program  can  only  accept  a  1-page      handler.      Bit 11 is 1 if there is room for a 2-page handler.     Notice that in the example above, the handler for DTA3 is to be loaded     into locations 6000 to 6177. If necessary, a two page handler could be     loaded;  the second page would be placed in locations  6200  to  6377.     After a normal return, ARG(3) is changed to contain the entry point of     the handler.      2-4     USER SERVICE ROUTINE     A different set of arguments is used to  fetch  a device handler by     number.  The following is an example of this form:       TAD VAL      /AC IS NOT ZERO       CDF 0      /DF = CURRENT FIELD       CIF 10      /IF = 1       JMS I (USR       1      /FUNCTION CODE = 1       6001      /ARG(1)       JMP ERR      /ERROR RETURN       .      /NORMAL RETURN       .       .     On entry to the USR, the AC contains the device number in bits 8 to 11     (bit  0  to  7 are ignored). The format for ARG(1) is the same as that     for ARG(3) in the previous example.  Following a normal return  ARG(1)     is replaced with the entry point of the handler.     The conditions that can cause an error return to occur in both  cases     are as follows:  1.  There is no device corresponding to the given device name or      device number, or  2.  An attempt was made to load a two page handler into one page.      If  this is  an attempt to  load  the handler by name, the      contents of ARG(2) have been changed already to the  internal      device number.     In addition, one of the  following Monitor  errors  can  be  printed,     followed by a return to the Keyboard Monitor:       Error Message  Meaning       _____________  _______  MONITOR ERROR 4 AT xxxxx Results if bits 8 to 11 of the AC  (ILLEGAL USR CALL) are zero  (and bits  0 to  7 are non-zero).  MONITOR ERROR 5 AT xxxxx Results if a read error occurs  (I/O ERROR ON SYS) while loading the device handler.     The FETCH function checks to see if the handler is in core, and if it     is not,  then  the  handler  and all co-resident handlers are loaded.     While the FETCH operation is essentially a simple one, the user should     be aware of the following points:  1.  Device handlers are always loaded into memory field 0.  2.  The entry point that is returned may  not  be  on  the  page      desired. This  would  happen  if  the  handler were already      resident.  3.  Never attempt to load a handler into the 7600  page  or  into      page 0. Never load a two page handler into the 7400 page.      2-5     USER SERVICE ROUTINE     For more information on using device handlers, see Chapter 4.      NOTE    Two or   more   device   handlers are    "co-resident"   when   they  are both    included in the same  one  or  two core    pages.   For  example,  the paper tape    reader   and    punch    routines are    co-resident,  as  are  the eight DECtape    handler routines.     2.2.2  LOOKUP Permanent file   Function Code = 2     This request locates a permanent file entry on a given device, if one     exists.  An example of a typical LOOKUP would be:       TAD VAL   /LOAD DEVICE NUMBER       CDF 0   /DF=CURRENT FIELD       CIF 10   /IF = 1       JMS I (USR       2   /FUNCTION CODE = 2       NAME   /ARG(1), POINTS TO FILE NAME       O   /ARG(2)       JMP ERR   /ERROR RETURN       .   /NORMAL RETURN     NAME,     FILENAME PROG.PA     This request looks up a permanent file entry with the  name  PROG.PA.     The  device number on which the lookup is to be performed is in AC bit     8 to 11. ARG(1) contains a pointer to the file name.   Note  that the     file name block must be in the same memory field as the call, and that     it cannot be in locations 10000 to 11777. The device handler must have     been  previously  loaded  into  core.   If the normal return is taken,     ARG(l) is changed to  the starting  block of  the  file and  ARG(2)     contains  the  file  length  in  blocks  as a negative number.  If the     device specified  is  a  readable, non-file  structured  device  (for     example,  the  papertape  reader), then ARG(1) and ARG(2) contain the     file length in blocks as a negative number.  If the  device  specified     is a readable, non-file structured device (for example, the paper tape     reader), then ARG(1) and ARG(2) are both set to zero.     If the error return is taken, ARG(1) and ARG(2)  are  unchanged. The     following conditions cause an error return:  1.  The device specified is a write-only device.  2.  The file specified was not found.     In addition,  specifying  illegal arguments  can cause  one  of the     following monitor errors,  followed  by a  return  to  the Keyboard     Monitor:      2-6     USER SERVICE ROUTINE       Error Message  Meaning       _____________  _______  MONITOR ERROR 2 AT xxxxx Results if an I/O error occurred  (DIRECTORY I/O ERROR) while reading the device directory.  MONITOR ERROR 3 AT xxxxx Results if the device  handler for  (DEVICE HANDLER NOT IN CORE) the  specified device is  not in core.  MONITOR ERROR 4 AT xxxxx Results if bits 8 to 11 of  the AC  (ILLEGAL USR CALL) are zero.     The LOOKUP function is the standard method of opening a permanent file     for input.     2.2.3  ENTER Output (Tentative) File   Function Code = 3     The ENTER function is used to create a tentative file entry to be used     for output.  An example of a typical ENTER function is as follows:       TAD VAL   /AC IS NOT ZERO       CDF 0   /DF = CURRENT FIELD       CIF 10   /IF = 1       JMS I (USR       3   /FUNCTION CODE = 3       NAME   /ARG(1) POINTS TO FILE NAME       0   /ARG(2)       JMP ERROR   /ERROR RETURN       .   /NORMAL RETURN       .       .     NAME,     FILENAME PROG.LS     Bits 8 to 11 of the AC contain  the  device  number  of  the  selected     device;   the  device handler for this device must be loaded into core     before performing an ENTER function.  If bits 0 to 7  of  the  AC are     non-zero, this value is considered to be a declaration of the maximum     length of the file.  The ENTER function searches  the  file  directory     for the smallest empty file that contains at least the declared number     of blocks. If bits 0 to 7 of the AC  are zero,  the  ENTER  function     locates the largest available empty file.     On a normal return, the contents  of  ARG(1)  are replaced  with the     starting  block  of the file.  The 2's complement of the actual length     of the created tentative file in blocks (which  can  be  equal  to or     greater  than  the requested  length)  replaces  ARG(2). If the file     directory contains any Additional Information Words, the  system  DATE     (location 17666) is written as the first Additional Information Word     of the newly created tentative file at this time.      2-7     USER SERVICE ROUTINE      NOTE    If the  selected  device  is  not file    structured but permits output operations    (e.g., the high speed punch), the  ENTER    operation always succeeds.   In this    case, ARG(l) and ARG(2) are both  zeroed    on return.     If the error return is taken, ARG(1) and ARG(2)  are  unchanged. The     following conditions cause an error return:  1.  The device specified by bits 8 to 11 of the AC is a read only      device.  2.  No empty file exists which  satisfies  the  requested  length      requirement.  3.  Another tentative file is already active on this device (only      one output file can be active at any given time).  4.  The first word of the file name was 0 (an illegal file name).     In addition, one of the following monitor errors can  occur,  followed     by a return to the Keyboard Monitor:       Error Message   Meaning       _____________   _______  MONITOR ERROR 2 AT xxxxx Result if an I/O error occurred  (DIRECTORY I/O ERROR) while reading or writing the device directory.  MONITOR ERROR 3 AT xxxxx Results if the device handler for  (DEVICE HANDLER NOT IN CORE) the  specified device is  not  in core.  MONITOR ERROR 4 AT xxxxx Results if AC bits 8 to 11 are  (ILLEGAL USR CALL) zero.  MONITOR ERROR 5 AT xxxxx Read error on the system device  (I/O ERROR ON SYS) while bringing in the overlay code for the ENTER function.  MONITOR ERROR 6 AT xxxxx Results if a directory overflow  (DIRECTORY OVERFLOW) occurred  (no room  for  tentative file entry in directory).     2.2.4 The CLOSE Function Function Code = 4     The CLOSE function has a dual purpose:  first, it is used to close the     current  active  tentative file, making it a permanent file.  Second,     when a tentative file becomes permanent it is necessary to remove any      2-8     USER SERVICE ROUTINE     permanent file having the same name;  this operation is also performed     by the CLOSE function.  An example of CLOSE usage follows:       TAD VAL   /GET DEVICE NUMBER       CDF 0   /DF=CURRENT FIELD       CIF 10   /IF=1       JMS I (USR       4   /FUNCTION CODE = 4       NAME   /ARG(1)       15   /ARG(2)       JMP ERR   /ERROR RETURN       .   /NORMAL RETURN       .     NAME,     FILENAME PROG.LS     The device number is contained in AC bits 8 to  11 when  calling the     USR.   ARG(1)  is a pointer to the name of the file to be deleted and     ARG(2) contains the number of blocks to be used for the new  permanent     file.     The normal sequence of operations on an output file is:  1.  FETCH the device handler for the output device.  2.  ENTER the tentative file on the output  device,  getting the      starting block and the maximum number of blocks available for      the file.  3.  Perform the actual output using the device  handler,  keeping      track  of how many blocks are written, and checking to insure      that the file does not exceed the available space.  4.  CLOSE the tentative file, making it  permanent. The  CLOSE      operation would always use the same file name as the ENTER      performed in step 2. The closing file length would have  been      computed in step 3.     After a normal  return  from  CLOSE,  the active tentative  file is     permanent and  any  permanent  file  having  the specified file name     already stored on the device is deleted.  If the specified device is a     non-file  structured device that permits output (the paper tape punch,     for example) the CLOSE function will always succeed.      NOTE    The user must be careful to specify the    same  file names  to  the ENTER and the    CLOSE functions.  Failure to do  so can    cause   several   permanent files with    identical  names  to   appear   in the    directory. If CLOSE is intended only to    be used to delete  some  existing  file,    then the number of blocks, ARG(2) should    be zero.      2-9     USER SERVICE ROUTINE     The following conditions cause the error return to be taken:  1.  The device specified by bits 8 to 11 of the AC is a read only      device.  2.  There is neither an active tentative file to be made  into  a      permanent file, nor a permanent file with the specified name      to be deleted.     In addition, one of the following Monitor errors can occur:       Error Message  Meaning       _____________  _______  MONITOR ERROR 1 AT xxxxx Results if the length specified by  (CLOSE,ERROR) ARG(2) exceeded the allotted space.  MONITOR ERROR 2 AT xxxxx Results if  an I/O error occurred  (DIRECTORY I/O ERROR) while reading or writing the device directory.  MONITOR ERROR 3 AT xxxxx Results if the device handler for  (DEVICE HANDLER NOT IN CORE) the  specified device is  not  in core.  MONITOR ERROR 4 AT xxxxx Results if AC bits 8 to 11 are  (ILLEGAL USR CALL) zero.     2.2.5  Call Command Decoder (DECODE) Function Code = 5     The DECODE function causes the USR to load and  execute  the  Command     Decoder. The  Command  Decoder accepts (from the Teletype) a list of     input and output devices and files, along with various  options. The     Command  Decoder  performs a LOOKUP  on  all  input  files,  sets up     necessary tables in the top page of field 1, and returns to  the  user     program.  These operations are described in detail in Chapter 3, which     should be read before attempting to use the DECODE function.     A typical call to the Command Decoder looks as follows:       CDF 0   /DF=CURRENT FIELD       CIF 10   /IF=1       JMS I (USR       5   /FUNCTION CODE = 5       2001   /ARG(1), ASSUMED INPUT EXTENSION       0   /ARG(2), ZERO TO PRESERVE ALL   /TENTATIVE FILES       .   /NORMAL RETURN       .       .     ARG(1) is the assumed input extension, in the preceding example it is     2-10     USER SERVICE ROUTINE     ".PA".  On return from the Command Decoder, information is stored in     tables located in the top page of memory field 1. The DECODE  function     also  resets  all system tables as in the RESET function (see RESET     function, section 2.2.11)  if  ARG(2)  is  0  all  currently  active     tentative files  remain  open;   if  ARG(2) is non-zero all tentative     files are deleted and the normal return is  to ARG(2) instead of     ARG(2)+1.     The DECODE function  has no  error  return  (Command  Decoder  error     messages are given in Chapter 3). However, the following Monitor error     can occur:       Error Message  Meaning       _____________  _______  MONITOR ERROR 5 AT xxxxx I/O error occurred while reading or  (I/O ERROR ON SYS) writing on the system device.     2.2.6  CHAIN Function  Function Code = 6     The CHAIN function permits a program to load and start another program     with  the restriction that the program chained to must be a core image     (.SV) file located on the system device.  A typical implementation of     the CHAIN function looks as follows:       CDF 0   /DF=CURRENT FIELD       CIF 10   /IF=1       JMS I (USR       6   /FUNCTION CODE = 6       BLOCK   /ARG(1), STARTING BLOCK NUMBER     There is no normal or error return from CHAIN.  However, the following     monitor error can occur:       Error Message  Meaning       _____________  _______  MONITOR ERROR 5 AT xxxxx I/O error occurred while reading or  (I/O ERROR ON SYS) writing on the system device.  CHAIN ERR If an attempt is made to CHAIN to a file  which  is not  a core image (.SV) file.  Control returns to the keyboard monitor.     The CHAIN function loads a core  image  file  located  on the  system     device  beginning at  the block number specified as ARG(1) (which is     normally determined by performing a LOOKUP on the desired file  name).     Once loaded, the program is started at an address one greater than the     starting address specified by the program's Core Control Block.     CHAIN automatically performs a USROUT function (see section 2.2.9) to     dismiss the USR from core, and a RESET to clear all system tables see     section 2.2.11), but CHAIN does not delete tentative files.     2-11     USER SERVICE ROUTINE     The areas of core altered by the CHAIN function are determined by the     contents  of  the Core Control Block of the core image file loaded by     CHAIN.  The Core Control Block for the file is set up by other  ABSLDR     or LOADER programs.  It can be modified by performing a SAVE command     with specific arguments.  Every page of core in  which  at least one     location  was  saved  is  loaded. If  the  page is  one of the "odd     numbered" pages (pages 1, 3, etc.; locations 0200 to  0377,  0600 to     0777,  etc.),  the previous page is always loaded. In  addition, CHAIN     always alters the contents of locations 07200 to 07577.     NOTE    CHAIN destroys a necessary part  of the    ODT resident  breakpoint routine.  Thus    an ODT  breakpoint should never be    maintained across a CHAIN.     With the above exceptions, programs can pass data back  and  forth in     core while chaining.  For example, FORTRAN programs normally leave the     COMMON area in memory field 1 unchanged.  This COMMON area can then be     accessed by the program activated by the CHAIN.     2.2.7  Signal User ERROR      Function Code = 7     The USR can be called to print a user error  message  for a  program.     The following is a possible ERROR call:       CDF 0   /DF = CURRENT FIELD       CIF 10   /IF = 1       JMS I (USR       7   /FUNCTION CODE = 7       2   /ARG(1), ERROR NUMBER     The ERROR function causes a message of the form:       USER ERROR n AT xxxxx     to be printed.  Here n is the error number given as ARG(1); n must be     between  0 and  11  (octal),  and xxxxx is the address of ARG(1). If     ARG(1) in the sample call above were at location 500 in field  0, the     message:       USER ERROR 2 AT 00500     would be printed. Following the message, the USR returns control to     the Keyboard Monitor, preserving the user program intact.     The error number is arbitrary.  Two numbers  have currently  assigned     meanings:     2-12     USER SERVICE ROUTINE       Error Message  Meaning       _____________  _______  USER ERROR 0 AT xxxxx During a RUN, GET,  or R  command, this  error  message indicates that an error occurred while loading the core image.  USER ERROR 1 AT xxxxx While executing a FORTRAN or  SABR program, this error indicates that a call was  made to  a subroutine that was not loaded.     2.2.8  Lock USR in Core (USRIN)   Function Code = 10     When making a number of calls to the USR  it  is  advantageous  for  a     program  to avoid reloading the USR each time a USR call is made. The     USR can be brought into core and kept there for subsequent use by the     USRIN  function.  The calling sequence for the USRIN function looks as     follows:       CDF 0   /DF = CURRENT FIELD       CIF 10   /IF = 1       JMS I (7700       10   /FUNCTION CODE = 10       .   /NORMAL RETURN       .       .     THE USRIN function saves the contents of locations 10000 to  11777 on     the  system  scratch  blocks,  provided the calling program loads into     this area as indicated by the current JSW, and  loads  the USR,  then     returns control to the user program.      NOTE    If bit 11 of the current Job Status Word    is a  one, the USRIN function will not    save the  contents of  locations  10000    thru 11777.     2.2.9  Dismiss USR from Core (USROUT) Function Code = 11     When a program has loaded the USR into core with  the  USRIN  function     and  no  longer wants or needs the USR in core, the USROUT function is     used to restore the original contents of locations 10000 to 11777. The     calling sequence for the USROUT function is as follows:     2-13     USER SERVICE ROUTINE       CDF 0   /DF = CURRENT FIELD       CIF 10   /IF = 1       JMS I (200   /DO NOT JMS TO 17700!!       11   /FUNCTION CODE = 11       .   /NORMAL RETURN       .       .     The  USROUT  function  and the  USRIN  function are   complementary     operations.   Subsequent calls to the USR must be made by performing a     JMS to location 7700 in field 1.       NOTE    If bit 11 of the current Job Status Word    is a  1,  the  contents of core are not    changed by the USROUT function.  In this    case  USROUT  is  a redundant operation    since core was  not  preserved  by the    USRIN function.     2.2.10  Ascertain Device Information (INQUIRE) Function Code = 12     On some occasions a user may wish to determine  what  internal  device     number  corresponds  to  a given device name  or whether the device     handler for a specified device is in core, without actually performing     a FETCH  operation.   INQUIRE performs these operations for the user.     The function call for INQUIRE  closely  resembles the  FETCH  handler     call.     INQUIRE, like FETCH, has two distinct forms:  1.  Obtain the device number corresponding to a given device name      and  determine  if  the  handler for  that device is in core      (example shown below).  2.  Determine if the handler corresponding  to  a  given  device      number is in core.     An example of the INQUIRE call is shown below:       CLA   /AC MUST BE CLEAR       CDF 0   /DF = CURRENT FIELD       CIF 10   /IF = 1       JMS I (USR       12   /FUNCTION CODE = 12       DEVICE DTA3   /GENERATES TWO WORDS:   /ARG(1) AND ARG(2)       0   /ARG(3)       JMP ERR   /ERROR RETURN       .   /NORMAL RETURN       .       .     2-14     USER SERVICE ROUTINE     ARG(1) and ARG(2) contain the device name in  standard  format.   When     the  normal  return  is  taken  ARG(2) is changed to the device number     corresponding to the given name, and ARG(3) contains either the  entry     point  of the device handler if it is already in core, or zero if the     corresponding device handler has not yet been loaded.     A slightly different set of arguments  is used  to  inquire  about  a     device by its device number:       TAD VAL   /AC IS NON-ZERO       CDF 0   /DF = CURRENT FIELD       CIF 10   /IF = 1       JMS I (USR       12   /FUNCTION CODE = 12       0   /ARG(1)       JMP ERR   /ERROR RETURN       .   /NORMAL RETURN       .       .     On entry to INQUIRE, AC bits 8 to 11 contain the device number.      NOTE    If AC bits O to 7 are non-zero, and bits    8  to  11  are  zero  (an illegal device    number) a:      MONITOR ERROR 4 AT xxxxx    message is printed and program execution    is terminated.     On normal return ARG(1) is set  to the  entry  point  of the  device     handler  if it is already in core, or zero if the corresponding device     handler has not yet been loaded.  The error return in  both  cases is     taken  only  if there is no device corresponding to the device name or     number specified.     2.2.11  RESET System Tables Function Code = 13     There are certain occasions when it is desired  to reset the  system     tables,  effectively removing from core all device handlers except the     system handler.  An example of the RESET function is shown below:       CDF 0   /DF = CURRENT FIELD       CIF 10   /IF = 1       JMS I (USR       13   /FUNCTION CODE = 13       0   /0 PRESERVES TENTATIVE FILES       .   /NORMAL RETURN       .       .     2-15     USER SERVICE ROUTINE     RESET zeros all entries except the one for the system  device  in the     Device  Handler  Residency Table (see  section  B.3.3,  removing all     device handlers, other than that for the  system  device, from  core.     This  should be done anytime a user program modifies any page in which     a device handler was loaded.     RESET has the additional function of  deleting  all  currently  active     tentative files (files that have been entered but not closed). This is     accomplished by zeroing bits 9 through 11 of every entry in the Device     Control Word Table (see section B.3.5).     If RESET is to be used in this last  fashion,  to delete all  active     tentative files, then ARG(1) must be non-zero and the normal return is     to ARG(1) rather than to ARG(1)+1. For  example,  the  following  call     would serve this purpose       CDF 0   /DF:CURRENT FIELD       CIF 10   /IF = 1       JMS I (USR       13   /FUNCTION CODE = 13       CLA CMA   /NON-ZERO:     The normal return would execute the CLA CMA and all  active  tentative     files on all devices would be deleted.  The Keyboard Monitor currently     does not reset the Monitor tables. If user programs which do not call     the  Command  Decoder  are used, it  is wise to do a RESET operation     before loading device handlers.  The RESET will ensure that the proper     handler will be loaded into core.     2-16   CHAPTER 3      THE COMMAND DECODER     OS/8 provides a powerful subroutine called the Command Decoder for use     by all system programs.  The Command Decoder is normally called when a     program starts running.  When called, the Command Decoder prints an  *     and  then accepts a  command  line  from the  console Teletype that     includes a list  of  I/O  devices, file  names,  and  various  option     specifications.   The  Command  Decoder validates the command line for     accuracy, performs a LOOKUP on all input files, and  sets up  various     tables for the calling program.     The operations performed by the Command Decoder greatly  simplify the     initialization  routines  of  all OS/8 programs. Also, since command     lines all have a standard basic structure, the Command  Decoder  makes     learning to use OS/8 much easier.     3.1  COMMAND DECODER CONVENTIONS     Chapter 1 of the OS/8 HANDBOOK describes the syntax  for  the  command     line  in  detail. A brief synopsis is given here only to clarify the     later discussion in this chapter.     The command line has the following general form:       *output files < input files/ (options)     There can be 0 to 3 output files and 0 to 9 input files specified.  Output File Format       Meaning  __________________       _______  EXPLE.EX Output to a file named EXPLE.EX on device DSK   (the   default  file storage device).  LPT: Output to  the LPT.   This  format generally   specifies a  non-file structured device.  DTA2:EXPLE.EX Output to a file named EXPLE.EX on device DTA2.  DTA2:EXPLE.EX[99] Output to a file named EXPLE.EX on device DTA2. A maximum output file size of 99 blocks is specified.  null No output specified.      3-1      THE COMMAND DECODER     An input file specification has one of the following forms:  Input File Format     Meaning  _________________     _______  DTA2:INPUT Input from a file named INPUT.df on device DTA2.  "df"  is the assumed input file extension  specified in the Command Decoder.  DTA2:INPUT.EX Input from a file named INPUT.EX on device DTA2. In  this  case .EX overrides the  assumed input  file extension.  INPUT.EX Input from a file named INPUT.EX. If there is no previously specified input device, input is from  device DSK,   the   default  file  storage device;   otherwise, the   input device is  the same  as  the last specified input device.  PTR: Input from  device  PTR;   no  file name   is   needed   for   non-file structured devices.  DTA2: Input from device DTA2 treated as a non-file structured device, as, for example, in the PIP command line:     *TTY:/L<DTA2: In both of the last two formats, no LOOKUP operation is performed since the  device  is  assumed   to be non-file structured.  null Repeats input from  the  previous device specified (must not be first in input list, and must refer to  a non-file  structured  device). For example:     * <PTR:,, (two  null  files)  indicates  that three paper tapes are to be loaded.      NOTE    Whenever a file extension is left off an    input  file specification, the Command    Decoder first performs a LOOKUP for the    given name appending a specified assumed    extension. If  the  LOOKUP  fails,   a      3-2      THE COMMAND DECODER    second  LOOKUP  is made  for  the file    appending a null (zero) extension.     The Command Decoder verifies that the  specified  device  names,  file     names, and extensions consist only of the characters A through Z and 0     through 9. If not, a syntax error is generated and the command line is     considered to be valid.     There are two  kinds  of options that  can  be specified:   first,     alphanumeric  option  switches  are  denoted  by a single alphanumeric     character preceded by a slash (/) or a string of  characters  enclosed     in parentheses; secondly,  a  numeric option can be specified as an     octal number from 1 to 37777777 preceded by an equal sign (=).  These     options are passed to the user program and are interpreted differently     by each program.     Finally, the Command Decoder permits the command line to be terminated     by either the RETURN or ALT MODE key.  This information is also passed     to the user program.     3.2  COMMAND DECODER ERROR MESSAGES     If an error in the command line is detected by  the  Command  Decoder,     one  of  the  following  error  messages  is printed.  After the error     message, the Command Decoder starts a new line, prints an *, and waits     for another command line. The erroneous command is ignored.       Error Message Meaning       _____________ _______  ILLEGAL SYNTAX The  command  line   is  formatted incorrectly.  TOO MANY FILES More than  three  output  files or nine  input  files  were specified. (Or in special mode,  more  than  1 output file  or  more than 5 input files.)  device DOES NOT EXIST The specified device name does not correspond  to any permanent device name or any  user  assigned  device name.  name NOT FOUND The specified input file  name was not found on the selected device.     3.3 CALLING THE COMMAND DECODER     The Command Decoder is initiated by the DECODE function  of  the  USR.     DECODE  causes  the  contents  of locations 0 to 1777 of field 0 to be      3-3      THE COMMAND DECODER     saved on the system scratch blocks, and Command Decoder to be  brought     into  that area  of core and started.  When the command line has been     entered and properly interpreted, the Command  Decoder  exits  to the     USR,  which restores the original contents of 0 to 1777 and returns to     the calling program.      NOTE    By setting bit 10 of the Job Status Word    to a  1  the user can avoid this saving    and restoring of core for programs that    do not occupy locations 0 to 1777.     The DECODE call can reside in the area between 0000 to 1777 and  still     function correctly.  A typical call would appear as follows: CDF 0   /SET DATA FIELD TO CURRENT FIELD CIF 10   /INSTRUCTION FIELD MUST BE 1 JMS I (USR /USR=7700 IF USR IS NOT IN CORE   /OR USR=0200 IF USRIN WAS PERFORMED 5   /DECODE FUNCTION = 5 2001   /ARG(1),ASSUMED INPUT EXTENSION 0   /ARG(2),ZERO TO PRESERVE   /ALL TENTATIVE FILES .   /NORMAL RETURN . .     ARG(1) is the assumed input extension.  If an input file name is given     with  no  specified  extension,  the  Command Decoder first performs a     LOOKUP for a file having the given name with  the assumed extension.     If the LOOKUP fails, the Command Decoder performs a second LOOKUP for     a file having the given name and a null  (zero)  extension.   In  this     example, the assumed input extension is ".PA".     DECODE performs an automatic RESET operation (see section 2.2.11) to     remove  from  core all device handlers except those equivalent to the     system device.  As in the RESET  function,  if  ARG(2)  is  zero all     currently active tentative  files  are preserved.   If ARG(2) is     non-zero, all tentative files are deleted and DECODE returns to ARG(2)     instead of ARG(2)+1.     As the Command Decoder normally handles all of its own  errors,  there     is no error return from the DECODE operation.     3.4  COMMAND DECODER TABLES     The Command decoder sets up various tables in the top page of field  1     that describe the command line typed to the user program.      3-4      THE COMMAND DECODER     3.4.1  Output Files     There is room for three entries in the output file table  that  begins     at location 17600. Each entry is five words long and has the following     format:  0  1 2  3  4 5  6  7  8  9 10 11 +-------------------------------------+ WORD 1 | USER SPECIFIED |4 BIT-DEVICE | | FILE LENGTH |    NUMBER   | +-----------------+-----+-------------+ WORD 2 | FILE NAME  |   FILE NAME      |\ | CHARACTER 1  |   CHARACTER 2     | | +-----------------+-------------------+ | WORD 3 | FILE NAME  |   FILE NAME      | \ OUTPUT FILE NAME | CHARACTER 3  |   CHARACTER 4     | / 6 CHARACTERS +-----------------+-------------------+ | WORD 4 | FILE NAME  |   FILE NAME      | | | CHARACTER 5  |   CHARACTER 6     |/ +-----------------+-------------------+ WORD 5 | FILE EXTENSION  |   FILE EXTENSION  |\ FILE EXTENSION | CHARACTER 1  |   CHARACTER 2     |/ 2 CHARACTERS +-----------------+-------------------+     Bits 0 to 7 of word 1 in each entry contain the file  length,  if the     file  length was specified with the square bracket construction in the     command line.  Otherwise, those bits are zero.     The entry for the first output file is in locations  17600 to  17604,     the  second  is  in  locations  17605  to 17611, and the third is in     locations 17612 to 17616. If  word  1  of any  entry  is zero, the     corresponding  output  file was not specified.  A zero in word 2 means     that no file name was specified.     Also, if word 5 of any entry is zero no file extension  was  specified     for  the  corresponding  file.  It is left to the user program to take     the proper action in these cases.     These entries are in  a  format  that  is acceptable  to the  ENTER     function.     3.4.2  Input Files     There is room for nine entries in the input file table that begins at     location  17617.  Each  entry  is two words long and has the following     format:      3-5      THE COMMAND DECODER   0  1 2  3  4  5  6 7  8  9 10 11       +-------------------------+--------------+       WORD 1  | MINUS FILE | 4-BIT DEVICE |       | LENGTH |  NUMBER |       +-------------------------+--------------+       WORD 2  | STARTING BLOCK OF FILE |       +----------------------------------------+     Bits 0 to 7 of word 1 contain the file length as  a  negative  number.     Thus,  377 (octal) in these bits is a length of one block, 376 (octal)     is a length of two blocks, etc. If  bits  0  to 7  are zero, the     specified file  has a length greater than or equal to 256 blocks or a     non-file structured device was specified.      NOTE    This restriction to 255 blocks of actual    specified  size  can cause some problems    if the program has no way  of  detecting    end-of-file conditions.   For  example,    PIP cannot copy in image mode  any file    on a  file structured  device  that is    greater than 255 blocks  long,  although    it can handle in /A or/B modes (ASCII or    Binary) files of unlimited size.  In  /A    or/B  modes PIP  will detect the CTRL/Z    marking the end-of-file.    If this is liable to be a problem, it is    suggested  that  the user program employ    the special mode of the Command  Decoder    described in section 3.5 and perform its    own LOOKUP on the input files to  obtain    the exact file length.     The two-word  input  file list  entries  beginning  at  odd  numbered     locations from  17617 to 17637 inclusive. If location 17617 is zero,     no input files were indicated in the command line. If less than  nine     input  files were specified, the unused entries in the input file list     are zeroed (location  17641  is  always  set  to  zero  to provide  a     terminator even when no files are specified).     3.4.3  Command Decoder Option Table     Five words are reserved beginning at  location  17642  to store the     various  options  specified  in the command line. The format of these     five words is as follows:      3-6      THE COMMAND DECODER     0 1  2  3 4  5  6  7  8 9  10 11    +-----------------------------------+      17642 |    HIGH ORDER 11 BITS OF |    |  = N OPTIONS |    +--+--+--+--+--+--+--+--+--+--+--+--+      17643 |A |B |C |D |E |F |G |H |I |J |K |L |    |  |  |  | |  |  | |  |  |  |  | |      17644 |M |N |O |P |Q |R |S |T |U |V |W |X |    |  |  |  | |  |  | |  |  |  |  | |      17645 |Y |Z |0 |1 |2 |3 |4 |5 |6 |7 |8 |9 |    +--+--+--+--+--+--+--+--+--+--+--+--+      17646 | LOW ORDER 12 BITS OF = > OPTIONS |    +-----------------------------------+     Each of these bits corresponds to one  of the  possible  alphanumeric     option  switches. The  corresponding  bit  is  1 if  the switch was     specified, 0 otherwise.      NOTE    If no  =  n option is  specified, the    Command  Decoder zeroes 17646 and bits 1    to 11  of  17642.  Thus,  typing  =0  is    meaningless  since  the  user  program    cannot  tell   that  any option was    specified.    Bit 0 of location  17642  is  0  if the    command   line   was   terminated  by  a    carriage return, 1 if it was  terminated    by an ALT MODE.     3.4.4  Example     To clarify some of the preceding, consider the interpretation  of the     following command line:       *BIN[10]<PTR:,,DTA2:PARA,MAIN /L=14200$     If this command line is typed to PAL8, it would cause  assembly  of  a     Program  consisting of four separate parts:  two paper tapes, one file     named PARA.PA (or just PARA) on DTA2, and one file named  MAIN.PA (or     just  MAIN)  also on DTA2. The binary output is placed on a file named     BIN.BN on device DSK, for which only 10 blocks need be allocated. No     listing  is  generated.   In addition, automatic loading of the binary     output is specified by the /L option, with the starting address  given     as 4200 in field 1. Finally, the line is terminated by the ALTMODE key     (which echoes as $) causing a return to the Keyboard Monitor after the     program is loaded.     In the case of this example, the Command Decoder returns to PAL8  with     the following values in the system tables:      3-7      THE COMMAND DECODER      NOTE    The entries for PTR (where no input file    name is specified) have a starting block    number and file size of zero.   This  is    always  true  of  the  input table for a    non-file structured device, or  a file    structured device on which no file name    is given.      3-8      THE COMMAND DECODER    +-------+       17600|  0242 |-- DSK:IS DEVICE NUMBER 2    |    |    |  0211 |\    |    | |    |  1600 |  > FILE NAME IS BIN    |    | |    |  0000 |/    |    |       17604|  0000 |-- NULL EXTENSION    |-------|       17605|    |\    |    | | REMAINING ENTRIES    ~    ~  > IN OUTPUT TABLES    |    | | ARE ZERO       17616|_______|/       17617|    |\    |  0016 | |    |    |  > FIRST PTR INPUT    |  0000 | |       17620|_______|/       17621|    |\    |  0016 | |    |    |  > SECOND PTR INPUT    |  0000 | |       17622|_______|/       17623|  7667 |\    |    | | DTA2: PARA PA IS 5 BLOCKS LONG,    |  0100 | | BEGINNING AT 100(8)       17624|_______|/       17625|    |\    |  0007 | | DTA2: MAIN PA IS 256(10) OR MORE    |    |  > BLOCKS LONG, BEGINNING AT BLOCK 105(8)    |  0105 | |       17626|_______|/       17627|    |\    |    | | REMAINING ENTRIES    ~    ~  > IN INPUT TABLES    |    | | ARE ZERO.       17641|    |/    |    |       17642|  4001 |-- LINE WAS TERMINATED BY ALT MODE    |    |       17643|  0001 |\    |    | |       17644|  0000 | \ /L WAS ONLY OPTION SWITCH    |    | / SPECIFIED    |    | |       17645|  0000 |/    |    |       17646|  4200 |-- =14200 WAS SPECIFIED    +-------+      3-9      THE COMMAND DECODER     3.5  SPECIAL MODE OF THE COMMAND DECODER     Occasionally the user program does not want  the  Command Decoder to     perform  the  LOOKUP  on  input files, leaving this option to the user     program itself.  Programs such as format conversion  routines  which     access non-standard file structures could use this special format. If     the input files  were  not OS/8  format, a  command  decoder  LOOKUP     operation would fail.  The capability to handle this case is provided     in the OS/8 Command Decoder.  This capability is generally referred to     as the "special mode" of the Command Decoder.     3.5.1  Calling the Command Decoder Special Mode     The special mode call to the  Command  Decoder  is identical  to the     standard  DECODE  call  except  that the assumed input file extension,     specified by ARG(1), is equal to 5200. The value 5200  corresponds to     an assumed  extension  of ".*", which  is  illegal.  Therefore, the     special mode of the Command Decoder  in  no  way  conflicts  with the     normal mode.     3.5.2  Operation of the Command Decoder in Special Mode     In special mode the Command Decoder is loaded  and inputs a  command     line  as  usual.  The appearance of the command line is altered by the     special mode in these respects:  1.  Only one output file can be specified.  2.  No more than five input files can be specified,  rather  than      the nine acceptable in normal mode.  3.  The characters asterisk (*) and question mark (?) are  legal      in  file names  and  extensions, both in input files and on      output files.  It is strongly suggested that these characters      be  tested  by the user program and treated either as special      options or as illegal file names. The user program  must be      careful  not  to ENTER  an  output  file with an asterisk or      question mark in its name as such a  file cannot easily be      manipulated or deleted by the standard system programs.     The output and option table set up by  the  Command  Decoder  is not     altered  in  special  mode.  Entries in the input table are changed to     the following format:      3-10      THE COMMAND DECODER  0  1 2  3  4 5  6  7  8  9 10 11 +-----------------------+--------------+ WORD 1 | | 4-BIT DEVICE |   BITS 0-7 ARE | | NUMBER       |   ALWAYS 0 +-----------------+-----+--------------+ WORD 2 | FILE NAME  |   FILE NAME       |\ | CHARACTER 1  |   CHARACTER 2      | | +-----------------+--------------------+ | WORD 3 | FILE NAME  |   FILE NAME       | \ INPUT FILE NAME | CHARACTER 3  |   CHARACTER 4      | / 6 CHARACTER +-----------------+--------------------+ | WORD 4 | FILE NAME  |   FILE NAME       | | | CHARACTER 5  |   CHARACTER 6      |/ +-----------------+--------------------+ WORD 5 | FILE EXTENSION  |   FILE EXTENSION   |\  FILE EXTENSION | CHARACTER 1  |   CHARACTER 1      |/  2 CHARACTERS +-----------------+--------------------+     The table entry for the first input file  is  in  locations  17605 to     17611;  the second in locations 17612 to 17616; the third in locations     17617 to 17623; the fourth in locations 17624 to 17630; and the  fifth     in locations  17631 to 17635. A zero in word 1 terminates the list of     input files.  If word 2 of an entry is zero, no input  file  name was     specified.     The OS/8 batch generating system  will  allow  calls  to  the  command     decoder in special mode.     3.6 CCL AND THE COMMAND DECODER     CCL uses its own copy of the  Command  Decoder  instead  of  the  copy     available from the monitor.  Thus, the CCL Command Decoder has several     options not available via standard USR  calls  to the  OS/8  Command     Decoder, e.g., multiple default extensions.     3.7 USEFUL LOCATIONS IN BATCH     BATCH will run whenever bit 0 of location 07777 is a 1. The  user may     wish to access the following useful locations in BATCH.  The locations     are in the highest memory field available to OS/8:    BATERR = 7000     JMP here to abort BATCH.    BATOUT = 7400     JMS here to print character      in AC in BATCH log.    BATSPL = 7200     JMS here to permit spooling      with default extension in AC.      3-11      THE COMMAND DECODER     3.8 CCL TABLES     A description of all tables used by CCL is included in the file CCL.PA     supplied to all users of OS/8 version 3.      3-12   CHAPTER 4     USING DEVICE HANDLERS     A device handler is a system subroutine that is used by all  parts of     the  OS/8 system and  by all standard system programs to perform I/O     transfers. All device handlers are called in the same  way  and  they     all  perform the same basic operation:  reading or writing a specified     number of 128 word records beginning at a selected core address.     These subroutines effectively  mask  the unique characteristics of     different I/O  devices from the calling program; thus, programs that     use device handlers properly  are effectively  "device  independent".     Changing devices involves merely changing the device handlers used for     I/O.     OS/8 device handlers have another important feature.  They are able to     transfer  a number of records as a single operation.  On a device like     DECtape this permits many blocks of data  to  be  transferred  without     stopping  the  tape  motion.   On a  disk,  a  single operation could     transfer an entire track or  more.   This  capability  significantly     increases the  speed of operation of OS/8 programs, such as PIP, that     have large buffer areas.      NOTE    The word "record" is defined to mean 128    words  of  data;   thus,  an  OS/8 block    consists of two 128 word records.     4.1  CALLING DEVICE HANDLERS     Device handlers are loaded into a user selected area in memory field 0     by the FETCH function.  FETCH returns in ARG(1) the entry point of the     handler loaded.  The handler is called by performing  a  JMS  to the     specified entry point address.  It has the following format:  CDF N /WHERE N IS THE VALUE OF THE CURRENT /PROGRAM INSTRUCTION FIELD TIMES 10 (OCTAL)  CIF 0 /DEVICE HANDLER ALWAYS IN FIELD 0  JMS I ENTRY  ARG(1) /FUNCTION CONTROL WORD  ARG(2) /BUFFER ADDRESS  ARG(3) /STARTING BLOCK NUMBER  JMP ERR /ERROR RETURN  . /NORMAL RETURN (I/O TRANSFER COMPLETE)  .     ENTRY 0 /ENTRY CONTAINS THE ENTRY POINT OF THE /HANDLER, DETERMINED WHEN LOADED BY FETCH      4-1      USING DEVICE HANDLERS     As with calls to the USR, it is important that the data field  is set     to the  current program field before teldevice handler is called. On     exit from the device handler, the data field will remain  set  to the     current program field.     ARG(1) is the  function  control  word,  and  contains  the  following     information:  Bits    Contents  Bit 0      0 for an input operation, 1  for an  output      operation.  Bits 1 to 5      The  number  of  128  word  records   to be      transferred.   If bits  1-5 are zero and the      device is non-file  structured  (i.e.,  TTY,      LPT, etc.) the operation is device dependent.      If  the  device  is  file structured   (SYS,      DECtape, disk,  etc.),  a  read/write  of 40      (octal) pages is performed.  Bits 6 to 8      The memory field in which the transfer is to      be performed.  Bits 9 to 11      Device dependent bits,  can  be left  zero.      Currently only  bit  11 is used; on DECtape      bit 11 determines the direction in which the      tape  is started.   If bit 11 is 0, the tape      starts in reverse.  If bit 11 is 1, the  tape      starts  forward. All  other handlers ignore      these bits at present (except TM8E and TA8E).      NOTE    Starting forward saves time as  long  as    the block number, ARG(3), is about seven    or more blocks greater than the  number    of the  block  at which  the  tape  is    currently positioned.     ARG(2) is the starting location of the transfer buffer.     ARG(3) is the number of the block on which the transfer is to  begin.     The  user program initially  determines this  value by performing a     LOOKUP or ENTER operation.  After each  transfer the  user  program     should  itself  add  to  the current block number the actual number of     blocks transferred, equal to one-half the number of 128  word  records     specified, rounded up if the number of records was odd.     There are two kinds of error returns:  fatal and non-fatal.   When an     error return occurs and the contents of the AC are negative, the error     is fatal. A fatal error can be caused by a parity error on  input,  a     write  lock  error on  output,  or an attempt to write on a read-only     device (or vice versa). The meaning can vary from device to  device,      4-2      USING DEVICE HANDLERS     but  in  all  cases  it  is  serious  enough to indicate that the data     transferred, if any, is invalid.     When an error return occurs and the contents of  the  AC  are  greater     than  or  equal  to  zero, a non-fatal error has occurred. This error     always indicates detection of the logical end-of-file.   For  example,     when  the paper tape reader handler detects the end of a paper tape it     inserts a CTRL/Z code in the buffer and takes the error exit with the     AC equal to  zero.   While all non-file structured input devices can     detect the end-of-file  condition, no  file  structured  device  can;     furthermore,  no  device handler takes the non-fatal error return when     doing output.     The following restrictions apply to the use of device handlers:  1.  If bits 1 to 5 of the  function  control word,  ARG(1), are      zero,  a transfer  of  40  (octal) pages or an entire memory      field is indicated.  Care must be used  to  ensure  that the      handler  is  not overlaid in this call.  This only applies to      file-structured handlers.  2.  The user program must never specify an input  into  locations      07600  to 07777, 17600 to  17777,  or 27600-27777, or the      page(s) in which the  device  handler  itself  resides. In      general, 7600-7777 in every memory field are reserved for use      by system software.  Those areas should be used with caution.  3.  Note that the amount of data transferred is given as a number      of  128  word  records,  exactly one  half of an OS/8 block.      Attempting to output an odd number of records can change the      contents of  the last  128 words of the last block written.      For example, outputting 128 words to a block on the RK8  disk      causes  the  last 128  words  of the block to be filled with      zeroes.  4.  The specified buffer address does not have to  begin  at the      start of a page. The specified buffer cannot overlap fields,      rather the address will "wrap around" memory.  For example, a      write  of 2  pages  starting  at location 07600 would cause      locations 07600-07777  and  00000-00177  of  field  0  to be      written.  5.  If bits 1-5 of the function control word ARG(1) are  zero,  a      device-dependent operation occurs.  Users should not expect a      40-page (full field) transfer of data.  The  CLOSE  operation      of  the  USR  calls the handler with bits 1-5 and 9-11 of the      function control word 0. This condition  means  'perform any      special close operations  desired'.  Non-file structured      handlers which need no special handling on the conclusion of      data  transfers should treat this case as a NOP. Examples of      usage of such special codes:   LPT - perform a form feed   CSAn, MTAn - write two file marks      4-3      USING DEVICE HANDLERS     4.2 DEVICE DEPENDENT OPERATIONS     This section describes briefly the operation of certain standard  OS/8     device    handlers,    including normal operation,   any   special     initialization operations for block  0,  terminating  conditions, and     response  to  control  characters typed  at  the keyboard.   Further     information on device handlers can be found in Chapter 5.     4.2.1  1-Page Terminal (TTY) (AS33)  1.  Normal Operation      This handler inputs characters from the terminal keyboard and      packs  them  into the  buffer or unpacks characters from the      buffer and outputs them to the console terminal.      On input, characters are echoed as they are typed.  Following      a carriage return, a line feed character is inserted into the      input buffer and printed on the terminal.  2.  Initialization for Block 0      None.  3.  Terminating Conditions      On input, detection of a CTRL/Z causes a CTRL/Z  (octal  code      232) to be placed in the input buffer, the remaining words of      the buffer to be filled with zeros, and a non-fatal error to      be  returned.   On output, detection of a CTRL/Z character in      the output buffer causes output  to  be  terminated  and the      normal  return  to  be  taken.   There  are  no  fatal errors      associated with the 1-page terminal handler.  4.  Terminal Interaction      CTRL/C forces a  return  to  the Keyboard  Monitor.   CTRL/Z      forces  an  end-of-file  on  input (see 3). CTRL/O terminates      printing of the contents of the current buffer on output.     4.2.2  High-Speed Paper Tape Reader (PTR)  1.  Normal Operation      This handler inputs characters from the high-speed paper tape      reader and packs them into the buffer.  2.  Initialization for Block 0      The handler prints an up-arrow (^) on the terminal and  waits      4-4      USING DEVICE HANDLERS      for  the user  to load the paper tape reader.  By typing any      single character (except CTRL/C) the user initiates  reading      of the paper tape.      NOTE    On some terminals, up-arrow is  replaced    by the circumflex (^) character.  3.  Terminating Conditions      Detection of  an end-of-tape  condition, indicated  by the      failure  to  get a  character in a specified period of time,      causes a CTRL/Z to be entered in the  buffer,  the  remaining      words  of the buffer to be filled with zeros, and a non-fatal      error to be returned.  Attempting output to  the paper  tape      reader causes a fatal error to be returned.  4.  Terminal Interaction      Typing CTRL/C forces a return to the Keyboard Monitor.     4.2.3  High-Speed Paper Tape Punch (PTP)  1.  Normal Operation      This handler unpacks characters from the output buffer and      punches them on the paper tape punch.  2.  Initialization for Block 0      None.  3.  Terminating Conditions      Attempting to input from the paper tape punch causes a  fatal      error   to  be  returned.  There are  no  non-fatal  errors      associated with this handler.  4.  Terminal Interaction      Typing CTRL/C forces a return to the  Keyboard  Monitor, but      only when actual punching has begun, or if ^C is typed before      punching commences.  If the punch is off line,  ^C  is  only      effective immediately before punching would begin.     4.2.4  Line Printer (LPT) (LPSV)  1.  Normal Operation      4-5      USING DEVICE HANDLERS      This handler unpacks characters from the buffer and  prints      them  on the  line  printer.   The characters horizontal tab      (ASCII 211)  causes  sufficient  spaces  to  be  inserted to      position the  next  character  at a "tab stop" (every eighth      column, by definition). The  character  vertical tab  (ASCII      213)  causes  a  skip to the next paper position for vertical      tabulation  if  the  line printer  hardware  provides   that      feature. The  character form feed (ASCII 214) causes a skip      to the top of the next page.  Finally, the handler  maintains      a record of  the current print column and starts a new line      after 80 or 128 columns  have  been  printed.   This  handler      functions properly  only on ASCII data. The handler for the      LS8E line printer handler utilizes  the expanded  character      capability  of  the  printer.   If  a  216 (CTRL/N) character      appears anywhere in a  line  of  text,  the  entire  line is      printed in the expanded character mode.  The 216 must be used      on a line-by-line basis.  2.  Initialization for Block 0      Before printing begins, the line printer handler  issues  a      form feed to space to the top of the next page.  3.  Terminating Condition      On detection of a CTRL/Z character in the buffer,  the  line      printer  handler issues a form feed and immediately takes the      normal return.  Attempting to input  from the  line  printer      forces  a fatal error to be returned.  A fatal error is also      returned if the line printer error flag is set.  There are no      non-fatal errors associated with the line printer handler.  4.  Terminal Interaction      Typing CTRL/C forces a return to the Keyboard Monitor.  5.  Patching the LPSV Handler      The following patches are available for the LPSV line printer      handler.      rel. loc 0: set to -printer width-l (i.e. set to -121(octal)  for  an  80  column  line  printer)      rel. loc 1: set to 4  for the LV8E   line  printers      set to 14  for  the  LP08  and  LS8E  printers      rel. loc 2: set to -40  to convert lower case to  upper case      set to 0  if your printer can print  lower case      4-6      USING DEVICE HANDLERS     4.2.5 Cassettes  1. Normal Operation      This handler performs character I/O between the cassettes and      the  buffer.   It treats cassettes as a non-file structured      device.  Data appears on cassette in 192-byte records.  2.  Initialization for Block 0      On input the cassette is rewound. On output the cassette is      rewound and a file gap is written.  3.  Terminating Condition      An end-of-file on input is a software error.  4.  Terminal Interaction      Typing CTRL/C forces a return to the Keyboard monitor.  5.  Special Codes (device dependent features)      If the handler is called with bits 1-5 of the  function  word      =0, then bits 10-11 are examined. The meaning of these codes      are as follows:      0   write a file gap      1   rewind also, then write a file gap if bit 0=1      2   space backwards one record      3   skip one file (direction depends on bit 0)      NOTE    The handler neither  reads nor  writes    standard  files.   It  is merely a paper    tape replacement.  It  writes  raw data    (organized into  192-byte records) onto    the cassettes starting at the beginning;    and then later reads it back.     The source is already in OS/8 BUILD format.  The handler has only two     entry  points (for drives A and B of a controller). The decision as to     which controller it uses is made at  assembly  time  by  changing the     symbol code.  The result is as follows:    CODE     DEVICE NAME   HANDLER DEVICE CODE    ____     ___________   _______ ___________     0 TA8A   A:CSA0    70   B:CSA1     1 TA8B   A:CSA2    71   B:CSA3      4-7      USING DEVICE HANDLERS     2 TA8C   A:CSA4    72   B:CSA5     3 TA8D   A:CSA6    73   B:CSA7     The handler has the internal device code of  27  (see  Table  2-12 in     Chapter 2 of the OS/8 HANDBOOK.  The handler is two pages long.     4.2.6  Card Reader (CDR)  1.  Normal Operation      This handler reads characters from the card reader and  packs      them  into the input buffer.  Trailing spaces (blank columns)      on a card are deleted from input.  The  handler can  accept      only  alphanumeric  format data on cards (the DEC029 standard      card codes are used).  2. Initialization for Block 0      None.  3. Terminating Conditions      A card which contains an underline character in column 1 (an      0-8-5   punch)   with  the  remaining  columns  blank  is an      end-of-file card. In addition, after reading each  card the      handler  checks to see if a CTRL/Z was typed at the keyboard.      After either an end-of-file card or a CTRL/Z being  typed,  a      CTRL/Z  is inserted in the buffer, the remaining words of the      input buffer are filled with zeros, and a non-fatal error is      returned.  Attempting  to output to the card reader causes a      fatal error to be returned.  4. Terminal Interaction      Typing CTRL/C forces a return to the Keyboard Monitor.      Typing CTRL/Z forces an end-of-file to occur (see 3.).     4.2.7 TM8-E Handler  1. Normal Operation:      When the handler is used in  its normal mode, single-file      mode, magtapes may consist of exactly one file.  It starts at      the beginning of the tape and consists of consecutive records      until an end-of-file mark (EOF) is reached.  In this sense, a      magtape is similar to one big paper tape. This is  the  same      way that OS/8 currently treats cassettes.      4-8      USING DEVICE HANDLERS      Since the capacity of magtapes is so  big,  provisions  have      been  made  for  storing multiple files per tape.  In such a      structure, several files may exist on one magtape.  They are      unlabeled and are separated from each other by a single file      mark.  The last one is followed  by  two file  marks.   Each      'file'  looks  like  a  paper  tape.   It is referenced in a      non-file structured manner.   The magtape  handler  must be      altered first to work in file mode.  Then the magtape must be      positioned to exactly the correct spot  where  the  read or      write  operation will  commence.  This may be done with any      program using  the  auxiliary  capabilities  of  the  magtape      handler  (described  below), or the positioner program, CAMP.      To read a file, the handler must be positioned to just before      the first data record of that file.  To write file #1, rewind      the tape (i.e., be at BOT).  To  write  file  #n, (n>1) the      handler  should  be positioned after the (n-1)st file mark on      the tape. Previous file n and all files past it then  become      unreadable (non-existent).      A. Device-Dependent Capabilities:  The TM8-E handler has several auxiliary  features  which  may  be invoked by a user program which calls the handler  in a device-dependent manner. These features all rely on  the  contents of bits 9-11 of the function word (argument  1 of the handler call) and some  require  argument  3 in  addition.  These features are brought to life whenever  the  handler  is  called  with  a  page  count  of 0  (bits 1-5 of the  function word).  Call bits 9-11 of the function word, the  Special Function Register (SFR) for short, and also refer  to bit 0 of the function word as the direction  bit. If  the  page  count  is not  0, the contents of the SFR are  ignored.  If the page count is 0, then the SFR together  with the  direction  bit  (and possibly argument 3) determine what  special function to perform, as follows:  SFR     OPERATION  ___     _________  0.  CLOSE.  Write two EOF's.  1.  Rewind.  2.  Space  forward/reverse  records. The  direction to      space  is determined  by the direction bit (0 means      space forward, 1 means space reverse).  The  negative      (two's  complement) of the number of records to space      over is given by argument 3 of the handler call. (-1      means  space  past one record, 0 means 4096 records.)      The error return is taken if either a  file  mark or      BOT is encountered.  In such cases, you would be left      4-9      USING DEVICE HANDLERS      positioned at the beginning of a file.  3.  Space forward/reverse files.  The direction to  space      is  determined  by  the  direction bit (0 means space      forward, 1 means space reverse). The negative of the      number  of  file marks  to  space  past is given by      argument 3 (-1 means space past  one  file  mark;  0      means  4096 file marks). In reverse mode, the tape is      left positioned at the end of a file;   an  error is      given  if BOT  is encountered.  In forward mode, the      tape is left positioned at the beginning of  a  file.      If EOD is reached, the handler automatically performs      a backspace record to leave you between the two  file      marks;  no error is given.  4.  Rewind the unit and put drive off-line.  5.  Write a single EOF.  6.  Special read/write function.  The direction  bit (as      usual)  determines  read or  write  (0 means read, 1      means  write).  The  specified   I/O   operation is      performed  between   the user's buffer (start is      specified by argument 2) and the very  next  magtape      record. Only  one  record  is  transferred  and the      user's buffer must be large  enough  to  contain it.      The  record  length  is  specified by the negative of      argument 3 (in words).  0 means a record length of      4096.  7.  Unused.  Reserved for future use. If  specified, it      currently acts as a NO-OP.     In each case, the unit affected is determined  by the  handler  entry     point.      B. Other Common Operations:  (a) To backspace n files, use Special Code 3 to pass over      n+1  file marks backwards, then use Special code 2 to      advance (forward) over one record (EOF) ignoring the      EOF error.  (b) To advance to EOD, first perform a backspace  of one      record  (or  perform  a rewind to play safe) then use      special code 3 to advance over  4096  files  in the      forward direction (argument 3=0).  2.  Special Handling for Block 0      If the handler is called to read or write block  0,  it  will      first  perform  a rewind. This feature can be patched out if      4-10      USING DEVICE HANDLERS      desired by altering relative location 1 from a 0 to a 1. This      altered  handler should be  operating  in  file mode. The      original handler should be operating in single-file mode.      A.  Special Handling for CLOSE:  A close operation is signaled to the handler by  calling  it with a function word which has a page Count of 0 (bits  1-5) and which has bits 9-11 all zeroes.  This is how the  USR  CLOSE  operation calls the handler (OS/8 V3 only).  This causes the handler  to  write  two  Successive  file  marks on the tape.  Two Successive EOF's is the software  indication of end-of-data (EOD).      B.  Restrictions:  In single-file mode, should not  have  more than  4095  blocks  because  on trying to write the 4096th block, the  handler will think it's writing block 0  and perform  a  rewind.   This  restriction does not apply when using the  handler in file-mode; but beware, some  CUSPs,  Such as  PIP, are  suspected to behave strangely on block 4096 of  non-file-structured devices.  3.  Terminating Conditions      None.  4.  Keyboard Interaction:      Typing ^C on the keyboard while the handler is  in  operation      causes  the  handler to abort and return to the OS/8 keyboard      monitor via location 7600. Such action is ill-advised  since      it leaves the magtape without an end-of-file indicator.  5.  Error Conditions:      On a hard error, the handler takes the error return  (with  a      negative AC)  and  the  AC contains the Contents of the main      status register, as follows:   Bit on      Meaning   ______      _______     0   Error flag     1   Tape rewinding     2   BOT     3   Select error     4   Parity error (vertical, longitudinal, or   CRC)     5   EOF     6   Record length incorrect     7   Data request late     8   EOT     9   File protect     10   Read compare error     11   Illegal function      4-11      USING DEVICE HANDLERS     4.2.8  File-Structured Devices  1.  Normal Operation      (DECtape, LINCtape, TD8E DECtape, DF32, RF08, and RK8, RK8E)      These handlers transfer data directly between the device and      the buffer.  2.  Initialization for Block 0      None.  3.  Terminating Conditions      A fatal error is returned whenever the transfer causes one of      the error flags in the device status register to be set. For      example, a  fatal error would  result  if  a  parity  error      occurred on input, or a write lock error occurred on output.      The device handlers generally try three times to perform the      operation before giving up  and  returning  a fatal error.      There are no non-fatal errors associated with file structured      devices.  4.  Terminal Interaction      Typing CTRL/C forces a return to the Keyboard Monitor.      NOTE    The system device handler  does NOT    respond to a typed CTRL/C.     4.2.9  TD8E DECtape     TD8E DECtape is the new accumulator transfer DECtape.  Since OS/8 is a     noninterrupt  driven  system,  TD8E  DECtape  has data transfer rates     equivalent to those for TC08 DECtape;  however, the  interrupt  should     never  be used  with  the TD8E. Device handlers for TD8 DECtape are     supplied as a standard part of OS/8.  Each pair of drives (0 and 1,  2     and  3,  etc.)  requires  a 2-page device handler.  Thus, to have all     eight TD8E drives in the system at one time will require four separate     handlers. Thus for TD8E, it is wise to restrict usage to those units     that physically exist.  Also, the tape drives are hardwired to  select     one  of  two  possible  unit  numbers;  thus, the first pair of drives     installed must be called units 0 to 1. Any others numbers will cause a     SELECT  error.   In  this case,  the computer hangs until the correct     drive is selected.      4-12      USING DEVICE HANDLERS     4.2.10 KL8E Terminal Handler     Listed  are  the  features of  the  KL8E handler.   Those  that are     conditional are marked by an asterisk:  1.  It reads a line at a time.  Whenever the user  types  CR, it      enters  CR,  LF into the buffer; it echoes CR, LF;  and then      pads the remainder of the buffer with nulls  and returns to      the calling program.  The characters get put into the buffer,      one character per word.  Thus every third character is a null      as far as OS/8 is concerned.  2.  RUBOUT deletes the previous character.  It echoes as either a      back  slash  (\) or as the character rubbed out, depending on      assembly parameters.  RUBOUT at the beginning of a line  acts      as ^U.  3.  CTRL/U echoes as ^U and erases the current line, allowing the      user  to retype it.   (It  also echoes CR, LF.) The buffer      pointer is reset to the beginning of the buffer.  4.  CTRL/Z  echoes  as  ^Z  (followed by  CR,  LF)  and  signals      end-of-input.   The ^Z enters the buffer and the remainder of      the buffer is padded with nulls. The error return  is  taken      with a positive AC (non-fatal error).  5.  Nulls are ignored. *6.  The altmode characters (octal 175 and 176) are  converted to      escapes (octal 33). *7.  Lower-case characters typed may be automatically converted to      upper case.  8.  CTRL/C echoes as ^C and  returns control to  the  keyboard      monitor via location 07600.     On output: (either normal output or when echoing input)  1.  CTRL/C on keyboard echoes as ^C and returns  control  to the      keyboard monitor via location 7600.  2.  CTRL/O on keyboard stops further echoing. All echoing ceases      (through possibly many buffer loads) until either the handler      is reloaded into core or the user types a  character  other      than to on the keyboard. Not operative during input.  3.  ^S causes the handler to stop sending to the  terminal. No      characters  are  lost  and  outputting  resumes  when a ^Q is      typed.   ^S  and ^Q  do not  echo.   These  characters are      operative only upon output.  On input, they are treated like      any other input characters.  This is  very  useful  on  high      speed CRT displays.      4-13      USING DEVICE HANDLERS  4.  Nulls are ignored. *5.  Lower case characters may be optionally printed as upper case      and flagged with an apostrophe. *6.  Tabs may be handled in one of three manners:      a.  Output as actual tabs,      b.  Output as actual tab followed by padding of two rubouts,      c.  Output as the correct number of spaces to bring the  text  to the start of the next tab stop.  7.  Whenever the output line reaches the end of the physical line      (length  set  at assembly  time),  the handler automatically      performs a carriage-return line-feed. *8.  The escape character (octal 33) prints as a dollar sign. *9.  The handler may be set to delay about 16 ms after typing any      character (specified  at assembly  time), for example, line      feed. *10.  Control characters are printed as their corresponding  letter      preceded by an up-arrow. Thus CTRL/K prints as ^K.      4-14   CHAPTER 5 RECONFIGURING THE OS/8 SYSTEM     It is sometimes necessary to construct an OS/8 system from scratch, or     to make a new peripheral device available to OS/8. Both of these tasks     are a part of reconfiguring the OS/8 system.   OS/8  BUILD,  which is     described in detail in Chapter 2 of the OS/8 HANDBOOK, allows the user     quickly and easily to build a  new system or  to alter the  device     complement of an existing system.     5.1  WRITING DEVICE HANDLERS     A device handler is a page-independent subroutine one  or two  pages     long.   The device handler must run properly in any single page or two     contiguous pages in field 0 (except 0000 to 0177 or 7600 to 7777). All     device handlers have the same calling sequence:  CDF N /N IS CURRENT FIELD TIMES 10 (OCTAL)  CIF 0 /DEVICE HANDLER LOCATED IN FIELD 0  JMS I ENTRY /ENTRY IS DETERMINED BY SR "FETCH"  FUNCTION /FUNCTION IS BROKEN DOWN AS FOLLOWS: /BIT 0 = 0 FOR READ /BIT 0 = 1 FOR WRITE /BITS 1 TO 5 = NUMBER OF PGS TO TRANSFER /BITS 6 TO 8 = FIELD FOR TRANSFER /BITS 9 TO 11 = DEVICE DEPENDENT BITS  BUFFER /CORE ADDRESS OF TRANSFER BUFFER  BLOCK /BLOCK NUMBER TO START TRANSFER  ERROR /ERROR RETURN, AC>=0 MEANS END-OF-FILE       AC<0 MEANS FATAL ERROR  NORMAL /NORMAL RETURN     The device handler reads or  writes  a  number  of 128  word  records     beginning at  the selected block. In general, device handlers should     conform to the following standards:  1.  On normal return from a device handler the AC is zero and the      DATA FIELD is always restored to its original entry value.  2.  Although the starting block number has true significance only      for file structured devices, handlers for non-file structured      devices can check the block number and perform initialization      if  the  block number is zero.  For example, the line printer      handler  outputs a  form feed  before  printing when the      specified block number is zero.      5-1  RECONFIGURING THE OS/8 SYSTEM  3.  Handlers should be written to be as  foolproof  as  possible      checking for  the most common errors in the calling program.      Examples of typical user errors  are:  calling  handler  with      non-zero AC (always perform a CLA in the handler); trying to      read on a write only device, or trying to write on  a  read      only  device (gives a fatal error return); specifying 0 pages      to be transferred (accept as meaning no actual transfer is to      take  place);  or attempting  to access a nonexistent block      (gives a fatal error return).  4.  Device handlers normally check to see if a CTRL/C (ASCII 203)      has  been typed at  the system console by the user.  If one      has, the handler aborts I/O and JMP's  to location  7600 in      field  0. The seven low order bits of the keyboard should be      checked for a 3 so as to allow parity terminals. KRS  should      be  used over  KRB so that any paper tape in the reader will      not be advanced if its character is not ^C.  5.  Device handlers should  be  able to  detect  standard  error      conditions   like  checksum   or parity errors.   Whenever      possible, several attempts to perform the transfer should be      made  before  aborting  I/O  and taking the error exit. In      addition, when operator intervention is required, the handler      would  normally  wait for the action rather than take a fatal      error exit.  For example, if the paper  tape  punch  is not      turned  on,  the PTP handler waits for the punch to be turned      on.  6.  By convention, in any handler for a  device  (like  DECtape)      that  can search either forward or backward for a block, Bit      11 of the function word (one of  the  device-dependent  bits)      controls the starting direction of the search.  Bit 11 is a 1      if the starting direction is  forward  and  a  0 if  it is      reverse. The  other  two  device  dependent  bits  are not      assigned any significance at the present time.  7.  Remember that the user specifies a multiple of 128  words to      transfer, whereas  the transfer starts at the beginning of a      128 or 256 word block.  This  means  that the  handler  must      provide  that capability of reading or writing the first half      of a block.  Writing the first half of the block causes the      contents of the second half of the block to be altered. For      example, writing 128 words to the RK8 disk (256 word  blocks)      causes the second half of the block to be filled with zeroes.      This is usually done by the hardware controller.  8.  The entry point to a two page device handler must be  in the      first page.  9.  A number of handlers (maximum of 15 decimal) can be  included      in the one or two pages of code. Where more than one handler      is included in a single handler subroutine, the handlers are      called  co-resident.  Co-resident handlers are always brought      5-2  RECONFIGURING THE OS/8 SYSTEM      into core together.  For example, all eight DECtape  handlers      fit   into   one page; hence, the  DECtape  handlers are      co-resident.  One restriction on co-resident handlers is that      if  they are  two pages long all entry points must be in the      first page. 10.  The USR, while doing file operations, maintains in  core the      last  directory  block  read in order to reduce the number of      directory reads necessary.  The proper  functioning  of  this      feature  depends on  the fact  that  every  handler  for  a      file-structured device on a single system has a unique  entry      point relative to the beginning of the handler.  The relative      entry points currently assigned for file structured  handlers      are: Device Handlers  Relative Entry Points _______________  _____________________      System Device Handler     7      DECtape, LINCtape or TD8E DECtape     10 to 17      RKA0     20      RKA1     21      RKA2     22      RKA3     23      RK08 or DF32     24      Reserved for user     40 to 67 11.  If the device is block oriented (such as DECtape,  LINCtape,      or  Disk),  then the handler transfers data directly with no      alteration.  However, if the  device  is character  oriented      (such as a paper tape reader, Teletype, or line printer), the      handler is required to pack characters  into  the buffer on      input and unpack them on output. The standard OS/8 character      packing format puts three 8-bit characters into two words as      follows:      +---------------+------------------+       WORD 1 |CHARACTER 3    | |      |  BITS 0-3    |  CHARACTER 1 |      +---------------+------------------+       WORD 2 |CHARACTER 3    | |      |  BITS 4-7    |  CHARACTER 2 |      +---------------+------------------+       0    3  4       11      For example, the 3 characters 'ABC' would be  packed  into  2      words as follows:   Word 1: 6301   Word 2: 1702      When packing characters on input, the character CTRL/Z (octal      232)  is inserted at the logical end-of-file (for example, at      the end of the  tape  in the  paper  tape  reader  handler).      Following CTRL/Z,  the  remaining  words of the input buffer      should be zeroed.      5-3  RECONFIGURING THE OS/8 SYSTEM 12.  A close operation should be performed by non-file structured      handlers if bits 1-5 and 9-11 of the function word are 0.     The device handler, whether one or two pages long, must be completely     page  independent:  it must be capable of executing in any page(s) in     field 0, except page 0 and 7600 to 7777.  Page  independent  code can     have  no  address constants.  Writing one page handlers is relatively     easy, since the addressing structure of the PDP-8 is essentially  page     independent.  Writing page relocatable code for two pages, however, is     considerably more difficult, as the two pages must communicate. The     usual  technique  utilized in writing two page handlers is to include     some initialization code which includes a JMS.   This  replaces  that     location  by  an address on the page the handler was loaded on.  Using     this, the handler can then determine where the relevant pieces of code     are in core.     As an example, the following is the initialization procedure performed     by the  TD8E DECtape routine.  This is by no means the only technique     that is possible, but it is a workable solution.    *200 /EXECUTED CODE     JINIT,    JMP INIT /START INITIALIZATION . . .     INIT,    JMS. /FOUND OUT WHERE WE ARE.     BASE,    TAD CRDQAD /INIT GETS ADDRESS OF BASE    SPA /NEGATIVE TERMINATES LIST    JMP NXINIT /INITIALIZE SECOND PAGE    TAD INIT /NOW UPDATE THE LIST OF    DCA CRDQAD /ADDRESS DEPENDENT LOCATIONS    ISZ .-1 /POINT TO NEXT ELEMENT    ISZ BASE /NEXT INPUT VALUE    JMP BASE /LOOP OVER INPUT TABLE. . . . .     CRDQAD,    R4LINE-BASE /THESE ARE ALL POSITIVE DIFFERENCES,     CINIT2,    INIT2-BASE /SINCE THE ROUTINES INDICATED ARE     CSELCT,    SELECT-BASE /IN THE SECOND PAGE. AFTER     CXUNIT,    XUNIT-BASE /INITIALIZATION, CRDQAD POINTS TO     BUFF,    4000 /THE ACTUAL ADDRESS OF R4LINE, ETC. . /THE 4000 IN BUFF TERMINATES . /THE FIRST INITIALIZATION. . /MORE PAGE INDEPENDENT CODE     NXINIT,    JMS I CINIT2 /INITIALIZE SECOND PAGE     BASE2,    DCA JINIT /CLEAR OUT JINIT. NO MORE    JMP JINIT /RELOCATING IS NEEDED UNTIL THE /HANDLER IS LOADED INTO CORE AGAIN.      5-4  RECONFIGURING THE OS/8 SYSTEM    *400 /SECOND PAGE OF HANDLER     INIT2,    0 /ADDRESS OF BASE2 GOES HERE     INIT3,    TAD CTRY3    SNA /A 0 TERMINATES THIS LIST    JMP I INIT2    TAD INIT2 /ADD VALUE OF BASE2 TO LIST    DCA CTRY3 /PUT BACK INTO LIST    ISZ .-1 /NEXT LOC. TABLE    ISZ INIT3    JMP INIT3 . . . .     CTRY3,    TRY3-BASE2 /THIS LIST GETS VALUE OF BASE2     CRWCOM,    TRWCOM-BSSE2 /ADDED IN TO POINT TO THE REAL     XBUFF,    0 /ROUTINE.     Writing 2 page independent code can be  expensive in  terms  of  core     required. The routines should be set up in such a way as to minimize     communication between the two pages.  Some other  points  to  keep in     mind are:  1.  Relocation code is once-only code.  It is done once when the      handler  is  loaded  and need  never be done again until the      handler is  re-loaded  from  the system device.  For  this      reason, the relocation code can be placed in a buffer area or      setup in temporary scratch locations which are later used as      temporary storage.  2.  A useful hint is that a JMP into the next page of code is not      required.  The code can just as easily fall through 377 into      400. This may save a few locations of relocation code.  3.  Useful techniques for writing 2-page handlers can be found in      the source of the KL8E handler.     5.2  INSERTING DEVICE HANDLERS INTO OS/8     After the handler has  been  written  and thoroughly  debugged  as  a     stand-alone routine, it can be integrated into the OS/8 Monitor, where     it will  become  a  resident  device  handler.   To  accomplish the     integration, use OS/8 BUILD, described thoroughly in the BUILD section     in Chapter 2 of the OS/8 HANDBOOK.     Notes for writing system handlers system handlers may  be integrated     into BUILD just like non-system handlers with the following additional     notes:      5-5  RECONFIGURING THE OS/8 SYSTEM  1.  Body of system handler should be origined to  200  but  must      start  with  a  2 BLOCK 7.  Entry point must be at relative      location 7 (corresponds to location 7607).  2.  Name of system handler must be SYS.  3.  Each  handler  entry  point  has an  8-word  handler   block      associated with it.  The following additions apply:       a.  word 5:  bits 9-11 should normally be 0.   If the device can have  multiple  platters  (like  RF08)   then this  field  specifies maximum number of platters   allowed.  Each platter above first  bumps  internal DCB   code by 1.   word 6:  bit 0=1 means system device is two pages  long.   The second page  is  origined  into 400 but resides in   field 2 location 7600. Bit 1=1 if entry  point  is  SYS.   Bit 2=1 if entry point is coresident with SYS.   word 7:  must be 0   word 10: number  of blocks in  device. Immediately   following  the  header  records  is the  code  for the   device's bootstrap. This  is  preceded  by minus the   number of words in the bootstrap.  No origins may appear   in this code.   It must be less than 47 locations long.      5-6   APPENDIX A      OS/8 FILE STRUCTURES     A.1  FILE DIRECTORIES     Blocks 1 through 6 on all file structured devices are reserved for the     file  directory  of  that device.  Six  blocks are always allocated,     though all are not necessarily active at any given time.  To  minimize     the  number  of  directory reads and writes necessary, OS/8 fills one     directory block completely before overflowing  onto  a  second  block.     Thus  the user with only a few files can perform directory LOOKUPs and     ENTERs faster than one with many files.     The directory blocks are each structured according to  the  following     format:      ENTRY  +--------------------------------+       0  | MINUS THE NUMBER OF ENTRIES   |  | IN THIS SEGMENT   |  +--------------------------------+       1  | THE STARTING BLOCK NUMBER   |  | OF THE FIRST FILE IN THIS   |  | SEGMENT   |  +--------------------------------+       2  | LINK TO NEXT SEGMENT-ZERO   |  | IF NO NEXT SEGMENT   |  +--------------------------------+       3  | FLAG WORD-POINTS TO LAST WORD  |  | OF TENTATIVE FILE ENTRY IN   |  | THIS SEGMENT   |  | DIRECTORY SEGMENTS ARE ALWAYS  |  | LOADED INTO LOCATIONS 11400   |  | TO 117777 BY THE USR; THIS   |  | POINTER IS EITHER 0 OR BETWEEN |  | 1400 TO 1777.   |  +--------------------------------+       4  | MINUS THE NUMBER OF   |  | ADDITIONAL INFORMATION WORDS.  |  | THE NUMBER OF ADDITIONAL   |  | INFORMATION WORDS SPECIFIED   |  | MUST BE THE SAME IN ALL   |  | DIRECTORY SEGMENTS   |  +--------------------------------+       5  | BEGINNING OF FILE ENTRIES   |  +--------------------------------+       .  |   |       .  ~   ~       .  |   |  +--------------------------------+       377| END OF DIRECTORY BLOCK   |       (8)+--------------------------------+      A-1      OS/8 FILE STRUCTURES     Locations 0 through 4 of each directory block are called  the  segment     header.     A.1.1  Directory Entries     There are three types of file directory entries.  They  are  PERMANENT     FILE  ENTRY,  EMPTY FILE ENTRY, and TENTATIVE FILE ENTRY. A permanent     file entry appears as follows:   Location  Contents      Notes +-------------------------------+       0 | FILE NAME  FILE NAME |\ | CHARACTER 1  CHARACTER 2 | | +-------------------------------+ |       1 | FILE NAME  FILE NAME | | | CHARACTER 3  CHARACTER 4 | |  THE FILE NAME AND EXTENSION +-------------------------------+  > ARE PACKED IN SIXBIT ASCII       2 | FILE NAME  FILE NAME | |  (i.e., "A" would be 01) | CHARACTER 5  CHARACTER 6 | | +-------------------------------+ |       3 | FILE EXTENSION FILE EXTENSION | | | CHARACTER 1  CHARACTER 2 |/ +-------------------------------+ | |\ | | |  N, THE NUMBER OF ADDITIONAL +-------------------------------+ |  INFORMATION WORDS, IS GIVEN | ADDITIONAL | |  BY WORD 4 OF THE DIRECTORY ~ INFORMATION ~  > HEADER.  WORD 4 OF THE ENTRY | WORDS | |  IS EITHER 0 OR THE CREATION +-------------------------------+ |  DATE OF THE FILE. | | |     N+3 | |/ +-------------------------------+ | |     N+4 | MINUS FILE LENGTH IN BLOCKS | +-------------------------------+      NOTE    If word 3 is zero, the given file has  a    null extension.     An empty file entry appears as follows:     Location   Contents   +-----------------------------+ 0 | ENTRY IS ALWAYS 0000 |   +-----------------------------+ 1 | MINUS THE NUMBER OF BLOCKS |   | IN THIS EMPTY FILE |   +-----------------------------+      A-2      OS/8 FILE STRUCTURES     A tentative file entry appears as a permanent file entry with a length     of zero. It  is always immediately followed by an empty file entry.     When the tentative file is entered in a directory, location 3  in the     segment  header  becomes  a pointer to this entry. The CLOSE function     inserts the length word of the  tentative file  entry,  making  it  a     permanent file,  and  adjusts  the length of the following empty file     entry (deleting that entry if the length becomes zero).     Whether or not there is  a tentative  file  open on  any device is     determined by examination of bits 9 to 11 of the system Device Control     Word Table (see section B.3.5) not the contents of location 3  in the     segment  header. Zeroing these bits in the Device Control Word Table     makes the active tentative file on the device inactive.  The next time     that  the system has  to write the directory segment, the inactive     tentative file entry is removed.  The distinction between active and     inactive  tentative  files is made so that OS/8 can avoid spending the     time required to perform  an  extra  read and  write  of the  device     directory.     A.1.2  Number and Size of OS/8 Files     All files on an OS/8 device must occupy a contiguous group of  blocks     on the  device.  The length of any file is indicated in its directory     entry, and the starting  block  of the  file  is deduced by  adding     together  word  1 of  the segment header and the lengths of all files     whose entries precede it in the directory segment.     Each directory segment must have enough unused words  at  the  end to     accommodate  a  permanent file entry (N+5 words, where N is the number     of Additional  Information Words).  Thus, if  N is  the number of     Additional Information  Words  the  maximum  number of permanent file     entries in any one segment is:      256-7 - (N+5)  244-N       MIN = [-------------] = [-----]   N+7   N+7     with N=1, MAX=40, and MIN=30.  Since there are  six  segments  in the     directory, the  maximum  number of files possible (with N=1) would be     240.     Finally, OS/8 devices are limited to 4095 blocks, each block being 256     words long.  Thus, the maximum size of any single OS/8 file structured     device is 1,048,320 words. Blocks 0  through  6  of  the device are     unavailable for file storage;  therefore, the largest possible file is     4088 blocks long, or 1,046,528 words.     A.1.3  Sample Directory     The initial directory written when the OS/8 system is built  looks as     follows:      A-3      OS/8 FILE STRUCTURES Location       Contents   Notes     +----------+ / 0  |   7776   | TWO ENTRIES | 1  |   0070   | FILE STORAGE STARTS AT BLOCK 70(8)*        HEADER <  2  |   0000   | NO ADDITIONAL DIRECTORY SEGMENTS | 3  |   0000   | NO TENTATIVE FILES. \ 4  |   7777   | ONE ADDITIONAL INFORMATION WORD     +----------+       /  5  |   0102   |  \       |  6  |   2314   |   >  FILE NAME IS "ABSLDR"     PERMANENT /  7  |   0422   |  / FILE  \ 10  |   2326   | FILE EXTENSION IS SV ENTRY  | 11  |   5370   | DATE IS 10/31/70       \ 12  |   7773   | LENGTH IS FIVE BLOCKS     +----------+ EMPTY  / 13  |   0000   | EMPTY FILE FILE <      | |        ENTRY  \ 14  |   6534   | LENGTH IS 1244(8) (676(10))BLOCKS -     +----------+ THIS IS DEPENDENT ON THE SYSTEM     | | DEVICE USED.  676 IS THE VALUE     ~ ~ FOR A DECTAPE SYSTEM     | |      377(8) +----------+ *This leaves room for the OS/8 System Areas     A.2  FILE FORMATS     There are three different standard file  formats used  by  OS/8 and     associated system programs:  1. ASCII and Binary files.  2,  Core Image files (.SV format).  3.  Relocatable  FORTRAN  library  files  (LIB8.RL  is  the  only      current example of this format).      NOTE    Binary files can contain either absolute    binary  data (i.e., output from PAL8) or    relocatable binary data  (i.e.,  output    from SABR).     A.2.1  ASCII and Binary Files     ASCII and Binary files are packed three characters into two words, as     follows:      A-4      OS/8 FILE STRUCTURES +---------------+------------------------+       WORD 1 |  CHARACTER 3 | CHARACTER 1 | |   BITS 0-3 | | +---------------+------------------------+       WORD 2 |  CHARACTER 3 | CHARACTER 2 | |   BITS 4-7 | | +---------------+------------------------+ 0       3 4       11     The following conventions are used by OS/8 system programs:  1.  In ASCII files the  character  NULL  (ASCII  000) is  always      ignored. Most programs only examine the low-order 7 bits, in      ASCII files.  The parity bit  is usually ignored;   do not      assume  that  this  bit  is  set or that data transfers will      preserve it (image mode transfers, always preserve it).  2.  In Binary files the binary data must be preceded by  one or      more  frames  of leader/trailer code  (ASCII 200 code). The      first character of binary data must  be  either  100  to 177      (octal) (an origin setting for absolute binary files), 240 to      257 (octal)  (a  COMMON  declaration  frame  for relocatable      binary  files),  or  300 (octal), which is an origin setting.      The end of binary data is indicated by one or more frames of      leader/trailer code.  3.  ASCII and Binary files are terminated by a CTRL/Z code (ASCII      232).  In binary files, a  CTRL/Z  code  data rather than      end-of-file.     A.2.2  Core Image (.SV Format) Files     A core image file consists of a header by the actual core image. The     header block is called the Core Control Block.  The Core Control Block     consists of the first 128 words of the 256 word  block  reserved for     that  purpose.   The  second  128 words are unused.  The Core Control     Block is formatted as follows:      A-5      OS/8 FILE STRUCTURES      Location       Contents   Notes     CORE CONTROL BLOCK     +------------------------------------+   0 | MINUS THE NUMBER OF CORE SEGMENTS |     +------------------------------------+   62N3 WHERE N IS THE   1 | CDF CIF (STARTING FIELD)  |<--STARTING FIELD     +------------------------------------+   2 | STARTING ADDRESS  |     +------------------------------------+   3 | JOB STATUS WORD  |     +------------------------------------+   4 |  |\  CORE SEGMENT     +------------------------------------+ | CONTROL DOUBLE WORDS     ~  ~  >     +------------------------------------+ | (K IS THE NUMBER OF       2K +3 |  |/  CORE SEGMENTS)     +------------------------------------+      377(8) ~  ~   REMAINDER OF BLOCK     +------------------------------------+   IS UNUSED     The format of the Job Status Word is as follows:     Bit Condition Meaning     _____________ _______  Bit 0 = 1      File does not load into locations 0  to  1777      in field 0.  Bit 1 = 1      File does not load into locations 0  to  1777      in field 1.  Bit 2 = 1      Program must be reloaded before it  can be      restarted.  Bit 3 = 1      Program never uses above 8K.  This  is  used      when Batch processing is active.  Bit 10 = 1      Locations 0 to 1777 in field 0  need  not be      preserved when the Command Decoder is called.  Bit 11 = 1      Locations 0 to 1777 in field 1  need  not be      preserved when the USR is called.      A-6      OS/8 FILE STRUCTURES     The Core Segment Doublewords control the reading and  writing  of the     associated areas of core. The format of each entry is as follows:     Location      Contents     Notes  +---------------------------------------------+ 1 |      CORE ORIGIN | MULTIPLE OF 400(8)  +---+------------------+-----------+----------+ 2 |   |NUMBER OF PAGES |   FIELD   | | BITS 0 AND 9-11  |   |  TO LOAD |  TO LOAD  | | ARE ZERO  +---+------------------+-----------+----------+   0   1 5 6    8 9      11     The core origin must be a multiple of 400 (octal). The  Core  Segment     Control  Doublewords  are sorted within the header block in order of     decreasing field and increasing origin within the same  field.   There     can  be  no more than 32 (decimal) Core Segment Control Doublewords in     any Core Control Block.     The Core Control Block for the program at the time it is  loaded  into     core is always saved in words 200 (octal) through 377 (octal) of block     37 (octal) (one of the system scratch blocks) on the  system  device.     It is  placed there by the GET and RUN operations or by the ABSLDR or     LOADER programs.  This Core Control Block is used when  performing  a     SAVE without arguments.      NOTE    The R  command  differs  from  the RUN    command   in  that the  program's Core    Control Block is not  written  onto the    scratch  area  when using the R command.    In order to SAVE a program that has been    loaded  by the  R command all  of the    arguments of the SAVE  command  must  be    explicitly stated.      A-7      OS/8 FILE STRUCTURES     A.2.3  Relocatable FORTRAN Library File     A relocatable FORTRAN library consists of a  library  directory  block     followed  by relocatable binary segments. The directory block has the     following format:  Location    Contents      Notes  ________    ________      _____  +--------------+---------------+      0  |   CH1 |    CH2 |\  +--------------+---------------+ |  NAME OF ENTRY IN      1  |   CH3 |    CH4 |  > SIXBIT ASCII PADDED  +--------------+---------------+ |  WITH TRAILING BLANKS      2  |   CH5 |    CH6 |/  +--------------+---------------+      3 +-| LOAD POINTER | | | +--------------+---------------+      4 | | ADDITIONAL ENTRIES | | ~  . ~      5 | |  . | | +------------------------------+ | |  0 |\ | +------------------------------+ | | |  0 | | | +------------------------------+  > DENOTES END OF | |  0 | |  NAME ENTRIES | +------------------------------+ | | |  0 |/ | +------------------------------+       /  ~ ~      |  +------------------------------+       \->| |-> LOADER CONTROL WORD(S)  +------------------------------+  |  0 |-> END OF LOADER CONTROL  +------------------------------+   WORDS FOR THIS ENTRY  ~ ~  +------------------------------+ 377(8)  | |  +------------------------------+     The Load Pointer is a number between 0 and 377  (octal)  which  points     (relative to the beginning of the block) to an array of Loader Control     Words.  The Loader Control Words have the following information:  +--------------+--------------------+  | |      |  +--------------+--------------------+   0 4 5    11   NUMBER OF PAGES OCCUPIED      (STARTING BLOCK OF RELO-   BY THIS SEGMENT AFTER LOADING       CATABLE BINARY DATA)       (DIRECTORY BLOCK #)-1      A-8      OS/8 FILE STRUCTURES     There can be one or more Loader Control Words  for each  entry. The     Loader  Control  Words  for an entry are terminated by a word of zero.     The following is a simple directory block.      Location       Contents      +---------------+  0   | 1117 |  NAME OF ENTRY IS "IOH___"      +---------------+  1   | 1040 |      +---------------+  2   | 4040 |      +---------------+  3   | 0376 |  LOAD POINTER FOR "IOH"      +---------------+  4   | 0530 |      +---------------+  5   | 1124 |  NAME OF ENTRY IS "EXIT__"      +---------------+  6   | 4040 |      +---------------+  7   | 0373 |  LOAD POINTER FOR "EXIT"      +---------------+ 10   | 0000 |      +---------------+ 11   | 0000 |  MARKS END OF ENTRIES      +---------------+ 12   | 0000 |      +---------------+ 13   | 0000 |      +---------------+      ~      ~      +---------------+      LOADER 373   | 0207 |  (RELATIVE BLOCK 10(8))(ONE      CONTROL      +---------------+  PAGE LONG)      WORDS FOR 374   | 0411 |  (RELATIVE BLOCK 12(8))(TWO      "EXIT"      +---------------+  PAGES LONG) 375   | 0000 |      +---------------+      LOADER 376   | 2400 |  (RELATIVE BLOCK 1)(12(8) PAGES      CONTROL      +---------------+  LONG)      WORDS FOR 377   | 0000 |      "IOH"      +---------------+      A-9   APPENDIX B DETAILED LAYOUT OF THE SYSTEM     This appendix covers three topics: the reserved areas on the  system     device, the resident portion of OS/8, and the various system tables.     B.1  LAYOUT OF THE SYSTEM DEVICE     The first 70 octal blocks (14K  words)  on  the system device are     reserved by the OS/8 system.  These blocks are used as follows:     Block(s) in Octal      Contents     _________________      ________  0      System Bootstrap Routine  1-6      Device Directory  7-12      Keyboard Monitor  13-15      User Service Routine  16-25      Device Handlers  26      ENTER Processor for USR  27-50      System Scratch Blocks  51-53      Command Decoder  54-55      SAVE and DATE Overlays  56      Monitor Error Routine  57      CHAIN Processor for USR  60-63      SYSTEM ODT  64      Reserved for System Expansion  65      CCL Reminiscences  66      12K TD8E Resident code  67      CCL Overlay     File storage begins with block 70 (octal).     The system scratch blocks are used for preserving the contents of core     when  the Keyboard  Monitor, USR, Command Decoder, or ODT are loaded.     In addition, various system  programs  use the  scratch  area.   Most     importantly,  the SAVE  command  expects the Core Control Block to be     loaded in words 200 (octal) to 377 (octal) of block  37  (octal). The     Core  Control  Block  is  stored  at those locations by the GET or RUN     command or by the ABSLDR or LOADER program.      B-1 DETAILED LAYOUT OF THE SYSTEM     A detailed breakdown of system scratch block usage follows:       Block(s) in Octal Contents       _________________ ________  27-32      The contents of locations 10000 to 11777 are      saved in this area when the USR is loaded.  33-36      The contents of locations 0 to 1777 are saved      in   this area  when  the  Command  Decoder,      Keyboard Monitor, or ODT is loaded.  37      Words 200 (octal) to  377  (octal)  of  this      block  contain the Core Control Block for the      last  program  loaded  by the  GET  or RUN      command, or the ABSLDR or LOADER program.  40-47      Used as scratch storage  by  the ABSLDR and      LOADER programs. 50      Reserved for future expansion.      B-2 DETAILED LAYOUT OF THE SYSTEM     B.2 LAYOUT OF THE OS/8 RESIDENT PROGRAM     The top core pages in fields 0, 1, and 2  are  used  by  the  resident     portion  of  OS/8 and  are  not accessible by the user.  As a general     rule, system and user programs should never destroy  the  contents of     locations 7600 to 7777 of any field.     The resident portion of OS/8 is structured as follows:  Location Contents     Notes  ________ ________     _____   +-------------------------+     7600  | WRITE OPERATION     |<- NON-DESTRUCTIVE   +-------------------------+ ENTRY TO OS/8     7605  | JMP TO FIELD 1 FOR READ |<- DESTRUCTIVE   +-------------------------+ ENTRY TO OS/8     7607  |     |<- ENTRY TO SYSTEM   ~ SYSTEM DEVICE HANDLER   ~ DEVICE HANDLER     7743  |     |   +-------------------------+     7744  |     |     7745  | CURRENT STARTING ADDRESS|   +-------------------------+     7746  | JOB STATUS WORD     |   +-------------------------+     7747  | 0     |<- MUST ALWAYS BE ZERO   +-------------------------+     7750  |     |   | RESERVED FOR DATA BREAK |   | LOCATIONS     |     7755  |     |   +-------------------------+     7756  |     |<- THE KEYBOARD MONITOR   ~ PROGRAM SETUP AREA     ~ AND ODT MODIFY THIS     7777  |     | AREA   +-------------------------+      B-3 DETAILED LAYOUT OF THE SYSTEM      TOP PAGE OF FIELD 1     Location Contents     Notes     +--------------------------------+     \     7600    ~    OUTPUT FILE LIST (3 ENTRIES)~      |     7616    +--------------------------------+      |     7617    ~    INPUT FILE LIST      ~   0 MARKS END |     |    (MAXIMUM 9 ENTRIES)    <---  OF LIST     | COMMAND     7641    +--------------------------------+       >DECODER     7642    |    *  HIGH 11 BITS OF =N      |<- * BIT 0=1   | AREA     +--------------------------------+   IF COMMAND  |     7643    |    SPECIFIED OPTIONS      |   LINE TERMI- |     7645    +--------------------------------+   NATED BY    |     7646    |    LOW 12 BITS OF =N      |   ALTMODE     |     +--------------------------------+      |     7647    |    DEVICE HANDLER      |     /     7665    ~    RESIDENCY TABLE      ~     +--------------------------------+     7666    |    SYSTEM DATE WORD      |     +--------------------------------+     7667    ~    READ OPERATION      ~     7677    |    (LOAD KEYBOARD MONITOR)     |     +--------------------------------+     7700    ~    USR CALL AND RETURN AREA    ~<- ENTRY TO USR     7740    +--------------------------------+      NOTE      ____     7741    ~    USER DEVICE      ~   SYSTEM ODT DESTROYS     7757    |    NAME TABLE      |   CONTENTS OF THIS TABLE     +--------------------------------+   WHEN SETTING BREAKPOINTS     7760    ~    DEVICE CONTROL WORD TABLE   ~     7776    +--------------------------------+     7777    |    UNUSED      |   RESERVED FOR FUTURE USE     +--------------------------------+     Systems built around TD8E DECtape without the Read-Only-Memory  option     use 7600 in field 2 as an extension of the system device handler.      TOP PAGE OF FIELD 2.       7600   +------------------+      | |      | |   Used   only   for 12K   TD8E      | |   systems. Part of   system      | |   handler resides here  in  that      | |   case.       7773   |__________________|       7774   | |      | |   Four words reserved for  BATCH      | |   use  if  machine  has  exactly      | |   12K.  Contains  pointers  into      | |   input file.      | |       7777   +------------------+      B-4 DETAILED LAYOUT OF THE SYSTEM     If the machine has more than 12K, the top 4 locations  (7774-7777) of     the last field are reserved for use by BATCH.     If a ROM (Read-Only-Memory) is being used with  an  8K  TD8E  system,     locations 7400-7777 of  field  7 are inaccessible to the user.  That     core is used for system handler functions.     B.3 SYSTEM DEVICE TABLES     Each device is described to the  system  by  entries  in  five  system     tables.   Each of these tables is fifteen words long, where the device     number is the index into the table.  The  five  tables  are  described     below.     B.3.1 Permanent Device Name Table     Entries in this table specify the permanent name of each device. The     entries are computed by encoding the actual four-character device name     in a single word as follows:  1.  The device name is expressed as two  words  in  the  standard      DEVICE  format. For  example, if the device name were "PTR"      the two words would be:   WORD 1: 2024   WORD 2: 2200      Note that when the device name is left  justified;   0's are      inserted to fill four characters.  2.  A single word is created by adding together these two words.  3.  If word 2 is non-zero, bit 0 of the resulting word is  forced      to be a one.  For example, the table entry for "PTR" would be      4224.     An entry of zero means that there is no device for the  corresponding     device number.      NOTE    Conventionally,  device  names   consist    only  of  the characters A to Z and 0 to    9. The first character  of the  device    name  should  be alphabetic.  The coding    used makes all  one and  two  character    device  names unique;  however, names of    more than two characters are not unique.    For example,  "PTR"  and "RTP" have the    same encoding.      B-5 DETAILED LAYOUT OF THE SYSTEM     The Permanent Device Name table is fifteen locations long; it resides     in the USR.  When the USR is in core the beginning of the table is in     field 1 at a location the address of which is  contained  in  location     10036.     B.3.2 User Device Name Table     Entries are made in this table whenever the user  performs an  ASSIGN     and  are  restored to zero by a DEASSIGN. These entries have the same     format as those in the Permanent Device Name Table.     The User Device Name Table resides in locations 17741 through 17757.     B.3.3  Device Handler Residency Table     When a device handler is loaded by the USR, the entry  in this  table     for  the device loaded (and entries for all devices whose handlers are     co-resident, if any) is set to contain the entry point for the  device     handler. Entries other than those that contain an address above 7600     (thus referring to the system handler) are restored to 0 when a RESET,     DECODE  or CHAIN function  is executed. When a program exits to the     Keyboard Monitor this table is  not  cleared.   The  Keyboard  Monitor     Commands GET, RUN, R, SAVE, and START (with no explicit address) clear     this table.      NOTE    Since  the system device handler  is    always  resident the first entry (SYS is    always device number 1)  in the  Device    Handler  Residency Table is always 7607    (the entry point of the  system  device    handler).     The Device Handler Residency Table resides in locations 17647  through     17665.     B.3.4  Device Handler Information Table     Each entry in this table contains all the information  needed  by the     USR to load the corresponding handler.  The format of these entries is     as follows:      B-6 DETAILED LAYOUT OF THE SYSTEM  Bit Condition  Meaning  _____________  _______  Bits 0 = 1   If this is a two page device handler.  Bits 1 to 4   Contain the relative block  location of   the device handler record on the system   device.  This is computed by subtracting   15  (octal) (one  less  than  the first   device handler block)  from the  actual   block number.  Bits 5 to 11   Contain the offset of the handler  entry   point  from the  beginning of the page.   Note that  the  entry  points  to all   handlers must be in the first page.     If an entry is 0 the corresponding device handler is not saved in any     of the  device handler storage blocks.  This is always true of device     number 1 (the system device) and for all device numbers that  are not     used  in  a given configuration.  The Device Handler Information Table     is 15 locations long and resides in the USR.  When the USR is in  core     the  beginning of the table is in field 1 at a location the address of     which is contained in location 10037.     B.3.5 Device Control Word Table     Entries  in  this table  specify special  device   characteristics,     including the physical device type.  The entry format is as follows:  Bit Condition  Meaning  _____________  _______  Bit 0 = 1   If the device is file-structured.  Bit 1 = 1   If the device is read-only.  Bit 2 = 1   If the device is write-only.  Bits 3 to 8   Contain the physical device type  code   (described below),  Bits 9 to 11   For file structured devices, these  bits   contain  the directory  block number of   the currently active tentative file. If   bits 9  to 11  are zero, there is no   active tentative  file  on  the  device.   For non-file structured devices, bits 9   to 11 are always zero.  Bits 9 to 11 are   reset  to zero by the commands GET, RUN,   R,  SAVE,  START   (with   no   explicit   address)  and  optionally   by  the USR   functions RESET and DECODE.      B-7 DETAILED LAYOUT OF THE SYSTEM     The device type is a number between 0  and 77  (octal),  of  which  0     through  20  (octal)  are currently  assigned to existing devices, as     follows:       Device Code Device       ___________ ______    0      Teletype    1      High-speed paper tape reader    2      High-speed paper tape punch    3      Card Reader    4      Line Printer    5      RK8 Disk    6      256K Disk (RF08)    7      512K Disk (RF08 + RS08)    10      768K Disk (RF08 + 2 RS08's)    11      1024K disk (RF08 + 3 RS08's)    12      32K Disk (DF32)    13      64K Disk (DF32 + DS32)    14      96K Disk (DF32 + 2 DS32's)    15      128K Disk (DF32 + 3 DS32's)    16      DECtape    17      LINCtape (PDP-12 only)    20      TM8E Magnetic Tape    21      TD8E DECtape    22      BATCH handler    23      RK8E Disk    24      NULL    25-26     reserved for future disks    27      TA8E Cassette    30      VR12 Scope    31-37     reserved for future use by DEC    40-57     reserved for use by users     The Device Control Word  Table  resides  in  locations  17760  through     17776.     B.3.6  Device Length Table     There is a sixth table that is not normally  considered  part  of the     system  tables.   This  is the Device Length Table and is used only by     PIP to perform the /Z  (zero  directory) and  /S (compress  device)     options.  This table is 64 locations long, one entry for each possible     device type.  In this table an entry of 0 means that the corresponding     device  is non-file  structured; otherwise  the entry contains the     negative of the number of available 256-word blocks on the device.     For example, the entry for a 256K disk would be  6000  (octal)  (minus     2000 (octal), or 1024 (decimal), 256-word blocks).      B-8 DETAILED LAYOUT OF THE SYSTEM     The Device Length Table resides in PIP.  When PIP is brought into core     the  Device  Length  Table is  in locations 13600 to 13677. When new     device types are added to the system this table should be patched with     ODT to reflect the device length of the new device.     A similar table occurs in RESORC which the user may wish to patch. It     is located  in  field 0 locations 2000-2377 and contains 64 four-word     entries;  one entry for each device type. Words 1 and 2 of  an  entry     are  the names of the device (in sixbit) and word 3 is the negative of     the number.  Word 4 of the entry should be 0 for non-standard devices.      B-9   APPENDIX C     SYSTEM ERROR CONDITIONS AND MESSAGES     This is a summary of all error messages that are a result of  system     errors.   These  errors are also described in the relevant sections of     this manual and in the OS/8 HANDBOOK.     C.1  SYSTEM HALTS     Errors that occur as a result of a major I/O  failure  on the  system     device can cause a system halt to occur.  These are as follows: Value of PC     Meaning ___________     _______  00601      A read error  occurred  while  attempting to      load  ODT.  Return to the Keyboard Monitor by      restarting at 07605.  07461      An error occurred while reading a  program      into  core  during  a  CHAIN.   Return to the      Keyboard Monitor by restarting at 07605.  07605      An error occurred while attempting  to  write      the  Keyboard  Monitor  area  onto the system      scratch  blocks. Verify that  the   system      device  is  not  WRITE  LOCKed and restart at      location 07600 to try again.  07702      A user program has performed a JMS to 7700 in      field  0. This is a result of trying to call      the USR without first performing a CIF 10. As      location 07700  has been destroyed, the user      must re-bootstrap the system.  07764      A read  error  occurred while loading  a      program. Return to the Keyboard Monitor by      restarting at 07605.  07772      A read error occurred on the  system  scratch      area  while loading a program.  Return to the      Keyboard Monitor by restarting at 07605.  10066      An input error occurred while  attempting to      restore  the  USR.   Return  to  the Keyboard      Monitor by restarting at 07605.  10256      A read error  occurred  while  attempting to      load the Monitor by restarting at 07605.      C-1     SYSTEM ERROR CONDITIONS AND MESSAGES  17676      An error occurred while  attempting  to  read      the  Keyboard Monitor from the system device.      Try again by restarting at location 07605. DO      NOT PRESS CONTINUE.  17721      An error occurred while saving the USR  area.      Verify  that  the system device is not WRITE      LOCKed, and press CONTINUE to try again.  17727      An error occurred while  attempting  to  read      the  USR from  the system device.  Return to      the Keyboard Monitor by restarting at 07605.  17736      An error occurred while reading  the  scratch      blocks  to  restore  the USR area.  Return to      the Keyboard Monitor by restarting at 07605.     Also, there is one halt in the LOADER program:  00005      A parity error occurred  when  attempting to      overlay  the  LOADER  from the system scratch      blocks.  Return to the  Keyboard Monitor by      restarting at 07605, and try again.     After retrying the operation which caused the failure,  if the  error     persists, it is the result of a hardware malfunction or a parity error     in the system area.  Run the appropriate diagnostic program  to  check     the device and rebuild the system.     C.2  USR ERRORS     Fatal errors that occur during operation of the USR cause the message:       MONITOR ERROR n AT xxxxx     to be printed.  In these cases, the value "n" describes the error and     "xxxxx"  is  the address of the call to the USR that caused the error.     The six Monitor errors are:       Message  Meaning       _______  _______  MONITOR ERROR 1 AT xxxxx File length in CLOSE  function is  [CLOSE ERROR] too large.  MONITOR ERROR 2 AT xxxxx An I/O error  occurred while at-  [DIRECTORY I/O ERROR] tempting  to  read   or  write  a directory block.  This is generally caused by the  device  being  WRITE LOCKed.  MONITOR ERROR 3 AT xxxxx The  device  handler required for a  [DEVICE HANDLER NOT IN CORE] file  operation  (LOOKUP,   ENTER, CLOSE) is not in core.      C-2     SYSTEM ERROR CONDITIONS AND MESSAGES  MONITOR ERROR 4 AT xxxxx Illegal call to the USR;  either an  [ILLEGAL USR CALL] attempt has  been made to call the USR from locations 10000  to  11777 or  a  device  number  of  zero was specified.  MONITOR ERROR 5 AT xxxxx I/O error occurred while reading or  [I/O ERROR ON SYS] writing on  the   system   device. Verify that  the  system device is not WRITE LOCKed.  MONITOR ERROR 6 AT xxxxx Directory  overflow  occurred  (see  [DIRECTORY OVERFLOW] section A.1.2  for  limitations on number of directory entries).     In addition to the MONITOR ERROR messages, system and  user  programs     can use the USR to print:       USER ERROR n AT xxxxx     by using the ERROR function.   In this  case  the value of  "n" is     user-defined and "xxxxx" is the address of the call to the USR.     Currently, two USER ERROR numbers have been assigned:       Message  Meaning       _______  _______  USER ERROR 0 AT xxxxx An   I/O   error   occurred   while attempting  to load a program with the GET, RUN, or R command.  USER ERROR 1 AT xxxxx While running  a  FORTRAN  or  SABR program,  an  attempt  was  made to call a subroutine that had not been loaded.     If an I/O error is made during the monitor CHAIN function the message       CHAIN ERR     is generated, and control returns to the keyboard.     Following either a MONITOR ERROR message or a USER ERROR  message the     USR  exits to the keyboard Monitor;  the current contents of core are     preserved and bit 2 of the Job Status Word is set to a  1 to  prevent     continuing from the error.     C.3  KEYBOARD MONITOR ERRORS     In addition to the USR  errors  described previously,  the  following     errors can occur after a command is given to the Keyboard Monitor:      C-3     SYSTEM ERROR CONDITIONS AND MESSAGES  Message  Meaning  _______  _______  aaaa?   The Keyboard Monitor  cannot  interpret   the command "aaaa". For example if the   user types HELLO the system will respond   HELLO?  BAD ARGS   Arguments  to   a   SAVE   command are   inconsistent, or illegal.  BAD CORE IMAGE   The file requested with an  R,  RUN, or   GET command is not a core image file.  BAD DATE   Improper syntax in a DATE command.  device NOT AVAILABLE   The permanent device name  specified in   an  ASSIGN, SAVE,  RUN,  or GET command   does not exist.  ILLEGAL ARG   The SAVE  command  was  not  expressed   correctly.  name NOT FOUND   The file name specified was not  located   on the device indicated.  This error can   also be caused by trying to RUN  or GET   from an output only device.  NO!!   A  START  command   (with   no   address   specified)  is  prohibited when bit 2 of   the Job Status Word (location 07746) is   a 1.  NO CCL!   Command was a  valid  CCL  command but   CCL.SV is not on the system.  SAVE ERROR   An I/O error occurred while saving the   program.   The  contents  of core remain   intact.  SYSTEM ERR   An error occurred while doing I/O to the   system device.  TOO FEW ARGS   An argument has  been  omitted  from  a   command.     C.4  CCL ERROR MESSAGES  Message  Meaning  _______  _______  BAD DEVICE   The device specified in a CCL command is   not of   the   correct   form,  (e.g.,   DTA0.PA:).      C-4     SYSTEM ERROR CONDITIONS AND MESSAGES  BAD EXTENSION   Either  an extension   was  specified   without  a file name (e.g., DTA1:.PA) or   two extensions  were  specified  (e.g.,   DTA1:FILE.PA.BN).  BAD MONITOR   The version of  the  Keyboard  Monitor   being  used is not compatible with CCL.   A new version of  the  monitor  must be   obtained  from Digital before CCL can be   used.  BAD NUMBER   A  CCL  command   which   uses   the  #   construction does  not  have  the  full   16-digit specification that is required.  BAD RECOLLECTION   An attempt was made to use a previously   remembered argument when no argument was   saved.   This  error occurs  when no   argument  was  previously  saved or when   the DATE command has been used since the   argument was saved.  BAD SWITCH OPTION   The character used with a slash  (/) to   indicate   an  option  is  not  a  legal   option.  CANNOT CHANGE CORE   A CORE  command  was issued while the  CAPACITY WHILE RUNNING   BATCH program was running.  BATCH  %CANT REMEMBER   The argument specified in a CCL  command   line is too long to be remembered or an   I/O error occurred.  CCL 3X OVERLAY &   The version of  CCL  being used is not  MONITOR INCOMPATIBLE   compatible  with  the  Keyboard  Monitor   present  on the  system.  Type R CCL to   retry.  COMMAND LINE OVERFLOW   The command line specified  with  the  @   construction is more than 512 characters   in length.  COMMAND TOO LONG   The length of a text argument in a  MUNG   command is too long.  CONTRADICTORY SWITCHES   Either two CCL processor  switches  were   specified   in  the same  command  line   (e.g., FILE-PA-FT) or the file extension   and the  processor switch do not agree   (e.g., FILE.FT-BA).  name DOES NOT EXIST   The device with the name  given  is not   present on the OS/8 system.      C-5     SYSTEM ERROR CONDITIONS AND MESSAGES  ERROR IN COMMAND   A command not entered directly from the   console  terminal  is  not  a  legal CCL   command.  This  error  occurs  when the   argument  of a UA, UB, or UC command was   not a legal command.  ILLEGAL * OR ?   An * or ? was used in a CCL command that   does   not accept  the wild   card   construction.  Only CCL  commands  that   run FOTP  or DIRECT allow the wild card   construction.  ILLEGAL SYNTAX   The CCL  command  line  was  formatted   incorrectly.  INPUT ERROR READING   CCL cannot read the file specified  with  INDIRECT FILE   the @ construction.  I/O ERROR ON SYS:   An error occurred while doing I/O to the   system  device.   The  system  must be   restarted   at   7600   or 7605. Do   not press  CONT.  as that  will  surely   cause further errors.  I/O ERROR TRYING TO   An I/O  error  occurred  while  CCL was  RECALL   trying to remember an argument.  NO CCL!   CCL.SV is  not  present  on the  system   device.  NOT ENOUGH CORE   The number specified in a  CORE  command   is  larger  than  the  number of 4K core   banks on the system.  name NOT FOUND   The file with  the  name  given  is not   present  on the specified device, or the   user tried to input from an output-only   device.  %SUPERCEDED   The file specified  in  a  MAKE  command   already   exists.   This  is a  warning   message  indicating that  the  file is   being replaced.  SWITCH NOT ALLOWED HERE  Either a CCL option was specified on the   left side of the < or was used when not   allowed.  For example:  COMPARE FILE-NB.  TOO MANY FILES   Too many files were included in  a CCL   command.      C-6     SYSTEM ERROR CONDITIONS AND MESSAGES     C.5  COMMAND DECODER ERRORS     The following errors are printed by the Command  Decoder. After the     error  message,  the Command Decoder starts a new line, prints a * and     waits for another command line.  The erroneous command is ignored.       Message  Meaning  ILLEGAL SYNTAX   The command    line    is  formatted   incorrectly.  TOO MANY FILES   More than three  output  files  or  nine   input   files  were specified  (regular   mode)  or  > 1  output  or >  5  input   (special mode).  name NOT FOUND   The specified input file  name  was not   found on the device indicated.      C-7   APPENDIX D       PROGRAMMING NOTES     This appendix is a potpourri of ideas and techniques that have  proven     useful in programming the PDP-8. OS/8 users may find some use in their     own programs for the techniques mentioned here.  D.1  The Default File Storage Device, DSK  D.2  Modification to Card Reader Handler  D.3  Suppression of Carriage Return/Line Feed in FORTRAN I/O  D.4  Accessing the System Date in a FORTRAN Program  D.5  Determining Core Size on PDP-8 Family Computers  D.6  Using PRTC12-F to Convert OS/8 DECtapes to OS/12 LINCtapes  D.7  Notes on Loading Device Handlers  D.8  Available Locations in the USR Area  D.9  Accessing Additional Information Words in OS/8  D.10 SABR Programming Notes     D.1  THE DEFAULT FILE STORAGE DEVICE, DSK     The Command Decoder, as noted earlier, makes certain assumptions about     the I/O device where none is explicitly stated.  Namely, on all output     files where no device name is given, the device DSK  is  assumed. On     the  first input file where no device name is given, DSK is assumed.     Subsequent input files assume the same device as  the  previous  input     file.  This convention was adopted to simplify typing command lines.     The permanent device name DSK is assigned when the system is  built.     On all standard systems, DSK is equivalent to SYS. A useful technique     is to  use  the  ASSIGN  command to  redefine  the  meaning  of DSK     temporarily.   For example, where device DTA0 is equivalent to DSK and     it becomes desirable to change DSK to DTA1, the following command can     be given:       .ASSIGN DTA1 DSK      D-1       PROGRAMMING NOTES     DTA1 remains the default file storage device until it  is assigned  a     new  name or  a  DEASSIGN command  is  executed.  This technique is     considerably easier to use than rebuilding the entire system.     If 'DSK' has not been assigned via the  ASSIGN  command, then  'DSK'     always  exists and has internal device number 2. User programs wishing     to use DSK should do an  INQUIRE  to  find its  number  in  case the     operator has re-assigned it.     D.2  MODIFICATION TO CARD READER HANDLER     The standard card reader handler for OS/8 uses  the  DEC029  standard     card  codes.   Some  installations may prefer to use the DEC026 codes     instead.  This can be done by changing the card conversion codes  with     the BUILD command ALTER.  1.  Call OS/8 BUILD by typing: RUN SYS:BUILD      in response to the dot printed by the Keyboard Monitor.  2.  Load the card reader handler as described on page 2-42 of the      OS/8 HANDBOOK.  3.  Use the ALTER command (see page  2-49 of the  OS/8  HANDBOOK)      to make the following changes:      CHANGE RELATIVE LOCATION FROM  TO      ________________________ ____  __      104 3203  7735      105 4007  4076      106 3502  0774      114 7514  3314      115 0577  1002      116 3637  0305      124 0104  3204      125 1211  1273      126 3374  3606      127 0641  1341      134 7316  3716      135 3410  1175      136 1376  3401     The new system will have modified card codes.     Note that this procedure does not affect FORTRAN run time card  input     with  READ (3,n). The  conversion  table for FORTRAN is UTILTY.SB on     source DECtape #2. (DEC-S8-OSYSB-A-UA2)      D-2       PROGRAMMING NOTES      026 PUNCH CARD CODES     Octal 8-bit   DEC026   Octal 8-bit  DEC026 CODE    CODE       CHARACTER     CODE   CODE  CHARACTER 240   BLANK  SPACE       300   8-4      @ 241   12-8-7  !       301   12-1      A 242   0-8-5  "       302   12-2      B 243   0-8-6  #       303   12-3      C 244   11-8-3  $       304   12-4      D 245   0-8-7  %       305   12-5      E 246   11-8-7  &       306   12-6      F 247   8-6  '       307   12-7      G 250   0-8-4  (       310   12-8      H 251   12-8-4  )       311   12-9      I 252   11-8-4  *       312   11-1      J 253   12  +       313   11-2      K 254   0-8-3  '       314   11-3      L 255   11  -       315   11-4      M 256   12-8-3  .       316   11-5      N 257   0-1  /       317   11-6      O 260   0  0       320   11-7      P 261   1  1       321   11-8      Q 262   2  2       322   11-9      R 263   3  3       323   0-2      S 264   4  4       324   0-3      T 265   5  5       325   0-4      U 266   6  6       326   0-5      V 267   7  7       327   0-6      W 270   8  8       330   0-7      X 271   9  9       331   0-8      Y 272   11-8-2  :       332   0-9      Z 273   0-8-2  ;       333   11-8-5     [ 274   12-8-6  <       334   8-7      \ 275   8-3  =       335   12-8-5     ] 276   11-8-6  >       336   8-5      ^ 277   12-8-2  ?       337   8-2      NOTE    On some IBM 026 Keyboards this character    is graphically represented as a [].    A card containing an  8-2  in  column  1    with  all  remaining columns blank is an    end-of-file card.      D-3       PROGRAMMING NOTES     D.3  SUPPRESSION OF CARRIAGE RETURN/LINE FEED IN FORTRAN     It is often desirable to suppress the automatic  carriage return/line     feed  (CR/LF)  following FORTRAN WRITE statements to achieve an easily     readable text.  The following three methods in  OS/8  FORTRAN  can be     used to achieve this result:  1.  Follow the I/O list of a WRITE statement with a comma.  Thus,      the following statements:  WRITE (1,100) N,   100  FORMAT (1X,15HTHE VALUE OF A(,I2,5H) IS )  READ (1,101)A(N)   101  FORMAT (F8.4)      result in the following single line (assume N has a value of      12 and a value of 147.83 is being input):   THE VALUE OF A(12) IS 147.83  2.  Use of an empty field print statement enables a  text  to be      printed  without a following CR/LF when there is no variable      to be printed.  For example:  WRITE (1,102)IDUMMY,   102  FORMAT ('DESIRED TEXT',I0)  3.  READ statement using break character, as follows:  READ (1,101) IA,IB,IC   101  FORMAT ('A=',I1,'B=',I1,'C=',I1)      results in no CR/LF after each phrase is printed.  That is,      the output is all printed on a single line.     D.4  ACCESSING THE SYSTEM DATE IN A FORTRAN PROGRAM     The availability of the system Date word in location 17666 is  useful     to many OS/8 programs.  The following FORTRAN program illustrates how     the Date can be accessed in SABR code:       C       PROGRAM PRINTS THE CURRENT DATE       C       S       DUMMY DATE       S       TAD I DATE       S       DCA TEMP       S       TAD TEMP       S       AND (7       S       DCA \IYR       S       TAD TEMP       S       RAR;RTR       S       AND (37      D-4       PROGRAMMING NOTES       S       DCA \IDAY       S       TAD TEMP       S       CLL RAL;RTL;RTL       S       AND (17       S       DCA \IMO       WRITE (1,100) IMO,IDAY,IYR       100     FORMAT (/'DATE: 'I2'-'I2'-197'I1/)       CALL EXIT       S       CPAGE 2       SDATE,  6211       S       7666       STEMP,  0     D.5  DETERMINING CORE SIZE ON PDP-8 FAMILY COMPUTERS     Many times system programs need  to  determine  the  amount  of  core     available to them at run time.  For example, the OS/8 system programs     LOADER,  PAL8,  and  CREF perform this  calculation.    Because of     differences  in the extended memory control of PDP-8 family computers,     subroutines that work on one machine might not work on another.     The following three conditions cause the most difficulty:  1.  On a  PDP-8  with an  extended  memory  control, addressing      nonexistent   memory   from  field  0  causes  the  following      instruction  to  be  skipped  and  the contents   of the      corresponding field 0 location to be executed.  For example:       CDF 70 /NONEXISTENT FIELD       TAD I(X) /EXECUTED LOCATION X       HLT /THIS INSTRUCTION SKIPPED       .       .       .   X,  CLA CLL CML RAR /LOAD 4000      The preceding code causes 4000 to be loaded into the  AC and      the HLT instruction to be skipped when executed on a PDP-8.  2.  On a PDP-12 with an odd number of 4K banks (12K, 20K,  28K),      all  reads  in the first nonexistent field load zeros.  Reads      to higher fields, as well as all reads to nonexistent  memory      on  a  machine  with  an even number of 4K banks load all one      bits.  3.  The PDP-8/L normally treats all CDF's to fields 2 through  7      as  NOP's.  (It  tests  bits  6  to  7  of  all  CDF  and CIF      instructions for 0's  before  executing  the  IOT.)  However,      there  is a special 12K option for the PDP-8/L called a BM08.      With this option a CDF to field 2 is valid, but  a  CDF's to      fields 4 through 7 remain NOP's.      D-5       PROGRAMMING NOTES     For those who are interested, the following subroutine has been tested     on the  PDP-8, 8/S, 8/L, 8/I, 8/E, PDP-12, and LINC-8 computers. For     the purpose of this example, it is assembled at 00200. /SUBROUTINE TO DETERMINE CORE SIZE. /THIS SUBROUTINE WORKS ON ANY PDP-8 FAMILY /COMPUTER. THE VALUE, FROM 1 TO 10 (OCTAL), /OF THE FIRST NON-EXISTENT MEMORY FIELD IS /RETURNED IN THE AC. /NOTE - THIS ROUTINE MUST BE PLACED IN FIELD 0     0200 0000 CORE, 0     0201 7300 CLA CLL     0202 6201 COR0, CDF 0 /(NEEDED FOR PDP-8L)     0203 1237 TAD CORSIZ /GET FIELD TO TEST     0204 7006 RTL     0205 7004 RAL     0206 0217 AND COR70 /MASK USEFUL BITS     0207 1232 TAD COREX     0210 3211 DCA .+1 /SET UP CDF TO FIELD     0211 6201 COR1, CDF \N /N IS FIELD TO TEST.     0201 1635 TAD I CORLOC /SAVE CURRENT CONTENTS     0213 7000 COR2, NOP /(HACK FOR PDP-8!)     0214 3211 DCA COR1     0215 1213 TAD COR2 /7000 IS A "GOOD" PATTERN     0216 3635 DCA I CORLOC     0217 0070 COR70, 70 /(HACK FOR PDP-8.,NO-OP)     0020 1635 TAD I CORLOC /TRY TO READ BACK 7000     0221 7400 CORX, 7400 /(HACK FOR PDP-8,.NO-OP)     0022 1221 TAD CORX /GUARD AGAINST "WRAP AROUND"     0223 1236 TAD CORV /TAD (1400)     0224 7640 SZA CLA     0225 5232 JMP COREX /NON-EXISTENT FIELD EXIT     0226 1211 TAD COR1 /RESTORE CONTENTS DESTROYED     0227 3635 DCA I CORLOC     0230 2237 ISZ CORSIZ /TRY NEXT HIGHER FIELD     0231 5202 JMP COR0     0232 6201 COREX, CDF0 /LEAVE WITH DATA FIELD 0     0233 1237 TAD CORSIZ /1ST NON-EXISTENT FIELD     0234 5600 JMP I CORE     0235 0221 CORLOC, CORX /ADDRESS TO TEST IN EACH FIELD     0236 1400 CORV, 1400 /7000+7400+1400=0     0237 0001 CORSIZ, 1 /CURRENT FIELD TO TEST     D.6  USING PRTC12-F TO CONVERT OS/8 DECTAPES TO OS/12 LINCTAPES     Many users of OS/8 on the PDP-12 will be interested in the fact  that,     since  OS/8  uses an  identical  file structure on all devices, PDP-8     DECtape in OS/8 format may be directly copied to OS/8 LINCtapes by the     PRTC12-F program.      D-6       PROGRAMMING NOTES     The PRTC12-F program uses the PDP-12 TC12-F hardware  option  to  read     DECtapes and convert these tapes to LINCtape.  This hardware option is     required to read DECtapes on the PDP-12     The PRTC12-F program is described in the document DEC-12-YIYA-D.  This     document  describes  the program operation in detail, and must be read     before attempting to use PRTC12-F. The operations that  convert  OS/8     format DECtapes are as follows:  1.  Mount the OS/8 DECtape  on  unit 1  and a  PDP-12  LINCtape      formatted with 129 words per block on unit 2.  2.  When the READ questionnaire is displayed, respond as  follows      (responses  are  underlined;   the  character  } stands for      carriage return and  ~   stands for line feed):   READ 1777  } BLOCKS   TAPE FORMAT A  }   UNIT 1 }   STARTING WITH BLOCK 0 } ~   etc.  3.  When  the WRITE questionnaire  is  displayed,  respond as      follows:   WRITE THE RESULT   IN TAPE FORMAT B } ON UNIT 2 }   STARTING AT BLOCK 0 } ~   etc.     D.7  NOTES ON LOADING DEVICE HANDLERS     D.7.1  Problem With Multiple Input Files     There is a problem associated with reusing Device Handler  areas in     OS/8.  This problem is best illustrated by an example:     Assume a program  has  reserved  locations 1000-1377  for its  input     handler  and  locations  7400-7577 for  its  output  handler.  If the     program gives a USR FETCH command to load the DTA1 handler as an input     device handler, all 8 DECtape handlers will load into 1000-1377, since     they are all co-resident. If another FETCH is issued to load the DTA2     handler  as an output device handler, that handler will not be loaded,     because it shares space with the DTA1 handler currently in core.  This     is fine - however, if the user now switches input devices and FETCHes     the paper tape reader handler as  an  input  device  handler  it  will     destroy the DTA2 handler and the next attempt to output using the DTA2     handler will produce errors.  There are two ways to  get  around  this     problem.      D-7       PROGRAMMING NOTES  1.  Always assign the handler which you expect to  stay  in  core      the  longest  first.  Most programs can process more than one      input file per program step (e.g., an assembly  pass  is one      program  step)  but  only one  output file;  therefore, they      assign the output handler before any of the  input  handlers.      In  the above example, the problem would be eliminated if the      DTA2 handler were assigned first.  2.  Always give a USR RESET call before each FETCH. Obviously,      this  call  should  not  delete  any open output files.  This      means that the USR will always load the new handler, even if      another  copy  is in  core.   The user must FETCH the output      handler again before issuing the USR  CLOSE  call,  otherwise      the USR will determine that the output handler is not in core      and give a MONITOR ERROR 3 message.     8K FORTRAN uses this second method for device-independent I/O  at run     time.     D.7.2  Dynamically Loading Device Handlers     Some programs which use dynamic core allocations will want to use OS/8     Device  handlers  but  cannot afford to always allocate the maximum of     two pages per handler.  The following is a subroutine  which  loads  a     device handler dynamically, returning its entry in the AC. It assumes     that the name of the handler is in locations NAME1 and  NAME2,  and  a     subroutine GETPAG exists which gets  a page  from  the  bottom of     available field 0 of storage and returns its address in the AC.   This     example  subroutine  runs in field 1 and can only be called from field     1, but can be rewritten for any other possibility.  ASSIGN, 0  TAD NAME1  DCA N1  TAD NAME2  DCA N2       /MOVE DEVICE NAME INTO "INQUIRE" COMMAND  CDF CIF 10  JMS I (7700  10       /USRIN - FORCE USR INTO CORE  JMS I (200  12       /INQUIRE  N1,  0  N2,  0  LOC1,  0  JMP ASSERR   /NO SUCH DEVICE - QUIT  TAD LOC1  SZA       /IS THE HANDLER ALREADY IN CORE?  JMP I ASSIGN /YES - RETURN ITS ENTRY POINT  JMS GETPAG   /GET A PAGE DYNAMICALLY  DCA LOC2  ASSTRY, TAD N2       /LOAD DEVICE NUMBER      D-8       PROGRAMMING NOTES  JMS I (200  1       /FETCH  LOC2,  0       /PAGE TO FETCH INTO  JMP TWOPAG   /FAILED - MUST BE A TWO-PAGE HANDLER  TAD LOC2  JMP I ASSIGN /RETURN ENTRY POINT  TWOPAG, JMS GETPAG   /GET ANOTHER PAGE  ISZ LOC2     /SET "TWO PAGE HANDLER ALLOWED" BIT  CLA  JMP ASSTRY   /FETCH WILL SUCCEED THIS TIME  ASSERR, .....       /ERROR ROUTINE     D.8 AVAILABLE LOCATIONS IN THE USR AREA     A few programs may need additional storage space in field 1  when the     USR  is  in  core.  A  number  of locations in the USR area (10000 to     11777) are available and may be used whenever the USR is in core. The     locations are as follows:  1.  Locations 10000 to 10006 are available  for  scratch  storage      and/or ODT breakpoint usage, without restriction.  2.  All auto-index registers (locations 10010 to  10017)  may be      used, but these locations are destroyed by USR operations.  3.  Location 10020 to 10037 may be used as scratch  storage  with      no restrictions.  4.  Locations 11400 to 11777 are used by the USR to preserve the      last directory segment read while performing a LOOKUP, ENTER,      or CLOSE operation.  Location 10007 contains a key specifying      which segment of which device is currently in core.      Any user program may use locations 11400 to 11777 as  scratch      storage  as  long as  location  10007 is set to 0 before the      first  use.   Of course, the  LOOKUP,  ENTER, and   CLOSE      operations  will read a directory segment into 11400 to 11777      and set 100007 to a non-zero value again.     D.9   ACCESSING ADDITIONAL INFORMATION WORDS IN OS/8     In all of these cases, the USR must have been previously brought  into     core with the USRIN function.     D.9.1   After a LOOKUP or ENTER     After a LOOKUP or ENTER, location 10017 points to the length  word of     the  file entry.  To get a pointer to the first Additional Information     Word, a program would execute the following code:      D-9       PROGRAMMING NOTES  CDF 10  TAD I (1404  /GET # OF ADDITIONAL INFORMATION WORDS  /FROM DIRECTORY  SNA  JMP NONE  /NO ADDITIONAL INFORMATION WORDS  TAD I (0017  DCA POINTER  .  .  .     "POINTER" now points to the first Additional Information Word.     D.9.2   After a CLOSE     Because CLOSE is a legal operation even if no output file is  present,     it is  not  suggested  that  Additional Information Words be modified     following a CLOSE. To alter the Additional  Information  Words  of  a     permanent file,  do  a LOOKUP to get the directory segment into core,     then alter the words and rewrite the directory segment.     D.9.3   Rewriting the Current Directory Segment     Whenever a user program changes the Additional Information Words of  a     file, it must rewrite the directory segment containing that file entry     in order to make sure the changes are permanently recorded.     The following code, which must be in field 1, will rewrite the current     directory segment:  CDF 10  /CODE IS IN FIELD 1  TAD 7  /GET DIRECTORY KEY WORD  AND (7  /EXTRACT SEGMENT NUMBER  DCA SEGNO  CIF 0  JMS I 51  /LOC 51 POINTS TO THE DEVICE HANDLER  4210  /WRITE OPERATION  1400  /DIRECTORY SEGMENT CORE ADDRESS  SEGNO,  0  JMP ERROR  /ERROR REWRITING DIRECTORY     Location 10051 will always point to the  device  handler  entry  point     used  to  read  in the  last directory segment, following a LOOKUP or     ENTER operation.     D-10       PROGRAMMING NOTES     D.10 SABR PROGRAMMING NOTES     D.10.1 Optimizing SABR Code     There are two types of users who will be using the SABR  assembler  -     those  who like the convenience of page-boundary-independent code and     are willing to pay the price for it, and those who need a relocatable     assembler but  are  still very location conscious.  These optimizing     hints are directed to the latter user.     One way to beat the  high cost  of  non-paged  code  is  to  Page It     Yourself. This  is  done by  using the LAP (Leave Automatic Paging)     pseudo-op and the PAGE pseudo-op to force paging where  needed.   This     saves  2  to  4  instructions  per page  from elimination of the page     escape.  In addition, the fact  that  the program must  be  properly     segmented may save a considerable amount.     Wasted core  may  be  reduced  by eliminating  the  ever-present CDF     instructions which SABR inserts into a program.  This is done by using     n fake indirects". Define the following op codes: OPDEF  ANDI 0400 OPDEF  TADI 1400 OPDEF  ISZI 2400 OPDEF  DCAI 3400 . . .     These codes correspond to the PDP-8 memory reference instructions but     they  include an indirect bit.  The difference can best be appreciated     by an example:     If X is off-page, the sequence       LABEL,  SZA       DCA X     is assembled by SABR into       LABEL,  SZA       JMS 45       SKP       DCA I (X)     or four instructions and one literal.     The sequence     D-11       PROGRAMMING NOTES       PX,     X       .       .       .       LABEL,  SZA       DCAI PX     assembles into three instructions for a saving of 40  percent.   Note,     however,  that  the  user must  be  sure that the data field will be     correct when the code at LABEL is encountered.   Also  note  that the     SABR  assumes  that  the  Data Field is equal to the Instruction Field     after a JMS instruction, so subroutine returns should not use the JMPI     op code.     The standard method to fetch a scalar integer argument of a subroutine     in SABR is:       Code       IARG,   DUMMY X       0       SUBR,   BLOCK 2       TAD I SUBR       DCA X       INC SUBR#       TAD I SUBR       DCA X#       INC SUBR#       TAD I X       DCA IARG       .       .       .       X,      BLOCK 2     This code requires  19  words  of core  and  takes  several  hundred     microseconds to execute.  The following sequence:       Code       IARG,   0       SUBR,   BLOCK 2       TAD I SUBR       DCA X       INC SUBR#       TADI SUBR#       DCA IARG       INC SUBR#       X,      HLT /THIS IS A CDF       TAD I IARG       DCA IARG       .       .       .     takes only 14 words and executes in approximately 1/3 the time.     D-12       PROGRAMMING NOTES     D.10.2  Calling the USR and Device Handlers from SABR Code     One important thing to remember is that any code which calls  the USR     must  not reside in  locations  10000 to 11777. Therefore, any SABR     routine which calls the USR must be loaded into a field other  than  1     or above location 2000 in field 1. To call the USR from SABR use the     sequence:  CPAGE n  /N=7+(# OF ARGUMENTS)  6212  /CIF 10  JMS 7700  /OR 200 IF USR IN CORE  REQUEST  ARGUMENTS  /OPTIONAL DEPENDING ON REQUEST  ERROR RETURN  /OPTIONAL DEPENDING ON REQUEST To call a device handler from SABR use the sequence:  CPAGE12  /10 IF "HAND" IN PAGE 0  6202  /CIF 0  JMS I HAND  /DO NOT USE JMSI  FUNCT  ADDR  BLOCK  ERROR RETURN  SKP  HAND,  0  /"HAND" MUST BE ON SAME PAGE  /AS CALL, OR IN PAGE 0!!     D-13   APPENDIX E CHARACTER CODES AND CONVENTIONS     Table E-1 contains a list of the control characters used by  OS/8 and     associated system programs.   Table  E-2 contains the OS/8 character     set, which is a subset of the complete ASCII code, the unlisted  codes     are  generally  not  used by  OS/8  or the system programs.  Note the     following:  1.  On some terminals, the character back-arrow (_)  is  replaced      by  an  underline (_)   character,  and the up-arrow (^) is      replaced by circumflex (^).  2.  Some terminals use  parity  codes rather than  forcing the      leading  bit  of the 8-bit character code to be a 1. To avoid      problems, OS/8 system programs always ignore the parity bit      during ASCII input.  3.  OS/8 does not handle lower case characters (octal codes 341      through  372).  The  exceptions to this are the editors, EDIT      and TECO. The KL8E and LPSV  handlers  can  be  modified to      handle lower case.   Table E-1    OS/8 Control Characters     +---------------------------------------------------------------------+     |  Octal   |     |  8-bit      Character   |     |  Code Name  Remarks   |     +---------------------------------------------------------------------+     |  000    null Ignored in ASCII input.   |     |   |     |  200    leader/trailer Leader/trailer code  precedes and|     | follows the data portion of binary|     | files.   |     |   |     |  203    CTRL/C OS/8 break character, forces return|     | to Keyboard Monitor, echoed as ^C. |     |   |     |  207    BELL CTRL/G.   |     |   |     |  211    TAB CTRL/I, horizontal tabulation.   |     |   |     |  212    LINE FEED Used as a control character by the|     | Command Decoder and ODT.   |     |   |     |  213    VT CTRL/K, vertical tabulation.   |     +---------------------------------------------------------------------+      E-1 CHARACTER CODES AND CONVENTIONS Table E-1 (Cont.)     OS/8 Control Characters     +---------------------------------------------------------------------+     |  Octal   |     |  8-bit      Character   |     |  Code Name  Remarks   |     +---------------------------------------------------------------------+     |  214    FORM CTRL/L, form feed.   |     |   |     |  215    RETURN Carriage return,  generally  echoed|     | as  carriage  return  followed by a|     | line feed.   |     |   |     |  216 Used only  on  LS8E  line  printer.|     | Puts  current  line  into  expanded|     | character mode.   |     |   |     |  217    CTRL/O Break Character, used  to  suppress|     | Teletype output, echoed as ^O.   |     |   |     |  225    CTRL/U Delete current input  line,  echoed|     | as ^U.   |     |   |     |  232    CTRL/Z End-of-File character for all ASCII|     | and  binary  files  (in relocatable|     | binary files  CTRL/Z  is   not  a|     | terminator  if it occurs before the|     | trailer code).   |     |   |     |  233    ESC ESCape replaces  ALTMODE  on  some|     | terminals.   Considered equivalent|     | to ALTMODE.   |     |   |     |  375    ALTMODE Special  break   character for|     | Teletype input.   |     |   |     |  376    PREFIX PREFIX replaces  ALTMODE  on  some|     | terminals.   Considered equivalent|     | to ALTMODE.   |     |   |     |  377    RUBOUT Key  is labeled  DELETE  on   some|     | terminals.   Deletes  the  previous|     | character typed.   |     +---------------------------------------------------------------------+      E-2 CHARACTER CODES AND CONVENTIONS     Table E-2       ASCII Character Codes     +-------+--------+----------+--------------+--------------------------+     | Octal |      | Punched |  Character |   |     | 8-bit | 6-bit | Card |  Representa- |   |     | Code  | Code  | Code |  tion |  Remarks   |     +-------+--------+----------+--------------+--------------------------+     |     |      | | |   |     | 240   |  40  | blank | |  space (non-printing)   |     | 241   |  41  | 11-8-2 |     ! |  exclamation point   |     | 242   |  42  | 8-7 |     " |  quotation marks   |     | 243   |  43  | 8-3 |     # |  number sign   |     | 244   |  44  | 11-8-3 |     $ |  dollar sign   |     | 245   |  45  | 0-8-3 |     % |  percent   |     | 246   |  46  | 12 |     & |  ampersand   |     | 247   |  47  | 8-5 |     ' |  apostrophe or acute   |     |     |      | | |  accent   |     |     |      | | |   |     | 250   |  50  | 12-8-5 |     ( |  opening parenthesis   |     | 251   |  51  | 11-8-5 |     ) |  closing parenthesis   |     | 252   |  52  | 11-8-4 |     * |  asterisk   |     | 253   |  53  | 12-8-6 |     + |  plus   |     | 254   |  54  | 0-8-3 |     , |  comma   |     | 255   |  55  | 11 |     _ |  minus sign or hyphen   |     | 256   |  56  | 12-8-3 |     . |  period or decimal point |     | 257   |  57  | 0-1 |     / |  slash   |     |     |      | | |   |     | 260   |  60  | 0 |     0 |   |     | 261   |  61  | 1 |     1 |   |     | 262   |  62  | 2 |     2 |   |     | 263   |  63  | 3 |     3 |   |     | 264   |  64  | 4 |     4 |   |     | 265   |  65  | 5 |     5 |   |     | 266   |  66  | 6 |     6 |   |     | 267   |  67  | 7 |     7 |   |     |     |      | | |   |     | 270   |  70  | 8 |     8 |   |     | 271   |  71  | 9 |     9 |   |     | 272   |  72  | 8-2 |     : |  colon   |     | 273   |  73  | 11-8-6 |     ; |  semicolon   |     | 274   |  74  | 12-8-4 |     < |  less than   |     | 275   |  75  | 8-6 |     = |  equals   |     | 276   |  76  | 0-8-6 |     > |  greater than   |     | 277   |  77  | 0-8-7 |     ? |  question mark   |     |     |      | | |   |     | 300   |  00  | 8-4 |     @ |  at sign   |     | 301   |  01  | 12-1 |     A |   |     | 302   |  02  | 12-2 |     B |   |     | 303   |  03  | 12-3 |     C |   |     | 304   |  04  | 12-4 |     D |   |     | 305   |  05  | 12-5 |     E |   |     | 306   |  06  | 12-6 |     F |   |     | 307   |  07  | 12-7 |     G |   |     +-------+--------+----------+--------------+--------------------------+      E-3 CHARACTER CODES AND CONVENTIONS Table E-2 (Cont.)       ASCII Character Codes     +-------+--------+----------+--------------+--------------------------+     | Octal |      | Punched |  Character |   |     | 8-bit | 6-bit | Card |  Representa- |   |     | Code  | Code  | Code |  tion |  Remarks   |     +-------+--------+----------+--------------+--------------------------+     |     |      | | |   |     | 310   |  10  | 12-8 |     H |   |     | 311   |  11  | 12-9 |     I |   |     | 312   |  12  | 11-1 |     J |   |     | 313   |  13  | 11-2 |     K |   |     | 314   |  14  | 11-3 |     L |   |     | 315   |  15  | 11-4 |     M |   |     | 316   |  16  | 11-5 |     N |   |     | 317   |  17  | 11-6 |     O |   |     |     |      | | |   |     | 320   |  20  | 11-7 |     P |   |     | 321   |  21  | 11-8 |     Q |   |     | 322   |  22  | 11-9 |     R |   |     | 323   |  23  | 0-2 |     S |   |     | 324   |  24  | 0-3 |     T |   |     | 325   |  25  | 0-4 |     U |   |     | 326   |  26  | 0-5 |     V |   |     | 327   |  27  | 0-6 |     W |   |     |     |      | | |   |     | 330   |  30  | 0-7 |     X |   |     | 331   |  31  | 0-8 |     Y |   |     | 332   |  32  | 0-9 |     Z |   |     | 333   |  33  | 12-8-2 |     [ |  opening bracket,SHIFT/K |     | 334   |  34  | 11-8-7 |     \ |  backslash, SHIFT/L   |     | 335   |  35  | 0-8-2 |     ] |  closing bracket, SHIFT/M|     | 336   |  36  | 12-8-7 |     ^ |  circumflex   |     | 337   |  37  | 0-8-5 |     _ |  underline - EOF signal  |     +-------+--------+----------+--------------+--------------------------+      NOTES  1.  These are the DEC029 standard card codes.  2.  On most DEC Teletypes circumflex is replaced by up-arrow (^).  3.  A card containing 0-8-5 in  column  1  with  all  remaining      columns blank is an end-of-file card.  4.  On most DEC Teletypes underline  is  replaced  by back-arrow      (_).  5.  On some IBM 029 keyboards 1 is graphically represented  as  a      cent sign (c /).  6.  On some IBM 029 keyboards \  is  graphically  represented as      logical NOT (-,).      E-4 CHARACTER CODES AND CONVENTIONS  7.  On some IBM 029 keyboards ^  is graphically  represented as      vertical bar (|).  8.  On a very few LP08 line printers, the character diamond  (<>)      is printed instead of backslash.  9.  On a very few LP08 line printers, the character heart (V) is      printed instead of underline. 10.  The character number sign on some terminals  is  replaced by      pound sign (L).      E-5   APPENDIX F  OS/8 INPUT/OUTPUT ROUTINES     Appendix F describes a set of generalized I/O routines for use  under     the OS/8 system.  The routines presented here are used in all the OS/8     CUSPs (Commonly Used System Programs)  in more  or  less this  form.     Variations are  made  depending on the particular application and how     errors are to be handled. The routines, as indicated,  will  work as     presented.  The  routines work most efficiently in field 1, since CIF     10's are not necessary when addressing the Monitor,  and  the  Command     Decoder tables are similarly available.  Obviously the routines can be     modified to run in any memory field or core locations.     F.1  GENERAL DESCRIPTION     These subroutines assume that the Command Decoder tables have been set     up to  indicate  the  proper I/O devices. The routines handle device     handler assignment without user interference.   All  I/O  is  done by     simple  subroutine calls.  The user program never needs to interface     with the Monitor or  device  handlers.   All  buffering  and  internal     bookkeeping  are  performed by the routines.  In these routines, it is     assumed that only one output device is  used  at  a  time, i.e., the     output  routine  does  not automatically set  up for the next output     device.  This modification can be made if desired. As  many  as  nine     inputs  are  handled  automatically.   When  input from one device is     exhausted, the input  routine  will  automatically utilize  the  next     device specified in the Command Decoder list of inputs.     F.2  SUBROUTINES FUNCTIONS     Following is a brief list of the subroutines and their functions.  ICHAR - Character input routine.   Call sequence:   JMS ICHAR   ERROR RETURN   NORMAL RETURN   Error:   If AC>0, an EOF on input has occurred.  No  more   input is available. If AC<0, a device error has   occurred.      F-1  OS/8 INPUT/OUTPUT ROUTINES   Normal:   8 bit character is in the AC.  OCHAR - Character output routine.   Call:   TAD CHAR /8 BIT CHARACTER   JMS OCHAR   ERROR RETURN   NORMAL RETURN   Error:   AC<0 implies a fatal error.   AC > or = 0 implies that the hole  allotted for   output was exceeded.   Normal:   AC=0. The character has been put into the device   output buffer.  IOPEN - Input initialize routine.   Call:   JMS IOPEN   RETURN  Return:   Input pointers reset.  The next  call  to  ICHAR   will read  from the first device in the Command   Decoder input list.  OOPEN - Output initialize routine.   Call:   JMS OOPEN   ERROR RETURN   NORMAL RETURN   Error:   If AC> or = 0, no output device was specified.   If AC<0, an error occurred opening the file.   Normal:   An output file has been opened.   No action if   the output was a non-file structured device.      F-2  OS/8 INPUT/OUTPUT ROUTINES  OCLOSE - Output close routine.   Call:   JMS OCLOSE   ERROR RETURN   NORMAL RETURN   Error:   Either the closing length is too large  for the   space allotted or an output error has occurred.   Normal:   The output file is now a permanent file  on the   output device.     F.3  SUBROUTINE PARAMETERS     These subroutines handle  device  assignment  and internal  buffering     automatically.  To accomplish this, certain parameters must be defined     at assembly time. These parameters specify  all  details of  handler     location, and buffer size for the routines.  Parameter Definition  _________ __________  INBUF = Address of input buffer.  INCTL = Input buffer control word.   See  the section on using device handlers for details of the control word format.  OUBUF = Output buffer address.  OUCTL = Output buffer control  word.  This must  be  a negative number to indicate a write operation.  INRECS = Number of input records in input buffer.  INRECS = INCTL/256 (DECIMAL).  INDEVH = Address of input device handler.  OUDEVH = Address of output device handler.     The parameters can either be a part of the actual subroutine  source,     or they can be contained in a separate parameter file to be assembled     with the  subroutine  file.   The latter approach  provides  greater     flexibility in using the routines.      F-3  OS/8 INPUT/OUTPUT ROUTINES     F.3.1  Example     Following is a sample of the use  of  the subroutines.   The  program     simply  calls  the Command Decoder, and transfers input from the input     devices to the output file, closes the output, and exits.       FIELD 1       *2000       JMS I (7700 /LOCK MONITOR INTO CORE.       10     CALLCD,   JMS I (200 /CALL COMMAND DECODER       5 /TO PICK OPTIONS.       0       JMS I (IOPEN /SETUP TO START LOOKING AT /CD INPUT FILE.       JMS I (OOPEN /OPEN UP AN OUTPUT FILE.       SMA CLA /IF AC<0, WE HAD A FATAL       JMP OK /TYPE ERROR. AC>0 IS O.K.       JMS TERR /ERROR.       TEXT /OPEN FAILED/     OK,       JMS I (ICHAR       JMP TSTEOF /EITHER ERROR OR EOF. /SAVE IT.       JMS I (OCHAR /TRANSFER THE CHARACTER       JMP OUTERR /OUTPUT ERROR       JMP OK /TRANSFER UNTIL EOF FOUND.     TSTEOF,   SMA CLA /IF NEG., FATAL       JMP CLOSE /EOF. CLOSE OUTPUT       JMS TERR       TEXT /READ ERROR/     CLOSE,    JMS I (OCLOSE /CLOSE OUTPUT FILE.       JMP CLERR /CLOSE ERROR       JMP CALLCD /NEXT.     OUTERR,   JMS TERR       TEXT /OUTPUT ERROR/     CLERR,    JMS TERR       TEXT /CLOSE ERROR/     TERR,     0       TAD I TERR       RTR;RTR;RTR       JMS TYPIT       TAD I TERR       JMS TYPIT       ISZ TERR       JMP TERR+1     TYPIT,    0       AND (77       SNA       JMP CRLF       TAD (300       JMS TTYOUT       JMP I TYPIT      F-4  OS/8 INPUT/OUTPUT ROUTINES     CRLF,     TAD (215       JMS TTYOUT       TAD (212       JMS TTYOUT       JMP CALLCD     TTYOUT,   0       TLS       TSF       JMP.-1       CLA       JMP I TTYOUT     F.3.2  Subroutine Listing     A listing of the routines follows. The parameters are set up in  such     a way  as to  allow  them  to  be put into a separate file.  Another     parameter, ORIGIN, determines the location of the routines.      F-5  OS/8 INPUT/OUTPUT ROUTINES /OS/8 GENERAL CHARACTER I/O ROUTINES FO   PAL8-VC0  05-OCT-96 PAGE 1              /OS/8 GENERAL CHARACTER I/O ROUTINES FOR BLEEP              /CALLED AS FOLLOWS:              /JMS I (IOPEN           INITIALIZES THE INPUT ROUTINE              /JMS I (ICHAR           READS A CHARACTER              /ERROR RETURN           AC>0 IF END OF FILE, AC<0 IF READ              /                       ERROR              /JMS I (OOPEN           INITIALIZES THE OUTPUT ROUTINE              /ERROR RETURN           AC>0 IF NO OUTPUT DEVICE/FILE, AC<0              /                       IF ERROR              /JMS I (OCHAR           OUTPUTS A CHARACTER              /ERROR RETURN           OUTPUT ERROR OR TOO MUCH OUTPUT              /JMS I (OCLOSE          CLOSES THE OUTPUT FILE              /ERROR RETURN           FILE TOO LARGE TO BE CLOSED OR OUTPUT              /                       ERROR              /JMS I (OTYPE           RETURNS DCB WORD OF OUTPUT DEVICE IN              /                       AC              /PARAMETERS NEEDED:              /INBUF=         ADDRESS OF INPUT BUFFER              /INCTL=         INPUT BUFFER CONTROL WORD              /OUBUF=         ADDRESS OF OUTPUT BUFFER              /OUCTL=         OUTPUT BUFFER CONTROL WORD (MUST BE NEGATIVE)              /INRECS=        [INCTL/256]              /INDEVH=        ADDRESS OF PAGE FOR INPUT HANDLER              /OUDEVH=        ADDRESS OF PAGE FOR OUTPUT HANDLER              /IORFLD=        /FIELD OF THE SUBROUTINES.              /ORIGIN=        /THE SUBROUTINES RESIDE AT 16600.              /ASSUMES I/O MONITOR IS RESIDENT IN CORE.              /CAN BE CALLED FROM ANY FIELD WITH BUFFERS IN ANY FIELD.      F-6  OS/8 INPUT/OUTPUT ROUTINES /OS/8 GENERAL CHARACTER I/O ROUTINES FO   PAL8-VC0  05-OCT-96 PAGE 2                      /PARAMETER DEFINITION:        5000          OUBUF=  5000    /OUTPUT BUFFER STARTS AT 05000        4200          OUCTL=  4200    /AND IS 2 PAGES LONG.        6600          OUDEVH= 6600    /OUTPUT HANDLER GETS LOADED AT 6600.                                      /WE ALLOW TWO PAGE HANDLERS.        5400          INBUF=  5400    /INPUT BUFFER STARTS AT 05400        0200          INCTL=  0200    /ALSO TWO PAGES LONG.        0001          INRECS= 1       /2 PAGES = 1 RECORD        7000          INDEVH= 7000    /ALLOW 2 PAGE INPUT HANDLER AT 7000.        0001          IORFLD= 1       /FIELD OF THE SUBROUTINES.        6600          ORIGIN= 6600    /THE SUBROUTINES RESIDE AT 16600.        0001          FIELD    IORFLD        6600          *ORIGIN        0000          INFLD=  INCTL&70        /INPUT BUFFER FIELD        0000          OUFLD=  OUCTL&70        /OUTPUT BUFFER FIELD        7760          DCB=    7760            /DEVICE CONTROL TABLE      F-7  OS/8 INPUT/OUTPUT ROUTINES /OS/8 GENERAL CHARACTER I/O ROUTINES FO   PAL8-VC0  05-OCT-96 PAGE 3 016600  0000  ICHAR,  0                       /INPUT A CHARACTER 016601  7600  IN7600, 7600 016602  6214          RDF                     /SAVE CALLING FIELD FOR RETURN 016603  1232          TAD     INCDIF 016604  3316          DCA     INRTRN 016605  6201  INCHAR, CDF     INFLD           /DATA FIELD TO FIELD OF BUFFER 016606  2265          ISZ     INJMP           /3 - WAY UNPACKING SWITCH 016607  2325          ISZ     INCHCT          /INPUT BUFFER EXHAUSTED? 016610  5265  INJMPP, JMP     INJMP           /NO..UNPACK THE NEXT CHAR. 016611  1321          TAD     INEOF           /DID LAST READ GIVE EOF ON 016612  7650          SNA CLA                 / THIS DEVICE? 016613  5216          JMP     INGBUF          /NO. CONTINUE READING. 016614  4325  GETNEW, JMS     INNEWF          /YES..GET NEXT INPUT IF IT                                              / EXISTS. 016615  5264          JMP     EOFERR          /TAKE EOF EXIT FROM ICHAR. 016616  1324  INGBUF, TAD     INCTR           /INCTR HOLDS THE CURRENT LENGTH                                              / OF THE INPUT FILE.  WHEN THE                                              / AMOUNT REMAINING TO READ IS                                              / LESS THAN THE SIZE OF THE                                              / INPUT BUFFER, AN EOF IS                                              / SIGNALED. 016617  7100          CLL 016620  1377          TAD     (INRECS 016621  7420          SNL 016622  3324          DCA     INCTR           /UPDATE REMAINING LENGTH 016623  7430          SZL 016624  2321          ISZ     INEOF           /AND SIGNAL EOF FOR NEXT READ. 016625  7172          CLL CML CMA RTR         /CONSTRUCT A CONTROL WORD FOR 016626  7012          RTR                     / THIS READ FROM THE OVERFLOW, 016627  7012          RTR                     / IF ANY, AND THE STANDARD 016630  1376          TAD     (INCTL+1        / CONTROL WORD. 016631  3235          DCA     INCTLW 016632  6203  INCDIF, CIF CDF 0               /NOW CALL THE INPUT HANDLER 016633  6211          CDF     10              /HANDLER IS IN FIELD 0 016634  4736          JMS I   INHNDL 016635  0000  INCTLW, 0                       /INPUT CONTROL WORLD 016636  5400  INBUFP, INBUF                   /INPUT BUFFER ADDRESS 016637  0000  INREC,  0                       /POINTER TO INPUT RECORD 016640  5260          JMP     INERRX 016641  1237  INBREC, TAD     INREC 016642  1377          TAD     (INRECS         /UPDATE POINTER INTO FILE 016643  3237          DCA     INREC 016644  1235          TAD     INCTLW          /NOW COMPUTE THE NUMBER OF 016645  0201          AND     IN7600          / CHARACTERS IN THIS INPUT 016646  7104          CLL RAL                 / BUFFER 016647  1235          TAD     INCTLW 016650  0201          AND     IN7600 016651  7040          CMA 016652  3325          DCA     INCHCT          /NEW NUMBER OF CHARACTERS 016653  1210          TAD     INJMPP          /RESET 3 WAY SWITCH 016654  3265          DCA     INJMP      F-8  OS/8 INPUT/OUTPUT ROUTINES /OS/8 GENERAL CHARACTER I/O ROUTINES FO   PAL8-VC0  05-OCT-96 PAGE 3-1 016655  1236          TAD     INBUFP 016656  3323          DCA     INPTR           /AND BUFFER POINTER 016657  5205          JMP     INCHAR          /NOW READ THE BUFFER 016660  2321  INERRX, ISZ     INEOF           /SET EOF JUST IN CASE 016661  7700          SMA CLA                 /IF <0, A PHYSICAL ERROR 016662  5241          JMP     INBREC          /EOF ON INPUT 016663  7330  INERR,  CLA CLL CML RAR         /FATAL 016664  5316  EOFERR, JMP     INRTRN          /GET OUT 016665  7402  INJMP,  HLT                     /3 WAY UNPACK SWITCH 016666  5307          JMP     ICHAR1          /GET 1ST OF 3 016667  5303          JMP     ICHAR2          /SECOND 016670  1210  ICHAR3, TAD     INJMPP 016671  3265          DCA     INJMP           /SET FOR FIRST CHAR. NEXT 016672  1723          TAD I   INPTR           /THE THIRD WORD IS MADE OF THE 016673  0320  IN200,  AND     IN7400          / HIGH ORDER FOUR BITS OF THE 016674  7112          CLL RTR                 / FIRST TWO. 016675  7012          RTR 016676  1235          TAD     INCTLW 016677  7012          RTR 016700  7012          RTR 016701  2323          ISZ     INPTR           /POINT TO NEXT WORD 016702  5310          JMP     INCOMN          /GET OUT WITH CHAR IN AC 016703  1723  ICHAR2, TAD I   INPTR 016704  0320          AND     IN7400          /SAVE HIGH ORDER FOR THIRD 016705  3235          DCA     INCTLW          / WORD 016706  2323          ISZ     INPTR 016707  1723  ICHAR1, TAD I   INPTR 016710  0375  INCOMN, AND     (377 016711  1374          TAD     (-232           /IS IT A ^Z (EOF)? 016712  7450          SNA 016713  5214          JMP     GETNEW          /YES..LOOK AT NEXT INPUT 016714  1373          TAD     (232 016715  2200          ISZ     ICHAR           /TAKE NORMAL RETURN 016716  0000  INRTRN, 0                       /CIF CDF N. 016717  5600          JMP I   ICHAR 016720  7400  IN7400, 7400 016721  0000  INEOF,  0                       /END OF FILE FLAG 016722  0000  INFPTR, 0                       /POINTER TO INPUT FILE NAMES 016723  0000  INPTR,  0                       /INPUT BUFFER POINTER 016724  0000  INCTR,  0                       /LENGTH OF CURRENT INPUT FILE      F-9  OS/8 INPUT/OUTPUT ROUTINES /OS/8 GENERAL CHARACTER I/O ROUTINES FO   PAL8-VC0  05-OCT-96 PAGE 4 016725  7777  INNEWF, -1                      /OPEN A NEW INPUT FILE        6725  INCHCT= INNEWF 016726  6211          CDF     10 016727  1372          TAD     (INDEVH+1       /INITIALIZE JUST IN CASE 016730  3336          DCA     INHNDL 016731  1722          TAD I   INFPTR          /MORE INPUT? 016732  7450          SNA 016733  5725          JMP I   INNEWF          /NOPE 016734  4673          JMS I   IN200           /CALL MONITOR TO GET HANDLER 016735  0001          1 016736  0000  INHNDL, 0 016737  7402          HLT                     /VERY BAD! 016740  1722          TAD I   INFPTR 016741  0371          AND     (7760           /GET INPUT FILE LENGTH 016742  7440          SZA 016743  1370          TAD     (17 016744  7132          CLL CML RTR 016745  7012          RTR                     /NEGATIVE OF FILE LENGTH 016746  3324          DCA     INCTR 016747  2322          ISZ     INFPTR          /POINT TO STARTING BLOCK 016750  1722          TAD I   INFPTR 016751  3237          DCA     INREC           /STORE IN HANDLER CALL 016752  2322          ISZ     INFPTR          /NEXT INPUT. 016753  3321          DCA     INEOF           /CLEAR EOF FLAG. 016754  2325          ISZ     INNEWF 016755  5725          JMP I   INNEWF 016770  0017 016771  7760 016772  7001 016773  0232 016774  7546 016775  0377 016776  0201 016777  0001        7000          PAGE     F-10  OS/8 INPUT/OUTPUT ROUTINES /OS/8 GENERAL CHARACTER I/O ROUTINES FO   PAL8-VC0  05-OCT-96 PAGE 5 017000  0000  OOPEN,  0                       /OPEN OUTPUT FILE 017001  7600  OU7600, 7600 017002  1347          TAD     OU7601          /POINT TO OUTPUT FILE NAME IN 017003  3221          DCA     OUBLK           / CD AREA 017004  1377          TAD     (OUDEVH+1 017005  3214          DCA     OUHNDL          /INITIALIZE OUTPUT HANDLER 017006  1601          TAD I   OU7600          /PICK UP OUTPUT DEVICE NUMBER 017007  0376          AND     (17 017010  7450          SNA                     /IS THERE ONE? 017011  5244          JMP     ONOFIL          /NO..INHIBIT OUTPUT 017012  4775          JMS I   (200            /FETCH OUTPUT HANDLER 017013  0001          1 017014  0000  OUHNDL, 0 017015  7402          HLT                     /BAD THING 017016  1601  OUENTR, TAD I   OU7600 017017  4775          JMS I   (200            /ENTER THE OUTPUT FILE 017020  0003          3 017021  7601  OUBLK,  7601                    /GETS STARTING BLOCK OF HOLE 017022  0000  OUELEN, 0                       /GETS SIZE OF HOLE AVAILABLE 017023  5232          JMP     OEFAIL          /FAILURE. SEE WHAT WE DID. 017024  3350          DCA     OUCCNT          /CLEAR CLOSING LENGTH 017025  3774          DCA I   (OUTINH         /CLEAR OUTPUT INHIBIT 017026  4773          JMS I   (OUSETP         /SET UP POINTERS 017027  2200          ISZ     OOPEN 017030  6213  OORETN, CDF CIF 10 017031  5600          JMP I   OOPEN           /RETURN O.K. 017032  1601  OEFAIL, TAD I   OU7600          /IF LENGTH=0, GIVE OPEN ERROR 017033  0372          AND     (7760           /IF NOT, MAKE IT 0 AND TRY 017034  7650          SNA CLA                 / AGAIN 017035  5242          JMP     ONTERR          /WAS 0. FAILED 017036  1601          TAD I   OU7600 017037  0376          AND     (17             /MAKE IT 0 017040  3601          DCA I   OU7600 017041  5216          JMP     OUENTR          /AND TRY AGAIN 017042  7330  ONTERR, CLA CLL CML RAR 017043  5230          JMP     OORETN 017044  2774  ONOFIL, ISZ I   (OUTINH         /INHIBIT OUTPUT 017045  5230          JMP     OORETN     F-11  OS/8 INPUT/OUTPUT ROUTINES /OS/8 GENERAL CHARACTER I/O ROUTINES FO   PAL8-VC0  05-OCT-96 PAGE 6 017046  0000  OUTDMP, 0                       /DUMP OUTPUT BUFFER 017047  3300          DCA     OUCTLW          /STORE CONTROL WORD 017050  6211          CDF     10 017051  1774          TAD I   (OUTINH         /IS OUTPUT INHIBITED? 017052  7640          SZA CLA 017053  5304          JMP     OUNOWR          /YEP. 017054  1350          TAD     OUCCNT          /IF THIS IS FIRST WRITE, START 017055  7450          SNA                     / SEARCH FORWARD ON DECTAPE 017056  2300          ISZ     OUCTLW 017057  1221          TAD     OUBLK           /GET STARTING BLOCK OF THIS 017060  3302          DCA     OUREC           / TRANSFER 017061  1300          TAD     OUCTLW 017062  7106          CLL RTL 017063  7006          RTL 017064  7006          RTL                     /COMPUTE # OF RECORDS TO 017065  0376          AND     (17             / OUTPUT 017066  1350          TAD     OUCCNT          /UPDATE CLOSING LENGTH 017067  3350          DCA     OUCCNT 017070  1350          TAD     OUCCNT          /SEE IF CLOSING LENGTH WILL 017071  7120          CLL CML                 / BE BIGGER THAN OUTPUT HOLE 017072  1222          TAD     OUELEN 017073  7660          SNL SZA CLA 017074  5646          JMP I   OUTDMP          /WILL BE TOO BIG 017075  6203  OUCDIV, CIF CDF 0 017076  6211          CDF     10 017077  4614          JMS I   OUHNDL          /DO THE WRITE 017100  0000  OUCTLW, 0 017101  5000          OUBUF 017102  0000  OUREC,  0 017103  7410          SKP                     /ERROR 017104  2246  OUNOWR, ISZ     OUTDMP          /TAKE NORMAL RETURN 017105  5646          JMP I   OUTDMP        0020  PTP=    0020     F-12  OS/8 INPUT/OUTPUT ROUTINES /OS/8 GENERAL CHARACTER I/O ROUTINES FO   PAL8-VC0  05-OCT-96 PAGE 7 017106  0000  OCLOSE, 0                       /CLOSE OUTPUT FILE 017107  6211          CDF     10 017110  1774          TAD I   (OUTINH         /IF OUTPUT INHIBITED, CLOSE                                              / IS A NOP. 017111  7640          SZA CLA 017112  5352          JMP     OCISZ           /A NOP 017113  4771          JMS I   (OTYPE          /DETERMINE IF OUTPUT IS TO PTP 017114  0370          AND     (770            /IF IT IS, DON'T OUTPUT A ^Z. 017115  1372          TAD     (-PTP 017116  7640          SZA CLA 017117  1367          TAD     (232            /NOT PTP. OUTPUT ^Z AS EOF 017120  4766          JMS I   (OCHAR 017121  5353          JMP     OCRET           /ERROR RETURN 017122  4766          JMS I   (OCHAR          /FILL WITH 0 CHARACTERS 017123  5353          JMP     OCRET 017124  4766  FILLIP, JMS I   (OCHAR          /FILL TO BOUNDARY WITH 0 017125  5353          JMP     OCRET 017126  4771          JMS I   (OTYPE          /IF OUTPUT IS DIRECTORY DEVICE, 017127  7710          SPA CLA                 / FILL WHOLE RECORD, ELSE HALF 017130  1365          TAD     (100            / RECORD 017131  1364          TAD     (77) 017132  0763          AND I   (OUDWCT         /ARE WE UP TO BOUNDARY YET? 017133  7640          SZA CLA 017134  5324          JMP     FILLIP          /NO 017135  1763          TAD I   (OUDWCT 017136  1375          TAD     (OUCTL&3700     /IS THERE A FULL WRITE LEFT? 017137  7450          SNA 017140  5344          JMP     NODUMP          /YES. BUT DON'T DO IT, AS ^Z                                              / IS OUT. 017141  1362          TAD     (4000+OUFLD 017142  4246          JMS     OUTDMP          /DUMP LAST BUFFER 017143  5353          JMP     OCRET 017144  1601  NODUMP, TAD I   OU7600          /GET DEVICE NUMBER 017145  4775          JMS I   (200            /CLOSE THE OUTPUT FILE 017146  0004          4 017147  7601  OU7601, 7601                    /POINTER TO FILE NAME 017150  0000  OUCCNT, 0                       /CLOSING FILE LENGTH HERE 017151  7410          SKP                     /ERROR 017152  2306  OCISZ,  ISZ     OCLOSE          /NORMAL RETURN 017153  6213  OCRET,  CDF CIF 10              /RESTORE CALLING FIELDS 017154  5706          JMP I   OCLOSE 017162  4000 017163  7272 017164  0077 017165  0100 017166  7211 017167  0232 017170  0770 017171  7274 017172  7760     F-13  OS/8 INPUT/OUTPUT ROUTINES /OS/8 GENERAL CHARACTER I/O ROUTINES FO   PAL8-VC0  05-OCT-96 PAGE 7-1 017173  7200 017174  7273 017175  0200 017176  0017 017177  6601        7200          PAGE     F-14  OS/8 INPUT/OUTPUT ROUTINES /OS/8 GENERAL CHARACTER I/O ROUTINES FO   PAL8-VC0  05-OCT-96 PAGE 8 017200  0000  OUSETP, 0                       /INITIALIZE OUTPUT POINTERS 017201  1377          TAD     (OUCTL&3700 017202  7041          CIA 017203  3272          DCA     OUDWCT          /DOUBLE WORD OUTPUT COUNT 017204  1376          TAD     (OUBUF          /INITIALIZE WORD POINTER 017205  3270          DCA     OUPTR 017206  1271          TAD     OUJMPE 017207  3224          DCA     OUJMP           /3 WAY UNPACK SWITCH 017210  5600          JMP I   OUSETP     F-15  OS/8 INPUT/OUTPUT ROUTINES /OS/8 GENERAL CHARACTER I/O ROUTINES FO   PAL8-VC0  05-OCT-96 PAGE 9 017211  0000  OCHAR,  0                       /OUTPUT CHARACTER ROUTINE 017212  0375          AND     (377            /ISOLATE EIGHT BITS 017213  3266          DCA     OUTEMP 017214  6214          RDF                     /GET FIELD WE WERE CALLED 017215  1374          TAD     (CIF CDF 0      / FROM 017216  3264          DCA     OUCRET 017217  1273          TAD     OUTINH          /OUTPUT INHIBITED 017220  7640          SZA CLA 017221  5263          JMP     OUCOMN          /YES. NOP. 017222  6201  OUCHAR, CDF     OUFLD           /GO TO DATA FIELD OF BUFFER 017223  2224          ISZ     OUJMP           /BUMP CHARACTER SWITCH 017224  7402  OUJMP,  HLT                     /GETS JMP.,JMP.+1,ETC. 017225  5261          JMP     OCHAR1 017226  5256          JMP     OCHAR2 017227  1266  OCHAR3, TAD     OUTEMP          /THIRD CHAR 017230  7106          CLL RTL                 /HIGH ORDER BITS GO INTO THE 017231  7006          RTL                     /HIGH ORDER 4 BITS OF THE 017232  0373          AND     (7400           /FIRST OF TWO WORDS 017233  1667          TAD I   OUPOLD 017234  3667          DCA I   OUPOLD 017235  1266          TAD     OUTEMP          /THE SECOND DOUBLE WORD GETS 017236  7112          CLL RTR                 /THE LOW ORDER BITS OF 017237  7012          RTR                     /THE THIRD CHAR 017240  7010          RAR 017241  0373          AND     (7400 017242  1670          TAD I   OUPTR 017243  3670          DCA I   OUPTR 017244  1271          TAD     OUJMPE          /RESET CHARACTER SWITCH 017245  3224          DCA     OUJMP 017246  2270          ISZ     OUPTR           /POINT TO NEXT BUFFER WORD 017247  2272          ISZ     OUDWCT          /BUMP DOUBLE COUNT AFTER                                              /3 CHARS. 017250  5263          JMP     OUCOMN          /GET OUT 017251  1372          TAD     (OUCTL          /READY TO OUTPUT A BUFFER 017252  4771          JMS I   (OUTDMP         /OUTPUT IT 017253  5264          JMP     OUCRET          /AN ERROR 017254  4200          JMS     OUSETP          /RESET OUTPUT POINTERS 017255  5263          JMP     OUCOMN 017256  1270  OCHAR2, TAD     OUPTR           /POINT TO FIRST DOUBLE WORD 017257  3267          DCA     OUPOLD 017260  2270          ISZ     OUPTR           /POINT OUPTR TO SECOND 017261  1266  OCHAR1, TAD     OUTEMP 017262  3670          DCA I   OUPTR 017263  2211  OUCOMN, ISZ     OCHAR           /NORMAL EXIT 017264  7402  OUCRET, HLT 017265  5611          JMP I   OCHAR 017266  0000  OUTEMP, 0 017267  0000  OUPOLD, 0 017270  0000  OUPTR,  0 017271  5224  OUJMPE, JMP     OUJMP 017272  0000  OUDWCT, 0     F-16  OS/8 INPUT/OUTPUT ROUTINES /OS/8 GENERAL CHARACTER I/O ROUTINES FO   PAL8-VC0  05-OCT-96 PAGE 9-1 017273  0000  OUTINH, 0 017274  0000  OTYPE,  0                       /OTYPE LOOKS AT THE OUTPUT 017275  6214          RDF                     / DEVICE #. 017276  1374          TAD     (CIF CDF 0 017277  3306          DCA     OTRTN 017300  6211          CDF     10 017301  1770          TAD I   (7600           /AND LOOKS UP THE DCB WORD 017302  0367          AND     (17             / FOR THAT DEVICE. 017303  1366          TAD     (DCB-1 017304  3266          DCA     OUTEMP 017305  1666          TAD I   OUTEMP          /GET DCB ENTRY 017306  7402  OTRTN,  HLT 017307  5674          JMP I   OTYPE     F-17  OS/8 INPUT/OUTPUT ROUTINES /OS/8 GENERAL CHARACTER I/O ROUTINES FO   PAL8-VC0  05-OCT-96 PAGE 10 017310  0000  IOPEN,  0                       /INITIALIZE THE INPUT ROUTINE 017311  7240          CLA CMA                 /SET TO FORCE READ FROM NEW 017312  3765          DCA I   (INCHCT         / DEVICE 017313  2764          ISZ I   (INEOF          /FORCE A NEW INPUT FILE. 017314  1363          TAD     (7617           /POINT TO CD INPUT LIST. 017315  3762          DCA I   (INFPTR 017316  6214          RDF 017317  1761          TAD I   (INCDIF 017320  3321          DCA .+1 017321  7402          HLT 017322  5710          JMP I   IOPEN 017361  6632 017362  6722 017363  7617 017364  6721 017365  6725 017366  7757 017367  0017 017370  7600 017371  7046 017372  4200 017373  7400 017374  6203 017375  0377 017376  5000 017377  0200        7400          PAGE     F-18  OS/8 INPUT/OUTPUT ROUTINES /OS/8 GENERAL CHARACTER I/O ROUTINES FO   PAL8-VC0  05-OCT-96 PAGE 11              /              /       EXAMPLE PROGRAM TO COPY A ASCII FILE              /        0001          FIELD 1        2000          *2000 012000  4777          JMS I   (7700           /LOCK MONITOR INTO CORE 012001  0010          10 012002  4776  CALLCD, JMS I   (200            /CALL THE COMMAND DECODER 012003  0005          5 012004  0000          0 012005  4775          JMS I   (IOPEN          /SETUP INPUT POINTERS 012006  4774          JMS I   (OOPEN          /OPEN OUTPUT FILE 012007  7700          SMA CLA                 /ERROR. IF AC<0, IT WAS FATAL 012010  5220          JMP OK                  /NON FILE STRUCTURED OUTPUT 012011  4263          JMS TERR 012012  1720          TEXT /OPEN FAILED/ 012013  0516 012014  4006 012015  0111 012016  1405 012017  0400 012020  4773  OK,     JMS I   (ICHAR          /READ A CHARACTER 012021  5227          JMP     TSTEOF          /ERROR. SEE IF EOF. 012022  7450          SNA                     /IGNORE BLANKS 012023  5220          JMP     OK 012024  4772          JMS I   (OCHAR          /AND OUTPUT THE CHARACTER 012025  5243          JMP     OUTERR 012026  5220          JMP     OK              /CONTINUE UNTIL EOF. 012027  7700  TSTEOF, SMA CLA                 /WAS IT FATAL? 012030  5240          JMP     CLOSE           /NO..EOF. CLOSE OUTPUT 012031  4263          JMS TERR 012032  2205          TEXT /READ ERROR/ 012033  0104 012034  4005 012035  2222 012036  1722 012037  0000 012040  4771  CLOSE,  JMS I   (OCLOSE 012041  5253          JMP     CLERR           /FILE CLOSE FAILED 012042  5202          JMP     CALLCD          /NEW INPUT. 012043  4263  OUTERR, JMS     TERR 012044  1725          TEXT /OUTPUT ERROR/ 012045  2420 012046  2524 012047  4005 012050  2222 012051  1722 012052  0000     F-19  OS/8 INPUT/OUTPUT ROUTINES /OS/8 GENERAL CHARACTER I/O ROUTINES FO   PAL8-VC0  05-OCT-96 PAGE 11-1 012053  4263  CLERR,  JMS     TERR            /CLOSE FAILURE 012054  0314          TEXT /CLOSE FAILED/ 012055  1723 012056  0540 012057  0601 012060  1114 012061  0504 012062  0000 012063  0000  TERR,     0                     /ROUTINE TO PRINT ERROR 012064  1663          TAD I   TERR            / MESSAGES 012065  7012          RTR;RTR;RTR 012066  7012 012067  7012 012070  4275          JMS     TYPIT           /TYPE THE CHARACTER 012071  1663          TAD I   TERR 012072  4275          JMS     TYPIT 012073  2263          ISZ     TERR 012074  5264          JMP     TERR+1 012075  0000  TYPIT,  0 012076  0370          AND     (77             /ISOLATE THE CHARACTER 012077  7450          SNA 012100  5304          JMP     CRLF            /0 TERMINATES IT 012101  1367          TAD     (300 012102  4311          JMS     TTYOUT 012103  5675          JMP I   TYPIT 012104  1366  CRLF,   TAD     (215 012105  4311          JMS     TTYOUT 012106  1365          TAD     (212 012107  4311          JMS     TTYOUT 012110  5202          JMP     CALLCD 012111  0000  TTYOUT, 0 012112  6046          TLS 012113  6041          TSF 012114  5313          JMP       .-1 012115  7200          CLA 012116  5711          JMP I     TTYOUT 012165  0212 012166  0215 012167  0300 012170  0077 012171  7106 012172  7211 012173  6600 012174  7000 012175  7310 012176  0200 012177  7700                      $$$$$$$$$$     F-20  OS/8 INPUT/OUTPUT ROUTINES /OS/8 GENERAL CHARACTER I/O ROUTINES FO   PAL8-VC0  05-OCT-96 PAGE 12 CALLCD 2002      OORETN 7030       CLERR  2053      ORIGIN 6600       CLOSE  2040      OTRTN  7306       CRLF   2104      OTYPE  7274       DCB    7760      OUBLK  7021       EOFERR 6664      OUBUF  5000       FILLIP 7124      OUCCNT 7150       GETNEW 6614      OUCDIV 7075       ICHAR  6600      OUCHAR 7222       ICHAR1 6707      OUCOMN 7263       ICHAR2 6703      OUCRET 7264       ICHAR3 6670      OUCTL  4200       INBREC 6641      OUCTLW 7100       INBUF  5400      OUDEVH 6600       INBUFP 6636      OUDWCT 7272       INCDIF 6632      OUELEN 7022       INCHAR 6605      OUENTR 7016       INCHCT 6725      OUFLD  0000       INCOMN 6710      OUHNDL 7014       INCTL  0200      OUJMP  7224       INCTLW 6635      OUJMPE 7271       INCTR  6724      OUNOWR 7104       INDEVH 7000      OUPOLD 7267       INEOF  6721      OUPTR  7270       INERR  6663      OUREC  7102       INERRX 6660      OUSETP 7200       INFLD  0000      OUTDMP 7046       INFPTR 6722      OUTEMP 7266       INGBUF 6616      OUTERR 2043       INHNDL 6736      OUTINH 7273       INJMP  6665      OU7600 7001       INJMPP 6610      OU7601 7147       INNEWF 6725      PTP    0020       INPTR  6723      TERR   2063       INREC  6637      TSTEOF 2027       INRECS 0001      TTYOUT 2111       INRTRN 6716      TYPIT  2075       IN200  6673       IN7400 6720       IN7600 6601       IOPEN  7310       IORFLD 0001       NODUMP 7144       OCHAR  7211       OCHAR1 7261       OCHAR2 7256       OCHAR3 7227       OCISZ  7152       OCLOSE 7106       OCRET  7153       OEFAIL 7032       OK     2020           F-21  OS/8 INPUT/OUTPUT ROUTINES ONOFIL 7044       ONTERR 7042       OOPEN  7000       ERRORS DETECTED: 0 LINKS GENERATED: 0     F-22     INDEX     Additional information words,  CLOSE function, 2-8, D-10 1-3, 2-7, D-10  Code, non-paged, D-11     Alphanumeric option, Command  Command Decoder Decoder, 3-3  calling, 3-3       switches, 3-6    conventions, 3-1     ALTMODE key, 3-3    error messages, 3-3     Ascertain device information    errors summary, C-7 (INQUIRE function), 2-14    example, 3-7     ASCII character codes, E-3, E-4    options, 3-3     ASCII files format, A-4    output files, 3-5     ASSIGN command, 1-6    special mode, 3-10     Asterisk, caution in using, 3-9    tables, 3-4  COMMON area, 2-12  Control characters, OS/8, E-1     Batch mode, 3-11  Conventions     Batch operating system, 1-6    Command Decoder, 3-1     Binary file format, A-4    OS/8, E-1     Block, core control, 1-4  Core control block, 1-4, 2-11, A-5     Blocks  Core image files (.SV format), A-5       directory, A-1  Core origin, A-7       system scratch, B-1  Core segment doublewords, A-7     Blocks of words, 1-2, 1-3  Core size, PDP-8 computers, D-5     BUILD program, 5-1    software, 1-6  Co-resident device handlers, 2-6  Creating files, 1-3     Call Command Decoder (DECODE function), 2-10, 3-3       in Special Mode, 3-9  Data exchange in core, 2-12     Calling device handlers, 4-1  Data field value, 2-2     Calling USR and device handlers  Data transfer, 4-1, 4-2 from SABR code, D-13  DATE command, 1-4, 2-7     Card codes, DEC029, 4-8  DECODE function, 2-10     Card Reader (CDR) operation, 4-8  DECtape operation, 4-1     Card Reader handler modification,  Default file storage device, DSK, D-2      D-1     Carriage return/line feed sup-  Deleting tentative files, 2-16 pression in FORTRAN, D-4  Device control word table, B-7     Cassettes operation, 4-7  Device dependent operations, 4-4     CCL, 3-10  Device handler     CCL error messages, C-4    entry point, 2-15, 5-8     CHAIN function, 2-11    information table, B-6     Character codes    residency table, 2-15, B-6       ASCII, E-3, E-4  Device handlers       OS/8, E-1    device dependent operations, 4-4     Character mode, expanded, 4-6      Card Reader (CDR), 4-8     Character packing format, 5-8      Cassettes operation, 4-7     Characters, lower case, E-1      High-Speed Paper Tape Punch     Circumflex (^) character, 4-5 (PTP), 4-5    INDEX 1     INDEX     Device handlers (Cont.)  FETCH device handler function, High-Speed Paper Tape Reader      2-4, 4-1   (PTR), 4-4  File creation, 1-3       file structured devices oper-  File directories, A-1   ation, 4-12  block format, A-1 TD8E DECtape, 4-12    entries, A-2 TM8E Magtape, 4-8    example, A-4     Device handlers, 1-1    formats, A-4       calling, 4-1    number, A-3       co-resident, 2-6    size, A-3       inserting into OS/8, 5-5  File extension, omission of, 3-2       loading dynamically, D-8  File length restriction, Command       notes on loading, D-7      Decoder, 3-6       writing, 5-1  FILENAME pseudo-op, 1-7     Device length table, B-8  Files, 1-2     Device names and numbers, 1-6    additional information words, 1-3     DEVICE pseudo-op, 1-7    devices, 1-2     Devices, file structured, 1-2    directories, 1-3     DF32 disk operation, 4-12    names, 1-2     Direct calling sequence, USR, 2-2  types, 1-3     Directories, file, 1-3  File structured devices operation,     Directory block structure format,      4-12 A-1  Formats for     Directory entries, A-2    character packing, 5-3     Directory example, A-4    command line, 3-1     Directory segment, rewriting,    directory block structure, A-1 D-10    files, A-4     Directory, system, 5-2    FORTRAN Library File, A-8     Dismiss USR from core, 2-13    input file, 3-2     Dot (.) used as system response,    Job Status Word, A-6 1-6  Form feed, 4-6     Doublewords, core segment, A-7       FORTRAN Library File Format, A-8  Functions, USR see USR functions     Empty file entry, A-2     Empty files, 1-3  High-Speed Paper Tape Punch (PTP)     End-of-file card, 4-8      operation, 4-5     End-of-file Condition, 4-2, 4-4  High-Speed Paper Tape Reader (PTR)     ENTER output (tentative) file      operation, 4-4 function, 2-7, D-9  Horizontal tab, 4-6     Entry points for device handlers, 5-2     ERROR function, 2-12  Indirect calling sequence, USR,     Error messages, Command Decoder,      2-2 3-3  Information words, additional, 1-3,     Error messages summary, C-1      2-7     Error returns, device handler,    accessing, D-10 4-2  Input file format, 3-2     Exit to Keyboard Monitor, 1-1  Input files, Command Decoder, 3-5     Expanded character mode, 4-6  Input/output routines, F-1     Extensions of file names, 1-2  Input table, Command Decoder, 3-9  INQUIRE function, 2-14  Inserting device handlers into      OS/8, 5-5    INDEX-2     INDEX     Job Status Word, 1-5, A-6  Records (definition), 4-1    outputting odd number of, 4-3  RESET system table, 2-15     Keyboard Monitor, 1-1  Resident program layout, B-3       error summary, C-3  RESORC, B-9     KL8E terminal handler, 4-13  Restrictions to USR calls, 2-2  RETURN key, 3-3  RF08 disk     LAP pseudo-op, D-11    operation, 4-12     Layouts for OS/8 system, B-1  RK8E handlers, 4-12     LINCtape operation, 4-12  ROM (Read-Only-Memory), B-4     Line Printer (LPT) operation, 4-5, 4-6     Load and start subprogram, 2-11  SABR programming notes, D-11     Loading device handlers dynam-  SAVE command, 1-4, 2-12 ically, D-8  Scratch blocks, B-1, B-2     Lock USR in core (USRIN), 2-13  Signal user ERROR function, 2-12     Logical blocks, 1-2  Size of OS files, A-3     LOOKUP permanent file function,  Software components, 1-1 2-6, D-9  Software core size, 1-6     Lower case characters, E-1  Special mode of Command Decoder,      3-10    calling, 3-9     Names of devices, 1-6    operation, 3-9     Names of files, 1-2  Standard USR call, 2-1     Number and size of OS files, A-3    restrictions, 2-2     Numbers of devices, 1-6  START command, 1-5     Numeric option, Command Decoder,  Starting address of program, 1-5 3-3  Storage space, additional, D-9  Storage words, 1-3  Subroutine     ODT breakpoint, 2-12    examples, F-4     Operations, device dependent, 4-4    functions, F-1, F-2     Options    listing, F-5       Command decoder, 3-3, 3-6    parameters, F-3     Origin of core, A-7  Summary of USR functions, see USR     Output files, Command Decoder,      functions 3-5  .SV file, 1-4  System DATE, 2-7  System device layout, B-1     PAGE pseudo-op, D-11  System devices, 1-6     Permanent device name table, B-5     System device table, B-5     Permanent file, 1-3  System halts error messages       deletion, 2-8, 2-9      summary, C-1       entry, A-2  System table values, Command     Physical blocks, 1-2      Decoder, 3-7     PIP, 3-6     Program, see specific subject     Programming notes, D-1  Tables     PRTC12-F used to convert DECtapes    Command Decoder, 3-4 to LINCtapes, D-6    device control word, B-7     Pseudo-ops    device handler information, B-6       DEVICE, 1-7    device handler residency, B-6       FILENAME, 1-7    device length, B-8     Punch card codes, DEC026, D-3    INDEX-3     INDEX     Tables (Cont.)       permanent device name, B-5       system device, B-5       user device name, B-6     TD8E DECtape       operation, 4-12     Teletype operation, 4-4     Tentative files, 1-3       closing, 2-8       deletion, 2-8       entry, A-3     Terminal handlers       1-page, 4-4       2-page, 4-13     up arrow (^) character, 4-5     User device name table, B-6     User Service Routine (USR), 1-1, 2-1       available location in area,   D-9       calling, 1-6, 2-1       calling sequences, 2-2       errors summary, C-2       restrictions on standard call, 2-2     USR functions       CHAIN, 2-11       CLOSE, 2-8       DECODE, 2-10       ENTER, 2-7       ERROR, 2-12       FETCH, 2-4       INQUIRE, 2-14       LOOKUP, 2-6       RESET, 2-15       summary, 2-3       USRIN, 2-13       USROUT, 2-13     Vertical tab, 4-6     Wrap around memory, 4-3     Writing device handlers, 5-1     Word blocks, 1-2    INDEX 4      HOW TO OBTAIN SOFTWARE INFORMATION    SOFTWARE NEWSLETTERS, MAILING LIST    __________________________________    The Software Communications Group, located at corporate headquarters in    Maynard, publishes newsletters and Software Performance Summaries (SPS)    for the various Digital products.  Newsletters are published monthly,       ___________    and contain announcements of new and revised software, programming    notes, software problems and solutions, and documentation corrections.    Software Performance Summaries are a collection of existing problems    ______________________________    and solutions for a given software system, and are published periodi-    cally.  For information on the distribution of these documents and how    to get on the software newsletter mailing list, write to:    Software Communications    P. O. Box F    Maynard, Massachusetts  01754    SOFTWARE PROBLEMS    _________________    Questions or problems relating to Digital's software should be reported    to a Software Support Specialist.  A specialist is located in each    Digital Sales Office in the United States.  In Europe, software problem    reporting centers are in the following cities.   Reading, England   Milan, Italy   Paris, France   Solna, Sweden   The Hague, Holland      Geneva, Switzerland   Tel Aviv, Israel   Munich, West Germany    Software Problem Report (SPR) forms are available from the specialists    or from the Software Distribution Centers cited below.    PROGRAMS AND MANUALS    ____________________    Software and manuals should be ordered by title and order number.  In    the United States, send orders to the nearest distribution center. Digital Equipment Corporation     Digital Equipment Corporation Software Distribution Center      Software Distribution Center 146 Main Street   1400 Terra Bella Maynard, Massachusetts  01754     Mountain View, California  94043    Outside of the United States, orders should be directed to the nearest    Digital Field Sales Office or representative.    USERS SOCIETY    _____________    DECUS, Digital Equipment Computer Users Society, maintains a user ex-    change center for user-written programs and technical application in-    formation.  A catalog of existing programs is available.  The society    publishes a periodical, DECUSCOPE, and holds technical seminars in the    United States, Canada, Europet and Australia.  For information on the    society and membership application forms, write to: DECUS   DECUS Digital Equipment Corporation     Digital Equipment, S.A. 146 Main Street   81 Route de l'Aire Maynard, Massachusetts 01754      1211 Geneva 26   Switzerland       OS/8 Software Support Manual       DEC-S8-OSSMB-A-D       READER'S COMMENTS  NOTE:  This form is for document comments only.  Problems with software should be reported on a Software Problem Report (SPR) form (see the E10A' TO OBTAIN SOFTWARE INFORMATION page).     Did you find errors in this manual?  If so, specify by page.     ______________________________________________________________________     ______________________________________________________________________     ______________________________________________________________________     ______________________________________________________________________     ______________________________________________________________________    Did you find this manual understandable, usable, and well-organized?    Please make suggestions for improvement.    ______________________________________________________________________    ______________________________________________________________________    ______________________________________________________________________    ______________________________________________________________________    ______________________________________________________________________    Is there sufficient documentation on associated system programs    required for use of the software described in this manual?  If not,    what material is missing and where should it be placed?    ______________________________________________________________________    ______________________________________________________________________    ______________________________________________________________________    ______________________________________________________________________    ______________________________________________________________________    Please indicate the type of user/reader that you most nearly represent. []  Assembly language programmer []  Higher-level language programmer []  Occasional programmer (experienced) []  User with little programming experience []  Student programmer []  Non-programmer interested in computer concepts and capabilities     Name______________________________________Date________________________     Organization__________________________________________________________     Street________________________________________________________________     City__________________________State_____________Zip Code______________ or     Country     If you do not require a written reply, please check here.  []     -------------------------------Fold Here------------------------------     -----------------Do Not Tear - Fold Here and Staple-------------------  +---------------+  |  FIRST CLASS  |  | PERMlT NO. 33 |  | MAYNARD. MASS.|  +---------------+ BUSINESS REPLY MAIL   ======== NO POSTAGE STAMP NECESSARY IF MAILED IN THE UNITED STATES  ========     ====================================================================== Postage will be paid by:   ========   ========  +-+-+-+-+-+-+-+   ========  |d|i|g|i|t|a|l|   ========  +-+-+-+-+-+-+-+   ========   ========      Software Communications   ========      P. O. Box F   ========      Maynard, Massachusetts  01754   ========

Back to content | Back to main menu