Black Box 4/BlackBox.cdr/dosutils/env18a.arj/ENV.DOC

Text File | 1992-04-26 | 28KB | 703 lines

             ENV - The Master Environment Utility
                         Version 1.8a

                              by

                         Kjell Eikland
                      674 St. John's Drive
                      Camp Hill, PA 17011

-----------------------------------------------------------------

ENV is a DOS environment utility which does everything the
internal SET command does, and much more.  If these are new
concepts to you, then you may read quickly through the Appendix
that contains a description of what the environment is and what
the SET command does.  ENV provides:

...  a powerful calculator with a large complement of scientific
     functions, date and time functions (with time zone
     adjustments), and also logical operators.

...  complete text manipulation functions, freely intermixable
     with the mathematical calculation services.

...  interactive editing of existing or new environment
     variables, for example the content of the PATH.

...  automatic prompting for input from the user.

...  read data from text, database (dBase) and spreadsheet files
     (Lotus 123 and Symphony, Borland Quattro and Quattro Pro), as
     well as complex comma-delimited environment variable values.

...  testing of environment variables with the result reported in
     DOS's ERRORLEVEL variable and in an environment variable.

...  batch commands to speed the execution time and to quickly
     insert new environment variables that may be stored in a
     "library".

...  selective listing, erasure and calculation of the
     environment's content based on an extended use of the
     * and ? wild-cards.

...  a simple report generator to facilitate the development of
     useful routines, such as a DOS command line calculator.

...  report generation to any DOS output file, device or pipe.

...  full support for DOS input pipes, such that the DOS
     commands SORT and FIND may be used to dramatically increase
     the possible uses of ENV.

...  free use of any environment present in your computer in
     addition to the standard use of the master DOS environment.

...  status information on the present environment, including the
     environment owner's name.

Licencing information
---------------------

ENV is a Shareware program.  That means you may try it out on
your computer for a limited period of time.  If you find that you
would like to keep ENV on your computer, please send a check for
US$15.00 to the address given on the first page, as indicated in
enclosed order form.


     ENV is written and copyrighted by Kjell Eikland 1991-92.



                      ----------------



      Feedback welcome through Compuserve (CIS) 72461,556


Using ENV


General syntax
--------------

ENV uses the following command structure:

     ENV [general command] [specific action]


The general commands are:

     HELP           Provide help for ENV
     STATUS         Show environment usage
     LIST           Display the content of the environment
     EDIT           Do interactive editing of a variable
     ERASE          Erase one or more variables
     EXIST          Test for the existence of a variable
     CALC           Compute the value of a text or mathematical
                    expression
     ASK            Interactively ask to define an environment
                    variable
     SET            Define the content of a variable
     SET%           As SET but add a leading and trailing %
                    to create an environment variable reference
     TEST           Test for equality


In its simplest form a mathematical calculation could be
performed by writing:

     ENV SET TEST=(1+2)/3
     ENV CALC TEST              ( or ENV CALC TEST=(1+2)/3 )
     ENV LIST TEST
     ENV ERASE TEST


(Of course, this is better implemented in an ENV batch file so
that DOS does not have to reload ENV every time)  Similarly, a
simple text expression could be written:

     ENV SET TEST=a+b+c+d+MID(efgh~2~2)
     etc.


or with variable substitution:

     ENV SET TEST=MID(%COMSPEC%~3~LENGTH(%COMSPEC%)-2)
     etc.

For convenience you may also write ENV CALC TEST=MID(...) to
directly define and evaluate the expression.


Reading data from files
-----------------------

ENV can read data from text (ASCII), dBase and spreadsheet
files. This can either be done through I/O redirection and
piping (see next section) or by using three special
functions in ENV.  These functions are READLN to read a line
from a text file, READDB to read a field in a dBase file, and
READSS to read the value of a cell in a spreadsheet file. A
line in a text file may then be retrieved and analyzed by
writing:

     ENV CALC TEST=MID(READLN(CONFIG.SYS~3)~5~8)

This would define the environment variable TEST as eight
characters from the fifth position in the third line of the
CONFIG.SYS file.  Similarly, a spreadsheed cell value could
be referenced by writing:

     ENV CALC TEST=READSS(TESTDATA.WK1~AB45)

This would define the variable TEST as the value of cell AB45
in the spreadsheet file TESTDATA.WK1.  Lotus 123 and Symphony,
as well as Borland's Quattro and Quattro Pro file formats are
supported.  Microsoft Excel files are not supported directly,
but must be saved as a Lotus file.

The value of a field in a dBase file could be retrieved by
defining:

     ENV CALC TEST=READDB(DATABASE~54~LASTNAME), or
     ENV CALC TEST=READDB(DATABASE~54~FIELD4), or

