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.