Introduction   ZCPR3 Utilities
DIRTDU/DUTDIR  
Named Directory/Disk User Conversion
DNSCAN et al   
Resolve Directory References
PARSER         
Parse Command Line
PFIND          
Search for File Along Path
PRGLOAD        
Program Loader (Chain)
PUTCL          
Store a Command Line
Qxxx           
Output Routines Based on the Quiet Flag
ROOT           
Locate ROOT Directory in Path
SHxxx          
Shell Stack Manipulation Routines
WAITs          
Delay Routines
Z3LOG          
Log into ZCPR3 FCB DU
Z3LVER         
Return Z3LIB.REL Version Number
ZPRSFN/ZFNAME  
Parse Token
:Introduction to ZCPR3 Utilities

     Thes堠 utilitie� provid� � numbe� o栠 convenien� �
function� fo� th� ZCPR�� Syste�� Programmer��  Acces� t� �
directories�� conversio� fro� tex� strin� name� t� director� �
referenc� values�� comman� an� comman� lin� parsing�� quie� �
outpu� routines�� shel� stac� manipulation�� dela� routines� �
and other ZCPR3-specific functions are provided.

:DIRTDU/DUTDIR


Z3LIB Routine:  DIRTDU


Function:
     DIRTD� convert� th� DI� nam� pointe� t� b� H� int� it� �
Dՠ equivalent��  Th� DI� nam� i� � strin� o� u� t� eigh� �
ASCIɠ characters�� an� it� en� i� denote� b�� � delimite� �
whic� i� an�� ASCIɠ characte� tha� i� no� � digi�� o� � �
letter� 


Inputs: HL = address of first character of DIR name


Outputs: If match found, BC = DU (disk A = 0) and NZ
          If no match, A=0 and Zero Flag Set (Z)
          H� alway� point� t� th� delimite� a� th� en� of
               name


Registers Affected: HL, BC, PSW

Side Effects: None

Special Error Conditions: None


Z3LIB Routine: DUTDIR


Function:
     DUTDI� searche� th� name� director� fo� th� D� give� i� �
B� (B=dis� wit� dis� � � 0� C=user)�  I� a� entr� exist� fo� �
th� correspondin� DU�� DUTDI� return� � pointe� i� H� t� th� �
8-characte� nam� (followe� b� a� 8-characte� password).


Inputs: BC = DU (disk A = 0)


Outputs: If found, A=0FFH and NZ and HL = pointer to name
               If not found, A=0 and Zero Flag is Set


Registers Affected: HL and PSW


Side Effects: None


Special Error Conditions: None
:DNSCAN/DUSCAN/DIRSCAN


Z3LIB Routine: DNSCAN


Function:
     DNSCAРscan� fo� � resolutio� o� th� director�� nam� �
pte� t� b� HL��  Th� dis� nam� i� a� mos� eigh�� character� �
lon� and�� i� les� tha� eigh� characters� i� terminate� b� � �
delimite� suc� a� � space�� � characte� les� tha� space�� � �
comma�� � period� � dash� etc�  I� found� th� D� i� returne� �
i� BC.  Both DIR and DU forms are resolved by this routine.


Inputs: HL = address of first character of directory name
               A = Flag:
                    A=0 if scan DU before DIR
                    A<>0 if scan DIR before DU