Here the value of the field LASTNAME in the 54th record in the
DATABASE.DBF file is put in the environment variable TEST.
If the name of the field is not known, but the column is then
you may write FIELDx, where x is the column (field) number in
the file. Note that - contrary to READLN and READSS - a file
extension is not needed. An extension of DBF is always assumed.


Using redirection and piping
----------------------------

ENV supports redirection and piping for all of the relevant
commands.  For example, the current directory may be retrieved by
writing:

     CD|ENV SET CURDIR


The environment may be sorted, saved and restored with the
commands:

     ENV LIST * SET {GET*NAME}={GET*VALUE}|SORT >ENVSAVE.TMP
     ENV ERASE *
     ENV BATCH <ENVSAVE.TMP


Similarly, a sorted listing of the environment may be printed by
writing:

     ENV LIST *|SORT >PRN


If you wish to store the version of the operating system in an
environment variable you would type:

     VER|FIND "Version"|ENV SET DOSVERSION


These are only some of the possible uses of redirection and
piping.  Particularly together with DOS's FIND and type
utilities, as well as the enhanced ability of DOS 5.0 of scan
subdirectories, there is effectively no limit to the possible
uses of redirection and piping in ENV.


Playing music
-------------

The most useless feature of ENV is probably its ability to use
the computer's otherwise "dumb" built-in speaker to give
something that resembles music. This PLAY feature is used as
the BATCH command and requires music data piped or redirected
from DOS. To play the enclosed TWILIGHT.MUS Twilight Zone
piece you would issue the commands:

         ENV SET ENVTEMPO=50             (beats per second)
         ENV PLAY <TWILIGHT.MUS

The Music file is a regular ASCII comma-delimited file with a
series of lines with the following structure:

         <Octave level>,<Tone>,<Duration>,<Rest>

         f.ex.: 3,C,4,0
                2,B,8,2
                3,C+,8,0

The octave level is normally in the range 2-4. The Tone is
an entry in the 12-tone scale C,C+,D,D+,E,F,F+,G,G+,A,A+,B.
The Duration and Rest entries are normally 0,2,4,8,16,32.


The use of wild-cards
---------------------

In certain situations, it is convenient or necessary to specify
more than one environment variable in one statement.  In DOS, a
similar situation arises when you wish to have a directory
listing of more than one file - say of all files whose names
begin with the letter A.  You would then type "DIR A*.*".  If the
files of interest have names with three letters you would type
"DIR ???.*".  DOS uses the character "*" to signify any character
or many characters.  "?" signifies a character.  Collectively,
"*" and "?" are called wild-cards.

The big problem with DOS's use of wild-cards wildcards is that
"*" may not be followed by a letter.  That means that it is
impossible to have DOS list all files that end with an "E"; i.e.
the command "DIR *E.*" is incomprehensible to DOS.

With this introduction it is fairly obvious that ENV handles full
wild-card usage.  Thus, if you wish to list all variables ending
with an "E" followed by two other letters you would write
"ENV LIST *E??".  The ENV LIST, ERASE and CALC commands all use
this syntax. You may therefore calculate all variables that
begin with a T by writing:

     ENV CALC T*

In order to protect the PATH, PROMPT and other variables from
accidental erasure you may define the ENVPROTECT variable to
include these variables, separated by commas. Wild-cards are
of course supported. The COMSPEC variable is always protected.

Additionally, in the case of piped input (consult the section on
"Using DOS pipes and files with ENV" if this concept is new to
you) to the ENV SET command an entire file or listing may be
loaded into the environment with numbered lines.  Two examples of
this usage:

     DIR|SORT|ENV SET FILE*        This would load the
                                   environment with the names of
                                   all files in the current
                                   directory sorted
                                   alphabetically, and given the
                                   names FILE001, FILE002, etc.

     TYPE CONFIG.SYS|ENV SET CFG*  This would load the
                                   environment with all lines in
                                   the CONFIG.SYS file, numbered
                                   consecutively.


Calculator operators and functions
----------------------------------

Math:

     Operators           Functions              1-0 Logic

  +  Addition            ABS(■Number■)       >  Greater than {GT}
  -  Subtraction         INT(■Number■)       <  Less than    {LT}
  *  Multiplication      ROUND(■Number■)     ≡  Equal to     {EQ}
  /  Division            LN(■Number■)        ≥  GT or EQ to  {GE}
  ^  Exponentiation      EXP(■Number■)       ≤  LT or EQ to  {LE}
  √  n'th root           SIN(■Number■)
     {ROOT}              ASIN(■Number■)
  @  Modulo/remainder    LRAND(■Number■)
     {MOD}               NRAND(■Number■)
  ÷  Integer division    !(■Number■)
     {DIV}               GAMMA(■Number■)
                         CUMNORM(■Number■)
                         PI()

