ENVICALC.TXT  www.merlyn.demon.co.uk  >= 2002-05-13;  see also the Pascal.


Copyrights apply; the code, text, etc. are presented only to help users.

ENVICALC.(PAS,EXE,TXT,ZIP) are available from the Web directory
<URL:http://www.merlyn.demon.co.uk/programs/>.

To do RPN Int32 calculations with parent Environment variables.

ENVICALC only needs 16-bit DOS;
OK in MSDOS, in Win3, Win9x DOS boxes; WinME, WinNT, Win2K, WinXP??


RPN

RPN evaluation is stack-based; the stack is 40 deep.  A given value
is pushed onto the Top of the Stack (ToS); an operator such as + removes
its arguments from the Top of the Stack, and pushes its result. Thus
arithmetic expressions do not need parentheses.  Additionally there are
26 named stores and one array indexed -100..+100.


PARAMETERS

The parameters presented on the command line or read from file are
processed in turn, operating on the stack.  Parameter letters are
case-dependent; initial / and - are not used, being themselves operators.

Lower-case letters are used for stack manipulation; upper-case are used
for I/O-related commands.

Semi-colon starting a parameter starts comment to end-of-line, apart from
redirection.

 0..9, +, -, $ : A parameter which starts with a digit, or which has more
  than one character and starts with + or - or $, is a number to be
  pushed; a number starting with $ is hexadecimal.

 p = Pop ToS
 d = Duplicate ToS
 s = Swap ToS and Next of stack
 g = replace ToS with ToSth of stack (Get)

 + = ToS := Next + ToS
 - = ToS := Next - ToS
 * = ToS := Next * ToS
 / = ToS := Next / ToS, using "div"
 % = ToS := Next mod ToS (write % as %% in a batch file)
 \ = %
 ^ = ToS := Next ^ ToS, Power
 ~ = ToS := Next ~ ToS, Absolute Difference

 n = ToS := - ToS, Negate
 a = ToS := Abs(ToS)
 i = ToS := Sign(ToS) : -1 0 +1

 &n = ToD :=      not ToS
 &a = ToS := Next and ToS
 &o = ToS := Next  or ToS
 &x = ToS := Next xor ToS

 (...) = loop till break
 = } { {} {= }= : if Pop ToS op 0, skip rest of line or break (...)
 N.B. use { } for < >, from 2001-08-01.

 # ], # [ : ] = pop into array, [ = push array copy; # is in -100..+100.
 ]x, [x (x=letter) : ]x = pop into store, [x = push store copy; A=a..Z=z

 @filename.ext = read commands, as parameters, from that file

 !envname = execute Env(envname)


Default output format is sign then ten decimal digits.
 S## = Number of decimal digits (more used if needed).
 B## = Output will start with character number B, default 1;
 L## = Output will be cut to L characters, default use all;
 These may change to handle negative numbers better?

 X# = monitoring (partial debug) output 1/0 = on/off; default off.

 G## = Generation; the environment manipulated is that of the ##'th
  ancestor back of the present program.  The effect of ##<0 is both
  undefined and unconsidered at present.  Default is 8, presumed to
  go back as far as possible.

 Exx = set the environment (Gen) variable xx = (pop ToS) directly,
 Vxx = as Exx but with less screen output;
 Pxx = send a 'SET xx=(pop ToS)' command to Standard Output (good for test),
 Qxx = as Pxx but '@SET xx=(pop ToS)',
 Rxx = send '%xx% (pop ToS)' (in %xx%, 'œ' is converted to '=').

 Rname = Write (Std out) Env(name)+ToS?  Use R. for just ToS.

 D# = Read 0..9 values (Std in).
  Note - may use either Read or Readln.  May change.  Do not use.

 T = Copy ToS to screen (B, L), T^ = write newline, Tstring = write string.

 Cxx = the value of the named string of environment Gen is pushed onto ToS.

 NOT: $ = I/O (E, V, P) is set to Hexadecimal,
 NOT: # = I/O (E, V, P) is set to Decimal (default state!),

 œ = Wait for <Enter>, useful in test,
 ? = Help.



OUTPUT

Output numbers are, by default, sign plus ten digits; signed 32-bit limit.


RUNTIME ERRORS

 201 : Range check error
 215 : Arithmetic overflow error
 216 : General Protection fault


STATUS

  Status values:
  0 = OK
  1 = No environment found
  2 = Empty environment found
  3 = No environment terminator found
  4 = Insufficient space for change
The Unit cannot at present expand the Environment; SETting (and clearing?)
the variable to be used could well do this.


NOTES

For the environment handling, including status, see the comment (and code)
in unit JRS_EnvU.pas (same directory).  It seems OK for DOS, Win3, Win98;
but that direct environment access is not effective in Windows NT.  XP?
Commands P & Q are necessarily safer than E or V and can always be used.

Windows NT:
 try     for /f %t in ('envicalc 3 4 + T') do @set XX=%t
or redirect P or Q output to a file and execute the file.


REFERENCES

Cf. <http://www.merlyn.demon.co.uk/programs/longcalc.pas>.


EXAMPLES

 1 To set EnvVar pp to 2^6 :
   ENVICALC 2 6 ^ Epp ; comment

 2 To increment four-digit EnvVar qq, which need not previously exist :
   ENVICALC Cqq 1 + B8 Vqq

 3 To set EnvVar pp to values 3, 2, 1 (in loop) :
   ENVICALC 3 ( d Epp 1 - d = )

 4 To set EnvVar pp to 2^6 (without using the ^ operator) :
   ENVICALC 6 1 ( 2 * s 1 - d = s ) p Vpp

 5 To set EnvVar pp to 6! :
   ENVICALC 6 1 ( 3 g * s 1 - d = s ) p Vpp

 6 To read EnvVar DIFSEC, then write EnvVars HH MM SS :
   ENVICALC Cdifsec d 60 %% B10 Ess 60 / d 60 %% Emm 60 / B6 Ehh

 7 To set the month and day of Gregorian Easter 2000 :
   ENVICALC 2000 @EASTER.SCR

 8 To compare an environment variable's magnitude
   (X to + or -, Y to -1 +0 +1) :
   ENVICALC C%envname% 45 - L1 d Ex i S1 L2 Ey

 9 To put the present age of a file, in seconds, into ZZ :
   NOWMINUS f16 Exx Ofilename.ext Eyy
   ENVICALC %xx% %yy% - d Ezz B99 d Exx Eyy

  ---