ftp.barnyard.co.uk/2015.02.ftp.barnyard.co.uk.tar/ftp.barnyard.co.uk/cpm/walnut-creek-CDROM/CPM/ZCPR33/S-Z/ZAPG.SI

Text File | 2000-06-30 | 56KB | 1,205 lines

.. intended to be printed with Newword 2.x or WS 4
.. ^Y turns italics on and off
.. ".bpoff" turns on draft-quality print, ".bpon" returns to letter-quality



















               ZCPR│ Applicatioε Programmer≤ Guide

                         b∙ DaviΣ McCord

                          Jul∙ 23¼ 1987

                  Copyrigh⌠ 198╖ Echelon¼ Inc.
.paè.FO                                i
                T A B L E   OF   C O N T E N T S

  1. Introduction...............................................1

  2. The ZCPR3 Environment......................................2
     2.1. What is a ZCPR3 Environment?..........................2
          2.1.1. The ZCPR3 Command Processor....................2
          2.1.2. Environment Descriptor.........................3
                 2.1.2.1. TCAP..................................3
          2.1.3. System Segments................................4
                 2.1.3.1. Resident Command Package..............4
                 2.1.3.2. Flow Command Package..................4
                 2.1.3.3. Input/Output Package..................5
                 2.1.3.4. Named Directory Register..............5
          2.1.4. Buffers and Work Areas.........................6
                 2.1.4.1. Multiple Command Line Buffer..........6
                 2.1.4.2. Shell Stack...........................6
                 2.1.4.3. Command Search Path...................7
     2.2. Structures............................................7
          2.2.1. Environment Descriptor.........................8
          2.2.2. TCAP...........................................9
          2.2.3. Command Search Path...........................10
          2.2.4. Named Directory Register......................10
          2.2.5. Multiple Command Line Buffer..................11
          2.2.6. Shell Stack...................................12
          2.2.7. ZCPR3 Utility Header..........................13
     2.3. Initialization Environment...........................14
          2.3.1. Default FCBs..................................14
          2.3.2. Command Line Tail Text........................14
          2.3.3. What's Your Program's Name?...................14

  3. Using ZCPR3 Shell Features................................16
     3.1. Invocation...........................................16
          3.1.1. How Was Your Program Invoked?.................16
          3.1.2. Pausing.......................................16
          3.1.3. Resetting Shell Invocation Flag...............17
          3.1.4. Environment Verification......................17
          3.1.5. Building a Shell Stack Entry..................17
          3.1.6. Pushing an Entry Onto the Shell Stack.........18
          3.1.7. Pending Commands..............................18
          3.1.8. Example Pseudocode for Invocation.............19
     3.2. Generating Commands..................................19
          3.2.1. Prompting the User............................19
          3.2.2. Setting Return Parameters.....................20
          3.2.3. Placing the Desired Command in the Buffer.....20
          3.2.4. Pseudocode for Shell "Generate Command" Funct.21
     3.3. Terminating a Shell..................................21

  4. Programming Examples......................................22
     4.1. Is ZCPR3 Available?..................................22
     4.2. Is ZRDOS Available?..................................22
.PAè.FO
.HE
.PN 1
1. Introduction

Thi≤ documen⌠ i≤ ß referencσ guidσ t∩ ZCPR│ anΣ ┌-Systeφ fo≥ áthσ ì
application≤ programme≥ wh∩ wishe≤ t∩ takσ advantagσ oµ áZCPR3/┌-ì
Systeφ feature≤ anΣ function≤ iε thei≥ applications«  I⌠ ágather≤ ì
togethe≥ áint∩ onσ convenien⌠ documen⌠ thσ informatioε needeΣ áb∙ ì
thσ ááapplicatioε áprogramme≥ áwheε áádevelopinτ ááZCPR│-orienteΣ ì
applications«  Echelon'≤ polic∙ i≤ t∩ suppor⌠ softwarσ developer≤ ì
interesteΣ áiε makinτ thei≥ produc⌠ attractivσ t∩ thσ man∙ áuser≤ ì
oµ thσ ZCPR3/┌-Systeφ environment«

I⌠ i≤ importan⌠ t∩ notσ tha⌠ i⌠ i≤ entirel∙ feasiblσ t∩ writσ áaε ì
applicatioε áwhicΦ áfunction≤ áunde≥ "vanillaó áCP/M¼ áyet¼ áwheε ì
runninτ áoε áß ácompute≥ áwherσ á┌-Systeφ ái≤ áavailable¼ áátake≤ ì
advantagσ áoµ áthσ áfeature≤ oµ ZCPR│ anΣ áZRDOS« á Thus¼ átakinτ ì
advantagσ áoµ ZCPR│ doe≤ no⌠ limi⌠ thσ possiblσ marke⌠ áfo≥ áyou≥ ì
program¼ anΣ caε hel≡ i⌠ t∩ bσ morσ successful.

Thi≤ ádocumen⌠ i≤ structureΣ iε threσ majo≥ sections«  First¼ áwσ ì
wil∞ discus≤ wha⌠ ZCPR│ i≤ oε aε overvie≈ basis¼ describinτ ásomσ ì
oµ áthσ feature≤ anΣ function≤ i⌠ offers¼ witΦ discussioε oµ áthσ ì
datß structure≤ anΣ concept≤ tha⌠ ZCPR│ i≤ baseΣ on«  Second¼ áwσ ì
wil∞ discus≤ iε detai∞ thσ mechanism≤ anΣ theor∙ oµ ZCPR3'≤ SHEL╠ ì
functions¼ áwhicΦ áhavσ no⌠ beeε documenteΣ adequatel∙ áiε áothe≥ ì
Echeloε ápublications« á Third¼ wσ wil∞ givσ áß áfe≈ áprogramminτ ì
example≤ iε aε effor⌠ t∩ savσ thσ applicatioε programme≥ timσ anΣ ì
effort.

GooΣ lucδ iε you≥ worδ witΦ ZCPR3/Z-System.
.paè2. Thσ ZCPR│ Environment

Thσ ZCPR│ environmen⌠ i≤ ß superse⌠ oµ thσ CP/═ 2.▓ áenvironment«  ì
Thσ áZCPR│ environmen⌠ give≤ thσ use≥ áadditiona∞ áfunctionality¼ ì
anΣ ágive≤ áthσ application≤ programme≥ ß mucΦ large≥ áamoun⌠ áoµ ì
informatioε áabou⌠ thσ characteristic≤ oµ thσ ácompute≥ áhardwarσ ì
anΣ áásoftwarσ áenvironment« á Thi≤ áadditiona∞ áinformatioε áái≤ ì
accesseΣ áiε áß marvelousl∙ simplσ way¼ usinτ ß áconstruc⌠ áaptl∙ ì
nameΣ thσ "environmen⌠ descriptor"«

Iε áthi≤ ásubsectioε wσ wil∞ describσ thσ component≤ oµ áß áZCPR│ ì
installatioε oε ß genera∞ overvie≈ basis«  Wherσ appropriate¼ áwσ ì
wil∞ referencσ supportinτ documentatioε fo≥ furthe≥ information«

2.1. Wha⌠ i≤ ß ZCPR│ Environment?

Therσ arσ fou≥ majo≥ "piecesó t∩ ß ZCPR│ installation«  The∙ are║ ì
thσ áZCPR│ áCommanΣ Processor¼ thσ áEnvironmen⌠ áDescriptor¼ áthσ ì
systeφ packages¼ anΣ thσ systeφ buffer≤ anΣ worδ areas«

No⌠ ácovereΣ áb∙ áthi≤ documen⌠ arσ thσ ove≥ á10░ áZCPR│ áutilit∙ ì
programs¼ áwhicΦ áarσ áquitσ aε asse⌠ iε áthei≥ áowε áright« á Aε ì
interesteΣ áprogramme≥ ácoulΣ árefe≥ át∩ áthσ ásourcσ áfo≥ áthesσ ì
program≤ fo≥ example≤ oµ ho≈ giveε function≤ arσ performed«

I⌠ i≤ recommendeΣ thσ thσ interesteΣ programme≥ als∩ revie≈ page≤ ì
▒-2░ áoµ áZCPR3: The Manual¼ especiall∙ iµ ápresentl∙ áunfamilia≥ ì
witΦ ZCPR3«  Thi≤ wil∞ givσ yo⌡ aε iε-deptΦ introductioε t∩ ásomσ ì
basiπ ZCPR│ concepts«

2.1.1. Thσ ZCPR│ CommanΣ Processor

Thσ áZCPR│ áCommanΣ Processo≥ i≤ thσ equivalen⌠ oµ thσ CC╨ áiε áß ì
conventiona∞ áCP/═ 2.▓ system¼ o≥ COMMAND.CO═ iε áMSDO╙ ásystems«  ì
It≤ áfunctioε i≤ t∩ acquirσ thσ nex⌠ commanΣ t∩ bσ executed¼ áanΣ ì
theε executσ it«

Fo≥ ácompatibilit∙ áreasons¼ áthσ ásizσ áoµ áthσ áZCPR│ ááCommanΣ ì
Processo≥ ái≤ á2δ bytes¼ samσ a≤ thσ CP/═ 2.▓ CCP«  Iε áorde≥ át∩ ì
makσ áspacσ áfo≥ áthσ áman∙ áadditiona∞ áfeature≤ áoffered¼ áman∙ ì
formerl∙-interna∞ component≤ oµ thσ CP/═ CC╨ havσ beeε moveΣ áou⌠ ì
oµ áthσ áZCPR│ CommanΣ Processo≥ anΣ int∩ reserveΣ ámemor∙ áarea≤ ì
(typicall∙ abovσ thσ BIOS¼ wherσ the∙ wil∞ no⌠ bσ overwritteε áb∙ ì
systeφ áactivity)«  Thesσ component≤ includσ construct≤ ásucΦ áa≤ ì
thσ commanΣ linσ buffer¼ thσ FC┬ useΣ wheε loadinτ programs¼ áthσ ì
stack¼ etc«