The BAND function forces a number to be between an upper and a lower
value, as presented below:

     BAND(■LowLimit■~■TestNumber■~■HighLimit■)

The functions DegC and DegF convert temperatures between Centigrade/
Celsius and Fahrenheit, and for the oilman the function DegAPI
converts the specific gravity of oil to the American Petroleum
Institute index for oil weight.

To complement the INT function that returns the integer part of a
number, the FRAC function returns the fractional part and the FLOOR
function returns the same as INT when the number is positive and
the next lower integer when the number is negative.

In addition to the SIN/ASIN functions, COS/ACOS and TAN/ATAN are
also defined.  All trigonometric functions use radians.  In
order to avoid the dependence on high ASCII characters above 128
synonyms are provided for these operators.  For example, the ≡
equality test can be substituted by writing {EQ} as follows:

     ENV CALC TEST=123{EQ}%OTHERNUM%

This would yield either 1 or 0 as a value for TEST, depending on
the value of %OTHERNUM%.


Date:
-----

  TIMENOW(■Time Zone Offset■)      Current time in HH.MMSS format
  DATENOW(■Time Zone Offset■)      Current date in YYYY.MMDD
                                   format
  DECTIME(■HMS time number■)       Convert time to decimal format
  HMSTIME(■DEC time number■)       Convert time to HMS format
  DAYS(■YYYY.MMDD day number■)     Days since 15 Oct.1582 serial
                                   number
  YMD(■Date serial number■)        Convert serial date to
                                   YYYY.MMDD format
  ROMAN(■Arabic integer number■)   Convert to a roman number
  ARABIC(■Roman number■)           Convert back to an arabic number


As an example, the expression DAYS(DATENOW())-DAYS(1918.1111)
would give the number of days since 11 november 1918.  The
expression DATENOW(-3) would give the date in current time zone
less 3 hours.


Text:
-----

  LENGTH(■String■)                           Length of a string
  POS(■Target■~■String■)                     Position of a
                                             substring
  MID(■String■~■StartPos■~■Chars■)           Extract a substring
  LEFT(■String■~■Chars■)                     Extract the leftmost
                                             characters in a string
  RIGHT(■String■~■Chars■)                    Extract the rightmost
                                             characters in a string
  INSERT(■AddString■~■String■~■StartPos■)    Insert a string into
                                             a string
  DELETE(■String■~■StartPos■~■Count■)        Delete characters in
                                             a string
  TRIM(■String■)                             Remove leading and
                                             trailing spaces
  UCASE(■String■)                            Convert string to
                                             upper case
  LCASE(■String■)                            Convert string to
                                             lower case
  ASC(■Character■)                           ASCII value of a
                                             character
  CHR(■AsciiValue■)                          Character of an
                                             ASCII code
  TEXT(■Number/Expression■)                  Convert number to text
  COPY(■Character■~■Count■)                  Replicate a
                                             character
  STATIC(■String■)                           Literal text; do not
                                             evaluate in CALC

NB! Note that from ENV version 1.7x the former TEXT function
    has been given the new name STATIC. TEXT now internally
    converts a number to a string or text format.

The expression MID(%COMSPEC%~1~2) would give the disk drive where
command processor COMMAND.COM is located.  The expression
COPY(CHR(205)~LENGTH(%PATH%)) would create a string of ═'s with a
lenght equal to the current length of the PATH variable.


File:
-----

  READLN(■FileName■~■LineNumber■)        Get a line in a text file
  READSS(■FileName■~■SpreadSheetCell■)   Get the value of a cell
                                         (i.e. A1) in a spread-
                                         sheet file
  READDB(■RootName■~■RecordNo■~■Field■)  Get the value of a field
                                         in a dBase file

These functions are fully comparable with all of the other
functions in ENV.  This means that they may be nested with any
other relevant function, including themselves.

In addition to these functions, environment variables may be
defined as a series of comma-delimited values. The individual
entries may be accessed by writing the name of the environment
variable followed by a number enclosed between parentheses in
the same manner as for a regular mathematical or string function.
In the environment variable DATA defined as:

  ENV SET DATA=1,2/3,STATIC(3.14+2),(This is a test),432+EXP(4)

subelements may therefore be accessed by writing:

  ENV CALC TEST=DATA(2)             Giving TEST=0.6666
  ENV CALC TEST=DATA(3)             Giving TEST=3.14+2
  ENV CALC TEST=DATA(4)             Giving TEST=This is a test

