---------- Hearing Research Lab FORTRAN User Guide (FORT.TS) ---------- H H RRRR L H H R R L HHHHH RRRR L H H R R L H H R R LLLLL FFFFF OOO RRRR TTTTT RRRR AAA N N F O O R R T R R A A NN N FFF O O RRRR T RRRR AAAAA N N N F O O R R T R R A A N NN F OOO R R T R R A A N N U U SSS EEEEE RRRR SSS U U S E R R S U U SSS EEE RRRR SSS U U S E R R S UUU SSS EEEEE R R SSS GGG U U III DDDD EEEEE G U U I D D E G GG U U I D D EEE G G U U I D D E GGG UUU III DDDD EEEEE This document describes the OS/8 FORTRAN II provided on HRL OS/8 systems. The source for this document is on diskette RX8-96 in the INFO box. REVISED - 23-FEB-82 ---------------------- ---------- Hearing Research Lab FORTRAN User Guide (FORT.TS) ---------- TABLE OF CONTENTS ----------------- 1.0 Introduction 1.1 Documentation 2.0 System Components 2.1 FORT Compiler 2.2 SABR Assembler 2.3 LOADER Linking Loader 2.4 LIBSET Librarian 3.0 Coding Conventions 3.1 Statements 3.2 File Header 3.3 Local Subroutines 4.0 Run-time System 4.1 Useful Features 4.2 Console I/O 4.2.1 Output Control 4.2.2 Input Editting 4.2.3 Input from BATCH Stream 4.2.4 Changing Input Prompt 4.2.5 Changing I/O Mode 4.2.6 Changing Device Codes 4.3 Line Printer I/O 4.4 Assignable Unit I/O 4.4.1 Load-time Requirements 4.4.2 Features 4.4.3 Access Mode and Status Code 4.4.4 Errors 4.5 Diagnostic Error Messages 5.0 Miscellaneous Utilities 5.1 LIBCAT - Print Library Catalog 5.2 RELSYM - Print External Names 5.3 CDOLRS - C$ Conditional Compilation 6.0 Subroutine Libraries 1 ---------- Hearing Research Lab FORTRAN User Guide (FORT.TS) ---------- 1.0 Introduction ------------ This document provides an overview of the FORTRAN II system available as a part of the OS/8 systems running on the PDP8 mini computers in the Hearing Research Lab. Many enhancements have been made to all facets of the FORTRAN system and many subroutines have been written and documented. These changes and additions are described in this document or in other documents referenced in the text of this document. Additions and corrections to this document should be made in a timely and expeditious manner. 1.1 Documentation ------------- Documentation members containing relevant information are: GUIDE.TS - Hearing Research Lab System Users' Guide FORT.TS - FORTRAN II Users Guide (this document) FORTX.TS - FORTRAN II Language Description XLIB8.TS - XLIB8 Library Subroutine Descriptions LAB8.TS - LAB8 Library Subroutine Descriptions FTNLIB.TS - FTNLIB Library Subroutine Descriptions LAB8.TS - LAB8 Library Subroutine Descriptions PLOT.TS - LAB8 Plotting Package Subroutine Descriptions DEC Manuals containing relevant information are: OS/8 LANGUAGES REFERENCE MANUAL (FORTRAN II section) 2 ---------- Hearing Research Lab FORTRAN User Guide (FORT.TS) ---------- 2.0 System Components ----------------- The FORTRAN II system contains the following components: FORT.SV - FORTRAN II Compiler (a.k.a. FORTX or SFORT) SABR.SV - SABR Assembler LOADER.SV - Relocatable Module Linking Loader LIBSET.SV - Library Setup Utility DIAG.SV - Run-time Error Diagnostic Utility XLIB8.RL - DEC Functions and Extended I/O Subroutine Library LAB8.RL - Laboratory Equipment Subroutine Library FTNLIB.RL - Miscellaneous Subroutine Library A complete up-to-date FORTRAN system is always kept on diskette RX8-4 in the FORT box. 2.1 FORT Compiler ------------- The FORTRAN II language compiler supplied by DEC is quite primitive, so the HRL programming staff made extensive changes and fixed many bugs and shortcomings. Although many references to the extended FORTRAN call it FORTX, it exists on OS/8 as FORT, so as to be the default FORTRAN used by various system utilities, CCLX, etc. FORTRAN II is described in the FORTRAN II section of the OS/8 LANGUAGES REFERENCE MANUAL. The differences between the new Extended FORTRAN II and the old DEC FORTRAN II are described in the FORTX.TS documentation member. 2.2 SABR Assembler -------------- The FORT compiler translates FORTRAN source into SABR source, and then calls the SABR assembler to complete the job. A few changes have been made to the SABR assembler and are as follows: (*) The symbol table was moved to it's own field, thus increasing the amount of symbol table storage from about 399 variables to about 782 variables. (*) The 'S' error processing was modified slightly. Since the 'S' error is the general catch-all for overflow-type errors, there used to be no way to tell exactly what the problem was. Now, whenever an 'S' error occurs, perform the following procedure: .ODT 12677/ xxxx (ODT prints xxxx value) (Control-C) (Return to KBM) then inform one of the programmers of the xxxx value. It is 3 ---------- Hearing Research Lab FORTRAN User Guide (FORT.TS) ---------- the approximate location in SABR which contains the code that detected the overflow condition, and the type of overflow can be determined by examining a SABR listing. Some commonly occuring values are: 2235 : Page symbol table overflow (see below) 5570 : Too much code generated to fit in one field. (*) The page symbol table was expanded from 64 entries to 128. This should eliminate 'S' errors with address = 2235 resulting from having many type-integer variables and constants. SABR is described in the SABR section of the OS/8 LANGUAGES REFERENCE MANUAL. 2.3 LOADER Linking Loader --------------------- The Linking Loader has been enhanced in two areas. Changes in general loader operation and features are described below. Changes in FORTRAN run-time assignable unit support are summarized below, with a more complete description provided in section 4.4. (*) The external symbol table size has been doubled to 128 entries. The 128th entry is reserved. It is the address of the last loaded address in the highest loaded field. (*) The /n options (force loading in field n) now apply to all files in the command line, not just the first one. It also applies to library files (/L option), although the default libraries will still load starting in field 0. (*) The current date word is stored in location 20. (*) Up to eight (8) default libaries are allowed. The table of default library names starts at location 100, and terminates with a zero filename. If a library cannot be found during loading, it is skipped without any error message. (*) The meaning of the assignable unit switch options have been changed slightly. /I now means allocate space for unit #4 buffers. /O now means allocate spcce for unit #5 buffers. /H still means allow space for 2 page handlers. When LOADER is run in a Batch job, it will not load anything into the highest field. This is to avoid creaming the Batch Monitor, which occupies the upper half of that field. So there is one less field available than when the LOADER is run directly by the user. LOADER is described in Chapter 13 of the SABR section of the 4 ---------- Hearing Research Lab FORTRAN User Guide (FORT.TS) ---------- OS/8 LANGUAGES REFERENCE MANUAL. 2.4 LIBSET Librarian ---------------- LIBSET creates a FORTRAN subroutine library containing individual modules combined into one file. LIBSET is described in Chapter 14 of the SABR section of the OS/8 LANGUAGES REFERENCE MANUAL. 5 ---------- Hearing Research Lab FORTRAN User Guide (FORT.TS) ---------- 3.0 Coding Conventions ------------------ 3.1 Statements ---------- (*) The FORTRAN compiler recognizes TABs contained in a FORTRAN source file. The first TAB stop is at column 7, instead of column 9. This is to accomodate the FORTRAN convention dictating that instructions start in column 7. (*) Only 72 characters are allowed in each input line. This includes any spaces produced as a result of expanding TABs. Any characters beyond 72 are ignored. Remember that since the first TAB stop is two short of what normally appears on a listing of an OS/8 file, column 72 on the OS/8 listing is really column 70 as far as FORTRAN is concerned. (*) To continue a statement on the next line, start the next line with a TAB followed by a single non-zero digit. This digit is in column 7, so FORTRAN recognizes it as a continuation. Do not use the non-blank character in column 6 continuation method. It works, but TABs are easier to use. (*) Statement formats are: C * nnnn nnnn c (continuation) (nnnn = statement number from 1 to 2047) (c = single non-zero digit continuation indicator) ( can have leading blanks and/or TABs) ( can have trailing '@' followed by a comment) The following examples contain TABs, and are shown as they would appear on an OS/8 listing with the first TAB stop in column 9 instead of column 7: C This is a comment * and so is this I = 1 123 J = 2 2040 FORMAT('THIS IS A TEXT 1 STRING') @ Comment on a continuation 3.2 File Header ----------- All files that are intended to be kept as permanent programs should have information at the beginning of the file describing the program and giving compiling and loading instructions. A modification history area ahould also be provided containing 6 ---------- Hearing Research Lab FORTRAN User Guide (FORT.TS) ---------- dates, programmer initials, and description of modification. Special characters of interest are: = Prints double width characters on line printer = Prints OS/8 date on line printer An example header would be: CNAME.FT - SHORT DESCRIPTION CListing Date - C 23-FEB-82 JVECREATED C .CO B:NAME 3.3 Local Subroutines ----------------- Internal subroutines without parameter lists can be generated by using SABR statements to generate the entry/exit code. For example: SCPAGE 5 /keep text and entry on same page STEXT "?NAME" /for error traceback SENTRY NAME SNAME, BLOCK 2 (subroutine code) SRETRN NAME Remember that variables are not local (an IVAL in the main program is the same as an IVAL in the internal subroutine). 7 ---------- Hearing Research Lab FORTRAN User Guide (FORT.TS) ---------- 4.0 Run-time System --------------- 4.1 Useful Features --------------- The following features are summarized here to make the programmer aware of their existence and usefulness: (*) The FORMAT statement processor has been enhanced to include the following features: T# format spec spaces output to column #, if not already past it. O# format spec is similar to I#, except that the number is octal, instead of integer, and output has leading zeroes instead of spaces. A '\' (backslash) in format text toggles upper to lower case conversion. For example 'O\PERATING\ S\YSTEM' produces 'Operating System'. The conversion is initialized to off when WRITE statements are executed. (*) Using an Fx.0 format for real number input results in free format input with optional decimal point. This is preferred over Fx.d so that the number of decimal places or the presence of the decimal point are both optional. If any decimal places are present, they are included in the number, even though the decimal field specified 0. (*) The program can exercise greater control over output or input if it so desires by leaving a trailing comma on WRITE or READ statements, and calling IOH to output or input individual values or strings. The psuedo-operator FINI will generate the code to finish the processing of the current FORMAT statement. 4.2 Console I/O ----------- The internal FORTRAN unit #1 I/O handler has been enhanced to make it more like the TTY handler in OS/8. The user is also allowed to change certain attributes of unit #1 I/O. Whenever console input has been requested the AC display on the PDP8 front panel (switch in AC position) will show a rotating bit pattern indicating that it is idle while waiting for console input. 4.2.1 Output Control -------------- Pressing Control-S will cause any terminal output in progress to pause. Output may be resumed by pressing any other keyboard character. 8 ---------- Hearing Research Lab FORTRAN User Guide (FORT.TS) ---------- Pressing Control-C will terminate output and exit to the OS/8 Keyboard Monitor. 4.2.2 Input Editting -------------- When input is requested from the console by a READ(1,format) statement, a prompt character sequence is printed on the terminal and the user may enter and edit the input line with the following control characters: Console Key Action ----------- ------ DELETE/RUBOUT Erases last character. Control-U Erases entire line, repeats prompt. LINE FEED Reprints input line as currently edited. RETURN Terminates input line. Up to 80 characters may be entered on a line. Extra characters are ignored. 4.2.3 Input from BATCH Stream ----------------------- If a program is started while Batch is active, unit #1 input is read from the BATCH input file instead of from the console. Batch input will continue until a '$' (BATCH command character) is found in column 1 of the Batch input stream. Input then returns to the console keyboard. This feature can be used to create 'free running' programs that require no operator console input. Line feeds from the Batch input file are ignored. All other characters are passed with the parity bit set (just like from the keyboard handler). The programmer can inhibit the unit #1 input from Batch feature by calling the FIXIO routine with a negative number with the '4' bit set. For example: CALL FIXIO(-5) @ inhibit batch READ (1,101)I @ read always from console CALL FIXIO(-1) @ re-enable Batch input 4.2.4 Changing Input Prompt --------------------- Console input is initially prompted by the string '->'. This prompt sequence may be changed by the user to any ASCII string of any length by calling the FIXIO subroutine with an array containing the new character string, one character per word, ending with a zero word. For example, to change the prompt to a '?': 9 ---------- Hearing Research Lab FORTRAN User Guide (FORT.TS) ---------- DIMENSION IPROM(2) IPROM(1)="?" IPROM(2)=0 CALL FIXIO(IPROM) The contents of the array must not change, as the prompt character string is obtained directly from it every time input is requested. This of course means that the prompt can be changed by changing the contents of the array after FIXIO has been called at least once. The prompt can be changed to a null string by calling FIXIO(0). 4.2.5 Changing I/O Mode ----------------- The type of input sequence may be controlled by the user program. The possible modes are: CALL FIXIO(-1) : Sets CRT mode. (default) CALL FIXIO(-2) : Sets TTY mode. CALL FIXIO(-3) : Sets immediate mode. The default is CRT mode, where input is signalled via the printing of the input prompt, and the input line can be editted as described in section 4.2.2 with the character erase sequence being a backspace, space, backspace. TTY mode is like CRT mode, except that the erase sequence is just printing a backslash for each character deleted. Immediate mode is quite different. No prompt is printed, and no buffering or editting is allowed. The usual application for this is getting a single character without requiring a carriage return. For example: CALL FIXIO(-3) CALL CHRIO(-1,IKEY) CALL FIXIO(-1) Batch input can be inhibited by setting the '4' bit of the FIXIO parameter. See section 4.2.3 for example. 4.2.6 Changing Device Codes --------------------- The device associated with unit #1 may be redefined to be any ASCII device. The format is: CALL FIXIO(IKDEV,IPDEV) IKDEV is the hardware device code for the desired unit #1 keyboard. IPDEV is the hardware device code for the desired unit #1 printer. These devices must be ASCII character-oriented devices with a standard TTY interface. Specifying a non-existent device will hang the program. The initial IKDEV 10 ---------- Hearing Research Lab FORTRAN User Guide (FORT.TS) ---------- value is 03 and IPDEV is 04. 4.3 Line Printer I/O ---------------- The Line Printer is accessed via unit #3. Column 1 control codes are processed as described in the FORTRAN section of the OS/8 LANGUAGES REFERENCE MANUAL and are as follows: '0' = Double space (converted to line feed) '1' = New page (converted to form feed) Anything else is discarded. 4.4 Assignable Unit I/O ------------------- In the past, FORTRAN II unit I/O has been full of restrictions and contradictions. Unit 4 was the only assignable device. A file could be opened for input, and read from unit 4, and another file could be opened for output and written from unit 4. Since unit 4 could be really two separate logical devices, this scheme is not according to standards adopted in the computer industry. The most efficient way to implement multiple device access and enhanced I/O capability was to replace the FORTRAN/SABR run-time routines for unit 4 I/O with a set of routines which access tables defining the parameters for each unit. The old subroutine set (IOPEN,OOPEN,OCLOSE) has been deleted and a new set of routines have been added: OPENI - Open file for input OPENO - Open file for output CLOSE - Close character output file CLOSB - Close binary-mode output file READB - Read binary data from file WRITB - Write binary data to file RESET - Reset file pointers to beginning of file IOHST - Return current file status These routines are described in detail in the XLIB8.TS documentation member. The unit numbers from 4 - 8 are now assignable. However, only units 4 and 5 are currently supported. Conventions established by early implementations dictate that unit 4 is to be used for previous unit 4 input, and unit 5 is to be used for previous unit 4 output. The packets and buffers required for units 6-8 do not exist yet. If any usage is planned for units 6-8, an initialization subroutine must be written which will load into Field 0 and contain the required handler and data buffer space, plus the UPP. The UPP table which contains pointers to the UPP's for each device can be patched at run time by this routine to point 11 ---------- Hearing Research Lab FORTRAN User Guide (FORT.TS) ---------- to the UPP for that unit. Look at the /I and /O option processor in the loader for more implementation details. 4.4.1 Load-time Requirements ---------------------- Assignable units require certain storage areas to hold the handler and the data buffer. Unit 4's areas were previously allocated by the loader via the /I, /O, and /H command decoder options. In the new unit I/O scheme, these parameters have the following meanings: /I : Allocate data buffer and handler buffer for unit 4 /O : Allocate data buffer and handler buffer for unit 5 /H : Make the handler buffer two pages instead of just one (Same meaning as before) Each unit also requires a storage area for the Unit Parameter Packet (UPP). This packet contains information such as file length, buffer pointer, and run-time routine handler status. The UPP's for units 4 and 5 are predefined in the run-time system, and can be activated by the /I and /O options to LOADER. 4.4.2 Features -------- Enhanced assignable unit features include: (*) Space filled device names and file names allowed. (*) Binary I/O (words instead of characters). (*) Previously fatal errors can be detected (i.e. file not found error does not automatically cause abort). (*) Binary I/O re-write in place capability. (*) Deletion of existing file. (*) File pointers can be reset to beginning of file without having to re-open the file. 4.4.3 Status Code and Access Mode --------------------------- Each unit has a Status Code and an Access Mode associated with it. The status code governs operations performed by the run-time unit I/O handler. The access mode defines the I/O access permission for the unit. This permission can be write-only (1), read-only (2), read and write (3), or access denied (0). The status code is very important in performing operations on the unit. The code is set to a non-zero value (usually 1) when 12 ---------- Hearing Research Lab FORTRAN User Guide (FORT.TS) ---------- a file is opened on the unit. This value stays non-zero during all accesses to the file, providing that no errors occur. The following chart shows the conditions required for each subroutine to be successfully executed, the values after a good call, and the values after a bad call. I O O C C R I O P P L L E / H E E O O S O S N N S S E T I O E B T Unit must have defined UPP no yes yes yes yes yes yes Status code when called ? ? ? >0 >0 ? >0 Access mode when called ? ? ? >0 >0 >0 >0 Status code after good call n/c 1 1 >0 >0 1 >0 Status code after error n/c 0 0 0 0 0 0 Access mode after good call n/c 2 1 n/c n/c 0-3 >0 Access mode after error n/c 0 0 0 0 0 n/c ? = Don't care n/c = No change 4.4.4 Errors ------ Non-fatal I/O errors -------------------- Attempt to read past end of file (the status code is set to zero, data is undefined) Attempt to write past end of file (the status code is set to zero). Fatal I/O errors ---------------- Attempt to access an undefined unit. Attempt to do I/O on unit while status code is 0. Attempt to do I/O on unit w/o resetting after closing. Attempt to do I/O on unit while access mode is 0. Attempt to read from write only file. Attempt to write on read only file. Hardware I/O errors on device. If control over I/O aborts is desired, it is the programmer's responsibility to check the status code after every I/O operation to ensure that he is not exceeding the bounds of his file. Any I/O access to a unit while the status code is zero is assumed to be a programming error and the program is aborted. 13 ---------- Hearing Research Lab FORTRAN User Guide (FORT.TS) ---------- Error messages ----- -------- Short Long ----- ---- IOER TRIED TO READ WITH NO INPUT FILE OPENED IPER HARDWARE INPUT ERROR IQER ATTEMPT TO READ PAST END-OF-FILE IUER TRIED TO ACCESS UNDEFINED INPUT UNIT OOER TRIED TO WRITE WITH NO OUTPUT FILE OPENED OPER HARDWARE OUTPUT ERROR OQER OUTPUT FILE SPACE FULL OUER TRIED TO ACCESS UNDEFINED OUTPUT UNIT RUER RESET UNIT NOT DEFINED 4.5 Diagnostic Error Messages ------------------------- When an error occurs during execution of a FORTRAN or SABR written program or subroutine, an error traceback is provided along with more informative error messages. The file DIAG.SV must be present on the system device for this feature to work. The error message and traceback messages have the following format: ?message? AT STATEMENT x.y OF ROUTINE "name" CALLED FROM STATEMENT x.y OF ROUTINE "name1" 'message' is the error message (described below). 'x' is the most recent statement number in the source file. 'y' is the number of intervening statements between the statement containing statement number 'x' and the current statement. If the statement was in a main program, the text MAIN PROGRAM replaces ROUTINE "name". If the error was non-fatal, the traceback is suppressed, and program execution continues. The error traceback prints the name of the routine where the error was called from, and then traces back as best it can to the main program, printing the names and relative statement numbers of points of call. In unusual cases, the 'x' or 'y' values might be off, due to other memory contents resembling statement flags and being interpreted as such. However, the routine name will always be correct. The more informative messages are produced by looking up the four-character error message in a table and printing a more wordy message instead of the short one. This table is in DIAG.PA, and should be updated when routines with new error 14 ---------- Hearing Research Lab FORTRAN User Guide (FORT.TS) ---------- messages are added. Examples of expanded messages: Short Long ----- ---- ALOG LOGARITHM OF NUMBER <= 0.0 PAT# INVALID ATTENUATOR INDEX OOER TRIED TO WRITE WITH NO OUTPUT FILE OPENED Any program compiled by the FORT compiler will have routine names imbedded in the code so the diagnostic messages should always be able to print the correct name. The statement flags are also imbedded in the code, but can be disabled by the FORT compiler /T option. The /T option should be used only if SABR 'S' errors are resulting from too much code being generated, and it is too difficult to split the program into smaller pieces. Using the /T option will result in about a 10% savings. Each statement number uses two extra words, and each statement without a number uses one extra word. 15 ---------- Hearing Research Lab FORTRAN User Guide (FORT.TS) ---------- 5.0 Miscellaneous Utilites ---------------------- A number of FORTRAN system-related utilities have been written to make life easier. They are described in the following sections. 5.1 LIBCAT - Print a Library Calatog -------------------------------- LIBCAT is a FORTRAN written utility that examines the control block of a FORTRAN library and prints information concerning each segment of the library (a segment is what used to be a separate module before inclusion into the library). This information includes the amount of memory the segment occupies when loaded into memory and the names of the subroutines and functions in each segment. Input can be from any file on any device and output can go to any file on any device. 5.2 RELSYM - Print Referenced External Names ---------------------------------------- RELSYM is a FORTRAN written utility that examines a relocatable binary module (.RL file) and prints a list of all external symbol names defined and/or referenced in the module. Input can be from any file on any device and output can go to any file on any device. 5.3 CDOLRS - C$ Conditional Compilation ----------------------------------- CDOLRS is a PAL written utility that operates on an input file containing conditional assembly directives and produces an output file in which the conditional statements that were enabled have been transformed into a FORTRAN statement by removal of the conditional compilation directives at the front of the statement. This feature is used extensively in the P.E.A.P experiment programs where the major portion of a program stays the same among different versions and only certain decision making statements are modified. This makes it easy to make general changes to all versions of a program at the same time without having to make the same changes to a number of different source programs. CDOLRS are described in the CDOLRS.TS documentation member. 16 ---------- Hearing Research Lab FORTRAN User Guide (FORT.TS) ---------- 6.0 Subroutine Libraries -------------------- Subroutines can be gathered together and put in a file called a library to be accessed by the linking loader at load time. The libraries available in the HRL FORTRAN system are: XLIB8.RL - DEC Functions and Extended I/O Subroutine Library LAB8.RL - Laboratory Equipment Subroutine Library FTNLIB.RL - Miscellaneous Subroutine Library LIB8 is not included. All routines from LIB8 except for the assignable unit I/O routines are included in XLIB8 and are described in Chapter 4 of the FORTRAN II section of the OS/8 LANGUAGES REFERENCE MANUAL. See section 1.1 for a list of library subroutine documentation members. There have also been other subroutines written that are not used very often and are not present in the libraries due to low demand. Sources for these routines are contained on the diskettes containing the sources for the various libraries. Any undefined externals encountered in old programs might be satisfied by these routines. 17