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



Invocation and eX Commands


eX Commands

Various eX commands exist for data entity allocation, macro and
variable input and output, and execution mode and debugging facility
control.  Additionally, macro invocation arguments are implemented as
eX commands.  With the exception that the inter-active mode command
may not be given in the inter-active mode (there's an alternative),
all commands may be given in the eX invocation command, the
inter-active mode, or within macros.  

eX takes any slash /, ASCII code 47, that is not immediately followed 
by an operator suffix or whitespace to be an eX command.  (I.e., if it
isn't a division operator, it's an eX command.)  The command specifier
must immediately follow the slash, and then the argument, if any, may
be given.  Alphabetic case is insignificant when specifying commands. 
There are three general forms: 

                   /Cmd
                   /CmdArgument
                   /Cmd Argument

The first form is an eX command that takes no argument.  'Nuff said? 

In the second form, the lack of whitespace after the command
identifier indicates that the argument is a literal delimited by the
command identifier and the whitespace subsequent to the argument. 
This implies that such a literal argument may contain no whitespace.  
Numeric arguments in this form may not include formatting. 

In the third form, the whitespace after the command identifier
indicates that the argument is not a literal delimited by the command 
identifier and whitespace subsequent to the argument.  Up until this
point, an eX command interpreter has been employed to interpret the
command.  But in this command form, the full eX interpreter is now 
employed to evaluate the argument.  This implies that eX can do
absolutely anything it is capable of within the argument of this form
of an eX command!  (But I guarantee an inter-macro program branch
ain't a smart thing to do in an eX invocation command, i.e., at the
DOS prompt... but a `gosub' would be just fine.)  The only thing you
must do is ultimately provide an argument for the command, and the
word ultimately is appropriate since once the command recieves its
argument, the opportunity for extraneous processing is lost. 

The simple way to do this is via an aggregation:  

                /Cmd (Argument ExtraneousProcessing)

The implied addition of the left parens is used to load the argument
into the accumulator for return upon exit from the aggregation.  Then
the extraneous processing is performed.  The only thing you need to be
careful about is not contaminating the argument's accumulator.  How's
this (allocate variables command)? 

                    /av (32 gosub "macro.x")


You might like to note that this last form will accept literal
arguments.  Strings must be delimited and numerics may include
formatting.  So, you can provide a string argument that includes
whitespace! 

                 /Cmd $1,234.56
                 /Cmd "String Literal"




Invocation

eX is invoked from the operating system prompt with the general
command 

     ex <<MacroFile1 <<... MacroFileN>> >> <<commands>>

Whitespace must exist between each element on the command line,
including between individual eX commands.   

If given, MacroFile1 is the file specification for a macro to be 
run in the program execution mode unless the eX inter-active mode
command `/i' is also given in the invocation command.  Any MacroFile2
... MacroFileN are macros that are to loaded into memory as macro #2
... macro #N.  If MacroFile1 is not given, eX will enter the
inter-active execution mode.  Note that on the eX invocation command
line, macro file specifications are un-delimted literal references and
should not begin with a colon :. 

Commands is one or more eX commands to be performed prior to 
commencing execution of any macro or entering the inter-active mode. 
Any eX command may be given, and note that not only may commands
preceed any macro file specification, macro specifications and
commands may be inter-mixed.  To illustrate, both of the following
invocations run the macro test (located in the exprogs directory of
disk drive c in the debug mode (/d).   

                   ex c:\exprogs\test /d
                   ex /d c:\exprogs\test

The only difference between the two is that the second activates debug
before evaluating the macro specification.  Placing the debug command
after ex is a nice trick to remember if you think you're having
trouble with something on the invocation command line---you might be
able to debug it! 
  
Macro invocation arguments are written as eX commands and either of
the first two general forms stated in the preceding section may be
used.  The command identifier that specifies an invocation argument is
a slash /. 

                         //Argument
                         // Argument

All invocation arguments are stored as strings with a maximum length
of 64 characters.  Therefore, a numeric macro invocation argument must
be converted from the string to a numeric with the eX function `val' and
the argument may include formatting.  The default macro invocation
argument allocation is 10. 

The eX function `iArgs' returns the number of macro invocation arguments
given in the eX invocation command and takes no argument.  The eX
function `iArg' returns the value of macro invocation argument number# 
given as the function's argument.  (Macro invocation arguments are
numbered in the relative order of their appearance in the eX
invocation command.)  In order to facilitate macro useability, both
`iArgs' and `iArg' number# are assignable: an executing macro can reset
the macro invocation arguments for a macro it is to call as a
sub-program or branch to. 

                    iArgs <<:= Number#>>
                    iArg number# <<:= Value$>>


Perhaps a small example of invocation arguments is in order.  Let's
create the macro ShowVal: 

                        show val iArg 1

Invoke it with 

                   ex ShowVal //**$2,345.67

and you'll see the output 

                          2,345.67

If val had been omitted, the output would have been the string "**$2,345.67". 

In summary: 

1. Elements in the eX invocation command may be given in any order.
   (Remember that an allocation command will destroy any data in the
   data entity and give it before you put any data in it.)
2. Any element that does not begin with a slash / is assumed to be a 
   macro file and is loaded into memory.  The first will be loaded as
   macro number 1, the second as macro number 2... .  The first macro 
   specified will be executed immediately unless the eX interactive 
   mode command /i is given.  
3. Macros loaded with the load macro eX command `/lm' are loaded as 
   macro number 2 or subsequent, but are not executed--- `/lm' commands 
   will not prevent eX from entering the inter-active mode.

