(RSX) RATFOR DOCUMENTATION VERSION 22, NOVEMBER, 1980 A. DESIGN RATFOR attempts to retain the merits of FORTRAN (universality, por- tability, efficiency), while hiding the worst FORTRAN inadequacies. RATFOR is FORTRAN e xcept for two aspects. First, since flow control is central to any program, re gardless of the application, the prima- ry task of RATFOR is to conceal this pa rt of FORTRAN from the user by providing decent flow control structures. Sec ond, it is possible at the same time to clean up many of the "cosmetic" deficie ncies of FORTRAN, thus providing a language which is easier to read and to write. Beyond these two aspects, flow control and cosmetics, RATFOR does nothing about other weaknesses of FORTRAN, except that the STRING data type is added. The design philosophy which has determined what should be in RATFO R and what should not has been that RATFOR should not know much FORTRAN. Furth er, that RATFOR should be as machine and operating system independent as pos sible to facilitate transport of RATFOR programs from one machine to another. I strongly recommend "Software Tools" (Addison-Wesley) by Kernighan and Pla uger for more detail and not a little philosophy on which RATFOR is based. David P. Sykes, American Management Systems, Inc. 1515 Wilson Blvd. Arlington, VA 22209 (703) 841-6086 (RSX) RATFOR DOCUMENTATION PAGE 2 VERSI ON 22, NOVEMBER, 1980 B. THE RATFOR LANGUAGE B.1 Statements (a) DO Statement Syntax: DO limits RATFOR statement becomes: DO label limits FORTRAN statement(s ) label CONTINUE The "limits" can be any Control=Initial,Final,Incremen t string ac- cepted by the local FORTRAN compiler, since it is copied into the FORTRAN code directly. RATFOR supplies the appropriate statement numb er. BREAK and NEXT statements may be used within "RATFOR state- ment". (b ) FOR Statement Syntax: FOR (initialize; condition; incremen t) RATFOR statement becomes: initialize FORTRAN statement label1 IF (.NOT.(condition)) GOTO label2 FORTRAN statement(s) increment FORTRAN statement GOTO label1 label2 CONTINUE The "initialize" statement is executed, then "condition" is tested. If it is true, "RATFOR statement" is executed, then "increment" is executed and "condition" is tested again. If "c ondition" is ever false, the loop is broken and control passes to the next st atement. "Initialize" is any single FORTRAN statement, which is to be done just once before the loop begins; "increment" is any single FORTRAN statemen t to be executed at the end of each loop, before the test; "condition" is a nything that is legal in a logical IF to the local FORTRAN compiler. Any of the three parts may be omitted, although the semicolons must remain. A null condition is treated as always true, so an infinite (RSX) RATFOR DOCUMENTATI ON PAGE 3 VERSION 22, NOVEMBER, 1980 lo op results. BREAK and NEXT statements are allowed within "RATFOR statement"; NEXT jumps immediately to "increment". Example: FOR (I=80; I > 0; I=I-1) IF (CARD(I) != blank) BREAK Note that the IF and the statement controlled by it (BREAK) are con- sidered t o be a single RATFOR statement, even though not enclosed in braces. (c) IF Statement Syntax: IF (condition) RATFOR stat ement1 ELSE RATFOR statement2 becomes: IF (.NOT.(condition)) GOTO label1 FORTRAN statement1(s) GOTO label2 label1 CONTINUE FORTRAN statement2(s) label2 CONTINUE The ELSE part is optional. The "condition" is anything legal in a logical I F to the local FORTRAN compiler. If "condition" is true, statement1 is execut ed. If it is false, and there is an ELSE clause, statement2 is execu ted. IF statements can be chained to provide the equivalent of the CASE state ment: IF (condition 1) RATFOR statement1 ELSE IF (condition 2) RATFOR statement2 ELSE IF (condi tion 3) RATFOR statement3 ELSE RATFOR statement4 (RSX) RATFOR DOCUMENTATION PAGE 4 VERSION 22, NOVEMBER, 1980 (d) REPEAT Statement Syntax : REPEAT RATFOR statement UNTIL (c ondition) becomes: label1 CONTINUE FORTRAN sta tement(s) IF (.NOT.(condition)) GOTO label1 The "RATFOR sta tement" is executed, then "condition" is tested. If not true, "RATFOR stateme nt" is executed again. The UNTIL part is optional, if it is omitted, the FORT RAN becomes: label1 CONTINUE FORTRAN statement(s) GOTO label1 Thus, the loop is infinite and must be broken i n some other way. "RATFOR statement" is always executed at least once. BREAK and NEXT statements are allowed within the REPEAT, with NEXT jumping immedi- ately to the UNTIL (if any, otherwise, repeating the loop). "Conditio n" can be anything legal in a logical IF to the local FOR- TRAN compiler. (e) RETURN (expression) Statement Syntax: RETURN (expr ession) becomes: function = (FORTRAN statement) return where "function" is the name of a FORTRAN function subprogram which RATFOR remembers from the last "FUNCTION" statement it saw (i.e., the one t hat started the function subprogram in which the RE- TURN statement appears). The parentheses are required (and are passed to the FORTRAN code). This st atement makes it very clear exactly what value the function is returning as it s value. "expression" can be any valid single FORTRAN statement that th e local compiler allows to be equated to (RSX) RATFOR DOCUMENTATION PAGE 5 VERSION 22, NOVEMBER, 1980 the function' s name. The normal rules for FORTRAN RETURNs apply: this statment is val id only within a FORTRAN function subprogram; it may occur several times within a function; the normal RETURN without the expression may occur anywhere, as always. (f) WHILE Statement Syntax: WHILE (cond ition) RATFOR statement becomes: label1 IF (.NOT.(cond ition)) GOTO label2 FORTRAN statement(s) GOTO label1 label2 CONTINUE As long as "condition" is true (which may be never), "RATFOR sta te- ment" is repeated; if it is ever false (including the first time) the l oop is broken and execution continues with the next statement. BREAK and NEX T statements are allowed within "RATFOR statement"; with NEXT going directly to the "condition". "Condition" can be anything legal in a logical IF to t he local FORTRAN compiler. (g) BREAK and NEXT Statements Synta x: BREAK n and NEXT n Allowed in DO , FOR, REPEAT, and WHILE loops to either proceed with the next iteration, or to break out of the loop. BREAK exits imme- diately from the loop. NEXT goes to the test part of DO, WHILE, and REPEAT, and to the increment step of a FO R. If n is specified, it is taken as the number of loops (of all four types) t o be broken out of (or skipped to the bottom of). If n is not specified, i t de- faults to 1; thus a simple BREAK gets you out of the inner-most loo p only; NEXT 2 gets you out of the current loop and at the bot- tom of the ne xt more inclusive DO, FOR, REPEAT or WHILE. Specifying n greater than the curr ent nesting level is illegal. (RSX) RATFOR DOCUMENTATION PAGE 6 VERSION 22, NOVEMBER, 1980 B.2 RATFOR Languag e Features (a) Since symbols are clearer than the .EQ., .GT., etc. used by FORTRAN, RATFOR allows the use of conventional mathematical symbols, which it converts into the equivalent FORTRAN. > or >> for .GT. < or << for .LT. >= FOR .GE. <= for .LE. == for .EQ. !, ^, or ~ for .NOT. !=, ^=, ~=, <> , or >< for .NE. \ or | for .OR. \\ or || for .XOR. & for .AND. && for .EQV. (b) All characters between a pound sign (# ) and the end of the line are treated as comments. This is equivalent to the exclamation point comment feature in DEC FORTRAN. The pound sign may occur in the first column, if desired, replacing the FORTRAN "C" in column one (w hich is not allowed in RATFOR source code). In this case, the entire line (w ith the "#" replaced by a "C"), will be copied into the FORTRAN code as a comm ent (unless the /CO switch is in effect). (c) If the input file(s) contai n more than one program module (delimited by the FORTRAN "END"), each new program will be started at the top of a new page in the listing file (if any) and will be separated by a formfeed in the FORTRAN output file. (d) RA TFOR source code lines are automatically continued: - The line en ds with a comma, - The line ends with an underline character , (the underline character is deleted), - The statement is obviously incomplete at the end of the line, as in the middle of the conditional part of a FOR or IF statement . Note however, that the convention is slightly different f or RATFOR and FOR- TRAN statements when dealing with balanced p airs of parentheses: A RATFOR statement is assumed to be continued; if the balancing closing parenthesis is not found on one line, we continue looking for it on the next line. A FORTRAN statement with unbalanced parenthesis o n the first line is more likely to be an error than an intenti onal continuation and so is flagged as an error (unless one of the two conven- tions above applies). (e) Statement s may be placed anywhere on the line. By conven- tion, blocks of statemen ts are usually indented three or four spaces. Multiple statements may appe ar on one line if separated by semicolons (no semicolon is required at the end of a statement which (RSX) RATFOR DOCUMENTATION PAGE 7 VERSION 22, NOVEMBER, 1980 is on a line by itself). If a s tatement begins with an all numeric token, it is assumed to be a FORTRAN sta tement label and is placed in colums 1-5 of the FORTRAN output. (f) RATF OR source lines may be up to 90 characters long. FORTRAN code is gen erated with a maximum line length of 72 char- acters. FORTRAN continuation li nes are created if necessary. (g) Any group of one or more statements (wi thin a single program and a single file) can be enclosed in braces or square b rackets and then treated as a single RATFOR statement and used anywhere a singl e statement may be used. Braces ({ }) and square brackets ([ ]) are synonym ous. Example: IF (I == J) [ J=1 I=2 ] causes both statements to be executed if I equals J , whereas IF (I == J) J=1 I=2 causes on ly J=1 to be executed conditionally; I=2 would be executed in any case becaus e only one statement or bracketed group of state- ments is controlled by the IF . "RATFOR statement" in any of the ex- amples above could be a bracketed grou p of several statements, or a single un-bracketed statement. (h) Strings in double quotes (e.g. "foo") are converted into the equivalent Hollerith st ring (e.g. 3hfoo), since that is the only legal form in ANSI standard FO RTRAN. Single quotes strings (e.g. 'A') are passed to the FORTRAN code unchanged. Both single and double quoted strings are treated as single tokens; this means that symbolic constants within them are not processed and that the string must be less then "maxtok" (currently 70) characters long. Two su ccessive apostrophes (single quotes) are passed to the FORTRAN code as a single apostrophe. Therefore, in direct access READ/WRITE statements, use two apostr ophes together (e.g. READ(1''23)). (i) Embedded blanks are significant to RATFOR because they sep- arate tokens and are used to break input code down i nto recognizable pieces (along with special characters). Leading and trailing blanks are not significant; in particular, the indentation of blocks of co de is meaningless to the pre-processor; it is for visual informa- tion only. The pre-processor does no formatting of the RATFOR source code on the RAT FOR listing; you must provide indentation and other formatting in the source code file the way you want it to ap- (RSX) RATFOR DOCUMENTATION PAGE 8 VERSION 22, NOVEMBER, 1980 pear on the listi ng. (RSX) RATFOR DOCUMENTATION PAGE 9 VERSION 22, NOVEMBER, 1980 C. PRE-PROCESSOR FEATURES Keywords for pre-processor features must, like language keywords, appear at the beginni ng of a line or after a semicolon. Except for Debug and Literal lines, these f eatures must not appear in the mid- dle of RATFOR statements, nor between an I F and its ELSE. C.1 INCLUDEs When a line of the form: INCLUDE RSX filespecification is encountered in the RATFOR source code, the specified file is opened and the input of source code continues from the start of that file until its end is reached, at which time input reverts to the next lin e of the original file. The INCLUDEd file may itself con- tain INCLUDEs; the y can be nested three deep. The format for the file specification is the sta ndard for RSX, optionally including UIC and device specifications, (the default s are the user's UIC and SY:); an extension (the default is RAT), and a version (default is the latest version). If the symbol "defaultopen" is defi ned (in RATRSX.RAT), and if the include file is not found based on the file specification as given in the INCLUDE statement, then the defaults specified i n "defaulto- pen" are prefixed to the specification in the INCLUDE and anot her attempt to find the file is made. However, this occurs only if the origi nal specification in the INCLUDE contains neither a device nor a UIC. Note th at the default string defined in "defaultopen" MUST be in double quotes; i t can contain a device specification, a UIC specification, or both. Example : DEFINE (DEFAULTOPEN="LB:[1,1]") INCLUDE FOO causes an attempt to open using "FOO.RAT". If that fails, another attempt to open using "LB:[1,1]FOO.RAT" is made. If you do not want the contents of the INC LUDEd file to be printed in the listing file, a "no-list" switch is allowed i n the INCLUDE: INCLUDE/NL RSXfilespecification Any INCLUDEs within the spe cified file will not be listed either, regardless of the switch settings of their INCLUDE lines. (Only the slash is actually checked for.) (RSX) RATFO R DOCUMENTATION PAGE 10 VERSION 22, NOVEMBER, 1980 Statements and lines cannot be split across file boundaries; otherwise, the INCLUDEd code is processed just as if it had been in the origi nal input file. In order to set the INCLUDEd code apart from the normal code, lines of code being taken from an INCLUDEd file are preceded by one or m ore asterisks on the listing (if they are listed). First level IN- CLUDEs are preceded by one asterisk, INCLUDEs within INCLUDEs by two asterisks, and third level INCLUDEd code by three asterisks. The INCLUDE feature is especially han dy where COMMON blocks are to be used by several different programs, since only one copy of the COMMON block and all associated declarations need be k ept up to date, but subroutines, definitions, or any other code can be in a n INCLUDEd file. INCLUDEs are also very useful for files containing a standar d set of DEFINEs, which can then be INCLUDEd in a series of related programs easily. C.2 DEFINE (Symbolic Constants) The pre-processor contains a simple text-replacement macro capabili- ty that allows the user to create symbolic constants (similar to FORTRAN variables, but not limited to six charac ters), and specify a "meaning" or definition for each, which can remain in eff ect across several programs. When the RATFOR code is converted into FORTRAN code, all occurrences of symbolic constants in the RATFOR code are replaced by their defined equivalents in the FORTRAN code. The de- finition itself ma y, in turn, be a symbolic constant. DEFINE state- ments may not appear in the middle of other RATFOR statements. Example: if DEFINE (character=BY TE) and DEFINE (maxline=80) then character LINE (maxline) is co nverted into the equivalent FORTRAN code: BYTE LINE (80) The symb olic constant ("character" in the first line above) and its definition ("BYTE" ) must be enclosed in parentheses and separated by either a comma or an equals sign. Currently, the symbolic constant and its definition can each be up t o 70 characters long (their length is DEFINEd in the pre-processor) but the ent ire DEFINE statement must fit on one line. Symbolic constants must be single , unique alphanumeric character strings beginning with a letter; no sp ecial characters (except underline) or blanks are allowed. Underlines may be embedded in (RSX) RATFOR DOCUMENTATION PAGE 11 VERSION 22, NOVEMBER, 1980 symbolic constants so that COBO L-like names can be used, e.g. DEFINE (DO_MONTH_END=YES). The definition o f a symbolic con- stant can be another symbolic constant. Once a symbolic co nstant is DEFINEd, it cannot be redefined within the files processed by a sin- gle command line. Definitions can be any character string less than 70 chara cters long but may not contain dollar signs. If the definition contains par- entheses, they must be balanced pairs. The definition, either in whole or i n part, can consist of a simple integer mathematical relationship between one or more symbolic con- stants and/or integers enclosed in less-than and greater -than signs (< >). Addition, subtraction, multiplication, and division are a l- lowed. Evaluation of the expression is strictly left to right; there is no precedence of operators. If the expression contains previously DEFIN Ed symbolic constants, they are replaced by their definitions prior to ma thematical evaluation. The result of the part is included in the defin ition in place of the ex- pression (it may be the entire definition). N umbers and the defini- tions of symbolic constants must be positive or negative integers. if DEFINE (foo=7) then DEFINE (blatz=) makes "blatz" equal "69" and is equivalent to DEFINE (blatz=69) and DEFINE (dumb=VERSION ) makes "dumb" equal "VERSION 8" If the /SC switch is specified in the command line, a table of all current (as of the end of the processing for that command line) sym- bolic constants and th eir definitions is included in the listing file. DEFINE statements may o ccur anywhere in a RATFOR program, except in the middle of another RATFOR st atement. Definitions remain in ef- fect for the remainder of processing of the command line in which the file containing them occurred. Normally, all definitions are cleared before processing the next command line, but this ca n be prevented by specifying the /RE (RETAIN) switch in the second com- man d line. A symbolic constant cannot be DEFINEd twice in files in the same co mmand line (or any INCLUDEd files used by that command line), or a subsequent command line if the /RE switch is used, since that would consitute redefinit ion, which is not allowed. DEFINEs and MACROs can be, and often are, in INCLUD Ed files. C.3 MACROs (RSX) RATFOR DOCUMENTATION PAGE 12 VERSION 22, NOVEMBER, 1980 The MACRO facility is ex actly like the DEFINE facility (in fact, the keywords are really synonymous), except that MACROs allow the pass- ing of a single argument to be included in t he definition at one or more places at pre-processing time. The place(s) in the definition where the argument is to be inserted are specified in the defini tion with a special flag character (a dollar sign). A MACRO is distingu- ishe d from a simple DEFINE by the presence of at least one dollar sign in the definition. MACROs may not appear in the middle of other RATFOR statements, but may appear anywhere else in the pro- gram. Example: MAC RO (foo,$=$+1) then foo(I) in the RATFOR code becomes I =I+1 in the FORTRAN code. because each "$" in the definition is re placed by the argument "I". if DEFINE (star=46) and MACRO (flag=E COL($)=star) then flag(7) in the RATFOR code be comes ECOL(7)=46 in the FORTRAN code. C.4 IFD EF / IFNOTDEF / ENDIFDEF (Conditional processing) Sections of RATFOR code (one or more lines) can be selectively pro- cessed into FORTRAN or ignored, depending upon the current define status of a specific symbolic constant. Whe n "IFDEF(symbol)" is en- countered in the RATFOR source code, a check is made t o see if "sym- bol" has previously appeared in a DEFINE or MACRO statement; if it has, the source code up to the balancing ENDIFDEF statement is pro- cess ed; if not, the source code is skipped until the balancing EN- DIFDEF is foun d. The "IFNOTDEF(symbol)" is similar, except that the RATFOR source code up to the balancing ENDIFDEF is processed if "symbol" has NOT been previously D EFINEd. The symbolic constant can be given a null definition, if it is being DEFINEd only for use with the IFDEF/IFNOTDEF statements (e.g. DEF INE(foo=) is sufficient). IFDEFs (and IFNOTDEFs) can be nested; if an o uter conditional is unsatisfied, all inner condi- tionals are skipped, just lik e all other code within the unsatisfied conditional. (RSX) RATFOR DOCUMENTA TION PAGE 13 VERSION 22, NOVEMBER, 1980 Example: DEFINE (foo=3) DEFINE (foo1=) IFDEF ( foo) I=9 IFNOTDEF (foo1) I=72 ENDIFDEF ENDIFDEF I=9 is processed; I=72 is ignored. Because th e IFNOTDEF is nested within the IFDEF, if "foo" were not defined, I=72 would not be pro- cessed regardless of the status of "foo1". Undefined conditional code (that not processed into FORTRAN) is nor- mally printed in the RATFOR so urce listing, but will have no source code line numbers on the lefthand side of the page. It can be de- leted from the listing entirely if a /NOIF switch i s included in the command line. C.5 Literal Lines (%) Occasionall y, a line of code which must be included in a program is modified in some unde sirable way by the pre-processor. If a percent sign (%) occurs in column 1 of the RATFOR source code line, the en- tire line, except for the percent sign, will be passed to the FOR- TRAN code without ANY modification whatsoever. Don 't forget enough leading blanks to put the start of the resulting FORTRAN lin e at or past column seven, as required by FORTRAN. C.6 Debug Lines ( ?) If a question mark occurs in column one of a RATFOR source code line , it is considered to be a debug line and will be processed into FORTRAN (minus the question mark) only if the /DE (DEBUG) switch was specified in the command line. Multiple levels of debug statements can be specified by a digit (1-9) in the second column (after the "?"). Debug lines whose level is equal t o or greater than the level specified in the /DE:n switch are processed, but lines with a lower level are not processed into FORTRAN. Lines with no level specified (blank in column two) are always processed if the /DE switch is s pecified. A /DE switch with no value causes all debug lines to be processed. (RSX) RATFOR DOCUMENTATION PAGE 14 VERSION 22, NOVEMBER, 1980 Example: ?5 WRITE (5,1) ?5 1 FORMAT (" DEBUG LINE") would be processed by specifying /DE or /DE: 5 or /DE:4, etc, but not be processed by specifying /DE:6 or /DE:9. C.7 STRINGs Since character processing frequently requires the use of strin gs (collections of characters of arbitrary length), the pre-processor adds t he STRING data type to FORTRAN. In FORTRAN, a STRING becomes a character ar ray with one character per element, plus one element for the terminator (end-of -string character, in DEC-land, a zero byte). Example: STRI NG FOO "BLATZ" becomes character FOO(6) DATA FOO /1hB, 1hL, 1 hA, 1hT, 1hZ, eos/ The string must be delimited by double quotes; single quotes are not allowed as delimiters. Single quotes, may, however, app ear within the string. Null strings are allowed, e.g. STRING FOO "". Note t hat the STRING function requires that the symbolic constants "character" and "eos" be defined (usually as "BYTE" and "0") when the STRING keyword is firs t encountered; otherwise, "character" and "eos" will be passed to the FORTR AN code as is and upset the com- piler. (The standard define file, DEFIN.RAT d oes this.) Since ANSI standard FORTRAN requires that all DATA statements mu st be grouped together and placed in the FORTRAN code after all other specif ication statements, but before any executable statements, STRING statemen ts must be grouped together and appear in the RATFOR source code after all othe r specification statements but before any DATA statements. The pre-processo r holds the DATA statement parts until it has output the "character" statement parts for all STRINGs, then outputs the DATA statements as a group. The pre-p rocessor re- ally doesn't care if STRING statements are grouped in this manner or not. DEC FORTRAN IV doesn't care either, but FORTRAN 4 PLUS and the ANSI s tandard do. Currently, there is a limit of 20 string specification stateme nts with a total of 300 characters (combined total of the string names and t he characters in the strings) in any one program module. (DEFINEd as 'nu mstr' and 'maxstr' in RATDEF.RAT). (RSX) RATFOR DOCUMENTATION PAGE 15 VERSION 22, NOVEMBER, 1980 D. PRE-PROCESS OR USE UNDER RSX D.1 RATFOR is normally installed with the task name "... RAT" so that it can be run as an MCR task or RUN independently: M CR>RAT command line or MCR>RUN RATFOR RAT>command line In the first example, the specified command line will be processed and the MCR will return; in the second example, RAT will return for another command line u ntil given a CTRL/Z (EOF). Regardless of the method of running RATFOR, an ind irect command file specification may be given by preceding it with the usual at sign (@). Only one level of indirect command files is allowed. The de- fault extension is CMD. MCR>RAT FTN,LST,OBJ=RAT1,...,RAT6/switches From le ft to right, the command line denotes: 1. the FORTRAN output file (defa ult extension FTN) 2. the RATFOR listing file (default extension LST) 3. the compiler output file (default extension OBJ) 4. up to six RATFOR input files (default extension RAT) The compiler output file will be produced if a nd only if the /GO switch is used. Here are some examples: MCR>RAT DB1:AL,AL,AL=AL/GO produces: AL.FTN, AL.LST, and AL.OBJ, all on DB1: (from SY: AL.RAT). MCR>RAT BOB,BOB,BOB=BOB produces: BOB.FTN and BOB.LST. There is no BOB.OBJ (even though it was denoted) because the /GO switch was omitted. MCR>RAT ED,ED=ED/-IN/NOSC produces: ED.FTN and ED.LST. MCR>RAT DM0:[3,3 ]FRED=FRED/GO produces: DM0:[3,3]FRED.FTN and DM0:[3,3]FRED.OBJ. MCR>RAT ,JAY=JAY/SP produces (and spools) only JAY.LST. A special feature of the c ommand line interpreter allows the most common form of command line (all default extensions, single input file, all output files with the same name as i nput file) to be ab- (RSX) RATFOR DOCUMENTATION PAGE 16 VERSION 22, NOVEMBER, 1980 breviated to a single file name . Thus, MCR>RAT MARY/GO/SP is equivalent to MCR>RAT MARY,MARY,MARY/SP=MARY/GO and MCR>RAT DK0:NANCY produces: DK 0:NANCY.FTN and DK0:NANCY.LST from DK0:NANCY.RAT The default device for all files is SY0:. The default UIC is the user's current UIC. If an explicit version number is specified, an explicit extension is required. The FORTRAN output file and the listing file are optional, but at least one must be pr esent. The compiler output file specification is optional, but if desired, the /GO switch must be used. Everything from a "!" to the end of the command l ine is ignored, thus trailing comments can be used either when the command line is input by the operator or from a indirect command file. Lines begin- n ing with a ";" or a "!" in column one cause the whole line to be ignored, bu t are allowed in indirect command files only. When more then one input file i s specified, they are concatenated into single FORTRAN output and listing files, and all command line switches and symbolic constant definitions are in e ffect for the en- tire command line. A single RATFOR input file may also con tain more than one program module. The end of the RATFOR program module i s identified by the FORTRAN "END" statement, and each will cause the start of a new page in the listing file. The RATFOR source listing contains the RATFOR line number, which is consecutive for all programs (and files) in a single command line. It also includes (in parentheses, on the extreme left) the l ine number of the FORTRAN code being generated for that RATFOR state- ment. These numbers should match (approximately) the line numbers the compiler will come up with for the FORTRAN code which is being generated by that RATFOR line. These numbers are very useful for debugging, since compiler and ru ntime errors are reported by line numbers. Almost always, you can find the off ending code in the RAT- FOR listing by looking up the matching (or almost m atching) line number. You should almost never have to look at a compiler listi ng. These numbers should be taken with a grain of salt; the relation- shi p of RATFOR to FORTRAN code is neither simple nor straightfor- ward. Many R ATFOR statements cause several FORTRAN statements to be (RSX) RATFOR DOCUMEN TATION PAGE 17 VERSION 22, NOVEMBER, 1980 generated; some generate no FORTRAN at all; still others generate some FOR TRAN now, some later. In general, the numbers listed cor- respond to the fir st significant FORTRAN statement generated by that RATFOR statement. For examp le, an ELSE IF generally generates a GOTO and a CONTINUE before the IF c orresponding to the RATFOR IF. In such cases, the listed FORTRAN statement numb er is for the IF. Complex RATFOR constructs may cause some of the list ed FORTRAN numbers to be off by 1 or 2, but the numbers always resynchronize after a couple of simple RATFOR statements (that can be passed di- rectly t o the FORTRAN output). The FORTRAN line numbers are correct for either DEC FOR TRAN IV or FORTRAN 4 PLUS (which differ in the way they number IF's), depending on the status of symbol "decf4p" (in RATRSX.RAT). An index is printed at the end of the RATFOR source listing. It contains an entry for: - The start of each file specified in the command line. The full f ile specification, including defaults is listed. - Each RATFOR source c ode line that begins with "#$ " in column 1-3. The whole line is li sted in the index. This is normally used to flag the beginning of eac h subroutine within the file. - Each INCLUDE file. The full file name, including defaults is listed. This index is not only very useful for finding a particular routine within the listing, but it is also a handy outline of the program structure because it shows at a glance the files, programs and in- cludes. The index can be suppressed with the /NOIN s witch. D.2 Command Line Switches The following command line switches are available to control the ac- tions of the pre-processor. They may be plac ed after any file spec- ification on the command line and apply to the entire c ommand line. Where appropriate, a switch can be negated by /NOsw or /-sw in the RSX style. For most of the switches, a default value (YES or NO) can b e defined in RATDEF.RAT. The standard defaults are: /NODE/NOFO/NOCO/NOGO/NOH E/IF/IN/NOLC/NORE/SC/NOSP/NOVE /DE:n debug Causes all li nes beginning with a question mark in column one to be pro cessed into FORTRAN code; by default such lines are ignored. If n is specified, only debug lines with an equal or higher value in column two will be processed. DEFAULT: /NODE /F O FORTRAN Causes the generated FORTRAN code to be included at (RSX) RATFOR DOCUMENTATION PAGE 18 VE RSION 22, NOVEMBER, 1980 the end of the listing file (if o ne was specified). Each program module starts a new page. Line numbers on the listing agree with DEC FORTRAN or F4P com- piler line numbers. For this switch to work, you must also specify an FTN output file or else the pre- processor must have been built with "openclose" support, so it can create a scratch output file. DEFAULT: /NOFO /CO compress Causes the FORTRAN code generated by t he pre-processor to be compressed for faster I/O by el- iminating all comments and unnecessary blanks in the generated FORTRAN code. This makes the FORTRAN es- sentially unreadable and is not recommended except for well debugged pr ograms. DEFAULT: /NOCO /GO go Causes the FORTRAN or F 4P compiler to be spawned with a command line of the form "FOO=FOO/SW", where FOO is from the RATFOR command line, and / SW is a string of switches for the compiler which can be de- fined in the symbol "ftnswitches". Thus, if you don't want a fancy compile, this allows RATFOR to pro duce a finished object module. This switch is available on ly on systems which support the SPAWN directive and the symbo lic constant "spawnit" must be defined (in RATRSX.RAT). R ATFOR does not wait for the compiler to finish, but goes on to the next command line at once unless the symbol "waitforftn" is defined in RATRSX.RAT. If a third output file is specified, it is used on the output side of the com- pil er command line. Example: M CR>RAT X,Y,Z=FOO/GO creates Z.OBJ If not given, the device, UIC, and name from the fir st output file specification (for the FTN file) are used for the OBJ file as well. Example: MCR>RAT X,Y=FOO/GO creates X.OBJ The compiler input file is always the FTN file cre- ated by RATFOR. DEFAULT: /NOGO (RSX) RATFOR DOCUMENTATION PAGE 19 VERSION 22, NOVEMBER, 1980 /HE help Causes a brief description of the command line switches to be printed on the user's terminal. The rest of t he command line, if any, is ignored. DEFAULT: /NOHE /IF ifdef listing Causes RATFOR source code within unsatisf ied condi- tionals (IFDEFs that are not defined or IFNOTDEF s that are defined) to be printed in the listing file. /NOIF suppresses printing of the code except for the I FDEF or IFNOTDEF line itself. DEFAULT: /IF /IN index Causes the RATFOR source code index to be printed at the end of the listing file. DEFAULT: /IN /LC lower case Causes RATFOR generated FORTRAN code to be output in lower case chara cters (code that is just transferred from the RATFOR source is in upper case) making it easy to identify. In addition, RAT FOR comments are also converted to lower case when printed o n the RATFOR listing, making it easier to separate com- ments from code. DEFAULT: /NOLC /RE retain Causes the symbolic constant definitions (if any) in effect at the end of the previous command line to remain in effect for the current command line. By default, any previous defi nitions are removed at the start of each command line. DEFAULT : /NORE /SC symbolic constant table Causes RATFOR to p rint a table of all symbolic con- stants defined in a progra m (or group of programs) at the end of the RATFOR source code listing (only if a listing file is specified in the command li ne). The table shows each symbol and its character string definition. DEFAULT: /SC /SP spool Causes the listing file, if one is specified, to be spooled to the li ne printer. The /SP switch is use- ful only if the listing is directed to a disk file; if directed to LP: the operating sy stem convention applies This switch works only if the symbol " open- close" is defined in the pre-processor. DEFAULT: /NOSP (RSX) RATFOR DOCUMENTATION PAGE 20 VERSION 22, NOVEMBER, 1980 /VE version C auses the RATFOR pre-processor to print its current version id entification on the user's terminal. The rest of the command line, if any, is ignored. DEFAULT: /NOVE (RSX) RA TFOR DOCUMENTATION PAGE 21 VERSION 22, NOVEMB ER, 1980 E. CONVENTIONS AND SUGGESTIONS While not required for prop er pre-processor operation, I have found the following helpful: Start pre-p rocessor features (INCLUDEs, IFDEFs, IFNOTDEFs, ENDIF- DEFs, DEFINEs, and MACROs) in column one of the RATFOR source code lines. Start the first level o f code in column four and indent each logical level three more spaces. If yo ur line printer, editor, and terminal will print lower case characters, ma ke all symbolic constants lower case in the RATFOR source code to make them easy to distinguish from variables. The case of symbolic constants is not significant to the pre-processor, but lower case makes them easy to locate in t he listing. If your line printer and FORTRAN compiler will handle lower c ase characters, use the /LC switch. Having the RATFOR-created FORTRAN code in lower case makes it easier to read and debug the FORTRAN if you have to. Also, having comments printed in lower case makes the RATFOR listing easier to read. On the listing, line numbering of pre-processor feature lines will n ot be exactly correct if the keywords (IFDEF, INCLUDE, DEFINE, etc) are not in upper case. However, processing of such keywords will be correct regardless of case. Symbols will be added to the symbolic constant table somewhat more quickly if DEFINEs and MACROs are encountered in alphabetical order by symboli c name. A "standard" set of DEFINEs is contained in the file DEFIN.RAT and is useful for most RATFOR programs as well as the pre-processor it- self. A shorter version, without definitions for lower case char- acters is in DEFI NS.RAT. Such symbolic constants as EOS, YES, NO, CHARACTER, and STDOUT and MAC ROs as INCREMENT($) and DECREMENT($) should be standardized for all your RAT FOR programs. If you like the IF...THEN, ENDIF, ENDDO, etc. convention use d by some other structured programming languages better than the brackets use d by RATFOR, you can DEFINE such keywords as open and close brackets; e. g. DEFINE(THEN=[), DEFINE(ENDIF=]). Leave the blank out of the FORTRAN DEFINE FILE statement, so it is not confused with the RATFOR DEFINE; FORTRAN doesn 't care. You need to be careful of some DATA statements. For example, DATA foo /"""/ or DATA foo /"#"/ will both be misunderstood by the pre-proc essor. In such cases, you can protect the lines with % or use the decimal v alue of the character instead of the literal char- acter. Note that RATFOR doe s not allow the DEC convention of double quotes for Octal constants unless the line is protected with a %. (RSX) RATFOR DOCUMENTATION PAGE 22 VERSION 22, NOVEMBER, 1980 The pre-processor uses a h omebrew command line interpreter whose calling sequence and structure are based on the RT11 routine ICSI. Command line syntax and style are identical to the RSX conventions with the following limitations on switch arguments: (1) Limit of one argument per switch, (2) Character arguments are not allowe d, (3) Arguments are always decimal numbers; neither "." nor "#" are allowe d to specify radix. The command line is converted to upper case before scan ning. The pre-processor works under F4P on processors without floating p oint processors, since it generates no FPP instructions, provided that symbol "realcode" (in RATRSX.RAT) is undefined. To include an apostrophe in a strin g or format statement, use a dou- ble quoted string, e.g. FORMAT ("here's Johnn y"). For direct access READs and WRITEs, use two successive apostrophes; they are convert- ed to a single apostrophe in the output code, e.g. READ (1''1). When creating FORTRAN statements, the pre-processor uses statement numbers starting at 20000 and going upward. Therefore, you should avoid using statem ent numbers in this range. The pre-processor will issue a warning message if i t suspects a statement number conflict. Study the RATFOR code of the pre-proc essor itself, it provides some good examples of what can be done with the lang uage. A common problem if you use FORTRAN 4 PLUS is statements in the gen- e rated FORTRAN that cannot be gotten to (FORTRAN IV doesn't care). Example: IF (... RETURN ELSE IF (... ... res ults in an unlabeled GOTO right after the RETURN. F4P is smart enough to kn ow you can't get to the GOTO and rejects it. The solu- tion is to change the E LSE IF to just an IF, which is logically equivalent. I find that I virt ually never have to look at the FORTRAN code gen- erated by RATFOR. I think the success of RATFOR depends consider- ably on the concept that the RATFOR co de IS the program, NOT the generated FORTRAN code. I find the most commo n RATFOR language error to be improperly nested IF...IF...ELSE statements. ELS E statements always apply to the most recent IF that does not already have an E LSE. Thus, if you have an IF...IF...ELSE sequence, the ELSE applies to the s econd IF. That's fine if that's what you want, but if you want the ELSE to bel ong to the first IF, you must put brackets around the second IF to show t hat it is a complete statement by itself; the ELSE will then fall back to the first IF. (RSX) RATFOR DOCUMENTATION PAGE 23 VERSION 22, NOVEMBER, 1980 Example: IF (statement) IF (statement) [ IF (statement) IF (sta tement) statement statement ] ELSE ELSE statement statement Assuming the indenta tion reflects the programmer's intent (ELSEing the first IF), the lefthand example is not correct, but the right- hand one is. Note that if the following statement were anything ex- cept an ELSE, both examples are equiva lent, since the IF (statement)/statement is really one RATFOR statement and is therefore controlled as a single unit by the first IF without the need for brackets. (RSX) RATFOR DOCUMENTATION PAGE 24 VERSION 22, NOVEMBER, 1980 Here are some rough timing data f or version 19: The RATFOR input in all cases is the file RATRSX.RAT (version 19). It contains 800 RATFOR source lines, including 157 symbolic constant de finitions. It produces 731 lines of FORTRAN. The data were col- lected on a dedicated 11/70 running RSX11/M,V3.1. All files were on the same RP06 disk. ...PREPROCESSOR BUILT WITH COMPILER OPTIONS.... FOR FOR FOR FOR F4P /CD:THR /CD: EIS /CD:EIS V2.2 V2.51 V2.1 /OP:SPD /OP:SPD /CD :EIS ASCII ASCII NOTASCII ASCII ASCII --------- ------------------------------------------------------- COMPILE TIME (F,F=RATR SX) :28 :27 1:30 -------------------------- -------------------------------------- RATFOR TASK SIZE(WDS) 28,352. 3 0,560. 31,776. 30,720. 28,800. ------------------------------------------ ---------------------- RAT F=F 1:38 1:06 1:49 1:10 1:00 ---------------------------------------------------------------- RAT ,F =F 1:56 1:18 2:17 1:20 1:09 ---------------------- ------------------------------------------ RAT F,F=F 2:04 1:25 2:38 1:28 1:17 ---------------------------------------------------- ------------ RAT F,F=F/LC 2:07 1:26 2:38 1:28 1:18 -- -------------------------------------------------------------- NOTES: The fi rst line is the time needed to compile the 731 lines of FOR- TRAN output. T he second line is the size of the pre-processor task if all pre-processor routi nes are compiled with the specified com- piler options. The last four lines are the elapsed time (m:ss) re- quired by the pre-processor to process the 800 lines of RATFOR source, given the command line specified. For the task sizes above, the symbols "openclose" and "spawnit" were not defined. See t he last page for a subroutine time breakdown which shows where the (Versi on 19) pre-processor spends its time. Overlaying (in Version 20) reduces the task size given above by about 4kw. In addition, other changes save abo ut 3kw and speed up the pre-processor about 8%. If the symbol ASCII is defin ed when the pre-processor itself is pro- cessed, the external character set ( ASCII on PDP-11's) is not con- verted to the internal character set (which is A SCII). Such conver- sion is not required on any processor which uses ASCII as its char- acter set, but would be on, say, IBM machines. Relative to the sec- ond column, the third column shows the overhead associated with this mapping. Clearly, mapping every character on input and output is very expensive, although the mapping routines could be speeded up somewhat. (RSX) RATFOR D OCUMENTATION PAGE 25 VERSION 22, NOVEMBER, 19 80 F. ERROR PROCESSING Error messages come in two flavors: 1. The command line interpreter and the RATFOR mainline call the error proces sing module in the command line interpreter (ICSIE) di- rectly. These messages are in lower case and generally cause the current (offending) command line to be thrown away and the next one processed (if an indirect command file). 2. RATFOR language errors and environmental problems found after process ing has begun are processed by ERROR and/or SYNERR and are in upper case. Non- fatal errors are reported by calling SYNERR direct- ly, which writes the err or into the listing file, if one is being created, and to the user's terminal ( by calling ICSIE). The error is printed in the listing file above the offen ding line. Fatal er- rors are processed by ERROR, which calls SYNERR and t hen exits, leaving junk output files and skipping the rest of the indirect com - mand file (if any). (RSX) RATFOR DOCUMENTATION PAGE 26 VERSION 22, NOVEMBER, 1980 G. BUILDING RATFOR A complete set of indirect command files is provided for RSX11/M, but should work under RSX11/D as well. Under M+, D or IAS you may want to edit the compi le and taskbuild files to create a multi-user version. The task build com mand files must be edited to use the correct resident libraries (if any) and de vice assignments for your system. All command files assume RATFOR and STRLIB are in your cur- rent UIC, and that the device is XX0:, you will have to assign XX0: before starting. You may also have to edit the ODL file, which as- su mes you have a FOROTS.OLB. Note that the build command file puts all modules into RATFOR.OLB for the task builder. When first installing RATFOR, build it from the FORTRAN files pro- vided. This will provide a basic version of RAT FOR. Edit the RAT- FOR source code to configure it for your needs (see RATDEF .RAT and the beginning of RATRSX.RAT) and pre-process it using the basic ver- sion of RATFOR. Compile and task build this customized version to get your production version. The pre-processor code is in three main files. RAT1, and RAT2 con- tain the computer-independent parts. All parts which may have to b e changed when moving RATFOR to a different environment are lumped into R ATRSX.RAT. The whole thing is designed to be as portable as possible without losing too much speed or capability. The pre-processor also needs STRLIB.RAT (string library) and ICSI.RAT (command line interpreter), and sev eral COMMON block definition files which are INCLUDEd all over the place. A variety of symbolic constants are available in RATDEF.RAT to con- figure t he pre-processsor for specific environments. Also, device assignments for all files can be set in the task build command files. The internal charac ter set used by the pre-processor is ASCII. When used on a machine whose external character set is also ASCII, PDP-11's, for example, much time is sav ed by not converting each external character to the equivalent internal character (which is the same anyway). However, if RATFOR is to be used on a machine whose external character set is not ASCII (IBM for example), conver- sion to and from the internal character set can be provided by unde- fining t he symbolic constant "ascii" in RATDEF.RAT because the internal-external conversion code is all conditionally pre-processed. You must e dit the ODL file to include OUTMAP and INMAP. If defined, the symbol "decwr iter" makes listing on a slow device faster by reducing the width of lines, especially the symbolic con- stant table listing. If symbol "strings" is un defined, the STRING data type and all code needed for it are deleted from t he pre-processor. No ODL changes are necessary. (RSX) RATFOR DOCUMENTATION PAGE 27 VERSION 22, NOVEMBER, 1980 The maximum nesting depth of INCLUDEs is one less then the value of "nfiles". If this is increased, logical unit number assigments ("stdout", etc) must be changed, since the input file LUNs are also the nesting level (LUN 1 being the basic source code file). RATDEF.RAT contains several symbols of the form "df ltXX" which de- fine the default settings for most of the switches. xx is the switch name. The maximum length of a line of RATFOR source code inpu t is defined by "maxcard"; the maximum length of a DEFINE or MACRO definition by "maxdef"; and the maximum length of a token (including quoted strin gs) by "maxtok". The maximum number of DEFINEs and MACROs allowed is def ined by "maxpts" and the total number of characters in all definitions is set by "maxtbl". Symbol "pagelength" can be adjusted for different line print ers. If defined in RATRSX.RAT, the symbol "decf4p" configures the pr e-processor for use with DEC F4P; if undefined, the pre-processor is configure d for DEC FORTRAN IV. The primary difference is the statement numbering on the FORTRAN code listing. It also determines which compiler is spawned by the /GO switch. The symbol "openclose" (in RATRSX.RAT and ICSI.RAT) must be def ined if you want support for spooling of listing files included (the de- faul t is still /NOSP). If "openclose" is defined, OPENs are used everywhere in stead of ASSIGN/FDBSET. This also allows for the odd case where you specify / FO without creating a FORTRAN output file (by creating a scratch output fi le). This also specifies the cor- rect carriage control so PIP does not get co nfused by the FORTRAN carriage control which otherwise applies to the output files. However, DEC's FORTRAN IV version 2.2 has a bug (feature?) and does not properly handle the ERR= transfer out of the OPEN statement un- less the reason for the ERR is "no such file". Any other error, such as a bad device name or non-existent UIC, causes an odd address trap (error 3). Therefo re, be advised, if you define "openclose" and use FORTRAN IV v2.2 and get od d address traps, don't panic, it's just DEC. Another FORTRAN IV v2.2 bug cau ses the compiler to print comments following an END statement as part o f the just-finished program instead of part of the next program (in a file w ith several mo- dules). The symbol "spawnit" (in RATRSX.RAT) must be defi ned if you have RSX11/M v3.2 or M PLUS and want to spawn the compiler to do the OBJ file. You can define a standard set of switches to be applied to the compiler command line by defining symbolic constant "ftnswitch es" in RATRSX.RAT. Note that the defined switch string must be a string in double quotes. (RSX) RATFOR DOCUMENTATION PAGE 28 VERSION 22, NOVEMBER, 1980 THIS IS TIMING FOR SYKES' RATFOR, VERSION 19. (COURTESTY OF STEVE LAZARUS). SINCE THIS TEST WAS RUN, SCOPY,TYPE ,SPAD, AND SCOMPR HAVE BEEN REWRITTEN TO SPEED THEM UP. PROGRAM RUN ON 01/ 02/80 AND FINISHED AT 09:40:45. 122.53 SECONDS ELAPSED TIME 7229. SAMPL ES 56 ROUTINES STRPUT 28.94% 2092.0 STRGET 26.75% 1934.0 G TOK 6.47% 468.0 SLEN 4.14% 299.0 SCOPY 3.83% 277.0 GETTOK 2.70% 195.0 SEQL 2.45% 177.0 NGETCH 2.24% 162.0 DEFTOK 1.90% 137.0 LOOKFR 1.87% 135.0 SCOMPR 1.80% 130.0 TYPE 1.69% 122.0 OUTSTR 1.47% 106.0 SHELL 1.34% 97.0 .MAIN. 1.16% 84.0 SPAD 1.13% 82.0 SITOC 1.07% 77. 0 OUTCH 0.79% 57.0 PRTLIN 0.73% 53.0 LEX 0.73% 53 .0 UNFOLD 0.66% 48.0 RATLST 0.62% 45.0 PUTBAK 0.59% 4 3.0 INDEX 0.58% 42.0 EATUP 0.58% 42.0 EQLS 0.54% 39.0 GETLIN 0.48% 35.0 PBSTR 0.41% 30.0 PUTLIN 0.33% 24.0 OPENI 0.26% 19.0 ALLDIG 0.24% 17.0 PARSE 0.24% 17.0 STRIM 0.14% 10.0 BALPAR 0.14% 10.0 OUTTAB 0.12% 9.0 RELATE 0.10% 7.0 OTHERC 0.10% 7.0 OUTDON 0.08% 6.0 ADDDEF 0.06% 4.0 FORCOD 0.06% 4.0 LRPAR 0.06% 4.0 UNSTAK 0.06% 4.0