SPECIAL PURPOSE SUBROUTINES FOR OS/8 FORTRAN IV This is a collection of subroutines written to extend the capabilities of D.E.C.'s FORTRAN IV for the PDP-8 and PDP-12. Most of the subroutines will run on either PDP-8 or PDP-12 systems with or without a hardware FPP. A few are obviously unique to the PDP-12 because they use devices such as the LINCtape or LINCscope. These routines were written by: Robert W. Phelps Dept. of Rad. Biol. Biophysics University of Rochester Medical Center Rochester,NY 14642 This write up was adapted for DECUS submission by: Bob Hassinger Liberty Mutual Research Center 71 Frankland Road Hopkinton, Mass. 01748 Subroutines included in this collection are: USR Subroutine to allow run-time declaration of files. MODE8 Subroutine to call 8-mode subroutines from FORTRAN. READB2 Subroutines READB and WRITEB to read and write binary (12 bit) data in OS/8 files and RLINK to read DIAL format LINCtapes. IOT Subroutine to issue an 8-mode IOT. TV Allows display of text on PDP-12 scope as a background task. NULL Used with TV for scope oriented teletype input. XYPLOT Modified version of DEC's CALCOMP routines. Allows plot data to be written in a file for later plotting or viewing. PLOTIT Subroutine to read a file produced with XYPLOT and produce the plot on a CALCOMP type plotter as a backgrond task. PREVU Subroutine to display the data in a file produced by XYPLOT on a storage scope. FMTX Experimental 'FORTRAN Multi-Tasking Executive'. Documentation is included in the file FMTX.WR. PAGE 2 USR --- This routine allows run-time declaration of files in D.E.C. OS/8 FORTRAN IV. Description of parameters: SUBROUTINE USR (UNIT, NAME, FUNCT, ERROR) UNIT - Logical unit number. Only numbers 5 thru 9 are allowed. Fewer logical units may be allowed depending on core availability -- see programming note below. NAME - dev:file.ex stored in 3A6 format or equivalent. Device assumed to be DSK: if not explicitly stated. This parameter may also be a Hollerith literal. Null characters ('@') and spaces are ignored in this field. FUNCT - Function: 2 - open file for input 3 - open file for output 4 - close output file The output file name given for a CLOSE must agree with the corresponding OPEN file name for that unit. Closing a file with 0 blocks or an input (FUNCT=2) file will delete that file name from the directory. ERROR - Return error condition: 0 - no errors. 1 - illegal device 2 - illegal file name 3 - illegal unit number (core exceeded!?) 4 - illegal function code User errors may terminate execution unless the /E option was specified to FRTS. The following user errors from USR are defined: 0002 - The user has defined a non-resident device handler external to USR. PROGRAMMING NOTE: Each unit is assigned 1000(8) locations in the highest field for buffer and handler (400 for its buffer and 400 for its handler). These locations are not dynamically allocated but are used for device buffer and handlers only if they are not used by the program. To use core most efficiently for large programs, use the highest order unit numbers possible. That is, using unit 5 allows 1000(8) fewer words for source code than if unit 6 were the lowest unit number used. PAGE 3 RESTRICTIONS: Because FRTS loads non-resident handlers from the top of core down, and USR also uses that area, the user is not allowed to make load time I/O unit declarations to devices with non-resident handlers external to USR. To do so will cause a fatal USER ERROR 2. It is recommended, and generally more convienent to use internal handlers and declare all other files at execution time with calls to this subroutine. The use of FRTS internal handlers, SYS:, and devices co-resident with SYS: are legal, even if defined external to this subroutine. EXAMPLES: 1. Define unit 9 to be the existing file NEW.DA on device DSK: CALL USR (9, 'NEW.DA', 2, ERROR) 2. Define unit 8 to be the existing file JUNK.TX on device LTA0: CALL USR (8, 'LTA0:JUNK.TX', 2, ERROR) 3. Read the name of a file from the keyboard terminal (unit 4), (if no device is included in the input statement, DSK:' is assumed). Open the file for output. When the program is done, close the file. DIMENSION NAME(3) READ (4, 100) NAME 100 FORMAT (3A6) CALL USR (7, NAME, 3, ERROR) CALL USR (7, NAME, 4, ERROR) GETTING 'USR' ON THE AIR: USR is written in RALF language and can be included in the FORTRAN IV library. The following commands will assemble the program and include it in the user's FORTRAN IV library: .R RALF /Run the RALF assembler *USR CALL MODE8 (,,, ... ) A maximum of six arguments are allowed and arguments not used may be omitted. Thus the simplest call is: EXTERNAL CALL MODE8 () If arguments are passed, they are truncated to integer values between 0 and 4095. The values of the arguments are passed in both directions just as in any other FORTRAN subroutine, however, arrays may NOT be passed. 8-mode code must be assembled by RALF and must be completely page relocatable. The subroutine is effectively called by the following code: CDF CIF JMS . . . A sample program is included in the source of MODE8. Insert MODE8 in your FORTRAN library in the same way shown for USR. PAGE 6 READB,WRITEB and RLINK ---------------------- File READB2 contains the subroutines READB,WRITEB and RLINK as a single RALF module. READB and WRITEB allow reading/writing binary files in FORTRAN. The calling sequence is: DIMENSION BUFR(256) CALL READB (UNIT, BUFR) or CALL WRITEB (UNIT, BUFR) This reads/writes the next block of 256 12-bit binary words from/to logical unit number UNIT into/from the 256 element array BUFR. The values read/written are between 0 and 4095. These routines will not read past an end of file. To check for end of file, code the following: EXTERNAL EOF LOGICAL EOF IF (EOF) GO TO 900 . . 900 RLINK allows a PDP-12 to read single LINCtape blocks into a 256 element array. The calling sequence is: DIMENSION BUFFER (256) CALL RLINK (BLOCK, BUFFER ) Integer values between 0 and 4095 are read from block BLOCK and are returned as elements of array BUFFE. The patch described in the USR writeup must be included in FRTS so RLINK can determine the highest field of core for a data buffer. Unpredictable results may occur if more than one device with a non-resident handler is used without using USR to open the files. To insert READB,WRITEB and RLINK in your FORTRAN IV library assemble and insert the file READB2 in the same way as shown for USR. PAGE 7 IOT --- Subroutine IOT allows 8-mode IOT's to be issued. The calling sequence is: CALL IOT (INST, AC) INST is the 8-mode IOT instruction (note: the octal code must be converted to a decimal value for use here). When IOT is called, AC contains the value that is to be in the accumulator when the IOT is issued. If the execution of the IOT changes the contents of the accumulator, the new value is returned. This feature may be used to read the switch regester if the 8-mode instruction LAS is issued in place of an IOT. Insert IOT in your FORTRAN library in the same way shown for USR. PAGE 8 TV,TVIN and NULL ---------------- Subroutine TV allows ASCII (i.e. formatted) information to be displayed on the PDP-12 scope in the background when executing FORTRAN programs. The routine is designed for more rapid interaction with users than is possible using the teletype as an output device. The calling sequence is: EXTERNAL TV CALL MODE8 (TV, UNIT) Where UNIT is the logical unit number used to output the ASCII data (this logical unit is usually designated to output to NULL:). TV will display the current contents of the OS/8 buffer associated with this logical unit on the scope. The FORTRAN command BACKSPACE will allow overwriting a line and the command REWIND will erase the screen. (Note: logical unit UNIT must be associated with an OS/8 device handler which will have an OS/8 I/O buffer associated with it rather than one of the internal drivers for units 1 thru 4 because they do not have OS/8 I/O buffers - if this handler is other than NULL: the data output to the scope will also be output to that device (and file) in the usual way). TVIN is an OS/8 device handler designed to make possible input from the keyboard using the PDP-12's scope to display the typed line. To use TVIN, the NULL handler (which is co-resident with TVIN) must be used as the output device associated with the TV display and the buffers for both NULL and TVIN must be in the same field. (This will be the case if USR was used to open these logical units.) All standard formatted read commands are allowed, e.g. READ (7, 100) I 100 FORMAT (I5) where 7 is the unit number associated with TVIN. A device error is printed if NULL does not exist or if the buffer fields of NULL and TVIN are different. TVIN can only be used under OS/8 FORTRAN IV. The NULL and TVIN device handlers may be inserted in your system with the following commands: .R PAL8 *NULL