Sometimes it is inconvenient or undersired to have ENV
automatically evaluate the expressions in a comma-delimited
line. In the example above, the second item was forced
static by use of the STATIC function but even this may be
inconvenient. Instead, such automatic evaluation can be
avoided by writing the reference to the field number between
DOUBLE parentheses. In the second DATA field above, the
result would therefore have been:

  ENV CALC TEST=DATA((2))           Giving TEST=2/3

If an other separator character is desired then the ENVARRAY
environment variable may be defined in the master environment,
containing such a new character. For example, if you wish to
access the third element within the PATH environment variable
then write:

  ENV SET ENVARRAY=;
  ENV CALC TEST=PATH(3)

As always, full use of functions and expressions is allowed
in a nested and recursive fashion.


Internal:
---------

  {ENV*OWNER}       Get the owner of the current environment
  {ENV*SIZE}        Retrieve the total size of the environment
  {ENV*USED}        Compute bytes currently used in the
                    environment
  {ENV*COUNT}       Total the current number of variables defined
  {GET*DISK}        Obtain the default/current disk drive
  {GET*DIR}         Obtain the default/current directory
  {GET*NAME}        Return the name of the currently active
                    variable
  {GET*VALUE}       Return the value of the currently active
                    variable
  {GET*DOSLIST}     Get DOS's list separator/parser character
  {GET*COUNTRY}     Obtain a record of DOS's country-specific
                    settings; including time, date and punctuation.
                    These values are separated by the list
                    separator obtained from {GET*DOSLIST}.


How ENV calculates numbers and strings
--------------------------------------

ENV uses standard algebraic rules for evaluating expressions.
That means that unless overridden by parentheses, the following
order is used for the various operators:

        +-       evaluated last
        */@÷
        ^√
        ≡≤≥      evaluated first

Functions are obviously only computed when their parameters have
been fully evaluated.

In general, all ENV function names are reserved, and environment
variables with these names should not be defined. However, ENV
allows this in a few cases, in which case the user-defined
"function" or comma-delimited environment variable overrides the
standard ENV function. Such override is possible for ENV's Date/
Time and Mathematical functions.

ENV attempts to evaluate all expressions as both text and number,
and - depending on the context - then determines from the context
or tries to make an intelligent guess about what is meant.
Unless changed by the calculations in ENV the default values for
any suboperation for a string is an empty string and for a
number a 0 (zero).

This means that sometimes ENV will be wrong, and needs to be
explicitly told what the user means. A typical example of such
a problem is when replacing text in a string using the REPLACE
function, such as in the commented examples below where the
functions STATIC or TEXT are used to solve the problem.

  REPLACE(12345~4~6)
  Returns a zero since all parameters are numbers when strings
  are assumed.

  REPLACE(STATIC(12345)~4~6)
  Returns 12345 since no string is specified for replacement.

  REPLACE(STATIC(12345)~STATIC(4)~6)
  Returns 1235, simply eliminating the 4 since the 6 never
  enters the picture as a string; instead the default empty
  string is assumed.

  REPLACE(STATIC(12345)~STATIC(4)~STATIC(6))
  This finally produces the correct result 12365.

The difference between STATIC and TEXT is that TEXT may contain
calculations within the parenteses, whereas STATIC assumes
what the name implies, that no modifications are to be done.
STATIC always assumes that the result is a character string.


Accessing other than the master environment
-------------------------------------------

Any environment may be accessed by defining ENVLEVEL=■n■ in the
master environment, where ■n■ is an integer specifying the loaded
order of the desired program.  The master environment may always
be accessed by ENV MASTER ■EnvCommand■.

    ENV MASTER SET ENVLEVEL=3     (use the third environment)
    ENV MASTER ERASE ENVLEVEL     (go back to the master env.)

By issuing the ENV STATUS command the name of owner of the
current environment will be displayed.


Changing default modes of operation
-----------------------------------
As already discussed in the section above, ENV uses special
environment variables for its own purposes in addition to the
ENVLEVEL variable. "ME" indicates that the variable must be
defined in the master environment to take effect.

      ENVPROTECT   If defined, contains a list of environment
                   variables protected from erasure with
                   each variable name separated by a comma.
                   In no instance is it allowed to erase the
                   COMSPEC variable. Wild-cards allowed. (ME)
      ENVDECIMALS  Sets the maximum number of decimals for
                   numerical results; the default is 5. (ME)
      ENVTRIM      If set to False or 0 this will suppress the
                   automatic removal of leading and trailing
                   spaces in command lines. (ME)
      ENVQUIET     If set to True or 1 this will suppress the
                   display of error messages. (ME)
      ENVPARSE     This may be defined to change the default
                   parsing/separator character in ENV (~)
                   functions to any other character
                   desired. (ME)
      ENVARRAY     Define this to change the default list
                   element separator from a comma to any other
                   character when accessing items within an
                   environment variable. (ME)

      ENVERROR     If defined in the active environment then
                   ENV will report all errors and test results
                   in the ENVERROR variable in addition to
                   setting the DOS ERRORLEVEL when applicable

