;
                                     ZEX.COM                                  

             Size (recs) CRC   Version    Author/Latest Issue      Disk
               5k (39)   4793  4.04       Joe Wright 11/88         Z3COM13

  1- Syntax  2- Flag Options  3- Control Cmds  4- Notes  5- Examples of Use   


   ZEX is  a  memory-based command file processor.  It behaves somewhat like a
combination of  SUB and XSUB, and because its input source is memory-resident,
the execution speed  of  ZEX is  significantly  greater than that of SUB/XSUB.
Vs 3.1 (3/84) by R. Conn.

   You may  move  into  any directory you desire while a ZEX command stream is 
being executed.  Up to 9  parameters  are  permitted  on the ZEX command line.
ZEX Type 4 now permits operation with programs such as dBase II, WordStar, and
Multiplan which attempt to flush keyboard input from time to time.  Nesting of
ZEX scripts is also supported.
:1

    Syntax:  ZEX                         <-- enter interactive mode

             ZEX [[dir:]subfile[.typ][ parameters][ commands]]

  Without a command tail, ZEX is interactive and allows you to enter commands 
and controls from the keyboard.  User input is terminated with an empty line.  
ZEX  will also take its commands from a batch file (.typ, .ZEX or  .SUB)  and 
pass  up  to nine parameters and any number of ZEX controls  on  the  command 
line.  These controls may be embedded in the text of the command file or user 
input line and will be executed after ZEX processing begins.

 |  Insert <CR>          ^|   Insert <CR>,<LF>         ;;  ZEX comment
^:  Rerun command file   ^.   Toggle print suppress    ^!  Abort if false
^#  Toggle ZEX msgs      ^$   Define default params    ^c  Insert cntrl char
^?  Wait for user <CR>   ^/   Ring and wait for <CR>   $n  1<=n<=9 for param
^*  Ring bell            ^"_  User input /w trigger    $$  =$ Insert literal
^<  Display chars only   ^>   Stop display             ^-  Toggle quiet flag
^(  IF flow true         ^)   ENDIF flow true          ^&  Toggle print IF
^=  Toggle XSUB mode     ^%   Toggle ZEX input
:2


 ZEX Type 4 Flag Options - 1/2 

   ZEX Type 4 defaults  to all flags (except XSUB) OFF and invites the user to
specify his options on the command line or in the batch file.  

   ^=  XSUB     ^= and ^% are used in combination to help control ZEX input to
                the  running program.   XSUB ON will allow ZEX  input  for the 
                remainder  of the file except  for those commands  which begin
                with ^%.   Conversely,  XSUB OFF will turn ZEX input OFF after
                each command except for those preceded by ^%.   

   ^-  QUIET    Setting  the QUIET flag  under ZEX Type 4  suppresses the  Z34 
                command prompt (A0:BASE>) as well as echo of the command line.
                ZEX Type 4  will restore the QUIET flag  to its original value
                when Done.



 ZEX Type 4 Flag Options - 2/2 

   ^#  MSUP     ZEX has  a number of messages of  its  own (ZEX:, Done, etc.). 
                ^# suppresses these messages until the next ^#.   If ^- and ^# 
                are  both toggled,  ZEX and Z34  will be completely silent and 
                batch commands  will execute  as if from  the multiple command 
                line or alias script with no reports to the console.

   ^.  PSUP     All Console Output may be suppressed with the ^. toggle.

   ^&  IPSUP    Any Console Output may be suppressed during a false flow state
                with the ^& toggle.  
:3


 Zex Control Commands - 1/14 

^*   -  causes ZEX  to  ring the bell.   It does  not insert  a BELL character 
        into the command  file like a ^G sequence would.  It simply  rings the 
        bell and continues processing.

;    -  a ZEX comment.  When ; is the first character on a line or is preceded
;;      by a space or tab,  the  ;  and  all characters following it up to and 
        including the  following  <LF>  are  not  included in the  ZEX command 
        stream.  They are simply treated as a comment in the  ZEX Command File
        and ignored.   Unlike  a conventional  ZCPR3 comment,  the ZEX comment 
        does not take up space in the command stream and  does not appear when 
        the command stream is executed.  ';;' will still do the same thing.

{    -  'field' comment.    As the first character of  a particular line,  '{' 
}       will cause  all subsequent  characters  and lines  to  be  treated  as 
        comment and otherwise ignored until  the corresponding closing bracket
        is encountered.



 Zex Control Commands - 2/14 

^<   -  used to  bracket characters which are simply echoed by the ZEX monitor 
^>      and  not  passed  back  to  the  calling  program.   This  causes  the 
        characters between  these commands  to  be  echoed  to the user during
        execution but not processed by any program.  This feature is very good
        for embedding comments to  be  printed  at  execution  time  into  the 
        command stream.   Unlike the  ZCPR3  comment  form,  which  is  a line 
        beginning with a semicolon, comments  enclosed by ^< and ^> may appear 
        anywhere, such as within an editor session.

^#   -  toggles suppression of informative messages generated by ZEX.

