eX version 0.4b User's Manual                         File eXMan25.txt
(C) Copyright 1995, 1996 William E. Wilgus III.   All rights reserved.


eX Commands & Modes

Commands

                              Caution

Since they destroy all data within the data entity type, allocation
commands should (normally) be executed prior to the placement of data
within that data entity type.  Therefore, the correct argument
placement to load or execute a macro and re-allocate macros in the
invocation command would be either of 

                    ex /am# /lmMacro.Fil
                    ex /am# MacroSpecification

 
eX commands may be employed as part of the eX invocation, within
macros, or---with the exception of the inter-active mode command
itself---within the inter-active mode.  All of them begin with a slash
(/), or ASCII code 47, that is followed by at least one character that
specifies the basic command.  This or any other additional alphabetic
character that is used to specify the command may be given in either
(or mixed) case.  
 
eX command arguments may be given in two ways.  

  1. As a literal delimited by the preceding portion of the command
     and the whitespace (if any) that follows it.  In the case where
     multiple arguments are used with a command, a comma (,) is used
     as the inter-argument delimiter.  Except for a decimal point,
     numeric literals must be un-formatted.  

                         /a@12,12

  2. As an eX term or eXpression that is seperated from the preceding
     portion of the command by whitespace.  The value(s) returned by
     the term or eXpression is (are) applied as the command
     argument(s).  In the case where multiple arguments are used with
     a command, a comma followed by whitespace is used as the
     inter-argument delimiter.  In this case, the term may be a
     literal, or an eXpression may include literals.  Such numeric
     literals may be formatted, and string literals must be 
     delimited by a pair of either double quotes (", ASCII code 34) or
     reverse apostrophes (`, ASCII code 96).  
 
     The use of variables as argument terms or within argument
     expressions on the eX invocation command line will work if the
     variable(s) have been assigned through an action caused by a
     preceding element of the eX invocation command such as `load
     variable' command precedes.  Just about anything can be done with
     this method.  

     I admit that until this point, I haven't thought of eX command
     recursion (using an eX command in an eX command argument) and
     don't know if it will work.  I doubt a command could use itself
     in the argument, but I think it could use others.  Something more
     to try!  I know this works: 

                    /a@ _Planes := 2, _Levels := 10


 
Data Entity Allocation
 
The letter A or a following the eX command token / indicates a data
entity allocation command.  The subsequent letter or character(s)
identify the data entity.  
 
Accumulators
                    /a@Planes#,Levels#
     The default allocation is 1 plane (yielding planes -2 thru 1)
     and 16 levels (yielding levels 0 thru 16).

Files
                    /af#<<,#<<,#>>>>

     The first argument (#) is the maximum number of files that may  
     be concurrently defined (0--255). The default is 32.  The
     optional second argument (#) represents the total number of
     random access file variables that will be used.  If not given, it
     is taken to be zero (0).  The default is 255.  The optional third
     argument (#) is the DOS open file limit exclusive of stderr,
     stdin, stdout, stdlist, and stdaux.  If not given, it will be
     taken to be the normal 15 (which is the default).  But if the
     open file limit is given, a random access variable argument must
     be given. 

     If running MS-DOS/PC-DOS version 3.3 or subsequent, eX will
     attempt to utilize an operating system capability to allow the
     number of files given in the argument to be open concurrently.  
     (The maximum allowed by DOS is 255.)  However, an argument of
     more than 15 requires that the DOS command FILES, with an
     assignment value >= to the argument, was included in the DOS file
     CONFIG.SYS.  NOTE that due to a bug in DOS, the FILES argument
     will be forced to odd by adding 1 if it is even.  If the number
     of files requested to be open concurrently cannot be complied
     with, the argument is forced to 15.  

Invocation Arguments
                              /a/#
     where # is the number of arguments to be provided for.  The
     default is 10.

Loops
                              /al#
     where # is the maximum loop nesting depth to be provided for.  
     The default is 16.

Macros
                              /am#
     where # is the number of macros to be allocated.  The
     default is 64. 

String Variables
                              /a$#
     where # is the number of string variables to be allocated.  The
     default is 64. 

Short Variables
                              /a_#
     where # is the number of short variables to be allocated.  The
     default is 64. 

Long Variables
                              /a__#
     where # is the number of long variables to be allocated.  The
     default is 64. 

Single Variables
                              /a.#
     where # is the number of single precision variables to be  
     allocated.  The default is 64. 

Double Variables
                              /a..#
     where # is the number of double precision variables to be 
     allocated.  The default is 64. 


Combined Variable Allocation
                              /av#
     where the single argument # is the number of variables to be  
     allocated for each of the variable types.



Input/Output


Load Macro
                    /lmFileSpecification<<,#>>
     The optional # specifies the macro number the macro is to be 
     loaded as.  If the macro number is not given, the following
     applies.  As an eX invocation argument, loads the specified macro
     as the first available macro number greater than 1.  Within a
     macro, loads the specified macro as the first available macro  
     number greater than 0.  If the macro file does not exist, the
     file will be created and the macro will be loaded as a null ("")
     macro.  It does not cause that or any other macro to be executed.
 
Load Variables
                    /lvFileSpecification$
     Loads the variables contained in the (sequential) file specified.
     The first entry for a variable is its identifier and the second
     is its value.  If a variable in the file does not already exist
     in memory, the variable is created (in memory) and assigned its
     value from the file.  If a variable in the file already exists in
     memory, it is assigned the value from the file.  

     A brief example of a variable file, as viewed with a text editor
     or similar program follows.

               _ShortVar
               123
               __LongVar
               123,456
               .SingleVar
               19.95
               ..DoubleVar
               12,986,458.001985
               $tringVar
               Mr. John Doe

Printer Width
                              /p#
     where # represents the printer width.  Sets the printer width
     (print columns) to # characters.  (eX sends carriage returns
     (ASCII code 13) to the printer when it believes the printer to be
     at the end of the print line.)  The default is 80, and the
     maximum is 255---which turns eX's printer width feature off. 

Save Macro
                    /smFileSpecification<<,a>>
     Saves the specified macro in the file of the same name (and
     path).  If the file previously existed, it will be over-written
     unless the optional a (append) is given to append the macro to
     the file.  If the macro is not memory resident, the macro will be
     created and saved as a null ("") macro.  

Save Variables
     Saves variables in the specified file using the format shown with
     the load variables command.  There are actually six commands with
     the gereral form

                    /sxFileSpecification<<,a>>

     The optional ,a indicates output in the append mode, and x may be
     any of the following: 
     
          V or v   saves all variables to the file, 
          $        saves all data type string variables to the file, 
          .        saves all data type single variables to the file,
          ..       saves all data type double variables to the file, 
          _        saves all data type short variables to the file, or
          __       saves all data type long variables to the file. 



Execution Mode and Monitoring

Mode
 
/b (eX break)
     Toggle's eX's `break' facility on or off.  If it is active,
     typing any key will suspend execution of the currently 
     executing macro and temporarily enter the debug mode.  
     Currently, it only checks for keystrokes at one point in the
     interpreter and cannot be relied on to escape from all `hang
     ups', and the temporary use of debug it provides cannot maintain
     monitor even though so commanded while in the mode.  But warts
     and all, it's better than nothing. 

browse (eX word)
     Causes eX to enter the browse facility, which is an inter-active
     device to view, create, edit and/or delete non-file data
     entities.  It may be invoked anywhere and any time, and does not
     take an argument.  On entering the browse facility, the
     data entity selection menu is presented. 

     Function Key    Legend     Data Entity
               1         @#     Numeric accumulators
               2         @$     String accumulators
               3         :      Macros
               4         _      Short variables
               5         __     Long variables
               6         .      Single variables
               7         ..     Double variables
               8         $      String variables
               9                (currently un-used but spoken for)
              10         Done   Terminate browse


Capture Command
     The capture command is used to initiate or terminate inter-active
     command capture (writing) to a sequential input file.  The
     command

                    /cFileSpecification<<,a>>

     initates capture to FileSpecification.  The optional a may be
     used to append capture to any pre-existing data in the file.  The
     sans-argument command is used to terminate capture and close the 
     file:
                              /c

     Capture may then be re-initiated to another file with the
     argument form of the command, or to the same file in the append
     mode with the command 
                              /c
     The file will automatically be closed when eX is exited, just in
     case you forget. 

Inter-Active Mode
                              /i
     Changes to the inter-active execution mode.  The inter-active
     mode may be terminated via Function Key 10 anytime the inter
     active menu is displayed (which is often).  If this command is
     given in the eX invocation command, execution of any execute
     macro argument is precluded until the IA Mode is terminated. 


 
De-bugging
 
Monitor
                              /m<<p<<#>>>>
     Toggles the program monitoring mode monitor.  The optional p
     sends the monitor output to the system printer rather than the
     video display.  If p is given, the width of the printer in
     columns may be specified.  Note that p may not be given when
     toggling monitor to off.


     Output Info        Video  Printer  Details shown
     -----------------------------------------------------------------

     evaluated values     x       x     value prefaced by eev# or eev$
     assignments          x       x     identifier, assigned value
     current macro        x       x     number and file specification
                          x       x     page, line and column number
                          x       x     next line of the current macro
     bytes remaining      x             in the eX interpreter's stack
                          x             for alphanumeric data
     Accumulators         x       x     current plane, level & values
     assignments          x       x     identifier & assigned value


Debug
                         /d<<p<<#>>>>
     Toggles the single-step macro execution mode debug.  The optional
     p sends the monitor output to the printer (instead of the video
     display).  If p is given, the optional #, which specifies the
     printer width, may be given.  p may not be given when toggling to
     off.

     Toggling debug to active forces monitor to active, but toggling
     debug to in-active does not toggle monitor to in-active.

Hesitate
                              /h#
     This command controls the time that execution is suspended while
     an assignment is displayed by the monitor mode.  # is in seconds
     and may be or have a fractional part. 

Trace
                              /t<<p<<#>>>>
     Toggles the trace mode of execution in which the macro is
     displayed as it is executed.  The optional p sends the trace
     output to the system printer rather than the video display. If p
     is given, the width of the printer in columns may be specified. 
     p may not be given when toggling trace to off. 

