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


Inter-active Mode and Debugging
  

Inter-active Mode

The inter-active mode provides a means of directly entering eX
commands, statements and eXpressions for immediate execution as
(un-named) macro 0.  Through a capture facility, these macros may
additionally be written to a disk file when and as entered.  The idea
behind capture is to try things---if you wish, commands may be limited
to any single component of the language---until you achieve the
desired result and then edit the capture file to produce the final
program. 

The maximum command length is 255 characters, and the input editing
features available are identical to those available with `?'.  The mode
is entered when eX is invoked without an execute macro argument, 
through an inter-active mode command `/i' given on the invocation line
or within an executing macro, or through the debug or monitor menus. 

The command prompt and the function key driven inter-active mode menu
are simultaneously displayed upon entry to the mode and whenever both
are simultaneously available to the user.  The function keys are
simply short-cuts to capabilities that might be frequently used---the
capture command, macro and variable load and save commands, operating
system command, and browse.  Selecting one facility for use by either
typing a function key or beginning to enter a command causes the
other's prompt or menu to be cleared from the display. 

The mode may be exited by typing function key 10 when the menu is 
displayed.  If the mode was entered from an executing macro, excution
of that macro resumes.  Otherwise, if entered from the eX invocation
command and no execute macro argument was given in the invocation
command, eX is also exited.  However, if the mode was entered from the
eX invocation command and an execute macro argument was given,
execution of that macro commences. 

With the exception of the mode command `/i' itself, the full eX language
is available in the inter-active mode.  For example, an existing macro
may be executed by any of the directives

               goto MacroReference
               gosub MacroReference
               LongJump MacroReference LabelReference
               LongCall MacroReference LabelReference

When execution of the macro ceases---whether normally or
abnormally---eX will return to the inter-active mode.  

The browse facility will often play an important part in inter-active
sessions.  It may be used to create, edit, and/or delete any data
entity---including macros.  The first menu displayed in browse
provides for selecting the data entity type to be browsed---numeric
accumulators, string accumulators, macros, short, long, single,
double, and string variables.  The second menu, shown once the data
entity type has been selected, provides the commands to edit, delete
and create within the selected data entity type.  (Accumulators cannot
be created or deleted, of course.)  Selection of the individual data
entity as well as control of the data entities that are displayed
within the type is provided by the cursor up and down keys, and the
page up and down keys.   The cursor left and right keys may be used to
scroll the displayed portion of string data so that the entire string
may be viewed.   

The numeric data editing facility includes a ten function calculator. 
As I have so far been un-able to include a full text editor in eX, the
macro creation/editing facilities currently use MS-DOS's EDIT.COM,
and may in turn uses QBASIC.EXE (and probably QBASIC.INI).  Both are
provided with MS-DOS 4.0 and subsequent, and both must either be in
the current directory or a directory given in the PATH.  Regrettably,
the string creation/editing facility provided for all other string
data entities is a quite poor field editor (I'm guilty) that employs
the first 24 video lines (eX's edit).  


Program Monitoring and De-bugging

One of the nicer things about eX's de-bugging facilities is that their
commands can be imbedded in a macro.  Finding bUGH!s and killing
them is usually a quick and easy process.  I've even used them to find
and squash bUGH!s in the eX interpreter that I couldn't isolate
otherwise.  (I don't lay down perfect code because it's too boring...)



Trace

As it is executed, a macro may be output to either the video display
or the printer (DOS device LPT1).   With the exception that structure
delimiters, else tokens, comments and delimited string literals are
always output verbatim, the characters in portions of tests and loops
that are not executed (because of a false condtion) are output as
ASCII periods (code 46). 

                [{1 > 2}..........~]


The tracing process is controlled by the eX trace command 

               /t<<p<<#>> >>

The command's optional `p' sends the trace to the printer (DOS device 
LPT1).   If p is given, the printer width # may be given.  /t is a
toggle: if trace is inactive, /t will activate trace; if active, /t
will de-activate trace.   The optional portions of the command may not
be given when toggling trace to off.  Note that the form "/tp #" is not
legal because the width argument is optional. 

  
Monitor
  
Monitor, among other things, allows monitoring the values returned by 
macro components and the values assigned to data entities.  The
process is controlled by the eX monitor command 

          /m<<p<<#>> >>

The output is sent to video lines 20--24 unless the command's optional
`p' is used to send the output to the printer (DOS device LPT1).  If
p is given, the printer width # may be given.  (The form "/mp #" is not
legal.)  If the output is to the display, macro execution is suspended
for about 1.5 seconds to allow viewing the situation.  (The interval
may be changed by the eX `/h' hesitate command.)  The debug mode may be
temporarily entered by pressing any key on the keyboard.  Most of the
output of monitor should be self-explanatory.  For assignment
operations, the data entity identifier and the assigned value are
output near the lower left-hand corner.  Values produced during
execution are prefaced by eev# or eev$ as appropriate, also appear
near the lower left-hand corner.


`/m' is a toggle: if monitor is inactive, `/m' will activate monitor; if
active, it will de-activate monitor.  (The optional p is not legal
when toggling monitor to off.)  Although forced on when debug is
activated, monitor may be turned off while debug is active, in effect
suspending debug.  Monitor is not forced off when debug is
de-activated.   


               Potential Screen Conflict:

Activating monitor to video with the video cursor on video lines
20--25 will cause the cursor to be moved to line 19.  Attempting to
move the video cursor to lines 20--25 while monitor is active to video
will case and illegal function and eX will crash.


Hesitate

The eX hesitate command controls the interval that macro execution is 
suspended by monitor to allow viewing the display's monitor area.   

                    /h#

where `#' is the number of seconds that execution is suspended, and may 
either be or contain a fractional part.  


  
Debug
  
Debug is a `single-step' mode of operation.  It is controlled by the
eX command 

                  /d<<p<<#>> >>

The optional `p' sends the monitor output to the printer (DOS device
LPT1) instead of the video display.  If p is given, the printer width
# may be given.  (The form "/dp #" is not legal and the optional p is
not legal when toggling debug to off.) The following actions are
available through the debug key menu after execution of a `step':

Go
     Continue execution. 
     Function Key 1 or any other key (except those listed for the
     subsequent function keys) resumes execution of the macro
     interrupted by debug at the point of interruption. 

Cmd,Go
     Command & continue. 
     Function Key 2 accepts keyboard input of any component(s) of 
     the eX language as an un-named macro numbered 0, executes it, and
     resumes execution of the macro interrupted by debug.  This
     function is precluded during execution of the command, and more
     specifically, whenever the current macro number is zero. 

Cmd
     Command & return for further command.
     Function Key 3 accepts keyboard input of any component(s) of the
     eX language as an un-named macro numbered 0 (zero), executes it,
     and returns for further command.  This function is precluded
     during execution of the command, and more specifically, whenever
     the current macro number is zero.  

I Mode
     Inter-active mode.   
     Function Key 5 transfers to the I-A mode of operation.  Debug is
     forced to off (but may be turned back on inter-actively).

Os Cmd
     Operating system command. 
     Function Key 6 accepts and executes any operating system command
     and returns to the debug menu when the command terminates.

Browse
     Browse mode.
     Function Key 7 enters the `browse' mode of operation, which
     enables the viewing, creation and editing of data entities.  eX  
     returns to the debug menu when the browse mode is terminated. 

Quit
     Aborts to the operating system.   
     Function Key 10, ESC or ctrl C causes an immediate exit to the
     operating system.   

The command entry features are identical to those of the inter-active
mode and the language's keyboard input facility `?'.  The maximum 
inter-active command length is 255 characters.  

  
