.PAPER SIZE 60,72;.LEFT MARGIN 9;.RIGHT MARGIN 72 .TITLE FIGure - Calculator program _. .BLANK 20 .CENTER;FIGure - Calculator program .CENTER;------ - ---------- ------- .BLANK 24 .LEFT MARGIN +40 .NOPERIOD;.NOFILL T. R. Wyant .BLANK 04-Apr-1986 .LEFT MARGIN -40;.PERIOD;.FILL .SUBTITLE Overview .PAGE .PARAGRAPH FIGure is a general purpose calculator, written in Fortran. It performs both arithmetic and bitwise logical operations in a syntax similar to that of the FORTRAN assignment statement. Up to 100 variables can be defined (with names of up to 6 characters), in addition to predefined variables that hold the result of the last calculation and the current default radix. Procedures can be stored in files and called up when needed. There is online help available. .SUBTITLE Short Course .PAGE .PARAGRAPH How you get into FIGure depends on what system you are running on and how your system manager has installed it. Normally, you would just enter .INDENT +4 FIGURE .BREAK in response to your system prompt. FIGure will then prompt you with: .INDENT +4 Enter calculation: .BREAK and you're ready to go. When through, terminate FIGure by entering a Control/Z. You also have the option of entering your calculation on the same line as the FIGure command. In this case, FIGure executes your calculation and then exits. .PARAGRAPH Calculations are entered into FIGure in generally the same way you would write them in an algebraic formula, or enter them in a BASIC or FORTRAN assignment statement. You can even create named variables to hold your results. The names may be up to 6 characters long; they must begin with a letter of the alphabet, and be composed of letters or numerals. For example, the statement .INDENT +4 ANSWER = 12 + 7*2 .BREAK Creates (if necessary) the variable "ANSWER", and stores the number 26 in it. ANSWER can then be referred to in subsequent calculations. There is a predefined variable called "RESULT", which always holds the value calculated by the last statement. For example, the sequence .INDENT +4 5 + 3 .INDENT +4 ANSWER = RESULT*2 .BREAK would store the number 16 in ANSWER. The variables you define in FIGure will retain their value until you exit FIGure. .PARAGRAPH Whenever a result is explicitly stored in a variable, the name of the variable is displayed, along with the value stored. If a statement does not result in a value being explicitly stored, you will get a display showing the value being stored in RESULT. Be aware that RESULT is ALWAYS updated, regardless of whether that update is displayed. .PARAGRAPH When entering a number in "scientific" notation, the syntax is (number)@(exponent), not (number)E(exponent) as in Fortran. See the section on alternate radices for why. For example, "three million" would be entered as "3@6", and "seven ten-thousandths" would be entered as "7@-4", or as ".7@-3". The display of results switches to this format if necessary. .PARAGRAPH Sequences of statements that you use often can be stored in a file and executed using the INCLUDE or CHAIN command. There is no difference between these commands when entered in response to the "Enter calculation: " prompt, but they have different effects when embedded in INCLUDEd (or CHAINed) files. INCLUDE causes execution of the statements in the current file to be suspended and the statements in the INCLUDEd file to be executed instead; when the end of the INCLUDEd file is reached, control returns to the file that initially issued the INCLUDE statement. There is a limit (currently 4) on the number of nested INCLUDEs that can be outstanding at any one time. CHAIN, on the other hand, causes execution of the file you are in to be terminated, and control is transferred to the CHAINed file. There is no limit on the number of files you can CHAIN to. .PARAGRAPH The syntax of the INCLUDE and CHAIN commands is similar: .INDENT +4 INCLUDE "filename" .BREAK and .INDENT +4 CHAIN "filename" .BREAK where the quoted filename represents a legal file name on your system. If the filename is uppercase only with no embedded blanks (true on all RSX and VMS systems), .INDENT +4 @filename .BREAK can be used as a synonym for the INCLUDE command. Missing filename elements are supplied from the following default filespecs: .LEFT MARGIN +8 .BLANK;.INDENT -4 RSX .BREAK SY:.FIG; .BLANK;.INDENT -4 VMS .BREAK SYS$DISK:[].FIG; .BLANK;.LEFT MARGIN -8 .PARAGRAPH HELP is available on-line in the normal FIGure installation. Just enter HELP in response to the .INDENT +4 Enter calculation: .BREAK prompt. Subtopics to the main HELP are available; these are accessed in a manner consistent with your system's HELP command. .SUBTITLE Full syntax of the Arithmetic statement .PAGE .PARAGRAPH This section will attempt to give a full explanation of the arithmetic capabilities and syntax of FIGure. The syntax is (as noted above) generally similar to the assignment statement in most languages, with the exception that actual assignment of the computed value to a variable is optional. The reader will find other exceptions noted in this document. .PARAGRAPH The following operations are available. For the binary operations (ie - those that combine two values, producing a single result), the syntax is .INDENT +4;operand operator operand .BREAK;and for unary operations (ie - those that take one value and produce a different result), the syntax is .INDENT +4;operator operand .BREAK There are a couple special cases, discussed below. .LEFT MARGIN +4;.BLANK .CENTER;Same as Fortran .BLANK .INDENT -4;_= - Assignment of a value to a variable (special case). .INDENT -4;() - Grouping operations. .INDENT -4;+ - Addition (binary). .INDENT -4;- - Subtraction or unary minus (binary or unary, depending on how used). .INDENT -4;* - Multiplication (Binary). .INDENT -4;/ - Division (Binary). .BLANK .CENTER;Different from Fortran .BLANK .INDENT -4;_^ - Exponentiation (raising to a power) (binary). .INDENT -4;_& - Bitwise logical AND (binary). .INDENT -4;_! - Bitwise logical OR (binary). .INDENT -4;_~ - Bitwise logical NOT (unary). .INDENT -4;ABS - Absolute value (unary). .INDENT -4;SIGN - Extract algebraic sign (unary). .INDENT -4;DIV - Integer division (binary). .INDENT -4;MOD - Remainder upon division (binary). .INDENT -4;=? - Test for equality (binary). .INDENT -4;>=? - Test for greater than or equal (binary). .INDENT -4;<=? - Test for less than or equal (binary). .INDENT -4;>? - Test for greater than (binary). .INDENT -4;? - Test for inequality (binary). .INDENT -4;%x - Temporary radix operator (special case). .BLANK;.LEFT MARGIN -4 .PARAGRAPH The "_=", is a special case. It can be treated as a binary operator, but each equals sign must have a variable name to its left. You can have more than one equals sign: .INDENT +4 A = X = 12*5 .BREAK assigns the value 60 to both A and X. Equals signs can appear within a statement if you observe this limitation: .INDENT +4 A = (X = 2*3)_^2 + 3*X + 4 .BREAK after which X has the value 6, and A has the value 58. .PARAGRAPH The "_%" sign is also a special case. It acts like a unary operator, but is really an instruction to the compiler on how to interpret any numeric constants that appear. See the section on alternate radices for more information. .PARAGRAPH All calculations are performed in REAL*4, except for the logical operations, which are done by converting the values to scaled integers. This has ramifications that are dealt with in a separate section. .PARAGRAPH Calculations are performed by priority of the operations being performed, in the following order: .LEFT MARGIN +4 .BLANK;.INDENT -4 () .BREAK All operations inside parentheses are performed first. .BLANK;.INDENT -4 -, _~, ABS, SIGN .BREAK Unary operations. .BLANK;.INDENT -4 _^ .BREAK Exponentiation. .BLANK;.INDENT -4 *, /, _&, DIV, MOD .BREAK Multiplication, division, and logical AND. .BLANK;.INDENT -4 +, -, ! .BREAK Addition, subtraction, logical OR. .BLANK;.INDENT -4 _=?, >?, _=?, <_=?, <>? .BREAK Comparisons .BLANK;.INDENT -4 _= .BREAK Assignment of value to variable. .LEFT MARGIN -4;.BLANK Note that temporary radix operations don't appear in the above table, being really commands to the compiler rather than executable operations. If they were commands, however, they would rate with parentheses and the unary operations. .SUBTITLE Radix control .PAGE .PARAGRAPH All internal operations are done in binary, and generally in REAL*4 format (except for logical operations, discussed in a separate section). Radix control thus applies only to how the data is interpreted and displayed by FIGure. .PARAGRAPH The display radix and default input radix are determined by the value stored in a predefined variable named "RADIX". The value stored in RADIX is trimmed to the range 1 to 36 before use (with no warning message). 1 is a special case, calling for a display of "TRUE" for negative values, and "FALSE" for zero or positive values. All others cause display in the given radix. For radices greater than ten, the letters of the alphabet are used in order ("A" being eleven, and so on). Because of this, the Fortran "E" format is not used for either input or output ("E" being just another digit in any radix greater than 14). Instead, an "@" sign is used to separate mantissa from exponent. .PARAGRAPH On input, the default radix can be overridden by temporary radix operators, which have the following format: .LEFT MARGIN +9 .INDENT -5;%B - Binary .INDENT -5;%O - Octal .INDENT -5;%D - Decimal .INDENT -5;%H - Hexadecimal .INDENT -5;%X - Hexadecimal .INDENT -5;%n - "n" is a decimal number indicating the desired radix. In this format, a space must separate the "n" from the number being represented. .LEFT MARGIN -9 If the temporary radix operator appears before a number, it affects that number only. If it appears before a left parenthesis, it affects all numbers between the left parenthesis and the corresponding right parenthesis unless overridden by another temporary radix operator. Examples: .LEFT MARGIN +8 .INDENT -4;%X 10 = 16 (decimal) .INDENT -4;%X(0A+12) = 10+18 (decimal) .INDENT -4;%B(%D6+100) = 6+4 (decimal) .INDENT -4;%3 12+%5 14 = 5+9 (decimal) .INDENT -4;%O 1.2@2 = 1.2 (octal)*(8 squared) = 80 (decimal) .LEFT MARGIN -8 Note that when the radix is greater than 10, numbers must begin with a decimal digit (eg: %X 0A, not %X A). .PARAGRAPH Results are always displayed in the default radix. Scientific notation is used when needed to represent the number with the proper number of significant bits. .SUBTITLE Logical operations .PAGE .PARAGRAPH The logical operations "AND" (_&), "OR", (_!), and "NOT" (_~) make no sense in the REAL*4 representations of the numbers. Therefore logical operands are converted to scaled integers by extracting the exponent field, swapping the words to get a ligitimate INTEGER*4 number, and negating if appropriate. .PARAGRAPH For "AND" and "OR", the operands are aligned by dividing the smaller (in absolute value) by two the appropriate number of times before the operation is performed. The result is converted back to REAL*4 by reversing the process that produced the scaled INTEGER*4 value. .PARAGRAPH The "NOT" operation presented a special problem, as some of the bits in the scaled integer can represent the fractional part of the original REAL*4 value. It was found by experience that performing a "NOT" on small integers produced results little different from negating them, unless the fractional bits were stripped afterwards. Therefore, the contents of the predefined variable TRIM are ANDed to the results of the logical NOT before converting back to REAL*4. The author likes the results obtained when TRIM is set to -1, so that is the initial setting. You can set it any way you like, though the author believes the following values will be most useful: .LEFT MARGIN +8 .INDENT -4;-2_^n - the negation of powers of 2. This results in all bits to the left of the given bit being saved, and all bits to the right being trashed. .INDENT -4;2_^n - powers of 2. This results in only 1 bit being kept. .INDENT -4;2_^m-2_^n with m>n - the difference of two powers of 2. Results in all bits between the two given bits being kept. .INDENT -4;%O177777 - same as above, with m=16, n=0. Keep 1 word of data. .INDENT -4;0 - special case that turns off trimming in case you think it's a bad idea. .LEFT MARGIN -8 .APPENDIX .LEFT MARGIN 9;.RIGHT MARGIN 72 .PARAGRAPH This appendix covers installation under RSX. .LIST .LE;Log in to a privileged account. .LE;Copy the distribution kit to the directory of your choice. .LE;Invoke the installation procedure by .INDENT +4 >@FIGINSRSX .BREAK This will build the FIG task to your specifications, and install HELP. Note that FIG must be built using the default FORTRAN on your system, if you plan to build it using FIGINSRSX.CMD, and this FORTRAN must be either F4P V2.5 (at least) or F77. .LE;If desired, copy the FIG task to the directory of your choice (eg: [3,54] under M+, or [1,54] under M). .LE;If desired, install FIG, and VMR it or edit your startup command file to have it installed on startup. .LE;If desired, insert the help into MCR and/or DCL HELP. .END LIST .APPENDIX .LEFT MARGIN 9;.RIGHT MARGIN 72 .PARAGRAPH This appendix covers installation under VMS. .LIST .LE;Log in to a privileged account (eg: the SYSTEM account). .LE;Copy the distribution kit to the directory of your choice. .LE;Invoke the installation procedure by .INDENT +4 >@FIGINSVMS .BREAK This will build the FIG image to your specifications, and install HELP. .LE;If desired, copy the FIG image to the directory of your choice (eg: SYS$SYSTEM). .LE;If desired, define FIGURE as a foreign command in your SYLOGIN command procedure. For example: .INDENT +4 $ FIG*URE :== $SYS$SYSTEM:FIG .END LIST .APPENDIX .LEFT MARGIN 9;.RIGHT MARGIN 72 .PARAGRAPH This appendix is intended to be a complete representation of FIGure syntax in Backus-Nauer form. The author would be glad to hear of any omissions or errors. .PARAGRAPH Backus-Nauer is a "metalanguage" adapted to clear and unambiguous specification of a recursive syntax. It goes back a long way (I learned Algol in it), but seems not to have caught on. The general syntax is: .LEFT MARGIN +8 .BLANK;.INDENT -4 <> - Used to enclose the names of formally defined syntax elements. .BLANK;.INDENT -4 :== - "Meta-assignment" operator. Used to define the syntax element on the left in terms of the definition on the right. .BLANK;.INDENT -4 {} - "Informal definition". Used to enclose an English (or at least non-Backus-Nauer) syntax element definition. .BLANK;.INDENT -4 | - "Exclusive or" operator. One and only one of the syntax elements separated by this operator must be selected. .BLANK;.INDENT -4 All other characters represent themselves, and are to be taken as literals. .BLANK;.INDENT -4 There is no explicit concatenation operator. Concatenation of syntax elements is represented by the concatenation of their formal representations. .BLANK;.INDENT -4 Spaces in Backus-Nauer are not significant (though they may be in the defined syntax). .BLANK 4 .LEFT MARGIN -8 .PARAGRAPH The general syntax for FIGure is defined below. A few basic language elements are defined first, followed by a top down definition of the useful statements and commands. .LEFT MARGIN +8 .BLANK 3;.INDENT -8 :== A _| B _| C _| D _| E _| F _| G _| H _| I _| J _| K _| L _| M _| N _| O _| P _| Q _| R _| S _| T _| U _| V _| W _| X _| Y _| Z _| a _| b_| c _| d _| e _| f _| g _| h _| i _| j _| k _| l _| m _| n _| o _| p _| q _| r _| s _| t _| u _| v _| w _| x _| y _| z .BLANK Note that FIGure is not sensitive to case. Lower case characters are translated to upper case characters before parsing. .BLANK 3;.INDENT -8 :== 0 _| 1 _| 2 _| 3 _| 4 _| 5 _| 6 _| 7 _| 8 _| 9 .BLANK 3;.INDENT -8 :== _| .BLANK 3;.INDENT -8 :== .BLANK Defined merely to show the intent to use the character as a number. The value of the "A" is ten, of "B" is eleven, and so on through "Z" which is thirty six. .BLANK 3;.INDENT -8 :== _| .BLANK Only s less than the current radix (as defined by the value of the variable RADIX or overridden by the most local ) are legal in an . .BLANK 3;.INDENT -8 :== _| .BLANK 3;.INDENT -8 :== {One or more characters of blanks and/or tabs, if it occurs between two s} _| {Zero or more characters of blanks or tabs otherwise} .BLANK 3;.INDENT -8 :== {Nothing at all. Indicates that the syntax element defined can be missing entirely.} .BLANK 3;.INDENT -8 :== {Any valid file name on your system.} .BLANK How the omitted elements of a file name are supplied depends on the system. At the current time, defined defaults are: .BLANK;.LEFT MARGIN +4;.NOFILL RSX - SY:.FIG; VMS - SYS$DISK:[].FIG; .FILL;.LEFT MARGIN -4 .BLANK 3;.INDENT -8 :== _| _| ; _| .BLANK A valid line is a list of zero or more statements followed optionally by a command, all separated by semicolons. In general statements need to be compiled before execution, whereas commands are executed immediately by the compiler. .BLANK 3;.INDENT -8 :== _| .BREAK ; .BLANK 3;.INDENT -8 :== <@ command> _| _| .BREAK _| .BLANK 3;.INDENT -8 <@ command> :== @ .BLANK This is a synonym for the (see below), but requires that the be insensitive to case (ie - valid when uppercased) and contain no embedded blanks. Not much of a restriction on the typical DEC system, but may be a real restriction if migrating FIGure to other systems. .BLANK 3;.INDENT -8 :== CHAIN " " .BLANK This command causes the file you are currently executing to be closed, and the next to be taken from the new file. If executed from command level (ie - in response to the "Enter calculation: " prompt, it is a synonym for the . .BLANK 3;.INDENT -8 :== HELP _| HELP {Help topic} .BLANK This command causes a help message to be displayed. In RSX and VMS, this capability is based on the system's HELP command, and will not work if not properly set up. Valid {Help topics} are defined in the top level HELP command. .BLANK 3;.INDENT -8 :== INCLUDE " " .BLANK This command causes the next to be fetched from the designated file. The file containing the remains open, and when the end of file "" is encountered, control returns to the following the . .BLANK 3;.INDENT -8 :== .BLANK The syntax allows for others, but this is all that's implimented at the moment. .BLANK 3;.INDENT -8 :== _| _| .BLANK The value of an is the value of the associated , , or .BLANK 3;.INDENT -8 :== _| .BREAK .BLANK The value of an is the value of the associated or .BLANK 3;.INDENT -8 :== = _| .BREAK = .BLANK The value of the or in which this occurs is assigned to each of the s in the list. .BLANK 3;.INDENT -8 :== .BLANK The value of the is determined by the values of the s, and the exact nature of the . .BLANK 3;.INDENT -8 :== =? _| >? _| ? _| >=? _| <=? .BLANK The symbol "=" represents equality, ">" represents the condition where the left hand expression is greater than the right hand expression, and "<" represents the condition where the left hand expression is less than the right hand expression. Any combination of these operators is legal (including "<=>?", which is of course always TRUE), and they may appear in any order (eg: ">?"). The meaning of the compound tests should be obvious. The value of the is the constant TRUE (defined below under ) if the relationship holds, and the constant FALSE otherwise. .BLANK 3;.INDENT -8 :== _| + _| .BREAK - _| ! .BLANK The value of the is the value of the , or the sum, difference, or bitwise OR if the values of the individual s, evaluated left to right. .BLANK 3;.INDENT -8 :== _| * _| _/ _| DIV _| .BREAK MOD _| _& .BLANK The value of the is the value of the , or the product, quotient, integer quotient, remainder after division, or bitwise AND of the values of the individual s, evaluated left to right. .BLANK 3;.INDENT -8 :== _| _^ .BLANK The value of the is the value of the , or the exponentiation (rasing to a power) of the individual s, evaluated left to right. Currently, exponentiation is implimented using logarithms, and so cannot be done on negative values. .BLANK 3;.INDENT -8 :== _| _| _| ( ) _| .BREAK ( ) _| - _| _~ _| ABS _| SIGN .BLANK The value of the is the value of the , , or , negated, bitwise NOTed, with sign stripped (absolute value), or with only the algebraic sign (-1, 0, +1). The unary operations if present are executed right to left, not left to right as with the binary operators. .BLANK 3;.INDENT -8 :== _| _| _| _| _| .BLANK In other (and clearer in this case) words, a variable is a letter followed (optionally) by 1 to 5 alphanumerics. The value of the variable is the value it acquired the last time it appeared in an . If it has not so appeared, its value is undefined, and an attempt to use it may return an error. .BLANK NOTICE: The maximum size of a can be increased in increments of 6 characters at the option of the installer. .BLANK NOTICE: The current implimentation actually allows the characters "$" and "." to appear in variable names, as long as they begin with an alphabetic character. This is not guaranteed to be true of future releases, and so is not documented (except here). Beware. .BLANK 3;.INDENT -8 :== % B _| % O _| % D _| % H _| % X _| .BREAK _% .BLANK The purpose of the radix operator is to alter the radix in which the affected s are evaluated. If it occurs before a , only the s occurring as a part of that are affected. If it occurs before an in parentheses, all occurring as part of constants in that are affected, unless overridden by a more local . The default radix in the absence of any radix operator is specified by the contents of the variable "RADIX" .BLANK 3;.INDENT -8 :== _| _| _| _| _| _| _| TRUE _| FALSE _| TEN .BLANK The value of TRUE is -1; the value of FALSE is 0, and the value of TEN is ten. .BLANK 3;.INDENT -8 :== .BLANK RESTRICTION: If the radix under which the is being evaluated is greater than ten, the first in the must be a . .BLANK RESTRICTION: In the current implimentation, the must be less than hexadecimal 7FFF. It is anticipated that this restriction will be lifted in a future release. .BLANK 3;.INDENT -8 :== . _| . .BLANK RESTRICTION: In the current implimentation, the must be less than hexadecimal 7FFF. It is anticipated that this restriction will be lifted in a future release. .BLANK 3;.INDENT -8 :== @ _| @ + _| @ - .BLANK .BLANK RESTRICTION: In the current implimentation, the must be less than hexadecimal 7F. This is hardware dependant, and may change for other implimentations. .LEFT MARGIN -8 .APPENDIX .LEFT MARGIN 9;.RIGHT MARGIN 72 .CENTER;Easy Modifications .BLANK 2 .PARAGRAPH A couple of characteristics of FIGure are parameterized, and thus easily adjustable by changing FIGI01.FTN and rebuilding. The items of interest are: .BLANK;.LEFT MARGIN +10 .BLANK;.INDENT -10 MXVARS - Controls the number of variables you are allowed to have. When modifying, remember that RESULT, RADIX, and TRIM count against this total. If you increase this, the task will grow by 4*MXVNAM+4 for each variable you add. .BLANK;.INDENT -10 MXVNAM - Controls the length of the longest allowed variable name. The maximum variable name length is 6*MXVNAM. If you increase this, the task will grow by 4*MXVARS for each increment of MXVNAM. .LEFT MARGIN -10 .APPENDIX .LEFT MARGIN 9;.RIGHT MARGIN 72 .CENTER;Migration to other systems. .PARAGRAPH FIGure is written in fairly generic Fortran, and so ought to port fairly well to any FORTRAN that supports INTEGER*4 and INCLUDE. Bear in mind, however, that this statement is written by someone who has not actually done this. The stuff that is different between a PDP-11 running RSX and a VAX running VMS is in FIGRSX.FTN and FIGVMS.FTN. Theoretically, you could port to any other system by providing a FIXxxx module for that system. .PARAGRAPH There probably ought to be another module for hardware-dependant stuff, but I blew it on that one. The only hardware dependancy that comes to mind at the moment is in the following routines: .LEFT MARGIN +8 .INDENT -8 RTOSI (Convert Real to Scaled Integer) .INDENT -8 SITOR (Convert Scaled Integer to Real) .INDENT -8 RALIGN (Convert two Reals to Scaled Integers with the same scale factor) .LEFT MARGIN -8 These are all found in FIGEVL.FTN, and are used for executing the bitwise logical operations. If the system you are trying to port to represents REAL*4 numbers in a manner inconsistent with the PDP-11/VAX-11 standard representation, you will have to replace these subroutines. .PARAGRAPH Also, the parser stores variable names in RAD-50. If your target system does not support RAD-50, you will have to write your own encoding and decoding routines. Use any scheme that maps three alphanumerics uniquely into 16 bits without tripping your system's overflow trapping (if any). .APPENDIX .LEFT MARGIN 9;.RIGHT MARGIN 72 Revision history: .BLANK;.LEFT MARGIN +7 .BLANK;.INDENT -7 86.080 Original release .BLANK;.INDENT -7 86.108 Allow variable names more than 6 characters long. Note that the distribution is still built to only allow 6. .LEFT MARGIN -7