Also¼ ZCPR│ typicall∙ utilize≤ Z8░ opcode≤ iε ß furthe≥ effor⌠ t∩ ì
reducσ ácodσ ásize¼ makinτ eveε morσ spacσ áavailablσ áfo≥ áaddeΣ ì
functions« á Othe≥ áideas¼ sucΦ a≤ movinτ thσ áresiden⌠ ácommand≤ ì
sucΦ a≤ DIR¼ ERA¼ etc.¼ t∩ ß separate¼ dynamicall∙-loadablσ area¼ ì
arσ áals∩ áemployed« á Thσ ne⌠ resul⌠ i≤ átha⌠ áß átypica∞ áZCPR│ ì
CommanΣ áProcesso≥ possesse≤ highl∙ advanceΣ ácommanΣ áprocessinτ ì
function≤ ácompareΣ át∩ áthσ CC╨ o≥ áCOMMAND.COM¼ áwitΦ ámultiplσ
.paèhierarchie≤ áoµ acquirinτ anΣ executinτ commands«  (reµ pτ á2╡-2╕ ì
oµ ZCP╥ 3.│ User'≤ Guide⌐

AlthougΦ thσ codσ sizσ oµ thσ ZCPR│ CommanΣ Processo≥ remain≤ thσ ì
samσ áa≤ thσ CP/═ 2.▓ CCP¼ thσ actua∞ memor∙ usagσ increase≤ áduσ ì
t∩ thσ placemen⌠ oµ thσ formerl∙-interna∞ component≤ int∩ ámemor∙ ì
area≤ áabovσ áthσ áBIOS«  Thσ ne⌠ resul⌠ i≤ ß ádecreasσ áoµ áfreσ ì
memor∙ seeε b∙ applicatioε programs«  Thi≤ i≤ thσ tradσ-ofµ ZCPR│ ì
represents║ ávastl∙ increaseΣ functionalit∙ doe≤ no⌠ comσ áa⌠ án∩ ì
cost«

Echeloε ha≤ certaiε recommendation≤ regardinτ thi≤ memor∙ áusage«  ì
┴ átypica∞ ZCPR│ implementatioε wil∞ rangσ betweeε 1δ anΣ á5δ áoµ ì
additiona∞ ámemor∙ áusagσ compareΣ t∩ standarΣ CP/═ á2.2« á ┴ á1δ ì
"overheadó áprovide≤ áaε áincompletσ áimplementatioε áoµ áZCPR3'≤ ì
components¼ ábu⌠ áonσ áiε whicΦ thσ use≥ caε áusσ áZCPR│ át∩ áhi≤ ì
advantage╗ ß 5δ "overheadó give≤ ß completσ implementatioε oµ al∞ ì
oµ áZCPR3'≤ components¼ anΣ iε Echelon'≤ opinioε árepresent≤ áthσ ì
bes⌠ átradσ-ofµ oµ freσ memor∙ versu≤ thσ enhanceΣ áfunctionalit∙ ì
tha⌠ ZCPR│ caε offer«

2.1.2. Environmen⌠ Descriptor

Thσ áenvironmen⌠ descripto≥ (shor⌠ form║ ENV⌐ i≤ ß 25╢ bytσ áraφ-ì
residen⌠ datß structurσ whicΦ describe≤ ß giveε compute≥ system'≤ ì
ZCPR│ áimplementatioε áanΣ machinσ environment«  Thσ EN╓ ái≤ áthσ ì
"heartó áoµ ß ZCPR│ installatioε anΣ thσ áapplicatioε áprogramme≥ ì
wh∩ áwishe≤ t∩ takσ advantagσ oµ ZCPR│ shoulΣ ábecomσ áintimatel∙ ì
acquainteΣ witΦ it«  (reµ pτ 245¼ 30░-304¼ ZCPR3: The Manual⌐

Thσ áEN╓ ái≤ aε ingeniou≤ solutioε t∩ thσ probleφ áfaceΣ áb∙ áan∙ ì
transien⌠ prograφ oµ easil∙ locating¼ accessing¼ o≥ ámanipulatinτ ì
ß ádesireΣ áfeaturσ áo≥ áaspec⌠ áoµ áthσ áZCPR│ áenvironment« á ┴ ì
transien⌠ áprograφ neeΣ onl∙ kno≈ thσ locatioε oµ thσ EN╓ anΣ ái⌠ ì
ma∙ determinσ a⌠ runtimσ thσ addres≤ anΣ sizσ oµ an∙ giveε áZCPR│ ì
CommanΣ áProcesso≥ áexterna∞ ácomponent¼ o≥ áacces≤ áan∙ áoµ áthσ ì
extendeΣ environmen⌠ definitioε datß thereiε available«

2.1.2.1. TCAP

┴ significan⌠ portioε oµ thσ EN╓ (12╕ bytes⌐ i≤ allocateΣ t∩ áthσ ì
Termina∞ áCapabilitie≤ Segment¼ referreΣ t∩ a≤ thσ TCAP«  Onσ áoµ ì
thσ majo≥ shortcoming≤ oµ CP/═ wa≤ tha⌠ i⌠ haΣ n∩ facilitie≤ áfo≥ ì
describinτ áthσ vide∩ characteristic≤ anΣ command≤ oµ thσ áuser'≤ ì
consolσ device«  Becausσ thi≤ informatioε wa≤ no⌠ availablσ áfroφ ì
thσ áoperatinτ ásystem¼ áever∙ ávide∩-orienteΣ áapplicatioε ááwa≤ ì
requireΣ t∩ internall∙ describσ thσ characteristic≤ oµ thσ systeφ ì
console¼ ásucΦ a≤ escapσ sequence≤ fo≥ curso≥ ápositioning¼ áetc«  ì
Obviously¼ ái⌠ i≤ highl∙ redundan⌠ fo≥ ever∙ applicatioε áprograφ ì
t∩ ámaintaiε áthi≤ áinformatioε internally¼ áanΣ áiµ áthσ ásysteφ ì
console'≤ ácharacteristic≤ áeve≥ áchange¼ áthσ áuse≥ ámus⌠ áátheε ì
reconfigurσ eacΦ applicatioε individually«

Thσ áTCA╨ ái≤ ß datß areß whicΦ describe≤ thσ ácontro∞ ásequence≤ ì
needeΣ t∩ bσ sen⌠ t∩ thσ consolσ t∩ perforφ commoε vide∩-orienteΣ ìèoperations« á Thi≤ áinclude≤ ácurso≥ ápositioning¼ áclearinτ áthσ ì
screen¼ clea≥ t∩ enΣ oµ line¼ etc« I⌠ als∩ include≤ thσ characte≥ ì
code≤ áemitteΣ b∙ thσ console'≤ arro≈ key≤ (iµ áavailable)« á Thσ ì
benefi⌠ oµ usinτ thσ TCA╨ i≤ simple║ transien⌠ program≤ neeΣ áno⌠ ì
bσ reconfigureΣ t∩ ruε oε system≤ witΦ differen⌠ vide∩ ácommands«  ì
Echeloε ácall≤ thi≤ concep⌠ "termina∞ independence"¼ anΣ use≤ ái⌠ ì
extensivel∙ iε ou≥ ZCPR│-orienteΣ product≤ t∩ gooΣ advantage«

2.1.3. Systeφ Segments

┴ áZCPR│ Systeφ Segmen⌠ i≤ ß codσ packagσ o≥ datß filσ whicΦ ácaε ì
bσ loadeΣ usinτ thσ LDR.CO═ utilit∙ int∩ RAM¼ anΣ oncσ s∩ loaded¼ ì
caε ábσ ácalleΣ áupoε b∙ thσ ZCPR│ CommanΣ áProcesso≥ áo≥ áZCPR│-ì
orienteΣ átransien⌠ áprogram≤ t∩ perforφ ß áfunctioε áo≥ áprovidσ ì
information«

Previousl∙ ámentioneΣ werσ thσ EN╓ anΣ TCAP¼ eacΦ oµ whicΦ ái≤ áß ì
Systeφ áSegment« Wσ wil∞ introducσ thσ remaininτ type≤ here¼ áanΣ ì
givσ aε overvie≈ oµ wha⌠ functioε eacΦ performs«

2.1.3.1. Residen⌠ CommanΣ Package

Thσ áResiden⌠ CommanΣ Packagσ (RCP⌐ i≤ ß direc⌠ extensioε oµ áthσ ì
ZCPR│ áCommanΣ áProcesso≥ áfunctioε oµ áprovidinτ áresiden⌠ á(no⌠ ì
transient⌐ ácommands¼ áexemplifieΣ witΦ thσ CP/═ áCCP'≤ ácommand≤ ì
DIR¼ ERA¼ REN¼ etc«  Thσ basiπ ideß i≤ t∩ removσ thesσ áfunction≤ ì
froφ áthσ commanΣ processo≥ t∩ increasσ thσ codσ spacσ áavailablσ ì
withiε áthσ á2δ álimi⌠ oµ thσ commanΣ processo≥ át∩ ábσ áuseΣ áb∙ ì
commanΣ áprocessinτ functions«  Anothe≥ benefi⌠ oµ ámakinτ áthesσ ì
noε-transien⌠ ácommand≤ áß separatσ entit∙ i≤ tha⌠ áthe∙ áma∙ ábσ ì
changeΣ oε-thσ-fl∙ o≥ eliminateΣ iµ desired«

Iµ aε RC╨ i≤ presen⌠ iε ß giveε ZCPR│ installation¼ i⌠ i≤ usuall∙ ì
2δ-byte≤ iε size¼ althougΦ thi≤ caε var∙ anΣ i≤ exactl∙ describeΣ ì
iε thσ ENV«  Typica∞ command≤ availablσ arσ ERA¼ REN¼ TYPE¼ PEEK¼ ì
POKE¼ áPORT¼ áCP¼ áanΣ áLIST¼ áalthougΦ áman∙ ácombination≤ ááarσ ì
possible«

Reµ page≤ 1▓-13¼ 191¼ 29▒-29╢ oµ ZCPR3: The ManualÖ

2.1.3.2. Flo≈ CommanΣ Package

Thσ Flo≈ CommanΣ Packagσ (FCP⌐ i≤ simila≥ iε man∙ respect≤ t∩ thσ ì
RCP«  Likσ thσ RCP¼ thσ FC╨ i≤ bes⌠ vieweΣ a≤ aε extensioε oµ thσ ì
ZCPR│ ááCommanΣ áProcesso≥ áintrinsiπ áá(noε-transient⌐ áácommanΣ ì
functions« á However¼ áthσ FC╨ provide≤ thσ specia∞ áfunctioε áoµ ì
conditiona∞ átestinτ a⌠ thσ operatinτ-systeφ-commanΣ álevel¼ áeg¼ ì
IF¼ AND¼ OR¼ ELSE¼ etc«  Thi≤ functioε enable≤ ß ZCPR│ systeφ át∩ ì
bσ ááver∙ áintelligen⌠ ádurinτ áan∙ átypσ áoµ ábatcΦ áo≥ ááscrip⌠ ì
processing«

Aε áinterestinτ ásidσ ánotσ oε thσ FC╨ i≤ tha⌠ ái⌠ ái≤ áspeciall∙ ì
supplementeΣ áwitΦ ß transien⌠ program«  Becausσ thσ áactua∞ áFC╨ ì
spacσ áiε áRA═ i≤ typicall∙ onl∙ 51▓ bytes¼ áthσ ámorσ áelaboratσ ì
conditiona∞ áátestinτ áfunction≤ áarσ áplaceΣ áiε áthi≤ ááspecia∞ ìètransient¼ whicΦ i≤ automaticall∙ loadeΣ anΣ executeΣ b∙ thσ áFC╨ ì
a≤ necessary«

2.1.3.3. Input/Outpu⌠ Package

Thσ ááInput/Outpu⌠ ápackagσ á(IOP⌐ áallow≤ áeasil∙ ááredirectablσ ì
characte≥ áI/╧ áusinτ áeithe≥ ácustoφ ádriver≤ áo≥ ááprσ-packageΣ ì
commercia∞ software«  ┴ variet∙ oµ implementation≤ arσ ápossible«  ì
Thσ áIO╨ concep⌠ provide≤ ß solutioε fo≥ ß shortcominτ áoµ áCP/M¼ ì
specificall∙ áß álacδ oµ ß standardizeΣ methoΣ áoµ áintercepting¼ ì
handling¼ anΣ redirectinτ characte≥-orienteΣ I/╧ streams«

Thσ áIO╨ ásolutioε lend≤ itselµ t∩ application≤ ásucΦ áa≤ áremotσ ì
acces≤ ásystems¼ áwherσ specia∞ áhandlinτ áoµ ácharacte≥-orienteΣ ì
peripheral≤ i≤ necessary«

Echeloε ámarket≤ commercia∞ IOP'≤ whicΦ perforφ certaiε ávaluablσ ì
functions¼ a≤ showε below║

NuKe∙ ¡ ß keyboarΣ redefine≥ whicΦ allow≤ an∙ ke∙ oε thσ keyboarΣ ì
t∩ ábσ redefineΣ int∩ ß desireΣ strinτ oµ characters«  ┴ áspecia∞ ì
featurσ áoµ NuKe∙ i≤ it≤ capabilit∙ oµ applyinτ thσ áredefinitioε ì
functioε át∩ ákey≤ whicΦ emi⌠ multiplσ ácharacter≤ á(eg¼ áspecia∞ ì
editinτ áo≥ functioε keys⌐ a≤ easil∙ a≤ key≤ whicΦ emi⌠ ß ásinglσ ì
character«

Input/Outpu⌠ áRecorde≥ á¡ Allow≤ outpu⌠ t∩ thσ áconsolσ áo≥ ális⌠ ì
devicσ t∩ bσ captureΣ t∩ ß file«

BackgrounΣ Printe≥ ¡ ┴ backgrounΣ prin⌠ spoole≥ whicΦ spool≤ datß ì
froφ ádisδ file≤ t∩ thσ lis⌠ device¼ whilσ permittinτ usσ oµ áthσ ì
compute≥ b∙ thσ user«

2.1.3.4. NameΣ Director∙ Register

Thσ áNameΣ áDirector∙ áRegiste≥ á(NDR⌐ ái≤ áuseΣ áb∙ áZCPR│ ááanΣ ì
compatiblσ áprogram≤ t∩ parsσ anΣ resolvσ reference≤ át∩ áZCPR3'≤ ì
NameΣ áDirectories« á ┴ átypica∞ ND╥ i≤ 25╢ byte≤ áiε ásize¼ áanΣ ì
permit≤ á1┤ ánameΣ ádirectorie≤ át∩ ábσ áactivσ áásimultaneously«  ì
However¼ variation≤ arσ commonplace«

┴ director∙ namσ unde≥ ZCPR│ i≤ bes⌠ though⌠ oµ a≤ ß synonyφ áfo≥ ì
ß disk/use≥ area«

Thσ áfunctioε áoµ ánameΣ directorie≤ i≤ t∩ ágivσ áthσ áuse≥ ámorσ ì
meaningfu∞ way≤ oµ referrinτ t∩ area≤ oµ hi≤ filσ storagσ system«  ì
Thσ techniquσ useΣ i≤ "flat"¼ eg¼ noε-hierarchical«

Iε áterminology¼ thσ ZCPR│ NameΣ Director∙ functioε i≤ áindicateΣ ì
b∙ áthσ symbolog∙ "DIR:"¼ anΣ thσ alternativσ oµ áspecifyinτ áthσ ì
explici⌠ disδ anΣ use≥ areß i≤ symbolizeΣ b∙ "DU:"«
.paè2.1.4. Buffer≤ anΣ Worδ Areas

A≤ stateΣ previously¼ ß variet∙ oµ component≤ previousl∙ interna∞ ì
t∩ áthσ CP/═ CC╨ arσ madσ externa∞ iε ß ZCPR│ installation« á Thσ ì
ZCPR│ CommanΣ Processo≥ anΣ compatiblσ utilitie≤ caε refe≥ t∩ anΣ ì
manipulatσ thesσ area≤ t∩ initiatσ ne≈ processe≤ o≥ terminatσ olΣ ì
ones¼ o≥ determinσ statu≤ information«

Therσ arσ man∙ buffer≤ anΣ worδ areas¼ to∩ man∙ t∩ bσ covereΣ áiε ì
thi≤ áovervie≈ document«  However¼ threσ tha⌠ arσ ver∙ usefu∞ át∩ ì
thσ application≤ programme≥ arσ thσ Multiplσ CommanΣ Linσ Buffer¼ ì
thσ Shel∞ Stack¼ anΣ thσ CommanΣ SearcΦ Path«

2.1.4.1. Multiplσ CommanΣ Linσ Buffer

Thσ áMultiplσ CommanΣ Linσ Buffe≥ i≤ thσ sourcσ fo≥ al∞ ácommand≤ ì
executeΣ áb∙ áthσ ZCPR│ CommanΣ áProcessor« á Application≤ áwhicΦ ì
desirσ t∩ issuσ operatinτ-systeφ-leve∞ command≤ caε d∩ s∩ áeasil∙ ì
b∙ ásimpl∙ áplacinτ thσ desireΣ commanΣ iε thσ buffer¼ áanΣ áwarφ ì
booting« á I⌠ áshoulΣ ábσ understooΣ tha⌠ therσ áma∙ áalread∙ ábσ ì
command≤ ápendinτ iε thσ buffer¼ s∩ thσ applicatioε shoulΣ áchecδ ì
fo≥ thi≤ situatioε anΣ iµ i⌠ applie≤ shoulΣ preservσ thσ ápendinτ ì
commands« á Thσ applicatioε programme≥ ma∙ desirσ hi≤ prograφ át∩ ì
bσ automaticall∙ rσ-invoked╗ thi≤ i≤ oµ coursσ possiblσ b∙ simpl∙ ì
appendinτ áthσ áthσ commanΣ witΦ thσ ástrinτ á";progname"¼ áwherσ ì
prognamσ ái≤ áthσ namσ oµ thσ desireΣ .CO═ filσ át∩ ábσ áinvoked«  ì
However¼ áß bette≥ solutioε t∩ thi≤ questioε i≤ thσ Shel∞ áStack¼ ì
describeΣ below«

2.1.4.2. Shel∞ Stack

Thσ áShel∞ áStacδ ái≤ ádesigneΣ t∩ copσ áwitΦ áthσ ásituatioε áoµ ì
multiplσ program≤ whicΦ al∞ wisΦ t∩ bσ automaticall∙ árσ-invoked«  ì
Fo≥ example¼ thσ Echeloε utilitie≤ MENU¼ VMEN╒ (Vide∩ Menu)¼ áHS╚ ì
(Historica∞ ááShell⌐ ááarσ áal∞ áprogram≤ áwhicΦ ááneeΣ áát∩ áábσ ì
automaticall∙ árσ-invokeΣ afte≥ generatinτ systeφ ácommands« á Iµ ì
thσ áShel∞ áStacδ werσ no⌠ present¼ thesσ program≤ coulΣ áno⌠ ábσ ì
useΣ átogethe≥ áiε an∙ predictablσ fashion¼ a≤ "nestingó áoµ áthσ ì
sequencσ oµ rσ-invocatioε woulΣ no⌠ bσ possible«

Wσ ácal∞ program≤ oµ thi≤ naturσ "shellsó (deriveΣ froφ thσ áUni° ì
meaninτ áoµ áthσ áword)« á Thσ Shel∞ Stacδ ái≤ áß átypica∞ ástacδ ì
structurσ á(eg¼ LIFO)¼ whicΦ contain≤ thσ name≤ oµ thσ ácurrentl∙ ì
activσ shells«  Thσ ZCPR│ CommanΣ Processo≥ wil∞ ruε thσ ácommanΣ ì
oε áto≡ oµ thσ Shel∞ Stacδ wheε thσ Multiplσ CommanΣ Linσ áBuffe≥ ì
i≤ empty«  Thus¼ ß shel∞ prograφ ma∙ placσ aε entr∙ iε thσ áshel∞ ì
stack¼ ágeneratσ thσ desireΣ operatinτ-systeφ-leve∞ command≤ á(b∙ ì
placinτ theφ iε thσ Multiplσ CommanΣ Linσ Buffer)¼ havσ thσ ZCPR│ ì
CommanΣ ááProcesso≥ ááexecutσ áthσ ádesireΣ ácommands¼ ááanΣ áábσ ì
automaticall∙ rσ-invokeΣ wheε commanΣ processinτ i≤ completed«

Becausσ áoµ áthσ ástacδ nature¼ iµ thσ firs⌠ áshel∞ ágenerate≤ áß ì
commanΣ áwhicΦ áactivate≤ ß seconΣ shell¼ thσ áfirs⌠ áshel∞ áwil∞ ì
remaiε suspendeΣ unti∞ thσ seconΣ shel∞ i≤ terminated«  Meanwhilσ
.paèthσ áseconΣ áshel∞ caε perforφ al∞ norma∞ shel∞ áfunctions¼ áeveε ì
invokinτ ß thirΣ shell¼ etc«

(Seσ Echeloε Applicatioε Notσ #1¼ ZCPR│ Shells¼ anΣ reµ pg≤ á13│-ì
14╖ anΣ 22╡-22╢ ZCPR3║ Thσ Manual⌐

2.1.4.3. CommanΣ SearcΦ Path

Iε thσ proces≤ oµ attemptinτ t∩ resolvσ command≤ generateΣ iε thσ ì
system¼ áthσ ZCPR│ CommanΣ Processo≥ consult≤ thσ CommanΣ áSearcΦ ì
PatΦ áfo≥ informatioε oε wherσ t∩ searcΦ fo≥ átransien⌠ áprogram≤ ì
(.CO═ áfiles)« á T∩ illustrate¼ comparσ ZCPR│ áwitΦ áconventiona∞ ì
CP/═ 2.2¼ a≤ follows«

Thσ áCP/═ áCCP¼ áwheε searchinτ fo≥ ß á.CO═ áfile¼ áexamine≤ áthσ ì
director∙ áoµ file≤ iε thσ currentl∙ loggeΣ disδ anΣ áuse≥ áarea«  ì
Iµ thσ desireΣ filσ i≤ no⌠ found¼ thσ commanΣ i≤ aborted« á Late≥ ì
version≤ áoµ CP/M¼ sucΦ a≤ CP/═ 3¼ wil∞ additionall∙ searcΦ áuse≥ ì
areß zer∩ oµ thσ currentl∙ loggeΣ drive«

ZCPR│ allow≤ thσ use≥ t∩ specif∙ wha⌠ disks/use≥ area≤ arσ t∩ ábσ ì
searcheΣ áfo≥ áinvokeΣ programs«  Thus¼ insteaΣ oµ havinτ án∩ áo≥ ì
ver∙ littlσ contro∞ (a≤ i≤ thσ casσ witΦ CP/M)¼ thσ use≥ i≤ áfreσ ì
t∩ áorganizσ hi≤ systeφ iε ß manne≥ mos⌠ convenien⌠ t∩ áhim« á Hσ ì
ma∙ áspecif∙ ß PatΦ sucΦ a≤ "A0║ M15║ B3:ó anΣ thσ ZCPR│ áCommanΣ ì
Processo≥ wil∞ searcΦ thesσ area≤ oµ hi≤ systeφ wheε lookinτ áfo≥ ì
CO═ files«  Thi≤ specificatioε i≤ thσ "CommanΣ SearcΦ Path"«

┴ átypica∞ ZCPR│ implementatioε possesse≤ ß CommanΣ áSearcΦ áPatΦ ì
whicΦ contain≤ u≡-t∩-╡ entries¼ bu⌠ thσ actua∞ lengtΦ oµ thσ patΦ ì
i≤ ádynamicall∙ changeable« EacΦ entr∙ i≤ ß disk/use≥ t∩ ásearch¼ ì
witΦ tw∩ byte≤ pe≥ entry«

Thσ áPatΦ ái≤ áuseΣ áals∩ áb∙ áZCPR│-compatiblσ átransient≤ áwheε ì
searchinτ fo≥ datß anΣ accessor∙ files¼ eg¼ thσ HELP.CO═ áprograφ ì
searche≤ áthσ PatΦ fo≥ invokeΣ *.HL╨ files« á Echeloε árecommend≤ ì
tha⌠ áaε applicatioε tha⌠ take≤ advantagσ oµ ZCPR│ áals∩ áutilizσ ì
thσ PatΦ function¼ iµ applicable«

2.2. Structures

Iε áthi≤ ásubsectioε wσ wil∞ documen⌠ thσ áprecisσ ástructurσ áoµ ì
variou≤ component≤ oµ thσ ZCPR│ environment¼ primaril∙ t∩ ágathe≥ ì
thi≤ áinformatioε áint∩ áß ásinglσ ádocument¼ áanΣ áprovidσ ááthσ ì
interesteΣ application≤ programme≥ conveniencσ wheε referrinτ át∩ ì
thi≤ information«

Thσ áarσ áman∙ ádifferen⌠ structure≤ whicΦ arσ par⌠ áoµ áß áZCPR│ ì
installation« áThi≤ subsectioε wil∞ documen⌠ thσ one≤ ádeemeΣ áoµ ì
majo≥ áimportance« á Iµ yo⌡ neeΣ informatioε oε ß ástructurσ áno⌠ ì
covereΣ herein¼ thσ bes⌠ sourcσ oµ informatioε i≤ thσ sourcσ codσ ì
t∩ thσ ZCPR│ CommanΣ Processor¼ anΣ thσ sourcσ codσ t∩ thσ áZ3LI┬ ì
anΣ VLI┬ codσ libraries«
.paèThσ structure≤ illustrateΣ hereiε arσ donσ s∩ usinτ Z8░ assemble≥ ì
sourcσ notation«

Fo≥ ááaε áexamplσ áoµ áthσ ámemor∙ áma≡ áoµ áß áápossiblσ ááZCPR│ ì
installation¼ árefe≥ t∩ thσ samplσ Z3BASE.LI┬ filσ listinτ oε ápτ ì
24╖ oµ ZCPR3: The Manual«

2.2.1. Environmen⌠ Descriptor

(reµ pτ 30░-303¼ ZCPR3: The Manual⌐

Thσ áEN╓ segment¼ a≤ mentioneΣ previously¼ actuall∙ include≤ áthσ ì
ZCPR│ TCA╨ (termina∞ capabilities⌐ segmen⌠ iε additioε t∩ wha⌠ i≤ ì
considereΣ thσ environmen⌠ descriptor«  Thσ TCA╨ i≤ discusseΣ áiε ì
detai∞ iε thσ followinτ section«

Ever∙ áZCPR│-compatiblσ áprograφ ácarrie≤ ß pointe≥ át∩ áthσ áEN╓ ì
segment¼ áwhicΦ áallow≤ i⌠ t∩ finΣ thσ othe≥ ácomponent≤ áoµ áthσ ì
ZCPR│ implementatioε iε ß standardizeΣ fashion«

.po 0
.rm 79
.bpoff
ENV:
        jp      0               ; in case someone jumps here by accident
        db      'Z3ENV'         ; signature string
        db      1               ; 1 = external ENV, 2 = internal ENV
ENV+9:
        dw      expath          ; address of PATH
        db      expaths         ; size of path in entries (2-byte elements)
ENV+0Ch:
        dw      rcp             ; address of RCP
        db      rcps            ; size of RCP in 128-byte blocks
ENV+0Fh:
        dw      iop             ; address of IOP
        db      iops            ; size of IOP in 128-byte blocks
ENV+12h:
        dw      fcp             ; address of FCP
        db      fcps            ; size of FCP in 128-byte blocks
ENV+15h:
        dw      z3ndir          ; address of NDR
        db      z3ndirs         ; # of entries (18 bytes each) in NDR
ENV+18h:
        dw      z3cl            ; address of multiple command line buffer
        db      z3cls           ; size of buffer in bytes
ENV+1Bh:
        dw      z3env           ; address of ENV
        db      z3envs          ; size of ENV in 128-byte blocks
ENV+1Eh:
        dw      shstk           ; address of Shell Stack
        db      shstks          ; number of entries
        db      shsize          ; size of each entry in bytes
ENV+22h:
        dw      z3msg           ; address of Message Buffer
ENV+24h:
        dw      extfcb          ; address of external 36-byte FCB
ENV+26h:
        dw      extstk          ; address of External Stack (always 48 bytes) èENV+28h:
        db      0               ; quiet flag (0 = not quiet, 1 = quiet)
ENV+29h:
        dw      z3whl           ; address of WHEEL byte
ENV+2Bh:
        db      speed           ; Processor speed in MHz
ENV+2Ch:
        db      'D'-'@'         ; maximum disk
        db      31              ; maximum user
ENV+2Eh:
        db      1               ; DUOK flag: 1 = OK to accept DU:
ENV+2Fh:
        db      0               ; CRT selection flag (0 or 1)
        db      0               ; Printer selection flag (0 or 1)
ENV+31h:
        db      80              ; width of CRT 0
        db      24              ; height of CRT 0
        db      22              ; number of lines of text to display on CRT 0
ENV+34h:
        db      132             ; width of CRT 1
        db      24              ; height of CRT 1
        db      22              ; number of lines of text to display on CRT 1
ENV+37h:
        db      80              ; width of Printer 0
        db      66              ; height of Printer 0
        db      58              ; number of lines of text on Printer 0
        db      1               ; formfeed flag (0=can't formfeed, 1=can)
ENV+3Bh:
        db      102             ; width of Printer 1
        db      66              ; height
        db      58              ; lines of text
        db      1               ; formfeed flag
ENV+7Eh:
        db      pubdrive        ; drive component of ZRDOS PUBLIC declaration
ENV+7Fh:
        db      pubuser         ; user component of ZRDOS PUBLIC declaration

.rm 65
.bpon
.po 8
2.2.2. TCAP

Thσ áTermina∞ áCapabilitie≤ Segmen⌠ (TCAP⌐ oµ ZCPR│ ái≤ áß ámajo≥ ì
asse⌠ át∩ áthσ áoperatioε áoµ áZCPR3« á Thi≤ ástructurσ áuse≤ ááß ì
combinatioε áoµ áfixeΣ-lengtΦ áanΣ ávariablσ álengtΦ áfield≤ áát∩ ì
describσ ke∙ vide∩ termina∞ characteristics«

Thσ áTCA╨ ái≤ áalway≤ locateΣ 12╕ ábyte≤ áabovσ áthσ áEnvironmen⌠ ì
Descriptor« á I⌠ áma∙ bσ loadeΣ independentl∙ usinτ áthσ áLDR.CO═ ì
utility«

Dozen≤ áoµ áprogram≤ árefe≥ át∩ áthσ áTCA╨ áfo≥ áeas∙ á"termina∞-ì
independentó áoperation╗ ásevera∞ program≤ anΣ áß ádatabasσ áals∩ ì
manipulatσ thσ TCAP«  Examples║ TCSELEC╘ anΣ thσ associateΣ áTCA╨ ì
databasσ áZ3TCAP.TC╨ á(whicΦ ácontain≤ ove≥ 7░ áTCAP≤ áwhicΦ áarσ ì
selecteΣ viß TCSELECT)¼ TCMAKE¼ etc«
.paèFo≥ codσ sample≤ showinτ ho≈ thesσ field≤ arσ accesseΣ anΣ áused¼ ì
seσ thσ sourcσ codσ thσ thσ VLI┬ subroutinσ library«  Als∩ árefe≥ ì
t∩ ápage≤ á304¼ áanΣ 30╣-32╖ oµ ZCPR│: Thσ ═anualÖ áfo≥ áfurthe≥ ì
information«

.po 0
.rm 79
.bpoff
(f)= fixed length
(v)= variable length, terminated with binary zero

        db      'Name of Terminal    '  ; 20 characters (f)
        db      'K'-'@'                 ; Arrow Key UP (f)
        db      'V'-'@'                 ; Arrow Key DOWN (f)
        db      'L'-'@'                 ; Arrow Key RIGHT (f)
        db      'H'-'@'                 ; Arrow Key LEFT (f)
        db      0                       ; Clear Screen Delay (ms) (f)
        db      0                       ; Cursor Addressing Delay (ms) (f)
        db      0                       ; Clear-To-End-Of-Line Delay (ms) (f)
        db      esc,'*',0               ; Clear Screen String (v)
        db      esc,'=%+ %+ ',0         ; Cursor Addressing String (v)

.bpon
(Seσ pagσ 31│ oµ ZCPR3: The ManualÖ fo≥ ß discussioε oµ thσ curso≥ addressinτ ì
symbology)
.bpoff

        db      esc,'t',0               ; Clear-To-End-Of-Line String (v)
        db      esc,')',0               ; Begin Standout (dim) Mode (v)
        db      esc,'(',0               ; End Standout (normal) Mode (v)
        db      0                       ; Terminal Init String (v)
        db      0                       ; Terminal De-init String (v)

.po 8
.rm 65
.bpon
2.2.3. CommanΣ SearcΦ Path

Thσ CommanΣ SearcΦ PatΦ caε bσ useΣ b∙ application≤ searchinτ fo≥ ì
accessor∙ o≥ datß files¼ fo≥ example¼ prograφ overlays«  Seσ áthσ ì
sourcσ codσ t∩ thσ Z3LI┬ routinσ PFIN─ fo≥ samplσ codσ t∩ álocatσ ì
ß filσ alonτ thσ CommanΣ SearcΦ Path«

(Reµ pτ ╣ oµ ZCPR3: The Manual⌐

EacΦ áentr∙ i≤ tw∩ byte≤ long«  ┴ terminatinτ entr∙ i≤ ásignifieΣ ì
wheε áthσ disδ bytσ i≤ ß binar∙ zero«  Iµ thσ specia∞ symbo∞ á"$ó ì
appears¼ ái⌠ árefer≤ t∩ eithe≥ thσ defaul⌠ disδ o≥ ádefaul⌠ áuse≥ ì
area¼ a≤ appropriate«

.bpoff
path:
        db      'A'-'@',0       ; Drive A, user 0 (A0:)
        db      'A'-'@',0       ; Drive A, User 15 (A15:)
        db      'C'-'@',3       ; Drive C, User 3 (C3:)
        db      0               ; end of Path
.bpon

2.2.4. NameΣ Director∙ Register

Thσ NameΣ Director∙ Registe≥ (NDR⌐ allow≤ meaningfu∞ name≤ t∩ ábσ ì
associateΣ witΦ specifiπ disk/use≥ areas«  EacΦ namσ ma∙ bσ áfroφ ì
onσ át∩ eigh⌠ characters¼ anΣ aε u≡-t∩-eigh⌠ ácharacte≥ ápassworΣ ì
ma∙ ábσ áassociateΣ áwitΦ ß giveε name«  Refe≥ t∩ ápage≤ á╖-╣ áoµ ì
ZCPR3║ Thσ Manual« è.pa
Thσ ásizσ oµ thσ NameΣ Director∙ Registe≥ caε var∙ ásignificantl∙ ì
froφ ásysteφ t∩ system«  A≤ always¼ aε applicatioε shoulΣ áalway≤ ì
examinσ áthσ Environmen⌠ Descripto≥ oµ thσ machinσ áfo≥ áaccuratσ ì
sizσ information«

┴ áquestioε átha⌠ áarise≤ wheε therσ arσ tw∩ ádifferen⌠ áway≤ áoµ ì
referrinτ t∩ ß director∙ (iε thi≤ case¼ eithe≥ thσ director∙ namσ ì
o≥ thσ DU:⌐ i≤ whicΦ referencσ methoΣ ha≤ priority«  Fo≥ example¼ ì
ß director∙ namσ oµ "C:ó ma∙ bσ resolveΣ onσ wa∙ iµ DU║ áscanninτ ì
occur≤ first¼ anΣ anothe≥ wa∙ iµ DIR║ scanninτ take≤ placσ áfirs⌠ ì
(anΣ therσ i≤ ß NameΣ Director∙ witΦ ß matchinτ name)«  Echelon'≤ ì
officia∞ distributioε ZCPR│ alway≤ scan≤ thσ DIR║ forφ first¼ át∩ ì
preven⌠ áthσ ásituatioε oµ thσ use≥ defininτ áß ánameΣ ádirector∙ ì
whicΦ i≤ no⌠ accessible«

Password≤ ácaε bσ associateΣ witΦ ß giveε nameΣ directory« á Thi≤ ì
passworΣ ái≤ onl∙ oµ significancσ iµ ß referencσ i≤ madσ t∩ átha⌠ ì
director∙ áviß thσ DIR║ form¼ anΣ i≤ unapplicablσ át∩ áreference≤ ì
usinτ thσ DU║ form«  Thus¼ iµ thσ DU║ forφ i≤ allowed¼ ápassword≤ ì
arσ ábypassed« á Thi≤ ái≤ áthσ áreasoε áfo≥ áthσ áfielΣ áoµ ááthσ ì
Environmen⌠ Descripto≥ labeleΣ thσ "DUO╦ flag"«  Wheε ß securit∙-ì
orienteΣ ásysteφ i≤ implemented¼ thσ systeφ implemento≥ wil∞ áse⌠ ì
thσ áDUO╦ áflaτ t∩ indicatσ tha⌠ program≤ shoulΣ no⌠ áaccep⌠ áDU║ ì
references╗ áthi≤ áforce≤ thσ use≥ t∩ usσ onl∙ áDIR║ áforms¼ áanΣ ì
thereforσ password≤ canno⌠ bσ bypassed«

Echeloε recommend≤ tha⌠ application≤ conforφ t∩ thi≤ respec⌠ áfo≥ ì
thσ securit∙ oµ directories¼ a≤ otherwisσ you≥ applicatioε ma∙ bσ ì
unsuitablσ fo≥ securσ systeφ usage«

EacΦ áentr∙ áiε thσ ND╥ i≤ 1╕ byte≤ long«  Thσ áfirs⌠ átw∩ ábyte≤ ì
indicatσ áthσ disk/use≥ thi≤ entr∙ i≤ t∩ bσ associateΣ áwith╗ áiµ ì
thσ ádisδ ábytσ ái≤ zero¼ thi≤ indicate≤ thσ áenΣ áoµ áthσ álist«  ì
Followinτ thσ firs⌠ tw∩ byte≤ arσ ╕ character≤ oµ uppercasσ átex⌠ ì
whicΦ denotσ thσ actua∞ namσ beinτ defined«  Followinτ thi≤ i≤ aε ì
additiona∞ eigh⌠ bytσ fielΣ whicΦ ma∙ contaiε ß password«

.bpoff
.po 0
.rm 79
z3ndir:
        db      'A'-'@',0       ; DU: associated with this entry (A0:)
        db      'ROOT    '      ; Name declared by this entry
        db      '        '      ; Password field (blanks=no password)

        db      'B'-'@',0       ; DU: associated with this entry (B0:)
        db      'WORK    '      ; Name declared by this entry
        db      'XYZZY   '      ; password

        db      0               ; End of NDR
.bpon
.po 8
.rm 65

2.2.5. Multiplσ CommanΣ Linσ Buffer

Thσ áZCPR│ Multiplσ CommanΣ Linσ Buffe≥ i≤ useΣ b∙ ß ávariet∙ áoµ ì
ZCPR│ tools« Iµ yo⌡ wisΦ t∩ utilizσ it¼ yo⌡ shoulΣ bσ awarσ átha⌠ ì
i⌠ i≤ possiblσ tha⌠ pendinτ command≤ ma∙ stil∞ bσ residen⌠ withiε ì
thσ ábuffer¼ áanΣ ápreservσ átheφ áiµ áso« á Also¼ áthσ ácommanΣ-ì
generatioε áproces≤ áshoulΣ átakσ int∩ áaccoun⌠ áthσ ápossibilit∙ ìègenerateΣ ácommanΣ plu≤ pendinτ command≤ ma∙ bσ to∩ largσ t∩ áfi⌠ ì
int∩ thσ buffer«

Thσ ásizσ oµ thσ buffe≥ oε mus⌠ ZCPR│ system≤ i≤ 20░ ábytes¼ ábu⌠ ì
thi≤ ácaε ávary« Refe≥ t∩ thσ Environmen⌠ áDescripto≥ át∩ áobtaiε ì
accuratσ information«

┴ ágooΣ examplσ oµ sourcσ codσ fo≥ handlinτ thσ multiplσ ácommanΣ ì
linσ ábuffe≥ ái≤ ágiveε áiε Z3LIB'≤ áGETCL1¼ áGETCL2¼ áanΣ áPUTC╠ ì
routines«

Thσ áusua∞ ámultiplσ ácommanΣ delimite≥ ái≤ áthσ ásemicoloε á(;)«  ì
Leadinτ áspace≤ áiε áindividua∞ ácommand≤ ácaε ábσ áásignificant¼ ì
especiall∙ unde≥ ZCP╥ 3.3«

.bpoff
.po 0
.rm 79
Z3CL:
     dw      nxtcmd        ; address of next command in buffer
     db      z3cls         ; size of command line buffer in bytes
     dΓ      dumm∙         ╗ dumm∙ bytσ se⌠ durinτ BDO╙ "ReaΣ Consolσ Bufferó
                           ╗ Functioε
nxtcmd:                    ; this varies depending on command execution
     db      'DIR;WS TEXT1'; Uppercase string of commands
     db      0             ; terminating binary zero

.bpon
.po 8
.rm 65
2.2.6. Shel∞ Stack

Thσ áShel∞ áStacδ ái≤ áuseΣ t∩ áassurσ ápredictablσ áfunctioε áoµ ì
multiplσ shel∞ program≤ ¡ program≤ tha⌠ arσ designeΣ t∩ ágeneratσ ì
operatinτ-systeφ-leve∞ ácommand≤ anΣ bσ automaticall∙ árσ-invokeΣ ì
wheε executioε oµ thosσ command≤ i≤ complete«

A≤ it≤ namσ implies¼ thσ Shel∞ Stacδ i≤ ß standarΣ Las⌠-Iε-Firs⌠-ì
Ou⌠ stack« Thσ programme≥ shoulΣ bσ awarσ tha⌠ i⌠ i≤ possiblσ át∩ ì
overflo≈ áthσ ástack¼ anΣ thi≤ shoulΣ bσ aε áerro≥ áconditioε át∩ ì
checδ for«

EacΦ áentr∙ iε thσ Shel∞ Stacδ i≤ ß u≡-t∩-3▓-bytσ (usually⌐ átex⌠ ì
strinτ áwhicΦ ái≤ essentiall∙ ß commanΣ t∩ reinvokσ áthσ ádesireΣ ì
program¼ plu≤ an∙ desireΣ trailinτ commanΣ linσ parameters« á Thσ ì
arσ áátypicall∙ áá┤ ásucΦ áentrie≤ áavailablσ áiε ááthσ áádefaul⌠ ì
configuratioε áoµ áZCPR│ recommendeΣ b∙ Echelon¼ bu⌠ áthσ áactua∞ ì
numbe≥ ái≤ declareΣ iε thσ system'≤ Environmen⌠ Descriptor« á Thσ ì
topmos⌠ áentr∙ áiε thσ stacδ wil∞ bσ executeΣ wheε therσ áarσ án∩ ì
pendinτ command≤ iε thσ Multiplσ CommanΣ Linσ Buffer«

Seσ áthσ ásectioε áoµ thi≤ documen⌠ átitleΣ á"Usinτ áZCPR│ áShel∞ ì
Featuresó fo≥ furthe≥ information¼ a≤ wel∞ a≤ thσ sourcσ codσ fo≥ ì
thσ ááZ3LI┬ ároutine≤ áGETSH1¼ áGETSH2¼ áanΣ áQSHELL¼ ááanΣ ááthσ ì
publicatioε Applicatioε Notσ #▒ ¡ ZCPR│ ShellsÖ.

EacΦ áshel∞ ástacδ áentr∙ ái≤ typicall∙ 3▓ ábyte≤ álong¼ áanΣ ái≤ ì
terminateΣ b∙ ß binar∙ zer∩ (whicΦ mus⌠ bσ counteΣ a≤ par⌠ oµ thσ ì
string'≤ length)«
.paè.bpoff
.po 0
.rm 79
shstk:
        db      'VFILER A15:',0 ; VFILER is on the "top" of the stack
        ds      20              ; space unused by above entry
        db      'M15:HSH',0     ; HSH will resume when VFILER terminates
        ds      24              ; space unused by above entry
        db      0               ; no entry
        ds      63              ; unused space

.bpon
.po 8
.rm 65
2.2.7. ZCPR│ Utilit∙ Header

Ever∙ ZCPR│-compatiblσ prograφ need≤ aε eas∙ wa∙ t∩ determinσ thσ ì
addres≤ áoµ thσ Environmen⌠ Descripto≥ s∩ tha⌠ i⌠ ma∙ áacces≤ áo≥ ì
manipulatσ áthσ expandeΣ function≤ offereΣ b∙ ZCPR3« á Thi≤ áeas∙ ì
wa∙ áoµ findinτ thσ Environmen⌠ Descripto≥ i≤ ásupporteΣ áthrougΦ ì
thσ usσ oµ ß standarΣ heade≥ fo≥ transien⌠ programs«  Onσ oµ áthσ ì
element≤ oµ thσ heade≥ i≤ ß pointe≥ t∩ thσ iε-RA═ ENV¼ anΣ i≤ se⌠ ì
eithe≥ áautomaticall∙ wheε thσ prograφ i≤ loadeΣ anΣ executeΣ áb∙ ì
thσ áZCPR│ áCommanΣ áProcesso≥ á(iε thσ casσ áoµ áZCP╥ á3.3)¼ áo≥ ì
manuall∙ áusinτ thσ installatioε too∞ Z3INS.CO═ (iε thσ ácasσ áoµ ì
ZCP╥ á3.0)«  Thi≤ pointe≥ i≤ thσ singlσ linδ tha⌠ áthσ átransien⌠ ì
ha≤ witΦ thσ ZCPR│ environment¼ anΣ obviousl∙ mus⌠ bσ correc⌠ fo≥ ì
thσ ásysteφ átha⌠ ái⌠ i≤ runninτ on¼ áotherwisσ áresult≤ áma∙ ábσ ì
unpredictable«

Iµ you≥ applicatioε i≤ actuall∙ goinτ t∩ bσ directl∙ (a≤ áopposeΣ ì
t∩ álettinτ áthσ ZCPR│ CommanΣ Processo≥ d∩ i⌠ fo≥ áyou⌐ áloadinτ ì
anothe≥ prograφ int∩ thσ TPA¼ i⌠ i≤ recommendeΣ tha⌠ you≥ prograφ ì
scaε áfo≥ áthσ standarΣ header¼ anΣ iµ onσ i≤ found¼ áensurσ áthσ ì
pointe≥ át∩ áthσ áEnvironmen⌠ áDescripto≥ ácontaineΣ áthereiε ái≤ ì
accurate«

I⌠ ái≤ áals∩ áthougΦ thσ usσ oµ thσ ástandarΣ áheade≥ átha⌠ áyou≥ ì
prograφ ácaε automaticall∙ determinσ whethe≥ i⌠ i≤ runninτ áiε áß ì
ZCPR│ ásystem«  Seσ thσ subsectioε titleΣ "Programminτ áExamplesó ì
fo≥ thσ detail≤ oµ ho≈ thi≤ i≤ done«

Refe≥ áát∩ ápagσ á22╣ áoµ áZCPR3║ áThσ áManualÖ ááfo≥ ááadditiona∞ ì
information«

Thσ standarΣ heade≥ fo≥ ß transien⌠ prograφ i≤ expecteΣ t∩ ábegiε ì
a⌠ áaddres≤ á100h«  T∩ determinσ iµ ß giveε .CO═ filσ ái≤ áZCPR│-ì
compatible¼ simpl∙ checδ fo≥ thσ "Z3ENVó string«

.bpoff
.po 8
.rm 79
100h:
        jp      start           ; jump over header...
        db      'Z3ENV'         ; signature string for identification
        db      1               ; denotes external environment
z3eadr:
        dw      z3env           ; pointer to ENV
        ...                     ; possible other data areas
start:                          ; the actual code start of your program
        ...                     ; your code

.bpon
.po 8
.rm 65
.paè2.3. Initialization Environment

Thi≤ áásubsectioε ádescribe≤ áwha⌠ ákinΣ áoµ ááenvironmen⌠ ááyou≥ ì
applicatioε ácaε áexpec⌠ wheε i⌠ i≤ loadeΣ anΣ ruε b∙ áthσ áZCPR│ ì
CommanΣ áProcessor«  I⌠ cover≤ thσ variation≤ betweeε áZCPR│ áanΣ ì
CP/═ áregardinτ ádefaul⌠ FC┬ initialization¼ anΣ als∩ áß áfeaturσ ì
uniquσ át∩ áZCPR│ átha⌠ allow≤ yo⌡ t∩ determinσ áwha⌠ ánamσ áyou≥ ì
prograφ wa≤ invokeΣ with«

2.3.1. Defaul⌠ FCBs

Thσ átw∩ ádefaul⌠ FCB≤ (a⌠ 005CΦ anΣ 006Ch⌐ áarσ ástructureΣ áanΣ ì
initializeΣ áb∙ áthσ commanΣ linσ parse≥ interna∞ át∩ áthσ áZCPR│ ì
CommanΣ áProcessor«  Thσ parse≥ scan≤ thσ commanΣ tai∞ passeΣ áb∙ ì
thσ áuser¼ áwhicΦ ma∙ contaiε ß filenamσ referencσ oµ áthσ áform≤ ì
FILENAME.TYP¼ D:FILENAME.TYP¼ U:FILENAME.TYP¼ DU:FILENAME.TYP¼ o≥ ì
DIR:FILENAME.TYP« áá Thσ ááadditiona∞ ádatß áavailablσ áát∩ ááthσ ì
programme≥ áiε thesσ situation≤ i≤ thσ use≥ numbe≥ oµ thσ áparseΣ ì
filename¼ áwhicΦ i≤ alway≤ placeΣ a⌠ FCB+1│ (thσ S▒ byte¼ iε áDR╔ ì
parlance)« á ┴ áprograφ runninτ unde≥ ZCPR│ shoulΣ ápreservσ áthσ ì
content≤ oµ thi≤ bytσ internally¼ anΣ prio≥ t∩ openinτ thσ áfile¼ ì
ensurσ áthσ appropriatσ use≥ numbe≥ i≤ selecteΣ viß DO╙ ácal∞ á3▓ ì
(set/ge⌠ áuser)«  Remember¼ thσ bytσ a⌠ FCB+░ i≤ thσ ádrivσ ábytσ ì
(jus⌠ áa≤ witΦ standarΣ cp/m⌐ anΣ therefore¼ n∩ matte≥ wha⌠ átypσ ì
oµ ádu║ áo≥ ádir║ prefi° wa≤ giveε b∙ thσ use≥ áa≤ ápar⌠ áoµ áthσ ì
commanΣ tail¼ thσ programme≥ caε alway≤ extrac⌠ thσ resolveΣ áDU║ ì
froφ FCB+░ anΣ FCB+1│ respectively«  Iµ thσ parse≥ canno⌠ resolvσ ì
thσ áDU║ o≥ DIR║ specification¼ FCB+░ anΣ FCB+1│ wil∞ bσ áse⌠ át∩ ì
thσ ácurren⌠ "defaultó DU:«  Thi≤ applie≤ t∩ onl∙ thσ áfirs⌠ átw∩ ì
token≤ oµ thσ commanΣ tail╗ an∙ additiona∞ token≤ arσ no⌠ áparseΣ ì
fo≥ FC┬ initialization«

Fo≥ ß sourcσ codσ samplσ oµ thσ algorithφ useΣ t∩ parsσ áfilenamσ ì
specifications¼ seσ thσ Z3LI┬ routinσ ZPRSFN«

2.3.2. CommanΣ Linσ Tai∞ Text

A≤ áwitΦ ácp/m¼ thσ actua∞ tex⌠ oµ thσ commanΣ linσ tai∞ ácaε ábσ ì
founΣ beginninτ a⌠ addres≤ 0080h«  Thσ firs⌠ bytσ i≤ ß ácharacte≥ ì
count¼ followeΣ b∙ thσ text¼ terminateΣ witΦ ß binar∙ zero«  Thi≤ ì
i≤ áwherσ thσ programme≥ ma∙ locatσ token≤ beyonΣ thσ áfirs⌠ áanΣ ì
second¼ o≥ t∩ perforφ hi≤ owε parsinτ iµ s∩ desired«

2.3.3. What'≤ You≥ Program'≤ Name?

Onσ áadditiona∞ áiteφ oµ informatioε whicΦ ma∙ bσ usefu∞ át∩ áthσ ì
programme≥ ái≤ áthσ ádeterminatioε oµ thσ ánamσ áunde≥ áwhicΦ ái≤ ì
prograφ wa≤ invoked«  Becausσ thσ FC┬ buil⌠ anΣ useΣ b∙ thσ ZCPR│ ì
CommanΣ áProcesso≥ áwheε loadinτ thσ prograφ i≤ átypicall∙ áiε áß ì
reserveΣ ámemor∙ áarea¼ áit≤ content≤ arσ áprotecteΣ áfroφ ábeinτ ì
overwritteε b∙ thσ transien⌠ loaΣ operation«  Thσ programme≥ áma∙ ì
determinσ thσ curren⌠ namσ oµ hi≤ prograφ b∙ firs⌠ examininτ áthσ ì
EN╓-residen⌠ pointe≥ t∩ thσ "externa∞ FCBó (founΣ a⌠ ENV+24h)╗ iµ
.paèthi≤ i≤ nonzero¼ i⌠ hold≤ thσ addres≤ oµ thσ externa∞ FCB¼ áwhicΦ ì
i≤ aε FC┬ containinτ thσ namσ thi≤ prograφ wa≤ invokeΣ with«

Thσ áaddres≤ áoµ áthσ externa∞ FC┬ i≤ founΣ áiε áthσ áEnvironmen⌠ ì
Descriptor«
.paè3. Usinτ ZCPR│ Shel∞ Features

Thi≤ ásubsectioε ádiscusse≤ thσ necessar∙ step≤ fo≥ ámakinτ áyou≥ ì
applicatioε prograφ int∩ ß ZCPR│ Shell«  Thσ advantage≤ oµ áusinτ ì
thσ áZCPR│ Shel∞ Stacδ havσ beeε previousl∙ ádiscussed« á Becausσ ì
thσ internal≤ oµ shel∞ operatioε havσ no⌠ beeε adequatel∙ covereΣ ì
iε áothe≥ Echeloε documentation¼ i⌠ wil∞ bσ discusseΣ áiε ádetai∞ ì
here.

Therσ arσ threσ aspect≤ oµ shel∞ operatioε whicΦ arσ necessar∙ iε ì
an∙ áshell¼ áwhicΦ áarσ discusseΣ iε ádetai∞ ábelow« á The∙ áare║ ì
Invocation¼ Generatinτ Commands¼ anΣ Exiting.

3.1. Invocation

Invocatioε áoµ ß prograφ witΦ shel∞ characteristic≤ i≤ áthσ ámos⌠ ì
comple° aspec⌠ oµ usinτ shel∞ features.

3.1.1. Ho≈ Wa≤ You≥ Prograφ Invoked?

Thσ áfirs⌠ áaspec⌠ oµ shel∞ operatioε i≤ thσ áinvocatioε áoµ áthσ ì
shell¼ wherσ i⌠ i≤ loadeΣ froφ disδ int∩ RAM«  Thi≤ ma∙ occu≥ áiε ì
eithe≥ áoµ tw∩ ways«  Onσ wa∙ tha⌠ thi≤ caε occu≥ i≤ b∙ thσ áuse≥ ì
enterinτ áß ácommanΣ áa⌠ áthσ commanΣ álinσ áwhicΦ áinvokeΣ áthi≤ ì
program« á Thi≤ i≤ referreΣ t∩ iε thσ subsequen⌠ tex⌠ a≤ á"manua∞ ì
invocation"« á Thσ othe≥ wa∙ oµ invocatioε i≤ wheε thσ áshel∞ ái≤ ì
automaticall∙ áinvokeΣ áb∙ áthσ ZCPR│ CommanΣ áProcesso≥ áa≤ áthσ ì
topmos⌠ ááentr∙ áiε áthσ áShel∞ áStack« á Thi≤ ái≤ áreferreΣ áát∩ ì
subsequentl∙ a≤ "shel∞ invocation".

I⌠ ái≤ importan⌠ t∩ initiall∙ determinσ whicΦ oµ thesσ tw∩ átype≤ ì
oµ áinvocation≤ átooδ place¼ becausσ iµ thσ áshel∞ áwa≤ ámanuall∙ ì
invokeΣ b∙ thσ user¼ thσ shel∞ mus⌠ instal∞ aε appropriatσ áentr∙ ì
iε thσ Shel∞ Stack.

ZCPR│ áprovide≤ ß signa∞ a≤ t∩ whicΦ typσ oµ invocatioε áoccurreΣ ì
witΦ áß áflaτ iε thσ ZCPR│ Messagσ Buffers« á Thσ áZ3LI┬ ároutinσ ì
QSHEL╠ read≤ thi≤ flaτ anΣ return≤ aε appropriatσ resul⌠ (reµ 1╖-ì
4¼ 1╖-╡ oµ ZCPR3║ Thσ Libraries).

3.1.2. Pausing

Iµ you≥ prograφ wa≤ shel∞ invoked¼ onσ decisioε yo⌡ mus⌠ makσ ái≤ ì
whethe≥ áyo⌡ áwisΦ you≥ prograφ t∩ responΣ t∩ ß "pauseó áflaτ áoµ ì
somσ átype« á ┴ pausσ i≤ usuall∙ necessar∙ t∩ allo≈ áthσ áuse≥ áß ì
chancσ át∩ áobservσ thσ result≤ oµ whateve≥ operation≤ áhaΣ ábeeε ì
performeΣ áimmediatel∙ prio≥ t∩ thσ shel∞ invocation«  ┴ flaτ áoµ ì
somσ átypσ wil∞ permi⌠ ß n∩-pausσ modσ oµ operatioε anΣ ápresume≤ ì
thσ áuse≥ ácaε áindicatσ áwheε hσ áwishe≤ át∩ ápausσ áupoε áshel∞ ì
invocatioε anΣ wheε hσ doe≤ not.

Somσ áZCPR│ áshell≤ usσ thσ "Shel∞ Messageó byte≤ áoµ áthσ áZCPR│ ì
Messagσ áBuffe≥ át∩ storσ thσ indicatioε oµ áwhethe≥ ápausinτ ái≤ ì
desireΣ áo≥ ánot« á Thesσ ácontent≤ oµ áthesσ ábyte≤ áarσ áeasil∙
.paèaccesseΣ viß thσ Z3LI┬ routine≤ GETSH═ anΣ PUTSH═ (reµ pagσ á1╡-▓ ì
oµ ZCPR3║ Thσ Libraries).

3.1.3. Resettinτ Shel∞ Invocatioε Flag

Wheε ááyou≥ áprograφ ái≤ áshel∞ áinvoked¼ ái⌠ ái≤ áthσ ááprogram≤ ì
responsibilit∙ át∩ árese⌠ áthσ flaτ whicΦ áindicate≤ ái⌠ áwa≤ ás∩ ì
invoked¼ ás∩ áan∙ subsequen⌠ ZCPR│ transient≤ wil∞ ábσ ápresenteΣ ì
witΦ ácorrec⌠ information«  Thi≤ i≤ usuall∙ donσ througΦ thσ áusσ ì
oµ Z3LIB'≤ PUTCS╘ routinσ (reµ pagσ 17-┤ oµ ZCPR3║ Thσ Manual).

3.1.4. Environmen⌠ Verification

A≤ ástateΣ previously¼ iµ you≥ prograφ wa≤ manuall∙ áinvoked¼ ái⌠ ì
mus⌠ instal∞ itselµ oε thσ Shel∞ Stack«  Iε orde≥ fo≥ thi≤ t∩ ábσ ì
successful¼ áthσ ZCPR│ implementatioε mus⌠ posses≤ thσ ánecessar∙ ì
elements« á Fo≥ prope≥ shel∞ behavior¼ therσ mus⌠ obviousl∙ bσ áß ì
Shel∞ Stacδ defineΣ iε thσ system«  Also¼ iµ systeφ command≤ áarσ ì
t∩ ábσ ágenerateΣ áb∙ thσ application¼ therσ mus⌠ áals∩ áexis⌠ áß ì
Multiplσ áCommanΣ Linσ Buffer«  I⌠ i≤ adviseΣ tha⌠ áyou≥ áprograφ ì
checδ áfo≥ thσ presencσ anΣ appropriatσ characteristic≤ oµ áthesσ ì
element≤ ááoµ ááthσ áZCPR│ áenvironmen⌠ ááprio≥ áát∩ ááattemptinτ ì
installatioε oε thσ Shel∞ Stack«

Thσ Z3LI┬ routine≤ GETSH▒ (reµ pagσ 1╡-╢ oµ ZCPR3║ Thσ Libraries⌐ ì
anΣ áGETCL▒ (reµ pagσ 1┤-┤ oµ ZCPR3║ Thσ Libraries⌐ áprovidσ áthσ ì
desireΣ informatioε oε thesσ systeφ elements«  Thesσ element≤ ma∙ ì
als∩ ábσ áverifieΣ áthrougΦ direc⌠ checkinτ oµ áthσ áENV« á Thesσ ì
element≤ áarσ considereΣ indispensiblσ t∩ thσ operatioε oµ áZCPR│ ì
a≤ áß áwhole¼ áanΣ áarσ ápresen⌠ áiε áeveε áthσ ásmalles⌠ ááZCPR│ ì
implementation≤ distributeΣ b∙ Echelon.

3.1.5. Buildinτ ß Shel∞ Stacδ Entry

Thσ ábes⌠ áwa∙ t∩ thinδ oµ aε entr∙ iε thσ Shel∞ Stacδ ái≤ áa≤ áß ì
smal∞ áZCPR│ ácommanΣ line¼ whicΦ i≤ designeΣ át∩ áreinvokσ áyou≥ ì
prograφ áautomatically«  Obviously¼ t∩ d∩ this¼ thσ áshel∞ ástacδ ì
entr∙ ámus⌠ ácontaiε áthσ ánamσ oµ you≥ áprograφ á(refe≥ át∩ áthσ ì
previou≤ áásubsectioε áoµ áthi≤ ádocumen⌠ átitleΣ á"What'≤ ááYou≥ ì
Program'≤ Name?"⌐ anΣ an∙ trailinτ parameter≤ yo⌡ deeφ necessary¼ ì
terminateΣ b∙ ß binar∙ zero.

Trailinτ ááparameter≤ ácaε ábσ áusefu∞ áfo≥ áápreservinτ áástatu≤ ì
informatioε áregardinτ áyou≥ program«  Wheε shel∞ áinvoked¼ áyou≥ ì
prograφ ácaε áexaminσ áthesσ átrailinτ áparameter≤ áanΣ ááresponΣ ì
appropriately« á ┴ gooΣ examplσ oµ thi≤ i≤ thσ casσ oµ ß áprograφ ì
whicΦ áma∙ áloτ áint∩ ádifferen⌠ DU:'≤ áthaε áthσ áonσ ácurrentl∙ ì
selecteΣ á("default"⌐ b∙ thσ ZCPR│ CommanΣ áProcessor« á Conside≥ ì
thσ scenari∩ oµ ß shel∞ manuall∙ invokeΣ wheε A0║ wa≤ thσ curren⌠ ì
directory¼ áanΣ withiε whicΦ thσ use≥ log≤ int∩ B3:« á Then¼ áthσ ì
use≥ áinitiate≤ somσ typσ oµ externa∞ command¼ whicΦ i≤ run¼ áanΣ ì
theε áthσ áshel∞ i≤ reinvokeΣ froφ thσ Shel∞ Stack« á Unles≤ áyo⌡ ì
havσ ástoreΣ thσ informatioε tha⌠ B3║ wa≤ thσ currentl∙ áselecteΣ ì
director∙ anΣ examinσ tha⌠ informatioε oε shel∞ invocation¼ áyou≥
.paèprograφ áwil∞ apparentl∙ changσ it≤ loggeΣ director∙ froφ B3║ át∩ ì
A0:.

3.1.6. Pushinτ aε Entr∙ Ont∩ thσ Shel∞ Stack

Thσ áac⌠ oµ placinτ ß ne≈ entr∙ int∩ thσ Shel∞ Stacδ i≤ áreferreΣ ì
t∩ a≤ ß "pushó operation«  I⌠ i≤ quitσ eas∙ t∩ utilizσ thσ áZ3LI┬ ì
routinσ SHPUS╚ (reµ pagσ 1╕-╣ oµ ZCPR3║ Thσ Libraries⌐ t∩ perforφ ì
thi≤ function.

Essentially¼ áSHPUS╚ áattempt≤ t∩ movσ an∙ existinτ áShel∞ áStacδ ì
entrie≤ onσ leve∞ deepe≥ iε thσ Shel∞ Stack¼ anΣ theε place≤ áthσ ì
ne≈ entr∙ oε to≡ oµ thσ stack.

I⌠ ái≤ áadviseΣ tha⌠ thσ programme≥ bσ awarσ i⌠ ái≤ ápossiblσ át∩ ì
overflo≈ áthσ Shel∞ Stack¼ anΣ thi≤ shoulΣ bσ aε erro≥ áconditioε ì
t∩ checδ for.

3.1.7. Pendinτ Commands

Thσ las⌠ actioε ß shel∞ mus⌠ takσ afte≥ beinτ manuall∙ invokeΣ i≤ ì
t∩ áchecδ thσ ZCPR│ Multiplσ CommanΣ Linσ Buffe≥ t∩ determinσ áiµ ì
therσ áarσ áan∙ pendinτ commands«  Iµ therσ áarσ ástil∞ ácommand≤ ì
pendinτ iε thσ buffer¼ thσ shel∞ prograφ mus⌠ exi⌠ (warφ boot⌐ t∩ ì
permi⌠ áthosσ command≤ t∩ bσ executeΣ prio≥ t∩ thσ actua∞ usσ áoµ ì
thσ áshel∞ program«  Thσ Z3LI┬ routinσ GETCL▓ (reµ pagσ á1┤-┤ áoµ ì
ZCPR3║ áThσ Libraries⌐ allow≤ thσ programme≥ t∩ easil∙ checδ áthσ ì
statu≤ oµ thσ Multiplσ CommanΣ Linσ Buffer.

Aε áexamplσ wil∞ hel≡ t∩ clarif∙ thi≤ subtlσ topic«  VFILE╥ i≤ áß ì
widel∙ áuseΣ áZCPR│ áshell«  Assumσ thσ use≥ invoke≤ ái⌠ áwitΦ áß ì
commanΣ linσ of:

A0:COMMAND>vfiler;dir<cr>

VFILE╥ áwil∞ ásensσ i⌠ ha≤ beeε manuall∙ invoked¼ áwil∞ ápusΦ áaε ì
entr∙ áont∩ thσ Shel∞ Stack¼ anΣ wheε i⌠ detect≤ tha⌠ átherσ áarσ ì
stil∞ pendinτ commands¼ i⌠ wil∞ exit«  Thσ DI╥ commanΣ wil∞ átheε ì
bσ áexecuted«  Afterward¼ thσ CommanΣ Linσ Buffe≥ i≤ áempty¼ áanΣ ì
ZCPR│ wil∞ theε nex⌠ ruε thσ topmos⌠ commanΣ iε thσ Shel∞ áStack¼ ì
whicΦ wil∞ shel∞ invokσ VFILER.

Thσ áreasoninτ fo≥ thi≤ aspec⌠ oµ shel∞ behavio≥ i≤ aε áextensioε ì
oµ áthσ áhierarchica∞ naturσ iε whicΦ ZCPR│ áprocesse≤ ácommands«  ì
Thσ áMultiplσ áCommanΣ Linσ Buffe≥ alway≤ ha≤ priorit∙ áove≥ áthσ ì
Shel∞ Stack«  Thσ neeΣ fo≥ thi≤ caε bes⌠ bσ observeΣ iε ß commanΣ ì
sequencσ sucΦ as:

A0:COMMAND>shell1;shell2;shell3<cr>

Iµ áthesσ shell≤ diΣ no⌠ behavσ iε thσ wa∙ outlineΣ áabove¼ áthe∙ ì
woulΣ no⌠ bσ nesteΣ properl∙ iε thσ shel∞ stack¼ anΣ an∙ áattemp⌠ ì
t∩ áruε aε externa∞ commanΣ froφ ß shel∞ earlie≥ iε thσ ásequencσ ì
woulΣ resul⌠ iε thσ use≥ endinτ u≡ runninτ thσ nex⌠ shel∞ oµ áthσ ì
sequence.è.pa
3.1.8. Examplσ Pseudocodσ fo≥ Invocation

.bpoff
Savσ Curren⌠ DU:
Executσ QSHELL
I╞ Manuall∙ Invoked
  Verif∙ Shel∞ Stacδ availablσ (GETSH1)
  Verif∙ sizσ oµ Shel∞ Stacδ entr∙ acceptablσ (als∩ GETSH1)
  Verif∙ numbe≥ oµ entrie≤ greate≥ thaε zer∩ (als∩ GETSH1)
  I╞ shel∞ wil∞ generatσ externa∞ commands
    Verif∙ Multiplσ CommanΣ Linσ Buffe≥ availablσ (GETCL1)
  ENDIF
  I╞ an∙ oµ thσ abovσ verification≤ failed
    Abor⌠ Shel∞ Functions
  ENDIF
  (Nex⌠ tw∩ line≤ builΣ ne≈ ß Shel∞ Stacδ entry)
  Ge⌠ Namσ oµ Prograφ (GETEFCB)
  Proces≤ Curren⌠ DU║ a≤ trailinτ paramete≥ iε ne≈ stacδ entry
  PusΦ ne≈ entr∙ ont∩ Shel∞ Stacδ (SHPUSH)
  I╞ an∙ error≤ durinτ Push
    Abor⌠ Shel∞ Functions
  ENDIF
  I╞ an∙ pendinτ command≤ iε thσ buffe≥ (GETCL2)
    Warφ Boot
  ENDIF
ELS┼ (thσ prograφ ha≤ beeε shel∞ invoked)
  I╞ pausσ desired
    Wai⌠ fo≥ Keypress
  ENDIF
  Rese⌠ Shel∞ Invocatioε Flaτ (PUTCS╘ witΦ A=0)
ENDIF
<Prograφ codσ commences>
.bpon

3.2. Generatinτ Commands

Thi≤ ásubsectioε discusse≤ generatinτ ZCPR│ command≤ froφ áwithiε ì
shel∞ áprograms«  I⌠ caε bσ assumeΣ tha⌠ an∙ shel∞ wil∞ ágeneratσ ì
operatinτ-systeφ-leve∞ ácommands¼ a≤ otherwisσ therσ woulΣ bσ án∩ ì
neeΣ fo≥ shel∞ functions.

3.2.1. Promptinτ thσ User

AlthougΦ i⌠ i≤ strictl∙ thσ programmer'≤ decisioε a≤ t∩ wha⌠ forφ ì
an∙ ágiveε áuse≥ promp⌠ wil∞ take¼ Echeloε árecommend≤ átha⌠ áan∙ ì
promp⌠ áfo≥ áß ZCPR│ commanΣ mimiπ thσ áZCPR│ áCommanΣ áProcesso≥ ì
prompt« á Thi≤ usuall∙ take≤ thσ forφ "DU:DIR>"¼ wherσ D╒ i≤ áthσ ì
defaul⌠ ádisδ anΣ use≥ area¼ anΣ DI╥ i≤ thσ ácorrespondinτ ánameΣ ì
director∙ áentr∙ á(iµ onσ exists)«  DIR║ form≤ ácaε ábσ áproduceΣ ì
easil∙ usinτ thσ Z3LI┬ routinσ DUND╥ (reµ pagσ 1╡-│ oµ ZCPR3║ Thσ ì
Libraries).

Somσ áshel∞ program≤ wil∞ havσ buil⌠-iε function≤ t∩ áchangσ áthσ ì
DU║ átha⌠ áthσ shel∞ i≤ operatinτ in«  Iµ thi≤ i≤ átruσ áoµ áyou≥ ì
application¼ you≥ promp⌠ t∩ thσ use≥ ma∙ requirσ specia∞ handlinτ ì
t∩ ásho≈ thσ actua∞ DU║ whicΦ wil∞ bσ useΣ b∙ thσ áZCPR│ áCommanΣ
.paèProcesso≥ wheε i⌠ i≤ processinτ commands¼ a≤ thi≤ ma∙ diffe≥ froφ ì
whateve≥ áDU║ you≥ shel∞ i≤ currentl∙ loggeΣ into«

Conside≥ thσ VFILE╥ prograφ a≤ aε example«  VFILE╥ i≤ áoriginall∙ ì
invokeΣ áwheε áthσ áuse≥ wa≤ loggeΣ int∩ A0:« á Whilσ áVFILE╥ ái≤ ì
running¼ áthσ áuse≥ áuse≤ thσ "Ló commanΣ t∩ áloτ áint∩ áthσ áB3║ ì
directory«  I⌠ i≤ importan⌠ t∩ notσ tha⌠ thi≤ changσ i≤ áinterna∞ ì
t∩ VFILE╥ anΣ doe≤ no⌠ affec⌠ thσ ZCPR│ CommanΣ Processor« á (Thσ ì
onl∙ áwa∙ t∩ affec⌠ thσ ZCPR│ CommanΣ Processo≥ i≤ t∩ changσ áthσ ì
CDIS╦ fielΣ a⌠ addres≤ 0004h¼ bu⌠ i⌠ i≤ considereΣ "illegaló áfo≥ ì
ß transien⌠ t∩ d∩ this.⌐  Iµ VFILE╥ prompt≤ thσ use≥ fo≥ ß áZCPR│ ì
command¼ aε inclusioε oµ B3║ iε thσ promp⌠ woulΣ bσ incorrect¼ a≤ ì
thσ áZCPR│ CommanΣ Processo≥ i≤ no⌠ loggeΣ int∩ átha⌠ ádirectory«  ì
Thσ ácorrec⌠ áDU║ t∩ displa∙ iε thσ promp⌠ i≤ áthσ áorigina∞ áDU║ ì
selecteΣ wheε VFILE╥ wa≤ initiall∙ loaded¼ A0:.

3.2.2. Settinτ Returε Parameters

RelateΣ át∩ thσ jus⌠-discusseΣ neeΣ t∩ ensurσ thσ prope≥ áDU║ ái≤ ì
presenteΣ át∩ áthσ user¼ i⌠ ma∙ als∩ bσ necessar∙ át∩ áprovidσ áß ì
mechanisφ áwhereiε you≥ shel∞ wil∞ returε t∩ thσ prope≥ DU║ áwheε ì
i⌠ ái≤ áshel∞ invokeΣ afte≥ thσ user'≤ ácommand≤ áarσ áprocessed«  ì
Thi≤ ái≤ ábecausσ wheε you≥ prograφ i≤ shel∞ invoked¼ áthσ áZCPR│ ì
CommanΣ áProcessor'≤ defaul⌠ DU║ i≤ selected«  Iµ actioε ái≤ áno⌠ ì
takeε t∩ handlσ thi≤ situation¼ i⌠ ma∙ appea≥ t∩ thσ use≥ tha⌠ hσ ì
raε thσ ZCPR│ commanΣ successfully¼ bu⌠ oε rσ-entr∙ t∩ thσ áshel∞ ì
i⌠ seem≤ t∩ bσ loggeΣ int∩ thσ "wrongó DU║ (eg¼ no⌠ thσ samσ áonσ ì
i⌠ wa≤ loggeΣ int∩ wheε thσ externa∞ command(s⌐ werσ generated).

Thσ áeasies⌠ áwa∙ át∩ áhandlσ thi≤ ásituatioε ái≤ áwitΦ átrailinτ ì
parameter≤ iε thσ Shel∞ Stacδ topmos⌠ entr∙ (whicΦ wσ caε áassumσ ì
belong≤ t∩ you≥ shell)«  Settinτ thesσ parameter≤ t∩ thσ áshell'≤ ì
presentl∙-selecteΣ áDU║ wheε generatinτ ZCPR│ commands¼ anΣ átheε ì
checkinτ áfo≥ átheφ áoε áshel∞ á(re)invocatioε áwil∞ ápermi⌠ áthσ ì
programme≥ át∩ pas≤ informatioε oµ thi≤ typσ ábetweeε ásuccessivσ ì
run≤ áoµ thσ shell«  An∙ kinΣ oµ informatioε ma∙ bσ ápasseΣ áthi≤ ì
way¼ ás∩ álonτ áa≤ ái⌠ ái≤ árepresenteΣ áiε álega∞ ácommanΣ álinσ ì
characters.

3.2.3. Placinτ thσ DesireΣ CommanΣ iε thσ Buffer

Placinτ áthσ desireΣ commanΣ iε thσ Multiplσ CommanΣ Linσ áBuffe≥ ì
i≤ áfairl∙ ástraightforward«  A≤ wa≤ ámentioneΣ ápreviously¼ áal∞ ì
shell≤ ádefe≥ áinitiall∙ t∩ an∙ pendinτ command≤ iε áthσ ábuffer«  ì
Thus¼ i⌠ caε bσ safel∙ assumeΣ tha⌠ therσ arσ n∩ pendinτ command≤ ì
t∩ preserve.

Thσ áZ3LI┬ routinσ PUTC╠ (reµ pagσ 1┤-╡ oµ ZCPR3║ Thσ áLibraries⌐ ì
caε ábσ áuseΣ át∩ áeasil∙ placσ thσ ádesireΣ ácommand≤ áint∩ áthσ ì
Multiplσ áCommanΣ Linσ Buffer«  Thσ desireΣ commanΣ strinτ t∩ ábσ ì
placeΣ iε thσ buffe≥ shoulΣ bσ capitalized.
.paè3.2.4. Pseudocodσ fo≥ Shel∞ "Generatσ Commandó Function

.bpoff
Ge⌠ origina∞ DU║ (selecteΣ wheε prograφ wa≤ initiall∙ invoked)
Promp⌠ use≥ fo≥ desireΣ command¼ usinτ origina∞ DU║ (DUNDR)
I╞ nul∞ command
  Abor⌠ generatσ commanΣ function
ENDIF
I╞ usinτ ß pausσ flag
  Se⌠ i⌠ a≤ appropriatσ (PUTSHM)
ENDIF
Se⌠ returε parameter≤ iε Shel∞ Stacδ a≤ desired
Placσ commanΣ iε buffe≥ (PUTCL)
Warφ Boot
.bpon

3.3. Terminatinτ ß Shell

Actually¼ áterminatinτ áß shel∞ i≤ quitσ simplσ compareΣ át∩ áthσ ì
othe≥ áaspect≤ áoµ áshel∞ operation«  Al∞ ß shel∞ ámus⌠ ád∩ áwheε ì
terminatinτ ái≤ "popó thσ Shel∞ Stack¼ anΣ warφ boot«  Thσ áZ3LI┬ ì
routinσ SHPO╨ (reµ pagσ 1╕-╣ oµ ZCPR3║ Thσ Libraries⌐ i≤ áusuall∙ ì
useΣ fo≥ thi≤ function.
.paè4. Programminτ Examples

Thi≤ ásubsectioε ápresent≤ ß fe≈ usefu∞ "tricksó tha⌠ áhavσ ábeeε ì
developeΣ át∩ ácopσ áwitΦ certaiε basiπ áquestion≤ áfaceΣ áb∙ áaε ì
applicatioε runninτ iε ß ZCPR│ environment«  Wσ recorΣ theφ áherσ ì
iε aε effor⌠ t∩ savσ thσ applicatioε programme≥ timσ anΣ energy«

4.1. I≤ ZCPR│ Available?

Thi≤ tricδ build≤ oε thσ fac⌠ tha⌠ ever∙ ZCPR│-compatiblσ prograφ ì
shoulΣ áhavσ áthσ ástandarΣ áutilit∙ áheade≥ á(seσ áthσ ápreviou≤ ì
subsectioε oε thσ topiπ "ZCPR│ utilit∙ headeró fo≥ thσ details)«

Thi≤ átricδ ápresume≤ tha⌠ you≥ applicatioε wil∞ ábσ ádistributeΣ ì
witΦ thσ pointe≥ t∩ thσ EN╓ iε thσ utilit∙ heade≥ se⌠ t∩ áaddres≤ ì
0000h« á Iµ áthσ pointe≥ i≤ changeΣ t∩ ß nonzer∩ ávaluσ áb∙ ásomσ ì
externa∞ process¼ thi≤ indicate≤ you≥ applicatioε i≤ runninτ iε ß ì
ZCPR│ environment«

Here's a code sample:

.bpoff
.po 8
.rm 79
testz3:
        ld      hl,(z3eadr)     ; get pointer from header
        ld      a,l             ; setup to test
        or      h
        jp      z,noz3          ; if Z result, ZCPR3 not available
yesz3:                          ; if we get here, ZCPR3 is available

.bpon
.po 8
.rm 65
4.2. I≤ ZRDO╙ Available?

Aε applicatioε ma∙ als∩ wisΦ t∩ tes⌠ fo≥ thσ presencσ oµ ZRDO╙ t∩ ì
takσ advantagσ oµ it≤ specia∞ feature≤ iµ i⌠ i≤ available« á Herσ ì
i≤ ß codσ samplσ enablinτ this║

.bpoff
.po 0
.rm 79
dos     equ     5            ; bdos/zrdos entry vector

test$zrdos:
        ld      c,12         ; DRI return version # function
        call    dos          ; go perform function
        ld      a,l          ; get result into A
        cp      22h          ; did we get 2.2?
        jp      nz,not$zrdos ; if not, we aren't using the 2.2 BDOS or ZRDOS
        ld      c,48         ; now let's differentiate between BDOS and ZRDOS
        call    dos          ; BDOS will return 0; ZRDOS returns version
        ld      a,l          ; get result into A
        or      a            ╗ i≤ i⌠ zero?
        jp      z,not$zrdos
zrdos$present║               ╗ iµ wσ ge⌠ here¼ ZRDO╙ i≤ available
        ...