CP/M/CPM_CDROM.iso/simtel/sigm/vols200/vol200/z3lib1.hqp/Z3LIB1.HLP

Text File | 1985-02-09 | 28KB | 943 lines

Introduction   ZCPR3 Environment
Command Line   
GETCL1/GETCL2
CRT/PRT Data   
GETCRT/GETPRT
External FCB   
GETEFCB
Environment    
GETENV/GETVID
FCP Address    
GETFCP
Filenames      
GETFN1/GETFN2
Initialize     
Z3INIT
IOP Address    
GETIOP
DU/Max DU      
GETDUOK/GETMDISK/GETMUSER
Messages       
GETMSG/GETSHM/PUTSHM
Named Dir      
GETNDR
Path           
GETPATH
Processor Spd  
GETSPEED
Quiet Flag     
GETQUIET
RCP Address    
GETRCP
Shell Stack    
GETSH1/GETSH2
Wheel Byte     
GETWHL/PUTWHL
ZEX Data       
GETZFC/GETZNC/GETZRUN/PUTZNC/PUTZRUN
:Introduction to the ZCPR3 Environment

     An∙á prograφ runninτ unde≥ ZCPR│ i≤ withiε wha⌠ caεá bσ ì
calleΣ ß ZCPR│ environment«á  ┴ hos⌠ oµ facilitie≤ anΣá datß ì
i≤á availablσá t∩ thi≤ prograφ whicΦ ß norma∞á CP/═á prograφ ì
doe≤á no⌠ have«á  Fo≥ instance¼á ß prograφ runninτ unde≥ thσ ì
ZCPR│ environment:

          . can find out what name it was invoked by
          . can access a set of messages from ZCPR3 which
               tell it a number of things about how it was
               invoked
          « caε senΣ message≤ t∩ ZCPR│ anΣ program≤ which
               run after it completes
          . can find out many things about its environment,
               such as the processor speed, CRT and printer
               characteristics, maximum number of disks
          . can determine what characteristics the user's
               terminal has and make use of these to employ
               cursor addressing and other such functions

     Al∞á oµá thσá informatioε outlineΣ abovσá anΣá morσá i≤ ì
