. FIGure - Calculator program ------ - ---------- ------- T. R. Wyant 04-Apr-1986 FIGure - Calculator program PAGE 2 Overview FIGure is a general purpose calculator, written in For- tran. It performs both arithmetic and bitwise logical opera- tions 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. FIGure - Calculator program PAGE 3 Short Course 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 FIGURE in response to your system prompt. FIGure will then prompt you with: Enter calculation: 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. 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 cre- ate named variables to hold your results. The names may be up to 6 characters long; they must begin with a letter of the al- phabet, and be composed of letters or numerals. For example, the statement ANSWER = 12 + 7*2 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 5 + 3 ANSWER = RESULT*2 would store the number 16 in ANSWER. The variables you define in FIGure will retain their value until you exit FIGure. 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. When entering a number in "scientific" notation, the syn- tax is (number)@(exponent), not (number)E(exponent) as in For- tran. See the section on alternate radices for why. For exam- ple, "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. 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 re- ached, 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 FIGure - Calculator program PAGE 4 Short Course 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. The syntax of the INCLUDE and CHAIN commands is similar: INCLUDE "filename" and CHAIN "filename" 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), @filename can be used as a synonym for the INCLUDE command. Missing fi- lename elements are supplied from the following default filespecs: RSX SY:.FIG; VMS SYS$DISK:[].FIG; HELP is available on-line in the normal FIGure installa- tion. Just enter HELP in response to the Enter calculation: prompt. Subtopics to the main HELP are available; these are accessed in a manner consistent with your system's HELP com- mand. FIGure - Calculator program PAGE 5 Full syntax of the Arithmetic statement 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 state- ment in most languages, with the exception that actual assign- ment of the computed value to a variable is optional. The reader will find other exceptions noted in this document. The following operations are available. For the binary operations (ie - those that combine two values, producing a single result), the syntax is operand operator operand and for unary operations (ie - those that take one value and produce a different result), the syntax is operator operand There are a couple special cases, discussed below. Same as Fortran = - Assignment of a value to a variable (special case). () - Grouping operations. + - Addition (binary). - - Subtraction or unary minus (binary or unary, depending on how used). * - Multiplication (Binary). / - Division (Binary). Different from Fortran ^ - Exponentiation (raising to a power) (binary). & - Bitwise logical AND (binary). ! - Bitwise logical OR (binary). ~ - Bitwise logical NOT (unary). ABS - Absolute value (unary). SIGN - Extract algebraic sign (unary). DIV - Integer division (binary). MOD - Remainder upon division (binary). =? - Test for equality (binary). >=? - Test for greater than or equal (binary). <=? - Test for less than or equal (binary). >? - Test for greater than (binary). ? - Test for inequality (binary). %x - Temporary radix operator (special case). 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: A = X = 12*5 assigns the value 60 to both A and X. Equals signs can appear within a statement if you observe this limitation: A = (X = 2*3)^2 + 3*X + 4 after which X has the value 6, and A has the value 58. The "%" sign is also a special case. It acts like a unary operator, but is really an instruction to the compiler on how FIGure - Calculator program PAGE 6 Full syntax of the Arithmetic statement to interpret any numeric constants that appear. See the sec- tion on alternate radices for more information. 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. Calculations are performed by priority of the operations being performed, in the following order: () All operations inside parentheses are performed first. -, ~, ABS, SIGN Unary operations. ^ Exponentiation. *, /, &, DIV, MOD Multiplication, division, and logical AND. +, -, ! Addition, subtraction, logical OR. =?, >?, =?, <=?, <>? Comparisons = Assignment of value to variable. Note that temporary radix operations don't appear in the above table, being really commands to the compiler rather than exe- cutable operations. If they were commands, however, they would rate with parentheses and the unary operations. FIGure - Calculator program PAGE 7 Radix control 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. 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 be- fore use (with no warning message). 1 is a special case, cal- ling 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 gre- ater than 14). Instead, an "@" sign is used to separate mantissa from exponent. On input, the default radix can be overridden by temporary radix operators, which have the following format: %B - Binary %O - Octal %D - Decimal %H - Hexadecimal %X - Hexadecimal %n - "n" is a decimal number indicating the desired radix. In this format, a space must separate the "n" from the number being represented. If the temporary radix operator appears before a number, it af- fects that number only. If it appears before a left paren- thesis, it affects all numbers between the left parenthesis and the corresponding right parenthesis unless overridden by anoth- er temporary radix operator. Examples: %X 10 = 16 (decimal) %X(0A+12) = 10+18 (decimal) %B(%D6+100) = 6+4 (decimal) %3 12+%5 14 = 5+9 (decimal) %O 1.2@2 = 1.2 (octal)*(8 squared) = 80 (decimal) Note that when the radix is greater than 10, numbers must begin with a decimal digit (eg: %X 0A, not %X A). 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. FIGure - Calculator program PAGE 8 Logical operations 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 lig- itimate INTEGER*4 number, and negating if appropriate. 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 con- verted back to REAL*4 by reversing the process that produced the scaled INTEGER*4 value. 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 lit- tle different from negating them, unless the fractional bits were stripped afterwards. Therefore, the contents of the pre- defined variable TRIM are ANDed to the results of the logical NOT before converting back to REAL*4. The author likes the re- sults 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: -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. 2^n - powers of 2. This results in only 1 bit being kept. 2^m-2^n with m>n - the difference of two powers of 2. Res- ults in all bits between the two given bits being kept. %O177777 - same as above, with m=16, n=0. Keep 1 word of data. 0 - special case that turns off trimming in case you think it's a bad idea. APPENDIX A This appendix covers installation under RSX. 1. Log in to a privileged account. 2. Copy the distribution kit to the directory of your choice. 3. Invoke the installation procedure by >@FIGINSRSX 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. 4. If desired, copy the FIG task to the directory of your choice (eg: [3,54] under M+, or [1,54] under M). 5. If desired, install FIG, and VMR it or edit your startup command file to have it installed on startup. 6. If desired, insert the help into MCR and/or DCL HELP. APPENDIX B This appendix covers installation under VMS. 1. Log in to a privileged account (eg: the SYSTEM ac- count). 2. Copy the distribution kit to the directory of your choice. 3. Invoke the installation procedure by >@FIGINSVMS This will build the FIG image to your specifications, and install HELP. 4. If desired, copy the FIG image to the directory of your choice (eg: SYS$SYSTEM). 5. If desired, define FIGURE as a foreign command in your SYLOGIN command procedure. For example: $ FIG*URE :== $SYS$SYSTEM:FIG APPENDIX C 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. Backus-Nauer is a "metalanguage" adapted to clear and un- ambiguous 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: <> - Used to enclose the names of formally defined syntax elements. :== - "Meta-assignment" operator. Used to define the syn- tax element on the left in terms of the definition on the right. {} - "Informal definition". Used to enclose an English (or at least non-Backus-Nauer) syntax element definition. | - "Exclusive or" operator. One and only one of the syn- tax elements separated by this operator must be select- ed. All other characters represent themselves, and are to be taken as literals. There is no explicit concatenation operator. Concatenation of syntax elements is represented by the concatenation of their formal representations. Spaces in Backus-Nauer are not significant (though they may be in the defined syntax). 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. :== 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 PAGE C-2 | o | p | q | r | s | t | u | v | w | x | y | z Note that FIGure is not sensitive to case. Lower case characters are translated to upper case characters be- fore parsing. :== 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 :== | :== 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. :== | 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 . :== | :== {One or more characters of blanks and/or tabs, if it occurs between two s} | {Zero or more characters of blanks or tabs otherwise} :== {Nothing at all. Indicates that the syntax element defined can be missing entirely.} :== {Any valid file name on your system.} How the omitted elements of a file name are supplied depends on the system. At the current time, defined defaults are: RSX - SY:.FIG; PAGE C-3 VMS - SYS$DISK:[].FIG; :== | | ; | A valid line is a list of zero or more statements fol- lowed optionally by a command, all separated by semico- lons. In general statements need to be compiled before execution, whereas commands are executed immediately by the compiler. :== | ; :== <@ command> | | | <@ command> :== @ This is a synonym for the (see below), but requires that the be insensitive to case (ie - valid when uppercased) and contain no embed- ded blanks. Not much of a restriction on the typical DEC system, but may be a real restriction if migrating FIGure to other systems. :== CHAIN " " This command causes the file you are currently execut- ing 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 . :== HELP | HELP {Help topic} 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. PAGE C-4 :== INCLUDE " " 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 . :== The syntax allows for others, but this is all that's implimented at the moment. :== | | The value of an is the value of the associated , , or :== | The value of an is the value of the asso- ciated or :== = | = The value of the or in which this occurs is assigned to each of the s in the list. :== The value of the is determined by the values of the s, and the exact nature of the . :== =? | >? | ? | >=? | <=? 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 PAGE C-5 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. :== | + | - | ! 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. :== | * | / | DIV | MOD | & 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 in- dividual s, evaluated left to right. :== | ^ 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 logar- ithms, and so cannot be done on negative values. :== | | | ( ) | ( ) | - | ~ | ABS | SIGN The value of the is the value of the , , or , ne- gated, 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. PAGE C-6 :== | | | | | In other (and clearer in this case) words, a variable is a letter followed (optionally) by 1 to 5 alphanumer- ics. The value of the variable is the value it ac- quired the last time it appeared in an . If it has not so appeared, its value is unde- fined, and an attempt to use it may return an error. NOTICE: The maximum size of a can be incre- ased in increments of 6 characters at the option of the installer. 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. :== % B | % O | % D | % H | % X | % 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 occur- ring 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" :== | | | | | | | TRUE | FALSE | TEN The value of TRUE is -1; the value of FALSE is 0, and the value of TEN is ten. :== PAGE C-7 RESTRICTION: If the radix under which the is being evaluated is greater than ten, the first in the must be a . 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. :== . | . 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. :== @ | @ + | @ - RESTRICTION: In the current implimentation, the must be less than hexadecimal 7F. This is hardware dependant, and may change for other implimen- tations. APPENDIX D Easy Modifications A couple of characteristics of FIGure are parameterized, and thus easily adjustable by changing FIGI01.FTN and rebuild- ing. The items of interest are: 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 vari- able you add. 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. APPENDIX E Migration to other systems. 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. 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: RTOSI (Convert Real to Scaled Integer) SITOR (Convert Scaled Integer to Real) RALIGN (Convert two Reals to Scaled Integers with the same scale factor) 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. 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 F Revision history: 86.080 Original release 86.108 Allow variable names more than 6 characters long. Note that the distribution is still built to only allow 6.