Command File Processing
Disk-Based Command Files -- SUB2
SUB2 Error Messages
SUB2 Command Summary
Memory-Based Command Files -- ZEX
ZEX Control Commands
Restrictions on Command Files
SUB2 and ZEX as Extended Command Processors Under ZCPR2
:Command File Processing

    � Comman� Fil� i� � fil� containin� commands�� wit� optiona� �
paramete� substitution�� whic� ca� b� execute� b� ZCPR2��  Thes� �
command� ar� exactl� th� sam� kind� o� command� a� yo�� woul� �
issu� a� th� console�� an� an� comman� yo� ca� issu� fro� th� �
consol� ca� b� issue� fro� withi� � Comman� Fil� (wit� jus� � �
couple of restrictions).

    Th� Comman� Fil� Facilitie� o� SUB� an� ZEؠ ar� availabl� �
unde� ZCPR2��  Simila� i� concep� t� th� SUBMI� facilit� o� CP/M� �
bot� SUB� an� ZE� ar� upward-compatabl� t� SUBMI� (an� SU  fil� �
ca� ru� unde� the� wit� fe� restrictions).

    Bot� SUB�� an� ZEؠ begi� processin� b�� translatin� th� �
comman� file� the� ar� give� int� slightl� differen� forms�  Bot� �
d� paramete� substitution� extractin� parameter� fro� th� comman� �
line� an� placin� the� int� th� tex� o� th� comman� strea� the� �
ar� building��  SUB� build� th� comman� strea� t� b� execute� o� �
dis� driv� � unde� th� curren� use� number�� an� ZE� build� th� �
comman� strea� i� memory.
    A� th� use� ca� guess�� ZE� i� generall� preferre� t� SUB2�  �
Unde� ZEX�� th� comman� strea� i� execute� muc� mor� quickl� tha� �
unde� SUB� sinc� ZE� jus� goe� int� memor� fo� th� nex� characte� �
whil� ZCPR� ha� t� g� t� disk�  ZEX� however� doe� tak� u� memor� �
space� an� tha� i� it� mai� drawback�  Th� TP� (Transien� Progra� �
Area�� unde� ZE� i� smalle� tha� wha� i� availabl� t� comman� �
file� runnin� unde� SUB2��  Thi� i� you� basi� trade-of� betwee� �
th� tw� Comman� Fil� Processors.

    Anothe� differenc� betwee� SUB� an� ZE� i� tha� SUB� comman� �
stream� ar� line-oriente� an� extracte� onl� b� ZCPR2��  Tha� is� �
SUB�� build� � comman� fil� name� $$$.SU� lik� SUBMIԠ does�� an� �
ZCPR�� extract� � lin� fro� th� $$$.SU� fil� eac� tim� i� i� �
entered�  Whe� ZCPR� i� entere� b� eithe� � Col� Boot� War� Boot� �
o� simpl� RETur� fro� � loade� program�� i� check� th� Multipl� �
Comman� Lin� Buffe� fo� � pendin� command��  I� i� find� it�� i� �
execute� it�  I� not� i� check� th� A� driv� (curren� user� fo� � �
$$$.SU  file��  I� i� find� one�� i� extract� th� nex� lin� fro� �
th� $$$.SU� file�� processe� it�� an� begin� executio� o� i� fro� �
th� Multipl� Comman� Lin� Buffer��  Finally�� i� th� $$$.SU� fil� �
is not found, ZCPR2 prompts the user for input.

    Tha� i� ho�� comman� strea� processin� unde� SUB��� i� �
performed�  ZEX� however� act� a� � combinatio� o� SUB� an� XSUB�  �
Onc� comman� strea� processin� begin� unde� ZEX� th� ZE� monitor� �
locate� unde� ZCPR� wit� th� associate� comman� stream�� supplie� �
� characte� eac� tim� th� BIO� Consol� Inpu� Routin� i� called�  �
ZE� extract� th� nex� characte� fro� th� comman� stream� examine� �
i� t� se� i� i� i� � ZE� comman� an� execute� i� i� so�� an� �
returns it to the calling program if it is not a ZEX command.

    Hence�� ZCPR�� itsel� doe� no� realiz� tha� ZE� i� running�  �
Neithe� d� th� transien� program� i� general��  ZEؠ simpl� �
intercept� al� call� t� th� BIO� Consol� Inpu� (an� Inpu� Status� �
routin� an� provide� a� inpu� characte� i� it� place��  Ther� ar� �
exceptions to this case, but they will be discussed later.

    Bot� SUB� an� ZE� fi� int� th� ZCPR� Syste� nicely� an� the� �
ca� b� use� t� ac� a� Extende� Comman� Processor� i� desired�  �
This is discussed later.

:Disk-Based Command Files -- SUB2

    SUB2�� commonl�� calle� SUB�� i� invoke� b�� on� o� th� �
following command lines:

         SUB or SUB //            <-- Print Help Message
         SUB /A Text              <-- Abort $$$.SUB File
                                       Processing at User's
                                       Discretion
         SUB /AB Text             <-- Same as /A but Ring Bell
                                       to Alert User
         SUB /D commands          <-- Perform Commands following
                                       the /D
         SUB /I                   <-- Enter Interactive Input
                                       Mode
         SUB filename params      <-- As in Standard SUBMIT

    Th� "SU  /A�� an� "SU  /AB�� form� allo�� th� use� t� �
gracefull�� abor� � $$$.SU� file��  ^� a� th� consol� ca� b� use� �
t� abor� suc� processin� a� unde� CP/M�� bu� th� /� for� allow� �
th� luxur�� o� startin� � comman� strea� an� stoppin� a� � �
critica� poin� t� allo� th� use� t� tak� hi� time�� inspec� wha� �
ha� happened� an� the� decid� whethe� t� procee� o� not.

    Th� "SU  /D�� for� ha� littl� utilit�� unde� � fully-�
implemente� ZCPR�� System��  Yo� ca� obtai� � bette� effec� b� �
simpl�� issuin� � conventiona� ZCPR� comman� stream��  Th� /� �
optio� i� goo� onl� i� environ� whic� d� no� suppor� multipl� �
commands.

    Th� "SU� /I� for� eliminate� th� nee� fo� th� use� t� us� a� �
edito� t� creat� � .SU� file��  I� th� use� ha� � comman� strea� �
h� want� t� execut� immediatel� an� doesn'� car� t� d� i� again� �
h� ca� us� thi� option��  I� response�� SUB� allow� hi� t� ente� �
hi� comman� strea� (sorry�� n� paramete� passing� � lin� a� � �
time��  Whe� i� i� al� entere� (use� enter� a� empt� line)�� th� �
$$$.SU� fil� i� buil� an� executed.
    Th� fina� form�� "SU� filenam� params"� i� identica� i� for� �
t� th� SUBMIԠ comman� supplie� wit� CP/M��  Th� "filename� �
specifie� th� nam� o� th� .SU� fil� t� b� executed�� an� th� �
parameter� ar� associate� wit� th� substitutio� variable� o� $1� �
$2�� etc��  U� t� 2� parameter� ma� b� specified��  Th� sequenc� �
"$$�� place� � "$� int� th� comman� line�� an� th� characte� �
sequenc� "^c�� place� th� indicate� contro� characte� int� th� �
comman� lin� (uparro� � place� Control-C).

    Th� SUB� comman� ma� b� neste� int� � $$$.SU� file��  I� � �
"SU  filenam� params� comman� i� encountere� i� � $$$.SU  file� �
SUB�� runs�� realize� tha� thi� ha� happened�� an� insert� th� �
indicate� comman� file�� wit� paramete� substitution�� int� th� �
runnin� comman� strea� a� th� appropriat� place��  Thi� ma�� b� �
neste� a� man� level� dee� a� desired.

    Unde� ZCPR2�� i� SUB� i� execute� wit� th� Multipl� Comman� �
Lin� Facilit� invoke� an� mor� command� follo� th� SUB� command� �
the� th� res� o� th� Multipl� Comman� Lin� i� inserte� a� th� en� �
of the generated $$$.SUB file.

    Finally�� SUB� follow� th� ZCPR� pat� whe� searchin� fo� th� �
indicate� comman� file��  I� i� full� integrate� int� th� ZCPR� �
Syste� an� i� abl� t� emplo� th� Externa� Pat� an� Multipl� �
Command Line Buffer features of ZCPR2.

:SUB2 Error Messages

    SUB�� provide� � numbe� o� informativ� diagnostic� t� th� �
user��  I� particular�� whe� processin� � Comman� File�� whe� a� �
erro� i� encountered� th� use� i� informe� o� th� lin� numbe� th� �
error occurs at.

    Th� followin� summarize� th� erro� message� presente� b� �
SUB2:

         Disk Full
              There is no room to write the $$$.SUB file

         Directory Full
              There is no directory space for the $$$.SUB file

         Memory Full
              There is not enough memory in which to build the
              command stream to be placed into the $$$.SUB file

SUB2 Error Messages, Con't

         SUBMIT File Not Found
              The .SUB file specified in the command line could
              not be found along the ZCPR2 path

         Parameter
              Invalid Parameter Specified

         Too Many Parameters
              More than 20 parameters were on the command line

         Line too Long
              The current line in the command stream exceeds
              128 bytes

         SUBMIT File Empty
              The .SUB file specified in the command line was
              found to be empty

SUB2 Error Messages, Con't

         Control Character
              The ^c form was not followed by a letter A-Z

:SUB2 Command Summary

    The following are valid SUB2 command line forms:

         SUB or SUB //            <-- Print Help Message

         SUB /A Text              <-- Abort $$$.SUB File
                                       Processing at User's
                                       Discretion

         SUB /AB Text             <-- Same as /A but Ring Bell
                                       to Alert User

         SUB /D commands          <-- Perform Commands following
                                       the /D

         SUB /I                   <-- Enter Interactive Input
                                       Mode

         SUB filename params      <-- As in Standard SUBMIT

:Memory-Based Command Files -- ZEX

    Th� Memory-Base� Comman� Fil� Processo� o� ZCPR2�� ZEX�� i� �
invoked by the following forms:

         ZEX //                   <-- Print Help

         ZEX                      <-- Enter Interactive Mode

         ZEX filename params      <-- Process .ZEX or .SUB
                                       file as with SUBMIT

    Th� Interactiv� Mod� o� ZE� execute� lik� th� Interactiv� �
Mod� o� SUB2��  Th� use� enter� comman� line� unti� h� i� �
satisfie� an� the� terminate� th� proces� b� enterin� a� empt� �
lin� (simpl� hittin� RETURN)��  ZE� the� execute� th� command� i� �
th� sequenc� entered��  N� paramete� passin� i� permitte� i� thi� �
mode of operation.


    Th� "ZEؠ filenam� params� for� i� lik� th� correspondin� �
SUB� form��  ZE� wil� searc� alon� th� ZCPR� Externa� Pat� fo� � �
comman� fil� o� th� for� filename.ZE� o� filename.SUB��  I� � �
director� i� entere� whic� contain� bot� suc� files�� th� fil� o� �
type ZEX will be executed.

    Onc� ZE� ha� begu� execution�� i� place� � ZE� Monito� jus� �
unde� ZCPR�� an� build� th� comman� strea� unde� th� monitor�  �
Onc� complete�� th� addres� o� th� BDO� i� adjuste� s� tha� th� �
ZEؠ monito� an� it� comman� strea� wil� no� b� overwritte� b� �
transien� programs�� an� executio� begins��  Eac� tim� th� BIO� �
Consol堠 Inpu� routin� i� called��� ZEؠ supplie� th� inpu� �
character.

    A� wit� SUB2�� � ^� fro� th� consol� wil� abor� executio� o� �
� ZE� comman� stream��  Also�� a� wit� SUB2� i� � comman� follow� �
ZEؠ i� � Multipl� Comman� Line�� ZE� append� thi� comman� t� th� �
command stream.


    Unlik� SUB2�� ZE� doe� no� permi� nestin� o� comman� files�  �
ZEؠ wil� simpl�� abor� i� � ZE� comman� i� encountere� i� th� �
comman� strea� i� i� processing.

    Unlik� SUB2�� ZEؠ support� man�� mor� embedde� commands�  �
Combinin� th� facilitie� o� SUB� an� XSU� i� thi� case�� th� �
embedde� command� o� ZE� reflec� th� XSUB-lik� capabilitie� o� �
ZE� a� wel� a� som� ne� ideas.

    Thes� extende� contro� command� ar� discusse� i� th� nex� �
information section.

:ZEX Control Commands

    The following summarizes the ZEX Control Commands:

         Cmd  Meaning                Cmd  Meaning
          |   insert <CR>            ^|   insert <CRLF>
         ^�   reru� comman� strea�   ^�   toggl� prin� suppress
         ^#   toggle ZEX messages    ^$   define default params
         ^?   wait for user input    ^/   ring bell and ^?
         ^*   ring bell              ^"   accept user input
         ^<   display chars only     ^>   stop display
         ;;   ZEX comment            $n   1<=n<=9 for param
         $$   $                      $^   ^
         $|   |                      ^c   control char


    This summary is also displayed via the built-in ZEX help.


    Th� followin� command� simpl� inser� character� int� th� ZE� �
command stream and will not be discussed in any greater detail.

         | inserts a <CR>         ^| inserts a <CR> <LF> pair
         $$ inserts a single $    $^ inserts a single ^
         $| inserts a single |    ^c inserts a control character

    Th� ^� comman� simpl� cause� ZE� t� rin� th� bell��  I� doe� �
no� inser� � BEL� characte� int� th� comman� fil� lik� � ^� �
sequenc堠 would���  I� simpl�� ring� th� bel� an� continue� �
processing.

    Th� ;�� comman� i� � ZE� comment��  I� an� al� character� �
followin� i� u� t� an� includin� th� followin� <LF�� ar� no� �
include� i� th� ZE� comman� stream�  The� ar� simpl� treate� a� � �
commen� i� th� ZEؠ Comman� Fil� an� ignored���  Unlik堠 � �
conventiona� ZCPR�� comment�� th� ZE� commen� doe� no� tak� u� �
spac� i� th� comman� strea� an� doe� no� appea� whe� th� comman� �
stream is executed.
    Th� ^� an� ^� command� ar� use� t� bracke� character� whic� �
ar� simpl� echoe� b� th� ZE� monito� an� no� passe� bac� t� th� �
callin� program��  Thi� cause� th� character� betwee� thes� �
command� t� b� echoe� t� th� use� durin� executio� bu� no� �
processe� b�� an�� program��  Thi� featur� i� ver�� goo� fo� �
embeddin� comment� t� b� printe� a� executio� tim� int� th� �
comman� stream��  Unlik� th� ZCPR� commen� form�� whic� i� � lin� �
beginnin� wit� � semicolon�� comment� enclose� b� ^� an� ^�� ma� �
appea� anywhere� suc� a� withi� a� edito� session.

    Th� ^� comman� toggle� suppressio� o� informativ� message� �
generated by ZEX.

    Th� ^� comman� cause� consol� outpu� t� ceas� unti� th� nex� �
^��� i� encountered��  Characte� inpu� fro� th� ZEؠ Monito� �
continues� bu� th� use� doe� no� se� wha� i� is.

    Th� ^�� comman� cause� th� ZE� monito� t� restar� executio� �
o� th� loade� comman� stream��  Th� entir� comman� stream�� a� �
initiall� processe� b� ZEX� i� execute� agai� fro� th� beginning.

    $n�� wher� 1<=n<=9�� wil� caus� th� indicate� specifie� o� �
default parameter to be substituted from the command line.

    Th� ^�� comman� i� use� t� defin� o� redefin� th� se� o� �
inpu� comman� parameters��  Th� res� o� th� lin� followin� th� ^� �
i� treate� a� � se� o� parameter� separate� b� blanks.

    Th� ^�� an� ^� command� replac� th� /� an� /A  option� o� �
SUB2��  ^� cause� ZE� t� sto� processin� an� wai� fo� th� use� t� �
strik� eithe� th� spac� ba� o� th� RETUR� ke� befor� continuing�  �
Th� use� ca� tak� hi� tim� an� examin� th� display�� and�� i� h� �
doe� no� wis� t� continue�� � ^� wil� abor� th� comman� stream�  �
Th� ^� comman� i� lik� ^?�� bu� i� periodicall� ring� th� bel� a� �
the console, summoning the user in an alarm fashion.


    Finally�� th� ^� comman� cause� ZE� t� sto� providin� inpu� �
fro� th� comman� strea� an� allo� th� use� t� inpu� whateve� h� �
wishe� unti� � specia� characte� i� output�� a� whic� tim� ZE� �
wil� resum� providin� input�  I� thi� case� ZE� ca� b� intimatel� �
linke� wit� ZCPR2�� an� i� i� intende� tha� th� specia� characte� �
tha� ZE� i� waitin� fo� i� associate� wit� th� ZCPR� prompt��  I� �
m�� case�� � mad� th� ZCPR� promp� t� b� � ">� characte� wit� th� �
mos� significan� bi� set��  Thi� i� uniqu� an� appear� onl�� whe� �
the prompt comes up on my system.

    No�� tha� ɠ hav� beate� th� subjec� o� th� ZEؠ Contro� �
Command� t� death� th� followin� example� illustrat� application� �
employin� them��  M� comment� appea� ou� t� th� side� prefixe� b� �
<--.


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

THIS IS FUN
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
   6:  ^Z
 <-- ^Z is 2 chars, xlated into
   7:  b0lt                       <-- Ctrl-Z by ZEX
   8:  1l
   9:  0lt
  10:  i                          <-- Input More Text
  11:  ^"                         <-- I now input text myself
  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

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 my input begins
   2:  I am now typing this line of my own volition   <-- I type
   3:  ZEX will allow me to continue doing this until
   4:  it sees the ZCPR2 prompt
   5:                                  <-- I type Ctrl-Z
   5: *e                               <-- I type "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 ZCPR2 prompt
This is only a test
This is a demo of ZEX Control

B1>era demo.txt
DEMO    .TXT
B1>
(ZEX Completed)
By Your Command >

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


B1>type a:m80.zex                  <-- My 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

B1>zex m80 demo                    <-- Run command file on my 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 -     <-- I can abort now
                                            <--  if I wish
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 Active)

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

:Restrictions on Command Files

    Th� followin� restriction� ar� applie� t� comman� file� �
processed by SUB2 and ZEX.

                       SUB2 Restrictions

    1��  Yo� ma� no� lo� int� use� area� othe� tha� th� on� yo� �
bega� processin� th� comman� fil� in��  I� yo� do�� ZCPR� loose� �
trac� o� th� $$$.SU� fil� an� executio� i� aborte� unti� yo� �
reenter the original user area, at which time execution resumes.

    2��  U� t� 2� parameter� ar� permitte� o� th� SUB�� comman� �
line.

    3.  You may nest SUB2 command files to any depth.



                       ZEX Restrictions

    1��  Yo�� ma� mov� int� an� director� yo� desir� whil� � ZE� �
command stream is being executed.

    2��  U� t� � parameter� ar� permitte� o� th� ZEؠ comman� �
line.

    3.  You may NOT nest ZEX command files.


:SUB2 and ZEX as Extended Command Processors Under ZCPR2

    Bot� SUB�� an� ZE� mak� nic� Extende� Comman� Processor� �
unde� ZCPR2��  W� hav� alread�� see� ho�� SUB�� an� ZEؠ ar� �
intimatel�� linke� wit� ZCPR2��  Bot� us� th� Externa� Pat� an� �
Multipl� Comman� Lin� Buffe� Facilitie� o� ZCPR2�� an� ZEؠ i� �
further prompted for input by the ZCPR2 prompt if desired.

    T� refres� th� reader�� an� Extende� Comman� Processo� i� � �
progra� invoke� b� ZCPR� whe� i� fail� t� fin� th� comman� alon� �
it� path��  ZCPR2�� upo� failin� t� fin� th� CO͠ fil� whic� �
correspond� t� th� comman� nam� give� t� it�� ca� b� se� u� t� �
eithe� searc� th� pat� o� g� directl� t� th� roo� o� th� pat� an� �
loo� fo� a� Extende� Comman� Processor���  I� found�� ZCPR� �
simulate� � comman� t� tha� Extende䠠 Comman䠠 Processor� �
substitutin� th� user'� comman� lin� a� th� argument� t� it.

    To illustrate my point, consider the following example:


    ɠ hav� � ZE� fil� name� MASM.ZEX�� an� i� perform� th� sam� �
set of commands that my M80.ZEX file did above, namely:

;  MASM.ZEX -- 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

    � typ� i� m� program�� name� DEMO.MAC� an� issu� th� comman� �
"MAS� DEMO"��  Wit� ZE� a� m� Extende� Comman� Processor�� ZCPR� �
look� alon� th� pat� fo� th� comman� MASM�� fail� t� fin� it� an� �
the� simulate� th� comman� "ZE� MAS� DEMO"��  Th� abov� comman� �
file is then executed with DEMO as its passed parameter!


    ɠ thin� tha� th� abov� exampl� illustrate� th� utilit�� o� �
employin� ZE� (o� SUB2� a� a� Extende� Comman� Processor��  Thi� �
i� don� ver� simpl� i� th� ZCPR� environment�  T� d� this� simpl� �
mak� � cop� o� ZEX.CO� an� nam� i� CMDRUN.COM�  Sinc� thi� i� th� �
nam� i� th� ZCPRHDR.LI� fil� an� th� facilit� i� turne� on�� yo� �
now have ZEX as the Extended Command Processor.