A-RCB-0091-2 THE RATFOR LIBRARY THIS PAGE INT ENTIONALLY BLANK A-RCB-0091-2 THE RATFOR LIBRARY PAGE 2 INTRODUCTION The RATFOR library is a set of rout ines available to RATFOR and FORTRAN programmers. Most of the routin es are written in RATFOR. There are routines for string manipulation, MCR line handling, character I/O, and timing. 1.0 STANDARD DEFINITIONS All routines in the RATFOR library use the symboli c names defined like this: DEFN RATLIB STANDARD DEFINITIONS THESE DEFINITIONS ARE CONSISTANT WITH THOSE OF THE RATFOR LIBRARY (RA TLIB) AND THE SYKES RATFOR PREPROCESSOR DEFINE (ALPHA=-4) DEFINE (ALPHABETIC=-4) DEFINE (ARB=10000) DEFINE (BAD=-1) DEFINE ( BINARY=2) DEFINE (BLANK=32) DEFINE (CHAR=LOGICAL *1) DEFINE (CHARACTER=LOGICAL*1) DEFINE (DECIMAL =10) DEFINE (DIGIT=-20) DEFINE (DUMMYSIZE=1) DEFINE (ENDBLOCK=]) DEFINE (ENDELSE=]) DEFINE (ENDFOR=]) DEFINE (ENDIF=]) DEFINE (E NDREPEAT=]) DEFINE (ENDWHILE=]) DEFINE (EOF=-3) DEFINE (EOS=0) END-OF-STRING !!!! DEFINE (ESCAPECHAR=64) DEFINE (HEX=16) DEFINE (HUGE=327 67) DEFINE (LETTER=-30) DEFINE (MAXDIGITS=18) DEFINE (MAXLINE=132) DEFINE (NEWLINE=10) DEFINE (NO=0) DEFINE (NUMERIC=-3) DEFINE (OCTAL=8) DEFINE (PAXPAT=81) DEFINE (PRINTER=6) A-RCB-0091-2 THE RATFOR LIBRARY PAGE 3 DEFINE (STDIN=3) DEFINE (STDLUNIN=3) DEFINE (STDLUNOUT=4) DEFINE (STDLUNTI=5) D EFINE (STDOUT=4) DEFINE (TAB=9) DEFINE (TYPER=5) DEFINE (YES=1) MACRO (DECREMENT,$=$-1) MACRO (INCREMENT,$=$+1) These DEFINE statements can be found in the file DEFN.RAT on the distribution medium. here is an explanation of some of these names: YES, NO, EOF: There are no LOG ICAL functions in the RATFOR library. Instead, INTEGER fun ctions, that can return one of these three values, are used. Such a function returns YES when successful, NO when the input is invalid, and EOF when there is no more input. CHAR, EOS: Many RATFOR routines manipulate strings. All string variables are CHAR vectors or scalars. Each string has a byte equal to EOS placed at the end as a marker. In RSX a nd F4P, zero bytes are used to mark the end of strings and chara cter constants, so EOS is defined to be 0. This means that a character constant can be used as an argument for any routine t hat expects a string argument. NEWLINE: Retur ned by the routine GETC at the end of each record. ESCAPECHAR: Used by the routine GETARG. NUMERIC, ALPH ABETIC: Returned by the character-typing routine TYPE. ARB: Used as the dimension of parameters when this dimension is arbitrary. STDLUNTI, STDLUNIN, STDLUNOUT: The se standard logical unit numbers (LUNs) are used by the routine s SETOTL and SETFLT. A-RCB-0091-2 THE RA TFOR LIBRARY PAGE 4 Some of the symbols have been d efined for improved program readability. For example, ENDIF and ENDELS E are used instead of the end of block character ']' to complement IF and ELSE. In general, no assumptions should be made about the values of these symbolic constants. They should only be used in tests of equality. However, these assumptions are permitted: 1) The values of EOF, NEWLINE, ALPHABETIC, and NUMERIC can be disti nguished from any ASCII character. A routine can return an ASCII character or one of these and the two cases can be disti nguished. 2) The value of EOF is a negative integer. A rout ine can return a line length or EOF unambiguously. 2.0 STRING MANIPULATION ROUTINES Following is a descriptio n of the string manipulation routines. Recall that strings are store d in CHAR vectors with a byte, equal to EOS, at the end as a marker. 2.1 EQUAL INTEGER FUNCTION EQUAL(S1,S2) EQU AL is called with two string arguments (CHAR vectors). It returns YES if they compare as equal, and NO otherwise. The strings must be of the s ame length and match at each character position to be considered equ al. EQUAL must be declared to be INTEGER in the calling program. Examples: EQUAL('ABC','ABC') r eturns YES EQUAL('ABC','ABCD') returns NO EQUAL('ABC','abc') returns NO A-RCB-0091-2 THE RATFOR LIBRARY PAGE 5 2. 2 LENGTH INTEGER FUNCTION LENGTH(STR) LENGTH returns the number of characters in its string argument. The EOS marker is not counted in this length. LENGTH should be declared to be INTEGER in t he calling program. Examples: LENGTH('A') returns 1 LENGTH('ABCdefH.') returns 8 2.3 SCOPY SUBROUTINE SCOPY(FROM,START 1,TO,START2,MAX) SCOPY copies the string FROM starting at positio n START1 to the string TO starting at position START2. No more than M AX-1 characters will be moved. (MAX-1 is used to leave room for an EOS.) FROM and TO must be CHAR vectors; START1, START2, and MAX must be INTEGER. An EOS marker is always placed at the end of TO. Examples: CHAR STR(15) INTEGER LENG TH,I STR(1)='*' CALL SCOPY('ABRACADABRA',1,STR,2 ,14) WRITE(5,10) (STR(I),I=1,LENGTH(STR)) 10 FOR MAT(1X,15A1) will output *ABRACADABRA 2.4 TYPE TYPE examines its CHAR argument and return s ALPHABETIC if the character is an upper or lower case letter, NUMER IC if the A-RCB-0091-2 THE RATFOR LIBRARY PA GE 6 character is any digit, and the character C itself otherwis e. Recall that ALPHABETIC and NUMERIC are symbolic constants. Since these two constants are distinguishable from any ASCII character, the seq uence TYPE(C)==C will be .TRUE. if and only if C is a non-alphanumeric (neither a letter nor a digit). This is a common idi om used to check for special characters. Both TYPE and C must be declared to be CHAR in the calling program. Examples: TYPE('A') returns ALPHABETIC TYPE('a ') returns ALPHABETIC TYPE('0') returns NUMERIC TYPE('*') returns '*' TYPE('[') returns '[' 2.5 CTOI INTEGER FUNCTION CTOI(IN,I,BASE) CTOI converts a CHAR str ing starting at position I in IN to a base BASE integer and returns this integer. If IN(I) is not a digit, the function returns 0. Otherwise, I is advanced to the first non-digit and a base BASE integer is built al ong the way. CTOI, BASE, and I must be declared to be INTEGER in the cal ling program; IN must be a CHAR vector with an EOS at the end. BASE may range from 2 to 10. Note well: This function has side effec ts. The value of I is changed. A constant must not be used as this arg ument; if a variable is used, it must be set to the proper value before CTOI is called. Of course, if we want to scan a string and pick out all the delimited integers, the side effect is exactly what we want. Examples: CTOI('01234',I,10) retu rns 1234 (BASE 10) AND I == 6 CTOI('12,34,56',I ,10) returns 12 (BASE 10) AND I == 3 CTO I('12,34,56',I,8) returns 10 (BASE 10) AND I == 3 CTOI('1100011,111',I,2) returns 99 (BASE 10) AND I == 7 A-RCB-0091-2 THE RATFOR LIBRARY PAG E 7 2.6 CHEXTI INTEGER FUNCTION CHEXTI(IN,I,BASE) CHEXTI is the same as the CTOI function described above with the exception that BASE may range from 2 to 16. therefore, the letters A-Z m ay be legal digits when BASE ranges from 11 to 16. 2.7 ITOC INTEGER FUNCTION ITOC(I,TO,BASE) ITOC converts an integer I to a CHAR string TO of base BASE, and returns the size of TO. If BASE is less than 2 or greater than 16., ITOC will make TO a null string and return 0. Example: ITOC(10,STRING,16) Retur ns 1 and 'A' in STRING. 2.8 INDEX INTEGER FUNCTION IN DEX(STR,C) INDEX searches the string STR for the character C. If it is found, the index (subscript) of C in the string is returned. If it is not found, 0 is returned. INDEX must be declared to be INT EGER and C and STR must be CHAR in the calling program. Exampl es: INDEX('ABCDE','A') returns 1 IN DEX('ABCDE','a') returns 0 INDEX('AABBCCDDEE','E') returns 9 A-RCB-0091-2 THE RATFOR LIBRARY PAGE 8 2.9 BRAKE INTEGER FUNCTION BRAKE(S1,S2,S3) BRAKE is similar to the SNOBOL function BREAK and is spelled dif ferently because BREAK is a RATFOR reserved word. BRAKE will elimin ate all characters in S1 starting from S1(1) that are NOT included in S2, up to the first match. The result is that S1 is shortened by the broken over characters, and S3 contains the characters that were rem oved from S1. A succesful call will return the number of characters re maining in S1. BRAKE will fail if no characters in S1 are br eak characters. The function will return -1 and place EOS in S3(1). BRA KE will also fail if the first character in S1 is a break character. The function will return 0 and place EOS in S3. BRAKE must be def ined INTEGER and the parameters defined CHAR except that S2 may be a l iteral string. 2.10 SPAN INTEGER FUNCTION SPAN(S1,S2, S3) SPAN is similar to the SNOBOL function of the same name. SPAN removes from S1 the longest string that solely consists of characters defined in string S2 and places them in S3. The result is that S1 becomes a new string with the spanned character(s) remove d, and S3 becomes a string that contains the only the spanned characters. On a successful call, SPAN returns the number of characters remaining in S1. SPAN will fail if all the characters in S1 are contain ed in S2. The function will return -1 and place EOS in S3(1), indicat ing that SPAN has matched ALL characters in S1. SPAN will also fail if the first character in S1 is not contained in S2. The function will return 0 and place EOS in S3(1), indicating no match. SPAN is usually used following the BRAKE function. If S1 contains 'ABCD???? EFG' BRAKE(S1,'?',S3) S1 now contains '????EFG' SPAN(S1,'?',S3) S1 now contains 'EFG' A-RCB-0091-2 THE RATFOR LIBRARY PAGE 9 SPAN must be defined INTEGER and the parameters as CHAR except that S2 may be a literal s tring. 2.11 MATCH INTEGER FUNCTION MATCH(LIN,PAT) MATCH will return the position in LIN of the first identical o ccurence of the string in PAT within the string LIN. If there is no exa ct match, MATCH will return NO. MATCH is taken from Kernighan and P lauger 'SOFTWARE TOOLS', page 140, and allows no metacharacters. LIN and PAT must be string of char, and may be literal. MATCH sho uld be defined as INTEGER. 2.12 ANY INTEGER FUNCTION ANY(S1,S2) ANY will return the first character position in S1 that contains any of the characters defined in S2. ANY must be defined INTEGER; S1 and S2 as string of char and may be literal. 2.13 NOTANY INTEGER FUNCTION NOTANY(S1,S2) NOTANY will return the first character position in s1 that does NOT contain any characters defined in S2. NOTANY must be defined intege r, and S1 and S2 either as string of char or literal. A-RCB-0091-2 THE RATFOR LIBRARY PAGE 10 2.14 SH IFT INTEGER FUNCTION SHIFT(S1,N) SHIFT will remove the first N characters from S1 and return the number of remaining characters in S1. SHIFT must be declared INTEGER and S1 either as string of CHAR or literal. 2.15 RPLACE INTEGER FUNCTION RPLACE(S1,OLD,NEW) RPLACE will replace all occurrences of the ch aracter 'OLD' in string S1 with the character 'NEW'. On a successful ca ll the function will return the number of characters replaced. RPLACE must be defined as INTEGER, and OLD and NEW as CHAR or literal. 2.16 TRIM INTEGER FUNCTION TRIM(S1) TRI M will trim out all trailing blanks and tabs in string S1 by repositionin g EOS and return the number of characters in the trimmed string. TRIM must be defined INTEGER and S1 as string of CHAR. 2.17 AP PEND INTEGER FUNCTION APPEND(S1,S2,COUNT) APPEND will con catenate S2 onto the end of S1 COUNT times and return the new length of S1. A-RCB-0091-2 THE RATFOR LIBRARY PAGE 11 APPEND must be declared INTEGER. COUNT must be an integer or integer variable. S1 must be string of CHAR, dimensioned larg e enough to contain the concatenation. S2 must either be string of CH AR or a literal expression. 2.18 REMOVE INTEGER FUNCT ION REMOVE(S1,FROM,TO) REMOVE will remove a substring from S1 begin ning at position FROM through position TO and return the new lengt h of S1. Function will fail if TO is LE FROM and return EOS. Function will fail if FROM is GE LENGTH(S1) and return EOS. if FROM is LE 1 , TO characters will be removed from S1 starting at S1(1). If TO is GE LENGTH(S1), S1 will be truncated at FROM. REMOVE must be declared I NTEGER. S1 must be string of CHAR. FROM and TO must be integers or intege r variables. 2.19 INSERT INTEGER FUNCTION INSERT(S1,F ROM,S2) INSERT will insert string S2 into S1 after S1(FROM) an d return the new length of S1. If FROM GE LENGTH(S1), S2 will be appended to S1. If FROM LT 1, S2 will be inserted before S1. INSER T should be declared INTEGER. S1 must be string of CHAR, and S2 eit her string of CHAR or literal expression. FROM must be an integer or inte ger variable. 2.20 LPAD INTEGER FUNCTION LPAD(S1,N) LPAD will insert N blanks before S1 and return the new lengt h of S1. LPAD must be declared INTEGER. S1 must be string of CHA R. N must be either an integer or integer variable. A-R CB-0091-2 THE RATFOR LIBRARY PAGE 12 2.21 RPAD INTEGER FUNCTION RPAD(S1,N) RPAD will append S1 with N blanks and return the new size of S1. RPAD MUST BE DECLARED INTEGER . S1 must be string of CHAR. N must be either an integer or integer var iable. 2.22 ALIGN INTEGER FUNCTION ALIGN(S1,POS,FIELD ) ALIGN will left justify, right justify, or center S1 in a field of length FIELD depending on value of POS and return the new le ngth of S1. This is accomplished by inserting the correct number of spac es before S1. If FIELD is LE LENGTH(S1) the function will fail and return EOS. If POS is LT 0, S1 will be left justified. If P OS is = 0, S1 will be centered on FIELD. If POS is GT 0, S1 will be r ight justified. ALIGN must be declared INTEGER. S1 must be s tring of CHAR. FIELD and POS must either be integers or integer variables . 3.0 CHARACTER I/O ROUTINES The character I/O routines are used to simplify the reading or writing of strings or single characters. GETL and PUTL read and write strings; GETC and PUTC handle one character at a time. A-RCB-0091-2 THE RAT FOR LIBRARY PAGE 13 3.1 GETL INTEGER FUNCTION GETL(LINE,MAXLIN,LUNIN) GETL reads the next record on LUN LUNIN and returns up to MAXLIN-1 characters in LINE. An EOS is always put at t he end of the input record in LINE. The function itself returns the lengt h of the record. If end-of-file is signalled, the function returns EOF, which can be distinguished from the normal case, since EOF is a n egative integer and hence different from any possible record length. GETL, MAXLIN, and LUNIN must be declared to be integers in the callin g program; LINE must be a CHAR vector of at least MAXLIN elements. Examples: CHAR INPUT(100) INTEGER GETL, N, I FOR (N=GETL(INPUT,100,1); N~=EOF; N =GETL(INPUT,100,1)) WRITE(2,10) (INPUT(I),I=1,N) 10 FORMAT(99A1) CALL EXIT END This program copies the file on LUN 1 to the file on LUN 2 truncating an y records longer than 99 characters. 3.2 PUTL SUBROUT INE PUTL(LINE,LUNOUT) PUTL writes a record containing the string LINE on to LUN LUNOUT. If the string has zero length, a null record is written . PUTL inserts no carriage control, although the calling program may have set the first character in LINE to a carriage control ch aracter. LINE must be a CHAR vector in the main program, and LUNOUT mus t be an INTEGER. Example: CALL PUTL('THE RAI N IN SPAIN FALLS MAINLY IN THE PLAIN',1) This call writ es the character string shown as the next record on LUN 1. A-RCB-0091-2 THE RATFOR LIBRARY PAGE 14 3.3 GET C CHAR FUNCTION GETC(C) GETC returns the next character o n LUN STDLUNIN in both GETC AND C. At the end of the first record on STDL UNIN, the character NEWLINE is sent. The next call to GETC will cause a new record to be read in. After the last character of each input record is sent, the next call to GETC will return the NEWLINE character and the call after that will cause a new record to be read and its first character returned. Note that NEWLINE is distinguishable from any ASCII character. At the end of file, EOF is sent. In the calling progra m, both GETC and C must be of type CHAR. GETC truncates any i nput record longer than 132 characters. Mixing GETC with any other ty pe of input on STDLUNIN can yield strange results. Such a trick should on ly be attempted immediately after a NEWLINE is returned by GETC. Examples: CHAR GETC,C INTEGER COUNT COUNT=0 WHILE (GETC(C)~=EOF) IF (C~=NEWLINE) COUNT=COUNT+1 WRITE(5,10) COUNT 10 FORMAT(I10) CALL EXIT END This program counts the number of characters in the file attached to STDLUNIN and prints this count. 3.4 PUTC SUBROUTINE PUTC(C) PUTC accepts a single character and b uffers it for future output on STDLUNOUT. When a NEWLINE is sent to P UTC, the buffer is output and a new record started. This allows easy inte raction between GETC and PUTC: GETC takes records apart and PUTC puts them back together. PUTC also starts a new record, if 133 ch aracters without a NEWLINE are sent. C must be of type CHAR in the callin g program. A-RCB-0091-2 THE RATFOR LIBRARY PA GE 15 Examples: CHAR C,GETC WHILE(GETC(C)~=EOF) IF(C~=BLANK & C~=TA B) CALL PUTC(C) CALL EXIT END This program copies the file attached to STDLUNIN to the file attached to STDLUNOUT, eliminating all blanks and tabs on the way. 4.0 MCR LINE ROUTINES The RATFOR library co ntains several routines for handling MCR lines and other terminal I/O. The lowest level routines are NXTMCR and NXTFIL. NXTMCR reads the next MCR line and places it in a COMMON buffer. This MCR line can com e from GETMCR, prompting, or even one level of indirect command file, if the calling program supplies NXTMCR with a dedicated LUN. The choice among these three is made automatically by NXTMCR. This line can th en be processed, or NXTFIL can be used to process it. NXTFIL scans the MCR line in the COMMON area and returns the file names, with their switc hes, one by one. NXTFIL also puts on default file extensions. We can a lso use NXTFIL to process file names which do not come from MCR lines, by loading the COMMON area MCR buffer ourselves. For example, this techn ique is used by the RATFOR processor to handle file names in INCLUDE s tatements. There are two higher-level routines for processing MCR input. These routines get the next MCR line, scan it, and open files on standard LUNs. Before discussing them, we are going to take a quick look at the concept of pipelines, filters and outlets. Many programs have one input file and one output file. We can imagine the data moving through a pipeline to the task; it is filtered by the task and allowed to move on: perhaps to the next filter for proc essing or perhaps to an outlet where the data is made available to the wor ld outside of the pipeline. The function SETFLT will set up a filt er-type program by reading an MCR line and opening an input file on STDLUN IN and an output file on STDLUNOUT. The function SETOTL will initialize a n outlet-type program by reading an MCR line and opening an input fil e on STDLUNIN. Both these subprograms remove any switches from file names they encounter and place them in a COMMMON area which can A-RCB-0091-2 THE RATFOR LIBRARY PAGE 16 be scanned using the function GETARG. Now for a detailed look at the M CR routines. 4.1 NXTMCR INTEGER FUNCTION NXTMCR(LUNPMT,PR OMPT,LUNIND,NUMOUT) NXTMCR reads the next command line and returns it in COMMON area MCRNFO. This COMMON area is set up like this: CHAR MCR(82) INTEGER POS COMMON /MCRNF O/ MCR,POS The command line is returned in MCR with an EOS at the end; POS points to the first valid character in this line. For example, if a program PRG, called NXTMCR, and this program was started with MCR>PRG FILE1=FILE2 then after calling NXTMCR we would have 'PRG FILE1=FILE2'EOS in the MCR array and 5 in POS. N XTMCR uses this algorithm to get an MCR line: 1) If this is th e first time NXTMCR has been called, try to read an MCR line using GETMCR. If this is successful, and there is someth ing on the MCR line besides the program name, keep this line . 2) Otherwise, if there is an indirect command file now open, read the next command line from it. 3) If ne ither of the above hold, prompt for a command line on LUNPMT. NXTMCR ignores any empty or blank command lines. When a command line starting with an @ is found, NXTMCR will try to open an indir ect command file. The caller must have supplied NXTMCR with a LUN in LUNIND by setting this argument to any positive integer. If the caller is unable to dedicate a LUN entirely for NXTMCR's use, the LUNIND arg ument is 0. Then any attempt at indirect command files will cause NXTMCR to type an error message and prompt for another command line. Note w ell: The calling program must be willing to dedicate a LUN solely for NXTMCR's use, if indirect command files are to be permitted. If not , always call NXTMCR with a LUNIND of 0. The PROMPT argument is a three-character string used by NXTMCR when prompting on the terminal. For example, if this A-RCB-0091-2 THE RATFOR LIBRARY PAGE 17 argument is 'PRG', NXTMCR will prompt wi th PRG>. This prompt is also used by NXTMCR to identify any error messag es it types. After it has the MCR line, NXTMCR scans it and count s the number of (possibly null) output file names. This value is returned in NUMOUT. It can be used by the calling program to det ermine how to process the MCR line. For example, consider these three MCR lines: OUTPUT=INPUT OUTPUT,LIST=INPUT ,LIST=INPUT For the first, NUMOUT would be set to 1. For b oth the second and third, NUMOUT would be set to 2. In the third case, t he calling program would have to recognize that the first output file na me was null. A summary of the arguments used to call NXTMCR i s: LUNPMT is a LUN (positive integer) used by NXTMCR to prompt for command lines and for typing error messages. Normally, it would be STDLUNTI. PROMPT is a three charact er string used by NXTMCR to prompt for command lines. Norma lly, it is a character constant giving the program name. LUNIND is a LUN used by NXTMCR for indirect command file I/O. If the calling program is unwilling to dedic ate a LUN solely for NXTMCR's use, this argument must be 0. NUMOUT is returned by NXTMCR. It is set to the number of output file names on the command line. If there is no equal sign (=) on the command line, NUMOUT is zero. Otherwis e, it is one more than the number of commas preceding this e qual sign not counting any commas in UICs. NXTMC R returns YES if it has read a command line successfully, and NO if there is no more command-line input. If NXTMCR did not have to pro mpt for a command line, it will return NO as soon as the first comm and line (read by GETMCR) is processed. Any indirect command file o n this line will be processed. If NXTMCR has to prompt for a comman d line, it will continue prompting until answered by ^Z, and then it will return NO. Hence, most programs using NXTMCR have a WHILE loop like this: WHILE (NXTMCR(STDLUNTI,'PRG',1,NUMOUT)==YES) { CALL SETUP(NUMOUT) CALL PROCES } CALL EXIT A-RCB-0091-2 THE RATFOR LI BRARY PAGE 18 END As long as NXTMCR fin ds a command line, this program will execute using the command line and th en process the indicated data. NXTMCR has local impure data which m ust not change between calls of the function. Hence, NXTMCR must re side in the root segment of an overlaid program. A special ca lling sequence is used to tell NXTMCR to flush the remainder of any indirect command file now open. This sometimes must be done if an erro r is detected in command-line input. If the LUNPMT argument is neg ative, then any indirect command file open on LUNIND will be closed. If an indirect command file is not open, the call has no effect. NXTMC R always returns YES after this special call. 4.2 NXTFIL INTEGER FUNCTION NEXFIL(EXT,FNAME,MAXFM,SWITCH,MAXSW) NXT FIL scans the command-line buffer in COMMON area MCRNFO and returns th e next file name in FNAME. Any switches on this file name are broken off and stored, as one string, in SWITCH. Only the first MAXFNM chracters of the file name are kept; only the first MAXSW characters of the switch es are kept. Both FNAME and SWITCH must be CHAR vectors in the calling p rogram; they are returned with a terminating EOS. The argument EX T is a four-character string which supplies a default extension for th e next file in the command line. If this next file has no extension, NXTFIL will put EXT on the file name returned in FNAME. The extension given in EXT must start with a period (.). NXTFIL sta rts scanning the command line left by NXTMCR in MCRNFO at position PO S. POS is incremented as NXTFIL scans the MCR line. When NXTFIL exits, POS is left pointing at the beginning of the next file name or at the EOS on the command line, if there are no more file names. Any bl anks or tabs in file names are removed; any lower case letters are tra nslated to upper case. A file name is terminated by a slash (/), comma (,), or equal sign (=). If the file name ends in a slash, the characters between this slash and the next comma or equal sign are sto red as a string in SWITCH. The opening slash is not stored; any subsequent slashes are stored. For example, say this MCR line was in the COMMON area: PROG OUT,,L;1/-SP=INPUT.EXT/AB/CD/EF A-RCB-0091-2 THE RATFOR LIBRARY PAGE 19 Consider this sequence of calls to NXTFIL: JUNK = NXTFIL ('.OTP',FNOUT,33,SWOUT,10) JUNK = NXTFIL('.MAP',FNMAP,33,SWMAP,1 0) JUNK = NXTFIL('.LST',FNLST,33,SWLST,10) JUNK = NXTFIL('.INP',FNINP,33,SWINP,10) These calls would each set JUNK to YE S and would leave the other variables in these states: (the quote s aren't part of the output of NXTFIL; they are shown here to delimit the strings returned by NXTFIL) FNOUT 'OUT.OTP' EOS SWOUT EOS FNMAP EOS SWM AP EOS FNLST 'L.LST;1'EOS SWLST '-SP ' EOS FNINP 'INPUT.EXT'EOS SWINP 'AB/CD/ EF' EOS Notice that NXTFIL considers null file names valid and returns a zero length string to represent them. Normally, NXTMCR and NXTFIL interact on their own; but we need not worry about the cont ents of the MCR buffer or the pointer POS. Instead, when NXTMCR returns YES, NUMOUT is checked and used to determine the sequence of calls to NXTFIL. After each call to NXTFIL a check must be made for null file-nam es. Consider a program which accepts command lines in these forms: OUTPUT=INPUT =INPUT INPUT Let us write a function to process these command lines, using NXTMCR and NXTFIL. The routine will return YES if it has set the f iles from a command line, NO if there is an error on the command line, an d EOF if there are no more command lines. If the output file is omitted, TI: is used as the output file. If there are any switches on the i nput file, they are returned in SWITCH; switches on the output file are ignored. When reading this routine, notice how the cases of null ou tput-files and no output files have been merged: A-RC B-0091-2 THE RATFOR LIBRARY PAGE 20 INTEGE R FUNCTION SETUP(SWITCH) CHAR FIN(33), FOUT(33), SWITCH(16) INTEGER NXTFIL, NXTMCR, NUMOUT, JUNK IF (NXTMCR(STDLUNIT, 'PRG', 0, NUMOUT)==NO) RETURN (EOF) ELSE IF (NUMOUT>>1) RETURN (NO) ELSE { IF (NUMOUT==0) FOUT(1) = EOS ELSE JUNK = NXTFIL('.OUT',FOUT,33,SWITCH ,1) # GET OUTPUT FILE IF (NXTFIL ('.INP', F IN, 33,SWITCH,16) == NO)) RETURN (NO) E LSE IF (FIN(1)==EOS || NXTFIL('.J NK',FIN,33,SWITCH,1)==YES) # CHECK FOR EXTRA INPUT RETURN (NO) IF (FOUT(1)==EOS) OPEN (UNIT=STDLUNOUT, NAME='TI:', ERR=100) ELSE OPEN (UNIT=STDLUNOUT, NAME=FOUT, ERR=100) OPEN ( UNIT=STDLUNIN, NAME=FIN, ERR=100) RETURN (YES) } 100 RETURN (NO) END 4.3 SET OTL INTEGER FUNCTION SETOTL(LUNPMT,PROMPT,EXTIN,LUNIND) S ETOTL is used to process the command lines of outlet type programs. Th ese command line must have exactly one file name. When called, SETOTL us es NXTMCR to get the next command line; if this fails, SETOTL returns NO. Otherwise, SETOTL makes sure there is exactly one input file on the command line, opens it on STDLUNIN, and returns YES. Any errors on t he command line are handled by SETOTL: it types an error message on LUNPM T and tries for a new command line. Any switches on the inp ut file are saved in a COMMON area SWITCH which is set up like this: CHAR SWITCH(80) COMMON /SWITCH/ SWITCH A-RCB-0091-2 THE RATFOR LIBRARY PAGE 21 This common area is accessed by the routine GETARG. If the input file name is missing (i.e. there are just switches on the command li ne), SETOTL will open the file PIPE.LYN for input. Furthermore, this open is done with DISP=DELETE so that when the input file is closed PIPE.LY N is removed. PIPE.LYN is always a temporary file holding partial result s produced by some other program. Each time SETOTL is calle d, it closes STDLUNIN before doing anything else. The argume nts to SETOTL have this purpose: LUNPMT: This LUN is used for prompting (by NXTMCR) and error message type out. It is usuall y STDLUNTI. PROMPT: This is a three-character program name used for prompting and error message identification. EXTIN: This is a four-character default extension for the input file name. It must start with a dot. LUNIND: If no n-zero, LUNIND provides a dedicated LUN for indirect command files; if zero, attempts to use indirect command files will el icit an error message. This example program accepts command li nes containing exactly one file name and types the number of lines in t he file. Since SETOTL opens its input on STDLUNIN and GETC reads from this LUN, the two co-operate quite nicely. CHAR GETC,C INTEGER SETOTL,COUNT WHILE (SETOTL( STDLUNTI,'COU','.LST',0)==YES) { COUNT = 0 WHILE (GETC(C)~=EOF) IF (C==NEWLINE) COUNT = COUNT+1 WRITE (5,10) COUNT 10 FORMAT(I10) } CALL EXIT END 4.4 SETFLT INTEGER FUNCTION SETFLT(LUNPMT,PROMPT,EXTIN,E XTOUT,LUNIND) A-RCB-0091-2 THE RATFOR LIBRARY PAGE 22 SETFLT reads and processes command lines for fil ter-type programs. Each such command line contains no more than 1 output and no more than 1 input file name. The input file is opened on L UN STDLUNIN, and the output file is opened on LUN STDLUNOUT. If the input file is omitted, the latest version of PIPE.LYN is used instead; simila ry if the output file is omitted, a new version of PIPE.LYN is created an d used. If there are switches on either the input file or the output fil e, they are saved in COMMON area SWITCH which is set up like this: CHAR SWITCH(80) COMMON /SWITCH/ SWITCH If swi tches appear on both file-names, only the input file name switches are kept. The SWITCH COMMON area is also accessed by the routine GETARG. SETFLT is an INTEGER function and must be declared to be IN TEGER in the calling program. It returns YES, if a command line is su ccessfully read and processed, and NO if there is no more command-line input. Any errors on the command line are handled by SETFLT. T he output file is opened with CARRIAGECONTROL='LIST'. Here is a detailed description of SETFLT's arguments: LUNPM T: This is a LUN used for prompting and error message print ing. It is usually STDLUNTI. PROMPT: This is a three-charact er program name used for prompting and error message identifi cation. EXTIN: This is the default extension for the inpu t file. It is four characters long and must start with a dot. EXTOUT: This is the default extension for the output file name. It must be four characters long and must start with a dot. LUNIND: If non-zero, LUNIN D provides a dedicated LUN for indirect command file I/O. Se tting LUNIND to zero means indirect command files are not permit ted. This example program transfers its input file to the output, compressing all runs of two or more blanks to a single blank. Not ice how SETFLT opens the right LUNs for GETC and PUTC. A-RCB- 0091-2 THE RATFOR LIBRARY PAGE 23 CHAR GET C,C INTEGER SETFLT WHILE (SETF LT(STDLUNTI,'BLA','.LST','.LST',0)==YES) WHILE (GETC(C)~=EOF) { IF (C==BLANK) { CALL PUTC(' ' ) WHILE (GETC(C)==BLANK) ; IF (C==EOF) BREAK } CALL PUTC(C) } CALL EXIT END 4.5 GETARG INTE GER FUNCTION GETARG(ARGNUM,ARG,MAXARG) GETARG is used to process th e switches placed in COMMON area SWITCH, normally set by SETOTL or SETF LT. This COMMON area is set up like this: CHAR SWITCH(8 0) COMMON /SWITCH/ SWITCH The parameters in this area are assumed to be separated by slashes. A call to GETARG provid es random access to these arguments. Argument number ARGNUM is copied f rom the SWITCH area into the string ARG. Only the first MAXARG-1 charact ers of this argument are copied. ARGNUM and MAXARG must be integers in the calling program; ARG must be a CHAR vector (on return, it will be EOS terminated). If argument number ARGNUM exists, it is c opied into ARG. GETARG then returns the argument's length. If the value of ARGNUM is too large, GETARG returns EOF. GETARG must be declare d to be INTEGER in the calling program. Arguments are separat ed (delimited) by slashes. Hence an argument normally can't conta in one of these characters. However, when a slash is preceded by the character ESCAPECHAR (@), the slash loses its separator function and is stored as part of the current argument. The ESCAPECHAR is removed when t his is done. If the @ character itself is to appear in switches processed by GETARG, it must be written as @@. A-RCB-00 91-2 THE RATFOR LIBRARY PAGE 24 Assume SWITCH h olds these characters: 'ARG1/ARG2@/WITH@/SLASHES/ARGUMENTNUMBE R3ISVERYLONGINDEE D'EOS Then GETARG(1,AR G,20) returns 4 with 'ARG1'EOS in ARG, GETARG(2,ARG,20) returns 17 with'ARG2/WITH/SLASHES'EOS in ARG, GETARG(3,ARG,20) returns 19 with 'ARGUMENTNUMBER3ISVE'EOS in ARG, GETARG(0,ARG,20) returns EOF, GETA RG(4,ARG,20) returns EOF. 4.6 MCRERR SUBROUTINE MCRERR(LUN,PRGNAM,MESS) MCRERR writes the string MESS on logical u nit number LUN, identified by the three-character program name PRGNAM . In the calling program, LUN must be an integer, PRGNAM a three-characte r string, and MESS any string (CHAR vector). Examples: CALL MCRERR(STDLUNTI,'MYP','THIS IS THE MESSAGE') types MYP -- THIS IS THE MESSAGE on the terminal. 4.7 CANT SUBROUTINE CANT(LUN,PRGNAM,FNAME) CANT is used to print an error message on LUN LUN identified by program name PRGNAM which says that the file named FNAME can't be open ed. LUN must be an INTEGER in the calling program, PRGNAM must be a thr ee character string, and FNAME any string. If the file name is null, the message NULL FILE NAME is printed. A-RCB-0091-2 THE RATF OR LIBRARY PAGE 25 Examples: CALL CANT(STDLUNTI,'HAL','NOFILE') types HAL -- CAN'T OPEN THIS FILE : NOFILE 4.8 KILFER SUBROUTINE(KILFER) K ILFER (KILl File ERrors) makes two calls to the ERRSET subroutine to turn off error reporting for most errors which can occur when a file is o pened with the OPEN statement. The ERR= construct is then used in these statements to handle errors. KILFER is always called by SETOTL A-RCB-0091-2 THE RATFOR LIBRARY PAGE 26 5.0 PERFORMANCE MEASUREMENT ROUTINES A useful set of perfo rmance measurement routines may be found in the performance libr ary, PERLIB. Refer to the documentation for The Performance Library. A-RCB-0091-2 THE RATFOR LIBRARY PAGE 27 ALPHABETICAL INDEX ALIGN . . . . . . . . . . . 12 ANY . . . . . . . . . . . . 9 APPEND . . . . . . . . . . 10 BRAKE . . . . . . . . . . . 8 CANT . . . . . . . . . . . 24 Character I/O Routin es . . 12 CHEXTI . . . . . . . . . . 7 CTOI . . . . . . . . . . . 6 EQUAL . . . . . . . . . . . 4 GETARG . . . . . . . . . . 16, 23 GETC . . . . . . . . . . . 14 GETL . . . . . . . . . . . 13 INDEX . . . . . . . . . . . 7 INSERT . . . . . . . . . . 11 I TOC . . . . . . . . . . . 7 KILFER . . . . . . . . . . 25 leng th . . . . . . . . . . 5 LPAD . . . . . . . . . . . 11 MATCH . . . . . . . . . . . 9 MCR Line routines . . . . . 15 MCRERR . . . . . . . . . . 24 NOTANY . . . . . . . . . . 9 NXTFIL . . . . . . . . . . 15, 18 NXTMCR . . . . . . . . . . 15, 16 Performance Measu rement Routines 26 PUTC . . . . . . . . . . . 14 PUTL . . . . . . . . . . . 13 REMOVE . . . . . . . . . . 11 RPAD . . . . . . . . . . . 12 RPLACE . . . . . . . . . . 10 SCOPY . . . . . . . . . . . 5 SETFLT . . . . . . . . . . 15, 21 SETOTL . . . . . . . . . . 1 5, 20 SHIFT . . . . . . . . . . . 10 SPAN . . . . . . . . . . . 8 Standard Definitions . . . 2 String Manipulation routines 4 TRIM . . . . . . . . . . . 10 A-RCB-0091-2 THE RATFOR L IBRARY PAGE 28 TYPE . . . . . . . . . . . 5