---------- XLIB8 Fortran Library Documentation (XLIB8.TS) ----------- Date of last documentation change - 23-FEB-82 This document describes routines contained in XLIB8.RL This library replaces LIB8.RL, which is no longer accessed by the loaders in the systems on HRL disks. All LIB8.RL routines are in XLIB8.RL with the exception of the I/O routines. New routines have been developed for enhanced assigned unit I/O capability and are described in this document and in the FORT.TS documentation member. Some entry point names that appear in the LIBCAT output for XLIB8.RL are not described here because they are internal routines that are a part of the SABR run-time operating system and are referenced by the Fortran Compiler. The average user will never directly reference those routines in Fortran source code. Some routines are part of the standard FORTRAN II library, and are described in the FORTRAN II section of the OS/8 LANGUAGE REFERENCE MANUAL. The sources for these routines are located on diskette RX8-220 in the FORT box. The source for this document is on diskette RX8-96 in the INFO box. FR = ABS (FVAL) (See OS/8 LANGUAGE REFERENCE) FR = ALOG (FVAL) (See OS/8 LANGUAGE REFERENCE) FR = ATAN (FVAL) (See OS/8 LANGUAGE REFERENCE) CALL CHAIN (FNAME) CALL CHRIO (IUNIT,IVAL) CALL CKIO CALL CLOSB (IUNIT) CALL CLOSE (IUNIT) FR = COS (FVAL) (See OS/8 LANGUAGE REFERENCE) FR = EXP (FVAL) (See OS/8 LANGUAGE REFERENCE) CALL EXIT CALL FIXIO (IMODE) -or- CALL FIXIO (IKDEV,IPDEV) FR = FLOAT (IVAL) (See OS/8 LANGUAGE REFERENCE) IR = IABS (IVAL) (See OS/8 LANGUAGE REFERENCE) 1 ---------- XLIB8 Fortran Library Documentation (XLIB8.TS) ----------- IR = IFIX (FVAL) (See OS/8 LANGUAGE REFERENCE) CALL IOH (ITEM) IR = IOHST (IUNIT) IR = IRDSW (DUMMY) (See OS/8 LANGUAGE REFERENCE) IR = IREM (IVAL) (See OS/8 LANGUAGE REFERENCE) CALL KEY (IVAL) CALL OPEN CALL OPENI (IUNIT,DNAME,FNAME,EXTEN) CALL OPENO (IUNIT,DNAME,FNAME,EXTEN) CALL READ (IUNIT,FORMT) CALL READB (IUNIT,LNGTH,BUFF) CALL RESET (IUNIT,IMODE) FR = SIN (FVAL) (See OS/8 LANGUAGE REFERENCE) FR = SQRT (FVAL) (See OS/8 LANGUAGE REFERENCE) FR = TAN (FVAL) (See OS/8 LANGUAGE REFERENCE) CALL WRITB (IUNIT,LNGTH,BUFF) CALL WRITE (IUNIT,FORMT) ----------------------------------------------------------------------- 2 ---------- XLIB8 Fortran Library Documentation (XLIB8.TS) ----------- CHAIN Subroutine Source: UNITIO.SB Date: 06-DEC-81 CALL CHAIN (FNAME) FNAME : File name in 3A2 format zero or space filled. CHAIN looks up the file with a .SV extension on the SYS device, calls the CKIO routine to wait for any uncompleted output, and chains to the file. ERROR MESSAGES: CHNA : ?CHAIN FILE NOT AVAILABLE ON SYS:? CHRIO Subroutine Source: CHRIO.SB Date: 13-APR-78 CALL CHRIO (IUNIT,IVAL) IUNIT : FORTRAN I/O unit number (1-5). IVAL : 8-bit character. Performs one character of I/O on the specified device according to the sign of IUNIT. If IUNIT is positive, IVAL is written to the device. If IUNIT is negative, the unit number is the absolute value of IUNIT, and a character is read from the unit and returned in IVAL. The parity bit is always set. The FORTRAN single character constants (e.g. "A") are the same value as the characters returned by CHRIO. CKIO Subroutine Source: UTILTY.SB Date: 11-FEB-82 CALL CKIO CKIO checks for any outstanding output operations on FORTRAN units 1 and 3, and waits for their completion before returning. This routine is called from the EXIT and CHAIN routines. CLOSB Subroutine Source: UNITIO.SB Date: 18-JAN-78 CALL CLOSB (IUNIT) IUNIT : FORTRAN I/O unit number (4-5). CLOSB does the same operations as CLOSE, except that instead of writing at least one control Z then padding any remainder, CLOSB will only pad the current buffer with 0's if it is not full (i.e. it won't force any end-of-file marker). 3 ---------- XLIB8 Fortran Library Documentation (XLIB8.TS) ----------- CLOSE Subroutine Source: UNITIO.SB Date: 18-JAN-78 CALL CLOSE (IUNIT) IUNIT : FORTRAN I/O unit number (4-5). CLOSE finishes writing the output file and makes the tentative output file permanent. If the unit is not currently write-enabled no operations are done on the file. If nothing had been written to the file and a CLOSE call is made, no new file will be created and any existing file of the same name will be deleted. After a close operation, a RESET can be done to re-access the file. Closing a new tentative file ---------------------------- When the file had been created via an OPENO call and has been written to, the following sequence occurs when CLOSE is called: ** At least one control Z (end of file marker) is written into the current buffer. If the buffer is not yet full, the remainder is padded with control Z's. ** The last buffer is written to the file. ** File length is reduced down to final closed length. ** A permanent directory entry is made for the file. ** Status code is set to 9, access mode is unchanged. Closing a rewritten existing file --------------------------------- When the file had been opened via an OPENI call then RESET to be a write-only or write and read file and has been accessed, the following sequence of steps occur. ** The current buffer is re-written to the file. ** Status code is set to 9, access mode is unchanged. EXIT Subroutine Source: UTILTY.SB Date: 11-FEB-82 CALL EXIT EXIT calls the CKIO routine to wait for any uncompleted output, and then exits from FORTRAN back into OS/8. 4 ---------- XLIB8 Fortran Library Documentation (XLIB8.TS) ----------- FIXIO Subroutine Source: UTILTY.SB Date: 11-FEB-82 CALL FIXIO (IMODE) or CALL FIXIO (IKDEV,IPDEV) IMODE : Mode of unit #1 operation. IKDEV : Change IOT device number for keyboard (unit #1 input). IPDEV : Change IOT device number for printer (unit #1 output). Modifies unit #1 I/O parameters. Parameter meaning depends on number of parameters present. CALL FIXIO has no effect. CALL FIXIO (IMODE) has effect described below. CALL FIXIO (IKDEV,IPDEV) changes IOT codes. IMODE Action ----- ------ <0 Absolute value of IMODE is mask of options: Bits 0-8: unused Bit 9: Inhibit input from Batch. Bit 10: Console is in TTY mode. Bit 11: Console is in CRT mode. (Both 10 and 11 set immediate mode) 0 Set prompt sequence to null string. >0 Set new prompt sequence. IMODE is an array of 8-bit characters ended with a word of 0. (The initial prompt is "->"). If console is set to TTY mode, a delete during input will be echoed as a backslash character. If console is set to CRT mode, a delete during input will be echoed as a backspace-space-backspace, which erases the previous character from the screen. If console is set to immediate mode, no buffering or editting is allowed, and each character is immediately passed on. This is the way the original FORTRAN system provided by DEC worked. Examples of FIXIO(IMODE) calls: CALL FIXIO(-1) Sets CRT mode and allows Batch input. CALL FIXIO(-3) Sets immediate mode and allows Batch input. CALL FIXIO(-5) Sets CRT mode and inhibits Batch input. CALL FIXIO(-7) Sets immediate mode and inhibits Batch input. See the FORT.TS documentation member for more information on unit #1 options. IOH Subroutine Source: IOH.SB Date: 18-AUG-81 CALL IOH (ITEM) ITEM : Integer, real, or text item to read or write. 5 ---------- XLIB8 Fortran Library Documentation (XLIB8.TS) ----------- Calls to IOH are generated automatically by the FORT compiler for each value encountered on a WRITE or READ statement. However, the user may control the IOH calls by leaving a trailing comma on the WRITE or READ statement, or by CALLing WRITE or READ with the format statement text in an array, and then CALLing IOH instead of letting FORT do it. See the READ and WRITE subroutine descriptions. IOHST Function Source: UNITIO.SB Date: 18-JAN-78 ISTAT = IOHST (IUNIT) IUNIT : FORTRAN I/O unit number (4-5). ISTAT : Status code. The IOHST function is used to determine whether an operation has succeeded or failed. The value that is returned is a state indicator that is used to determine the next operation. This state (status code) is 0 when no operations are currently possible (e.g. no file opened, already past end-of-file, etc.). It is non-zero when operations are allowed on the unit. Each value has a specific meaning, but for purposes of error checking, only a greater than zero value need be checked for success. The values returned are: -1 Unit has not been set up to have a valid UPP (Unit Parameter Packet). Any access to this unit by any other unit subroutines will result in program aborts. This value is returned for unit 4 if the /I option was not used at load time, or for unit 5 if the /O option was not used at load time. =0 No operations are currently allowed. This may be due to the last operation having failed for some reason (e.g. file not found, read/write past end-of-file, etc.). >0 Last operation was successful. More operations are allowed. KEY Subroutine Source: KEY.FT Date: 09-DEC-81 CALL KEY (IVAL) IVAL : Character returned from unit 1. KEY reads a single character from unit 1 without buffering. It consists of the following statements: CALL FIXIO(-3) CALL CHRIO(-1,IVAL) CALL FIXIO(-1) 6 ---------- XLIB8 Fortran Library Documentation (XLIB8.TS) ----------- OPEN Subroutine Source: UTILTY.SB Date: 11-FEB-82 CALL OPEN OPEN initializes the FORTRAN I/O units for operation. This includes resetting any software flags and buffer pointers that need to be reset, and initializing the hardware by sending null characters out to the console, paper tape punch, and line printer. OPENI Subroutine Source: UNITIO.SB Date: 18-JAN-78 CALL OPENI (IUNIT,DNAME,FNAME,EXTEN) IUNIT : FORTRAN I/O unit number (4-5). DNAME : Device name in 2A2 format zero or space filled. FNAME : File name in 3A2 format zero or space filled. EXTEN : File name extension in 1A2 format zero or space filled. The handler for the device is loaded and a lookup is performed for the file with the given name and extension. A failure in either of these operations is not fatal but sets both the status code and the access mode to 0. If the lookup is successful the status will be 1 and the access mode will be 2 (read-only). When an existing file is opened, IOHST should be called to verify that the lookup operation was successful before continuing with I/O operations on that unit. Any I/O operations attempted while the status is zero is a fatal error causing the program to abort. An existing file may be re-written in place by opening the existing file for input and then calling RESET to set the mode to 1 (write-only) or 3 (read-write) on that unit. OPENO Subroutine Source: UNITIO.SB Date: 18-JAN-78 CALL OPENO (IUNIT,DNAME,FNAME,EXTEN) IUNIT : FORTRAN I/O unit number (4-5). DNAME : Device name in 2A2 format zero or space filled. FNAME : File name in 3A2 format zero or space filled. EXTEN : File name extension in 1A2 format zero or space filled. The handler for the device is loaded, and an enter (create tentative output file) is performed for a file with the given name and extension. A failure in either of these operations is not fatal but sets both the status code and the access mode to 0. If the enter is successfu the status code will be 1 and the access mode will be 1 (write-only). 7 ---------- XLIB8 Fortran Library Documentation (XLIB8.TS) ----------- When a tentative output file is opened, IOHST should be called to verify that the enter operation was successful before continuing with I/O operations on that unit. Any I/O operations attempted while the status is zero is a fatal error causing the program to abort. READ Subroutine Source: IOH.SB Date: 18-JAN-78 CALL READ (IUNIT,FORMT) IUNIT : Fortran I/O unit number (1-5). FORMT : Array containing format statement text. Calls to the READ subroutine are generated by FORT when READ statements are encountered. If the user wants to use a format statement that is in an array, a direct call to READ can be used to pass the format text, followed by calls to IOH to handle any numbers or strings. The FINI statement should be used to finish out the I/O processing for the READ. READB Subroutine Source: UNITIO.SB Date: 18-JAN-78 CALL READB (IUNIT,LNGTH,BUFF) IUNIT : FORTRAN I/O unit number (4-5). LNGTH : Length of buffer in words. BUFF : Address of buffer. This subroutine will read LNGTH words from the file being accessed via unit IUNIT into BUFF. BUFF can be a subscripted array address. If an attempt is made to read past the end-of-file the status code is set to zero and the remaining words in the buffer are not changed. The subroutine then returns and the user should check the status code by calling IOHST. If READB is called when the access mode is write-only or when the status code or access mode is zero a fatal abort occurs. RESET Subroutine Source: UNITIO.SB Date: 18-JAN-78 CALL RESET (IUNIT,IMODE) IUNIT : FORTRAN I/O unit number (4-5). IMODE : Mode of reset to be performed. RESET performs a reset (rewind) on the unit and can also change the access mode for that unit: 8 ---------- XLIB8 Fortran Library Documentation (XLIB8.TS) ----------- IMODE Operation ----- --------- -1 Delete the file and set status code to 0. 0 Reset pointers. Do not change access mode. 1 Reset pointers and enable file for writing only. 2 Reset pointers and enable file for reading only. 3 Reset pointers and enable file for writing and reading. The status code of a unit can be zero when the RESET function is called. However, if the access mode is being changed (IMODE=1, 2, or 3) there has to be a valid access mode already present (read, write, or both). This enables RESET to be called after detection of end-of-file, but will disallow opening up an undefined area for access (e.g. after a file had been deleted). An unsuccessful OPENI or OPENO operation sets the access mode to zero (none allowed), and any attempt to follow that with a RESET will result in a fatal error and the program will abort. The RESET function can be used to: ** Verify the presence of the packets and buffers needed for that unit (see LOADER /I and /O options). A soft check can be made with IOHST, and the program can print an error message. But if you just wants to make sure that packets and buffers are allocated properly and abort if not, a call to RESET with a IMODE of 0 will fatal abort if the unit is undefined and will be a null reset operation otherwise. ** Reset the file pointers back to beginning-of-file without having to do another explicit OPENI or OPENO call. On output, this can be done without doing a close operation, but the last buffer of data will not be written. To re-read a file that was just written and closed, calling RESET with a mode of 2 (read-only) will effectively write-protect the file while resetting the file pointers. ** Reset the file pointers back to beginning-of-file and enable both reads and writes on an existing file. (This works only with binary I/O) This method may be used to rewrite data in place without having to explicitly copy a file to a new file. The way that simultaneous read/write access was implemented is that when the file pointer moves to the next block, the old block (if any) is re-written and the new block (if any) is read into the buffer to become the current block. This allows rewriting of even just a single word by reading out to the word, writing the single word, and continuing on to eventually flush the buffer with a CLOSB. ** Delete an existing file. After first doing an OPENI for the file a RESET(IUNIT,-1) will delete that file if it exists. The status code and access mode are both unconditionally set to zero after the 9 ---------- XLIB8 Fortran Library Documentation (XLIB8.TS) ----------- operation to prevent further access to the file. Therefore, an IOHST call is not neccessary (and is useless) to check the success or failure of a RESET(IUNIT,-1) call. WRITB Subroutine Source: UNITIO.SB Date: 18-JAN-78 CALL WRITB (IUNIT,LNGTH,BUFF) IUNIT : FORTRAN I/O unit number (4-5). LNGTH : Length of buffer in words. BUFF : Address of buffer. This subroutine will write LNGTH words from BUFF to the file being accessed via unit IUNIT from BUFF. BUFF can be a subscripted array address. If an attempt is made to write past end-of-file, the status code is set to zero and the remaining words in the buffer are skipped. The subroutine then returns and the user should check the status code by calling IOHST. If WRITB is called when the access mode is read-only or when the status code or access mode is zero, a fatal abort occurs. WRITE Subroutine Source: IOH.SB Date: 18-JAN-78 CALL WRITE (IUNIT,FORMT) IUNIT : Fortran I/O unit number (1-5). FORMT : Array containing format statement text. Calls to the WRITE subroutine are generated by FORT when WRITE statements are encountered. If the user wants to use a format statement that is in an array, a direct call to WRITE can be used to pass the format text, followed by calls to IOH to handle any numbers or strings. The FINI statement should be used to finish out the I/O processing for the WRITE. 10