availablσ t∩ an∙ runninτ prograφ thr⌡ thσ ZCPR│á Environmen⌠ ì
Descriptor«á  Thi≤á i≤á ß blocδ oµ memor∙ (25╢ bytes⌐á whicΦ ì
contain≤á addresse≤á anΣ othe≥ datß iεá ßá precisely-defineΣ ì
format«á  A⌠ installatioε time¼á thσ ZCPR│ utilitie≤ caεá bσ ì
se⌠á u≡á t∩ internall∙ contaiε aε Environmen⌠ Descripto≥á o≥ ì
the∙á caεá bσá installeΣ witΦ ß pointe≥á t∩á aεá Environmen⌠ ì
Descripto≥á whicΦ reside≤ a⌠ somσ fixeΣ locatioεá iεá memor∙ ì
(thi≤á i≤á thσ preferreΣ approach)«á  Oncσ thσá routine≤á iε ì
Z3LI┬ havσ beeε initializeΣ witΦ knowledgσ oµ thσ addres≤ oµ ì
thi≤á environmen⌠á descriptor¼á the∙á caεá extrac⌠á specifiπ ì
informatioε froφ i⌠ fo≥ usσ iε thσ applicatioε program.


     Thσá followinτ informatioε i≤ containeΣ withiε ßá ZCPR│ ì
Environment Descriptor:

     . address of External Path    . size of External Path
     . address of RCP              . size of RCP
     . address of FCP              . size of FCP
     . address of IOP              . size of IOP
     . address of Named Dir        . size of Named Dir
     . address of Command Line     . size of Command Line
     . address of Env Descriptor   . size of Env Descriptor
     . address of Shell Stack      . size of Shell Stack
     . address of Z3 Messages      . size of Stack Entries
     . address of External FCB     . address of External Stk
     . address of Wheel Byte       . quiet flag
     . processor speed             . DU approval flag
     . maximum disk allowed        . maximum user allowed
     « datß oε CR╘                 « datß oε Printe≥
     . two reserved file names     . ZCPR3 TERMCAP (Z3TCAP)


     Thσ purposσ oµ Z3LI┬ i≤ t∩ providσ thσ programme≥á witΦ ì
eas∙á acces≤á t∩á thσ informatioε iε thσá ZCPR│á Environmen⌠ ì
Descripto≥á anΣá t∩á allo≈ hiφ t∩ easil∙ makσá usσá oµá thi≤ ì
information.  To illustrate, the some Z3LIB routines are:

          . GETPRT  - return data on the width, number of
                      lines, and form feed ability of the
                      printer
          . GETCL2  - return the address of the first char
                      of the next command to be run, if any
          . GETEFCB - return the address of the external
                      FCB so the program can determine its
                      name
          . SHPUSH  - push a command line on the shell stack
          « SHPO╨   - po≡ ß commanΣ linσ froφ thσ shel∞ stk
          . IFT     - invoke the next IF level and make it T
          . IFEND   - back up to previous IF level


     Thi≤á HL╨á filσ describe≤ thosσá Z3LI┬á routine≤á whicΦ ì
providσá acces≤á t∩ thσ ZCPR│ Environmen⌠á Descripto≥á data«  ì
All of these routines are of the general name:

          GETxxxxx

wherσá thσ mnemoniπ followinτ thσ GE╘ prefi° allude≤ t∩ wha⌠ ì
information is being obtained.
:Command Line   GETCL1/GETCL2


Z3LIB Routine: GETCL1


Function:
     Return≤á thσ addres≤ oµ thσ CommanΣ Linσ Buffe≥á iεá H╠ ì
anΣá it≤á sizσ (iε byte⌐ iε A«á  Thσ CommanΣ Linσ Buffe≥á i≤ ì
structured as follows:

          cmdline:
               db   <address of next char to process>
               db   <size of buffer>
               db   <dummy used for BDOS READLN function>
               db   <characters in command line>
               db   0

     GETCL▒á return≤á thσ addres≤ oµ CMDLIN┼ iε H╠á anΣá thσ ì
size (at CMDLINE+2) in A.



Inputs: None


Outputs: HL=address of CMDLINE, A=size


Registers Affected: HL, PSW


Side Effects: None


Special Error Conditions:
     HL = 0 if there is no command line buffer



Z3LIB Routine: GETCL2


Function:
     Return≤ thσ addres≤ oµ thσ firs⌠ characte≥ oµ thσá nex⌠ ì
commanΣá t∩ bσ executeΣ iε thσ CommanΣ Linσ Buffe≥ iε H╠ anΣ ì
thσ firs⌠ characte≥ oµ thσ nex⌠ commanΣ iε A«á  A=░ anΣá thσ ì
Zer∩á Flaτ i≤ Se⌠ (Z⌐ iµ therσ arσ n∩ furthe≥ character≤á iε ì
the line.
     The Command Line Buffer is structured as follows:

          cmdline:
               db   <address of next char to process>
               db   <size of buffer>
               db   <dummy used for BDOS READLN function>
               db   <characters in command line>
               db   0

     GETCL▓ return≤ thσ addres≤ containeΣ iε thσ firs⌠ D╫ a⌠ ì
thσ labe∞ CMDLIN┼ iε H╠ anΣ thσ cha≥ a⌠ thi≤ addres≤ iε A.


Inputs: None


Outputs: HL=address of next command, A=first char


Registers Affected: HL, PSW


Side Effects: None


Special Error Conditions:
     HL = 0 if there is no Command Line Buffer.

:CRT/PRT Data   GETCRT/GETPRT


Z3LIB Routine: GETCRT


Function:
     Returε thσ addres≤ oµ thσ CR╘ datß recorΣ iε HL«á  Thi≤ ì
record is structured as follows:

          crtdata:
               db   <width of the CRT in characters>
               db   <number of lines on CRT screen>
               db   <number of text lines on CRT screen>

     For example, a conventional CRT would look like:

               db   80   ; 80 cols
               db   24   ; 24 lines
               db   22   ; 22 text lines


     Thσá numbe≥á oµ tex⌠ line≤ shoulΣ bσ tw∩ les≤ thaεá thσ ì
tota∞á numbe≥ oµ lines«á  I⌠ ma∙ bσ madσ │ o≥ ┤ les≤ iµá thσ ì
use≥ want≤ t∩ seσ wide≥ overla≡ oε hi≤ screen«á  Thσ purposσ ì
oµá thi≤ recorΣ elemen⌠ i≤ t∩ tel∞ utilitie≤ likσá PAG┼á ho≈ ì
man∙á line≤á t∩ outpu⌠ beforσ pausinτ t∩ allo≈ thσá use≥á t∩ ì
reaΣá thσá screen¼á anΣ thi≤ caε bσ reduceΣ (g∩ t∩ 2░ o≥á 1╕ ì
lines⌐á t∩ allo≈ thσ use≥ t∩ seσ morσ oµ thσ las⌠ screeεá hσ ì
was viewing.


Inputs: None


Outputs: HL contains the address of the CRT record


Registers Affected: HL


Side Effects: None


Special Error Conditions: None



Z3LIB Routine: GETPRT


Function:
     Returεá thσ addres≤ oµ thσ Printe≥ datß recorΣá iεá HL«  ì
This record is structured as follows:

          prtdata:
               db   <width of printer in characters>
               db   <number of lines on printer page>
               db   <number of text lines on printer page>
               db   <form feed flag (0=printer can't FF)>

     For example, a typical printer data record would be:

               db   80   ; 80 columns
               db   66   ; 66 lines
               dΓ   5╕   ╗ 5╕ tex⌠ line≤ (┤ up/┤ dε margin)
               db   1    ; printer can form feed


     Usinτá thσ thirΣ bytσ (numbe≥ oµ tex⌠ line≤ pe≥á page)¼ ì
thσá printe≥á pagσá margin≤ arσ selecteΣ a≤á thσá differencσ ì
betweeεá thσá tota∞ numbe≥ oµ line≤ anΣ thσ numbe≥á oµá tex⌠ ì
lines.
     Wheε routine≤ likσ PRIN╘ run¼á the∙ prin⌠ thσ numbe≥ oµ ì
tex⌠á line≤ anΣ then¼á iµ thσ printe≥ caεá forφá feed¼á the∙ ì
issuσá ßá forφ feeΣ character«á  Iµ thσ printe≥á can'⌠á forφ ì
feed¼á thσá senΣá ou⌠á thσ prope≥ numbe≥ oµ blanδá line≤á t∩ ì
advance to the next page.


Inputs: None


Outputs: HL is address of printer data buffer


Registers Affected: HL


Side Effects: None


Special Error Conditions: None
:External FCB   GETEFCB


Z3LIB Routine: GETEFCB


Function:
     Return≤á thσá addres≤ oµ thσ ZCPR│ Externa∞ FC┬ iεá HL«  ì
Return≤á witΦá HL=░á anΣ Zer∩ Flaτ Se⌠ (Z⌐ iµá therσá i≤á n∩ ì
External FCB.

     Unde≥á ZCPR3¼á ß prograφ caε finΣ ou⌠ wha⌠ namσ i⌠á wa≤ ì
invokeΣá b∙á througΦ thσ Externa∞ FCB«á  Byte≤á 1-╕á oµá thσ ì
Externa∞á FC┬á (firs⌠á bytσ i≤ 0⌐ contaiε thσá namσá oµá thσ ì
program just executed by ZCPR3.

     Thi≤á featurσ i≤ particularl∙ usefu∞ fo≥ program≤á likσ ì
Shell≤á whicΦá havσá t∩á pusΦá thei≥á namσá anΣá operationa∞ ì
parameter≤á ont∩á thσ Shel∞ Stacδ iε orde≥ t∩á bσá reinvokeΣ ì
wheε ß commanΣ linσ completes«á  ┴ Shel∞ caε usσ thσ datß iε ì
thσá Externa∞á FC┬á t∩ determinσ wha⌠ it≤á namσá i≤á withou⌠ ì
having to assume that it has a particular name at all times.



Inputs: None


Outputs: HL = address of External FCB, A=0 and Z if none


Registers Affected: HL, PSW


Side Effects: None


Special Error Conditions: None

:Environment    GETENV


Z3LIB Routine: GETENV


Function:
     Returεá thσ addres≤ oµ thσ ZCPR│ Environmen⌠ Descripto≥ ì
in HL.

     Thi≤á functioε i≤ usefu∞ fo≥ thosσ program≤ whicΦá neeΣ ì
t∩á modif∙ thσ ZCPR│ Environmen⌠ Descriptor«á  Mos⌠á oµá thσ ì
routine≤ iε Z3LI┬ whicΦ acces≤ thσ environmen⌠ descripto≥ d∩ ì
s∩á iεá ß R/╧ modσ (the∙ d∩ no⌠ allo≈ thσ prograφ t∩á changσ ì
datß iε it)«á  Somσ program≤ ma∙ neeΣ t∩ d∩ this¼á s∩ GENEN╓ ì
i≤ provided«á  Z3LDR¼á fo≥ example¼á load≤ ß ne≈ Environmen⌠ ì
Descripto≥ froφ ß filσ oε disk¼á anΣ i⌠ use≤ GETEN╓ t∩á finΣ ì
out where to load the file.



Inputs: None


Outputs: HL = address of Environment Descriptor


Registers Affected: HL


Side Effects: None


Special Error Conditions: None



Z3LIB Routine: GETVID


Function:
     Returε thσ addres≤ oµ thσ ZCPR│ TCA╨ (Z3TCAP⌐ Buffe≥ iε ì
HL.  Indicate if this buffer contains a TCAP entry.

     Thi≤á functioε i≤ usefu∞ fo≥ thosσ program≤ whicΦá neeΣ ì
t∩á modif∙á thσ ZCPR│ TCA╨ Buffe≥ anΣ thosσá program≤á whicΦ ì
neeΣá t∩á determinσá iµá thσ TCA╨á i≤á loaded«á  I⌠á ma∙á bσ ì
desirablσá t∩á cal∞á thi≤ routinσ beforσá ßá screen-orienteΣ ì
utilit∙á i≤á executeΣá iε orde≥ t∩ insurσá tha⌠á ßá TCA╨á i≤ ì
available.

     Returεá witΦá A=░ anΣ Zer∩ Flaτ Se⌠ (Z⌐á iµá n∩á Z3TCA╨ ì
entr∙ exist≤ withiε thσ buffer.



Inputs: None


Outputs: HL = address of Z3TCAP Buffer
          A=0 and Zero Flag Set (Z) if no entry in buffer


Registers Affected: HL, PSW


Side Effects: None


Special Error Conditions: None

:FCP Address    GETFCP


Z3LIB Routine: GETFCP


Function:
     Returεá thσ addres≤ oµ thσ flo≈ commanΣ packagσá buffe≥ ì
iε H╠ anΣ thσ sizσ oµ thσ buffe≥ iε term≤ oµ 128-bytσ block≤ ì
in A.  If there is no FCP buffer, A=0 and Zero Flag Set (Z).

     GETFC╨ simpl∙ return≤ detail≤ oε thσ FC╨ buffe≥ addres≤ ì
anΣá size¼á bu⌠ i⌠ doe≤ no⌠ sa∙ iµ aε FC╨ i≤ residen⌠ withiε ì
it«á  T∩á finΣ thi≤ out¼á looδ a⌠ thσ firs⌠ bytσ oµ thσá FC╨ ì
buffer¼á and¼á iµ i⌠ i≤ zero¼á theε therσ i≤ n∩ FC╨ present«  ì
Example:
          ext  getfcp    ;reference
          ...
          call getfcp    ;obtain data
          jz   nofcpbuf  ;no FCP buffer is available
          mov  a,m       ;get first byte of buffer
          ora  a         ;set zero flag accordingly
          jz   nofcpload ;no FCP is in the buffer


Inputs: None


Outputs║ H╠ ╜ addres≤ oµ FC╨ buffer
               A=0 and Zero Flag Set (Z) if no buffer, else
               A=sizσ oµ buffe≥ iε 128-bytσ block≤ anΣ NZ


Registers Affected: HL, PSW


Side Effects: None


Special Error Conditions: None

:Filenames      GETFN1/GETFN2


Z3LIB Routine: GETFN1 or GETFN2


Function:
     Thesσá routine≤ returε thσ addres≤ iε H╠ oµ filenamσá ▒ ì
(GETFN1⌐á anΣ filenamσ ▓ (GETFN2⌐ iε thσá ZCPR│á Environmen⌠ ì
Descriptor«á  EacΦ filenamσ entr∙ i≤ 1▒ byte≤ long¼ matchinτ ì
the filename and filetype fields of the CP/M FCB.

     Thesσá name≤ arσ useΣ t∩ pas≤ name≤ oµ specia∞ file≤ t∩ ì
program≤á fo≥á late≥ use«á  Thei≥ exac⌠á definitioεá i≤á no⌠ ì
presenteΣá anΣá lef⌠ t∩ thσ installer«á  Onσ applicatioεá oµ ì
thesσá i≤ t∩ allo≈ GETFN▒ t∩ returε thσ namσ oµá thσá maste≥ ì
HL╨á filσá (HELP.HLP⌐ whicΦ i≤ t∩ bσ useΣ t∩ inde° int∩á thσ ì
Help System.



Inputs: None


Outputs: HL is address of the selected file name


Registers Affected: HL


Side Effects: None


Special Error Conditions: None

:Initialize     Z3INIT


Z3LIB Routine: Z3INIT


Function:
     Obtaiε thσ addres≤ oµ thσ ZCPR│ Environmen⌠á Descripto≥ ì
froφá thσ callinτ prograφ anΣ se⌠ i⌠ iε ß globa∞ buffe≥á fo≥ ì
future use by the Z3LIB routines.

     Z3INIT is called as follows:

          ext  z3init    ;reference
          ...
          lxi  h,z3env   ;address of ZCPR3 Environment Desc
          call z3init    ;perform function
          ...


Inputs: HL = address of ZCPR3 Environment Descriptor



Outputs: None


Registers Affected: None


Side Effects: None


Special Error Conditions: None

:IOP Address    GETIOP


Z3LIB Routine: GETIOP


Function:
     Returεá thσ addres≤ oµ thσ input/output packagσá buffe≥ ì
iε H╠ anΣ thσ sizσ oµ thσ buffe≥ iε term≤ oµ 128-bytσ block≤ ì
in A.  If there is no IOP buffer, A=0 and Zero Flag Set (Z).

     GETIO╨ simpl∙ return≤ detail≤ oε thσ IOP buffe≥ addres≤ ì
anΣá size¼á bu⌠ i⌠ doe≤ no⌠ sa∙ iµ aε IOP i≤ residen⌠ withiε ì
it«á  T∩á finΣ thi≤ out¼á looδ a⌠ thσ firs⌠ bytσ oµ thσá IOP ì
buffer¼á and¼á iµ i⌠ i≤ zero¼á theε therσ i≤ n∩ IOP present«  ì
Example:
          ext  getiop    ;reference
          ...
          call getiop    ;obtain data
          jz   noiopbuf  ;no IOP buffer is available
          mov  a,m       ;get first byte of buffer
          ora  a         ;set zero flag accordingly
          jz   noiopload ;no IOP is in the buffer


Inputs: None


Outputs║ H╠ ╜ addres≤ oµ IO╨ buffer
               A=0 and Zero Flag Set (Z) if no buffer, else
               A=sizσ oµ buffe≥ iε 128-bytσ block≤ anΣ NZ


Registers Affected: HL, PSW


Side Effects: None


Special Error Conditions: None

:DU/Max Disk/User  GETDUOK/GETMDISK/GETMUSER


Z3LIB Routine: GETDUOK


Function:
     Returε thσ DUO╦ flaτ iε ┴ witΦ thσ Zer∩ Flaτ Se⌠ (Z⌐ iµ ì
A=0«á  DUO╦á i≤á ß flaτ whicΦ tell≤ thσ prograφ iµ i⌠ i≤á t∩ ì
permi⌠ thσ use≥ t∩ specif∙ thσ DU║ prefi° t∩ changσ disδ anΣ ì
use≥ area«  ┴ ZCPR│ utilit∙ caε alway≤ specif∙ ß DIR║ prefi° ì
(nameΣá directory⌐ iε identifyinτ thσ disδ anΣ use≥ areßá t∩ ì
examine¼á bu⌠á iεá somσá "secureóá application≤á i⌠á i≤á no⌠ ì
desirablσá t∩á allo≈ thσ use≥ t∩ emplo∙ thσá DU║á prefi°á t∩ ì
acces≤á AN┘á disk/use≥ area«á  Thi≤ flaτá (DUOK⌐á tell≤á thσ ì
utility if it is OK for the user to employ the DU: prefix.


Inputs: None


Outputs: A=0 and Zero Flag Set (Z) if NOT OK to use DU:
            A=0FFH and Zero Flag Clear (NZ) if OK to use DU:



Registers Affected: PSW


Side Effects: None


Special Error Conditions: None



Z3LIB Routine: GETMDISK


Function:
     Returεá thσá numbe≥á oµ thσ maximuφ disδá iεá A«á  Thi≤ ì
numbe≥ i≤ iε thσ rangσ froφ ▒ t∩ 16¼ wherσ ▒ mean≤ disδ ┴ i≤ ì
the maximum disk on the system and 16 means disk P is.

     Thσá ZCPR│á Environmen⌠á Descripto≥á ma∙á bσá useΣáá t∩ ì
restric⌠á acces≤á t∩á certaiεá part≤á oµá thσá system«á  Fo≥ ì
instance¼á ßá "norma∞ useró ma∙ bσ denieΣ acces≤ t∩ disk≤á ├ ì
anΣá ─ anΣ t∩ an∙ use≥ areß beyonΣ 10«á  ┴ "privelegeΣ useró ì
wh∩ ha≤ thσ powe≥ t∩ changσ thσ ZCPR│ Environmen⌠ Descripto≥ ì
can gain access to any disk or user area he desires.


Inputs: None


Outputs: A = disk number (disk A = 1)



Registers Affected: PSW


Side Effects: None


Special Error Conditions: None



Z3LIB Routine: GETMUSER


Function:
     Returε thσ numbe≥ oµ thσ maximuφ use≥ areß iε A«á  Thi≤ ì
number is in the range from 0 to 31.

     Thσá ZCPR│á Environmen⌠á Descripto≥á ma∙á bσá useΣáá t∩ ì
restric⌠á acces≤á t∩á certaiεá part≤á oµá thσá system«á  Fo≥ ì
instance¼á ßá "norma∞ useró ma∙ bσ denieΣ acces≤ t∩ disk≤á ├ ì
anΣá ─ anΣ t∩ an∙ use≥ areß beyonΣ 10«á  ┴ "privelegeΣ useró ì
wh∩ ha≤ thσ powe≥ t∩ changσ thσ ZCPR│ Environmen⌠ Descripto≥ ì
can gain access to any disk or user area he desires.


Inputs: None


Outputs: A = maximum user area which may be accessed



Registers Affected: PSW


Side Effects: None


Special Error Conditions: None

:Messages       GETMSG/GETSHM/PUTSHM


Z3LIB Routine: GETMSG


Function:
     Returεá thσ addres≤ oµ thσ ZCPR│ Messagσ Buffe≥ iεá HL«  ì
A=░á anΣá Zer∩á Flaτ Se⌠ (Z⌐ iµ therσ i≤á n∩á ZCPR│á Messagσ ì
Buffer.
     Seσ thσ Z3LI┬ informatioε section≤ oε ZCPR│ Messages.


Inputs: None


Outputs: HL = address of ZCPR3 Message Buffer
            A = 0 and Zero Flag Set (Z) if there is none


Registers Affected: HL, PSW


Side Effects: None


Special Error Conditions: None



Z3LIB Routine: GETSHM


Function:
     GETSH═á return≤á thσ valuσ oµ thσ shel∞á messagσá whosσ ì
numbe≥á i≤ specifieΣ iε B«á  Therσ arσ threσ shel∞ messages¼ ì
s∩ ░ <╜ ┬ <╜ ▓ (thσ programme≥ mus⌠ bσ surσ ß valiΣ valuσ i≤ ì
presented).


Inputs: B = Message Number (0, 1, 2)


Outputs: A = Message Value (Zero Flag Set Accordingly)


Registers Affected: PSW


Side Effects: None


Special Error Conditions: None



Z3LIB Routine: PUTSHM


Function:
     PUTSH═ set≤ thσ valuσ oµ thσ shel∞ messagσ whosσ numbe≥ ì
i≤ giveε iε B«á  Thσ messagσ valuσ i≤ iε A«á  Therσ arσ onl∙ ì
three shell messages, so B = 0, 1, or 2.


Inputs: A = Message Value, B = Message Number = 0,1,2


Outputs: None


Registers Affected: None


Side Effects: Message Value is Set


Special Error Conditions: None

:Named Dir      GETNDR


Z3LIB Routine: GETNDR


Function:
     Returεá thσ addres≤ oµ thσ nameΣ director∙ buffe≥ iε H╠ ì
anΣ thσ sizσ oµ thσ buffe≥ iε term≤ oµ 128-bytσ block≤ iε A«  ì
Iµ therσ i≤ n∩ ND╥ buffer¼ A=░ anΣ Zer∩ Flaτ Se⌠ (Z).

     GETNDR simpl∙ return≤ detail≤ oε thσ NDR buffe≥ addres≤ ì
anΣá size¼á bu⌠ i⌠ doe≤ no⌠ sa∙ iµ aε NDR i≤ residen⌠ withiε ì
it«á  T∩á finΣ thi≤ out¼á looδ a⌠ thσ firs⌠ bytσ oµ thσá NDR ì
buffer¼á and¼á iµ i⌠ i≤ zero¼á theε therσ i≤ n∩ NDR present«  ì
Example:
          ext  getndr    ;reference
          ...
          call getndr    ;obtain data
          jz   nondrbuf  ;no NDR buffer is available
          mov  a,m       ;get first byte of buffer
          ora  a         ;set zero flag accordingly
          jz   nondrload ;no NDR is in the buffer


Inputs: None


Outputs║ H╠ ╜ addres≤ oµ NDR buffer
               A=0 and Zero Flag Set (Z) if no buffer, else
               A=sizσ oµ buffe≥ iε 128-bytσ block≤ anΣ NZ


Registers Affected: HL, PSW


Side Effects: None


Special Error Conditions: None

:Path           GETPATH


Z3LIB Routine: GETPATH


Function:
     Returεá thσ addres≤ oµ thσ ZCPR│ Command-SearcΦ PatΦ iε ì
HL«á  A=░á anΣ Zer∩ Flaτ Se⌠ (Z⌐ iµ therσ i≤ n∩ ZCPR│á Path«  ì
Iµá therσá i≤á ß ZCPR│ Path¼á ┴ ╜ numbe≥á oµá two-bytσá patΦ ì
elements allowed in it.

     A ZCPR3 Path Element is structured as follows:

          Byte 1:  Disk ID
                    Disk A = 1, B = 2, etc
                    Current Disk = '$'
          Byte 2:  User ID
                    Number from 0 to 31


     A ZCPR3 Path is terminated by a Disk ID of 0.  Example:

          path:
               db   '$',1     ;current disk, user 1
               db   1,'$'     ;disk A, current user
               db   1,15      ;disk A, user 15
               db   0         ;end of path


Inputs: None


Outputs: HL = address of ZCPR3 Path
            A = 0 and Zero Flag Set (Z) if there is none


Registers Affected: HL, PSW


Side Effects: None


Special Error Conditions: None

:Processor Spd  GETSPEED


Z3LIB Routine: GETSPEED


Function:
     Returε thσ speeΣ oµ thσ processo≥ iε A«á  Thi≤ one-bytσ ì
valuσá i≤ t∩ represen⌠ thσ processo≥ speeΣ iεá MHz¼á s∩á A=▒ ì
means 1 MHz, A = 4 means 4 MHz, etc.

     This function is useful for software timing loops.


Inputs: None


Outputs: A = processor speed


Registers Affected: PSW


Side Effects: None


Special Error Conditions: None

:Quiet Flag     GETQUIET


Z3LIB Routine: GETQUIET


Function:
     Returε thσ Quie⌠ Flaτ iε A«  A╜ ░ anΣ Zer∩ Flaτ Se⌠ (Z⌐ ì
iµá thσ prograφ i≤ NO╘ t∩ ruε quietly¼á A=0FF╚ anΣ N┌ iµ thσ ì
program is to run quietly.

     B∙ quie⌠ operation¼á thσ prograφ i≤ no⌠ t∩ displa∙á an∙ ì
informative messages.


Inputs: None
è
Outputs: A = Quiet Flag (0=not quiet) and Zero Flag set
               accordingly



Registers Affected: PSW


Side Effects: None


Special Error Conditions: None

:RCP Address    GETRCP


Z3LIB Routine: GETRCP


Function:
     Returεá thσá addres≤ oµ thσá residen⌠á commanΣá packagσ ì
buffe≥ iε H╠ anΣ thσ sizσ oµ thσ buffe≥ iε term≤ oµ 128-bytσ ì
block≤ iε A«á  Iµ therσ i≤ n∩ RC╨ buffer¼á A=░ anΣ Zer∩ Flaτ ì
Se⌠ (Z).

     GETRC╨ simpl∙ return≤ detail≤ oε thσ RC╨ buffe≥ addres≤ ì
anΣá size¼á bu⌠ i⌠ doe≤ no⌠ sa∙ iµ aε RC╨ i≤ residen⌠ withiε ì
it«á  T∩á finΣ thi≤ out¼á looδ a⌠ thσ firs⌠ bytσ oµ thσá RC╨ ì
buffer¼á and¼á iµ i⌠ i≤ zero¼á theε therσ i≤ n∩ RC╨ present«  ì
Example:
          ext  getfcp    ;reference
          call getfcp    ;obtain data
          jz   nofcpbuf  ;no FCP buffer is available
          mov  a,m       ;get first byte of buffer
          ora  a         ;set zero flag accordingly
          jz   nofcpload ;no FCP is in the buffer


Inputs: None


Outputs║ H╠ ╜ addres≤ oµ RC╨ buffer
               A=0 and Zero Flag Set (Z) if no buffer, else
               A=sizσ oµ buffe≥ iε 128-bytσ block≤ anΣ NZ


Registers Affected: HL, PSW


Side Effects: None


Special Error Conditions: None

:Shell Stack    GETSH1/GETSH2


Z3LIB Routine: GETSH1


Function:
     Returεá thσ addres≤ oµ thσ shel∞ stacδ iε HL¼á thσ sizσ ì
oµá eacΦ shel∞ stacδ entr∙ iε B¼á anΣ thσ numbe≥ oµá entrie≤ ì
possiblσ iε thσ shel∞ stacδ iε A«  A=░ anΣ Zer∩ Flaτ Se⌠ (Z⌐ ì
if there is no shell stack.

     Seσá thσ SHPUS╚ anΣ SHPO╨ routine≤ fo≥ detai∞ oεá othe≥ ì
facilitie≤ fo≥ dealinτ witΦ shel∞ stack≤ provideΣ b∙á Z3LIB«  ì
GETSH▒ serve≤ mainl∙ t∩ providσ data.


Inputs: None


Outputs: HL = address of Shell Stack
               B = number of bytes in each shell stack entry
               A = number of entries possible in the stack
                    A = 0 and Zero Flag Set (Z) if no stack



Registers Affected: HL, B, PSW


Side Effects: None


Special Error Conditions: None



Z3LIB Routine: GETSH2


Function:
     Returε thσ addres≤ oµ thσ shel∞ stacδ iε HL¼á thσá sizσ ì
oµá eacΦ shel∞ stacδ entr∙ iε DE¼á anΣ thσ numbe≥ oµ entrie≤ ì
possiblσ iε thσ shel∞ stacδ iε botΦ ┴ anΣ B«á  A=░ anΣá Zer∩ ì
Flaτ Se⌠ (Z⌐ iµ therσ i≤ n∩ shel∞ stack.

     Seσá thσá SHPUS╚á anΣ SHPO╨ routine≤á fo≥á othe≥á Z3LI┬ ì
capabilitie≤á wr⌠ shells«á  GETSH▓ serve≤ mainl∙ t∩á providσ ì
datß iε ß forφ tha⌠ i≤ morσ usablσ fo≥ certaiεá application≤ ì
thaε GETSH1.


Inputs: None


Outputs: HL = address of Shell Stack
              DE = number of bytes in each shell stack entry
             A,B = number of entries possible in the stack
                    A = 0 and Zero Flag Set (Z) if no stack



Registers Affected: HL, DE, B, PSW


Side Effects: None


Special Error Conditions: None


:Wheel Byte     GETWHL/PUTWHL


Z3LIB Routine: GETWHL


Function:
     Returε thσ Whee∞ Bytσ iε A«  A╜ ░ anΣ Zer∩ Flaτ Se⌠ (Z⌐ ì
iµ thσ prograφ i≤ NO╘ t∩ givσ Whee∞ powers¼ A=0FF╚ anΣ N┌ iµ ì
thσ prograφ i≤ t∩ ruε iε ß privelegeΣ mode.

     B∙ whee∞ operation¼á thσ prograφ i≤ no⌠ t∩ prohibi⌠ thσ ì
use≥ froφ performinτ an∙ function«á  Fo≥ instance¼á allowinτ ì
thσá use≥ t∩ changσ thσ PAT╚ shoulΣ bσ ß Whee∞á functioεá s∩ ì
tha⌠á thσá "normalóá use≥á i≤á no⌠á alloweΣá t∩á changσá hi≤ ì
environmen⌠ whilσ ß "privelegedó use≥ is.


Inputs: None


Outputs: A = Wheel Byte (0=not wheel) and Zero Flag set
               accordingly



Registers Affected: PSW


Side Effects: None


Special Error Conditions: None



Z3LIB Routine: PUTWHL


Function:
     Se⌠ thσ Whee∞ Bytσ iε A«  A╜ ░ anΣ Zer∩ Flaτ Se⌠ (Z⌐ iµ ì
thσá prograφ i≤ NO╘ t∩ givσ Whee∞ powers¼á A=0FF╚ anΣ N┌á iµ ì
thσ prograφ i≤ t∩ ruε iε ß privelegeΣ mode.


Inputs: A=Wheel Byte Value


Outputs: None


Registers Affected: None


Side Effects: Wheel Byte is Set


Special Error Conditions: None

:ZEX Data      GETZFC/GETZNC/GETZRUN


Z3LIB Routine: GETZFC


Function:
     GETZF├ return≤ thσ addres≤ iε H╠ oµ thσ firs⌠ characte≥ ì
iεá thσ ZE╪ tex⌠ buffer«á  Carr∙ Flaτ i≤ se⌠ iµ datß i≤á no⌠ ì
available.


Inputs: None


Outputs: HL = Address of First Character
               A = Character
               Carry Flag Set (C) if No Data


Registers Affected: HL, PSW


Side Effects: None


Special Error Conditions: None


Z3LIB Routine: GETZNC


Function:
     GETZN├á return≤ thσ addres≤ iε H╠ oµ thσ nex⌠ characte≥ ì
whicΦ ZE╪ wil∞ return«  Carr∙ Flaτ i≤ Se⌠ iµ n∩ data«  Reτ ┴ ì
contains the character.


Inputs: None


Outputs: HL = Address of Next Character in ZEX Text Buffer
               A = Next Character in ZEX Text Buffer
               Carry Flag Set (C) if no data


Registers Affected: HL, PSW


Side Effects: None


Special Error Conditions: None



Z3LIB Routine: GETZRUN


Function:
     GETZRU╬á return≤ thσ ZE╪ Ruε Messagσ Bytσ iεá A«á  Zer∩ ì
Flaτá i≤ se⌠ accordingly«á  Carr∙ Flaτ i≤ Se⌠ iµ n∩á messagσ ì
available«á  Thi≤ messagσ indicate≤ iµ ZE╪ i≤ runninτ o≥ no⌠ ì
(A=0 if not running).


Inputs: None


Outputs: A = ZEX Run Message
               Carry Flag Set (C) if no data


Registers Affected: PSW


Side Effects: None


Special Error Conditions: None



Z3LIB Routine: PUTZNC


Function:
     PUTZN├ set≤ thσ addres≤ oµ thσ nex⌠ characte≥ whicΦ ZE╪ ì
wil∞ returε t∩ tha⌠ containeΣ iε HL«á  Thi≤ routinσ provide≤ ì
a GOTO function for ZEX control.


Inputs: HL = address of next character ZEX will return


Outputs: Carry Flag Set (C) if data not available
               (Message Buffers not available)


Registers Affected: PSW


Side Effects: ZEX Next Character Address Message is set


Special Error Conditions: None



Z3LIB Routine: PUTZRUN


Function:
     PUTZRU╬ set≤ thσ ZE╪ Runninτ Messagσ bytσ t∩ thσá valuσ ì
iεá thσá ┴ register«á  Carr∙ Flaτ i≤ Se⌠ upoε returεá iµá n∩ ì
message≤á arσ supported«á  Thi≤ messagσ indicate≤ iµ ZE╪á i≤ ì
running¼ anΣ A=░ iµ ZE╪ i≤ no⌠ running.


Inputs: A=Value of ZEX Running Message Byte


Outputs: Carry Flag Set if no message buffers


Registers Affected: PSW


Side Effects: ZEX Running Message Byte is set


Special Error Conditions: None