;[CALHELP.CAL] This is XCAL's primary help file. It documents XCAL's usage, ; general description, switches, and native functions. To ; create a XCAL.DOC file containing all available information ; about this installation of XCAL, including its current ; complement of macro libraries, redirect the output of the ; XCAL command "XCAL /H:?" to XCAL.DOC. ; ; For example: ; ; DECsystem-20/TOPS-20: xcal /h:? > xcal.doc ; IBM-PC/DOS or MS-DOS: xcal /h:? > xcal.doc ; Unix & Ultrix: xcal /h:? >xcal.doc ; ; VAX/VMS: $ photo xcal.doc ; $ xcal /h:? ; $ logout ; ;HelpSection What is XCAL? ;HelpStart ;HelpStart CAL,XCAL,CALHELP0 ;HelpStart GENERAL ;HelpStart XCAL XCAL is an extensible, programmable, double precision calculator. It can be run with arguments given on the command line for a one-shot evaluation of an expression or it can be run interactively in a wide variety of operating modes. XCAL is available for the following computers: . IBM-PC (and clones) running DOS or MS-DOS . All VAXen running Digital Equipment Corporation's VMS . All VAXen running BSD-Unix or DEC's Ultrix . DECsystem-20 running TOPS-20 . SUN-Sparc & SUN-386i running Sun-Os Note: Most other Unix based architectures are also supported; call or write for more information about newly supported architectures and operating systems. XCAL's operating environment on all supported computer systems is absolutely identical. Libraries of functions developed on one system can be moved to another and run without modification. This version of XCAL has over 100 builtin native functions and supports up to 1000 user defined functions implemented as macros. Macros may be defined by typing its definition, loaded from a XCAL library file, or from one or more startup initialization files. Note: XCAL looks for the files "xcalsys.cal" (a system wide initialization file) and "xcalini.cal" (a users' personal initialization file) at startup. If found, XCAL processes these files before processing the command line arguments. These files are not required and may be omitted from any XCAL installation. The precise locations of both "xcalsys.cal" and "xcalini.cal" vary from one architecture and operating system to another. Some of the most common implementations are listed below: IBM-PC & Clones: Both xcalini.cal and xcalsys.cal are in the directory pointed to by the XCAL environment variables "xcal" and "home". For example: AUTOEXEC.BAT: SET xcal=C:\XCAL\ SET home=C:\XCAL\ If "home" is not defined, XCAL looks for xcalini.cal in "xcal". VAX/VMS: "Sys$Login:" is searched for xcalini.cal. "XCAL:" is searched for xcalsys.cal. DECsystem-20/Tops-20: xcal:xcalsys.cal and ps:xcalini.cal All Unix environments: "home" is searched for xcalini.cal and "xcal" is searched for xcalsys.cal. SHAREWARE: This software is distributed under the SHAREWARE concept. SHAREWARE is software provided to you to "try before you buy". IT IS NOT FREE SOFTWARE. The author requests a registration fee from those who try XCAL and decide they will continue to use it. If you find this program useful, please give consideration for my time and effort in developing this tool. I intend to continue to develop and enhance XCAL. Please send $20 to the address above and ask for XCAL registration. In return, you will receive a floppy disk with the latest version of the program. You may use the software and make multiple backup copies of it. Copies of XCAL designated as SHAREWARE may be given to friends and uploaded to electronic bulletin boards provided no changes have been made to the distribution. ;HelpEnd XCAL ;HelpPage ;HelpSection Usage ;HelpStart USAGE,DEFAULT usage: xcal expression [ expression expression expression ...] or xcal variable=expression [ variable=expression variable=expression...] eg: xcal 5^(4*3!-22)-1 11+3^2*3! 1+1.6E-2 factor(18900) 24 65 1.016 1*2^2*3^3*5^2*7=18900 or: xcal /c Xcal>pi radius=1.5+2*3/4 length=2.7+0.3 width=5.0 3.14159265359 radius=3 length=3 width=5 Xcal>circlearea=pi*radius^2 2*sin(90) volume=length*width*height circlearea=28.2743334 2 ?Variable "height" not found. Xcal> Xcal>dec2hex(n)='/i:10 /o:16 n' dec2hex(255) fifteen=dec2hex(15) #FF fifteen=#F Xcal> Xcal>Area(Length,Width)='Length*Width' Xcal>Perimeter(Length,Width)='2*(Length+Width)' Xcal>Volume(Length,Width,Height)='Area(Length,Width)*Height' Xcal>SheetArea=Area(30,40) SheetPerim=Perimeter(30,40) SheetArea=1200 SheetPerim=140 Xcal>BoxVolume=Volume(30,40,10) BoxVolume=12000 Xcal>^C ;HelpEnd USAGE,DEFAULT ;HelpStart FORMULA,BASE,RADIX,EXPRESSION,EXPRESSIONS,ASSIGN,ASSIGNMENT Expressions ----------- Expressions may contain constants (numbers expressed as digits in any base from 2 to 36), user variables, reserved variables, user defined macros, native functions, supported operators (no embedded blanks), parentheses to force operator precedence, and quoted strings. ;HelpEnd FORMULA,BASE,RADIX,EXPRESSION,EXPRESSIONS,ASSIGN,ASSIGNMENT ;HelpStart CONSTANT,CONSTANTS,BASE PREFIX,#,` Constants --------- Constants may be integer or real values expressed as simple numerics or scientific notation. Either form may be preceded by a Base Prefix indicating the base in which to evaluate the constant. A Base Prefix can be a Grave (`) for Octal, a Pound-Sign (#) for Hexidecimal, a Colon (:) for Sexagesimal No- tation, or standard Base Prefix notation. That is, the string "0b" followed by a decimal number indicating the base of the constant, followed by the sign and value of the constant. For example: pi = 3.14159 = +0.314159e1 = 314159e-05 = 0b10+0.000314159e+4 2^8-1 = 255 = '377 = 0b8+377 = #FF = 0b16+FF = 0b2+11.111111e+110 radian = 57.29577951308232 = :57:17:44.806247096362 ;HelpEnd CONSTANT,CONSTANTS,BASE PREFIX,#,` ;HelpPage ;HelpStart VARIABLE,VARIABLES,PI Variables --------- Variable names are 1 to 10 "alphanumeric" characters (the first must be an "alpha") where "alpha" is any char in [A..Z] which is not a digit in the current input base. Variables are assigned with the syntax: Variable=Expression or Variable="A Quoted String" The only RESERVED variable name is "Pi" which XCAL defines accurate to 24 decimal places. XCAL will NOT let you redefine Pi. Additionally, there are some predefined variables which XCAL uses to control its environment. You can change them to suit your needs. They are: Variable Default Value What it does -------- ------------- ------------ AnyLog(Expr,Base)='Log(Expr)/Log(Base)' Macro; simply a convenience. CalExit '/S:Q' Macro; if invoked, it allows you to perform any desired "last-operation" before XCAL exits (such as saving your variables and macros). CalPrompt "Xcal>" String; it defines XCAL's prompt. CalVer "XCAL V3.1c Buffer=4kb " String; it defines XCAL's version #. CalEPrefix 0 String; the error message prefix. If defined, XCAL displays this string before displaying an error message. Typically, this is a video escape sequence allowing you to place error messages anywhere on the screen. CalESuffix 0 String; the error message suffix. If defined, XCAL displays this string after displaying an error message. Typically, it restores the cursor position. CalOPrefix 0 String; the output prefix. If its defined, XCAL displays this string before displaying its output. CalOSuffix 0 String; the output suffix. If its defined, XCAL displays this string after displaying its output. See the XCAL library files ANSI.CAL and PRIMES.CAL for examples of how to use these predefined variables. ;HelpEnd VARIABLE,VARIABLES,PI ;HelpPage ;HelpStart MACRO,MACROS Macros ------ Macro names are 1 to 10 "alphanumeric" characters (the first must be alpha- betic). Macros are defined with the syntax: MacroName='Expression1 [Expression2 Expression3 ...] ' or Macro(Arg1,Arg2, ..., Arg10)='Expression Expression Expression' Examples: CircleArea(Radius)='Pi*Radius*2' !Area of a Circle CylinderVol(Radius,Height)='CircleArea(Radius)*Height' Anylog(Expression,Base)='Log(Expression)/Log(Base)' RandTest='Seed=1 Rand(0) Rand(0) Rand(Seed) Rand(0) Rand(0)' Macro definitions may contain an arbitrary number of expressions separated by white space (a space or tab) but may not exceed 140 characters in overall length. The last expression evaluated in a macro is the value returned by that macro. Up to 10 parameters (or arguments) may be passed to a macro. The parameters are substituted for the arguments in the macro definition in the obvious manner. Expressions in macros may reference other macros. The maximum macro nesting level is 20. ;HelpEnd MACRO,MACROS ;HelpPage ;HelpStart QUOTE,QUOTED,STRING,STRINGS,QUOTED STRING Quoted String Commands ---------------------- A qouted string is any arbitrary text delimited by double-quotes. The text, including the Double Quote delimiters, must be less than 140 characters in length and may contain any arrangement of XCAL escape sequences. XCAL evaluates the quoted string replacing escape sequences with appropriate text and either displays the result or assigns it to a variable. Quoted strings are defined with the syntax: Xcal>"text of string" or Xcal>MyVariable="text of string" The first quoted string command displays the string "text of string" while the second assigns "text of string" to MyVariable and produces no output at all. The following is a list of escape sequences supported by XCAL: Escape Sequence XCAL's output --------------- ------------ \b Backspace \e The Escape character \f Formfeed \n Carriage-Return & Linefeed \r Carriage-Return \t Tab \{ The "{" character. \ The Ascii character whose decimal value is . \\ The "\" character. {variable} The string representation of the numeric value of a variable (converted from internal form to a string using the current output base). {macro} The string representation of the last computed value of a macro (converted from internal form to a string using the current output base). {$macro} The text of the definition of a macro. Some examples: xcal /c Xcal>"display this text\n" display this text Xcal>a=11 b=22 c=33 MyFunct(a,b,c)='a+b+c' MyFunct(a,b,c) a=11 b=22 c=33 66 Xcal>string="A={a}, B={b}, C={c}, while {$MyFunct}={MyFunct}\n" Xcal>/v ;Pi=3.14159265359 a=11 b=22 c=33 MyFunct(a,b,c)='a+b+c' ;66 string="A=11, B=22, C=33, while 'a+b+c'=66\n" Xcal>"{$string}" A=11, B=22, C=33, while 'a+b+c'=66 Xcal> ;HelpEnd QUOTE,QUOTED,STRING,STRINGS,QUOTED STRING ;HelpPage ;HelpSection Summary of Operators and Native Functions ;HelpStart DEFAULT ;HelpStart OPERATOR,OPERATORS,FUNCTION,FUNCTIONS,+,-,*,/,!,^,%,&,|,~,~&,~|,||,>>,<< Supported Operators Native functions of the form: FUNCT(expr) ------------------- ---------------------------------------------- + Unary Plus SIN COS TAN COT SEC CSC - Unary Minus (two's comp) SINH COSH TANH COTH SECH CSCH + Addition ASIN ACOS ATAN ACOT ASEC ACSC - Subtraction ASINH ACOSH ATANH ACOTH ASECH ACSCH * Multiplication * Squared and Cubed functions for all the above / Division are supported in the form: SIN2(x) for Sine ^ Exponentiation Squared and COS3(x) for Cosine Cubed. ! Factorial For Example: SIN2(30)=SIN(30)^2 % Integer Modulus EXP EXP2 EXP10 LOG LOG2 LOG10 & Bitwise AND ABS DEG INT FACTOR FRAC RAD | Bitwise OR RAND ROUND SQRT SIGN TRUNC ~ Bitwise NOT (ones comp) ~& Bitwise NAND Native functions of the form: FUNCT(expr,expr) ~| Bitwise NOR ---------------------------------------------- || Bitwise XOR (Exclusive Or) GCD(x,y) LCM(x,y) PRIMES(Min,Max) >> Bitwise Right Shift COMB(n,r) PERM(n,r) << Bitwise Left Shift For more information, use XCAL's help command switch "XCAL /H:topic". For help with XCAL's "/H" help command switch and its UNIX "More" style presentation, type "XCAL /H:help. You can create a complete printable architecture specific manual for this implementation of XCAL by redirecting XCAL's "help" output to a file with the command: xcal /h:? > xcal.doc ;HelpEnd OPERATOR,OPERATORS,FUNCTION,FUNCTIONS,+,-,*,/,!,^,%,&,|,~,~&,~|,||,>>,<< ;HelpEnd DEFAULT ;HelpStart PRECEDENCE,OPERATOR,OPERATORS Precedence and Order of Evaluation ---------------------------------- The table below summarizes the rules for precedence of operators. Operators on the same line have the same precedence. The rows are arranged in order of decreasing precedence. For example, Addition (+) and Subtraction (-) have the same precedence which is lower than that of Multiplication (*), Division (/), and Integer Modulus (%). Parenthesis '()' Unary Plus, Unary Minus, Not '+', '-', '~' Factorial '!' Exponentiation '^' Multiplication, Division, Modulus '*', '/', '%' Addition, Subtraction '+', '-' Right Shift, Left Shift '<<', '>>' And, Or, Nand, Nor, Exclusive Or (Xor) '&', '|', '~&', '~|', '||' Operands (including macros) Functions, Variables, Constants Operators of the same precedence in an expression are evaluated from left to right. ;HelpEnd PRECEDENCE,OPERATOR,OPERATORS ;HelpEnd GENERAL ;HelpPage ;HelpSection XCAL Command Switches ;HelpStart SWITCH,SWITCHES,/ ;HelpStart /B,/NB,/N:B,BASE PREFIX,RADIX,#,`,: /B Enable Base-Prefix Notation for values output. Base-Prefix Notation is always legal for type-in constants. ;HelpEnd /B,/NB,/N:B,BASE PREFIX,RADIX,#,`,: ;HelpStart /C,/NC,/N:C /C Set XCAL Command-Mode. Do not exit upon completion of command line processing. Display a "Xcal>" prompt and wait for more commands. This mode allows more rapid execution of all switches and commands. Exit from Command-Mode with /NC, /Q, or (of course) Control-C (^C). ;HelpEnd /C,/NC,/N:C ;HelpStart /D,/ND,/N:D,DEBUG,/D1,/D2 /D[:n] Enable Debugging. The optional "n" specifies the debugging level: /D:0 Maintainer Debug D2A Translator /D:1 User Debug Operators (default for "/D") /D:2 User Debug User Defined Macros /D:3 Maintainer Debug Macro Expansions, File-IO & Help /D:3 Maintainer Debug Macros & Data /D:4 Maintainer Debug Operators /D:5 Maintainer Debug FindCCP; Critical Points /D:6 Maintainer Debug FindCCP; Internals /D:7 Maintainer Debug Expression Parser (Structure-Level) /D:8 Maintainer Debug Expression Parser (Low-Level) /D:9 Maintainer Debug CCP: Expression Parser Video Debugger ;HelpEnd /D,/ND,/N:D,DEBUG,/D1,/D2 ;HelpStart /E,/NE,/N:E,ECHO /E Enable .CAL command file line echoing during /L:f. ;HelpEnd /E,/NE,/N:E,ECHO ;HelpStart /F,PRECISION,DIGITS /F[:]n Set output Max-Fractional-Digits (precision). The default maximum is a function of the output base and determined by the formula: MFD=(146/OutputBase)-2 and the default MFD is never less than 7. Note: It is possible to output results with precisions which exceed the mathematical limits of your computer. You can test your computer's mathematical precision limit with the command: "xcal /f:64 1/3" and count the number of consecutive 3's. ;HelpEnd /F,PRECISION,DIGITS ;HelpPage ;HelpStart /H,HELP,HELPFILE,TOPIC,TOPICS /H[:]["][topic]["][@HelpFile | @@HelpDirFile] This is the Help command switch. It must be terminated with white space and all its arguments are optional. It reads, translates, and outputs information from the active help library file. The default help library is defined by the files listed in "calibdir.cal" from the XCAL library. Supplying the @HelpFile directs XCAL to search the XCAL-Help formatted text of the specified file only for the topic given. Specifying the @@HelpDirFile will only search those files whose names are listed in the HelpDirFile. The default help function is invoked by running XCAL without supplying any command line arguments or by issuing a "/H" from within XCAL. It displays the entire contents of the default help library file. If a topic is specified, all sections referencing it are displayed. Double-Quotes are required only if the topic contains white space or an atsign (@). Multiple comma delineated topics may be specified. The topic "?" (specified as /h? or /h:?) is special. It processes all XCAL-Help formatted files found in the XCAL Library directory file. (The default XCAL Library directory file is CALIBDIR.CAL in the XCAL library. You can process all files specified in another Library directory file by using the @@HelpDirFile construct.) This form of the help command switch may be used to produce a complete help document of all XCAL's features, native functions, and macro libraries by redirecting XCAL's output to a file (ie. xcal /h:? > xcal.doc). By default XCAL displays its help in a manner which will, when output is redirected, produce a printable text file. XCAL will display its help in unix MORE style if the MODE option (/M:n) is set to the number of lines in the display window. For more information on the MODE option see the "/M" command switch. When displaying help in MORE style a screen full of information is presented. XCAL then waits for a response from you. Invalid responses simply beep. Valid responses are: E or e Exit from XCAL's help facility. Q or q Same as above. X or x Same as above. Display the next line of information and wait for another response. Display the next screen full of information and wait for another response. Discard the current help display and proceed to the next section matching any of the topics specified. ? Display this list of valid responses. ;HelpEnd /H,HELP,HELPFILE,TOPIC,TOPICS ;HelpPage ;HelpStart /I,INPUT BASE,RADIX /I[:]n Set default Input base to "n". The colon ":" is optional and "n" is always specified in base-10. All subsequent type-in values will be evaluated in base "n" unless specified in Base-Prefix Notation. ;HelpEnd /I,INPUT BASE,RADIX ;HelpStart /L,LOAD,GET,READ,INPUT,LIBRARY,CALINI,CALSYS,XCALINI,XCALSYS /L[:f] Load Variable and Macro library file "f". The default filename is "xcalsav.cal" in the default directory. Initialization text files may contain Variable and Macro definitions, expressions, constants, switches and comments. Comments begin with a " ;" or " !" and terminate at the end of a line. Library files may in turn load other library files. The maximum nesting depth is 10. Note: The file specification prefix "*" may be used to refer to a file in the system-wide XCAL library (the directory pointed to by the environment variable "xcal"). The file specification prefix "#" may be used to refer to a file your personal XCAL library (the directory pointed to by the environment variable "home"). ;HelpEnd /L,LOAD,GET,READ,INPUT,LIBRARY,CALINI,CALSYS,XCALINI,XCALSYS ;HelpStart /M,MODE,MODES,OPTION,OPTIONS /M[:]m Set a function specific mode or option; the default mode is Zero. Function specific modes are defined as follows: PRIMES: The number of columns to use for the prime display. /M:0 computes max number of columns for a video display. Example: /M:1 Primes(1000,2000) creates a one-column list of prime numbers from 1000 to 2000 inclusive. /H: The number of lines in the MORE style Help window. /M:0 implies the help window has infinite length (ie. don't pause). Example: "\e[3;21r\e[21;1H" /M:19 /H creates a 19 line help window in lines 3 thru 21 (on ANSI terminals and on PC's with ANSI.SYS loaded) and presents a MORE style display of XCAL's help in it. ;HelpEnd /M,MODE,MODES,OPTION,OPTIONS ;HelpStart /N,RESET,NO,DISABLE,DEBUG,BASE PREFIX,RADIX,RADIAN,RADIANS,#,` ;HelpStart /NB,/ND,/NE,/NC,/NR,/N:B,/N:D,/N:E,/N:C,/N:R,/B,/D,/E,/C,/R /N[:]x Disable or Reset option "x" (read as "No x"), where "/N:x" is one of: /N:B No Base-Prefix Notation on output. /N:D No Debugging at all. /N:E No .CAL command file line echoing during /L:f. /N:C No Command-Mode; this is the same as /Q. /N:R No transcendental Radians; use Degrees. ;HelpEnd /NB,/ND,/NE,/NC,/NR,/N:B,/N:D,/N:E,/N:C,/N:R,/B,/D,/E,/C,/R ;HelpEnd /N,RESET,NO,DISABLE,DEBUG,BASE PREFIX,RADIX,RADIAN,RADIANS,#,` ;HelpStart /O,OUTPUT BASE,RADIX /O[:]n Set default Output base to "n". The colon ":" is optional and "n" is always specified in base-10. All values output will be in base "n". For bases greater than 10, the chars [A..Z] will be used to represent the values 10 thru 36. The supported output bases are [2..36], and 60 for sexagesimal notation. ;HelpEnd /O,OUTPUT BASE,RADIX ;HelpPage ;HelpStart /Q,QUIT,EXIT /Q Quit (Exit) from Command-Mode. ;HelpEnd /Q,QUIT,EXIT ;HelpStart /R,/NR,/N:R,RADIAN,RADIANS,TRANSCENDENTAL,TRANSCENDENTAL UNITS,TRIG /R Set units for transcendental functions to Radians. By default, Arc functions accept a dimensionless quantity and return Degrees while all other transcendental functions accept Degrees and return a dimension- less quantity. The /R switch sets the units for all transcendental functions to Radians. ;HelpEnd /R,/NR,/N:R,RADIAN,RADIANS,TRANSCENDENTAL,TRANSCENDENTAL UNITS ;HelpStart /S,STATE,FLAGS,INITIAL STATE /S[:]x Save/Restore or Set/Reset XCAL's State. Option "x" is one of: /S:E Reset Error flag and Quiet mode (Enable output). /S:I Restore XCAL's Initial State /S:Q Set Quiet mode; disable all output. /S:R Restore XCAL's State last saved with "/S:S". /S:S Save XCAL's present State. The flags saved are: Base-Prefix (/B) Command file echo function (/E) Debugging level (/D) Input and Output Base (/I and /O) Max-Fractional-Digits (/F) User Mode value (/M:m) Quiet mode (/S:Q) Transcendental units (/R) ;HelpEnd /S,STATE,FLAGS,INITIAL STATE ;HelpStart /T,DATE,TIME,TIMER,MONTH,DAY,WEEKDAY,HOURS,MINUTES,SECONDS /T[:n] Display current date and time. The output format is determined by the optional argument n whose default value is 11. The legal values for n (which may be OR'd together) are: 0 "Weekday dd-Mmm-yy hh:mm:ss" (default) 1 "Weekday " 2 "dd-Mmm-yy " 4 "Month dd, yyyy " 8 "hh:mm:ss" 16 "[Timer Reset]" (same as /T[:]R) 32 "hh:mm:ss" since last "[Timer Reset]" (same as /T[:]S) ;HelpEnd /T,DATE,TIME,TIMER,MONTH,DAY,WEEKDAY,HOURS,MINUTES,SECONDS ;HelpStart /V,VARIABLE,VARIABLES,MACRO,MACROS /V Display all defined Variables and Macros. Variables have the form: Variable= Macro definitions have the form: MacroName='' ; or MacroName(arg1, ...argN)='' ; ;HelpEnd /V,VARIABLE,VARIABLES,MACRO,MACROS ;HelpStart /W,WRITE,SAVE,STORE,FILE,OUTPUT,CALSAV,XCALSAV /W[:f] Write all defined Variables and Macros in text file "f". The default filename is "xcalsav.cal" in the default directory. Note: The file specification prefix "*" may be used to refer to a file in the system-wide XCAL library (the directory pointed to by the environment variable "xcal"). The file specification prefix "#" may be used to refer to a file your personal XCAL library (the directory pointed to by the environment variable "home"). ;HelpEnd /W,WRITE,SAVE,STORE,FILE,OUTPUT,CALSAV,XCALSAV ;HelpEnd SWITCH,SWITCHES,/ ;HelpEnd CAL,XCAL,CALHELP0 ;HelpEnd ;********************************************************************** ;******* End of CALHELP0.CAL ******* ;**********************************************************************