--------- FTNLIB Fortran Library Documentation (FTNLIB.TS) ---------- Date of last documentation change - 23-FEB-82 This document describes routines contained in FTNLIB.RL. The sources for these routines are located on diskette RX8-8 in the FORT box. The source for this document is on diskette RX8-96 in the INFO box. CALL CAL (MTEXT,IDAY,IYEAR,DTEXT) CALL CAT (INFO) CALL CCL (TEXT) CALL DATE (IMON,IDAY,IYEAR) CALL DIR (IUNIT,DNAME) FR = DYDIM (NUM,LNGTH) CALL DYGET (VECTR,ILOW,IMAX,IBUFF) CALL DYPUT (VECTR,ILOW,IMAX,IBUFF) CALL DYRST FR = F4096 (IVAL) IR = IFCHN (ITEXT) IR = IFDIF (FVAL1,FVAL2) IR = IFIXR (FVAL) IR = INTFS (TEXT,DNAMO,FNAMO,DNAMI,FNAMI) IR = INVAL (IUNIT,LNGTH,TEXT,VAL) IR = ISWR (IBIT) IR = I4096 (FVAL) IR = LEX (STR1,STR2) CALL MOVE (BUFF1,BUFF2,LNGTH) CALL NUMB (FVAL or IVAL,TEXT,IWIDE,IDEC) FR = OCTA4 (IVAL) CALL PACK (TEXTI,TEXTO) 1 --------- FTNLIB Fortran Library Documentation (FTNLIB.TS) ---------- FR = RAND (SEED) FR = RND (SEED) FR = STDEV (NVARS,SUM,SQRS) CALL UEXIT (ITYPE) CALL UNPAC (TEXTI,TEXTO) CALL VTCLR CALL VTESC (ICODE) CALL VTHOM CALL VTPOS (ICOL,IROW) CALL ZFILL (TEXT,LNGTH) ----------------------------------------------------------------------- 2 --------- FTNLIB Fortran Library Documentation (FTNLIB.TS) ---------- CAL Subroutine Source: CAL.SB Date: 25-JUN-81 CALL CAL (MTEXT,IDAY,IYEAR,DTEXT) MTEXT : Month in 5A2 format. IDAY : Day of month (1-31). IYEAR : Calendar year (1977-1984). DTEXT : Day of week in 5A2 format. Returns current date information derived from the OS/8 date. CAT Subroutine Source: DIR.SB Date: 01-JAN-82 CALL CAT (INFO) INFO : 9 word array into which directory information is written. Returns next directory entry. Word Contents ---- -------- 1-3 File name. (See file name note below). 4 Extension. 5 Month (1-12). 6 Day (1-31). 7 Year (70-77). 8 File length in blocks. 9 File starting block. If INFO(1)=0 then entry is for an empty file. INFO(8) is the length. If INFO(1)=-1 then end of directory. See DIR subroutine for selecting which device from which directory is to be read. CCL Subroutine Source: CCL.SB Date: 20-NOV-81 CALL CCL (TEXT) TEXT : Packed 6-bit text of CCL command. Chains to CCLX which then executes the command contained in TEXT. Since CCLX has no 'return to caller' feature, there is no return from this routine (it is very much like the CHAIN routine). TEXT must be in packed 6-bit (A2 format) with an ending '00' byte. Imbedded '@' characters are not allowed, since they are represented by a '00' code. A maximum of 34 characters are allowed in the text. 3 --------- FTNLIB Fortran Library Documentation (FTNLIB.TS) ---------- For example, CALL CCL('SUBMIT NAME@') will cause the same action as if the SUBMIT NAME command had been entered via the console. DATE Subroutine Source: DATE.FT Date: 25-JUN-81 CALL DATE (IMON,IDAY,IYEAR) IMON : Month (0-12). IDAY : Day of month (0-31). IYEAR : Year (1970-2001). Returns the date maintained by OS/8. DIR Subroutine Source: DIR.SB Date: 01-JAN-82 CALL DIR (IUNIT,DNAME) IUNIT : FORTRAN I/O unit number (4-5). DNAME : Device name in 2A2 format. Initializes directory catalog reading from specified device via specified I/O unit. That unit must not be used for any other purpose until the final call to CAT has been made. The device being read must remain in the drive because the directory blocks are read one at a time as they are needed. See CAT subroutine for reading the directory entries. DYDIM Function Source: DYN.SB Date: 12-AUG-81 VECTR = DYDIM (NUM,LNGTH) NUM : Number of elements to allocate from dynamic storage. LNGTH : Length in words of each element. Creates a dynamic array of NUM elements of size LNGTH. For example, LNGTH = 1 is used for integer arrays, and LNGTH = 3 is used for real arrays. The type real VECTR value returned contains 3 words of information used by the DYGET and DYPUT routines and is meaningless otherwise. VECTR = 0.0 if there was insufficient room left in dynamic storage to allocate the requested array. Otherwise it has some non-zero value. For example, to allocate and use a 10 element real array: 4 --------- FTNLIB Fortran Library Documentation (FTNLIB.TS) ---------- dimension array(9) call dyrst vect1 = dydim (10,3) call dyput (vect1,1,1,3.14) [1st el. = 3.14] call dyput (vect1,2,10,array) [2nd - 10th = array] call dyget (vect1,1,1,pi) [pi set to 3.14] See DYRST subroutine for info on initializing dynamic storage. DYGET Subroutine Source: DYN.SB Date: 12-AUG-81 CALL DYGET (VECTR,ILOW,IMAX,IBUFF) VECTR : Real variable that holds info from DIM call. ILOW : Array index of first dynamic element to read. IMAX : Array index of last dynamic element to read. BUFF : Real or integer array into which data is to be written. Copies an array from dynamic to static storage. See DYDIM function for info about dynamic storage allocation. ERROR MESSAGES: VAL? : Invalid dynamic array vector or index out-of-range. DYPUT Subroutine Source: DYN.SB Date: 12-AUG-81 CALL DYPUT (VECTR,ILOW,IMAX,IBUFF) VECTR : Real variable that holds info from DIM call. ILOW : Array index of first dynamic element to write. IMAX : Array index of last dynamic element to write. BUFF : Real or integer array from which data is to be read. Copies an array from static to dynamic storage. See DYDIM function for info about dynamic storage allocation. ERROR MESSAGES: VAL? : Invalid dynamic array vector or index out-of-range. DYRST Subroutine Source: DYN.SB Date: 12-AUG-81 CALL DYRST Resets dynamic storage allocation free space pointers. DYRST must be called before any calls to DYDIM are made in order for 5 --------- FTNLIB Fortran Library Documentation (FTNLIB.TS) ---------- the free memory limits to be determined. DYRST can also be called after any DYDIM calls to reset the free space pointers. Any vectors allocated up until then can no longer be referenced. Free memory limits are determined by examining the 127th entry in the external symbol table. It is set by the loader at load time to the highest address loaded. The remaining locations in that field, and all of any remaining higher fields are available for dynamic storage (except for 07600-07777 and 17600-17777 to avoid destroying system areas). See DYDIM function for info on dynamic storage allocation. F4096 Function Source: CONVRT.SB Date: 14-SEP-77 FVAL = F4096 (IVAL) IVAL : Integer value. Floats IVAL to a number from 0. to 4095. instead of from -2048. to 2047. IFCHN Function Source: IFCHN.SB Date: 21-SEP-77 IFLAG = IFCHN (ITEXT) ITEXT : 20 word buffer (40 characters) for parameter. IFLAG : -1 if program chained to, 0 otherwise. Checks if program chained to, and constructs parameter text. The parameter is retrieved from locations 17600 - 17646, one character per word. It is packed into 6-bit character format, ignoring all non-six-bit set characters. The remainder is zero-filled. A first word of zero indicates no parameter. The text can be put there by another program, or by using CCLX's DEFINE command, and subsequent invocations of the program with a parameter. For example: .DEFINE PROG .PROG,PARAMETER TEXT The IFCHN function would return a -1 for IFLAG, and "PARAMETER TEXT" in ITEXT. If PROG were just run normally, IFCHN would return a 0 for IFLAG. 6 --------- FTNLIB Fortran Library Documentation (FTNLIB.TS) ---------- IFDIF Function Source: MISC1.SB Date: 14-SEP-77 IFLAG = IFDIF (FVAL1,FVAL2) FVAL1 : First value to compare. FVAL2 : Second value to compare. IFLAG : 0 if FVAL1 equals FVAL2, or non-zero if FVAL1 differs from FVAL2. FVAL1 and FVAL2 are compared without using floating subtraction. This function is designed to be used for text string comparisons. Using floating subtraction to compare strings sometimes produces equalities where none exist due to, for example, single character, zero-filled values. These will have a non-zero exponent, but a zero mantissa. Thus zero minus zero is zero, which is an incorrect result. IFIXR Function Source: CONVRT.SB Date: 16-SEP-77 IRSLT = IFIXR (FVAL) FVAL : Value to convert from real to integer. IRSLT : Converted value. Converts real value to integer by rounding off decimal fraction. The IFIX function truncates instead of rounds. INTFS Function Source: INTFS.SB Date: 20-NOV-81 IFLAG = INTFS (TEXT,DNAMO,FNAMO,DNAMI,FNAMI) TEXT : Text string containing file specification to interpret. DNAMO : Text from output device name field of string. FNAMO : Text from output file name field of string. DNAMI : Text from input device name field of string. FNAMI : Text from file name field of string. IFLAG : Indicates whether or not interpretation was successful. Interprets 6-bit zero-filled text and returns zero-filled file specifications along with a code indicating whether the interpretation was successful: IFLAG Meaning ----- ------- -1 Format error. 0 Processed o.k., but more text followed on input side. +1 Processed o.k. TEXT format is the same as for command decoder file specification format. In addition, a semicolon can be used in place of a colon, and a leading asterisk will be allowed (and ignored). 7 --------- FTNLIB Fortran Library Documentation (FTNLIB.TS) ---------- For example: TEXT of 'TTY:12 : IBIT parameter was out of range. I4096 Function Source: CONVRT.SB Date: 14-SEP-77 IVAL = I4096 (FVAL) FVAL : Real value to convert. IVAL : Converted value. Integerizes real numbers without checking for range to allow integerizing numbers outside the range handled by the IFIX routine. LEX Function Source: LEX.SB Date: 15-SEP-77 IFLAG = LEX (STR1,STR2) STR1 : First 12 character string to compare. STR2 : Second 12 character string to compare. IFLAG : Indicates lexicographical order of STR1 and STR2. Compares two 12 character strings for lexicographic ordering. Strings are in packed 6-bit text format. 8 --------- FTNLIB Fortran Library Documentation (FTNLIB.TS) ---------- IFLAG Meaning ----- ------- -1 STR1 precedes STR2 in lexicographical order. 0 STR1 = STR2. 1 STR2 precedes STR1 in lexicographical order. MOVE Subroutine Source: MISC1.SB Date: 20-NOV-81 CALL MOVE (BUFF1,BUFF2,LNGTH) BUFF1 : Source buffer. BUFF2 : Destination buffer. LNGTH : Count of words to move. Multiple of 3 for real values. Moves LNGTH consecutive words from BUFF1 to BUFF2. If LNGTH is negative, the absolute value is used for the number of words, and the move terminates when a '00' code ('@' character) is encountered in the bottom character of a word (any remainder in BUFF2 is zero-filled). This can be used to move a text string of undetermined length into a buffer and not move any extra garbage in with it. NUMB Subroutine Source: NUMB.SB Date: 15-SEP-77 CALL NUMB (FVAL/IVAL,TEXT,IWIDE,IDEC) FVAL : Real value to convert if IDEC not -2. IVAL : Integer value to convert if IDEC = -2. TEXT : Text string returned (A1 format). IWIDE : Number of characters desired in text string. IDEC : Number of places to the right of the decimal point. Converts a real or integer value into its character string representation. The value is right-adjusted with leading blanks. The PACK routine can be used to convert it from A1 format to packed 6-bit (A2) format. The format can be controlled with IDEC as follows: IDEC VAL type Period in text? ---- -------- --------------- >0 Real Yes, followed by IDEC decimal places. 0 Real Yes, as last character. -1 Real No, one's digit is last character. -2 Integer No, one's digit is last character. 9 --------- FTNLIB Fortran Library Documentation (FTNLIB.TS) ---------- OCTA4 Function Source: OCTA4.SB Date: 14-SEP-77 TEXT = OCTA4 (IVAL) IVAL : Integer value. TEXT : A4 format character representation of octal value. Returns four digit A4 format display code of the octal value. PACK Subroutine Source: CHAR.SB Date: 15-SEP-77 CALL PACK (TEXTI,TEXTO) TEXTI : Input text string in 6A1 format. TEXTO : Output text string in A6 format. Packs a text string. See UNPAC routine for inverse operation. RAND Function Source: (none) Date: 14-SEP-77 FVAL = RAND (SEED) SEED : 0 if next number desired, non-zero if seeding. FVAL : Next random number if SEED = 0. Seeds/calls random number generator. This subroutine is part of the binary file received from DECUS, catalog number 8-154. The DECUS writeup describing this routine is in the binder at the end of this section. See RND function for a different random number generator. RND Function Source: (none) Date: 14-SEP-77 FVAL = RND (SEED) SEED : 0 if next number desired, non-zero if seeding. FVAL : Next random number if SEED = 0. Seeds/calls random number generator. This subroutine is part of the binary file received from DECUS, catalog number 8-154. The DECUS writeup describing this routine is in the binder at the end of this section. See RAND function for a different random number generator. 10 --------- FTNLIB Fortran Library Documentation (FTNLIB.TS) ---------- STDEV Function Source: STDEV.SB Date: 14-SEP-77 FVAL = STDEV (NVARS,SUM,SQRS) NVARS : Number of values summed up in SUM and SQRS. SUM : Sum of NPARS values. SQRS : Sum of squares of NPARS values. FVAL : Calculated standard deviation. Computes standard deviation from sum and sum of squares. The formula used to compute standard deviation is: --------------------------------- / / NVARS * SQRS - SUM * SUM \ -- / ( -------------------------- ) \/ \ NVARS * (NVARS -1) / If NVARS is either 0 or 1, a STDEV of 0.0 is returned, although the result is technically undefined. The user should do his own checks for these cases. UEXIT Subroutine Source: UEXIT.SB Date: 06-NOV-81 CALL UEXIT (ITYPE) ITYPE : Indicates what type of user exit. Modifies the behavior of the FORTRAN run time system when the EXIT routine is called, which is in the following cases: 1. When the FORTRAN instruction STOP is executed. 2. When a Control-C is detected on the console keyboard. 3. After a fatal error message is printed. The EXIT routine waits for any I/O in progress to complete, and then exits to the OS/8 system. The UEXIT routine can be used to regain control when the above conditions occur. ITYPE Action ----- ------ 0 Cancel User Exit (next EXIT will go to OS/8) 1 EXIT calls will instead return from the last UEXIT call 2 EXIT calls restart the program For example: itrap = .false. call uexit(1) if (itrap) then c code to handle trapped exits goes here endif c Otherwise, falls through the first time, only itrap = .true. 11 --------- FTNLIB Fortran Library Documentation (FTNLIB.TS) ---------- Note that a CALL UEXIT(0) must be executed in order to exit to OS/8 after any other UEXIT calls have been made. UNPAC Subroutine Source: CHAR.SB Date: 15-SEP-77 CALL UNPAC (TEXTI,TEXTO) TEXTI : Input text string in A6 format. TEXTO : Output text string in 6A1 format. Unpacks a text string. See PACK routine for inverse operation. VTCLR Subroutine Source: VTSUB.SB Date: 14-SEP-77 CALL VTCLR Clears VT50 screen from cursor line on down by sending an (ESC J) sequence (033 112) to FORTRAN unit 1. VTESC Subroutine Source: VTSUB.SB Date: 14-SEP-77 CALL VTESC (ICODE) ICODE : 1 byte code to follow ESC byte. Sends escape sequence (033) (ICODE) to FORTRAN unit 1. VTHOM Subroutine Source: VTSUB.SB Date: 14-SEP-77 CALL VTHOM Positions VT50 cursor at upper left corner by sending an (ESC H) sequence (033 110) to FORTRAN unit 1. VTPOS Subroutine Source: VTSUB.SB Date: 14-SEP-77 CALL VTPOS (ICOL,IROW) ICOL : Column number. IROW : Row number (row 1 is bottom row). Positions VT50 cursor at ICOL from left, IROW from bottom by sending an (ESC Y 070-IROW 037+ICOL) sequence (033 131 0YY 0XX) to FORTRAN unit 1. 12 --------- FTNLIB Fortran Library Documentation (FTNLIB.TS) ---------- ZFILL Function Source: ZFILL.SB Date: 14-SEP-77 CALL ZFILL (TEXT,LNGTH) TEXT : Text string to zero or space fill. LNGTH : Length of string in words. If LNGTH is positive, trailing spaces and zero codes will be converted to zero codes. If LNGTH is negative, trailing spaces and zero codes will be converted to spaces with the absolute value of LNGTH taken as the length. This function is used primarily to space-fill and zero fill text strings such as file names. A subroutine might require a zero filled text argument but printout requires space filled text to avoid printing trailing 'at' (@) signs. ZFILL comes in handy for making the conversions between the two formats. 13