Outputs: BC = DU (disk A = 0) if found
               A = Return Code:
                    A=� an� Zer� Fla� Se� (Z� i� no� valid
                    A=0FFH and NZ if valid and BC=DU


Registers Affected: BC, PSW


Side Effects: None


Special Error Conditions: None



Z3LIB Routine: DUSCAN


Function:
     DUSCAРresolve� th� D� for� pte� t� b�� HL��  Th� D� �
strin� i� store� i� � buffe� u� t� eigh�� character� long� �
an� i� i� terminate� b� � delimiter� whic� ma� b� an� o� th� �
following bytes:

          a character of value space or less
          an equal sign (=)
          an underscore (_)
          a period (.)
          a colon (:)
          a comma (,)
          a less-than sign (<)
          a greater-than sign (>)



Inputs: HL = address of first char


Outputs: A=0FFH, NZ, and BC=DU (disk A = 0) if valid
               A=0 and Zero Flag Set (Z) if not valid


Registers Affected: BC, PSW


Side Effects: None


Special Error Conditions: None



Z3LIB Routine: DIRSCAN


Function:
     DIRSCAРresolve� th� DI� for� pte� t� b� HL��  Th� DI� �
strin� i� store� i� � buffe� u� t� eigh�� character� long� �
an� i�� i� terminate� b� � delimite� i� i� i� unde� eigh� �
character� long� whic� ma� b� an� o� th� followin� bytes:

          a character of value space or less
          an equal sign (=)
          an underscore (_)
          a period (.)
          a colon (:)
          a comma (,)
          a less-than sign (<)
          a greater-than sign (>)



Inputs: HL = address of first char


Outputs: A=0FFH, NZ, and BC=DU (disk A = 0) if valid
               A=0 and Zero Flag Set (Z) if not valid


Registers Affected: BC, PSW


Side Effects: None


Special Error Conditions: None

:PARSER


Z3LIB Routine: PARSER


Function:
     PARSE� perform� � complet� pars� o� th� comman� pointe� �
t� b� H� (th� comman� i� � strin� terminate� b� � binar�� � �
o� a� MC� delimiter�� � semicolo� [;])�  Al� element� o� th� �
comman� lin� ar� parse� a� thoug� th� ZCPR� C� wer� parsin� �
th� line.

     Th� followin� buffer� ar� initialize� a� pe� th� ZCPR� �
CP conventions:
          FCB1 (at 5CH)
          FCB2 (at 6CH)
          TBUFF (at 80H)

     The command name is returned in an FCB pted to by DE.



Inputs: HL = address of command
               A = 0 if DIR form scanned before DU
               A <> 0 if DU form scanned before DIR


Outputs: HL = address of next command (0 or leading ;)
               DE = address of FCB with command name
                    (verb.COM)
               A = Flag:
                    A=0 and Zero Flag Set (Z) if OK
                    A=number of question marks and NZ if
                         verb contains one or more ? chars


Registers Affected: HL, DE, PSW


Side Effects: Buffers Altered


Special Error Conditions: None

:PFIND


Z3LIB Routine: PFIND


Function:
     PFIN� searche� fo� th� fil� specifie� i� th� targe� FC� �
alon� th� ZCPR� comman� searc� path�  I� found� th� D� i� i� �
located in is returned.


Inputs: DE = Address of FCB
               A=0 if search current directory
               A<>0 if no search of current directory


Outputs: BC = DU (disk A = 0)
               A=0 and Zero Flag Set (Z) if not found
               A=0FFH and NZ if found


Registers Affected: BC, PSW

Side Effects: FCB is affected

Special Error Conditions: None

:PRGLOAD


Z3LIB Routine: PRGLOAD


Function:
     PRGLOAĠ load� th� progra� indicate� b� th� firs�� 1� �
byte� pointe� t� b� D� int� memor� a� 100Ƞ an� transfer� �
contro� t� it��  I� i� � chai� function�  Th� loade� an� FC� �
use� fo� th� loa� ar� relocate� t� jus� unde� th� CР afte� �
PRGLOAĠ begin� execution�� s� th� TP� i� fre� fo� th� load�  �
Car� shoul� b� take� t� ensur� tha�� th� syste�� stac� �
(locate� ou� o� th� TP� i� � saf� area� i� use� instea� o� �
som� stac� i� th� TP� whic� ma� b� overwritte� durin� th� �
load.

�     I� PRGLOAĠ return� fro� bein� called�� a� erro� i� �
loadin� occurred��  I� al� goe� well�� th� loade� progra� �
executes successfully.



Inputs: DE pts to first 12 bytes of FCB


Outputs: None


Registers Affected: All (if PRGLOAD returns, load was a
                         failure)


Side Effects: None


Special Error Conditions: None


:PUTCL


Z3LIB Routine: PUTCL


Function:
     PUTC̠ store� � comman� lin� a� � prefi� i� th� ZCPR� �
comman� lin� buffer��  Th� buffe� content� ar� repacke� s� �
tha�� a� overflo� i� averte� i� mos� cases��  I� � comman� �
alread� exist� i� th� buffer� th� ne� lin� i� postfixe� wit� �
a semicolon so continuation is enabled.


Inputs: HL = Address of command line (ending in 0)


Outputs: A=0 and Zero Flag Set (Z) if overflow (no change
               to command line in this case)
               A = 0FFH and NZ if OK


Registers Affected: PSW

Side Effects: Command Line Buffer is modified

Special Error Conditions: None

:Qxxxx

     Thes� routine� outpu� thei� value� onl� i� th� Quie� �
Fla� i� clea� (0)��  I� th� Quie� Fla� i� TRU� (no� 0)� the� �
no values are output.

     This class of routines includes the following:

          QCOUT     Console Character Output with Control
          QCRLF     New Line
          QOUT      Console Character Output
          QPRINT    String Output (Return Address)
          QPSTR     String Output (HL)



Z3LIB Routine: QCOUT


Function:
     QCOU� output� th� characte� i� � wit� contro� characte� �
processing (1 outputs as ^A) if the Quiet Flag is OFF (0).


Inputs: A=Character


Outputs: None


Registers Affected: None


Side Effects: Character(s) is printed


Special Error Conditions: None



Z3LIB Routine: QCRLF


Function:
     QCRL� output� � Ne� Lin� (C� L� pair� i� th� Quie� Fla� �
is OFF (0).


Inputs: None


Outputs: None


Registers Affected: None


Side Effects: CRLF is Output


Special Error Conditions: None



Z3LIB Routine: QOUT


Function:
     QOUԠ output� th� characte� i� �� withou��� contro� �
characte� processin� (� output� a� 1� i� th� Quie� Fla� i� �
OFF (0).


Inputs: A=character to output


Outputs: None


Registers Affected: None


Side Effects: Character is output


Special Error Conditions: None



Z3LIB Routine: QPRINT


Function:
     QPRIN� output� th� string� terminate� b� � binar� 0� a� �
th� retur� addres� i� th� Quie� Fla� i� OF� (0)�  Contro� i� �
returned to the byte following the string.


Inputs: None (String at Return Address)


Outputs: None


Registers Affected: None


Side Effects: String is output


Special Error Conditions: None



Z3LIB Routine: QPSTR


Function:
     QPSTҠ output� th� string�� terminate� b� � binar�� 0� �
pted to by HL if the Quiet Flag is OFF (0).


Inputs: HL = address of first character of the string


Outputs: None


Registers Affected: None


Side Effects: String is output


Special Error Conditions: None

:ROOT


Z3LIB Routine: ROOT


Function:
     ROOԠ return� th� D� i� B� (dis� � � 0�� o� th� las� �
director� i� th� comman� searc� path��  N� pat� optimizatio� �
i� performed��  Thi� routin� provide� � convenien� wa�� t� �
fin� th� ROO� directory�� wher� thi� director� i� th� las� �
directory referenced in a path expression.

     Thi� routin� i� sometime� no� consisten� wit� th� ZCPR� �
CРi� th� MINPAT� (Minimiz� Pat� Expression�� optio� i� �
selected�  ROO� advance� t� th� las� reference� director� i� �
th� pat� withou� minimization�� whic� ZCPR�� minimize� th� �
searc蠠 an䠠 ma�� resolv� � pat� t terminat堠 (wit� �
duplication�� a� � director� othe� tha� th� physicall�� las� �
directory in the path.



Inputs: None


Outputs: BC = DU (Disk A = 0)


Registers Affected: BC, PSW


Side Effects: None


Special Error Conditions: None

:SHxxx

     Thi� se� o� routine� support� Shel� Stac� manipulation�  �
The following routines are provided:

          SHEMPTY - test to see if Shell Stack is empty
          SHFULL  - test to see if Shell Stack is full
          SHPOP   - pop top string off of Shell Stack
          SHPUSH  - push string onto Shell Stack

     �� Shel� Stac� i� implemente� a� � serie� o� string� �
(recommende� siz� i� 3� bytes/string�� an� th� stac� shoul� �
contai� a� leas� fou� o� thes� strings)�  Th� to� elemen� o� �
� Shel� Stac� specifie� th� comman� lin� t� b� execute� a� � �
Shel� b� th� ZCPR� CP�  Thi� comman� lin� i� copie� int� th� �
Multiple Command Line Buffer for execution.



Z3LIB Routine: SHEMPTY


Function:
     SHEMPT� determine� i� th� shel� stac� i� empty��  I� i� �
i� empt� o� n� shel� stac� i� available�� A=0� i� no� empty� �
A<>0.


Inputs: None


Outputs: A=0 and Zero Flag Set (Z) if empty or none
               A<>0 and NZ if not empty


Registers Affected: PSW


Side Effects: None


Special Error Conditions: None



Z3LIB Routine: SHFULL


Function:
     SHFUL̠ determine� i� th� shel� stac� i� full��  I� th� �
stac� i� ful� o� no� available�� A=0�� else� i� th� stac� i� �
not full, A<>0.


Inputs: None


Outputs: A=0 and Zero Flag Set (Z) if stack full or none
               A<>0 if stack not full


Registers Affected: PSW


Side Effects: None


Special Error Conditions: None



Z3LIB Routine: SHPOP


Function:
     SHPOР pop� th� to� elemen� of� o� th� Shel� Stac� an� �
discard� i� i� possible��  SHPO� return� wit� A=� i� po� wa� �
successful�� els� A<>0��  Th� followin� erro� code� ar� �
returned:

          A=1 if no Shell Stack available
          A=2 if Shell Stack is empty


Inputs: None


Outputs: A=Code:
               A=0 if success (and Zero Flag Set - Z)
               A=1 if no Shell Stack available (NZ)
               A=2 if Shell Stack empty (NZ)



Registers Affected: PSW


Side Effects: String is popped from Shell Stack


Special Error Conditions: None



Z3LIB Routine: SHPUSH


Function:
     SHPUS� pushe� th� strin� (includin� th� endin� 0�� pte� �
t� b� H� ont� th� Shel� Stac� i� possible��  SHPUS� return� �
with A=0 if successful, else A<>0.


Inputs: HL = string to push onto Shell Stack (end in 0)


Outputs: A=Return Code:
               A=0 if successful and no error (Z)
               A=1 if no Shell Stack available (NZ)
               A=2 if Shell Stack is full (NZ)
               A=3 if string is too long for Shell Stack
                   entry (NZ)


Registers Affected: PSW

Side Effects: String is pushed onto Shell Stack

Special Error Conditions: None
:WAITs

     Th� followin� routine� provid� � softwar� dela�� base� �
upo� th� processo� spee� valu� i� th� ZCPR�� Environmen� �
Descriptor��  Thes� routine� simpl� dela� fo� th� indicate� �
perio䠠 o� tim� (approximately�� an� the� return���  N� �
registers are affected.

     The routines are:

          WAIT1S    - delay for 1 second
          WAIT1MS   - delay for 0.001 second
          WAITP1S   - delay for 0.1 second



Z3LIB Routine: WAIT1S


Function:
     WAIT1S delays for approximately 1 second.


Inputs: None


Outputs: None


Registers Affected: None


Side Effects: A 1-second delay takes place


Special Error Conditions: None



Z3LIB Routine: WAIT1MS


Function:
     WAIT1MӠ delay� fo� approximatel� � millisecon� (0.00� �
second).


Inputs: None


Outputs: None


Registers Affected: None


Side Effects: A 1-millisecond delay takes place


Special Error Conditions: None



Z3LIB Routine: WAITP1S


Function:
     WAITP1Ӡ delay� fo� approximatel� on� tent� (0.1� o� � �
second.


Inputs: None


Outputs: None


Registers Affected: None


Side Effects: A 0.1-second delay takes place


Special Error Conditions: None

:Z3LOG


Z3LIB Routine: Z3LOG


Function:
     Z3LO� log� int� th� D� containe� i� � ZCPR� FCB��  Thi� �
FC  contain� th� dis� referenc� i� Byt� � an� th� Use� Are� �
i� Byt� 1� (S1)��  Thi� i� th� standar� forma� use� b� ZCPR� �
to store a complete DU reference in an FCB.


Inputs: DE = First Byte of FCB


Outputs: None


Registers Affected: None


Side Effects: Directory is logged into


Special Error Conditions: None

:Z3LVER


Z3LIB Routine: Z3LVER


Function:
     Retur� Versio� Numbe� o� Z3LIB.REL�  H=Majo� Version� � �
= Minor Version.  Numbers are in pure binary.


Inputs: None


Outputs: HL = Version Number (H=Major, L=Minor)


Registers Affected: HL


Side Effects: None


Special Error Conditions: None

�:ZPRSFN


Z3LIB Routine: ZPRSFN/ZFNAME


Function:
     ZPRSFΠ i� � complet� FC� toke� parse� i� th� sens� o� �
th� ZCPR� C� (se� PARSER�� whic� i� related)��  O� input� H� �
point󠠠 t� ᠠ� token����� lik堠�� 'dir:filename.typ'� �
'du:filename.typ'��� 'filename.typ'��� etc��� an� � ZCPR3-�
identica� pars� i� performe� o� th� token��  Th� resultin� �
FC� contain� th� filenam� an� ty� an� � prope� D� reference.

     ZFNAMŠ i� � litera� interpretatio� o� th� cod� withi� �
th� ZCPR� CP��  ZPRSF� i� � mor� efficien� bod� o� cod� bu� �
use� mor� buffe� space.


Inputs: HL = address of first char of token
               DE = address of 36-byte FCB
               A = Flag:
                    A = 0 if scan for DIR form before DU
                    A = 1 if scan for DU form before DIR



Outputs: HL = address of char after token
               A = number of question marks in filename.typ
                    and Zero Flag set accordingly


Registers Affected: HL, PSW


Side Effects: FCB is loaded


Special Error Conditions: None