It is important to remember that it is only the value of these
variables in the MASTER environment that count, and that the
value of these are retrieved at the beginning of ENV.  This
means that the mode of operation cannot be changed in the
middle of an ENV batch file. The only exeption to this rule
is the ENVERROR variable, which is always read and set in the
currently active environment (as set by ENVLEVEL).

                           Appendix
              The INs and OUTs of the SET command

SET is an internal DOS command which adds, changes or deletes
elements in the command processor's environment.  Being an
internal command, you will not see a SET.COM or SET.EXE file in
any directory listing.  The command processor is the program that
gives you the DOS prompt (i.e. A> or C>) where you can issue DOS
commands and start programs.  Normally the command processor is a
file with the name COMMAND.COM.

The command processor (and all programs) have reserved a portion
of memory to store parameters that are necessary for the
execution of the program, or simply useful.  This area of memory
is called the "environment".  The command processor's environment
is called the "master environment" because it is the first
created and one that is always there as long as your computer is
turned on.

The master environment always contains two elements, namely
COMSPEC and PATH.  In the simplest setup possible for your
computer these two elements have the values:

     PATH=
     COMSPEC=A:\COMMAND.COM

You may see the content of your master environment by typing SET
from the DOS prompt.

COMSPEC identifies where a program may find the command processor
and what it is called.  In some installations the command
processor may have the name 4DOS.COM.  PATH identifies where DOS
should look for programs when the program is not located in the
present directory.  The peculiar thing about PATH is that it may
contain nothing (nothing to the right of the =-sign).  Any other
relationship is removed if it doesn't contain anything.

Another standard element in the master environment is PROMPT.  By
adding PROMPT to your environment you can change the way the
command processor prompts you for a command.  If you type:

     SET PROMPT=$P$G

the prompt would, for example, look like "A:\DATA>".  Other
values for PROMPT are described in your DOS manual.  By typing
SET, your environment would now contain:

     PATH=
     COMSPEC=A:\COMMAND.COM
     PROMPT=$P$G

Please note the capitalization rules here.  The identifier or
name of the variable (e.g. PATH or COMSPEC) are always
capitalized regardless how you typed them.  The value on the
right hand side, however, will be copied as you type it.  The
general format for using the SET command is then:

     SET                      List all entries in the
                              environment.

     SET <Name>=<Value>       Define a new or replace an
                              existing relationship.

     SET <Name>=              Remove an entry in the
                              environment.


Generally, these possible usage options are summarized by:

     SET [<Name>=[<Value>]]


where the square brackets indicate a user option.  <Value> may be
any combination of valid letters and characters, but can also
contain environment variables!  Now, how can you as a user make
use of environment variables?  Some programs require that you
define certain environment variables, but because of DOS's rather
rudimentary batch command language and the limited capabilities
of the SET command the usefulness is relatively limited.

By enclosing the variable name between %-signs in a batch file
the value of that variable will be substituted.  Many variables
may be substituted on the same line.  For example, consider the
following segment of a batch file:

     SET OLDPATH=%PATH%
     SET PATH=C:\
     ECHO Starting a secondary command processor
     ECHO I'm using %COMSPEC% with the path %PATH%
     %COMSPEC% /E:512
     SET PATH=%OLDPATH%
     SET OLDPATH=


The default size of the environment is between 128 and 180 bytes,
depending on the DOS version.  You may specify a larger
environment using the SHELL command in the CONFIG.SYS setup file
(see your DOS manual).  The maximum size of the environment is
32 kilobytes in DOS 3.2 and higher; enough for most purposes.

But every time you start a program, DOS will create a new (child)
environment for that program, leaving the command processor's
environment in the dust.  All unused space will be eliminated in
the child environment.  That means that the program essentially
receives a "dead-end" environment.  In a multi-tasking world,
such as under Microsoft Windows or QuarterDeck's DesqView,
programs cannot communicate through their respective environments.
Microsoft Windows even uses two environments at the same time,
neither of any use for the normal user since they have been
truncated and are not easily accessible by other programs or the
SET command!

... until the appearance of ENV!