DEC-10-AJAA-D 19-Oct-76 DECsystem-10 FOCAL-10 PROGRAMMING MANUAL DIGITAL EQUIPMENT AUSTRALIA * Melbourne * Australia This document reflects FOCAL-10 as of version 5J(345)-1. The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Australia. Actual distribution of the software described in this manual will be subject to terms and conditions announced from time to time by Digital Equipment Australia Pty. Ltd. Digital Equipment Australia assumes no responsibility for the use or reliability of its software on equipment which is not supplied by Digital Equipment Australia Pty. Ltd. For additional copies, order DEC-10-AJAA-D from Digital Equipment Australia, 60 Park Street, South Melbourne, VICTORIA 3205, AUSTRALIA. Price - $9.00. FOCAL-10 Page 2 ================================================================= 0.0 Table of contents --- ----- -- -------- 0.1 Introduction 0.2 Equipment requirements 0.3 Features of FOCAL-10 0.4 Getting on the air with FOCAL 0.5 Rubout 0.6 Errors 1.0 Simple arithmetic using the commands "TYPE" and "SET" 1.1 Symbols 1.2 Arrays 1.3 Arithmetic operators 1.4 Example of "TYPE" and "SET" 1.5 The symbol table 2.0 FOCAL program commands 2.1 The program text: WRITE, ERASE, COMMENT, MODIFY 2.1.1 WRITE 2.1.2 ERASE 2.1.3 COMMENT 2.1.4 MODIFY 2.2 Program directives: QUIT, GO, GOTO, DO, RETURN 2.2.1 QUIT 2.2.2 GO 2.2.3 GOTO mm.nn, GO TO mm.nn 2.2.4 DO 2.2.5 RETURN 2.3 Program loops and branches: FOR, IF 2.3.1 FOR 2.3.2 IF 2.4 SET 2.5 XECUTE 2.6 TYPE 2.6.1 TYPE "text" 2.6.2 TYPE 'text" 2.6.3 TYPE $ 2.6.4 TYPE $$ 2.6.5 TYPE /nn 2.7 Typeout of numeric results 2.7.1 TYPE %mm.nn 2.7.2 TYPE %Emm.nn 2.8 ASK 2.8.1 ASK /nn 3.0 LIBRA Commands 3.1 LIBRA CALL 3.2 LIBRA DELETE 3.3 LIBRA SAVE 3.4 Format of LIBRA commands 4.0 Input and output on other devices 4.1 Input and output channels 4.2 Input device initialization 4.3 Output device initialization 4.4 Releasing a device 4.5 Defaults FOCAL-10 Page 3 ================================================================= 4.6 Differences between OPERATE INPUT and LIBRA CALL 4.7 Notes on file I/O 5.0 The trace feature 6.0 Examples of FOCAL programs 7.0 Stopping FOCAL 7.1 How to force a FOCAL program to exit 7.2 The "REENTER" monitor command 8.0 Functions 8.1 What is a function? 8.2 Standard functions 8.3 External functions: FNEW 8.4 Parameters and values internal to FOCAL: FOCAL 8.5 Monitor information: GETTAB(TABNUM,TABINX) 8.6 Random number generator: FRAN 8.7 Single character I/O: FCHR 8.8 Single character string: FCHR$ 8.9 Sleeping and hibernating: FHIBER 8.10 Notes on implementing new functions 9.0 Function summary 10.0 FOCAL command summary 11.0 Character interpretations by FOCAL 12.0 Compatibility of FOCAL implementations. 12.1 General differences. 12.2 PDP-8 FOCAL. 12.3 PDP-12 FOCAL. 12.4 DECsystem-10 FOCAL 12.5 PDP-11 FOCAL. 12.6 FOCAL-GT. 12.7 FOCAL-11/RTX. 12.8 FOCAL-G11. 12.9 PDP-15 FOCAL. 13.0 Error diagnostics 13.1 Fatal errors 13.2 Non-fatal errors 13.3 Format of error print 13.4 List of error diagnostics 13.5 Push-down-list Overflow 14.0 External function: FNEW 14.1 How to load your FNEW program 14.2 Example of an FNEW routine 15.0 Internal representation of numbers --- accuracy 15.1 Single precision 15.2 Double precision KA-10 15.3 Double precision KI-10 16.0 Speed of FOCAL 16.1 Speed of Character Interpretation 16.2 Speed of Line-finding 16.3 Speed of Command-execution 16.4 Speed of Arithmetic Operations 16.5 Speed of Item Evaluation APPENDICES A FOCAL memory map FOCAL-10 Page 4 ================================================================= 0.1 Introduction --- ------------ FOCAL is an online, conversational, interpretive language for the DIGITAL family of computers. It is designed to help students, engineers, and scientists solve numerical problems. The language consists of short, easy-to-learn, imperative English statements. Mathematical expressions are typed in standard notation. FOCAL puts the full calculating power and speed of the computer at your fingertips. FOCAL is an easy way of simulating mathematical models, plotting curves, handling sets of simultaneous equations in n-dimensional arrays, and much more. FOCAL-10 programs and data can be read from or written on any device - see section 4. FOCAL-10 can call subroutines written in other languages - see section 14. The best way to learn the FOCAL language is to sit at the computer terminal and try the commands, starting with a few of the examples in this manual. 0.2 Equipment requirements --- --------- ------------ FOCAL-10 operates on any DECsystem-10 computer in at least 3k of user core. Unlike versions of FOCAL which run on smaller machines, FOCAL-10 has no "initial dialogue". Due to the large size of available memory, all standard functions are retained automatically. In general FOCAL-10 language features are more extensive than those on smaller computers (section 12), and the user should take care to avoid certain of them if he will want his program to run elsewhere. However, almost all FOCAL programs for the PDP-8, PDP-9, PDP-11, PDP-12, and PDP-15 should run on the DECsystem-10. Exceptions are those programs with special functions, and those with the PDP-11 type of subroutines. (Edit off the * at the end of papertape programs.) FOCAL-10 Page 5 ================================================================= 0.3 Features of FOCAL-10 --- -------- -- -------- * Sharable interpreter (Fully re-entrant) * Memory requirements 2k hiseg + 0.5k loseg * Completely versatile memory-management (fully expandable) * Double precision or single precision (assembly feature) * Will run on KA-10, KI-10 and PDP-6 under all monitors * FOR-loops can use positive or negative increment * Variables can be numbers or strings * Three-letter variable names * Variable names can start with the letter "F" * Up to 18 subscripts may be used for each variable * Can have function subprograms in other languages * File I/O to 14 input or output files plus TTY and LIBRA * Automated test files included * Adjustable %E format * Error messages in English * Error messages include the interpreter's pointer * Floating-point trap * Two levels of error-message severity * Can suppress non-fatal error messages * Can suppress colon cue for "ASK" command * Can suppress equals sign on numeric type-out * Numeric type-out has a floating sign * Listing headers have time and date * Symbol table not destroyed unnecessarily * Symbol table typed in alphabetical order * Space after commands not mandatory if not ambiguous * "GO TO" allowed as two words * All commands allowable in indirect mode (even MODIFY) * Handles upper and lower case * Can type out quote marks, form feed & special characters * Can abort on an "ASK" command in a loop with control-P * LIBRA CALL, SAVE and DELETE commands * Nested library calls * Exponentiation with uparrow or double asterisk * Positive response if too many rubouts typed * Internal indexing of text (for greater speed) * GETTAB function to obtain monitor information * Logical IF FOCAL-10 Page 6 ================================================================= 0.4 Getting on the air with FOCAL --- ------- -- --- --- ---- ----- The user should first obtain access to a DECsystem-10 terminal, and go through the "login" procedure, typing in the project- programmer numbers and password. Thereafter, all that is required is to type "R FOCAL" followed by carriage-return. The monitor will then load the FOCAL interpreter into memory and start it running. FOCAL will type an asterisk indicating its readiness to accept a command or line from the keyboard. Each time the user completes typing a program line and terminates it by depressing the carriage-return key (or line-feed or alt-mode or escape) or after FOCAL has performed a command, an asterisk is typed to tell the user that FOCAL is ready for another command or line. A program line contains a command or series of commands preceded by a reference number and terminated by a carriage-return, line-feed, alt-mode, or escape. If the reference number is omitted, the typed-in line is immmediately executed (immediate mode). The reference number is called a "line number" and has the form mm.nn, where mm is called the "group number" and nn is called the "step number". The group number lies between 1 and 99, and the step number lies between 01 and 99. All lines having the same mm form a "group". The group is then referenced by commands as mm or mm.0. For example: 56.78 THIS AND THE NEXT LINE ARE IN GROUP 56. 56.93 THIS LINE IS PART OF GROUP 56. 63.22 THIS LINE IS THE ONLY LINE IN GROUP 63. When several commands are typed on one line, they must be separated by semicolons (;). For example: 49.76 SET X=6;SET Y=X+3;TYPE Y;ERASE 56.93 The same command may be executed on several successive arguments by separating the arguments with commas. For example: 71.42 SET X=3, Y=4, Z=5 71.61 TYPE X, Y, Z 71.62 DO 44, 45, 99.62 As only the first letter of a command word is significant to FOCAL, only the first letter need be typed. Also spelling is unimportant. For example the following forms are all equivalent: FOCAL-10 Page 7 ================================================================= TYPE X tyep X T X Note: FOCAL-10 commands and command-modifiers may be any sequence of alphabetic characters. Spaces, tabs or control characters (any character with ASCII value less than 41-octal) may be used between commands, command-modifiers or arguments to improve clarity. They do not affect execution. The available commands are summarised in section 10 and described fully in sections 2, 3 and 4. 0.5 Rubout --- ------ FOCAL-10 uses the control-U character to delete back to the beginning of the line. (This is in contrast to PDP-8 FOCAL, which uses the backarrow.) Single characters may be deleted with the RUBOUT or BACKSPACE key. If sufficient rubouts are used to go back beyond the beginning of the line, FOCAL-10 will echo ^, U, cr, lf, and asterisk. (In a MODIFY command the asterisk is not printed). After a few rubouts, you may wish to use control-R to display the input-line-so-far. 0.6 Errors --- ------ FOCAL constantly checks user input for invalid commands, illegal formats, and many other kinds of errors. It types a message indicating the kind of error detected. In the following example, HELP is not a valid command: *HELP ? ?Illegal command HELP ^ * The complete list of error diagnostics and meanings is given under "error diagnostics" (see section 13). A trace (debug) feature is included (see section 5). FOCAL-10 Page 8 ================================================================= 1.0 Simple arithmetic using the commands "TYPE" and "SET" --- ------ ---------- ----- --- -------- ------ --- ----- "TYPE" to FOCAL means "type out the result of the following expression." When you type (following the asterisk which FOCAL printed), *TYPE 36.4318+48.1346 And then press the carriage-return key, FOCAL prints = 84.5664* The next command may be entered immediately, or carriage return may be typed to improve readability. If the "TYPE" command is terminated by an exclamation mark (!), output advances to the next line after the answer has been printed. "SET" tells FOCAL "store this symbol and its numerical value. When this symbol appears in an expression, insert the numerical value." Thus, you may type, *SET A=3.14159;SET B=428.77; SET C=2.71828 * You may now use these symbols to manipulate the values defined in the SET command. 1.1 Symbols --- ------- Symbols consist of one, two or three alphanumeric characters. The first character must be a letter. Note:"alphanumeric" means one of the characters: ABCDEFGHIJKLMNOPQRSTUVWXYZ (UPPER CASE) abcdefghijklmnopqrstuvwxyz (lower case) 0987654321 1.2 Arrays --- ------ Arrays may be stored in FOCAL. However, the arrays may be sparse, and do not require a DIMENSION statement, since they are stored without intervening unused elements. Each subscript may consist of a number, symbol or expression and the subscripts are all enclosed in parentheses, so that elements of an array are written in one of the forms: A(5), B(X), Q(3,3,X), or VEC(Q+2*J/43.) Further details are given in section 12.9. FOCAL-10 Page 9 ================================================================= 1.3 Arithmetic Operators --- ---------- --------- Numeric expressions may be formed by combining numeric variables and constants with the arithmetic operators. In order of precedence the arithmetic operators are: parentheses exponentiation ^ or ** division / multiplication * addition + and subtraction - Evaluation is done from left to right, so that, for example, 15/3/2 has the value 2.5 (not 10). 1.4 Example of "TYPE" and "SET" --- ------- -- ------ --- ----- The following dialogue illustrates the use of the "TYPE" and "SET" commands and the arithmetic operators. (See also section 2.7 on formats) *SET A=2,B=3;TYPE A*B;SET X=A^B;TYPE X;SET Y=X/A+5;TYPE Y = 6.0000= 8.0000= 9.0000* *SET ASQ=FSQT(A);TYPE ASQ,A,A*A,A*(A+1) = 1.4142= 2.0000= 4.0000= 6.0000* 1.5 The symbol table --- --- ------ ----- The command "TYPE $" causes both the currently defined symbols and their current values to be typed out. (See section 2.6.3) FOCAL-10 Page 10 ================================================================= 2.0 FOCAL program commands --- ----- ------- -------- A command preceded by a line number is not executed immediately but stored in the FOCAL text buffer area in memory. 2.1 The program text: WRITE, ERASE, COMMENT, MODIFY --- --- ------- ----- ------ ------ -------- ------ 2.1.1 WRITE ----- ----- The WRITE command lists all or part of the program contained in the FOCAL text buffer area in memory. Arguments, if any, may be "ALL", group number or line number, or a string of these separated by commas. If the first argument is not a line or group number, FOCAL will write a header showing time and date. To list the entire program with a header, type "WRITE ALL", and to list the entire program without a header, type "WRITE 0". 2.1.2 ERASE ----- ----- "ERASE" deletes the currently defined symbols and their values. "ERASE mm", "ERASE mm.nn", "ERASE mm.n1,mm.n3,mm.n4" erases from the program text the group, line, or lines specified. "ERASE ALL" removes the whole program text. An ERASE command contained within a program will be executed. This is useful in programming "once-only" applications, or where you wish to erase a line after executing it. If the command erases itself, the rest of the line won't be executed. Similarly, if a "DO", "FOR" or "LIBRA CALL" (see sections 2.2.4, 2.3.1 and 3.1) was in progress when the line containing it was erased, the rest of the line would be ignored. 2.1.3 COMMENT ----- ------- Beginning a command with the letter C will cause the remainder of that line to be ignored. FOCAL-10 Page 11 ================================================================= 2.1.4 MODIFY ----- ------ The "MODIFY" command enables alteration of part of a line. To alter line mm.nn, type "MODIFY mm.nn" followed by carriage return. FOCAL types a bell and awaits a character (the search character). Choose a suitable character in line mm.nn for FOCAL to use as a search character, and key it in. FOCAL will type out the line up to and including the first occurrence of the search character. At this position in the line you may perform any of the following functions: * Insert characters by typing them in. * Delete characters to the left one at a time with the RUBOUT or BACKSPACE keys, or all to the left with control-U (^U). * Delete all the line to the right by pressing carriage-return. * Proceed to the next occurrence of the search character by typing control-L (form-feed). * Change to a different search character by typing control-G (bell) followed by the new character. * Preserve the line as modified by typing a line feed. * Abort the modification by typing control-P. * Display the line to the left (cleaned up) by typing control-R. Technical notes: a. A "MODIFY" command may be included in a program, but if the object line contains an active "DO", "FOR" or "LIBRA CALL" (sections 2.2.4, 2.3.1, 3.1) then the rest of the line won't be executed. For example: 32.22 TYPE X; DO 34.44; TYPE Y 34.44 MODIFY 32.22 The execution of line 32.22 can never proceed beyond the second semicolon, no matter what the MODIFY command does. b. The "MODIFY" command will not work exactly the same on a half-duplex terminal. The printing of the search character is by hardware and so cannot be suppressed by software. Also, rubbed-out characters are printed with a back-slash before each one, rather than as a group inside back-slashes as on full-duplex terminals. c. Input-end-of-file has the same effect as line-feed. d. The line number itself cannot be altered in any way by the "MODIFY" command. If this is required, the line must be inserted again by re-typing. An empty line will be deleted. FOCAL-10 Page 12 ================================================================= 2.2 Program directives: QUIT, GO, GOTO, DO, RETURN --- ------- ----------- ----- --- ----- --- ------ 2.2.1 QUIT ----- ---- The "QUIT" command terminates execution, FOCAL then awaits further commands from the current input device. If the keyboard is the current input device, a * cue will be given. (Emergency stops - section 7). 2.2.2 GO ----- -- The "GO" command (or "GOTO") without an argument is interpreted exactly as "DO ALL". (See 2.2.4 below). It will therefore start executing at the beginning of the FOCAL program, and if the "GO" is part of the program or a LIBRA-CALL file, that program or file will be continued when the "DO ALL" finishes. 2.2.3 GOTO mm.nn, GO TO mm.nn ----- ---- ------ -- -- ----- The "GOTO" command may be followed by a line number (mm.nn). In this usage "GOTO" may be written as two separate words. The "GOTO" command effectively causes the line to which it points (object line) to be interpreted as a continuation of the line containing the "GOTO" command. Action at the end of this "object line" depends on which of the following occurred most recently and is still not completely executed (see sections 2.2.4, 2.3.1, 3.1 for details): DO-line The DO is concluded. DO-group, GOTO outside group The DO is concluded. DO-group, GOTO within group Execution continues to the end of the group. DO ALL Execution continues to end of program. FOR The next iteration is begun. LIBRA CALL Execution continues to end of program, then LIBRA CALL file is continued. None of these Execution continues to end of program. FOCAL-10 Page 13 ================================================================= 2.2.4 DO ----- -- "DO" or "DO ALL" means execute all lines of the program text. "DO mm.nn" means execute the line mm.nn "DO mm.0" or "DO mm" means execute the lines of group mm. Control returns to the command after the DO when execution has been completed as specified or when a "RETURN" command is encountered. Lines of the form DO mm.nn;DO m2;DO mm.n2 may be written as DO mm.nn, m2, mm.n2 2.2.5 RETURN ----- ------ The "RETURN" command has the following effects: During a "FOR" command (section 2.3.1), iteration continues as though end-of-line was reached. During a "DO" command, control returns as though the limit of the DO (end of line, end of group, end of text) had been reached. During a "LIBRARY CALL" command (section 3.1), the remainder of that file is ignored. If none of the above commands is in progress, execution terminates as for a QUIT command. If any of the above commands are nested, RETURN only affects the most recent of the nested commands. FOCAL-10 Page 14 ================================================================= 2.3 Program loops and branches: FOR, IF --- ------- ----- --- --------- ---- -- 2.3.1 FOR ----- --- "FOR X=A,B,C;commands" The commands are executed with X=A. X is then incremented by B and the following test is made: If B is positive or zero, is X greater than C? If B is negative, is X less than C? If the answer is no, the loop is continued (commands executed, X incremented again, test X again). If the answer is yes, control passes to the next statement. If there are only two arguments, B is assumed to be 1. If B is zero, and C is greater than A, the loop will repeat indefinitely. If there are more commands than will fit on one line, continue the line with a GOTO or DO-line, or use a DO-group command. Note that the parameters A, B and C are computed only once, before the beginning of the first loop. 2.3.2 IF ----- -- 2.3.2.1 Arithmetic IF ------- ---------- -- "IF(x)m1.n1,m2.n2,m3.n3" "IF(x)m1.n1,m2.n2;commands" "IF(x)m1.n1;commands" where x is a defined numeric symbol, value, or expression. If x < 0 control passes to line m1.n1 If x = 0 control passes to line m2.n2 If x > 0 control passes to line m3.n3 Where m2.n2 or m3.n3 is not specified, the commands on the IF line are executed. 2.3.2.2 Logical IF ------- ------- -- "IF(x);commands" where x is a logical expression. The commands are executed if the logical expression is true. A logical expression consists of a pair of numeric expressions or a pair of FOCAL-10 Page 15 ================================================================= string expressions separated by a logical operator. The logical operator may be one of the following: = (test for equality) # (test for inequality) .EQ. ) .NE. ) .LT. ) .LE. ) comparative operators (must be upper case) .GT. ) .GE. ) The programmer must ensure that ambiguous cases such as 1.NE.2 are eliminated by using spaces or extra periods. Ambiguities will arise if command scanning would allow a character to be interpreted from the left as part of a number whereas the programmer intended a logical operator. For example in the case 1.NE.2, the N is regarded as 14 in the first decimal place, E is regarded as the exponent indicator, and .2 is the power of ten used, so it can make a legal number. Remove the ambiguity by using 1..NE.2 or 1 .NE.2 instead. FOCAL-10 Page 16 ================================================================= 2.4 SET --- --- See section 1.0 for an introduction to the SET statement. The SET command may be used to assign values to any symbol. If the symbol contains a terminating $ sign, (e.g. ABC$(5,4) or X$) then the symbol refers to a string variable, but otherwise the symbol refers to a numeric variable. The SET command takes the form: sym = expr where sym is a variable name and expr is an expression of the same type. A string variable can only be assigned the value of a string expression, and a numeric variable can only be assigned the value of a numeric expression. String expressions may be formed by combining string variables with string constants, using the string-concatenation operator "+". For example: SET SV$(4) = SV$(4)+"TODAY" Technical notes: a. The setting of a symbol to zero is insufficient to place a new entry in the symbol table. To ensure that a symbol is placed in the symbol table it must be assigned a non-zero value. 2.5 XECUTE --- ------ "XECUTE EXPR" will evaluate the expression EXPR and discard the result. It has the same effect as SET DUMMY=EXPR and is used in cases where a function is to be called without requiring any value to be returned. FOCAL-10 Page 17 ================================================================= 2.6 TYPE --- ---- See section 1.0 for introduction to "TYPE". The "TYPE" command may be used to output numbers, values, expressions, text, or the contents of the symbol table. To cause carriage-return and linefeed after typing, terminate the command with the exclamation mark(!). To cause carriage-return only, terminate with hatch (#). When outputting text, enclose the text in double quotes. 2.6.1 TYPE "text" ----- ---- ------ All material within the quote marks is typed out. The quote marks themselves are not typed out. The text may include single quotes and must be all on one line. If there are no closing quote marks, the command will type out everything up to the end of the line. 2.6.2 TYPE 'text" ----- ---- ------ A double quote is typed out followed by the text, which may be null. If you want to type out some text enclosed in double quotes, you should use the form: TYPE 'text"'" Note: This feature may be removed at a later date to provide compatibility with PDP-11 FOCAL. 2.6.3 TYPE $ ----- ---- - The symbol table is typed in alphabetical order. For example: S I = 6.0000 S J = 6.0000 S PI = 3.1415 S X = 3.0999 S Y = 22.4000 S Z(43) = 126.0000 S FOO$ = "Hi there!" 2.6.4 TYPE $$ ----- ---- -- The symbol table is typed in the same way as for TYPE $, but the octal value of the symbol is commented on to the table thus: FOCAL-10 Page 18 ================================================================= S I = 6.0000 ;C 203600000000 000000000000 S J = 6.0000 ;C 203600000000 000000000000 S PI = 3.1415 ;C 202622077325 021026430215 S X = 3.0999 ;C 202614623027 301573224215 S Y = 22.4000 ;C 205546314631 231463146315 S Z(43) = 126.0000 ;C 207770000000 000000000000 S FOO$ = "Hi there!" 2.6.5 TYPE /nn ----- ---- --- To select another output channel, give the command TYPE /nn, where nn is a decimal number less than 16, representing a channel which has previously been initialized for output (see section 4). If zero is selected, the controlling terminal will be used for output. Once a channel has been selected for output, all output generated by TYPE and WRITE commands will be directed to that channel. 2.7 Typeout of numeric results --- ------- -- ------- ------- When FOCAL types out numeric results, the format may be either of the following: F-format 3672.4906 or E-format 0.3672E+4 FOCAL is initially set to type out results in F-format with up to eight digits, four to the left of the decimal point (the integer part) and four to the right of the decimal point (the fractional part). This format is %8.04. Leading zeroes are suppressed and spaces are shown instead. Trailing zeroes are always printed. FOCAL-10 will use F-format if it is legal and the value does not exceed the maximum allowable by the current F-format specification. E-format will be used otherwise. To force the use of E-format the command TYPE % may be given (equivalent to %00.00). FOCAL-10 Page 19 ================================================================= 2.7.1 TYPE %mm.nn ----- ---- ------ To change the F-format specification, use the command TYPE %mm.nn where mm is the total number of digits including any leading spaces, and nn is the number of digits to the right of the decimal point including trailing zeroes. (nn may be either blank or two digits but not one digit.) If nn is zero or blank, the data will be printed as integers without a decimal point. If mm.nn is zero or blank, the data will be printed in E-format. If the F-format specification is changed, the changed format will remain operative until reset by the user. For example: *SET A=-12.34;TYPE A;TYPE %2,A;TYPE %,A;TYPE A;TYPE %8.04,A = -12.3400=-12=-1.2340E+1=-1.2340E+1= -12.3400* * Rule: mm must be greater than or equal to nn. F-format is initially set at %8.04. 2.7.2 TYPE %Emm.nn ----- ---- ------- To change the E-format: nn is the number of decimal places (and must be specified as two digits). Rule: mm must be greater than nn by at least 1. E-format is initially set at %E5.04. FOCAL-10 Page 20 ================================================================= 2.8 ASK --- --- ASK X,Y,Z When this command is encountered during execution, FOCAL types a colon (:). (The : may be suppressed - See section 8.4) The user then types a value for the first symbol (X), followed by a comma, carriage-return, line-feed, alt-mode, escape or space. Leading spaces are ignored before numeric values. FOCAL then types another colon and so on until all symbols in the ASK statement have been given values. If the ASK statement had been written as ASK "x,y,z?" X,Y,Z the text x,y,z? would have been typed out before the first colon. If a string is being asked for, it must be terminated by carriage-return or line-feed. If the user types a value followed by an escape, or just an escape by itself, then the symbol retains its original value. (Escape and alt-mode have the same effect.) Characters may be rubbed out individually with the RUBOUT or BACKSPACE keys. If a space is rubbed out, then leading spaces are once again acceptable (i.e. ignored). If all the characters were rubbed out before RUBOUT or BACKSPACE was struck, FOCAL would echo ^U, CR, LF and the colon cue again. You may display the cue and cleaned-up line-so-far by typing control-R. If a control-P is typed, the program will be aborted, since control-P has the effect of an instantaneous "QUIT". Thus a program loop containing an "ASK" can be broken by typing control-P, and the program will be terminated as though the "ASK" command had been a "QUIT" command. It should be noted, however, that if the ASK arguments were enclosed in question marks, then the debug switch will remain on. Technical Notes: "Leading space" includes any "non-wake-up" character with ASCII value less than space. Input-end-of-file has the same effect as line-feed. During an ASK command, output data will never go anywhere but to TTY. However, output is generated only if the currently-selected input channel (see section 4) is TTY. FOCAL-10 Page 21 ================================================================= 2.8.1 ASK /nn ----- --- --- To select another input channel, give the command ASK /nn, where nn is a decimal number less than 16, representing a channel which has previously been initialized for input (see section 4). If zero is selected, the controlling terminal will be used. Once a channel has been selected for input, FOCAL will expect all input to come from that channel, including commands and data. FOCAL-10 Page 22 ================================================================= 3.0 LIBRA Commands --- ----- -------- 3.1 LIBRA CALL --- ----- ---- A previously written program is recalled from a file - either program or immediate-mode commands or both. The whole file is read into memory before its data is used in any way. If you are using the LIBRA CALL command to replace a program already in the text buffer, you should first give the "ERASE ALL" command, so that the old text buffer is removed; otherwise the new program is superimposed on the old. The FOCAL-10 LIBRA CALL is akin to BASIC-10's "WEAVE" command. 3.2 LIBRA DELETE --- ----- ------ The file specified is deleted from the device. 3.3 LIBRA SAVE --- ----- ---- All or part of the program text may be saved as a file. If no list is specified on the LIBRA SAVE command, the symbol table is written out as part of the file, so that a subsequent LIBRA CALL will restore the symbols as well as the program. FOCAL will perform a backup function if LIBRA SAVE is given for an already-existing file name. The existing file will be renamed to *.BAK, and the name will be given to the newly created save. [The backup feature is not available for KA-10 double-precision FOCAL.] 3.4 Format of LIBRA commands --- ------ -- ----- -------- LIBRA func dev:file.ext [proj,prog] list LIBRA is the FOCAL command (may be abbreviated). func is the library function "SAVE" or "CALL" (may be abbreviated.) dev: (optional) is the device name. Only the first six characters are significant. Spaces may not be included. The delimiter ":" must immediately follow the name. If omitted, "DSK" is assumed. file is the filename. Only the first six characters are significant. Spaces may not be included. If omitted, "FOCAL" is assumed. The delimiter ".", if given, must immediately follow the file name. ext (optional) is the file extension. If the delimiter "." is encountered, the program expects a file extension to follow it. However a null extension is allowed, which is indicated by a space following the ".". Only the first three characters are significant. FOCAL-10 Page 23 ================================================================= Spaces may not be included. If no file extension is given, the defaults are: CALL: First look for "FCL". If not found, look for a null extension. SAVE: "FCL" is the default extension. [proj,prog](optional) indicates the disk area to be used for the command. (optional)(SAVE function only) is an octal number indicating the protection to be given to the file. Warning: If an error occurs during LIBRA SAVE command, and a pre-5-series monitor is being used, the device is released without renaming to the requested protection. list (optional)(SAVE function only) indicates which lines or groups are to be saved. If omitted, or "all" is specified, the whole program is saved. LIBRA commands may be included in programs, with some restrictions on the LIBRA CALL. LIBRA CALL may not attempt to overwrite the program line which issued the call. On a LIBRA CALL, there must generally be sufficient memory space to hold the whole file because it is read in in its entirety before execution/loading is commenced. (This enables I/O functions to be nested to any depth.) FOCAL-10 Page 24 ================================================================= 4.0 Input and output on other devices --- ----- --- ------ -- ----- ------- Although the controlling terminal is usually selected as the input and output device, this is not essential; in fact it is possible to use almost any DECsystem-10 device for this purpose. To select another input or output device, it must first be initialized, and the following set of commands performs both the initialization and selection functions. 4.1 Input and output channels --- ----- --- ------ -------- DECsystem-10 software allows programs like FOCAL to associate up to 16 (decimal) devices or files with the program, and each such association is called a "channel". In FOCAL, the controlling terminal uses channel zero, the LIBRA commands use channel one, and the other channels are available for file input and output. The channels are numbered in decimal from 0 to 15. In FOCAL it is not possible to use a single channel for both input and output simultaneously, and attempts to do so will result in the first selection being cleared. (The controlling terminal, however, can have both input and output on the same channel). In FOCAL, when a certain channel has been selected for input, then all input, (commands and data) will be taken from that channel. This applies to such commands as ASK, MODIFY, and input subsequent to the QUIT command. In FOCAL, when a certain channel has been selected for output, then all subsequent output from WRITE and TYPE will be directed to that channel. 4.2 Input device initialization --- ----- ------ -------------- The command: OPERATE INPUT dev:file.ext[prj,prg]/m initializes the specified file on channel n, and selects channel n for input. Defaults are used if necessary as specified below. Channel 1 is used for the LIBRA command, and is therefore unavailable for input in other ways. FOCAL-10 Page 25 ================================================================= 4.3 Output device initialization --- ------ ------ -------------- The command: OPERATE OUTPUT dev:file.ext[prj,prg]/m is used to initialize a file for output on channel m and select channel m for output. Defaults are used if necessary as specified below. Channel 1 is used for the LIBRA command, and is, therefore, unavailable for output in other ways. 4.4 Releasing a device --- --------- - ------ The most convenient method for releasing a device/file from a channel is to attempt to initialize device "TTY" on that channel. This will automatically release the channel because the device "TTY", being the user's console is always assigned to channel zero. 4.5 Defaults --- -------- dev: DSK file FOCAL .ext .LST for output. .FCL for input, but if the file is not found, look for a null extension. /m 2 for output. 3 for input. 4.6 Differences between OPERATE INPUT and LIBRA-CALL --- ----------- ------- ------- ----- --- ---------- At the end-of-file, the LIBRA-CALL will continue the program which called it; when the OPERATE INPUT file reaches the end, FOCAL will exit. The QUIT command will terminate the LIBRA-CALL but not the OPERATE INPUT file. The entire LIBRA-CALL file is read into memory first; the OPERATE INPUT file is read in one buffer at a time. FOCAL-10 Page 26 ================================================================= 4.7 Notes on file I/O --- ----- -- ---- --- Errors are typed out and cause reversion to keyboard mode, and the output device is released (without on 4-series monitors). At end-of-file, the following action takes place: FCHR(-1) takes the value -1. Input to MODIFY and ASK is as though terminated by a line-feed. Input to the command scanner causes FOCAL-10 to exit after the last command has been executed. While non-keyboard input is in progress, FOCAL suppresses the asterisk cue used to indicate readiness to accept another command. This asterisk is neither typed out nor sent to the output file. FOCAL-10 Page 27 ================================================================= 5.0 The trace feature --- --- ----- ------- The "?" character has special significance when it appears in a string being interpreted by FOCAL. It is ignored except for its action in turning the "debug" feature on and off. When FOCAL is started or re-started, the "debug" feature is inactive. This means that any "?" appearing in the interpreter's input string is able to activate the "debug" feature. When "debug" is active, every character passing through the interpreter is typed out. A second "?" will de-activate the "debug". Any errors will de-activate the "debug". "Appearing in the interpreter's input string" means appearing anywhere within a line number, command, command-modifier or argument but not inside a pair of double quotes as a string constant. The question mark itself is never typed. Lines typed in by the user with line numbers at the beginning ("indirect" commands) are not considered as being interpreted while they are merely being placed in the program. This applies to the LIBRA CALL command too. It is illegal to put a question mark in a line number preceding a line to be placed in a program. In other words you must not type 1.0?1 SET X=5 Warning: If ?? are put around the arguments of an ASK command, then any abnormal action (control-C or control-P) leaves the trace feature activated. FOCAL-10 Page 28 ================================================================= 6.0 Examples of FOCAL programs --- -------- -- ----- -------- .R FOCAL *C THE FOLLOWING IS A SAMPLE SHOWING USE OF FOCAL *C TO WRITE AND RUN A PROGRAM, DEBUG IT AND SAVE IT. *C THE PROGRAM WILL CONVERT DEGREES F TO DEGREES C. * *1.02 ASK "ENTER F",F; DO 2 *1.04 GO TO 1.02 *2.02 SET C =(F-32)*5/9; T "F",F," C",C! *C NOW WRITE OUT ALL *W C-FOCAL v3C(245)-1 1227 15-Jan-74 1.02 ASK "ENTER F",F; DO 2 1.04 GO TO 1.02 2.02 SET C =(F-32)*5/9; T "F",F," C",C! * *C THE PROGRAM AS WRITTEN WILL CONTINUE FOREVER UNLESS *C STOPPED WITH ^C (SEE SECTION 7). *C OTHERWISE WE COULD, *C BY DIRECT COMMAND, RUN A SERIES OF CHOSEN VALUES: *FOR F=34,2,38;DO 2 F= 34.0000 C= 1.1111 F= 36.0000 C= 2.2222 F= 38.0000 C= 3.3333 * *C THE TEXT MAY BE STORED AS A FILE WITH A LIBRA SAVE *L S TEXTF * *C WHICH STORES IT AS TEXTF.FCL ON DISK. * *C SUPPOSE, IN TYPING 2.02, WE HAD WRITTEN 3" INSTEAD OF *C 32, LEADING TO AN ILLEGAL CHARACTER MESSAGE *C *C IF THE CAUSE IS NOT OBVIOUS, USE DEBUG - SECTION 5. *C THE CHARACTER CAUSING THE TROUBLE CAN BE LOCATED. *?DO 2.02 DO 2SET C =(F-3? ?Mismatched parentheses 02.02 SET C =(F-3")*5/9; T "F",F," C",C! ^ * *C THE ERROR MESSAGE TURNS OFF THE DEBUG. * * * *C NOW GET A PROGRAM PREVIOUSLY SAVED AS FILE G1.FCL ON DSK *ERASE ALL;C- USUALLY A GOOD IDEA. *L C G1 *C TO GET A LISTING GIVE COMMAND WRITE, OR WRITE ALL *W FOCAL-10 Page 29 ================================================================= C-FOCAL v3C(245)-1 2123 15-Jan-74 1.01 C-PROGRAM TO TYPE THE VALUE OF PI. 1.02 TYPE %20.17,"PI",4*FATN(1)! 1.03 QUIT * *GO PI= 3.14159265358980672 * *C NOW IF WE HAVE FINISHED, WE CAN TYPE CONTROL-Z *^Z EXIT . FOCAL-10 Page 30 ================================================================= 7.0 Stopping FOCAL --- -------- ----- If FOCAL is waiting for you to type something, you may return to the DECsystem-10 monitor by typing control-C. If FOCAL has tied itself into a loop or if for some other reason you wish to quit during execution, you may return to the DECsystem-10 monitor by typing control-C twice. In either case, you may continue by giving the monitor command "CONTINUE" or re-start FOCAL with the "START" or "REENTER" commands or log off the system with the "KJOB" command (see monitor manual). "START" will give an error message, but "REE" will cause the action of a "QUIT" command to be executed. If you have been doing output ("OPERATE" command), and want to close the output files before finishing, you should type control-Z, which causes FOCAL to exit to the monitor. This is a clean method of closing all files. FOCAL may be saved with the monitor "SAVE" command after typing control-C, but thereafter it cannot be re-started or continued except by the "START" command. All text, symbols and values are retained, but I/O in progress will be aborted. (To save program only see section 3) A re-start will always reset the "FOCAL" function switches. If FOCAL is waiting for you to type a command or to type something during an ASK command, you may abort by typing control-P. This will have the effect of executing an instantaneous "QUIT". 7.1 How to force a FOCAL program to exit --- --- -- ----- - ----- ------- -- ---- You can take advantage of FOCAL's behaviour when it reaches the end of its input file. For example, the following program will exit cleanly: OPERATE INPUT NUL: ;QUIT Alternatively, if input is from the keyboard, control-Z will cause FOCAL to exit. FOCAL-10 Page 31 ================================================================= 7.2 The "REENTER" monitor command --- --- --------- ------- ------- While FOCAL is executing a program, you may wish to abort the current task. To do this, type two control-C's and "REENTER". REENTER has the effect of executing a QUIT command without releasing any I/O devices. FOCAL will continue using the same input device as before; it will take its next command from there and continue execution. FOCAL-10 Page 32 ================================================================= 8.0 Functions --- --------- 8.1 What is a function? --- ---- -- - --------- Certain specific names relate to mathematical functions that take an argument (in parentheses following the function name) and use it to produce a numerical result. For example: *SET X=FSIN(37.5*180/PI) This statement will give X the value represented by the sine of the expression inside the parentheses. If there is no expression in parentheses immediately following the function name (or no parentheses at all), zero will be used as the argument. For example: *SET X=5+FCOS+3 This will use the cosine of zero in evaluating the expression to the right of "=". 8.2 Standard functions --- -------- --------- The standard FOCAL functions, FSIN, FCOS, FATN, FSQT, FEXP, and FLOG are tabulated in section 9.0. Additional functions included are: FLOG10 log to base 10 FSIND sine in degrees FCOSD cosine in degrees 8.3 External functions: FNEW --- -------- ---------- ---- External function - see section 14. FOCAL-10 Page 33 ================================================================= 8.4 Parameters and values internal to FOCAL: FOCAL --- ---------- --- ------ -------- -- ------ ----- If the first argument is in the range 1-18 inclusive, "FOCAL" is a two-argument function capable of modifying the operation of FOCAL itself. The first argument specifies the switch to be modified by its serial number. The second argument provides the value to be inserted. For logical switches, +1.0 means set, -1.0 means clear, and zero means restore to initial setting. The previous setting is returned as the function value. Switch initially if set, switch will ------ --------- -- ---- ------ ---- 1 cleared suppress ":" cue for ASK data 2 cleared suppress "=" prefix to numeric O/P 3 cleared suppress non-fatal error messages. If the first argument is greater than or equal to 23, "FOCAL" is a one-argument function performing a "PEEK" on FOCAL's low segment. The argument is the address in the low segment, and the value returned by the function is a signed 36-bit number which is the contents of that location. Some useful locations are: Address Contents ------- -------- 23-95 Job data area 34 Accumulated error count 36 Highest address in low segment 95 FOCAL's version number 97 Right half holds address of index data block 98 Right half points just below FOCAL's text area 101 Pointer to last character in FOCAL text area 102 Current output channel number 103 Current input channel number 104-151 Sixteen sets of 3-word buffer-headers 152-167 Buffer space pointers - one per channel 168 FORFLG: Current "FOR" line number (right half) 170 Most recent argument of repetitive loop (line number) 172 Current line number 173 LINNUM: Current line number in right half 176 Highest address in the symbol table 177 F-format control 178 E-format control 179 Last random number (floating point) Further details must be obtained from Appendix A. FOCAL-10 Page 34 ================================================================= 8.5 Monitor information: GETTAB(TABNUM,TABINX) --- ------- ------------ --------------------- FOCAL programs may obtain certain information from the DECsystem-10 monitor by the use of the GETTAB function. The FOCAL "GETTAB" function uses the monitor GETTAB UUO which must therefore be available as a monitor service. GETTAB requires two arguments - a table number and a table index. The table numbers and table indices are listed in the monitor manual, but it should be noted that numbers in FOCAL are decimal while the numbers in the monitor manual are probably octal! The answer returned by the monitor is interpreted as a signed 36-bit integer. Single-precision versions of FOCAL are not capable of holding all 36 bits at once. There are no plans to remove this restriction. Examples of GETTAB calls. GETTAB(4,-1) total time used by this job (in jiffies) GETTAB(5,-1) kilo-core-ticks of this job GETTAB(9,8) time of day in jiffies since midnight GETTAB(9,9) today's date (12-bit format) If the GETTAB UUO gives the error return, location .JBERR in the job data area will be incremented, and the GETTAB function will return TABNUM+(TABINX*2**18). 8.6 Random number generator: FRAN --- ------ ------ ---------- ---- Function FRAN will generate a random or pseudo-random number greater than or equal to 0.5 and less than 1.0. The argument determines what kind of random number is given: ARGUMENT RESULT -------- ------ 0 Next in pseudo-random sequence. Positive Restart pseudo-random sequence as for virgin program. Negative True random number FOCAL-10 Page 35 ================================================================= 8.7 Single character I/O: FCHR --- ------ --------- ---- ---- To output a single character with ASCII value q, execute the function FCHR(q), where q is zero or positive. To input a single character, waiting for it if necessary, but not affecting terminal echoing status, use the function FCHR(-1), which will return the ASCII value of the character. If end of file has been passed, FCHR will return the value -1. All negative arguments are treated as -1, but are reserved for future definition, to control echoing, waiting etc. You may use FHIBER(1+2^21) to test whether FCHR(-1) would wait for input or not. FOCAL programs using FCHR for input should include a check for ^P so that users can escape from program loops easily. 8.8 Single character string: FCHR$ --- ------ --------- ------- ----- FCHR$(x) returns a string containing a single character created by taking the value of x modulo 128 as an ASCII value. 8.9 Sleeping and hibernating: FHIBER --- -------- --- ------------ ------ At times it is useful for a FOCAL program to pause for a while during execution. The FHIBER function may be used to do this by specifying the length of pause as the argument (in milliseconds). For example a five-second pause may be introduced by the FOCAL command X FHIBER(5000). There are other ways of hibernating too, such as waiting for certain events to occur, and details may be obtained from the documentation of the HIBER monitor UUO. FHIBER accepts an argument which is treated as a signed 36-bit integer. The 36-bit number so formed is used in an accumulator for the HIBER UUO. For example X FHIBER(5000+2^21) will sleep for 5 seconds or until a character is typed on the controlling terminal - whichever occurs first. As another example, X FHIBER(10000-2^(35)) will cause an immediate swap-out and a pause for 10 seconds. If FOCAL is running under a monitor lacking the HIBER UUO, FOCAL uses the SLEEP UUO, and the FHIBER argument is the number of seconds to sleep, modulo 4096. The value returned by the FHIBER function gives the status of the terminal controlling FOCAL. If the terminal's input buffer is empty, FHIBER returns zero, but otherwise it returns 1.0. This feature is useful when you don't want your program to hang up in "input-wait" state, and can also be used to determine whether the FHIBER sleep was woken by the teletype or not, if you used those particular wake bits in the FHIBER argument. It should be noted that due to FOCAL-10 Page 36 ================================================================= certain idiosyncrasies of the HIBER UUO it may be necessary to include X FHIBER(1) at the beginning of your program to remove a spurious wake-up later on. Execution of the FHIBER function will cause .JBERR to be incremented if the job is detached or TRMNO. UUO is illegal. 8.10 Notes on implementing new functions ---- ----- -- ------------ --- --------- By re-assembling FOCAL, more functions may be included. Function names may be any number of characters of which the first six are significant. Function names need not commence with the letter "F" in FOCAL-10. However, it is suggested that they should, to comply with the rule that reserved words begin with "F". Note: In evaluating an expression, if the interpreter finds a name in the list of functions, then the interpreter takes it as a function name. FOCAL-10 Page 37 ================================================================= 9.0 Function summary --- -------- ------- NAME DESCRIPTION ---- ----------- FSQT Square root FABS Magnitude part FSGN Sign part (i.e. +1.0 or -1.0) FITR Integer part (rounded towards zero) FRAN Random number between 0.5 and 1.0 FEXP Exponential FSIN Sine with argument in radians FCOS Cosine with argument in radians FSIND Sine with argument in degrees FCOSD Cosine with argument in degrees FATN Arctangent (range -PI/2 to +PI/2) FLOG Logarithm FLOG10 Logarithm to base 10 FOCAL Change internal parameters of FOCAL GETTAB Obtain monitor information FNEW External function call FCHR Single character I/O FCHR$ Single character string FHIBER Hibernate or sleep FOCAL-10 Page 38 ================================================================= 10.0 FOCAL command summary ---- ----- ------- ------- ASK X Accepts a value from the keyboard. COMMENT Allows dummy lines in a program. DO mm.nn Executes a line or group as a subroutine. ERASE Wipes the symbol table. ERASE mm.nn Wipes a line (or group) from the program. FOR X=1,.5,20 Loops while incrementing a variable. GO, GOTO Reroutes execution. IF (X) m1.n1,m2.n2,m3.n3 Allows conditional branching. IF NAME$ = "Harry" ;TYPE "Fred." Allows conditional commands. LIBRA CALL Executes a file or loads it if it has line numbers. LIBRA DELETE file Deletes the named file from the users file directory on the disk. LIBRA SAVE mm.nn Writes a line or group as a file. LIBRA SAVE Writes the program as a file. MODIFY mm.nn Allows program editting. OPERATE INPUT file Initializes a new file for input. OPERATE OUTPUT file Initializes a new file for output. QUIT Stops execution. RETURN Terminates subroutine and returns to caller. SET X=Y+3 Assigns a value to a variable. TYPE "Hello",X! Prints data on the terminal. WRITE mm.nn Lists a line or group WRITE ALL Lists the entire program. XECUTE exp Evaluates expression exp and discards the result. FOCAL-10 Page 39 ================================================================= 11.0 Character interpretations by FOCAL ---- --------- --------------- -- ----- Symbol meaning or use ------ ------- -- --- A-Z Used to construct commands, function names and variable names. a-z Lower case letters are treated as upper case letters except when they appear in strings between quote marks. E or e Used to introduce the exponent part of a constant. 0-9 Decimal digits. Used to construct numeric constants and array indices + Arithmetic addition operator. - Arithmetic subtraction operator. * Arithmetic multiplication operator, or part of arithmetic exponentiation operator. / Arithmetic division operator. Also channel-selection indicator (see sections 2.6.4, 4.2 and 4.3). ^ Arithmetic exponentiation operator. ( ) Parentheses. Used to hold array indices, function parameters, and arithmetic sub-expressions. [ ] Parentheses. May be used instead of (). Also to hold project-programmer pairs. < > Parentheses. May be used instead of (). Also to hold file protection code. It is suggested that the use of <> as parentheses should be avoided where possible in FOCAL-10. The present specification provides compatibility of FOCAL-10 with other FOCAL implementations, but a future extension of FOCAL to cover logical operations may require <> for other purposes. , Comma. Used to separate function arguments and command arguments. . Decimal point. Used to construct numbers and logical operators, and also to separate file name from file extension. ; Semicolon. Used to terminate statements. : Colon. Used to delimit device name. = Equals. Used in the construction of the "FOR" and "SET" FOCAL-10 Page 40 ================================================================= statements. Also used as a logical operator. ! Exclamation mark. In the ASK or TYPE statement - cr/lf (see sections 1.0, 2.6 and 2.8). # Hatch. In the ASK or TYPE statement - CR only (see section 2.6). Also used as a logical operator to mean "not equal to". " Double quote. Used to delimit string constants (see section 2.6.1 and 2.4). ' Single quote. Used in the "TYPE" and "ASK" statements to delimit string constants (see section 2.6.2). & Ampersand. Not legal except in text. @ At. Not legal except in text. % Percent. Used in "TYPE" statements to change the format (see sections 2.7.1, 2.7.2). $ Dollar. Used in "TYPE" statements to cause output of the symbol table (see section 2.6.3). Also as the delimiter of a string name. $ Escape. May be used to terminate a command in the same way that a carriage-return does. _ Backarrow. Not legal except in text. ? Question mark. Used to turn the "trace" feature on and off (see section 5). ^C Control-C. This is a monitor-call request. It suspends FOCAL and puts the terminal into monitor mode. (Two control-C's may be required if a program is running.) ^P Control-P. If FOCAL encounters a control-P in input data, it will execute a QUIT command. ^R Control-R. During type-in you can display the line-so-far by typing control-R. The cue will precede it at the beginning of the line. ^U Control-U. Never appears in FOCAL text. Used from the keyboard to erase the whole of the current input line. ^Z Control-Z. FOCAL-10 will EXIT if you type control-Z on the keyboard during keyboard input. RUBOUT Never appears in FOCAL text. Used from the keyboard to erase the most recent character from the input line. FOCAL-10 Page 41 ================================================================= BACKSPACE Never appears in FOCAL text. Used from the keyboard to erase the most recent character from the input line. FOCAL-10 Page 42 ================================================================= 12.0 Compatibility of FOCAL implementations. ---- ------------- -- ----- ---------------- Historically, the raison-d'etre of FOCAL was the need for a powerful interpreter in a minimal core size. The language was designed to allow the implementer to take short cuts in coding by restricting the freedom of the language to a certain extent, and many of these restrictions remain in the small-computer FOCALs today. Recent enhancements, particularly in the PDP-11 versions, have enabled FOCAL to be used as a software operating system to drive special hardware, and we see FOCAL-GT, FOCAL-11/RTX etc. with large sets of special functions for special hardware. The problem for the user, however, is the increased complexity of the language introduced by such enhancements, and the confusion which new incompatibilities introduce. The intent of the following section is to serve as a guide to the differences between FOCAL implementations, to assist the user who changes machines or who wishes to allow himself full flexibility. 12.1 General differences. ---- ------- ------------ The following list illustrates incompatibilities which arise because of the environment such as word size, software operating system and interfacing. 12.1.1 Always different. - Accuracy. Every implementation of FOCAL uses a different internal storage method and therefore the number of significant figures varies. - Loading, starting and re-starting. This is always machine-dependent. - Error messages. Each FOCAL has its own set of error messages. 12.1.2 OPERATE command. Paper-tape-only systems usually have a * command. More sophisticated systems use the OPERATE command with a single letter as argument. Under a high-level disk operating system, a high-level OPERATE command is used. 12.1.3 Function list. All FOCALs have certain functions specific to themselves. There is no standard for the range or distribution of the FRAN function, nor for the meaning of its argument. 12.1.4 LIBRA command. Not all FOCALs have this command. Those which do usually have LIBRA CALL and LIBRA SAVE; some have more options. 12.1.5 Character set. Most FOCALs use ASCII-1968 (ANSI X3.4-1968) with a few FOCAL-10 Page 43 ================================================================= minor variations. 12.2 PDP-8 FOCAL. ---- ----- ------ 12.2.1 Implementation characteristics. - The fundamental interpreting process is fairly simple. FOCAL-8 will almost always scan until a "terminator" is found, skip over the terminator and then perform the function. This requires that all commands be delimited by a space or similar "noise character", since the interpreter will not backspace over it when it continues after performing the command. In a few cases this may lead to problems unless liberal spacing is allowed. The Technical Specifications (para 2.1.3) does not actually define "terminator". - Additional terminators for ASK data are allowed beyond space, comma, carriage-return, line-feed and escape. - Arithmetic expressions must be terminated by a comma. - WRITE disables trace. - WRITE .., MODIFY .., ERASE .., TYPE $ cannot be followed by ;commands. - Line numbers only extend to 31.99. - Format descriptors are limited to 19.19. - Symbols are held as two characters. 12.2.2 OPERATE command. FOCAL-8 uses the * command which is incompatible with the more usual OPERATE command because of its usage and handling of end-of-file. 12.2.3 Function list. FOCAL-8 has all standard functions. 12.2.4 LIBRA command. The LIBRA version of FOCAL-8 has this command, including LIBRA LIST, but it is not necessarily compatible with other FOCALs. 12.2.5 Character set. Uses ASCII-1963. Altmode is non-printing. Characters 175 176 and 33 octal are treated as altmode. Backarrow is used instead of ^U. The rubout key is handled differently from most FOCALs. FOCAL-10 Page 44 ================================================================= 12.3 PDP-12 FOCAL. ---- ------ ------ 12.3.1 Implementation characteristics. FOCAL-12 is an expansion of FOCAL-8. The extensions are principally for utilizing the PDP-12 peripheral devices including LINC tape. 12.3.2 OPERATE command. FOCAL-12 uses a command called "OUTPUT" which is similar to an "OPERATE" command. It is used to change the output device (O S and O T), but it also has some unrelated functions (O D to display or to indicate the display refresh rate; O E and O C to clear all or part of the display screen; O I to do timing). Some of the functions normally associated with the OPERATE command are performed by the LIBRA commands in FOCAL-12 (see below). 12.3.3 Function list. FOCAL-12 functions are very similar to FOCAL-8 functions. 12.3.4 LIBRA command. LIBRA SAVE and LIBRA LOAD in FOCAL-12 are the traditional commands to save and recall FOCAL programs (LIBRA SAVE and LIBRA CALL in FOCAL-10). The command LIBRA GO in FOCAL-12 is a convenience to facilitate chaining of FOCAL programs. (In FOCAL-10 this would be done by using LIBRA CALL;GO). In FOCAL-12 LIBRA LOAD and LIBRA GO imply prior ERASE ALL and ERASE. This means a WEAVE is not possible. In FOCAL-10 you would use ERASE ALL,;LIBRA CALL etc. to simulate the FOCAL-12 LIBRA LOAD. FOCAL-12's LIBRA MAKE is used to allocate a space on the file storage device for use as random-access storage. The space is used by opening (LIBRA OPEN), referencing (Fn(mm)), and closing (LIBRA CLOSE) such a random-access area. In FOCAL-10 this kind of operation would be done by using normal FOCAL variables, since large amounts of core storage are usually available. The array could be saved and recalled from disk with the usual LIBRA SAVE and LIBRA CALL commands or by explicitly writing the array with the TYPE command. 12.3.5 Character set. Uses ASCII-1963. Altmode is non-printing. Characters 175 176 and 33 octal are treated as altmode. Backarrow is used instead of ^U. FOCAL-10 Page 45 ================================================================= 12.4 DECsystem-10 FOCAL ---- ------------ ----- 12.4.1 Implementation characteristics. 12.4.1.1 ** may be used for exponentiation. 12.4.1.2 Variable names may be any number of characters, of which the first three are significant, and the first must be a letter. (It may be "F") [In evaluating an expression, if the interpreter does not find a name in the list of functions, then it takes it as a variable name.] 12.4.1.3 Any non-alphanumeric can be used to delimit, and FOCAL-10 (in contrast to FOCAL-8) will interpret the delimiter. For example, TYPE"ABC" will work in FOCAL-10 as if it had a space after the E. 12.4.1.4 Arrays may be multiple-dimensioned. Elements of an array are written as the array name followed by the list of subscripts in parentheses, each separated by commas. It is up to the user to remember to specifically cite the exact number of subscripts each time an element is referenced, otherwise wrong values may be used. The subscripts are evaluated and used modulo a certain value which depends on the total number of subscripts. The following table describes the array element successor function, the combined subscript value, and the modulo applicable to each subscript. Number of Subscripts Subscript Modulo Subscripts Value none none 0 - 1 (a) a 262144 2 (a,b) a+512*b 512 3 (a,b,c) a+64*b+4096*c 64 4 (a,b,c,d) a+16*b+256*c+4096*d 16 5 (a,...e) a+8*b+...+4096*e 8 6 (a,...f) a+8*b+...+32768*f 8 7 (a,...g) a+4*b+...+4096*g 4 8 (a,...h) a+4*b+...+16384*h 4 9 (a,...i) a+4*b+...+65536*i 4 10 (a,...j) a+2*b+...+512*j 2 11 (a,...k) a+2*b+...+1024*k 2 .... ..... ...... 2 18 (a,...r) a+2*b+...+131072*r 2 19 or more (a,b,...) 0 - 12.4.1.5 Replacement of an active line. If while a line is being executed a replacement is inserted, FOCAL-10 will behave as if the line were first erased and then a new one inserted. For example: FOCAL-10 Page 46 ================================================================= 2.22 2.22 The quick brown fox will effectively erase itself. Also the program: 2.22 DO 4.44; TYPE Y 4.44 2.22 DO 4.44; TYPE Y will never execute beyond the semicolon. 12.4.1.6 The symbol table is typed in alphabetical order. FOCAL-10 has the capability (TYPE $$) to include octal in the symbol-table printout. The symbol table is not destroyed unless explicitly ERASEd; some small computer FOCALs use the symbol table space during immediate-mode commands. 12.4.1.7 GO TO may be two words. 12.4.1.8 ASK data may have leading spaces. 12.4.1.9 Negative FOR indices are allowed. 12.4.1.10 FOCAL-10 has no computed GOTO. 12.4.1.11 FOCAL-10 has no FSBR function. The reason for this is that the character & is reserved for future expansion in FOCAL-10. 12.4.1.12 The FCHR function does not have multiple arguments. The reason for this is that expansion plans call for control of echoing, which is difficult for multi-argument FCHR. FCHR should be called once for each desired argument. 12.4.1.13 FOCAL-10 does not have a control character to interrupt execution. This is a monitor restriction. It has been suggested that control-C might have been used, but control-C, in my opinion, should be used only to return to monitor mode, and it is not possible to use it for two purposes. 12.4.1.14 FOCAL-10 allows string values. 12.4.1.15 FOCAL-10 allows logical IF. 12.4.2 OPERATE command. The asterisk (for paper-tape mode) is not used in DECsystem-10 FOCAL. 12.4.3 Function list. Unique FOCAL-10 functions include GETTAB, FOCAL, FSIND, FCOSD, FLOG10, FHIBER and FCHR$. Some of the standard functions may behave slightly differently on the DECsystem-10. 12.4.4 LIBRA Command. Only LIBRA CALL, LIBRA SAVE and LIBRA DELETE are FOCAL-10 Page 47 ================================================================= available. There is no LIBRA LIST command and it is unlikely to be implemented, since DECsystem-10 users expect wild-card handling which is very complex and can be obtained with the DIRECT program. If the user desires the FOCAL text area to be cleared before the LIBRA CALL he should execute ERASE ALL first. If the user desires immediate execution following the CALL, he should either arrange to have GO in the called file, or execute LIBRA CALL ..;GO. 12.4.5 Character set. FOCAL-10 uses ASCII-1968. Special character-handling is as follows. - Escape echoes as $, for compatibility with other DECsystem-10 software. - Any control-Z character from the keyboard will cause FOCAL to exit. - Any control-P character in the input file will cause immediate execution of a QUIT. - A control-R from the keyboard will display the cue and first part of the input line. - Lines are delimited by line-feed only. Escape (33 octal) is always changed to line-feed except in the ASK data; carriage-returns are ignored. Other break characters such as form-feed etc. may be used as ordinary characters. - Control-U, rather than backarrow, is used for line deletion. - Rubout echoes the rubbed-out characters embedded in - Backspace is used to rub out. 12.5 PDP-11 FOCAL. ---- ------ ------ 12.5.1 Implementation characteristics. - Only the first two characters of a symbol's name are stored internally. - FOCAL-11 variables can take either one or two subscripts. - FOCAL-11 variables cannot begin with the letter F. - The symbol table print-out always uses two subscripts instead of one. - Care should be taken when using the ASK command. Some versions of FOCAL-11 accept expressions but not alphabetic equivalents of numeric literals (such as "YES"="0YES"). - The rubout key cannot be used while inputting data for the ASK command. - Data tapes require nulls embedded in them. - Care should be taken with the function FITR(-x), since it may not be compatible with your intuitive concepts. - The format-size specifier % can accept an expression as argument. FOCAL-10 Page 48 ================================================================= - The width of E-format printout cannot be varied. - The input line width is limited to 79 characters. (77 for indirect commands.) - The output line width is limited to 71 characters. - The exponentiation operator (^) is restricted to positive integer arguments. - The command ERASE ALL in PDP-11 FOCAL not only erases all text, but it also erases the symbol table; the command ERASE TEXT takes the form ERASE ALL in other FOCALs. - The KILL command is unnecessary in other FOCALs. - Computed GOTO except with expressions that begin with the letter A. - The DO command can accept as argument a variable or a number except a variable that begins with the letter A. - The symbol table is not retained in any particular order. - The maximum total width of numerical type-out is limited. - ASK will print a colon on the terminal even though input is coming from another device. - In the FOR command, if the increment is negative, iterations beyond the second will continue indefinitely because the sense of the looping test is independent of the sign of the increment. This is different from FOCAL-10. 12.5.2 OPERATE command. This has single-letter arguments and hence is not compatible with disk system FOCALs. 12.5.3 Function list. Unique FOCAL-11 functions are FX, FCLK and FSBR. The range of FRAN is from -1 to +1. The argument of FRAN is less generalized than FOCAL-10's FRAN. FSGN(0) is zero instead of +1. FCHR function accepts multiple arguments and treats them as though the function were called multiple times. 12.5.4 LIBRA command. 12.5.5 Character set. Uses ASCII-1963. Altmode is non-printing. Character 175 octal is treated as alt mode(esc). Backarrow is used instead of ^U. Control-C is used as an interrupt character. Rubout echoes as \ in MODIFY commands. 12.6 FOCAL-GT. ---- --------- 12.6.1 Implementation characteristics. FOCAL-GT follows PDP-11 FOCAL in most respects. 12.6.2 OPERATE command. This is the same as FOCAL-11. 12.6.3 Function list. FOCAL-GT has the following unique functions: FVEC, FOCAL-10 Page 49 ================================================================= FMOV, FXCO, FYCO, FPT, FSET, FCLR, FTXT, FSKP, FLP, FSAM, FLED, FDIS, FTIC. 12.6.4 LIBRA command. 12.6.5 Character set. Uses ASCII-1963. FOCAL-GT prompts with # rather than *. Control-C is used to escape from the display program. Control-T and Control-F have special functions. Altmode is non-printing. Characters 175, 176 and 33 octal are treated as altmode. Backarrow is used instead of ^U. 12.7 FOCAL-11/RTX. ---- ------------- 12.7.1 Implementation characteristics. FOCAL-11/RTX is very similar to PDP-11 FOCAL. - FOCAL-11/RTX has an option on the TYPE command to provide a facility like FORTRAN's T-format. TYPE 'mm brings the carriage to column mm. - All commands must be delimited by a space. - There is a BLOCK command but its purpose is obscure. 12.7.2 OPERATE command. 12.7.3 Function list. Unique FOCAL-11/RTX functions are FWT, FZCL, FTIC, FDI, FDO, FTR, FADC, FDAC, FDT, FTI, FTO, FLED, FSAM, FSCD, FOCAL, FINT and FATR. The FOCAL function is incompatible with FOCAL-10's function of the same name, since FOCAL-11/RTX does not allow you to leave a parameter unchanged or to find out what its previous setting was. 12.7.4 LIBRA command. 12.7.5 Character set. Uses ASCII-1963. Altmode is non-printing. Characters 175 176 and 33 octal are treated as altmode. Backarrow is used instead of ^U. 12.8 FOCAL-G11. ---- ---------- 12.8.1 Implementation characteristics. FOCAL-G11 is an implementation of FOCAL designed to work with the GAMMA-11 system. FOCAL-G11 follows PDP-11 FOCAL in most respects. The UTILITY command performs a data interface function with the GAMMA-11 Save registers. The ASK command has been slightly modified in FOCAL-G11 to allow comment material on data tapes. TYPE $ is not included in FOCAL-G11. 12.8.2 OPERATE command. This is the same as FOCAL-11. 12.8.3 Function list. FOCAL-G11 has the following unique functions: FMPAR, FMATG, FMATD, FMATS, FMATW, FMATB, FMATSM, FRPAR, FROIG, FOCAL-10 Page 50 ================================================================= FROID, FROIP, FROIC, FNCR, FPICK. FOCAL-G11 contains the standard functions FEXP and FLOG. 12.8.4 LIBRA command. FOCAL-G11 LIBRA command is similar to DECsystem-10 LIBRA except that it does not include ppn or protection facilities. FOCAL-G11 has a LIBRA LIST command, which DECsystem-10 FOCAL does not. FOCAL-G11 LIBRA CALL reads the entire program in as a block and destroys the old program. 12.8.5 Character set. Uses ASCII-1963. Control-L is used to enter FOCAL-G11, and control-S is used to leave FOCAL-G11 and return to GAMMA-11. Altmode is non-printing. Characters 175, 176 and 33 octal are treated as altmode. Backarrow is used instead of ^U. 12.9 PDP-15 FOCAL. ---- ------ ------ 12.9.1 Implementation characteristics. - Since the PDP-15 console Teletype is wired for half-duplex operation, various commands such as MODIFY will appear differently on the PDP-15. - FOCAL-15 uses a concept of "COMMON" to allow certain variables to be retained permanently and not be erased during the ERASE command or during MODIFY. - MODIFY erases the symbol table. - MODIFY uses alt-mode instead of form-feed. - Because only LINES are acceptable as data for the ASK command, a comma or space will not terminate the ASK command. - Commands to FOCAL-15 may be spelled in full or abbreviated to a single letter, but may not be partially abbreviated or misspelled. - ERASE ALL will erase the symbol-table too. - FOCAL-15 allows only a single subscript in arrays. - Symbols may not begin with the letter F. - Only a single E is permitted in numbers. This is realistic but may represent a minor difference from other implementations. - Exponents can be used to + or - 999. - Exponentiation can be performed only with positive integers. i.e. in m^n, n must be a positive integer. - FOCAL-15 does not use the equal sign (=) during numeric print-out. - The format of symbol-table print-out does allow for reading it back in through the paper-tape reader. - Output lines are limited to a width of 72 characters. - The width of the E-format printout cannot be varied. 12.9.2 OPERATE command. FOCAL-15 uses the * command which is incompatible with the more usual OPERATE command because of its usage and handling of end-of-file. FOCAL-10 Page 51 ================================================================= 12.9.3 Function list. FOCAL-15 has all the standard functions. However, FRAN has a different range and is by no means random. ("Most numbers are positive.") 12.9.4 LIBRA command. FOCAL-15 has a complicated set of LIBRA commands but they essentially perform just the standard LIBRA SAVE and LIBRA CALL functions. It is necessary to perform the LIBRA SAVE function in three steps - LIBRA OUT, LIBRA WRITE, and LIBRA CLOSE. A slight advantage here is that the LIBRA WRITE can actually perform editting operations such as prefixing an ERASE ALL to the file or suffixing a GO to the file. On FOCAL-10 this could be done in a more complicated way or else they could be done at calling time with a command such as ERASE ALL,;LIBRA CALL FILNAM;GOTO 55.46. The LIBRA IN command of FOCAL-15 is the same as FOCAL-10's LIBRA CALL except that the * command apparently terminates reading the file. 12.9.5 Character set. Uses ASCII-1963. Altmode is non-printing. Characters 175 176 and 33 octal are treated as altmode. Backarrow is used instead of ^U. ^U echoes as "@". FOCAL-10 Page 52 ================================================================= 13.0 Error diagnostics ---- ----- ----------- All errors occurring during execution of a FOCAL program will be counted in .JBERR (location 34 decimal) and may or may not cause an error message to be printed. 13.1 Fatal errors ---- ----- ------ Certain errors will not allow execution to continue. These errors are flagged with a question mark (?). 13.2 Non-fatal errors ---- --------- ------ Certain errors may occur which, although representing a failure of logic, accuracy, etc., will allow execution to continue if desired. These are flagged by a percent mark (%), and execution continues as best it can. Arithmetic underflow and overflow are fixed by making the best approximation and other operations leading to errors are treated by ignoring them. If desired, the messages from these errors may be suppressed. (See section 8.4) 13.3 Format of error print ---- ------ -- ----- ----- Error messages are typed in the following format: ? ?Error diagnostic mm.nn this line was in error ^ except where an immediate-mode command was involved in which case mm.nn is omitted. The up-arrow points to the place where the interpreter discovered the error. FOCAL-10 Page 53 ================================================================= 13.4 List of error diagnostics ---- ---- -- ----- ----------- Cannot find FOCAL.SHR on DSK: or SYS: or NEW: or OLD:. Error detected by FNEWGO routine in FOCALL.REL. In loading FNEW with FOCALL.REL, and executing at the normal starting address, a routine called FNEWGO is invoked, which tries to set up the high segment. FNEWGO tries to find FOCAL.SHR on various places on the disk, and fails if FOCAL.SHR or FOCAL.EXE cannot be found on the user's disk or on SYS or NEW or OLD. Channel not correctly INITted In order to select a channel with a TYPE command it must have previously been initialized for output, and to select a channel with an ASK command it must have been initialized for input. ENTER error # This file name cannot be used to write on the device. Perhaps the DECtape directory has 22 file names in it or you cannot enter this particular name in the disk UFD. - The monitor manual will explain the meaning of the octal number code. Floating-point overflow Result of an arithmetic operation (e.g. Divide by zero) produced a number greater than the computer could handle. The result was replaced by the nearest approximation and execution continued. Floating-point underflow Result of an arithmetic operation produced a number smaller than the computer could handle. Zero was used instead, and execution continued. Remember that the "FOCAL" function can be used to suppress the printing of this warning message, so it won't mess up your output. FOCALL.REL and FOCAL.SHR are different versions. This is a warning message, indicating that the procedure in FOCALL.REL which found FOCAL.SHR on either DSK or SYS or NEW or OLD could not find a version which exactly matched the requirements of FOCALL.REL. Checks are made on the version number and on a core location towards the end of the high segment. It is likely that this warning message will be followed by a fatal error such as Illegal UUO, indicating that the attempt to continue did not succeed. Illegal command One of - Unrecognizable command name (first letter unrecognizable) Unrecognizable LIBRA option (not CALL, SAVE or DELETE) Illegal format (ignored) That particular format specifier was not legal. Remember that two digits may be required after the decimal point. Also remember that the number before the decimal point must be larger than the number after it. In any event your specification was ignored and execution continued. FOCAL-10 Page 54 ================================================================= Illegal number A request was made to store a program line with an illegal number, or to use an I/O channel outside the range 0-15 decimal. Illegal variable A "FOR" index, or the argument of a "SET" command, is not a variable name. Imaginary roots required An attempt has been made to take the square root of a negative number. INIT error This device cannot be initialized either because some-one else is using it or you do not have the privilege to do so. Input device error # Probably a parity error. - Consult the monitor manual to find the meaning of the number code, as that may help you to understand why the error occurred. (The number comes from a GETSTS UUO.) Insufficient core The program is probably in an erroneous loop. There is a request for more variables to be set up or more program lines to be entered than the system can handle. Loading error: FOCALL.REL must be loaded first. Error detected by FNEWGO routine in FOCALL.REL. LINK-10 must be instructed to load FOCALL.REL in such a way that the low segment location counter is zero (to start in absolute 140 octal). This is because FOCAL.SHR high segment relies on certain locations in the low segment in much the same way as an overlay does. Loading error: High segment is forbidden. Error detected by FNEWGO routine in FOCALL.REL. In loading and executing FOCALL.REL with FNEW, the high segment space cannot be used by any routine such as FOROTS, because it is going to be used by FOCAL.SHR. FOCALL checks for the absence of a high segment prior to doing a GETSEG on FOCAL.SHR. LOOKUP error # FOCAL cannot find this file name on the device. - Consult the monitor manual to find the meaning of the number code, as that may help you to understand why the error occurred. Mismatched parentheses Either mismatched number of brackets in an arithmetic expression, or mismatched "[" with "]" in project-programmer pair, or mismatched "<" with ">" in protection key field Nonexistant line An "IF", "GOTO", or "MODIFY" command specifies a line number which does not exist. Output device error # For example write-lock on, parity error, tape full, etc. - Consult the monitor manual to find the meaning of the number code, as that may help you to understand why the error occurred. (The number comes from a GETSTS UUO.) FOCAL-10 Page 55 ================================================================= Program re-started Either a previously-run program was saved and re-executed or control-C/START sequence was used. (This is not really an error.) RENAME error # Either during library deletion or at the end of writing a file, there was a protection failure or other kind of failure during a rename UUO. Please consult the monitor manual to determine the meaning of the octal code. Unexpected character FOCAL was expecting either a semicolon or carriage-return (at the end of a command), a "=" (after a "SET" command variable), or a comma (after a project number before the programmer number). String expressions cannot be mixed with numeric expressions. Note: # is the (octal) numerical code returned by the monitor 13.5 Push-down-list Overflow ---- -------------- -------- Occasionally a FOCAL program may enter a loop which causes FOCAL's internal push-down list to fill to capacity. This may be caused, for example, by a program which includes a DO ALL which calls itself. The push-down-list overflow error message (pdl ov) is generated by the monitor, and if it occurs, the user should recover by giving the monitor START command. FOCAL-10 Page 56 ================================================================= 14.0 External function: FNEW ---- -------- --------- ---- If you desire to link FOCAL with some other language, this is done using the FNEW construction. By this method, FOCAL may call a routine or subroutine with an unlimited number of arguments, may execute machine code directly, and may return one numeric result. The arguments are transferred to the subroutine by value only, and it is therefore not possible to modify an argument from the subroutine. Arguments may be numeric (single or double precision) or ASCII string (FORTRAN type 17). The DECsystem-10 standard calling sequence is used. If there is no FNEW routine, a call to FNEW will produce an error message or, if there is only one argument, will give the value of the argument. 14.1 How to load your FNEW program ---- --- -- ---- ---- ---- ------- To use the "FNEW" feature, you must write the FNEW routine itself and compile it. Then load it with the relocatable binary file "FOCALL.REL", making sure that FOCALL is loaded first and that there is no high segment. The core image thus obtained can be executed with the monitor "START" command. then FNEW may be called from a FOCAL program just like any other function. 14.2 Example of an FNEW routine ---- ------- -- -- ---- ------- Here is an example of a FORTRAN subroutine which may be called from FOCAL. The value returned by FNEW will be equal to the number of characters in the string. DOUBLE PRECISION FUNCTION FNEW(I) C FNEW RETURNS THE NUMBER OF CHARACTERS IN A STRING. DIMENSION I(100) FNEW=0 DO 100 J=1,100 M=I(J)/2 DO 100 K=1,5 IF((M.AND."376000000000).EQ.0)RETURN M=M*128 100 FNEW=FNEW+1 END FOCAL-10 Page 57 ================================================================= Here is how you might use this function in FOCAL: .EXECUTE SYS:FOCALL/REL,DSK:FNEW.F4/COMP/F10 ........... *1.01 ASK X$;IF (FNEW(X$)#7) ; GO TO 1.01 *GO :NO :FOO :WORRY :ASK :CORRECT * Note: FORTRAN subroutines must be compiled with ---- FORTRAN-10, not F40. --- FOCAL-10 Page 58 ================================================================= 15.0 Internal representation of numbers --- accuracy ---- -------- -------------- -- ------- --- -------- Data words may be represented internally within the DECsystem-10 in a number of different forms, depending on how FOCAL was assembled. It is normally assembled as double-precision. 15.1 Single precision The DECsystem-10 holds the numbers in 36-bit words, of which 27 bits are fraction and nine bits are exponent. Of the 27 bits, the left-most is always a 1, so there are really only 26 bits of precision, or 26 times log-2-to-base-10 =8 digits. 15.2 Double precision KA-10 There are 26+27 fraction bits, so the accuracy is 26+27 times log-2-to-base-10 =53*0.30103=16 digits 15.3 Double precision KI-10, KL-10 There are 26+35 fraction bits, so the accuracy is 26+35 times log-2-to-base-10 =61*0.30103=18 digits. 15.4 String values. The symbol table holds only a pointer to the string which is stored in a different area of core. FOCAL-10 Page 59 ================================================================= 16.0 Speed of FOCAL ---- ----- -- ----- There are many factors governing the speed of execution of a FOCAL program. The most important thing to realize is that the program itself is stored in source form, i.e. as strings of ASCII characters making up the lines of the program. As the program is executed, FOCAL examines each letter of the program text, deciding what meaning to give to each letter, and then doing whatever is required. For example, if the line contained "SET X= 0", FOCAL would first find the "S", determine that it was therefore a "SET" command, and move the scanning pointer forward past the "E" and "T" until it found the space. Then it would go to the "Symbol-find" routine which would find the "X", determine that it was not indexed, and ensure that it was followed by "=" and skip the "=". A call to the "EVAL" routine would then skip the space, evaluate the zero, and return to the "SET" routine which would store the answer. The only remaining thing to do would be to ensure that the line is terminated correctly. Thus it appears that since FOCAL is an "interpreter", time could be saved by omitting the "E" and "T", and the space before the zero. 16.1 Speed of Character Interpretation ---- ----- -- --------- -------------- The basic speed of FOCAL's character interpreter may be measured in units of micro-seconds per character, by finding the difference between times for FOR X=1,1000;S Y=0 and FOR X=1,1000;SET Y=0 It is apparent that these lines differ by two characters, and the interpreter's speed will be the time difference as measured above, divided by 2000. Depending on memory speed, configuration etc., FOCAL-10 will show about 75 microseconds per character (KI-10) or 125 microseconds per character (KA-10). Since FOCAL-10 has a special capability to skip spaces quickly, the figure is about 30 to 40 microseconds per character for spaces and tabs. FOCAL-10 Page 60 ================================================================= 16.2 Speed of Line-finding ---- ----- -- ------------ Interpreters such as FOCAL-10 have various methods of storing program lines. One method could be to store all program lines with their line numbers in the text storage area. In such a case, the line-finding routine would need to scan all text, searching for end-of-line followed by the line number. FOCAL-10, however, stores the line numbers in a separate table, in order of line number, with a similar table of pointers to the line itself. In finding a line, then, FOCAL-10 must first scan the table and then use the pointer to get to the line itself. Speeds are measured by finding the difference between FOR X=1,1000;DO 1.01 and FOR X=1,1000;DO 1.99 where 1.01 through 1.99 are identical and contain only the letter "C". Typical times for FOCAL-10 are 18 - 30 microseconds per line scanned over. The time depends on the number of entries in the table of line numbers. Obviously it will be quicker to find low-numbered lines in FOCAL-10, but in all cases it would be faster than an interpreter which did not have a line table. (A 100-line program would still take only 2 milliseconds to find the hundredth line). 16.3 Speed of Command-execution ---- ----- -- ----------------- Many commands in FOCAL can be timed by including them in loops and performing them many times. The times may be compared with "COMMENT" execution. However, many commands can not be executed satisfactorily during loops ("ERASE", "MODIFY", "WRITE") and some others are I/O-dependent. Some examples of times in FOCAL-10 are: "DO" 2100 (KA-10), 1000 (KI-10) microseconds including line-number decoding. "GOTO" 1150 (KA-10), 780 (KI-10) microseconds including line-number decoding. "SET" 680 (KA-10), 450 (KI-10) microseconds including data-storage but not expression-evaluation. FOCAL-10 Page 61 ================================================================= 16.4 Speed of Arithmetic Operations ---- ----- -- ---------- ---------- Multiplication, division etc. will take a time dependent on the hardware being used and also precision (single or double). All simple operations take about the same time within about 20% or 30%, including addition, subtraction, multiplication, division, and exponentiation. Test results may be produced by the FOCAL test program XSPEED.FCL. 16.5 Speed of Item Evaluation ---- ----- -- ---- ---------- There are many types of evaluations performed by FOCAL. For example arithmetic functions, constants and variables. Each of these is determined and printed by the test program XSPEED.FCL; note that per-character interpretation times must be computed separately and added to those figures. FOCAL-10 Page 62 ================================================================= Appendix A. FOCAL memory map. -------- -- ----- ------ ---- Accumulators (000000 thru 000017) Job data area (000020 thru 000137) Static data base (see below: BUFH thru PDL-1) Push-down list (PDL thru PDL+PDC-1) Low segment program (if any) FOCAL program if non-sharable version (FOCAL thru CODEND-1) Function subroutines (if any - e.g. FNEW) DDT if any (DDT thru DDTEND-1) DDT symbols (if DDT is loaded) Patch area (if any) A patch area may be created at run time if required for DDT debugging, by modifying the left half of .JBSA before starting FOCAL. For example: .GET FOCAL .DDT FOCAL$: .JBSA/ 7016,,400010 7116,,400010 7016/ 0 (or rubbish) PAT: PATCH: ^C .SAVE FOCAL Dynamic data base (@.JBSA/L thru @.JBREL) I/O buffers pointed to by BUFTAB.(@.JBSA/L thru @INDEX-2) FOCAL text index (@INDEX-1 thru @TEXTL) This data block consists of one-word links in the format Bits 4-17 Program line number. Bits 18-35 Address just below text. Words must be stored in order of line number. Zero words represent deleted line numbers. The first word contains -1; INDEX points to this word. The last word contains -1; TEXTL points to this word. FOCAL program text(@TEXTL+1 thru @BUFL) The right half of TEXTL points just below the first character. The pointer in BUFL points to the right-most character-position of the last word in this data area. Statements appear in this data area as character strings, without the line-number prefix. Each new statement begins in a new word. The line-delimiter is stored as a single character, "eol". LIBRA-CALL text area(@BUFL+1 thru @BUFH) This contains groups of text-lines, where lines are separated by eol's. BUFL defines the lower limit of this FOCAL-10 Page 63 ================================================================= area, such that the first character would be obtained into CH by executing ILDB CH,BUFL. BUFH defines the upper limit of this area such that BUFH always points above the top eol. Initially the buffer area is empty and c(BUFL)=c(BUFH). The area is set to empty condition each time FOCAL types "*" to accept a new FOCAL command. When we execute code in this section it is executed as line zero. During the evaluation of string expressions, BUFH is temporarily moved up and the temporary strings are stored in this area. Unused core (@BUFH thru @SYMTBL) Symbol table (1+@SYMTBL thru @.JBREL) Variable labels and values (1+@SYMTBL thru @SYMTBC) If a variable exists, it will have an entry in this table. If there is no entry, then the variable has not been defined and we may assume it does not exist. Entries are stored in alphabetical order, working downwards from @SYMTBC. Each entry has the following format: Top word is the name, in which bit 0 indicates whether string (0) or number (1), bits 1-17 are the sixbit label, and bits 18-35 contain the index if any. The other word(s) contain the value being a floating-point number in the case of numeric data, or a string pointer in the case of string data. The double precision entry also contains a zero word of padding. The purpose of this is to speed searching. The floating-point format used depends on the hardware FOCAL-10 is assembled for. Double-precision versions of FOCAL-10 contain the string pointer in the word with the lesser address, and the other word if any contains zero. String variable values (1+@SYMTBC thru @SYMTBH) The data portion of string variables is stored here. Space is never reclaimed, so as the variable values change, this space expands without limit. High segment (if applicable)(400000 thru @.JBHRL/R) Vestigial jobdata area(400000 thru 400007) Function subroutines (if any)(FNEW thru FNWEND-1) FOCAL program (if sharable version)(FOCAL thru CODEND-1) FOCAL-10 Page 64 ================================================================= FOCAL low segment data base (extract from FOCAL.MAC) ----- --- ------- ---- ---- -------- ---- ---------- (subject to change without notice) SUBTTL LOW SEGMENT DATA RELOC 0 ;******** Data-block pointers ******** BUFH: BLOCK 1 ;Pointer to last character in LIBRA-CALL text area. DBP: ;This group is checked by the SQUEEZ routine. INDEX: BLOCK 1 ;Left half unused (contains -1). Right half - address of index data block. TEXTL: BLOCK 1 ;Right half points just below FOCAL program text. Left half contains -1. PNTR: BLOCK 1 ;Current byte pointer to FOCAL text. THISPT:BLOCK 1 ;Pointer to beginning of execution of current line. BUFL: BLOCK 1 ;Pointer to just below LIBRA-CALL text area. Left half contains 010700. DBPEND=+. ;End of data-block pointers. ;******** Program status data words ******** OUTCHN:BLOCK 1 ;Current-output-channel. INCHN: BLOCK 1 ;Current-input-channel. WPC==3 ;Three words per channel. HEDTAB:BLOCK 20*WPC ;Buffer headers. BUFTAB:BLOCK 20;Table of pointers to buffer space allocated to each channel. If entry is zero, then no buffers are allocated. If the word is negative, it means the channel is initted for output. Following data is gotten by negating the whole word first: Left half - size of buffer space. Right half - address of buffer space. FORFLA:BLOCK 1 ;Contains zero if no 'FOR' in execution. Otherwise XWD -1,LINNUM-of-FOR. FOVSUP:BLOCK 1 ;If this word is non-zero (set to -1), then suppress floating-point trap error messages. LUPARG:BLOCK 2 ;Most recent argument of repetitive loop. (2 locations to preserve historical map.) THISLN:BLOCK 1 ;# of the line being executed. LINNUM:BLOCK 1 ;Right-half - line number of current interest (Always positive). Left half if negative is a link to nested lines and pointers. Previous LINNUM is at PDLEND-2+LH(LINNUM). Previous PNTR is at PDLEND-1+LH(LINNUM). ;******** Symbol table pointers ******** SYMTBL:BLOCK 1 ;Address just below bottom of symbol-table. It is a pointer including index RL. SYMTBC:BLOCK 1 ;Address of first name in symbol table. It is a pointer including index RL. SYMTBH:BLOCK 1 ;Highest location of symbol table. Normally contains same as .JBREL. FORMAT:BLOCK 1 ;Format control for typing numbers. Bits 0-28:total # of digits. Bits 29-35:# of digits right of point. FOCAL-10 Page 65 ================================================================= EORMAT:BLOCK 1 ;Format control for E-format output OLDRAN:BLOCK WPV;Save last random number. FORMAX:BLOCK WPV;Logarithm of upper size limit for F-format output before rounding. EORMAX:BLOCK WPV;Logarithm of upper size-limit Of F-part of E-format type-out. ;******** Temporary storage ******** TEMP1: BLOCK WPV;This storage is not TEMP2: BLOCK WPV;guaranteed preserved by subroutines. TEMP3: BLOCK WPV;Therefore only use it on the one page. TEMP4: BLOCK WPV TEMPE: BLOCK WPV;Temporary storage for EXP. routine. TEMPR: BLOCK WPV;Temporary storage for RECIPR routine. TEMPT: BLOCK WPV;Temporary storage for type-out routine. LUKENT:BLOCK .RBDEV+2+AA ;LOOKUP/ENTER block. IFLE MONITOR-4.72,< WPD=4 ;Words per directory entry. FILTAB:BLOCK 20*WPD ;Space for file name etc. >;End IFLE MONITOR-4.72 BUFBOT:BLOCK 1 ;Save .JBFF here. ;******** Push-down list ******** PDL: BLOCK PDC;Program push-down list. PDLEND:BLOCK 2 ;Two spare for overflow. FOCAL-10 Page 66 ================================================================= ! . . . . . . . . . . . . . . . 8 " . . . . . . . . . . . . . . . 17 # . . . . . . . . . . . . . . . 17 $ . . . . . . . . . . . . . . . 9, 17 % . . . . . . . . . . . . . . . 18-19, 52 * . . . . . . . . . . . . . . . 9, 12 ** . . . . . . . . . . . . . . 9 + . . . . . . . . . . . . . . . 9 - . . . . . . . . . . . . . . . 9 / . . . . . . . . . . . . . . . 9, 18, 21, 24-25 : . . . . . . . . . . . . . . . 20 ; . . . . . . . . . . . . . . . 6, 39 ? . . . . . . . . . . . . . . . 27 Abbreviations . . . . . . . . . 7 Accuracy . . . . . . . . . . . 58 Addition . . . . . . . . . . . 9 Alphanumeric . . . . . . . . . 8 Alt-mode . . . . . . . . . . . 6, 20 Arithmetic . . . . . . . . . . 8-9 Arithmetic operators . . . . . 9, 45 Arithmetic speed . . . . . . . 61 Arrays . . . . . . . . . . . . 8, 45 ASK command . . . . . . . . . . 20 Asterisk cue . . . . . . . . . 6, 26 Asterisk for paper-tape input . 46 Availability . . . . . . . . . 1 Back-slash . . . . . . . . . . 11 Backarrow . . . . . . . . . . . 47 Backspace . . . . . . . . . . . 7, 11, 20, 41 Calculator . . . . . . . . . . 8 Carriage-return . . . . . . . . 6, 8, 11, 17, 47 Channel . . . . . . . . . . . . 18, 21, 24 Channel not correctly INITted . 53 Character interpretations . . . 39, 45 Colon . . . . . . . . . . . . . 20 COMMENT command . . . . . . . . 10 Conditional branching . . . . . 14 Configuration . . . . . . . . . 4 Control-C . . . . . . . . . . . 27-28, 31, 40, 55 Control-G (bell) . . . . . . . 11 FOCAL-10 Page 67 ================================================================= Control-L . . . . . . . . . . . 11 Control-P . . . . . . . . . . . 11, 20, 27, 30, 40, 47 Control-R . . . . . . . . . . . 7, 11, 20, 40, 47 Control-U . . . . . . . . . . . 7, 11, 40 Control-Z . . . . . . . . . . . 29-30, 40, 47 Cue for ASK data . . . . . . . 33 Data base . . . . . . . . . . . 62 Date . . . . . . . . . . . . . 10, 34 DDT symbols . . . . . . . . . . 62 Debug . . . . . . . . . . . . . 20, 27-28 Deletion of files . . . . . . . 22 Desk calculator . . . . . . . . 8 Diagnostics . . . . . . . . . . 7, 52-53 Dimension . . . . . . . . . . . 8, 45 Disk I/O . . . . . . . . . . . 24 Distribution . . . . . . . . . 1 Division . . . . . . . . . . . 9 DO command . . . . . . . . . . 12-13 Dollar($) . . . . . . . . . . . 17 E-format . . . . . . . . . . . 18-19 Emergency . . . . . . . . . . . 30 ENTER error # . . . . . . . . 53 ERASE command . . . . . . . . . 10 Error messages . . . . . . . . 33, 52-53 Errors . . . . . . . . . . . . 7 Escape . . . . . . . . . . . . 6, 20, 40 Evaluation speed . . . . . . . 61 Examples . . . . . . . . . . . 9, 28 Examples of FOCAL programs . . 28 Exclamation(!) . . . . . . . . 8, 17 Execute Command . . . . . . . . 16 EXIT . . . . . . . . . . . . . 25, 30, 47 Exponentiation . . . . . . . . 9 F-format . . . . . . . . . . . 18-19 FCHR function . . . . . . . . . 35 Features of FOCAL-10 . . . . . 5 FHIBER function . . . . . . . . 35 File storage . . . . . . . . . 22 Floating-point overflow . . . . 53 Floating-point underflow . . . 53 FNEW function . . . . . . . . . 32, 56 FOCAL commands . . . . . . . . 6, 12, 38 FOCAL examples . . . . . . . . 9, 19, 28 FOCAL function . . . . . . . . 33 FOR command . . . . . . . . . . 13-14 Form feed . . . . . . . . . . . 11 Format . . . . . . . . . . . . 18-19, 33, 64-65 Full-duplex . . . . . . . . . . 11 Function FNEW . . . . . . . . . 56 Function FOCAL . . . . . . . . 33 Function names . . . . . . . . 32, 36-37 FOCAL-10 Page 68 ================================================================= Generalised I/O . . . . . . . . 24 GETTAB . . . . . . . . . . . . 34 Getting FOCAL program . . . . . 6 Getting on the air with FOCAL . 6 Getting started . . . . . . . . 6 GO command . . . . . . . . . . 12 GO TO command . . . . . . . . . 12 GOTO command . . . . . . . . . 12 Group number . . . . . . . . . 6 Half-duplex . . . . . . . . . . 11 Hatch(#) . . . . . . . . . . . 17 Heirarchy of operators . . . . 8 HELP . . . . . . . . . . . . . 7 Hibernating and sleeping . . . 35 I/O channel . . . . . . . . . . 18, 21, 24, 33 IF command . . . . . . . . . . 14 Illegal command . . . . . . . . 53 Illegal format (ignored) . . . 53 Illegal number . . . . . . . . 54 Illegal variable . . . . . . . 54 Imaginary roots required . . . 54 Immediate mode . . . . . . . . 6 INIT error . . . . . . . . . . 54 Initial dialogue . . . . . . . 4 Input device error . . . . . . 54 Insufficient core . . . . . . . 54 Interpretation speed . . . . . 59 Iteration . . . . . . . . . . . 14 Jiffies . . . . . . . . . . . . 34 Job data area . . . . . . . . . 33, 62 KA-10 . . . . . . . . . . . . . 5, 58 KI-10 . . . . . . . . . . . . . 5, 58 Kilo-core-ticks . . . . . . . . 34 KJOB . . . . . . . . . . . . . 30 LIBRA CALL command . . . . . . 22, 25 LIBRA SAVE command . . . . . . 22 LIBRARY CALL command . . . . . 13 Line number . . . . . . . . . . 6 Line-feed . . . . . . . . . . . 6, 11 Line-finding speed . . . . . . 60 Logging on procedure . . . . . 6 Login . . . . . . . . . . . . . 6 LOOKUP error # . . . . . . . . 54 Loops . . . . . . . . . . . . . 14, 55 Memory requirements . . . . . . 5 Mismatched parentheses . . . . 54 MODIFY command . . . . . . . . 11 Monitor . . . . . . . . . . . . 6, 30-31, 34 FOCAL-10 Page 69 ================================================================= Monitor SAVE command . . . . . 30 Multiplication . . . . . . . . 9 Nonexistant line . . . . . . . 54 OPERATE INPUT command . . . . . 24-25, 30, 38 OPERATE OUTPUT command . . . . 25, 30, 38 Operators . . . . . . . . . . . 8-9 Output device error . . . . . . 54 Parentheses . . . . . . . . . . 9, 32, 39 Patch area . . . . . . . . . . 62 pdl ov (monitor error message) 55 PDP-11 FOCAL . . . . . . . . . 17 PDP-6 . . . . . . . . . . . . . 5 PDP-8,PDP-9 etc. . . . . . . . 4 PEEK . . . . . . . . . . . . . 33 Percent mark . . . . . . . . . 18-19, 52 Peripheral devices . . . . . . 24 Precision . . . . . . . . . . . 58 Price . . . . . . . . . . . . . 1 Program . . . . . . . . . . . . 6, 10 Program lines, groups . . . . . 6 Program re-started . . . . . . 55 Program storage . . . . . . . . 22 Program text . . . . . . . . . 10 Project-programmer numbers . . 22 Prompt for ASK data . . . . . . 33 Protection . . . . . . . . . . 23 Protection of files . . . . . . 22 Push-down-list Overflow . . . . 55 Query(?) . . . . . . . . . . . 27-28 QUIT command . . . . . . . . . 12 Quote marks . . . . . . . . . . 17 Random numbers . . . . . . . . 33-34, 65 Re-starting FOCAL . . . . . . . 30 REE . . . . . . . . . . . . . . 30-31 REENTER . . . . . . . . . . . . 30-31 RENAME error # . . . . . . . . 55 RETURN command . . . . . . . . 13 Rubout . . . . . . . . . . . . 7, 11, 20, 40 Run time . . . . . . . . . . . 34 Running FOCAL . . . . . . . . . 6 SAVE command . . . . . . . . . 30 Search character . . . . . . . 11 Semicolon . . . . . . . . . . . 6, 39 SET command . . . . . . . . . . 8 Simple arithmetic . . . . . . . 8 Sleeping and hibernating . . . 35 Speed . . . . . . . . . . . . . 59-60 START command . . . . . . . . . 30, 55 FOCAL-10 Page 70 ================================================================= Step number . . . . . . . . . . 6 Stopping . . . . . . . . . . . 30 String constants . . . . . . . 16 String expressions . . . . . . 16 String variables . . . . . . . 16 Subroutines (DO) . . . . . . . 13 Subscripts . . . . . . . . . . 8, 45 Subtraction . . . . . . . . . . 9 Symbol table . . . . . . . . . 9, 17 Symbols . . . . . . . . . . . . 8, 10, 20 Text . . . . . . . . . . . . . 10, 17 Text buffer . . . . . . . . . . 10 Time . . . . . . . . . . . . . 10 Time-of-day . . . . . . . . . . 10, 34 Trace feature . . . . . . . . . 27-28 TYPE $ . . . . . . . . . . . . 9 TYPE command . . . . . . . . . 8, 17 Unexpected character . . . . . 55 UUO -GETTAB . . . . . . . . . . 34 Variables . . . . . . . . . . . 8 Vectors . . . . . . . . . . . . 8, 45 Vestigial jobdata area . . . . 63 WEAVE . . . . . . . . . . . . . 22 WRITE command . . . . . . . . . 10 XECUTE Command . . . . . . . . 16 \ . . . . . . . . . . . . . . . 11 ^ . . . . . . . . . . . . . . . 7, 9