^.   -  causes console output  to  cease  until  the  next ^. is  encountered.
        Character input from the ZEX Monitor continues, but the  user does not 
        see what it is.



 Zex Control Commands - 3/14 

^:   -  causes the ZEX  monitor  to  restart  execution  of the loaded command 
        stream.  With ZEX Type 4 default flags are  re-established rather than
        the  entire command  stream,  as  initially processed  by  ZEX,  being
        executed again from the beginning.  

$n   -  where 1<=n<=9, causes the  indicated specified or default parameter to 
        be substituted from the command line.

^$   -  used to  define or redefine the set of input command parameters.   The 
        rest of the  line  following the  ^$ is treated as a set of parameters 
        separated by blanks.



 Zex Control Commands - 4/14 

^?   -  replace  the  /A and /AB  options  of  SUB.   ^?  causes  ZEX  to stop 
^/      processing and wait for the user to strike either the space bar or the
        RETURN key before continuing.   The user can take his time and examine
        the display, and, if he does not wish to continue, a ^C will abort the
        command stream.  The ^/ command  is like ^?, but it periodically rings 
        the bell at the console, summoning the user in an alarm fashion.

^"   -  causes ZEX to  stop  providing input from the command stream and allow 
        the user to input whatever  he  wishes  until  a  special character is 
        output, at which time ZEX will resume providing input.   In this case, 
        ZEX can be intimately linked with ZCPR3, and  it  is intended that the
        special  character  that  ZEX is  waiting  for  is associated with the 
        ZCPR3 prompt.   In  my case, I  made  the  ZCPR3  prompt  to  be a ">" 
        character with the  most  significant  bit  set.   This  is unique and 
        appears only when the prompt comes up on my system.



 Zex Control Commands - 5/14 

   The  following  examples  illustrate  applications  employing  ZEX  control 
commands.  Comments appear out to the side, prefixed by <--.

B1>zex
ZEX, Version 1.3
1: ^$ this is fun                  <-- Define 3 params
2: echo $1 $2 $3
3: ^$ hello from happy acres       <-- Define 4 params
4: echo $1 $2 $3 $4
5: 
(ZEX Active)                       <-- ZEX is running now
B1>echo this is fun

THIS IS FUN



 Zex Control Commands - 6/14 

B1>echo hello from happy acres

HELLO FROM HAPPY ACRES
B1>
(ZEX Completed)
By Your Command >

B1>ed demo.zex                     <-- Demo Command File

NEW FILE
     : *i
    1:  ed demo.txt                <-- Edit DEMO.TXT
    2:  i                          <-- Insert text while in ED
    3:  This is a test
    4:  This is only a test
    5:  This is a demo of ZEX Control



 Zex Control Commands - 7/14 

    6:  ^Z                         <-- ^Z is 2 chars, xlated into
    7:  b0lt                       <-- Ctrl-Z by ZEX
    8:  1l
    9:  0lt
   10:  i                          <-- Input More Text
   11:  ^"                         <-- Allow user to input text
   12:  type demo.txt              <-- When ZEX continues, this
   13:  era demo.txt               <--  is what it does next
   14:  
     : *e

B1>zex demo                        <-- Run the command file
ZEX, Version 1.3
(ZEX Active)
B1>ed demo.txt



 Zex Control Commands - 8/14 

NEW FILE
     : *i                          <-- ZEX is typing this in
    1:  This is a test
    2:  This is only a test
    3:  This is a demo of ZEX Control
    4:  
     : *b0lt
    1:  This is a test
    1: *1l
    2: *0lt
    2:  This is only a test
    2: *i                          <-- Now user input begins
    2:  I am now typing this line of my own volition   <-- User
    3:  ZEX will allow me to continue doing this until
    4:  it sees the ZCPR3 prompt



 Zex Control Commands - 9/14 

    5:                                  <-- User types Ctrl-Z
    5: *e                               <-- User types "e"

(ZEX Active)
B1>type demo.txt                        <-- ZEX resumes
This is a test
I am now typing this line of my own volition
ZEX will allow me to continue doing this until
it sees the ZCPR3 prompt
This is only a test
This is a demo of ZEX Control

B1>era demo.txt
DEMO    .TXT



 Zex Control Commands - 10/14 

B1>
(ZEX Completed)
By Your Command >

B1>ed demo.mac                     <-- Now to use ZEX for
                                   <--  program assembly
NEW FILE
     : *i                          <-- User types program
    1:          ext     print
    2:  
    3:          call    print
    4:          db      'Hello, World ... It''s Another Day',0
    5:          ret
    6:  
    7:          end



 Zex Control Commands - 11/14 

    8:  
     : *e

B1>type a:m80.zex                  <-- M80.ZEX command file
;  M80.SUB -- MACRO-80 Assembler and Linker
M80 =$1
;  Please Type $^C if Error(s) Exist - ^?
ERA $1.BAK
ERA $1.COM
L80 /P:100,$1,A:SYSLIB/S,$1/N,/U,/E
ERA $1.REL
;  Assembly Complete



 Zex Control Commands - 12/14 

B1>zex m80 demo                    <-- Run command file on pgm
ZEX, Version 1.3
(ZEX Active)
B1>;  M80.SUB -- MACRO-80 Assembler and Linker
B1>M80 =DEMO

No Fatal errr(s)

(ZEX Active)

B1>;  Please Type ^C if Error(s) Exist -     <-- User can abort now
                                             <--  if he wishes



 Zex Control Commands - 13/14 

B1>ERA DEMO.BAK
DEMO    .BAK
B1>ERA DEMO.COM
No File
B1>L80 /P:100,DEMO,A:SYSLIB/S,DEMO/N,/U,/E

Link-80  3.44  09-Dec-81  Copyright (c) 1981 Microsoft
Data    0100    01C5    <  197>

35936 Bytes Free

Data    0100    01C5    <  197>

35936 Bytes Free
[0000   01C5        1]



 Zex Control Commands - 14/14 

(ZEX Active)

B1>ERA DEMO.REL
DEMO    .REL
B1>;  Assembly Complete
B1>
(ZEX Completed)
By Your Command>demo                    <-- Run pgm now
Hello, World ... It's Another Day
B1>
:4

 ZEX Notes - 1/4 

   a. The Interactive Mode of ZEX executes  like the Interactive Mode  of SUB.
      The user enters command  lines until he is satisfied and then terminates 
      the process by  entering  an  empty  line (simply hitting RETURN).   ZEX 
      then  executes  the commands  in  the  sequence  entered.  No  parameter 
      passing is permitted in this mode of operation.

   b. The "ZEX filename params" form is like the corresponding SUB form.   ZEX
      will search along the ZCPR3 External Path for a command file of the form
      filename.ZEX or  filename.SUB.  If a directory is entered which contains 
      both such files, the file of type ZEX will be executed.

   c. Once ZEX  has begun execution, it  places a ZEX Monitor just under ZCPR3 
      and builds  the command  stream  under the  monitor.  Once complete, the 
      address of the BDOS is adjusted so  that the ZEX monitor and its command 
      stream will not be  overwritten  by transient  programs,  and  execution 
      begins.  Each  time  the  BIOS  Console  Input  routine  is  called, ZEX 
      supplies the input character.


 ZEX Notes - 2/4 

   d. As with SUB, a ^C from the console will abort execution of a ZEX command
      stream.  Also, as with SUB,  if  a  command  follows  ZEX  in a Multiple 
      Command Line, ZEX appends this command to the command stream.

   e. Unlike SUB, ZEX  does  not  permit nesting  of command files.   ZEX will 
      simply abort if a ZEX command is encountered in the command stream it is
      processing.

   f. Unlike SUB, ZEX supports  many  more  embedded  commands.  Combining the 
      facilities  of  SUB and  XSUB in this case, the embedded commands of ZEX 
      reflect the XSUB-like capabilities of ZEX as well as some new ideas.
 
   g. ZEX Type 4 ignores  tabs and spaces  at the beginning of a command line.
      Subsequent tabs are converted to spaces and subsequent spaces prior to a
      ZEX comment  or CR that  ends the  line are removed.   This allows  more 
      freedom to format the input file for readability.   The ZEX literal '$ '
      should be used for commands preceded by a space.  


 Zex Notes - 3/4 

   h. ZEX Type 4 has a patch area right after the Z3ENV header at 0200h.  Each
      patchable byte is preceded  by its name and '>' for easy identification:

      KDEL>  05         number of false responses between normal chars
      CDEL>  0F         number of lies after <cr>
        
      XSUB>  00 or FF   ZEX Input Mode (FF)
      MSUP>  00 or FF   Suppress ZEX messages
      PSUP>  00 or FF   Suppress Console Output
      IPSUP> 00 or FF   Suppress Conout IF false
      QUEIT> 00 or FF   Initial Z3 quiet flag

      ZEXDU> 00 00      No ZEX directory declared or..
      ZEXDU> 03 01      Search directory A3: only
      ROOT>  00 or FF   Search Root directory only
      CURDU> 00 or FF   Search Current directory only  


 Zex Notes - 4/4 

   i. Version 4.04 updates:
      - Line  formatting  has  been  further  relaxed  by  allowing  a  single 
      semicolon ';' to denote  a comment if  it is the  first character on the
      line or if it is  preceded by  a space or tab.   Multiple Command system
      syntax ERA *.BAK;ERA *.PRN;DIR *.Z80 still  works because  the character
      prior to ; is not a space.  The ';;' ZEX comment form still works but is
      unnecessary.   If ; is  required  at the beginning of  a line or after a 
      space, use the $; literal form.
      - Also added is the 'field' comment.   A left curly bracket  '{'  as the
      first  character of  a  particular line  will cause all subsequent char-
      acters and lines  to be treated  as comment  otherwise ignored until the
      corresponding closing bracket is encountered. 
:5


 Examples of Use 

   a. ZEX         

      - the user now enters a group of commands

   b. ZEX mycmds p1 p2
                  
      - processing of  the file mycmds.ZEX, or, if  not  found,  mycmds.SUB is 
        performed; p1 is substituted for $1 and p2 for $2 
