CP/M/CPM_CDROM.iso/jsage/zsus/progpack/v42-docs.lbr/Z3LIB42.DZC/Z3LIB42.DOC

Text File | 1990-06-08 | 121.3 KB | 2,589 lines

.hm1
.fm1
.sr0
.he                                ZCPR3: THE LIBRARIES 4.2 -- Z3LIB
.fo                                                           Page #
.pn 85

         II«  Z3LI┬ -¡ ZCPR│ Suppor⌠ anΣ Acces≤ Routines

     Introductioε « « « « « « « « « « « « « « « « « « « « « «  87
          ExtendeΣ Environmen⌠ Descriptioε  « « « « « « « « «  87
     Acces≤ t∩ thσ ZCPR│ Environmen⌠  « « « « « « « « « « « «  90
          Command Linσ  « « « « « « « « « « « « « « « « « « «  91
               APPCL¼ CLRCL¼ GETCL1¼ GETCL2¼ PUTCL
          CR╘ anΣ PRT Datß  « « « « « « « « « « « « « « « « «  92
               GETCRT¼ GETPRT¼ PUTCRT¼ PUTPRT
          External Filσ Contro∞ Blocδ « « « « « « « « « « « «  94
               GETEFCB
          Environmen⌠ « « « « « « « « « « « « « « « « « « « «  94
               GETENV¼ GETVID
          Flo≈ Command Packagσ (FCP) Addres≤  « « « « « « « «  95
               GETFCP
          Filename≤ « « « « « « « « « « « « « « « « « « « « «  95
               GETFN1, GETFN2¼ GETFNX¼ PUTFNX
          ╔nitializσ  « « « « « « « « « « « « « « « « « « « «  96
               WHRENV¼ Z3INIT
          System Datß « « « « « « « « « « « « « « « « « « « «  97
               ZSYSCHK¼ Z33CHK¼ GETBDOS¼ GETCCP¼ GETECP
          Input-Outpu⌠ Packagσ (IOP) Concept≤ « « « « « « « «  99
               GETION¼ GETIOP¼ GETIOS¼ IOMATCH¼ PUTIOD
          Input-Outpu⌠ Packagσ (IOP) Recordinτ  « « « « « « « 101
               IORCOFF, IORCON, IORLOFF, IORLON
          Drive/Use≥  « « « « « « « « « « « « « « « « « « « « 101
               GETDUOK¼ GETMDISK¼ GETMUSER¼ PUTDUOK,
               PUTMDISK¼ PUTMUSER¼ HIGHUSER¼ GCMDDU
          Message≤  « « « « « « « « « « « « « « « « « « « « « 103
               GETMSG¼ GETSHM¼ PUTSHM
          Named Directorie≤ « « « « « « « « « « « « « « « « « 104
               ADDNDR¼ DIRNDR¼ DUNDR¼ GETNDR¼ SUBNDR
          PatΦ  « « « « « « « « « « « « « « « « « « « « « « « 106
               GETPATH
          Processor SpeeΣ « « « « « « « « « « « « « « « « « « 106
               GETSPEED¼ PUTSPEED
          Quiet Flaτ  « « « « « « « « « « « « « « « « « « « « 107
               GETQUIET¼ PUTQUIET
          Residen⌠ CommanΣ Packagσ (RCP) Addres≤  « « « « « « 107
               GETRCP
          Shell Stacδ « « « « « « « « « « « « « « « « « « « « 108
               GETSH1¼ GETSH2
          Wheel Bytσ  « « « « « « « « « « « « « « « « « « « « 108
               GETWHL¼ PUTWHL
     Flo≈, ZE╪¼ anΣ SUBMIT Contro∞  « « « « « « « « « « « « « 109
          Flow Contro∞  « « « « « « « « « « « « « « « « « « « 109
               IFEND¼ IFT, IFF¼ IFTEST¼ IFELSE
          ZEX Access and Contro∞  « « « « « « « « « « « « « « 111
               ZEX Datß « « « « « « « « « « « « « « « « « « « 112
                    GETZFC¼ GETZNC¼ GETZRUN¼ PUTZNC¼ PUTZRUN
               ZEX Status and Contro∞ « « « « « « « « « « « « 113
                    GETZEX¼ PUTZEX¼ HALTZEX¼ STOPZEX¼ STRTZEX
.pa
è          SUBMIT and XSUB Contro∞ « « « « « « « « « « « « « « 114
               SUBMIT Data and Contro∞  « « « « « « « « « « « 115
                    SUBON¼ HALTSUB¼ GETSRUN¼ GETSFCB
               XSUB Data and Contro∞  « « « « « « « « « « « « 116
                    STOPXSUB¼ GXSUB¼ PXSUB
     ZCPR3 Message≤ « « « « « « « « « « « « « « « « « « « « « 116
          Command Status Messagσ  « « « « « « « « « « « « « « 118
               GETCST¼ PUTCST¼ QERROR¼ QSHELL
          Error Flag and Error CommanΣ  « « « « « « « « « « « 119
               ERRADR¼ GETER1¼ PUTER1¼ GETERC¼ PUTERC
          Inter-Transient Error Codσ  « « « « « « « « « « « « 121
               GETER2¼ PUTER2
          Command Error Flag and Handle≥  « « « « « « « « « « 121
               GETER3¼ PUTER3¼ INVERROR
          Command Status Flaτ « « « « « « « « « « « « « « « « 122
               SETEPB¼ RESEPB¼ RETCST
          Register Acces≤ « « « « « « « « « « « « « « « « « « 123
               GETREG¼ PUTREG
          Default Drive/User Buffe≥ « « « « « « « « « « « « « 124
               GDEFDU¼ PDEFDU
     ZCPR│ Utilitie≤  « « « « « « « « « « « « « « « « « « « « 124
          Named Directory-Drive/User Conversioε « « « « « « « 124
               DIRTDU¼ DUTDIR
          Resolve Directory Reference≤  « « « « « « « « « « « 125
               DNSCAN¼ DUSCAN¼ DIRSCAN
          Parse Command Linσ  « « « « « « « « « « « « « « « « 126
               PARSER
          Path Search for Filσ  « « « « « « « « « « « « « « « 126
               PFIND
          Program Loading (Chaining⌐  « « « « « « « « « « « « 126
               PRGLOAD
          Console Quie⌠ Outpu⌠  « « « « « « « « « « « « « « « 127
               QCOUT¼ QCRLF¼ QOUT¼ QPRINT¼ QPSTR
          Locate ROOT Director∙ « « « « « « « « « « « « « « « 128
               ROOT
          Shell Stack Routine≤  « « « « « « « « « « « « « « « 128
               SHEMPTY¼ SHFULL¼ SHPOP¼ SHPUSH
          Delay Routine≤  « « « « « « « « « « « « « « « « « « 129
               WAIT1S¼ WAIT1MS¼ WAITP1S
          Log into ZCPR3 Filσ Contro∞ Block Drive/Use≥  « « « 130
               Z3LOG
          Return Z3LIB Versioε  « « « « « « « « « « « « « « « 130
               Z3LVER
          Parse Tokeε « « « « « « « « « « « « « « « « « « « « 131
               ZPRSFN, ZFNAME
          ZCPR 3.3 Parser≤  « « « « « « « « « « « « « « « « « 131
               Z33FNAME¼ PARSE2¼ REPARSE¼ SCAN
          Check ZCP╥ 3.3 Parse Result≤  « « « « « « « « « « « 132
               FCB1CHK, FCB2CHK¼ FCBCHK
          Print Load Module Datß  « « « « « « « « « « « « « « 133
               PRTTYPE
          ZCP╥ 3.3 Internal Program Namσ  « « « « « « « « « « 133
               GETNAME¼ PRTNAME
          Highest Useable Memor∙  « « « « « « « « « « « « « « 134
               GZMTOP
è.pa

           Z3LI┬ -¡ ZCPR│ Suppor⌠ anΣ Acces≤ Routines


INTRODUCTION:é á Z3LI┬ ácontain≤ suppor⌠ utilitie≤ áwhicΦ áprovidσ ì
acces≤ t∩ ZCPR│¡ specifiπ feature≤ anΣ capabilities«  Z3LI┬ árouì
tine≤ caε bσ divideΣ int∩ fou≥ categories:

     1.ZCPR│ áEnvironmen⌠ Acces≤ ¡¡ Utilitie≤ enablinτ áyo⌡ át∩ ì
áááááeasil∙ áextrac⌠ datß froφ thσ Z│ Environmen⌠ Descripto≥ áanΣ ì
ááááámodif∙ certaiε Z│ environmen⌠ parameters.

     2.ZCPR│ áFlo≈ Contro∞ ¡¡ Utilitie≤ allowinτ yo⌡ t∩ áeasil∙ ì
ááááámanipulatσ áZCPR3'≤ Flo≈ Contro∞ environmen⌠ b∙ áraisinτ áo≥ ì
ááááálowerinτ áthσ curren⌠ I╞ leve∞ anΣ togglinτ thσ ácurren⌠ áI╞ ì
ááááácondition.

     3.ZCPR│ áMessage≤ ¡¡ Utilitie≤ providinτ acces≤ át∩ áZCPR│ ì
ááááámessages¼ enablinτ program≤ t∩ reaΣ anΣ writσ message≤ áfroφ ì
áááááanΣ t∩ thσ system.

     4.ZCPR│ áUtilitie≤ á¡¡ Utilitie≤ whicΦ árelievσ áyo⌡ áfroφ ì
áááááconstantl∙ reprogramminτ somσ commonl∙-useΣ ZCPR│ features.

EXTENDE─ áENVIRONMEN╘ DESCRIPTION:é  Versioε ┤ oµ áZ3LI┬ áincorpoì
rate≤ áman∙ áenhanceΣ function≤ developeΣ b∙ Joσ Wrigh⌠ áanΣ áJa∙ ì
Sagσ iε NZCO═ anΣ ZCPR3│ anΣ 34«  Duσ t∩ redefinitioε oµ somσ áoµ ì
thσ ábyte≤ iε thσ Environmen⌠ Descriptor¼ ß fe≈ oµ áthσ áorigina∞ ì
module≤ áwil∞ no⌠ perforφ a≤ originall∙ intended« á Fo≥ áexample¼ ì
onl∙ onσ consolσ (CR╘ device⌐ i≤ supported«  Thσ remaininτ áspacσ ì
iε thσ EN╓ contain≤ vector≤ t∩ systeφ segments.

Somσ program≤ sucΦ a≤ Plu*Perfec⌠ Systemsº JETLD╥ anΣ Alphß áSysì
temsº NZCO═ se⌠ aε existinτ Environmen⌠ Descripto≥ t∩ reflec⌠ thσ ì
necessar∙ áextendeΣ ádefinitions«  Iµ yo⌡ d∩ áno⌠ ároutinel∙ áusσ ì
eithe≥ áoµ thesσ products¼ yo⌡ shoulΣ creatσ ß ne≈ áSYS.EN╓ áfilσ ì
fo≥ usσ witΦ you≥ existinτ ZCPR│ system«  Thσ ne≈ definition≤ arσ ì
markeΣ áwitΦ aε asterisδ (*⌐ iε thσ followinτ sourcσ codσ ásamplσ ì
Environmen⌠ Descriptor.


     ; Library:  NZENV.LIB
     ; Author:   Joe Wright
     ; Version:  1.0
     ; Date:     29 Nov 87

     ; Adapted from Rick Conn's original SYSENV.LIB circa 1984

     Z3ENV║    J╨        CBIOS+╢   ;* Real BIOS Addr (+6) for your
                                   ╗  system (* Was JP 0 *)
               DEF┬      'Z3ENVº   ; Environment ID
               DEF┬      80╚       ;* Extended Env shown by Bit 7

               DEF╫      EXPAT╚    ; External Path address
               DEF┬      EXPATH╙   ; # of 2-byte elements in Path

è               DEF╫      RC╨       ; RCP address
               DEF┬      RCP╙      ; # of 128-byte blocks in RCP

               DEF╫      IO╨       ; IOP address
               DEF┬      IOP╙      ; # of 128-byte blocks in IOP

               DEF╫      FC╨       ; FCP address
               DEF┬      FCP╙      ; # of 128-byte blocks in FCP

               DEF╫      Z3NDI╥    ; NDR address
               DEFB      Z3NDIRS   ; # of 18-byte entries in NDR

               DEFW      Z3CL      ; ZCPR3 Command Line
               DEFB      Z3CLS     ; # of bytes in Command Line

               DEFW      Z3ENV     ; ZCPR3 Environment Descriptor
               DEFB      Z3ENVS    ; # of 128-byte blks in ENV

               DEFW      SHSTK     ; Shell Stack address
               DEFB      SHSTKS    ; # SHSIZE-byte entries in Stk
               DEFB      SHSIZE    ; Size of a Shell Stack entry

               DEFW      Z3MSG     ; ZCPR3 Message Buffer

               DEFW      EXTFCB    ; ZCPR3 External FCB

               DEFW      EXTSTK    ; ZCPR3 External Stack

               DEFB      0         ; Quiet flag (0=not quiet)

               DEFW      Z3WHL     ; Address of Wheel Byte

               DEFB      4         ; Processor Speed in MHz

               DEFB      'P'-'@'   ; Maximum Disk
               DEFB      31        ; Maximum User
               DEFB      1         ; 1=Ok to accept DU:, 0=Not Ok

               DEFB      0         ;* CRT Selection   (* Unused *)
               DEFB      0         ; Printer Sel (only 0 or 1)

               DEFB      80        ; Width of CRT 0
               DEFB      24        ; Number of lines on CRT 0
               DEFB      22        ; Number of text lines on CRT 0

     ; CRT 1 descriptor is replaced with this valid drive vector.
     ; The command processor ignores 'maximum disk' above, and uses
     ; this vector instead.  This allows 'holes' in the disk map.
     ; A user might have drives A, B, E, F, and G for example.  In
     ; this case, his vector would look like:
     ;    DEFW 0000000001110011B
     ; The command processor will treat drive C the same as drive H
     ; (unavailable) and take appropriate action.

               DEFW      1111111111111111B ;* Valid drive vector (16)
è               DEFB      0         ;* Not used

               DEFB      80        ; Width of Printer 0
               DEFB      66        ; Number of lines on Printer 0
               DEFB      58        ; Number of text lines on Ptr 0
               DEFB      1         ; H/W Form Feed (0=can't,1=can)

               DEFB      102       ; Width of Printer 1
               DEFB      66        ; Number of lines on Printer 1
               DEFB      58        ; Number of text lines on Ptr 1
               DEFB      1         ; H/W Form Feed (0=can't,1=can)

     ;* Descriptors for Printers 2 and 3 replaced with System Data

               DEFW      CCP       ;* ZCPR 3.x start loc'n       3FH
               DEFB      CCPS      ;* Size in records            41H

               DEFW      DOS       ;* DOS starting location      42H
               DEFB      DOSS      ;* Size in records            44H

               DEFW      BIOS      ;* NZBIO starting location    45H

               DEFB      'SH      ' ; Shell Variable Filename
               DEFB      'VAR'     ; Shell Variable Filetype

               DEFB      '        ' ; Filename 1
               DEFB      '   '     ; Filetype 1

               DEFB      '        ' ; Filename 2
               DEFB      '   '     ; Filetype 2

               DEFB      '        ' ; Filename 3
               DEFB      '   '     ; Filetype 3

               DEFB      '        ' ; Filename 4
               DEFB      '   '     ; Filetype 4

               DEFB      0         ;* Public drive OFF           7EH
               DEFB      0         ;* Public user OFF            7FH
                                   ;  (* Only defined for ZRDOS *)

     ; This dummy Terminal Capabilities description (Z3TCAP) will
     ; normally be replaced with a tailored MYTERM.Z3T on start up.

     ENVORG2:  DEFB      '               ' ; Terminal Name (15 chars)
               DEFB      0         ; No terminal attributes
               DEFB      'E'-'@'   ; Cursor Up
               DEFB      'X'-'@'   ; Cursor Down
               DEFB      'D'-'@º   ; Cursor Right
               DEFB      'S'-'@'   ; Cursor Left
               DEFB      0         ; Cl delay
               DEFB      0         ; Cm delay
               DEFB      0         ; Ce delay
               DEFB      0         ; Cl string
               ─EFB      0         ; Cm string
è               DEFB      0         ; Ce string
               DEFB      0         ; So string
               DEFB      0         ; Se string
               DEFB      0         ; Ti string
               DEFB      0         ; Te string

     ; File filled with Zeros to end of 128-byte segment

ACCES╙ T╧ TH┼ ZCPR│ ENVIRONMENT:é  An∙ prograφ runninτ unde≥ ZCPR│ ì
i≤ áwithiε áß ZCPR│ environment«  Man∙ facilitie≤ áanΣ ádatß áarσ ì
availablσ át∩ áthi≤ prograφ whicΦ t∩ no⌠ exis⌠ áfo≥ ánorma∞ áCP/═ ì
programs«  Fo≥ instance¼ ß prograφ runninτ unde≥ thσ ZCPR│ áenvΘì
ronmen⌠ can:
   o Find out what name it was invoked by
   o Acces≤ áß se⌠ oµ message≤ froφ ZCPR│ whicΦ tel∞ i⌠ ß ánumbe≥ ì
áááááoµ thing≤ abou⌠ ho≈ i⌠ wa≤ invoked
   o SenΣ message≤ t∩ ZCPR│ anΣ program≤ whicΦ ruε afte≥ i⌠ ácomì
ááááápletes
   o FinΣ áou⌠ áman∙ thing≤ abou⌠ it≤ environment¼ ásucΦ áa≤ áthσ ì
áááááprocesso≥ áspeed¼ CR╘ anΣ printe≥ ácharacteristics¼ ámaximuφ ì
ááááánumbe≥ oµ disks
   o Determinσ thσ you≥ termina∞ characteristic≤ anΣ usσ theφ át∩ ì
áááááenhancσ áthσ displa∙ witΦ visua∞ attribute≤ sucΦ áa≤ ácurso≥ ì
áááááaddressinτ anΣ highlighteΣ text.

Thσ informatioε outlineΣ abovσ anΣ morσ i≤ availablσ t∩ an∙ áproì
graφ áthr⌡ thσ ZCPR│ Environmen⌠ Descriptor«  Thi≤ i≤ ß á25╢-bytσ ì
blocδ oµ memor∙ containinτ addresse≤ anΣ othe≥ datß iε ß preciseì
l∙-defineΣ format«  ZCPR│ utilitie≤ ma∙ bσ writteε witΦ aε interì
na∞ áEnvironmen⌠ áDescripto≥ o≥ the∙ ma∙ áacces≤ áaε áEnvironmen⌠ ì
Descripto≥ áresidinτ a⌠ somσ fixeΣ memor∙ locatioε (thi≤ ái≤ áthσ ì
preferreΣ approach)«  Wheε executed¼ program≤ caε extrac⌠ áspeciì
fiπ informatioε froφ thσ descripto≥ fo≥ use.

Thσ followinτ informatioε i≤ containeΣ withiε ß ZCPR│ Environmen⌠ ì
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 directory    size of named directory
     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 stack
     address of wheel byte         quiet flag
     processor speed               DU approval flag
     maximum disk allowed          maximum user allowed
     data on CRT                   data on printer
     two reserved filenames        ZCPR3 TERMCAP (Z3TCAP)

Thσ purposσ oµ Z3LI┬ i≤ t∩ providσ yo⌡ witΦ eas∙ acces≤ t∩ inforì
matioε áiε thσ ZCPR│ Environmen⌠ Descripto≥ anΣ t∩ allo≈ áyo⌡ át∩ ì
easil∙ áusσ thi≤ information«  T∩ illustrate¼ somσ oµ áthσ áZ3LI┬ ìèroutine≤ are:

   o GETPR╘ á¡¡ áreturε datß oε thσ width¼ numbe≥ oµ álines¼ áanΣ ì
áááááforφ feeΣ abilit∙ oµ thσ printer
   o GETCL▓ á¡¡ returε thσ addres≤ oµ thσ firs⌠ characte≥ oµ áthσ ì
ááááánex⌠ commanΣ t∩ bσ run¼ iµ any
   o GETEFC┬ á¡¡ áreturε thσ addres≤ oµ thσ externa∞ FC┬ ás∩ áthσ ì
áááááprograφ caε determinσ it≤ name
   o SHPUSH -- push a command line on the shell stack
   o SHPOP -- pop a command line from the shell stack
   o IFT -- invoke the next IF level and make it T
   o IFEND -- back up to previous IF level

Thi≤ filσ describe≤ thosσ Z3LI┬ routine≤ whicΦ providσ acces≤ át∩ ì
thσ áZCPR│ Environmen⌠ Descripto≥ data«  Man∙ oµ áthesσ ároutine≤ ì
arσ oµ thσ genera∞ name:
     GETxxxxx
wherσ áthσ mnemoniπ followinτ thσ GE╘ prefi° allude≤ t∩ wha⌠ áinì
formatioε i≤ beinτ obtained.

COMMAND LINE:

     Routine║  APPCL
     Function║ Append command string to command line buffer
     Entry║    HL = address of command string to append
     Exit║     A <> 0, zero flag clear (NZ) if append complete
               ┴ ╜ 0¼ zer∩ flaτ se⌠ (Z⌐ iµ buffe≥ overflow≤ o≥ n∩ ì
ááááááááááááááácommanΣ linσ buffe≥ (n∩ changσ t∩ commanΣ line)
     Affected║ AF╗ command line buffer is changed
     Usage:    Append≤ ááthσ áspecifieΣ áNU╠-terminateΣ áácommanΣ ì
ááááááááááááááástrinτ t∩ thσ enΣ oµ thσ ZCPR│ commanΣ linσ buffe≥ ì
áááááááááááááááfo≥ áexecution«  ┴ leadinτ semicoloε i≤ áprependeΣ ì
ááááááááááááááát∩ allo≈ thi≤ linσ t∩ executσ afte≥ thσ las⌠ álinσ ì
áááááááááááááááiε áthσ buffer«  Thσ commanΣ linσ buffe≥ ácontent≤ ì
áááááááááááááááarσ árepackeΣ át∩ aver⌠ overflo≈ áiε ámos⌠ ácases«  ì
áááááááááááááááPUTC╠ ái≤ áß complementar∙ functioε iε áwhicΦ áthσ ì
ááááááááááááááácommanΣ ástrinτ i≤ addeΣ t∩ thσ beginninτ áoµ áthσ ì
ááááááááááááááácommanΣ linσ buffe≥ a≤ thσ firs⌠ command.

     Routine║  CLRCL
     Function║ Clear the command line buffer
     Entry:    None
     Exit:     A <> 0, zero flag clear (NZ) if command line cleared
               A = 0, zero flag set (Z) if no command line buffer
     Affected: AF
     Usage:    Clear≤ áthσ commanΣ linσ buffe≥ b∙ settinτ ái⌠ át∩ ì
áááááááááááááááempty«  An∙ remaininτ command≤ iε thσ buffe≥ áwil∞ ì
áááááááááááááááno⌠ bσ executeΣ wheε contro∞ i≤ returneΣ t∩ ZCPR3.
.pa
è     Routine║  GETCL1
     Function║ Return pointer to command line buffer
     Entry:    None
     Exit:     H╠ ╜ addres≤ oµ commanΣ linσ buffe≥ (░ iµ nonexisì
ááááááááááááááátent)
               A = size of buffer
     Affected: AF¼ HL
     Usage:    Locate≤ áanΣ return≤ commanΣ linσ ábuffe≥ áparameì
áááááááááááááááters«  Thσ commanΣ linσ buffe≥ i≤ structureΣ as:

                    CMDLIN║   DEF╫      <address of next character to process>
                              DEF┬      <size of buffer in bytes>
                              DEFB      <dummy used for BDOS READLN function>
                              DEFB      <....chars in command line>
                              DEFB      0              ; end of command string

     Routine║  GETCL2
     Function║ Return next command info from command line buffer
     Entry:    None
     Exit:     H╠ ╜ addres≤ oµ nex⌠ commanΣ (░ iµ n∩ commanΣ linσ ì
ááááááááááááááábuffer)
               ┴ ╜ firs⌠ characte≥ oµ command¼ zer∩ clea≥ (NZ⌐ iµ ì
ááááááááááááááávalid
               A = 0, zero flag set (Z) if no characters in line
               Affected: AF¼ HL
     Usage:    UseΣ áiε application≤ wherσ yo⌡ neeΣ át∩ ádirectl∙ ì
áááááááááááááááacces≤ ácharacter≤ iε thσ nex⌠ commanΣ ástoreΣ áiε ì
áááááááááááááááthσ commanΣ linσ buffer.

     Routine║  PUTCL
     Function: Storσ ácommanΣ linσ a⌠ beginninτ oµ ácommanΣ álinσ ì
ááááááááááááááábuffer
     Entry:    HL = address of NUL-terminated command line
     Exit:     A <> 0, zero flag clear (NZ) if OK
               A = 0 zero set (Z) if overflow (no buffer change)
     Affected: AF
     Usage:    Add≤ ß commanΣ linσ a≤ ß prefi° iε thσ ZCPR│ ácomì
ááááááááááááááámanΣ linσ buffe≥ a≤ opposeΣ t∩ APPC╠ whicΦ append≤ ì
ááááááááááááááát∩ áthσ áenΣ oµ thσ commanΣ linσ ábuffer« á 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Φ ß semicoloε s∩ continuatioε i≤ enabled.

CR╘ AN─ PRT DATA:

     Routine║  GETCRT
     Function║ Return address of CRT data record from ENV
     Entry:    None
     Exit:     HL = address of CRT record
     Affected: HL
     Usage:    Determine≤ thσ parameter≤ oµ thσ installeΣ átermiì
ááááááááááááááánal«  Thσ CR╘ recorΣ i≤ structureΣ as:

                    CRTDAT║   DEF┬      8░        ; width of CRT in characters
                              DEFB      24        ; number of lines on the screen
                              DEFB      22        ; number of text lines on screen
è
               Thσ ánumbe≥ oµ tex⌠ line≤ shoulΣ bσ tw∩ les≤ áthaε ì
áááááááááááááááthσ átota∞ numbe≥ oµ lines«  Yo⌡ ma∙ providσ ámorσ ì
áááááááááááááááoverla≡ áb∙ ámakinτ i⌠ │ o≥ ┤ less« á Thi≤ árecorΣ ì
áááááááááááááááelemen⌠ átell≤ utilitie≤ likσ PAG┼ ho≈ man∙ áline≤ ì
ááááááááááááááát∩ outpu⌠ beforσ pausinτ t∩ allo≈ yo⌡ t∩ reaΣ áthσ ì
áááááááááááááááscreen« á Thi≤ ácaε ábσ reduceΣ (g∩ t∩ á2░ áo≥ á1╕ ì
ááááááááááááááálines⌐ át∩ áallo≈ áyo⌡ t∩ seσ ámorσ áoµ áthσ álas⌠ ì
áááááááááááááááscreen.

     Routine║  GETPRT
     Function║ Return the address of the printer data record
     Entry:    None
     Exit:     HL = address of printer data record
     Affected: HL
     Usage:    Provide≤ datß oε somσ oµ thσ printe≥ ácharacterisì
ááááááááááááááátic≤ áfo≥ áusσ iε formattinτ ároutines¼ áo≥ áothe≥ ì
áááááááááááááááuses« á Thσ returneΣ pointe≥ i≤ t∩ ß printe≥ ádatß ì
ááááááááááááááárecorΣ as:

                    PRTDAT║   DEF┬      8░        ; width of printer in characters
                              DEFB      66        ; number of lines on printer page
                              DEFB      58        ; number of text lines per page
                              DEFB      1         ; formfeed flag (0=can't FF, 1=can)

               Program≤ ásucΦ áa≤ PRIN╘ ma∙ áusσ áthσ ádifferencσ ì
ááááááááááááááábetweeε thσ thirΣ anΣ seconΣ entrie≤ t∩ ádeterminσ ì
áááááááááááááááto≡ anΣ bottoφ margins¼ anΣ tes⌠ thσ las⌠ bytσ át∩ ì
ááááááááááááááádeterminσ áwhethe≥ át∩ issuσ ß formfeeΣ áo≥ ácoun⌠ ì
ááááááááááááááálinσ feeΣ character≤ t∩ advancσ t∩ thσ nex⌠ page.

     Routine║  PUTCRT
     Function║ Stores terminal select byte (no real function)
     Entry:    A = selection value (0)
     Exit:     A <> 0, zero flag clear (NZ) if entry was 0
               A = 0, zero flag set (Z) if invalid (not 0)
     Affected: AF
     Usage:    Perform≤ n∩ actua∞ functioε iε thσ extendeΣ áenviì
áááááááááááááááronmen⌠ áwhicΦ support≤ onl∙ onσ defineΣ CR╘ ádatß ì
áááááááááááááááblock« á Fo≥ compatibility¼ i⌠ sense≤ áthσ áselec⌠ ì
ááááááááááááááávaluσ anΣ simpl∙ return≤ statu≤ baseΣ oε it.

     Routine║  PUTPRT
     Function║ Store printer selection byte (0..1) in environment
     Entry:    A = printer selection value (0 or 1)
     Exit:     A <> 0, zero flag clear (NZ) if OK
               A = 0, zero flag set (Z) if invalid (not 0 or 1)
     Affected: AF
     Usage:    Store≤ thσ selectioε (░ o≥ 1⌐ iε thσ PR╘ selectioε ì
ááááááááááááááábuffe≥ oµ thσ ZCPR│ Environmen⌠ Descripto≥ showinτ ì
ááááááááááááááátha⌠ ái⌠ i≤ thσ currentl∙ activσ áprinter« á Unde≥ ì
áááááááááááááááthσ extendeΣ environment¼ onl∙ tw∩ printer≤ ma∙ bσ ì
ááááááááááááááádefineΣ insteaΣ oµ thσ fou≥ originall∙ supported.
.pa
èEXTERNA╠ FIL┼ CONTRO╠ BLOCK:

     Routine║  GETEFCB
     Function: Returε áthσ áaddres≤ oµ thσ áZCPR│ áexterna∞ áfilσ ì
ááááááááááááááácontro∞ blocδ (FCB)
     Entry:    None
     Exit:     HL = address of external FCB
               A <> 0, zero flag clear (NZ) if OK
               A = 0, zero flag set (Z) if not found
     Affected: AF¼ HL
     Usage:    Unde≥ áZCPR3¼ ß prograφ caε finΣ ou⌠ b∙ wha⌠ ánamσ ì
ááááááááááááááái⌠ wa≤ invokeΣ througΦ thσ externa∞ FCB«  Byte≤ ▒-ì
ááááááááááááááá╕ áoµ thσ externa∞ FC┬ (firs⌠ bytσ i≤ á0⌐ ácontaiε ì
áááááááááááááááthσ namσ oµ thσ prograφ jus⌠ executeΣ b∙ ZCPR3.

               Thi≤ áfeaturσ ái≤ particularl∙ usefu∞ áfo≥ á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⌠ havinτ t∩ assumσ tha⌠ ái⌠ ì
áááááááááááááááha≤ ß particula≥ namσ a⌠ al∞ times.

ENVIRONMENT:

     Routine║  GETENV
     Function║ Return address of the ZCPR3 Environment Descriptor
     Entry:    None
     Exit:     HL = address of Environment Descriptor
     Affected: HL
     Usage:    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Σ ou⌠ wherσ t∩ loaΣ ì
áááááááááááááááthσ file.

     Routine║  GETVID
     Function║ Return address of the ZCPR3 TCAP (Z3TCAP)
     Entry:    None
     Exit:     HL = address of Z3TCAP buffer
               A <> 0, zero flag clear (NZ) if OK
               A = 0, zero flag set (Z) if no entry in buffer
     Affected: AF¼ HL
     Usage:    Fo≥ thosσ program≤ whicΦ neeΣ t∩ modif∙ thσ áZCPR│ ì
áááááááááááááááTCA╨ ábuffe≥ anΣ thosσ program≤ whicΦ neeΣ t∩ ádeì
áááááááááááááááterminσ áiµ thσ TCA╨ i≤ loaded«  I⌠ ma∙ bσ ádesirì
áááááááááááááááablσ t∩ cal∞ thi≤ routinσ beforσ ß screeε-orienteΣ ì
áááááááááááááááutilit∙ ái≤ áexecuteΣ át∩ insurσ tha⌠ áß áTCA╨ ái≤ ì
áááááááááááááááavailable.
.pa
èFLO╫ COMMAND PACKAG┼ (FCP⌐ ADDRESS:

     Routine║  GETFCP
     Function║ Return address of the flow commanΣ package buffer
     Entry:    None
     Exit:     HL = address of FCB buffer
               ┴ ╜ numbe≥ oµ 12╕-bytσ FC╨ blocks¼ zer∩ clea≥ (NZ⌐ ì
áááááááááááááááiµ OK
               A = 0, zero flag set (Z) if no buffer
     Affected: AF¼ HL
     Usage:    Return≤ áthσ FC┬ parameter≤ froφ áthσ áEnvironmen⌠ ì
áááááááááááááááDescriptor«  Thσ startinτ addres≤ anΣ sizσ oµ áthσ ì
áááááááááááááááFC╨ ábuffe≥ áiε term≤ oµ 12╕-bytσ block≤ áarσ áreì
áááááááááááááááturned«  T∩ finΣ ou⌠ iµ aε FC╨ i≤ installed¼ álooδ ì
áááááááááááááááa⌠ áthσ áfirs⌠ bytσ oµ thσ FC╨ buffer«  Iµ ái⌠ ái≤ ì
ááááááááááááááázero¼ theε n∩ FC╨ i≤ present.
     Example:

                         EXT       GETFCP         ; declare the routine
                         ...                      ; ..preliminary code
                         CALL      GETFCP         ; get addr/size from ENV
                         JR        Z,NOFCP        ; ..jump if no FCB buffer avail
                         LD        A,(HL)         ; examine the first buffer byte
                         OR        A              ; anything installed?
                         JR        Z,LODFCP       ; ..jump to load an FCP if not
                         ...                      ; else use existing one

FILENAMES:

     Routine║  GETFN1¼ GETFN2
     Function: GETFN▒ áget≤ addres≤ oµ shel∞ ávariablσ áfilename¼ ì
áááááááááááááááGETFN▓ get≤ addres≤ oµ firs⌠ oµ systeφ filenames
     Entry:    None
     Exit:     H╠ ╜ addres≤ oµ 1▒-characte≥ filσnamσ entry
     Affected: HL
     Usage:    Return≤ áthσ addres≤ iε H╠ oµ thσ áshel∞ ávariablσ ì
áááááááááááááááfilenamσ (GETFN1⌐ anΣ thσ firs⌠ oµ thσ fou≥ systeφ ì
áááááááááááááááfilename≤ á(GETFN2⌐ iε thσ ZCPR│ áEnvironmen⌠ áDeì
áááááááááááááááscriptor« á Thσ filenamσ entr∙ i≤ 1▒ ábyte≤ álong¼ ì
ááááááááááááááámatchinτ áthσ filenamσ anΣ filetypσ field≤ oµ áthσ ì
áááááááááááááááCP/═ filσ contro∞ block.

               Thesσ filename≤ arσ useΣ t∩ pas≤ name≤ oµ áspecia∞ ì
áááááááááááááááfile≤ t∩ program≤ fo≥ late≥ use«  Thei≥ exac⌠ áusσ ì
ááááááááááááááái≤ áno⌠ defineΣ anΣ i≤ lef⌠ t∩ you«  Onσ áapplicaì
ááááááááááááááátioε áwoulΣ bσ t∩ allo≈ GETFN▒ t∩ returε thσ ánamσ ì
áááááááááááááááoµ thσ maste≥ HL╨ filσ (HELP.HLP⌐ t∩ bσ useΣ a≤ aε ì
áááááááááááááááinde° int∩ thσ hel≡ system.
.pa
è     Routine║  GETFNX
     Function║ Return address of nth filename of system filenames
     Entry:    A = filename number (1..4) in ENV filename buffer
     Exit:     H╠ á╜ addres≤ oµ firs⌠ bytσ oµ indicateΣ filσ á(1▒ ì
ááááááááááááááácharacters)
               A <> 0, zero flag clear (NZ) if OK
               ┴ á╜ á0¼ zer∩ flaτ se⌠ (Z⌐ iµ inpu⌠ valuσ áno⌠ áiε ì
ááááááááááááááá1..┤ range
     Affected: AF¼ HL
     Usage:    Return≤ áthσ áaddres≤ oµ thσ ntΦ filenamσ áiε áthσ ì
áááááááááááááááZCPR│ áEnvironmen⌠ áDescriptor« á Therσ áarσ áfou≥ ì
ááááááááááááááásysteφ files¼ numbereΣ ▒ t∩ 4¼ anΣ the∙ arσ struπì
ááááááááááááááátureΣ álikσ áthσ Fn.F⌠ field≤ oµ áß áfilσ ácontro∞ ì
áááááááááááááááblocδ á(1▒ ábyte≤ each)«  Oε input¼ ┴ á╜ á1..┤ át∩ ì
áááááááááááááááindicatσ áthσ filename«  Oε output¼ H╠ ápoint≤ át∩ ì
áááááááááááááááthσ áfirs⌠ bytσ oµ thσ name«  ┴ validit∙ checδ ái≤ ì
ááááááááááááááádonσ oε thσ valuσ oµ ┴ whicΦ mus⌠ bσ 1..4.

     Routine║  PUTFNX
     Function: Se⌠ ntΦ (1..4⌐ filenamσ iε Environmen⌠ Descriptor
     Entry:    A = filename number (1..4)
               HL = address of FCB+1 of new filename value
     Exit:     A <> 0, zero flag clear (NZ) if OK
               ┴ á╜ á0¼ zer∩ flaτ se⌠ (Z⌐ iµ inpu⌠ valuσ áno⌠ áiε ì
ááááááááááááááá1..┤ range
     Affected: AF
     Usage:    Set≤ thσ ntΦ (1..4⌐ filenamσ iε thσ ZCPR│ Environì
ááááááááááááááámen⌠ Descripto≥ t∩ thσ FC┬-entr∙ pointeΣ t∩ b∙ áH╠ ì
ááááááááááááááá(FCB+1¼ o≥ thσ Fε field¼ i≤ pointeΣ t∩ b∙ HL)« á ┴ ì
ááááááááááááááái≤ useΣ t∩ identif∙ thσ filename.

INITIALIZE:

     Routine║  WHRENV
     Function: Returε áinstalleΣ áZCPR│ áEnvironmen⌠ ááDescripto≥ ì
áááááááááááááááaddress
     Entry:    HL = candidate address of Environment Descriptor
     Exit:     HL = points to start address of ENV (0 if not found)
               A <> 0, zero flag clear (NZ) if ENV validated
               A = 0, zero flag set (Z) if not found
     Affected: AF¼ BC¼ DE¼ HL
     Usage:    Provide≤ áß mean≤ oµ locatinτ ß ZCPR│ áEnvironmen⌠ ì
áááááááááááááááDescripto≥ áwithou⌠ thσ assistancσ oµ ZCP╥ 3.│ áo≥ ì
ááááááááááááááálate≥ ácommanΣ processors«  Callinτ WHREN╓ witΦ áß ì
ááááááááááááááácandidatσ addres≤ oµ thσ DO╙ entr∙ addres≤ áloadeΣ ì
áááááááááááááááfroφ location≤ ╢ anΣ ╖ wil∞ causσ ß searcΦ fo≥ áaε ì
áááááááááááááááenvironmen⌠ áfroφ tha⌠ addres≤ u≡ áthrougΦ áFEFFh«  ì
áááááááááááááááCallinτ ái⌠ áwitΦ áß paramete≥ oµ á░ ápreclude≤ áß ì
ááááááááááááááásearcΦ át∩ signif∙ tha⌠ thσ aut∩-searcΦ i≤ át∩ ábσ ì
ááááááááááááááádisabled.
     Example:

                         EX╘       WHRENV,Z3INI╘  ; declare routines
                         ...                      ; ..any header info here
                         LD        HL,(6)         ; load candidate location
                         CALL      WHRENV         ; ..and test it
è                         LD        (Z3EADR),HL    ; save any returned value
                         JR        Z,NOENV        ; ..jump if no ENV validated
                         CALL      Z3INIT         ; else set globals (or Z3VINIT)

     Routine║  Z3INIT
     Function: Se⌠ ágloba∞ buffe≥ t∩ arbitrar∙ addres≤ fo≥ áZCPR│ ì
áááááááááááááááenvironment
     Entry:    HL = address of ZCPR3 environment descriptor
     Exit:     None
     Affected: None
     Usage:    Set≤ ß globa∞ variablσ t∩ thσ ZCPR│ pointe≥ ávaluσ ì
áááááááááááááááinstalleΣ áiε áthσ prograφ áheader« á Thi≤ ágloba∞ ì
ááááááááááááááávariablσ i≤ useΣ b∙ othe≥ Z3LI┬ routines.
     Example:

                         EXT       Z3INIT         ; declare the routine
                         ...                      ; ..header code
                         LD        HL,Z3ENV       ; load the Env Desc address
                         CALL      Z3INIT         ; ..and install!
                         ...                      ; carry on!

SYSTE═ DATA:

     Routine║  ZSYSCHK
     Function║ Validate ZCPR3 Environment Descriptor address
     Entry:    HL = points to candidate Z3 environment
     Exit:     A = 0, zero set (Z) if valid environment
               A <> 0, zero clear (NZ) if environment not valid
     Affected: AF
     Usage:    Check≤ ávariou≤ parameter≤ iε aε áEnvironmen⌠ áDeì
áááááááááááááááscripto≥ ápredicateΣ oε thσ specifieΣ áaddres≤ át∩ ì
áááááááááááááááseσ áiµ i⌠ i≤ valid«  I⌠ wil∞ prin⌠ ß ámessagσ áiµ ì
áááááááááááááááthσ áenvironmen⌠ i≤ invalid«  Fo≥ bes⌠ result≤ áoε ì
áááááááááááááááZCP╥ á3.│ áo≥ later¼ pas≤ thσ valuσ iε H╠ áa⌠ áthσ ì
ááááááááááááááátimσ áthσ prograφ starts«  Thi≤ wil∞ no⌠ áworδ áoε ì
áááááááááááááááZCP╥ á3.0¼ ábu⌠ wil∞ detec⌠ áBackGrounde≥ áiΘ áanΣ ì
áááááááááááááááversion≤ sincσ ZCP╥ 3.3.
     Example:

                    EXT       ZSYSCHK             ; declare the routine
                    ...
                    LD        HL,(ENVADR)         ; load candidate environment
                    CALL      ZSYSCHK             ; is it valid? (message if not)
                    RET       NZ                  ; ..quit if invalid
                    ...                           ; else continue with valid ENV

     Routine║  Z33CHK
     Function║ Check for presence of ZCPR 3.3 or later
     Entry:    None
     Exit:     A = 0, zero set (Z) if CCP is ZCPR 3.3 or later
               A <> 0, zero clear (NZ) if not ZCPR >= 3.3
     Affected: AF
     Usage:    ShoulΣ ábσ useΣ iε thσ initia∞ setu≡ portioε oµ áß ì
áááááááááááááááprograφ áiµ man∙ oµ thσ ne≈ Z3LI┬ routine≤ arσ át∩ ì
ááááááááááááááábσ used«  Routine≤ sucΦ a≤ Z33FNAM┼ rel∙ oε speciì
áááááááááááááááfiπ áentr∙ point≤ iε thσ commanΣ áprocesso≥ áwhicΦ ì
áááááááááááááááonl∙ áexis⌠ iε ZCP╥ 3.│ o≥ later«  Iµ ásucΦ ácall≤ ìèáááááááááááááááarσ madσ unde≥ othe≥ commanΣ processors¼ o≥ iµ thσ ì
áááááááááááááááC╨ i≤ overwritten¼ you≥ prograφ wil∞ bσ unablσ át∩ ì
áááááááááááááááfunction.
     Example:

                         EXT       Z33CHK         ; declare the routine
                         ...
                         CALL      Z33CHK         ; Is CP ZCPR 3.3 or later?
                         JR        NZ,NOTZ3       ; ..jump if not
                         ...                      ; else we can use it

     Routine║  GETBDOS
     Function║ Return BDO╙ start address
     Entry:    None
     Exit:     HL = calculated or loaded BDOS starting address
     Affected: HL
     Usage:    Return≤ áthσ ástartinτ addres≤ oµ thσ áBasiπ áDisδ ì
áááááááááááááááOperatinτ Systeφ (BDOS⌐ froφ aε extendeΣ áenvironì
ááááááááááááááámen⌠ iµ present¼ elsσ i⌠ wil∞ calculatσ thσ startì
áááááááááááááááinτ addres≤ froφ thσ BIO╙ warφ boo⌠ vecto≥ áassumì
áááááááááááááááinτ áß á3.5╦ BDO╙ size«  Yo⌡ shoulΣ no⌠ áusσ áthi≤ ì
áááááááááááááááaddres≤ áa≤ thσ to≡ oµ availablσ memory¼ bu⌠ áonl∙ ì
ááááááááááááááát∩ locatσ thσ DOS«  Usσ thσ addres≤ a⌠ location≤ ╢ ì
áááááááááááááááanΣ ╖ o≥ GZMTO╨ t∩ finΣ thσ highes⌠ usablσ ámemor∙ ì
ááááááááááááááálocatioε dependinτ oε whethe≥ o≥ no⌠ thσ CC╨ i≤ t∩ ì
ááááááááááááááábσ retained.

     Routine║  GETCCP
     Function║ Return command processor starting address
     Entry:    None
     Exit:     HL = calculated or loaded CCP starting address
     Affected: HL
     Usage:    Return≤ áthσ startinτ addres≤ oµ thσ commanΣ áproì
ááááááááááááááácesso≥ áfo≥ usσ iε calculatinτ addresse≤ oµ áentr∙ ì
ááááááááááááááápoints¼ anΣ iε locatinτ ZCPR│ configuratioε bytes«  ì
áááááááááááááááThi≤ ároutinσ áfirs⌠ attempt≤ t∩ álocatσ áthσ áCC╨ ì
áááááááááááááááaddres≤ áfroφ aε extendeΣ environmen⌠ iµ ápresent¼ ì
áááááááááááááááotherwisσ ái⌠ wil∞ calculatσ thσ startinτ áaddres≤ ì
áááááááááááááááfroφ áthσ áBIO╙ warφ boo⌠ vecto≥ assuminτ áß á3.5╦ ì
áááááááááááááááBDO╙ anΣ ß 2╦ CCP.

     Routine║  GETECP
     Function║ Return address of extended command processor name
     Entry:    None
     Exit:     HL = address of ECP name
     Affected: HL
     Usage:    Locate≤ thσ namσ oµ thσ ZCP╥ versioε 3.│ o≥ álate≥ ì
áááááááááááááááextendeΣ commanΣ processor«  Require≤ ZCP╥ 3.│ áo≥ ì
ááááááááááááááálate≥ anΣ thσ commanΣ processo≥ mus⌠ no⌠ havσ beeε ì
áááááááááááááááoverwritten.
.pa
èINPUT/OUTPU╘ áPACKAG┼ (IOP⌐ CONCEPTS:é  Thi≤ se⌠ oµ routine≤ áproì
vidσ áacces≤ t∩ thσ systeφ Input/Outpu⌠ Packagσ (IOP)« á Thσ ádeì
vice≤ iε aε IO╨ arσ identifieΣ b∙ ß logica∞ I─ (referrinτ t∩ áthσ ì
generiπ CON¼ RDR¼ PUN¼ anΣ LS╘ devices⌐ anΣ ß physica∞ I─ (referì
rinτ át∩ thσ specifiπ devicσ unde≥ thσ generic)«  B∙ áconvention¼ ì
routine≤ áiε thi≤ collectioε alway≤ pas≤ thσ logica∞ I─ iε thσ á┬ ì
registe≥ áanΣ thσ physica∞ I─ iε thσ ├ register« á Thσ áfollowinτ ì
tablσ show≤ thσ assignments:

      logical ID
       (B reg)       device
          0           CON:
          1           RDR:
          2           PUN:
          3           LST:

Thσ IO╨ statu≤ table¼ containeΣ iε ever∙ IOP¼ return≤ informatioε ì
oε áthσ physica∞ ID's«  I⌠ tell≤ ho≈ man∙ physica∞ device≤ á(PID⌐ ì
arσ availablσ fo≥ eacΦ logica∞ ID¼ anΣ thσ curren⌠ assignmen⌠ á(░ ì
t∩ PI─-1)«  Thi≤ tablσ i≤ structureΣ as:

         offset               number of current
         bytes     device    devices  assignment
          0-▒       CON║      Byte ░    Byte 1
          2-3       RDR:      Byte 2    Byte 3
          4-5       PUN:      Byte 4    Byte 5
          6-7       LST:      Byte 6    Byte 7

Fo≥ áexample¼ iµ bytσ ░ (numbe≥ oµ physica∞ consoles⌐ i≤ 5¼ átheε ì
bytσ á▒ (curren⌠ physica∞ consolσ assignment⌐ caε onl∙ bσ iε áthσ ì
rangσ froφ ░ t∩ 4«  GETIO╙ return≤ thσ addres≤ oµ thi≤ table.

The routines in the IOP collection are:

     GETIONÅ¡-returε áß ástrinτ givinτ thσ namσ áoµ áthσ ádevicσ ì
ááááááááááidentifieΣ b∙ ß logica∞ I─ anΣ ß physica∞ ID.
     GETIOP -- return the address and size of the IOP.
     GETIOS -- return a pointer to the IOP status table.
     IOMATCHÅ¡-searche≤ áfo≥ ß physica∞ devicσ ánamσ áassociateΣ ì
ááááááááááwitΦ ß particula≥ logica∞ ID.
     PUTIOD -¡ select and IOP device by logical and physical ID.

     Routine║  GETION
     Function║ Return address of name for specified device
     Entry:    B = logical device ID (0..3)
               C = physical ID
     Exit:     HL = address of string naming the indicated device
               A <> 0, zero flag clear (NZ) if no error
               A = 0, zero flag set (Z) if no IOP or range error
     Affected: AF¼ HL
     Usage:    Return≤ áß ápointe≥ t∩ thσ strinτ ádescribinτ áthσ ì
ááááááááááááááádevicσ áwhosσ álogica∞ I─ (░ t∩ á3¼ áwherσ áCON=0¼ ì
áááááááááááááááRDR=1¼ áPUN=2¼ anΣ LST=3⌐ i≤ iε ┬ anΣ physica∞ áI─ ì
ááááááááááááááái≤ iε C.

è     Routine║  GETIOP
     Function║ Return address and size of IOP buffer definition
     Entry:    None
     Exit:     HL = address of IOP buffer
               ┴ á╜ ánumbe≥ oµ 12╕-bytσ block≤ áiε ábuffer¼ ázer∩ ì
áááááááááááááááclea≥ (NZ)
               A = 0, zero flag set (Z) if no buffer
     Affected: AF¼ HL
     Usage:    Return≤ detail≤ oε thσ IO╨ buffe≥ addres≤ anΣ sizσ ì
áááááááááááááááfroφ áthσ Environmen⌠ Descriptor¼ bu⌠ i⌠ doe≤ áno⌠ ì
ááááááááááááááása∙ áiµ áaε IO╨ i≤ resident«  T∩ áfinΣ áthi≤ áout¼ ì
áááááááááááááááexaminσ áthσ áfirs⌠ bytσ oµ thσ áIO╨ ábuffer« á Iµ ì
ááááááááááááááázero¼ theε n∩ IO╨ i≤ exists.
     Example:

                         EX╘       GETIOP         ; declare the routine
                         ...                      ; ..preceeding code
                         CALL      GETIOP         ; get IOP buff data from ENV
                         J╥        Z,NOIO╨        ╗ ..jum≡ iµ n∩ IO╨ buffer
                         LD        A,(HL)         ; else get first byte
                         OR        A              ; is anything installed?
                         JR        Z,LODIOP       ; ..jump to load if not there
                         ...                      ; else continue, IOP present

     Routine║  GETIOS
     Function║ Return pointer to I/O package status table
     Entry:    None
     Exit:     HL = address of IOP status table
               A <> 0, zero flag clear (NZ) if OK
               A = 0 zero set (Z) if no IOP loaded
     Affected: AF¼ HL
     Usage:    Return≤ ß pointe≥ t∩ thσ I/╧ packagσ statu≤ átablσ ì
áááááááááááááááiε HL«  Thσ tablσ i≤ structureΣ as:
                   offset               number of current
                   bytes     device    devices  assignment
                    0-1       CON║      Byte ░    Byte 1
                    2-3       RDR:      Byte 2    Byte 3
                    4-5       PUN:      Byte 4    Byte 5
                    6-7       LST:      Byte 6    Byte 7

     Routine║  IOMATCH
     Function║ Search for physical device name for logical ID
     Entry:    HL = address of device name string
               B = logical ID (CON=0, RDR=1, PUN=2, LST=3)
     Exit:     C = physical ID
               A <> 0, zero flag clear (NZ) if OK
               A = 0, zero flag clear if not found or no IOP
     Affected: AF¼ C
     Usage:    Searche≤ fo≥ thσ namσ oµ ß physica∞ devicσ associì
áááááááááááááááateΣ witΦ ß particula≥ logica∞ ID«  Thi≤ namσ i≤ ß ì
áááááááááááááááNU╠-terminateΣ ástrinτ o≥ an∙ characte≥ les≤ áthaε ì
áááááááááááááááo≥ áequa∞ át∩ ß space«  Thσ ánamσ ái≤ ácapitalizeΣ ì
áááááááááááááááinternally« á Iµ found¼ ├ return≤ thσ physica∞ áI─ ì
áááááááááááááááoµ thσ device.
.pa
è     Example:

                         EXT       IOMATCH        ; declare the routine
                         ...                      ; ..preceeding code
                         LD        HL,MYCON       ; point to name string
                         LD        B,0            ; select CON device
                         CALL      IOMATCH        ; search for the device
                         JR        Z,ERROR        ; ..jump error if bad
                         ...                      ; else C=physical ID of MYCON
               MYCON:    DEFB      'CRT1',0       ; name of desired CON device

     Routine║  PUTIOD
     Function║ Select the IOP device from specified logical ID
     Entry:    B = logical ID (CON=0, RDR=1, PUN=2, LST=3)
               C = physical ID
     Exit:     A <> 0, zero flag clear (NZ) if OK
               ┴ ╜ 0¼ zer∩ flaτ se⌠ (Z⌐ iµ n∩ IO╨ o≥ rangσ áerro≥ ì
ááááááááááááááá(physica∞ o≥ logica∞ I─ numbe≥ invalid)
     Affected: AF
     Usage:    Select≤ áaε IO╨ devicσ froφ ß se⌠ oµ álogica∞ áanΣ ì
áááááááááááááááphysica∞ áID's« á Logica∞ I─ number≤ áarσ áiε áthσ ì
ááááááááááááááárangσ oµ ░ t∩ 3¼ wherσ CO╬ ╜ 0¼ RD╥ ╜ 1¼ PU╬ ╜ á2¼ ì
áááááááááááááááanΣ LS╘ ╜ 3«  Seσ thσ introductor∙ IO╨ sectioε fo≥ ì
ááááááááááááááámorσ details.

INPUT/OUTPU╘ PACKAGE (IOP⌐ RECORDING:

     Routines║ IORCON¼ IORCOFF¼ IORLON¼ IORLOFF
     Function║ Turε oε anΣ ofµ I/╧ recordinτ iε curren⌠ IOP
     Entry:    HL = address of ZCPR3 FCB for recorded information
     Exit:     A <> 0, zero flag clear (NZ) if OK
               ┴ á╜ 0¼ zer∩ flaτ se⌠ (Z⌐ iµ n∩ IO╨ áo≥ árecordinτ ì
áááááááááááááááno⌠ supporteΣ iε IOP
     Affected: AF
     Usage:    IORCO╬ áturn≤ oε consolσ recording¼ IORCOF╞ áturn≤ ì
áááááááááááááááofµ áconsolσ recording¼ IORLO╬ turn≤ oε ális⌠ áreì
ááááááááááááááácording¼ áIORLOF╞ turn≤ ofµ lis⌠ árecording« á Thσ ì
áááááááááááááááFC┬ ápasseΣ t∩ thesσ routine≤ i≤ ß standarΣ áZCPR│ ì
áááááááááááááááFCB¼ áwherσ offse⌠ ░ contain≤ thσ disδ anΣ áoffse⌠ ì
ááááááááááááááá1│ ácontain≤ thσ use≥ data«  ┴ particula≥ IO╨ áma∙ ì
áááááááááááááááo≥ áma∙ áno⌠ pa∙ attentioε t∩ áthi≤ áFC┬ ápointer¼ ì
ááááááááááááááádependinτ oε implementation.

DRIVE/USER:

     Routine║  GETDUOK
     Function║ Return the value of the DUOK flag
     Entry:    None
     Exit:     A <> 0, zero flag clear (NZ) if DU use OK
               A = 0, zero flag set (Z) if DU use not allowed
     Affected: AF
     Usage:    Return≤ áthσ DUO╦ flaτ valuσ whicΦ tell≤ thσ áproì
ááááááááááááááágraφ iµ i⌠ i≤ permissiblσ t∩ specif∙ thσ D╒ prefi° ì
ááááááááááááááát∩ changσ disδ anΣ use≥ area«  ZCPR│ utilitie≤ caε ì
áááááááááááááááalway≤ áspecif∙ ß DI╥ 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σ D╒ prefi° t∩ áacì
áááááááááááááááces≤ áan∙ ádisδ o≥ use≥ area« á Thi≤ áflaτ á(DUOK⌐ ì
ááááááááááááááátell≤ áthσ áutilit∙ iµ i⌠ i≤ O╦ fo≥ áthσ áuse≥ át∩ ì
áááááááááááááááemplo∙ thσ D╒ prefix.

     Routine║  GETMDISK
     Function║ Return the maximum allowable disk
     Entry:    None
     Exit:     A = maximum disk number (1=A..16=P)
     Affected: AF
     Usage:    Obtain≤ áinformatioε áfroφ thσ áZCPR│ áEnvironmen⌠ ì
áááááááááááááááDescripto≥ whicΦ ma∙ bσ useΣ t∩ restric⌠ acces≤ t∩ ì
ááááááááááááááácertaiε ápart≤ áoµ thσ system« á Fo≥ áinstance¼ áß ì
ááááááááááááááá"norma∞ useró ma∙ bσ denieΣ acces≤ t∩ disk≤ ├ áanΣ ì
áááááááááááááááD« á ┴ á"privelegeΣ áuseró wh∩ ha≤ áthσ ápowe≥ át∩ ì
áááááááááááááááchangσ áthσ ZCPR│ EnvΘronmen⌠ Descripto≥ caε ágaiε ì
áááááááááááááááacces≤ t∩ an∙ desireΣ disδ.

     Routine║  GETMUSER
     Function║ Return the maximum allowable user area
     Entry:    None
     Exit:     A = maximum allowable user area (0..31)
     Affected: AF
     Usage:    Provide≤ áinformatioε froφ thσ áZCPR│ áEnvironmen⌠ ì
áááááááááááááááDescripto≥ whicΦ ma∙ bσ useΣ t∩ restric⌠ acces≤ t∩ ì
ááááááááááááááácertaiε ápart≤ áoµ thσ system« á Fo≥ áinstance¼ áß ì
ááááááááááááááá"norma∞ áuseró áma∙ bσ denieΣ acces≤ t∩ áan∙ áuse≥ ì
áááááááááááááááareß ábeyonΣ 10«  ┴ "privelegeΣ useró wh∩ ha≤ áthσ ì
ááááááááááááááápowe≥ át∩ changσ thσ ZCPR│ Environmen⌠ áDescripto≥ ì
ááááááááááááááácaε gaiε acces≤ t∩ an∙ desireΣ use≥ area.

     Routine║  PUTDUOK
     Function║ Set the DUOK byte to specified value
     Entry:    A = DUOK value (0=DU not OK, 0FFh = DU is OK)
     Exit:     None
     Affected: None
     Usage:    Set≤ áthσ áDUO╦ bytσ froφ A«  Iµ ┴ ╜ á0¼ áDUO╦ ái≤ ì
áááááááááááááááfalsσ anΣ D╒ forφ oµ filσ specificatioε i≤ no⌠ OK«  ì
áááááááááááááááIµ A<>░ (0FFΦ i≤ preferred)¼ DUO╦ i≤ truσ anΣ filσ ì
áááááááááááááááspecificatioε usinτ thσ D╒ forφ i≤ permitted.

     Routine║  PUTMDISK
     Function║ Set the maximum allowable disk in the environment
     Entry:    A = maximum allowable disk numbe≥ (1=A..16=P)
     Exit:     None
     Affected: None
     Usage:    Set≤ thσ maximuφ allowablσ disδ iε thσ Environmen⌠ ì
áááááááááááááááDescriptor« á ValiΣ disδ number≤ rangσ froφ ▒ áfo≥ ì
ááááááááááááááádrivσ ┴ t∩ 1╢ fo≥ drivσ P.
.pa
è     Routine║  PUTMUSER
     Function║ Set the maximum allowable user number (0..31)
     Entry:    A = maximum allowable user number (0..31)
     Exit:     None
     Affected: None
     Usage:    Set≤ thσ maximuφ allowablσ use≥ areß iε thσ áEnviì
áááááááááááááááronmen⌠ Descriptor«  ValiΣ use≥ number≤ rangσ froφ ì
ááááááááááááááá░ througΦ 31.

     Routine║  HIGHUSER
     Function: Returε flaτ showinτ suppor⌠ fo≥ user≤ highe≥ thaε 15
     Entry:    None
     Exit:     Zero clear (NZ) if users highe≥ than 15 supported
               Zer∩ áse⌠ á(Z⌐ iµ n∩ ZCP╥ 3.│ o≥ n∩ áuser≤ áhighe≥ ì
áááááááááááááááthaε 15
               A = undefined
     Affected: AF
     Usage:    Return≤ áß áflaτ indicatinτ whethe≥ áuse≥ ánumber≤ ì
ááááááááááááááágreate≥ thaε 1╡ arσ supported«  Thi≤ definitioε i≤ ì
áááááááááááááááobtaineΣ áfroφ thσ ZCP╥ 3.│ o≥ late≥ commanΣ ápr∩ì
ááááááááááááááácessor«  Require≤ ZCP╥ 3.│ o≥ highe≥ anΣ thσ ácomì
ááááááááááááááámanΣ processo≥ mus⌠ no⌠ havσ beeε overwritten.

     Routine║  GCMDDU
     Function║ Return drive and user number in external FCB
     Entry:    None
     Exit:     BC = DU; B=drive (0=A..15=P), C=user (0..31)
     Affected: BC
     Usage:    Return≤ thσ drivσ anΣ use≥ fo≥ thσ filσ áspecifieΣ ì
áááááááááááááááiε áthσ externa∞ FCB«  I⌠ i≤ ofteε useΣ t∩ ádeterì
áááááááááááááááminσ áwherσ áthσ filσ wa≤ actuall∙ áfounΣ á(shell¼ ì
ááááááááááááááápath¼ áetc.⌐ áiε orde≥ t∩ loτ int∩ áo≥ ásavσ átha⌠ ì
ááááááááááááááálocation« á Externa∞ FC┬ mus⌠ havσ beeε parseΣ áb∙ ì
áááááááááááááááZCP╥ 3.│ o≥ later¼ whicΦ place≤ thσ use≥ numbe≥ iε ì
áááááááááááááááFCB+1│ anΣ thσ drivσ iε FCB+14.

MESSAGES:

     Routine║  GETMSG
     Function║ Return the address of the ZCPR3 message buffer
     Entry:    None
     Exit:     HL = address of the ZCPR3 message buffer
               A <> 0, zero flag clear (NZ) if valid
               A = 0, zero flag set (Z) if no buffer
     Affected: AF,HL
     Usage:    Iε áconjunctioε áwitΦ othe≥ messagσ ároutine≤ áfo≥ ì
ááááááááááááááásynchronizatioε ábetweeε programs¼ anΣ statu≤ áinì
áááááááááááááááformation« á Seσ áZ3LI┬ áinformatioε ásection≤ áoε ì
áááááááááááááááZCPR│ Messages.
.pa
è     Routine║  GETSHM
     Function: Ge⌠ ávaluσ oµ shel∞ messagσ fo≥ specifieΣ ámessagσ ì
ááááááááááááááánumber
     Entry:    B = message number (0, 1, 2)
     Exit:     A = message value (zero flag set accordingly)
     Affected: AF
     Usage:    Return≤ thσ valuσ oµ thσ shel∞ messagσ whosσ ánumì
ááááááááááááááábe≥ i≤ specified«  Therσ arσ threσ shel∞ messages¼ ì
ááááááááááááááás∩ ░ <╜ ┬ <╜ ▓ (yo⌡ mus⌠ bσ surσ ß valiΣ valuσ ái≤ ì
ááááááááááááááápresented).

     Routine║  PUTSHM
     Function║ Set the value of specified shell message number
     Entry:    A = message value
               B = message number (0,1,2)
     Exit:     None
     Affected: None
     Usage:    Place≤ áß ámessagσ int∩ onσ oµ thσ áthreσ ámessagσ ì
áááááááááááááááposition≤ iε thσ shel∞ area.

NAMED DIRECTORIES:

     Routine║  ADDNDR
     Function║ Add directory name to the named directory buffer
     Entry:    ┴ ╜ passworΣ flaτ (0=se⌠ t∩ spaces¼ noε-0=se⌠ froφ ì
áááááááááááááááDE)
               D┼ ╜ addres≤ oµ passworΣ buffe≥ iµ A<>░ (╕-characì
áááááááááááááááters)
               HL = address of FCB containing DU and disk name
     Exit:     ┴ á<╛ 0¼ zer∩ flaτ clea≥ (NZ⌐ iµ namσ áaddeΣ ásucì
ááááááááááááááácessfully
               A = 0, zero set (Z) if no buffer, or buffer full
     Affected: AF
     Usage:    Add≤ ß director∙ namσ t∩ thσ nameΣ director∙ (NDR⌐ ì
ááááááááááááááábuffe≥ defineΣ iε thσ Environmen⌠ Descriptor«  Thσ ì
áááááááááááááááname¼ áalonτ áwitΦ ádisδ anΣ áuse≥ álocation≤ áarσ ì
ááááááááááááááápasseΣ áiε áZCPR│ FC┬ forφ wherσ thσ ádisδ ái≤ áa⌠ ì
áááááááááááááááoffse⌠ á░ (A=1,..P=16)¼ anΣ thσ use≥ numbe≥ i≤ áa⌠ ì
áááááááááááááááoffse⌠ á1│ (0..31)«  Thσ director∙ namσ i≤ iε áthσ ì
áááááááááááááááFε áfielΣ oµ thσ FCB«  Aε optiona∞ passworΣ oµ áu≡ ì
ááááááááááááááát∩ eigh⌠ character≤ (spacσ-filleΣ oε right⌐ ma∙ bσ ì
ááááááááááááááápasseΣ áa≤ ß strinτ iε thσ D┼ registe≥ ápair« á Oε ì
áááááááááááááááinput¼ áiµ A=░ theε thσ D┼ pointe≥ i≤ ignoreΣ áanΣ ì
áááááááááááááááthσ passworΣ i≤ se⌠ empt∙ (al∞ spaces).

               ADDND╥ capitalize≤ thσ disδ namσ anΣ password¼ anΣ ì
ááááááááááááááásort≤ thσ nameΣ director∙ buffe≥ b∙ D╒ afte≥ addiì
ááááááááááááááátion« á N∩ áchecδ i≤ madσ fo≥ duplicatσ áname≤ áo≥ ì
áááááááááááááááduplicatσ D╒ references.
.pa
è     Routine║  DIRNDR
     Function║ Find named directory buffer entry for specified name
     Entry:    HL = address of 8-character buffer with name to find
     Exit:     HL = address of NDR entry, if found
               BC = DU (disk in B, 1=A..16=P) if found
               A <> 0, zero flag clear (NZ) if name found
               A = 0, zero flag set (Z) if no NDR or not found
     Affected: AF¼ BC¼ HL
     Usage:    Recover≤ áthσ drivσ anΣ use≥ datß fo≥ ß áspecifieΣ ì
ááááááááááááááánamσ áfroφ thσ nameΣ director∙ buffer«  Thσ áentr∙ ì
ááááááááááááááánamσ i≤ automaticall∙ capitalized«  Iµ found¼ áthσ ì
ááááááááááááááádrivσ ái≤ returneΣ iε registe≥ ┬ (1=A..16=P)¼ áanΣ ì
áááááááááááááááthσ áuse≥ iε registe≥ ├ (0..31)«  Thσ H╠ áregiste≥ ì
ááááááááááááááápai≥ áwil∞ poin⌠ t∩ thσ ND╥ entr∙ whicΦ i≤ ástrucì
ááááááááááááááátureΣ arounΣ 1╕-bytσ entrie≤ as:

                         DEFB      ▒              ; disk (1=A..16=P)
                         DEFB      15             ; user (0 to 31)
                         DEFB      'ROOT    º     ; name, 8-chars, space filled
                         DEFB      'MYPASS  '     ; password, 8-char, space fill

     Routine║  DUNDR
     Function: FinΣ nameΣ director∙ entr∙ froφ drive/use≥ áspeciì
áááááááááááááááfication
     Entry:    BC = drive/user in DU to locate (disk 1=A..16=P)
     Exit:     HL = address of NDR entry if found
               A <> 0, zero flag clear (NZ⌐ if found
               A = 0, zero flag set if no NDR buffer or not found
     Affected: AF¼ HL
     Usage:    Locate≤ áß ánameΣ director∙ áfroφ áthσ ádrive/use≥ ì
áááááááááááááááspecificatioε áiε áD╒ forφ wherσ thσ drivσ ái≤ áiε ì
áááááááááááááááregiste≥ ┬ (drivσ 1=A..16=P⌐ anΣ use≥ i≤ iε regisì
áááááááááááááááte≥ á├ (0..31)«  Iµ found¼ thσ addres≤ oµ thσ á1╕-ì
ááááááááááááááábytσ ánameΣ ádirector∙ buffe≥ entr∙ ái≤ áreturned«  ì
áááááááááááááááEntrie≤ arσ structureΣ as:

                         DEF┬      ▓              ╗ disδ (1=A..16=P)
                         DEFB      0              ; user (0..31)
                         DEFB      'HELP    '     ; name, 8-char, space filled
                         DEFB      '        '     ; password, 8-char, space fill

     Routine║  GETNDR
     Function║ Returε ánameΣ ádirector∙ ábuffe≥ áparameter≤ áfroφ ì
áááááááááááááááenvironment
     Entry:    None
     Exit:     HL = address of NDR buffer
               A = buffer size in 128-byte blocks, zero clear (NZ)
               A = 0, zero set (Z⌐ if no NDR buffer
     Affected: AF¼ HL
     Usage:    Thi≤ ároutinσ return≤ thσ addres≤ anΣ sizσ oµ áthσ ì
ááááááááááááááánameΣ director∙ buffe≥ a≤ defineΣ iε thσ áEnvironì
ááááááááááááááámen⌠ Descriptor«  I⌠ doe≤ no⌠ indicatσ thσ ástatu≤ ì
áááááááááááááááoµ áan∙ áentrie≤ withiε it« á T∩ ádeterminσ áthis¼ ì
áááááááááááááááexaminσ áthσ firs⌠ bytσ iε thσ buffer« á Iµ ázero¼ ì
ááááááááááááááátheε n∩ ND╥ i≤ presen⌠ iε thσ buffer.
.pa
è     Example:

                         EX╘       GETNDR         ; declare the routine
                         ...                      ; ..preceeding code
                         CALL      GETNDR         ; get data from ENV
                         JR        Z,NONDRBF      ; ..jump if no NDR bufr exists
                         LD        A,(HL)         ; have an NDR. Is data there?
                         OR        A
                         JR        Z,LODNDR       ; ..jump if not and load some

     Routine║  SUBNDR
     Function: Removσ áspecifieΣ nameΣ director∙ entr∙ áfroφ áND╥ ì
ááááááááááááááábuffer
     Entry:    HL = address of 8-character buffer containing name
     Exit:     A <> 0, zero flag clear (NZ) if removal successful
               A = 0, zero flag set if no NDR or name not found
     Affected: AF
     Usage:    Remove≤ aε entr∙ specifieΣ b∙ namσ froφ thσ ánameΣ ì
ááááááááááááááádirector∙ buffer«  Thσ namσ mus⌠ bσ provideΣ a≤ áß ì
ááááááááááááááástrinτ oµ u≡ t∩ eigh⌠ characters¼ spacσ-filleΣ áoε ì
ááááááááááááááárigh⌠ iµ les≤ thaε eigh⌠ characters«  Thσ namσ ái≤ ì
ááááááááááááááácapitalizeΣ beforσ i⌠ i≤ checkeΣ agains⌠ ápossiblσ ì
áááááááááááááááentries« á Iµ located¼ thσ entr∙ i≤ áremoved¼ áanΣ ì
áááááááááááááááthσ remaininτ buffe≥ i≤ repacked.

PATH:

     Routine║  GETPATH
     Function: Returε addres≤ oµ thσ commanΣ searcΦ patΦ froφ thσ ì
áááááááááááááááenvironment
     Entry:    None
     Exit:     H╠ ╜ addres≤ oµ ZCPR│ searcΦ patΦ froφ Environmen⌠ ì
áááááááááááááááDescriptor
               A = number of elements, zero flag clear (NZ) if OK
               A = 0, zero set (Z) if no path defined in ENV
     Affected: AF¼ HL
     Usage:    Returε áthσ áaddres≤ oµ thσ ZCPR│ ácommanΣ ásearcΦ ì
ááááááááááááááápatΦ a≤ defineΣ iε thσ Environmen⌠ Descriptor«  Iµ ì
ááááááááááááááátherσ i≤ ß ZCPR│ path¼ i⌠ wil∞ bσ structureΣ a≤ áß ì
áááááááááááááááserie≤ oµ tw∩-bytσ patΦ element≤ structureΣ as:

                         DEF┬      ▒              ; disk #1 (current='$', A=1..P=16)
                         DEFB      15             ; user #1 (current='$', 0..31)
                         DEFB      '$'            ; disk #2
                         DEFB      0              ; user #2
                         DEFB      0              ; end-of-list is drive = 0

PROCESSOR SPEED:

     Routine║  GETSPEED
     Function║ Return processor speed in MHz from environment
     Entry:    None
     Exit:     A = processor speed in megahertz
     Affected: AF
     Usage:    Mos⌠ ofteε useΣ iε softwarσ timinτ loop≤ t∩ permi⌠ ì
áááááááááááááááß greate≥ amoun⌠ oµ portabilit∙ iε software« á Thσ ì
áááááááááááááááreturneΣ valuσ i≤ t∩ thσ neares⌠ megahertz¼ s∩ ▒ ╜ ìèááááááááááááááá▒ MHz¼ ┤ ╜ ┤ MHz¼ etc.

     Routine║  PUTSPEED
     Function: Se⌠ áprocesso≥ speeΣ iε environmen⌠ át∩ áspecifieΣ ì
ááááááááááááááávalue
     Entry:    A = processor speed in megahertz
     Exit:     None
     Affected: None
     Usage:    Set≤ áthσ processo≥ speeΣ a≤ defineΣ iε thσ áEnviì
áááááááááááááááronmen⌠ Descripto≥ t∩ thσ specifieΣ valuσ iε Megaì
áááááááááááááááHert· wherσ ▒ ╜ ▒ MHz¼ ┤ ╜ ┤ MHz¼ etc.

QUIE╘ FLAG:

     Routine║  GETQUIET
     Function║ Return value of quiet flag
     Entry:    None
     Exit:     A = value of quiet flag from environment
               Zer∩ flaτ se⌠ accordingly║ ░ (no⌠ quiet⌐ ╜ Z¼ 0FFΦ ì
ááááááááááááááá(quiet⌐ ╜ NZ
     Affected: AF
     Usage:    Ofteε áuseΣ áiε program≤ t∩ suppres≤ áunneedeΣ áo≥ ì
áááááááááááááááunwanteΣ ástatu≤ messages«  B∙ sensinτ áthσ áquie⌠ ì
áááááááááááááááflaτ anΣ usinτ conditiona∞ prin⌠ statements¼ ámorσ ì
ááááááááááááááápleasinτ áoperatioε ácaε result«  Thσ áquie⌠ áflaτ ì
ááááááááááááááávaluσ iε storeΣ iε thσ Environmen⌠ Descriptor.

     Routine║  PUTQUIET
     Function║ Set the value of the quiet flag
     Entry:    A = quiet flag value (0=not quiet, 0FFh=quiet)
     Exit:     None
     Affected: None
     Usage:    Set≤ thσ quie⌠ flaτ t∩ thσ specifieΣ value«  Whilσ ì
ááááááááááááááá0FFΦ i≤ preferreΣ t∩ indicatσ quie⌠ operation¼ an∙ ì
ááááááááááááááánoε-zer∩ valuσ wil∞ suffice.

RESIDEN╘ COMMAN─ PACKAG┼ (RCP⌐ ADDRESS:

     Routine║  GETRCP
     Function: Returε addres≤ anΣ sizσ oµ residen⌠ commanΣ ápackì
áááááááááááááááagσ (RCP⌐ defineΣ iε environment
     Entry:    None
     Exit:     HL = address of RCP buffer
               A = size of buffer in 12-byte blocks, zero clear (NZ)
               A = 0, zero flag set (Z) if no RCP defined
     Affected: AF¼ HL
     Usage:    Return≤ thσ residen⌠ commanΣ packagσ buffe≥ ádefiì
ááááááááááááááánition≤ ácontaineΣ iε thσ Environmen⌠ áDescriptor«  ì
áááááááááááááááYou≥ áprograφ ámus⌠ checδ fo≥ ß valiΣ ápackagσ áiµ ì
ááááááááááááááánecessar∙ b∙ examininτ thσ firs⌠ bytσ oµ thσ ábufì
áááááááááááááááfer.
.pa
è     Example:

                         EX╘       GETFCP         ; declare the routine
                         ...                      ; ..preceeding code
                         CALL      GETFCP         ; get ENV definitions
                         JR        Z,NOFCPBUF     ; ..jump if no RCP exists
                         LD        A,(HL)         ; check first byte of bufr
                         OR        A              ; anything there?
                         JR        Z,LODRCP       ; ..jump if not to load
                         ...                      ; else have an RCP in place

SHELL STACK:

     Routine║  GETSH1
     Function: Returε ádefineΣ shel∞ stacδ parameter≤ froφ áenviì
áááááááááááááááronment
     Entry:    None
     Exit:     HL = address of shell stack
               B = number of bytes in each shell stack entry
               A = number of possible entries, zero clear (NZ)
               A = 0, zero flag set (Z) if no shell stack
     Affected: AF¼ B¼ HL
     Usage:    Return≤ ádatß áoε thσ overal∞ shel∞ ástacδ ásysteφ ì
áááááááááááááááfroφ áthσ Environmen⌠ Descriptor«  Seσ SHPUS╚ áanΣ ì
áááááááááááááááSHPO╨ routine≤ fo≥ detail≤ oε othe≥ facilitie≤ fo≥ ì
ááááááááááááááádealinτ witΦ shel∞ stack≤ provideΣ b∙ Z3LIB.

     Routine║  GETSH2
     Function: Returε ádefineΣ shel∞ stacδ parameter≤ froφ áenviì
áááááááááááááááronment
     Entry:    None
     Exit:     HL = address of shell stack
               DE = number of bytes allowed in each stack entry
               B¼ A = number of allowed entries, zero clear (NZ)
               A = 0, zero set (Z) if no shell stack defined
     Affected: AF¼ B¼ DE¼ HL
     Usage:    Thi≤ ái≤ aε alternativσ routinσ t∩ árecove≥ áshel∞ ì
ááááááááááááááástacδ parameter≤ froφ thσ Environmen⌠ áDescriptor«  ì
áááááááááááááááFo≥ somσ uses¼ thi≤ forφ i≤ morσ easil∙ manipulatì
áááááááááááááááeΣ áthaε áGETSH▒ covereΣ above« á Seσ áSHPUS╚ áanΣ ì
áááááááááááááááSHPO╨ routine≤ fo≥ detail≤ oε othe≥ facilitie≤ fo≥ ì
ááááááááááááááádealinτ witΦ shel∞ stack≤ provideΣ b∙ Z3LIB.

WHEEL BYTE:

     Routine║  GETWHL
     Function║ Return the wheel byte value from the environment
     Entry:    None
     Exit:     A = wheel byte
               Flag≤ se⌠ accordingly║ ░ (no⌠ wheel⌐ ╜ Z¼ 0FFΦ (i≤ ì
áááááááááááááááwheel⌐ ╜ NZ
     Affected: AF
     Usage:    Restrict≤ user≤ froφ accessinτ part≤ oµ áprograms¼ ì
áááááááááááááááo≥ áaffectinτ prograφ flow«  Fo≥ example¼ yo⌡ áma∙ ì
áááááááááááááááno⌠ áwisΦ remotσ user≤ t∩ changσ thσ patΦ ádefiniì
ááááááááááááááátion« á B∙ assigninτ "n∩ wheeló statu≤ át∩ áremotσ ìèáááááááááááááááusers¼ áthσ áPAT╚ áutilit∙ wil∞ árefusσ át∩ áallo≈ ì
áááááááááááááááchanges¼ sincσ i⌠ sense≤ thσ privelege≤ witΦ áthi≤ ì
ááááááááááááááároutine«  Whilσ ß 0FFΦ valuσ i≤ listeΣ fo≥ ágrantì
áááááááááááááááinτ whee∞ priveleges¼ an∙ noε-zer∩ valuσ currentl∙ ì
ááááááááááááááásuffices.

     Routine║  PUTWHL
     Function║ Set the value of the wheel byte in the environment
     Entry:    A = wheel byte value to set (0=no wheel, 0FFh=wheel)
     Exit:     None
     Affected: None
     Usage:    Set≤ thσ whee∞ bytσ oε (0FFh⌐ o≥ ofµ (0)¼ áthereb∙ ì
ááááááááááááááágrantinτ o≥ denyinτ whee∞ privelege≤ t∩ áexecutinτ ì
áááááááááááááááprograms.

FLOW¼ ZEX¼ AN─ SUBMI╘ CONTROL:

FLO╫ áCONTROL:é  Al∞ commanΣ sequence≤ issueΣ unde≥ ZCPR│ ácaε ábσ ì
though⌠ t∩ executσ iε ß TRU┼ flo≈ contro∞ state«  Tha⌠ is¼ áwhenì
eve≥ ß commanΣ i≤ executeΣ unde≥ ZCPR3¼ thσ statσ oµ flo≈ contro∞ ì
i≤ TRUE«  Iµ thσ statσ oµ flo≈ contro∞ i≤ FALS┼ theε n∩ ácommand≤ ì
excep⌠ áflo≈ ácommand≤ wil∞ bσ executeΣ unti∞ thσ statσ áoµ áflo≈ ì
contro∞ become≤ TRUE.

Background║  Wheε ZCPR│ firs⌠ come≤ up¼ thσ statσ oµ flo≈ contro∞ ì
i≤ alway≤ TRUE«  An∙ commanΣ issueΣ wil∞ bσ executed«  Iµ ß áFlo≈ ì
CommanΣ áPackagσ i≤ installeΣ whicΦ support≤ thσ IF/ELSE/F╔ á(EnΣ ì
IF⌐ ácommands¼ theε thσ statσ oµ flo≈ contro∞ caε bσ ádynamicall∙ ì
changeΣ áb∙ use≥ commands¼ a≤ thσ followinτ termina∞ sessioε ái∞ì
lustrates:


     SCR>; any command will execute now
     SCR>era *.bak
     No Files
     SCR>dir
     MYFILE  .TXT  |  OBJECT  .BIN
     SCR>; we can set a flow control state to be false
     SCR>IF F
      IF F
     SCR>; no command will execute now
     SCR>dir
     SCR>else
      IF T
     SCR>dir
     MYFILE  .TXT  |  OBJECT  .BIN
     SCR>FI
      No IF
     SCR>

Hence¼ wheε an∙ commanΣ i≤ executed¼ beforσ thσ executioε actualì
l∙ ábegins¼ ZCPR│ wil∞ looδ t∩ seσ iµ thσ statσ oµ thσ flo≈ áconì
tro∞ ái≤ áTRUE«  SucΦ i≤ thσ casσ wheε wσ arσ no⌠ áwithiε áaε áI╞ ì
conditioε o≥ wheε wσ arσ withiε onσ o≥ morσ I╞ conditions¼ al∞ oµ ì
whicΦ arσ TRUE.

èZCPR│ áallow≤ yo⌡ t∩ bσ nesteΣ int∩ IF'≤ u≡ t∩ eigh⌠ á(8⌐ álevel≤ ì
deep«  Tha⌠ is¼ thσ structurσ oµ you≥ commanΣ sequence≤ caε átakσ ì
thσ followinτ forφ whicΦ caε bσ nesteΣ t∩ ╕ level≤ oµ IF's:


     <set of commands>
     IF T
          <set of commands>
          IF T
               <set of commands>
               IF T
                    <set of commands>
               FI
               <set of commands>
          ELSE
               <set of non-executed commands>
               IF T
                    <set of non-executed commands>
               FI
          FI
     ELSE
          <set of non-executed commands>
     FI

CommanΣ ástructure≤ likσ thosσ presenteΣ abovσ arσ áno≈ ápossiblσ ì
unde≥ ZCPR3«  Iε essence¼ ZCPR│ command≤ caε no≈ takσ thσ forφ oµ ì
ß programminτ languagσ iε thei≥ owε right.

Thσ áse⌠ oµ routine≤ availablσ iε thi≤ par⌠ oµ Z3LI┬ arσ useΣ át∩ ì
providσ áyo⌡ witΦ ß simplσ interfacσ t∩ contro∞ thσ flo≈ ácontro∞ ì
withiε (anΣ outside⌐ you≥ program«  Yo⌡ caε issuσ command≤ to:
   o Enter the next IF level in TRUE or FALSE condition
   o Toggle the state of the current IF level
   o Drop down to the previous IF level
   o Determine the current IF level number
   o Or multiples of the above

     Routine║  IFEND
     Function║ Drop to previous IF level
     Entry:    None
     Exit:     A <> 0, zero flag clear (NZ) if successful
               A = 0, zero flag set (Z) if no IF level
     Affected: AF
     Usage:    Terminate≤ áthσ curren⌠ I╞ leve∞ anΣ drop≤ t∩ áthσ ì
ááááááááááááááápreviou≤ I╞ level¼ iµ thσ prograφ i≤ withiε onσ o≥ ì
ááááááááááááááámorσ áIF's« á Fo≥ ß transien⌠ áprogram¼ átherσ ái≤ ì
áááááááááááááááeithe≥ án∩ I╞ level¼ o≥ therσ i≤ ß TRU┼ flo≈ áconì
ááááááááááááááátro∞ statσ (al∞ preceedinτ IF'≤ arσ TRUE).

     Routines║ IFT¼ IFF
     Function║ Raisσ anΣ se⌠ I╞ level
     Entry:    None
     Exit:     A <> 0, zero flag clear (NZ) if IF level OK
               A = 0, zero set (Z) on IF level overflow
     Affected: AF
     Usage:    IF╘ áset≤ I╞ leve∞ t∩ TRUE¼ IF╞ set≤ I╞ áleve∞ át∩ ìèáááááááááááááááFALSE« á Thesσ routine≤ arσ useΣ t∩ se⌠ flo≈ áconì
ááááááááááááááátro∞ ástate≤ áanΣ raisσ thσ I╞ álevel« á Thσ áflo≈ ì
ááááááááááááááácontro∞ ástatσ caε suppor⌠ u≡ t∩ eigh⌠ (8⌐ álevel≤ ì
áááááááááááááááoµ IF's«  IF╘ anΣ IF╞ returε erro≥ code≤ fo≥ overì
áááááááááááááááflo≈ ácondition≤ whicΦ shoulΣ bσ senseΣ t∩ áinsurσ ì
áááááááááááááááthσ integrit∙ oµ thσ program.

     Routine║  IFTEST
     Function║ Determine the current IF level
     Entry:    None
     Exit:     A = number of current IF level
               Zero flag i≤ se⌠ accordingly
     Affected: AF
     Usage:    Determine≤ áthσ ácurren⌠ I╞ level« á Thσ áreturneΣ ì
áááááááááááááááleve∞ valuσ range≤ froφ ░ t∩ 8«  Iµ A=0¼ therσ ái≤ ì
ááááááááááááááán∩ ácurren⌠ IF«  Thσ zer∩ flaτ i≤ se⌠ áaccordingl∙ ì
ááááááááááááááát∩ allo≈ rapiΣ testing.
     Example:

                         EX╘       IFTEST         ; declare the routine
                         ...                      ; ..preceeding code
                         CALL      IFTEST         ; get current IF level
                         JR        Z,NOIF         ; ..jump if none
                         CP        8              ; is it at max level?
                         JR        Z,ATMAX        ; ..jump if at max IF level
                         ...                      ; else carry shows empty levels

     Routine║  IFELSE
     Function║ Toggle TRUE/FALSE state of current IF level
     Entry:    None
     Exit:     A <> 0, zero flag clear (NZ) if successful
               A = 0, zero flag set (Z) if no current IF
     Affected: AF
     Usage:    Toggle≤ thσ curren⌠ statσ oµ thσ curren⌠ I╞ level«  ì
áááááááááááááááIµ ácalleΣ aε eveε numbe≥ oµ times¼ thσ ástatσ ái≤ ì
áááááááááááááááeffectivel∙ unchanged.

ZE╪ áACCES╙ áAN─ CONTROL:é  Thσ ZE╪ commanΣ filσ áfacilit∙ á(unde≥ ì
ZCPR│ only⌐ caε bσ controlleΣ b∙ thi≤ se⌠ oµ Z3LI┬ routines«  ZE╪ ì
intercept≤ al∞ BIO╙ call≤ fo≥ input¼ and¼ wheε iε intercep⌠ mode¼ ì
i⌠ áprovide≤ inpu⌠ froφ tex⌠ containeΣ iε it≤ ámemor∙-baseΣ átex⌠ ì
buffe≥ rathe≥ thaε allowinτ thσ use≥ t∩ inpu⌠ character≤ froφ thσ ì
keyboard«  Thesσ routine≤ arσ useΣ t∩ quer∙ thσ statu≤ oµ ZE╪ anΣ ì
t∩ áinstruc⌠ ZE╪ t∩ continuσ interceptinτ character≤ o≥ át∩ ásto≡ ì
interceptinτ character≤ anΣ allo≈ use≥ input.

Thi≤ áse⌠ áoµ routine≤ provide≤ acces≤ t∩ áthσ áZE╪ ámemor∙-baseΣ ì
commanΣ filσ processo≥ anΣ it≤ environment«  Yo⌡ caε takσ contro∞ ì
oµ ZE╪ througΦ thesσ routines.

Summary of Routines:

     GETZEX -- get the ZEX control message
     GETZFC -- get the first character in ZEX buffer
     GETZNC -- get the next character to be returned
     GETZRUN -- get ZEX running flag
è     HALTZEX -- terminate the ZEX processor
     PUTZEX -- set the ZEX control message
     PUTZNC -- set the next character to be returned
     PUTZRUN -- set ZEX running flag
     STOPZEX -- suspend ZEX execution
     STRTZEX -- resume ZEX execution from a STOPZEX

ZEX DATA:

     Routine║  GETZFC
     Function║ Return address of first character in ZEX buffer
     Entry:    None
     Exit:     HL = address of first character in ZEX script buffer
               A = character at that address
               Carry clear (NC) if data
               Carry flag set (C) if no text data in buffer
     Affected: AF¼ HL
     Usage:    UseΣ t∩ examinσ thσ scrip⌠ datß fo≥ ß runninτ áZE╪ ì
áááááááááááááááscrip⌠ sequence.

     Routine║  GETZNC
     Function║ Get next character ZEX will process
     Entry:    None
     Exit:     HL = address of next character in ZEX text buffer
               ┴ ╜ nex⌠ characte≥ t∩ bσ returned¼ carr∙ clea≥ áiµ ì
ááááááááááááááávalid¼ carr∙ flaτ se⌠ (C⌐ iµ n∩ tex⌠ datß remains
     Affected: AF¼ HL
     Usage:    Ma∙ ábσ áuseΣ t∩ effec⌠ change≤ t∩ ß árunninτ áZE╪ ì
áááááááááááááááprograφ b∙ examininτ thσ nex⌠ characte≥ tha⌠ áwil∞ ì
ááááááááááááááábσ returned.

     Routine║  GETZRUN
     Function║ Determine run status of ZEX from run message byte
     Entry:    None
     Exit:     A = run message
               Zero set accordingly (0=not running)
               Carry flag set (C) if no message available
     Affected: AF
     Usage:    Return≤ áthσ ZE╪ ruε messagσ bytσ anΣ áset≤ áflag≤ ì
áááááááááááááááindicatinτ statu≤ as║  zer∩ flaτ i≤ se⌠ (Z⌐ iµ ZE╪ ì
áááááááááááááááno⌠ runninτ o≥ clea≥ (NZ⌐ iµ i⌠ is╗ carr∙ flaτ ái≤ ì
áááááááááááááááse⌠ á(C⌐ iµ therσ i≤ n∩ messagσ o≥ clea≥ á(NC⌐ áiµ ì
ááááááááááááááátherσ is.

     Routine║  PUTZNC
     Function║ Set address of next ZEX character (GOTO)
     Entry:    HL = address of next character ZEX will return
     Exit:     Carry flag clear (NC) if operation successful
               Carry set (C) if ZEX buffers not available
     Affected: AF
     Usage:    Set≤ thσ addres≤ oµ thσ nex⌠ characte≥ whicΦ áwil∞ ì
ááááááááááááááábσ áreaΣ áb∙ ZEX«  Usinτ thi≤ routinσ áprovide≤ áß ì
áááááááááááááááGOT╧ functioε fo≥ ZE╪ control.
.pa
è     Routine║  PUTZRUN
     Function║ Set value of ZEX running message byte
     Entry:    A = value of ZEX running message byte
     Exit:     Carry flag set (C) if no message buffers
     Affected: AF
     Usage:    Set≤ áthσ ZE╪ runninτ messagσ bytσ t∩ ß áuse≥-supì
áááááááááááááááplie≤ ávalue« á It≤ purposσ i≤ át∩ áallo≈ árunninτ ì
áááááááááááááááprogram≤ át∩ ádisablσ o≥ suspenΣ áZE╪ áprocessing«  ì
áááááááááááááááSe⌠ t∩ zer∩ t∩ sto≡ ZE╪ processing.

ZEX STATUS AND CONTROL:

     Routine║  GETZEX
     Function║ Return ZEX control message byte
     Entry:    None
     Exit:     A = ZEX control message (0,1,2)
               Zero set accordingly
     Affected: AF
     Usage:    Allow≤ program≤ t∩ determinσ thσ curren⌠ statσ áoµ ì
áááááááááááááááZEX«  Thσ contro∞ messagσ bytσ caε havσ onσ oµ thσ ì
áááááááááááááááfollowinτ threσ values:
                     0 = Normal«  ZE╪ i≤ runninτ anΣ interceptinτ ì
áááááááááááááááááááááááááBIO╙ calls.
                     1 = ZCPR│ Prompt«  ZE╪ i≤ alloweΣ t∩ ruε anΣ ì
áááááááááááááááááááááááááintercep⌠ áBIO╙ ácalls¼ bu⌠ áZE╪ áthink≤ ì
ááááááááááááááááááááááááátha⌠ i⌠ i≤ providinτ inpu⌠ t∩ thσ áZCPR│ ì
ááááááááááááááááááááááááácommanΣ áprocesso≥ directl∙ (ZE╪ i≤ áno⌠ ì
áááááááááááááááááááááááááprovidinτ inpu⌠ t∩ an∙ program).
                     2 = ZE╪ Suspended«  ZE╪ i≤ no⌠ áinterceptinτ ì
áááááááááááááááááááááááááBIO╙ call≤ anΣ use≥ inpu⌠ i≤ allowed.

               ┴ á▒ codσ shoulΣ neve≥ bσ seeε b∙ ß prograφ ásincσ ì
ááááááááááááááái⌠ i≤ se⌠ b∙ ZCPR│ anΣ cleareΣ t∩ ░ afte≥ ZE╪ áha≤ ì
ááááááááááááááácompleteΣ thσ commanΣ linσ input«  An∙ ZE╪ contro∞ ì
ááááááááááááááámessagσ i≤ rese⌠ upoε executioε oµ ZCPR│ t∩ ░ wheε ì
áááááááááááááááZCPR│ ái≤ áentereΣ anΣ theε t∩ ▒ áwheε áthσ áZCPR│ ì
ááááááááááááááápromp⌠ áappear≤ á(ZCPR│ input)«  Wheε áZCPR│ ácomì
áááááááááááááááplete≤ áit≤ input¼ i⌠ reset≤ thσ ZE╪ contro∞ ámesì
ááááááááááááááásagσ t∩ 0.

     Routine║  PUTZEX
     Function║ Set ZEX control message byte (change ZEX state)
     Entry:    A = ZEX control message byte (0¼ 1¼ 2)
     Exit:     None
     Affected: None
     Usage:    Allow≤ ß prograφ t∩ se⌠ thσ statσ tha⌠ ZE╪ i≤ áin«  ì
áááááááááááááááThi≤ contro∞ messagσ bytσ mus⌠ onl∙ bσ se⌠ t∩ áonσ ì
áááááááááááááááoµ thesσ values:
                     0 = Normal«  ZE╪ i≤ runninτ anΣ interceptinτ ì
áááááááááááááááááááááááááBIO╙ calls.
                     1 = ZCPR│ Prompt«  ZE╪ i≤ alloweΣ t∩ ruε anΣ ì
áááááááááááááááááááááááááintercep⌠ BIO╙ call≤ bu⌠ ZE╪ think≤ tha⌠ ì
ááááááááááááááááááááááááái⌠ i≤ providinτ inpu⌠ t∩ thσ ZCPR│ ácomì
ááááááááááááááááááááááááámanΣ áprocesso≥ ádirectl∙ á(ZE╪ ái≤ áno⌠ ì
áááááááááááááááááááááááááprovidinτ inpu⌠ t∩ an∙ program).
è                     2 = ZE╪ Suspended«  ZE╪ i≤ no⌠ áinterceptinτ ì
áááááááááááááááááááááááááBIO╙ call≤ anΣ use≥ inpu⌠ i≤ allowed.

               ┴ ▒ codσ ma∙ bσ se⌠ b∙ an∙ prograφ iµ i⌠ want≤ ZE╪ ì
ááááááááááááááát∩ á"thinkó tha⌠ i⌠ i≤ providinτ inpu⌠ át∩ áZCPR3«  ì
áááááááááááááááIµ áZE╪ wa≤ previousl∙ suspended¼ i⌠ áadvance≤ át∩ ì
áááááááááááááááthσ beginninτ oµ thσ nex⌠ linσ anΣ resume≤ wheε i⌠ ì
ááááááááááááááásee≤ thi≤ code«  An∙ ZE╪ contro∞ messagσ i≤ árese⌠ ì
áááááááááááááááupoε executioε oµ ZCPR│ t∩ ░ wheε ZCPR│ i≤ entereΣ ì
áááááááááááááááanΣ theε t∩ ▒ wheε thσ ZCPR│ promp⌠ appear≤ (ZCPR│ ì
áááááááááááááááinput)«  Wheε ZCPR│ complete≤ it≤ input¼ i⌠ reset≤ ì
áááááááááááááááthσ ZE╪ contro∞ messagσ t∩ 0.

     Routine║  HALTZEX
     Function║ Halt ZEX completely by setting ZEX end-of-file
     Entry:    None
     Exit:     A <> 0, zero flag clear (NZ) if ZEX is halted
               A = 0, zero flag set (Z) if ZEX i≤ not running
     Affected: AF
     Usage:    Terminate≤ áexecutioε áoµ ZE╪ ácompletely« á Othe≥ ì
ááááááááááááááároutine≤ providσ temporar∙ executioε contro∞ ásucΦ ì
áááááááááááááááa≤ áSTOPZE╪ (suspenΣ execution)¼ anΣ STRTZE╪ á(reì
ááááááááááááááásumσ execution)¼ bu⌠ HALTZE╪ cause≤ ZE╪ t∩ átermiì
ááááááááááááááánatσ itselµ completel∙ b∙ settinτ thσ nex⌠ characì
áááááááááááááááte≥ ZE╪ wil∞ proces≤ t∩ thσ terminatioε ácharacte≥ ì
áááááááááááááááoµ 0FFh.

     Routine║  STOPZEX
     Function║ Temporarily suspend ZEX script processing
     Entry:    None
     Exit:     None╗ ZEX control message byte is set to 2
     Affected: None
     Usage:    Temporaril∙ stop≤ ZE╪ froφ interceptinτ BIO╙ call≤ ì
áááááááááááááááanΣ allow≤ thσ use≥ t∩ inpu⌠ characters«  Thi≤ ái≤ ì
áááááááááááááááß shorthanΣ t∩ placinτ thσ ▓ contro∞ codσ int∩ thσ ì
áááááááááááááááZE╪ contro∞ messagσ byte.

     Routine║  STRTZEX
     Function║ Start processing from ZEX script
     Entry:    None
     Exit:     None
     Affected: None
     Usage:    Allow≤ áZE╪ t∩ intercep⌠ BIO╙ call≤ áanΣ áprevent≤ ì
áááááááááááááááuse≥ froφ inputtinτ characters«  Thi≤ i≤ ß áshortì
áááááááááááááááhanΣ át∩ placinτ thσ ░ contro∞ codσ int∩ áthσ áZE╪ ì
ááááááááááááááácontro∞ messagσ byte.

SUBMI╘ AN─ XSU┬ CONTROL:é  Iε enhancinτ thσ ZCPR│ commanΣ áprocesì
sor≤ anΣ defininτ thσ extendeΣ environment¼ provision≤ werσ áals∩ ì
madσ át∩ contro∞ prograφ flo≈ froφ SUBMI╘ anΣ XSU┬ áutilitie≤ áiε ì
thσ samσ manne≥ a≤ thσ memor∙-baseΣ ZE╪ processinτ covereΣ áelseì
where.

SUBMI╘ áprocessinτ i≤ determineΣ viß flag≤ anΣ othe≥ datß áwithiε ì
ZCP╥ áVersioε á3.│ anΣ later«  Routine≤ supportinτ áit≤ áfeature≤ ìèmus⌠ havσ acces≤ t∩ thσ commanΣ processor«  I⌠ i≤ you≥ áresponsiì
bilit∙ t∩ insurσ tha⌠ thσ processo≥ i≤ no⌠ overwritten.

Thσ ácombinatioε áoµ SUBMI╘ witΦ aε XSU┬-likσ áutilit∙ áforφ áthσ ì
basi≤ oµ ß disδ-baseΣ corollar∙ t∩ ZE╪ fo≥ use≤ wherσ ß largσ TP┴ ì
space¼ áo≥ áver∙ largσ script≤ mus⌠ bσ áprocessed« á "Hooksó áarσ ì
thereforσ provideΣ witΦ thesσ routine≤ t∩ enablσ sucΦ ß facility.

SUBMI╘ DAT┴ AN─ CONTROL:

     Routine║  SUBON
     Function║ Determine whether SUBMIT processing is enabled
     Entry:    None
     Exit:     Zero clear (NZ) if SUBMIT is enabled
               Zero set (Z) if no ZCPR 3.3 or SUBMIT disabled
               A = destroyed
     Affected: AF
     Usage:    Require≤ áZCP╥ 3.│ o≥ later« á Determine≤ áwhethe≥ ì
áááááááááááááááthσ áSUBMI╘ áfacilit∙ withiε ZCP╥ versioε á3.│ áo≥ ì
ááááááááááááááálate≥ i≤ enabled«  Aε erro≥ statu≤ i≤ returneΣ áiµ ì
áááááááááááááááSUBMI╘ ái≤ disabled¼ o≥ thσ commanΣ áprocesso≥ ái≤ ì
áááááááááááááááno⌠ ZCP╥ 3.│ o≥ later«  Thσ commanΣ processo≥ mus⌠ ì
áááááááááááááááno⌠ havσ beeε overwritten.

     Routine║  HALTSUB
     Function║ Terminate an executing SUBMIT job
     Entry:    None
     Exit:     None; the $$$.SUB filσ is deleted
     Affected: None
     Usage:    Stop≤ áaε áexecutinτ SUBMI╘ joΓ áb∙ ádeletinτ áthσ ì
ááááááááááááááá$$$.SU┬ filσ addresseΣ iε thσ ZCP╥ 3.│ submi⌠ FCB.

     Routine║  GETSRUN
     Function║ Return flag indicating SUBMIT job status
     Entry:    None
     Exit:     A <> 0, zero clear (NZ) if SUBMIT job is running
               A = 0, zero set (Z) if SUBMIT is not running
     Affected: AF
     Usage:    Determine≤ whethe≥ wσ arσ currentl∙ runninτ withiε ì
áááááááááááááááß SUBMI╘ job«  Thi≤ i≤ sometime≤ necessar∙ áinforì
ááááááááááááááámatioε át∩ ádeterminσ possiblσ áaction≤ áwithiε áß ì
áááááááááááááááprogram.

     Routine║  GETSFCB
     Function║ Return the ZCPR 3.3 or later submit FCB address
     Entry:    None
     Exit:     DE = address of SUBMIT FCB (undefined if error)
               A <> 0, zero flag clear (NZ) if OK
               A = 0, zero set (Z) if no SUBMIT or ZCPR 3.3
     Affected: AF¼ DE
     Usage:    Require≤ ZCP╥ 3.│ o≥ later«  Thi≤ routinσ áreturn≤ ì
áááááááááááááááthσ áSUBMI╘ FC┬ addres≤ froφ ZCP╥ versioε á3.│ áo≥ ì
ááááááááááááááálate≥ FCB«  Aε erro≥ statu≤ i≤ returneΣ iµ áSUBMI╘ ì
ááááááááááááááái≤ no⌠ enableΣ o≥ thσ commanΣ processo≥ i≤ no⌠ áoµ ì
áááááááááááááááthσ árigh⌠ type«  Thσ commanΣ processo≥ ámus⌠ áno⌠ ìèáááááááááááááááhavσ beeε overwritten.

XSU┬ DAT┴ AN─ CONTROL:

     Routine║  STOPXSUB
     Function║ Reset XSUB input redirection flag
     Entry:    None
     Exit:     None; XSUB is halted
     Affected: None
     Usage:    Stop≤ áXSU┬ prograφ flo≈ fo≥ loca∞ consolσ áinput«  ì
áááááááááááááááThi≤ ái≤ accomplisheΣ b∙ resettinτ ß flaτ áiε áthσ ì
ááááááááááááááámessagσ buffer.

     Routine║  GXSUB
     Function║ Return the value of the XSUB redirection flag
     Entry:    None
     Exit:     A = value of the XSUB redirection flag
     Affected: AF
     Usage:    Determine≤ áiµ áinpu⌠ t∩ thσ árunninτ áprograφ ái≤ ì
ááááááááááááááácominτ áfroφ aε XSU┬ utility«  Thi≤ i≤ áusefu∞ áiε ì
áááááááááááááááerro≥ condition≤ wherσ thσ norma∞ flo≈ oµ command≤ ì
áááááááááááááááanΣ datß mus⌠ bσ altereΣ fo≥ operato≥ input.

     Routine║  PXSUB
     Function║ Set the XSUB input redirection flag
     Entry:    A = value to set XSUB input redirection flag
     Exit:     None; the value is set
     Affected: None
     Usage:    Activate≤ XSU┬ processinτ froφ ß commanΣ scrip⌠ o≥ ì
áááááááááááááááSU┬ áfile«  B∙ settinτ thσ XSU┬ redirectioε áflag¼ ì
áááááááááááááááprograφ flo≈ caε bσ dynamicall∙ altered«  Unti∞ áß ì
ááááááááááááááábette≥ ádefinitioε i≤ developed¼ i⌠ ái≤ ásuggesteΣ ì
ááááááááááááááátha⌠ áthσ ácommanΣ byte≤ useΣ fo≥ ZE╪ ábσ áapplieΣ ì
ááááááááááááááá(seσ GETZEX).

ZCPR│ áMESSAGES:é  ZCPR│ offer≤ man∙ feature≤ no⌠ founΣ áiε áCP/M¼ ì
ZCPR1¼ áo≥ áZCPR2«  Onσ ver∙ specia∞ featurσ i≤ tha⌠ áoµ ácommanΣ ì
processo≥ messages.

ZCPR│ ásupport≤ ß messagσ buffe≥ whicΦ contain≤ ß numbe≥ oµ ámesì
sage≤ áwhicΦ caε bσ passeΣ froφ onσ transien⌠ prograφ t∩ áanothe≥ ì
o≥ ábetweeε áZCPR│ itselµ anΣ al∞ transien⌠ áprogram≤ áwhicΦ áruε ì
unde≥ it«  Command≤ caε bσ giveε directl∙ t∩ ZCPR3¼ statu≤ inforì
matioε caε bσ passeΣ froφ ZCPR│ t∩ thσ transients¼ anΣ botΦ statì
u≤ áanΣ ácommand≤ ácaε bσ passeΣ froφ onσ átransien⌠ át∩ áanothe≥ ì
througΦ thesσ messages.

These message can be divided into six basic classes:
   o Messages which command ZCPR3
   o Status messages sent by ZCPR3
   o ZEX command messages
   o Statu≤ áanΣ commanΣ message≤ sen⌠ b∙ onσ prograφ t∩ áanothe≥ ì
áááááwhicΦ arσ ignoreΣ b∙ ZCPR3
   o User-defined messages
   o Reserved messages
è
Beforσ áusinτ an∙ Z3LI┬ routine≤ t∩ acces≤ thesσ ámessages¼ áyou≥ ì
prograφ shoulΣ ensurσ tha⌠ thσ messagσ buffe≥ i≤ availablσ t∩ it«  ì
Thi≤ ácaε easil∙ bσ donσ b∙ callinτ thσ GETMS╟ routinσ á(seσ áthσ ì
screeε oε thσ  ZCPR│ environment)«  GETMS╟ return≤ witΦ thσ ázer∩ ì
flaτ se⌠ (Z⌐ iµ n∩ ZCPR│ messagσ buffe≥ exists«  Hence:

               EX╘       GETMS╟              ; declare the routine
               ...
               CALL      GETMSG              ; get message buffer status
               JR        Z,NOZ3MSGS          ; ..jump if no msgs to read
               ...

Thσ áfollowinτ summarize≤ facilitie≤ availablσ througΦ thσ áZCPR│ ì
messagσ buffer.

Message≤ whicΦ CommanΣ ZCPR3:é  Somσ oµ thσ message≤ iε thσ áZCPR│ ì
messagσ ábuffe≥ arσ se⌠ b∙ externa∞ program≤ (transient≤ o≥ ácomì
manΣ ápackages⌐ áanΣ arσ reaΣ anΣ interpreteΣ áb∙ áZCPR3« á Thesσ ì
message≤ are:
   o Curren⌠ I╞ leve∞ anΣ activσ (T/F⌐ statu≤ oµ al∞ I╞ levels
   o Whethe≥ áaε erro≥ handle≥ i≤ availablσ anΣ wha⌠ thσ ácommanΣ ì
ááááálinσ t∩ invokσ i⌠ is

Statu≤ Message≤ Sen⌠ b∙ ZCPR3:é  Somσ oµ thσ message≤ iε thσ ZCPR│ ì
messagσ ábuffe≥ áarσ se⌠ onl∙ b∙ ZCPR│ o≥ ß ZCPR│ shel∞ áanΣ áarσ ì
intendeΣ át∩ bσ useΣ a≤ R/╧ message≤ b∙ transients« á Thesσ ámesì
sage≤ are:
   o ZCPR│ commanΣ statu≤ ¡¡ thσ transien⌠ loadeΣ i≤ o≥ i≤ no⌠ áß ì
áááááshell¼ anΣ thσ transien⌠ loadeΣ i≤ o≥ i≤ no⌠ aε erro≥ áhandì
áááááler
   o Erro≥ áaddres≤ ¡¡ iµ thσ transien⌠ loadeΣ i≤ aε erro≥ áhandì
áááááler¼ thi≤ i≤ thσ addres≤ oµ thσ firs⌠ characte≥ oµ thσ ácomì
ááááámanΣ linσ whicΦ wa≤ iε error

ZE╪ áCommanΣ Messages:é  Onσ messagσ iε thσ ZCPR│ messagσ ábuffer≤ ì
i≤ áintendeΣ át∩ directl∙ senΣ command≤ t∩ thσ áZE╪ ámemor∙-baseΣ ì
commanΣ áfilσ processor«  Thi≤ messagσ bytσ tell≤ ZE╪ threσ ádifì
feren⌠ things:
   o Ruε normall∙ ¡¡ ZE╪ i≤ t∩ intercep⌠ inpu⌠ call≤ anΣ áprovidσ ì
ááááácharacter≤ iε placσ oµ consolσ input
   o ZCPR│ i≤ promptinτ ¡¡ ZE╪ i≤ providinτ inpu⌠ directl∙ t∩ thσ ì
ááááácommanΣ processo≥ ZCPR3
   o SuspenΣ áintercep⌠ á¡¡ ZE╪ i≤ t∩ sto≡ áinterceptinτ áconsolσ ì
áááááinpu⌠ áanΣ allo≈ inpu⌠ froφ thσ consolσ unti∞ norma∞ áexecuì
ááááátioε o≥ thσ ZCPR│ promp⌠ appears

Message≤ IgnoreΣ b∙ ZCPR3:é  Tw∩ prσ-defineΣ message≤ arσ áignoreΣ ì
b∙ ZCPR3«  Thσ firs⌠ i≤ thσ prograφ erro≥ code«  Thi≤ bytσ caε bσ ì
se⌠ b∙ an∙ prograφ unde≥ ZCPR│ t∩ indicatσ ß returε statu≤ t∩ thσ ì
nex⌠ program«  Thσ conventioε ha≤ beeε adopteΣ tha⌠ iµ thi≤ ábytσ ì
i≤ á0¼ átheε thσ prograφ completeΣ successfully«  Iµ i⌠ ái≤ ánoε-ì
zero¼ áthσ prograφ faileΣ fo≥ somσ reasoε anΣ thσ valuσ áoµ áthi≤ ì
codσ indicate≤ tha⌠ reasoε t∩ ß followinτ program.

Thσ áseconΣ messagσ i≤ thσ registe≥ buffer«  Teε onσ-bytσ áregi≤ìèter≤ arσ availablσ anΣ caε bσ testeΣ b∙ thσ Flo≈ CommanΣ Package«  ì
Condition≤ álikσ "I╞ ░ 5ó (I╞ Registe≥ ░ ╜ 5⌐ caε bσ átesteΣ áanΣ ì
processeΣ áb∙ thσ Flo≈ Command Package¼ anΣ othe≥ transien⌠ ápr∩ì
gram≤ o≥ residen⌠ commanΣ package≤ caε manipulatσ thesσ áregiste≥ ì
values.

Use≥-DefineΣ áMessages:é  ┴ se⌠ oµ 1╢ message≤ arσ áavailablσ áfo≥ ì
use≥ ádefinition«  EacΦ messagσ i≤ onσ bytσ long¼ anΣ Z3LI┬ árouì
tine≤ arσ provideΣ t∩ placσ value≤ int∩ thesσ message≤ anΣ áquer∙ ì
them.

ReserveΣ Messages:é  ┴ se⌠ oµ 1╢ onσ-bytσ message≤ i≤ reserveΣ fo≥ ì
futurσ usσ iε thσ ZCPR│ systeφ anΣ shoulΣ no⌠ bσ useΣ b∙ applicaì
tion≤ áprogrammers«  Z3LI┬ doe≤ no⌠ providσ acces≤ t∩ thesσ ámesì
sages.

COMMAN─ STATU╙ MESSAGE:é  Thesσ message≤ returε thσ statu≤ oµ áthσ ì
curren⌠ átransien⌠ a≤ se⌠ b∙ ZCPR3«  An∙ transien⌠ ha≤ ábeeε áinì
vokeΣ iε onσ oµ threσ possiblσ states:
     1.A≤ ß "normaló transient¼ executeΣ a⌠ thσ reques⌠ oµ áthσ ì
use≥ o≥ anothe≥ program
     2.A≤ ß "shell"¼ invokeΣ b∙ ZCPR│ itself
     3.A≤ áaε "erro≥ handler"¼ invokeΣ b∙ ZCPR│ itselµ wheε ái⌠ ì
canno⌠ áproces≤ thσ curren⌠ commanΣ linσ (canno⌠ finΣ ß ámatchinτ ì
CO═ filσ o≥ CMDRU╬ facility)

     Routine║  GETCST
     Function║ Return the ZCPR3 command status message
     Entry:    None
     Exit:     A = message code (zero flag set accordingly)
     Affected: AF
     Usage:    Return≤ thσ ZCPR│ commanΣ statu≤ messagσ whicΦ ái≤ ì
áááááááááááááááalway≤ se⌠ b∙ ZCPR│ anΣ no⌠ intendeΣ t∩ bσ se⌠ áb∙ ì
áááááááááááááááan∙ program«  I⌠ caε havσ onσ oµ threσ values:
                    0 = this is a "normal" transient
                    1 = this is a "shell"
                    2 = this is an "error handler"

     Routine║  PUTCST
     Function║ Set the ZCPR3 command status message
     Entry:    A = ZCPR3 command status message value (0, 1, or 2)
     Exit:     None
     Affected: None
     Usage:    ProvideΣ t∩ allo≈ ß ZCPR│ shel∞ prograφ t∩ se⌠ thσ ì
áááááááááááááááZCPR│ ácommanΣ ástatu≤ messagσ byte« á I⌠ ái≤ áno⌠ ì
áááááááááááááááintendeΣ fo≥ genera∞ usσ b∙ applicatioε áprograms«  ì
áááááááááááááááAllowablσ ávalue≤ fo≥ thσ commanΣ ástatu≤ ámessagσ ì
áááááááááááááááare:
                    0 = this is a "normal" transient
                    1 = this is a "shell"
                    2 = this is an "error handler"
.pa
è     Routine║  QERROR
     Function║ Test command status message for error handler
     Entry:    None
     Exit:     A = message code
               Zer∩ áse⌠ á(Z⌐ iµ transien⌠ i≤ aε áerro≥ áhandler¼ ì
áááááááááááááááelsσ clea≥ (NZ)
     Affected: AF
     Usage:    UseΣ áa≤ ß quicδ tes⌠ t∩ seσ iµ thσ ZCPR│ ácommanΣ ì
ááááááááááááááástatu≤ messagσ indicate≤ tha⌠ thσ curren⌠ átransiì
áááááááááááááááen⌠ i≤ aε erro≥ handler«  Thσ ZCPR│ commanΣ statu≤ ì
ááááááááááááááámessagσ i≤ reaΣ anΣ testeΣ agains⌠ thσ erro≥ handì
ááááááááááááááále≥ codσ value«   Zer∩ flaτ i≤ se⌠ iµ thσ ácurren⌠ ì
ááááááááááááááátransien⌠ i≤ aε erro≥ handler.

     Routine║  QSHELL
     Function║ Test command status message for shell transient
     Entry:    None
     Exit:     A = message code
               Zero set (Z) if transient is shell
     Affected: AF
     Usage:    UseΣ áa≤ ß quicδ tes⌠ t∩ seσ iµ thσ ZCPR│ ácommanΣ ì
ááááááááááááááástatu≤ messagσ indicate≤ tha⌠ thσ curren⌠ átransiì
áááááááááááááááen⌠ i≤ ß shell«  Thσ ZCPR│ commanΣ statu≤ ámessagσ ì
ááááááááááááááái≤ áreaΣ anΣ testeΣ agains⌠ thσ shel∞ codσ ávalue«  ì
áááááááááááááááZer∩ áflaτ ái≤ se⌠ iµ thσ curren⌠ transien⌠ ái≤ áß ì
áááááááááááááááshell.

ERRO╥ FLA╟ AN─ ERRO╥ COMMAND:é  Thi≤ se⌠ oµ routine≤ perform≤ áthσ ì
followinτ functions:
     ERRADRÅ¡-return≤ thσ addres≤ oµ thσ firs⌠ characte≥ oµ áthσ ì
áááááááááácommanΣ linσ iε error
     GETER1 -- returns the error flag
     PUTER1 -- sets the error flag
     GETERCÅ¡-return≤ thσ addres≤ oµ thσ firs⌠ characte≥ oµ áthσ ì
ááááááááááerro≥ handle≥ commanΣ line
     PUTERC -- set the error handler command line

     Routine║  ERRADR
     Function: Oε erro≥ returε firs⌠ characte≥ oµ erroreΣ commanΣ ì
áááááááááááááááline
     Entry:    None
     Exit:     HL = address of first character of error line
     Affected: HL
     Usage:    Assuminτ átha⌠ thσ curren⌠ transien⌠ i≤ áaε áerro≥ ì
áááááááááááááááhandler¼ (cal∞ t∩ QERRO╥ returninτ witΦ zer∩ áflaτ ì
áááááááááááááááset)¼ áthi≤ ároutinσ return≤ thσ áaddres≤ áoµ áthσ ì
áááááááááááááááfirs⌠ ácharacte≥ oµ thσ commanΣ linσ whicΦ wa≤ áiε ì
áááááááááááááááerror«  Fo≥ example¼ iµ thσ command:

                    xxx params;dir
               i≤ áissueΣ áanΣ XXX.CO═ canno⌠ ábσ áfound¼ áERRAD╥ ì
áááááááááááááááreturn≤ áthσ addres≤ oµ thσ firs⌠ characte≥ á("X"⌐ ì
áááááááááááááááoµ thσ string:

                    DEF┬      'XXX PARAMS;DIR',0
.pa
è     Routine║  GETER1
     Function║ Return error flag
     Entry:    None
     Exit:     A <> 0, zero flag clear (NZ) if error present
               A = 0, zero set (Z) if no error
     Affected: AF
     Usage:    Return≤ áthσ áerro≥ flaτ iε A« á GETER▒ áha≤ ábeeε ì
áááááááááááááááredefineΣ froφ thσ origina∞ purposσ oµ determininτ ì
áááááááááááááááerro≥ áhandle≥ presencσ anΣ no≈ onl∙ áreturn≤ áthσ ì
ááááááááááááááávaluσ oµ thσ erro≥ flag.

     Routine║  PUTER1
     Function: Engagσ anΣ disengagσ erro≥ handle≥ flaτ [n∩ longe≥ ì
áááááááááááááááused]
     Entry:    None
     Exit:     None
     Affected: None
     Usage:    Thi≤ ároutinσ án∩ longe≥ perform≤ ß áfunctioε áanΣ ì
ááááááááááááááásimpl∙ return≤ t∩ thσ callinτ program.

     Routine║  GETERC
     Function║ Return address of string invoking error handler
     Entry:    None
     Exit:     HL = address of first character of string invoking error handler
               A <> 0, zero flag clear (NZ) if valid character
               A = 0 and zero flag set if string is empty
     Affected: AF¼ HL
     Usage:    Facilitate≤ erro≥ handle≥ constructioε b∙ áreturnì
áááááááááááááááinτ áthσ strinτ addres≤ anΣ firs⌠ ácharacter« á Iµ ì
áááááááááááááááthσ erro≥ handle≥ i≤ t∩ bσ invokeΣ b∙ thσ command:

                    error params
               theε GETER├ return≤ thσ addres≤ oµ thσ firs⌠ charì
áááááááááááááááacte≥ of:

                    DEF┬      'ERROR PARAMS',0

     Routine║  PUTERC
     Function║ Set the error handler command line
     Entry:    H╠ á╜ addres≤ oµ firs⌠ characte≥ oµ erro≥ áhandle≥ ì
ááááááááááááááácommanΣ line
     Exit:     A <> 0, zero flag clear (NZ) if OK
               ┴ ╜ 0¼ zer∩ flaτ se⌠ (Z⌐ iµ commanΣ linσ to∩ álonτ ì
ááááááááááááááá(morσ thaε 3▓ bytes)
     Affected: AF
     Usage:    Establishe≤ áß strinτ whicΦ i≤ t∩ bσ áthσ ácommanΣ ì
ááááááááááááááálinσ áexecuteΣ át∩ invokσ aε erro≥ áhandler« á Thσ ì
áááááááááááááááerro≥ ástring¼ includinτ thσ endinτ 0¼ mus⌠ bσ á3▓ ì
ááááááááááááááábyte≤ lonτ o≥ less.
     Example:

                         EX╘       PUTER├         ; declare the routine
                         ...                      ; ..preceeding code
                         LD        HL,ERSTR       ; address this string
                         CAL╠      PUTER├         ╗ se⌠ i⌠ a≤ handle≥ comnΣ line
                         JR        NZ,OK          ; ..jump if string accepted
                         ...                      ; else take other action
               ERSTR:    DEFB      'ERROR NOOPT',0
è
INTE╥-TRANSIEN╘ ERRO╥ CODE:é  Thσ inte≥-transien⌠ erro≥ codσ i≤ áß ì
onσ-bytσ ámessagσ whicΦ an∙ prograφ caε se⌠ t∩ indicatσ it≤ ácomì
pletioε success«  Thσ conventioε i≤ tha⌠ iµ thi≤ messagσ bytσ ái≤ ì
se⌠ t∩ 0¼ theε thσ prograφ completeΣ successfully«  Iµ thi≤ ámesì
sagσ ábytσ i≤ no⌠ 0¼ theε thσ prograφ haΣ aε erro≥ anΣ thσ ávaluσ ì
oµ thi≤ messagσ bytσ indicate≤ thσ error.

GETER▓ áallow≤ áß prograφ t∩ determinσ thσ valuσ oµ áthi≤ áinte≥-ì
transien⌠ erro≥ codσ anΣ PUTER▓ allow≤ ß prograφ t∩ se⌠ thσ valuσ ì
oµ thσ inte≥-transien⌠ erro≥ code.

     Routine║  GETER2
     Function║ Return the value of inter-transient error code
     Entry:    None
     Exit:     A = error code, zero clear (NZ) if error
               A = 0, zero flag set (Z) if no error
     Affected: AF
     Usage:    Determine≤ iµ ß preceedinτ prograφ passeΣ aε erro≥ ì
ááááááááááááááát∩ thi≤ onσ iε thσ inte≥-transien⌠ erro≥ code.

     Routine║  PUTER2
     Function║ Set inter-transient error code
     Entry:    A = error code (0 for no error)
     Exit:     None
     Affected: None
     Usage:    Signal≤ áfollowinτ program≤ tha⌠ n∩ áerro≥ ástatu≤ ì
áááááááááááááááresulteΣ froφ thσ presentl∙-executinτ transient.

COMMAN─ ERRO╥ FLA╟ AN─ HANDLER:

     Routine║  GETER3
     Function║ Return the value of the command error flag
     Entry:    None
     Exit:     A <> 0, zero clear (NZ) if message exists
               A = 0, zero set (Z) if no message
     Affected: AF
     Usage:    Mos⌠ áofteε áuseΣ b∙ erro≥ áhandler≤ át∩ áidentif∙ ì
áááááááááááááááwhethe≥ o≥ no⌠ aε erro≥ occurred«  Iµ aε erro≥ ái≤ ì
ááááááááááááááádetecteΣ froφ thσ commanΣ erro≥ flag¼ thσ ámessagσ ì
ááááááááááááááábuffer≤ ma∙ bσ useΣ t∩ pas≤ additiona∞ informatioε ì
áááááááááááááááoε thσ causσ anΣ action.

     Routine║  PUTER3
     Function║ Set the command error flag
     Entry:    A = value to set command error flag
     Exit:     None; value is stored in command error flag
     Affected: None
     Usage:    Set≤ áthσ commanΣ erro≥ flaτ fo≥ possiblσ áinvocaì
ááááááááááááááátioε oµ aε erro≥ handler«  Additiona∞ áinformatioε ì
áááááááááááááááma∙ bσ passeΣ iε othe≥ messagσ buffers.
     Example:

                         EX╘       PUTER│         ; declare the routine
                         ...
               ISERR:    LD        A,0FFH         ; signal error occurrance
è                         JR        ERRV           ; ..with command error flag
               NOERR:    XOR       A              ; enter here to set no errs
               ERRV:     CALL      PUTER3         ; ..set/clear comnd err flag
                         ...                      ; continue

     Routine║  INVERROR
     Function║ Invoke error handler
     Entry:    A = 0 for internal errors
               A <> 0 for external errors
               ┬ ╜ erro≥ codσ fo≥ externa∞ errors¼ undefineΣ áfo≥ ì
áááááááááááááááinterna∞ errors
     Exit:     A = ░ iµ erro≥ i≤ interna∞ t∩ ZCPR 3.3
               A <> ░ iµ erro≥ i≤ externa∞ t∩ ZCPR 3.3
     Affected: AF¼ DE¼ HL
     Usage:    Set≤ áal∞ parameter≤ fo≥ aε erro≥ handle≥ áinvocßì
ááááááááááááááátion«  I⌠ i≤ normall∙ useΣ jus⌠ prio≥ t∩ ß prograφ ì
áááááááááááááááabor⌠ t∩ eithe≥ thσ commanΣ processo≥ o≥ t∩ ß warφ ì
áááááááááááááááboot.
     Example:

                         EX╘       INVERRO╥       ; declare the routine
                         ...                      ; ..pgm flow w/detected error
                         LD        A,(ERRCODE)    ; get error code (if external)
                         LD        B,A            ; ..and put in correct register
                         LD        A,(ERRTYPE)    ; load the error type
                         CALL      INVERROR       ; call the routine
                         JP        NZ,0           ; ..jump warm boot if no ZCPR33
                         ...                      ; else return to command proc

COMMAN─ STATU╙ FLAG:

     Routine║  SETEPB
     Function║ Set external program bit in command status flag
     Entry:    None
     Exit:     None
     Affected: None
     Usage:    Set≤ thσ externa∞ prograφ bi⌠ iε thσ commanΣ statì
áááááááááááááááu≤ áflaτ t∩ signif∙ t∩ thσ ZCP╥ 3.│ o≥ late≥ ácomì
ááááááááááááááámanΣ processo≥ tha⌠ curren⌠ action≤ (sucΦ a≤ parsì
áááááááááááááááing⌐ i≤ beinτ requesteΣ b∙ aε externa∞ program.

     Routine║  RESEPB
     Function║ Reset external program bit in command status flag
     Entry:    None
     Exit:     None
     Affected: None
     Usage:    Reset≤ áthσ áexterna∞ prograφ bi⌠ iε áthσ ácommanΣ ì
ááááááááááááááástatu≤ áflaτ indicatinτ t∩ thσ ZCP╥ 3.│ áo≥ álate≥ ì
ááááááááááááááácommanΣ áprocesso≥ tha⌠ an∙ action≤ therσ arσ áinì
áááááááááááááááterna∞ anΣ no⌠ relateΣ t∩ aε externa∞ program.
.pa
è     Routine║  RETCST
     Function║ Return the address of the command status flag
     Entry:    None
     Exit:     HL = address of the command status flag
     Affected: HL
     Usage:    Return≤ áthσ addres≤ oµ thσ commanΣ ástatu≤ áflag«  ì
áááááááááááááááI⌠ ái≤ useΣ b∙ SETEPB¼ RESEPB¼ anΣ othe≥ áinterna∞ ì
ááááááááááááááámodules.

REGISTE╥ ACCESS:é  Thσ ZCPR│ messagσ buffe≥ provide≤ teε áonσ-bytσ ì
message≤ áwhicΦ arσ useΣ a≤ onσ-bytσ registers«  Thσ áGETRE╟ áanΣ ì
PUTRE╟ routine≤ allo≈ ß prograφ t∩ obtaiε anΣ se⌠ ß valuσ iε áan∙ ì
onσ oµ thσ teε registers.

     Routine║  GETREG
     Function║ Return contents of specified message buffer
     Entry:    B = number of register to access (0..9)
     Exit:     A = value of register, zero flag set accordingly
     Affected: AF
     Usage:    UseΣ át∩ obtaiε thσ content≤ oµ aε arbitrar∙ ámesì
ááááááááááááááásagσ ábuffer« á Thesσ ábuffer≤ áarσ ábytσ ávalues«  ì
áááááááááááááááGETRE╟ perform≤ n∩ validit∙ checδ oε thσ specifieΣ ì
áááááááááááááááregiste≥ number¼ merel∙ usinτ i⌠ a≤ aε inde° áint∩ ì
áááááááááááááááthσ ámessagσ buffe≥ array«  Yo⌡ mus⌠ áinsurσ átha⌠ ì
áááááááááááááááonl∙ value≤ iε thσ rangσ oµ 0..╣ arσ passed.
     Example:

                         EX╘       GETREG         ; declare the routine
                         ...                      ; ..preceeding code
                         LD        B,5            ; get the value of reg 5
                         CALL      GETREG         ; return reg 5 value byte
                         JR        Z,R5EQ0        ; ..jump to process if 0
                         ...                      ; else check more, etc

     Routine║  PUTREG
     Function: Se⌠ áß specifieΣ messagσ buffe≥ registe≥ t∩ ágiveε ì
ááááááááááááááávalue
     Entry:    B = register number to set (0 to 9)
               A = value to set in register (0 to 255)
     Exit:     None
     Affected: None
     Usage:    Set≤ áß áspecifieΣ messagσ buffe≥ áregiste≥ át∩ áß ì
ááááááááááááááágiveε valuσ whicΦ ma∙ bσ testeΣ b∙ othe≥ programs«  ì
áááááááááááááááN∩ checδ i≤ madσ t∩ ensurσ tha⌠ ┬ contain≤ ß valiΣ ì
áááááááááááááááregiste≥ number«  Yo⌡ mus⌠ insurσ tha⌠ iε contain≤ ì
áááááááááááááááonl∙ value≤ froφ ░ t∩ 9.
     Example:

                         EX╘       PUTREG         ; declare the routine
                         ...                      ; ..preceeding code
                         LD        B,9            ; set message register 9
                         LD        A,20           ; ..to 20
                         CALL      PUTREG         ; do it
                         ...                      ; ..and continue
.pa
èDEFAUL╘ DRIVE/USE╥ BUFFER:

     Routine║  GDEFDU
     Function║ Return current drive and user
     Entry:    None
     Exit:     BC = DU; B=drive (0=A..15=P), C = user number
     Affected: BC
     Usage:    Return≤ áthσ curren⌠ drivσ anΣ use≥ setting≤ áfroφ ì
áááááááááááááááthσ áZCP╥ á3.│ messagσ buffe≥ fo≥ usσ áb∙ áthσ áC─ ì
ááááááááááááááá(changσ directory⌐ routine¼ shells¼ o≥ wheε ß use≥ ì
ááááááááááááááánumbe≥ ágreate≥ áthaε 1╡ i≤ logged«  Thi≤ ái≤ áthσ ì
ááááááááááááááápreferreΣ ámethoΣ oµ logginτ int∩ higΦ use≥ áarea≤ ì
ááááááááááááááásincσ thσ CURDR╓ bytσ a⌠ locatioε ┤ onl∙ áaccommoì
ááááááááááááááádate≤ user≤ froφ ░ througΦ 15.

     Routine║  PDEFDU
     Function║ Make specified drive and user current
     Entry:    BC = DU; B=drive (0=A..15=P), C=user (0..31) to set
     Exit:     None; CURDR and CURUSR are set to specified values
     Affected: None
     Usage:    Store≤ specifieΣ drivσ anΣ use≥ value≤ int∩ áCURD╥ ì
áááááááááááááááanΣ CURUS╥ location≤ iε thσ ZCPR│ messagσ ábuffer¼ ì
áááááááááááááááthereb∙ makinτ theφ current«  I⌠ i≤ normall∙ áuseΣ ì
áááááááááááááááwheε drivσ anΣ use≥ arσ obtaineΣ froφ patΦ áspeciì
áááááááááááááááfication≤ t∩ signa∞ shell≤ o≥ erro≥ handler≤ wherσ ì
áááááááááááááááactivitie≤ occurred.

ZCPR│ UTILITIES:é  Thesσ utilitie≤ providσ ß numbe≥ oµ áconvenien⌠ ì
function≤ fo≥ ZCPR│ programmers«  Acces≤ t∩ directories¼ áconverì
sioε áfroφ tex⌠ strinτ name≤ t∩ director∙ referencσ values¼ ácomì
manΣ anΣ commanΣ linσ parsing¼ quie⌠ outpu⌠ routines¼ shel∞ stacδ ì
manipulation¼ dela∙ routines¼ anΣ othe≥ ZCPR│-specifiπ áfunction≤ ì
arσ provided.

NAME─ DIRECTORY-DRIVE/╒SER CONVERSION:

     Routine║  DIRTDU
     Function║ Convert specified DIR name to DU equivalent
     Entry:    HL = address of first character of DIR name
     Exit:     HL = points to delimiter at end of name
               BC = DU, B=disk (0=A..15=P), C=user (0..31)
               A <> 0, zero flag clear (NZ) if found
               A = 0, zero flag set (Z) if not found
     Affected: AF¼ BC¼ HL
     Usage:    Convert≤ áß DI╥ namσ consistinτ oµ ß strinτ oµ áu≡ ì
ááááááááááááááát∩ áeigh⌠ character≤ terminateΣ b∙ áan∙ ácharacte≥ ì
áááááááááááááááothe≥ thaε ß digi⌠ o≥ lette≥ t∩ it≤ D╒ áequivalen⌠ ì
áááááááááááááááfounΣ iε thσ nameΣ director∙ buffer.
.pa
è     Routine║  DUTDIR
     Function║ Convert specified DU to DIR equivalent
     Entry:    BC = DU, B=disk (0=A..15=P), C=user (0..31)
     Exit:     HL = pointer to 8-character name string
               A <> 0, zero flag clear (NZ) if found
               A = 0, zero flag set (Z) if not found
     Affected: AF¼ HL
     Usage:    Searche≤ thσ nameΣ director∙ fo≥ thσ specifieΣ DU«  ì
áááááááááááááááIµ áaε áentr∙ exist≤ fo≥ thσ correspondinτ áDU¼ áß ì
ááááááááááááááápointe≥ i≤ returneΣ t∩ thσ ╕-characte≥ namσ á(folì
áááááááááááááááloweΣ b∙ aε ╕-characte≥ password).

RESOLV┼ DIRECTOR┘ REFERENCES:

     Routine║  DNSCAN
     Function║ Resolve directory name using both DU and DIR
     Entry:    H╠ á╜ addres≤ oµ thσ firs⌠ characte≥ oµ ádirector∙ ì
áááááááááááááááname
               A = 0 (scan DU before DIR)
               A <> 0 (scan DIR before DU)
     Exit:     BC = DU, B=disk (0=A..15=P), C=user (0..31)
               A <> 0, zero flag clear (NZ) if found
               A = 0, zero flag set (Z) if not found
     Affected: AF¼ BC
     Usage:    Attempt≤ t∩ resolvσ ß candidatσ director∙ namσ áb∙ ì
ááááááááááááááácheckinτ ábotΦ áDI╥ anΣ D╒ áformat≤ áiε áspecifieΣ ì
áááááááááááááááorder« á Thσ ácandidatσ namσ ma∙ bσ áu≡ át∩ áeigh⌠ ì
ááááááááááááááácharacter≤ áterminateΣ áb∙ ß delimite≥ sucΦ áa≤ áß ì
áááááááááááááááspace¼ comma¼ period¼ dash¼ ß characte≥ les≤ áthaε ì
áááááááááááááááspace¼ etc«  Iµ found¼ thσ D╒ i≤ returneΣ iε BC.

     Routine║  DUSCAN
     Function║ Resolve addressed string in DU form
     Entry:    HL = address of string (up to 8 characters)
     Exit:     BC = DU, B=disk (0=A..15=P), C=user (0..31)
               A <> 0, zero flag clear (NZ) if valid DU form
               A = 0, zero flag set (Z) if not valid
     Affected: AF¼ BC
     Usage:    Resolve≤ thσ D╒ forφ oµ ß strinτ addresseΣ b∙ áHL«  ì
áááááááááááááááThσ áD╒ strinτ i≤ storeΣ iε ß buffe≥ u≡ át∩ áeigh⌠ ì
ááááááááááááááácharacter≤ long¼ anΣ i≤ terminateΣ b∙ ß delimiter¼ ì
áááááááááááááááwhicΦ ma∙ bσ ß characte≥ les≤ thaε ß space¼ áequa∞ ì
ááááááááááááááásigε á(=)¼ underscorσ (_)¼ perioΣ (.)¼ commß á(,)¼ ì
áááááááááááááááles≤ thaε (<)¼ o≥ greate≥ thaε (>).

     Routine║  DIRSCAN
     Function║ Resolve addressed strinτ in DIR form
     Entry:    HL = address of string (up to 8 characters)
     Exit:     BC = DU, B=disk (0=A..15=P), C=user (0..31)
               A <> 0, zero flag clear (NZ) if valid DU form
               A = 0, zero flag set (Z) if not valid
     Affected: AF¼ BC
     Usage:    Resolve≤ thσ DI╥ forφ oµ ß strinτ addresseΣ b∙ HL«  ì
áááááááááááááááThσ áD╒ strinτ i≤ storeΣ iε ß buffe≥ u≡ át∩ áeigh⌠ ì
ááááááááááááááácharacter≤ long¼ anΣ i≤ terminateΣ b∙ ß delimiter¼ ìèáááááááááááááááwhicΦ ma∙ bσ ß characte≥ les≤ thaε ß space¼ áequa∞ ì
ááááááááááááááásigε á(=)¼ underscorσ (_)¼ perioΣ (.)¼ commß á(,)¼ ì
áááááááááááááááles≤ thaε (<)¼ o≥ greate≥ thaε (>).

PARS┼ COMMAN─ LINE:

     Routine║  PARSER
     Function║ Parse complete command line
     Entry:    HL = address of command line
               A = 0 (scan DIR before DU)
               ┴ <╛ ░ (scan DU before DIR)
     Exit:     HL = address of next command (0 or leading ;)
               DE = address of FCB with command name (verb. COM)
               A = 0, zero flag set (Z) if OK
               ┴ á╜ numbe≥ oµ questioε marks¼ zer∩ clea≥ (NZ⌐ áiµ ì
áááááááááááááááverΓ contain≤ onσ o≥ morσ "?ó characters
     Affected: AF¼ DE¼ HL
     Usage:    Parse≤ áß completσ commanΣ u≡ t∩ aε endinτ NU╠ áo≥ ì
ááááááááááááááámultiplσ ácommanΣ linσ delimite≥ (usuall∙ ß ásemiì
ááááááááááááááácolon)« á I⌠ parse≤ anΣ initialize≤ áal∞ áelement≤ ì
ááááááááááááááápe≥ thσ ZCPR│ commanΣ convention≤ t∩ includσ áFCB▒ ì
áááááááááááááááa⌠ á005Ch¼ áFCB▓ a⌠ 006CΦ anΣ thσ ádefaul⌠ ábuffe≥ ì
ááááááááááááááá(TBUFF⌐ a⌠ 0080h«  Thσ commanΣ namσ i≤ returneΣ iε ì
áááááááááááááááaε FC┬ addresseΣ b∙ DE.

PAT╚ SEARC╚ FO╥ FILE:

     Routine║  PFIND
     Function║ Search for specified file along search path
     Entry:    DE = address of an FCB
               A <> 0 to search current directory
               ┴ = 0 if no current search
     Exit:     BC = DU, B=disk (0=A..15=P), C=user (0..31)
               A <> 0, zero flag clear (NZ) if found
               A = 0, zero flag set (Z) if not found
     Affected: AF¼ BC
     Usage:    Locate≤ ß filσ alonτ thσ ZCPR│ searcΦ path« á Wheε ì
ááááááááááááááálocated¼ áthσ ádisδ anΣ use≥ wherσ áthσ áfilσ áwa≤ ì
áááááááááááááááfounΣ arσ returned.

PROGRA═ LOADIN╟ (CHAINING):

     Routine║  PRGLOAD
     Function║ Load and execute specified program (chain)
     Entry:    DE = address oµ ß filσ contro∞ block
     Exit:     None
     Affected: Al∞ áregisters╗ iµ thi≤ routinσ returns¼ theε áthσ ì
áááááááááááááááloaΣ wa≤ ß failure.
     Usage:    Thi≤ routinσ i≤ ß "chainó functioε whicΦ load≤ thσ ì
áááááááááááááááprograφ indicateΣ b∙ thσ firs⌠ 1▓ byte≤ áaddresseΣ ì
áááááááááááááááb∙ D┼ int∩ memor∙ a⌠ 100Φ anΣ transfer≤ contro∞ t∩ ì
áááááááááááááááit« á Thσ áloade≥ anΣ FC┬ useΣ fo≥ áthσ áloaΣ áarσ ì
ááááááááááááááárelocateΣ át∩ ájus⌠ unde≥ áthσ ácommanΣ áprocesso≥ ì
ááááááááááááááá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µ ß stacδ iε thσ TP┴ áwhicΦ ì
áááááááááááááááma∙ bσ overwritteε durinτ load.

               Iµ áPRGLOA─ áreturn≤ t∩ thσ ácallinτ áprogram¼ áaε ì
áááááááááááááááerro≥ iε loadinτ occurred«  Iµ al∞ goe≤ well¼ áthσ ì
áááááááááááááááloadeΣ prograφ execute≤ successfully.

CONSOL┼ QUIE╘ OUTPUT:é  Thesσ routine≤ outpu⌠ thei≥ value≤ onl∙ iµ ì
thσ quie⌠ flaτ i≤ clea≥ (0)«  Iµ thσ quie⌠ flaτ i≤ TRU┼ (no⌠ á0)¼ ì
theε n∩ value≤ arσ 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)

     Routine║  QCOUT
     Function║ Print character on console if not quiet
     Entry:    A = character to print
     Exit:     None
     Affected: None
     Usage:    Compariblσ t∩ thσ SYSLI┬ COU╘ routine¼ excep⌠ tha⌠ ì
ááááááááááááááái⌠ onl∙ print≤ iµ thσ quie⌠ flaτ i≤ off« á Contro∞ ì
ááááááááááááááácharacter≤ arσ printeΣ a≤ ß care⌠ (^⌐ followeΣ áb∙ ì
áááááááááááááááthσ characte≥ offse⌠ b∙ 40Φ (▒ output≤ a≤ ^A).

     Routine║  QCRLF
     Function║ Print a new line (CR/LF pair) if not quiet
     Entry:    None
     Exit:     Nonσ
     Affected: None
     Usage:    Correspond≤ t∩ thσ SYSLI┬ CRL╞ routinσ excep⌠ tha⌠ ì
áááááááááááááááiε ái≤ onl∙ sen⌠ t∩ thσ consolσ iµ thσ quie⌠ áflaτ ì
ááááááááááááááái≤ ofµ (0).

     Routine║  QOUT
     Function: Prin⌠ withou⌠ contro∞ characte≥ processinτ iµ áno⌠ ì
áááááááááááááááquiet
     Entry:    A = character to output
     Exit:     None
     Affected: None
     Usage:    Output≤ thσ characte≥ iε ┴ withou⌠ contro∞ characì
áááááááááááááááte≥ áprocessinτ á(▒ output≤ a≤ binar∙ á1⌐ áiµ áthσ ì
áááááááááááááááquie⌠ flaτ i≤ ofµ (0).

     Routine║  QPRINT
     Function║ Inline print of string if not quiet
     Entry:    None; string at return address
     Exit:     None
     Affected: None
     Usage:    Print≤ áß NU╠-terminateΣ strinτ whosσ áaddres≤ ái≤ ì
ááááááááááááááácontaineΣ áoε thσ stacδ to≡ iµ thσ quie⌠ áflaτ ái≤ ìèáááááááááááááááofµ (0)«  Executioε resume≤ a⌠ thσ bytσ áfollowinτ ì
áááááááááááááááthσ NU╠ afte≥ thσ strinτ i≤ printed.

     Routine║  QPSTR
     Function║ Print NUL-terminated string if not quiet
     Entry:    HL = address of first character of the string
     Exit:     None
     Affected: None
     Usage:    Samσ a≤ QPRIN╘ above¼ excep⌠ tha⌠ printinτ i≤ froφ ì
áááááááááááááááß registe≥ a≤ opposeΣ thσ inlinσ addres≤ froφ áthσ ì
ááááááááááááááástack.

LOCAT┼ ROO╘ DIRECTORY:

     Routine║  ROOT
     Function║ Return DU for the last directory in search path
     Entry:    None
     Exit:     BC = DU, B=disk (0=A..15=P), C=user (0..31)
     Affected: BC
     Usage:    Provide≤ ß convenien⌠ wa∙ t∩ finΣ thσ las⌠ ádirecì
ááááááááááááááátor∙ áiε ß patΦ expressioε (ROO╘ ádirectory)« á N∩ ì
ááááááááááááááápatΦ optimizatioε i≤ performed.

               Thi≤ routinσ i≤ sometime≤ no⌠ consisten⌠ witΦ áthσ ì
áááááááááááááááZCPR│ ácommanΣ processo≥ iµ thσ MINPAT╚ á(minimizσ ì
ááááááááááááááápatΦ áexpression⌐ áoptioε i≤ selected« á ROO╘ áadì
ááááááááááááááávance≤ át∩ áthσ las⌠ referenceΣ director∙ áiε áthσ ì
ááááááááááááááápatΦ áwithou⌠ minimization¼ whilσ ZCPR│ áminimize≤ ì
áááááááááááááááthσ ásearcΦ áanΣ ma∙ resolvσ ß patΦ t∩ áenΣ á(witΦ ì
áááááááááááááááduplication⌐ a⌠ ß director∙ othe≥ thaε thσ áphysiì
ááááááááááááááácall∙ las⌠ director∙ iε thσ path.

SHEL╠ STAC╦ ROUTINES:é  Thi≤ se⌠ oµ routine≤ support≤ shel∞ ástacδ ì
manipulation«  Thσ followinτ routine≤ arσ 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▓ byte≤ pe≥ 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│ ì
commanΣ processor«  Thi≤ commanΣ linσ i≤ copieΣ int∩ thσ multiplσ ì
commanΣ linσ buffe≥ fo≥ execution.

     Routine║  SHEMPTY
     Function║ Return status of shell stack
     Entry:    None
     Exit:     A <> 0, zero flag clear (NZ) if not empty
               A = 0, zero flag set (Z) if empty or none
     Affected: AF
     Usage:    Provide≤ áthσ ácurren⌠ statσ oµ thσ áshel∞ ástack«  ì
áááááááááááááááThσ zer∩ flaτ indicate≤ whethe≥ o≥ no⌠ shel∞ stacδ ì
áááááááááááááááspacσ i≤ available.
è
     Routine║  SHFULL
     Function║ Determine if the shell stack is full
     Entry:    None
     Exit:     A <> 0, zero flag clear (NZ) if stack not full
               A = 0, zero set (Z) if stack full or none
     Affected: AF
     Usage:    Return≤ áß flaτ indicatinτ iµ thσ shel∞ ástacδ ái≤ ì
áááááááááááááááful∞ o≥ noε-existant.

     Routine║  SHPOP
     Function║ Pop top element from shell stack and discard
     Entry:    None
     Exit:     A = 0, zero flag set (Z) if OK
               A = error code, zero clear (NZ):
                    1 = no shell stack
                    2 = shell stack empty
               Affected: AF
     Usage:    Remove≤ áthσ to≡ elemen⌠ froφ thσ shel∞ stack¼ áiµ ì
ááááááááááááááápossible¼ anΣ discard≤ it«  Erro≥ code≤ repor⌠ áiµ ì
áááááááááááááááthσ áoperatioε wa≤ successful¼ o≥ thσ áreasoε áfo≥ ì
áááááááááááááááthσ error.

     Routine║  SHPUSH
     Function║ Push NUL-terminated string onto shell stack
     Entry:    H╠ ╜ addresse≤ NU╠-terminateΣ strinτ t∩ pusΦ áont∩ ì
ááááááááááááááástack
     Exit:     A = 0, zero flag set (Z) if successful
               A = return code¼ zer∩ clea≥ (NZ):
                    1 = no shell stack available
                    2 = shell stack is full
                    3 = string too long for entry
     Affected: AF
     Usage:    Perform≤ áneedeΣ function≤ t∩ pusΦ áNU╠-terminateΣ ì
ááááááááááááááástring≤ áont∩ áthσ shel∞ stack« á ReturneΣ ástatu≤ ì
áááááááááááááááshow≤ thσ result≤ oµ thσ action.

DELA┘ ROUTINES:é  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∩ register≤ áarσ áafì
fected«  The routines are:
     WAIT1S -- delay for 1 second
     WAIT1MS -- delay for 0.001 second
     WAITP1S -- delay for 0.1 second

     Routine║  WAIT1S
     Function║ Wait for approximately one second
     Entry:    None
     Exit:     None
     Affected: None
     Usage:    Pause≤ áfo≥ approximatel∙ onσ seconΣ baseΣ oε áthσ ì
áááááááááááááááprocesso≥ áspeeΣ áiε thσ environmen⌠ anΣ áthσ áCP╒ ì
ááááááááááááááátype.

è     Routine║  WAIT1MS
     Function║ Wait for approximately one millisecond
     Entry:    None
     Exit:     None
     Affected: None
     Usage:    Pause≤ áfo≥ áapproximatel∙ onσ ámilliseconΣ á(.00▒ ì
ááááááááááááááásecond⌐ baseΣ oε thσ processo≥ speeΣ iε thσ áenviì
áááááááááááááááronmen⌠ anΣ thσ CP╒ type.

     Routine║  WAITP1S
     Function║ Wait for approximately one-tenth second
     Entry:    None
     Exit:     None
     Affected: None
     Usage:    Pause≤ áfo≥ áapproximatel∙ onσ-tentΦ oµ áß áseconΣ ì
ááááááááááááááábaseΣ oε thσ processo≥ speeΣ anΣ thσ CP╒ type.

LO╟ INT╧ ZCPR│ FIL┼ CONTRO╠ ┬LOCK DRIVE/USER:

     Routine║  Z3LOG
     Function: Loτ int∩ drive/use≥ containeΣ iε ß specifieΣ ZCPR│ ì
áááááááááááááááfilσ contro∞ block
     Entry:    D┼ á╜ addres≤ oµ firs⌠ bytσ oµ ZCPR│ filσ ácontro∞ ì
áááááááááááááááblock
     Exit:     None
     Affected: None
     Usage:    Log≤ int∩ thσ drivσ anΣ use≥ containeΣ iε ß speciì
áááááááááááááááfieΣ áZCPR│ filσ contro∞ block«  Thσ drivσ ái≤ áiε ì
ááááááááááááááábytσ ░ oµ thσ FC┬ (1=A..16=P⌐ anΣ thσ use≥ (0..31⌐ ì
ááááááááááááááái≤ áiε bytσ 13«  Thi≤ i≤ thσ standarΣ forma⌠ áuseΣ ì
áááááááááááááááb∙ áZCPR│ át∩ storσ ß completσ D╒ referencσ áiε áß ì
áááááááááááááááFCB.

RETUR╬ Z3LI┬ VERSION:

     Routine║  Z3LVER
     Function║ Return version number of Z3LIB.REL
     Entry:    None
     Exit:     HL = version number (H=major, L=minor) in binary
     Affected: HL
     Usage:    Record≤ thσ Z3LI┬ versioε iε linkeΣ programs¼ áfo≥ ì
ááááááááááááááádebugginτ witΦ differen⌠ versions.
.pa
èPARS┼ TOKEN:

     Routines║ ZPRSFN¼ ZFNAME
     Function║ Parse filσ contro∞ blocδ token
     Entry:    HL = address of first character of token
               DE = address of 36-byte filσ contro∞ block
               A = flag:
                    0 = scan for DIR form before DU
                    1 = scan for DU form before DIR
     Exit:     HL = address of character after token
               A = number of question marks in filename.typ
               Zero flag set accordingly
     Affected: AF¼ HL
     Usage:    Perform≤ thσ identica∞ functioε oµ parsinτ ß ácomì
ááááááááááááááápletσ áFC┬ tokeε a≤ thσ ZCPR│ ácommanΣ áprocessor«  ì
áááááááááááááááToken≤ áma∙ takσ thσ forφ áoµ á"dir:filename.typ"¼ ì
ááááááááááááááá"du:filename.typ"¼ á"filename.typ"¼ etc«  Thσ áreì
ááááááááááááááásultinτ áFC┬ contain≤ thσ filenamσ anΣ typσ anΣ áß ì
áááááááááááááááprope≥ D╒ reference«  (Seσ PARSER¼ whicΦ i≤ relatì
áááááááááááááááed.)

               ZFNAM┼ ái≤ áß litera∞ interpretatioε oµ áthσ ácodσ ì
áááááááááááááááwithiε áthσ ZCPR│ commanΣ processor¼ whilσ áZPRSF╬ ì
ááááááááááááááái≤ áß ámorσ efficien⌠ bod∙ oµ codσ bu⌠ áuse≤ ámorσ ì
ááááááááááááááábuffe≥ space.

ZCP╥ 3.│ PARSERS:

     Routine║  Z33FNAME
     Function║ Parse single token from external command buffer
     Entry:    DE = address of user-defined FCB to receive token
     Exit:     HL = addres≤ oµ delimiter in command buffer
     Affected: HL
     Usage:    Require≤ ZCP╥ 3.│ o≥ later«  Thi≤ routinσ parse≤ ß ì
ááááááááááááááásinglσ tokeε froφ thσ externa∞ commanΣ buffe≥ t∩ ß ì
áááááááááááááááspecifieΣ FCB«  I⌠ use≤ thσ SCA╬ entr∙ iε ZCP╥ 3.│ ì
áááááááááááááááo≥ álater«  Yo⌡ mus⌠ insurσ tha⌠ thσ commanΣ áproì
ááááááááááááááácesso≥ ha≤ no⌠ beeε overwritteε t∩ usσ thi≤ áfuncì
ááááááááááááááátion.

     Routine║  PARSE2
     Function║ Parse command line using ZCPR 3.3 REPARSE entry
     Entry:    HL = address of the command line to reparse
     Exit:     None; line is reparsed and FCB's filled
     Affected: None
     Usage:    Require≤ ZCP╥ 3.│ o≥ later«  Thi≤ routinσ parse≤ ß ì
áááááááááááááááspecifieΣ commanΣ linσ t∩ thσ defaul⌠ FCB'≤ a⌠ 5CΦ ì
áááááááááááááááanΣ 6Ch«  Yo⌡ mus⌠ insurσ tha⌠ thσ commanΣ procesì
áááááááááááááááso≥ ha≤ no⌠ beeε overwritteε t∩ usσ thi≤ routine.
.pa
è     Routine║  REPARSE
     Function║ Reparse default command line one token later
     Entry:    None
     Exit:     None; the command line is reparsed
     Affected: None
     Usage:    Require≤ ZCP╥ 3.│ o≥ later«  Thi≤ routinσ reparse≤ ì
áááááááááááááááthσ curren⌠ commanΣ linσ startinτ onσ tokeε áafte≥ ì
ááááááááááááááácurren⌠ ásettinτ anΣ set≤ thσ defaul⌠ FCB's« á Yo⌡ ì
ááááááááááááááámus⌠ áinsurσ átha⌠ thσ commanΣ processo≥ áha≤ áno⌠ ì
ááááááááááááááábeeε overwritteε t∩ usσ thi≤ routine.

     Routine║  SCAN
     Function║ Scan single token from specified command line
     Entry:    HL = points to command line to scan
               DE = points to FCB to receive parsed token
     Exit:     None; token is parsed
     Affected: None
     Usage:    Require≤ ZCP╥ 3.│ o≥ later«  Thi≤ routinσ parse≤ ß ì
ááááááááááááááásinglσ átokeε froφ ß use≥-specifieΣ ácommanΣ álinσ ì
áááááááááááááááint∩ ß specifieΣ FC┬ usinτ thσ SCA╬ entr∙ iε áZCP╥ ì
ááááááááááááááá3.│ áo≥ later«  Yo⌡ mus⌠ insurσ tha⌠ áthσ ácommanΣ ì
áááááááááááááááprocesso≥ áha≤ áno⌠ beeε overwritteε t∩ áusσ áthi≤ ì
ááááááááááááááároutine.

CHEC╦ ZCP╥ 3.│ PARS┼ RESULTS:

     Routines║ FCB1CHK¼ FCB2CHK
     Function║ Examinσ defaul⌠ filσ contro∞ block≤ fo≥ validity
     Entry:    None
     Exit:     A = 0, zero set (Z) if FCB has valid name
               A <> 0, zero clear (NZ) if error or no name
     Affected: AF
     Usage:    Require≤ áFC┬ parseΣ b∙ ZCP╥ 3.│ o≥ later« á Thesσ ì
ááááááááááááááároutine≤ áexaminσ thσ defaul⌠ FCB'≤ áa⌠ álocation≤ ì
ááááááááááááááá5CΦ (FCB1CHK⌐ anΣ 6CΦ (FCB2CHK⌐ fo≥ validl∙ parseΣ ì
áááááááááááááááfilename≤ froφ ZCP╥ 3.│ o≥ late≥ parsers« á Error≤ ì
áááááááááááááááarσ áduσ t∩ D╒ ou⌠ oµ range¼ illega∞ nameΣ ádirecì
ááááááááááááááátory¼ o≥ illega∞ password.

     Routine║  FCBCHK
     Function║ Examine specified filσ contro∞ block for validity
     Entry:    DE = address of an FCB to check
     Exit:     A = 0, zero set (Z) if FCB has valid name
               A <> 0, zero clear (NZ) if error or no name
     Affected: AF
     Usage:    Require≤ áFC┬ parseΣ b∙ ZCP╥ 3.│ o≥ álater« á Thi≤ ì
ááááááááááááááároutine≤ áexamine≤ thσ FC┬ a⌠ ß specifieΣ áaddres≤ ì
áááááááááááááááfo≥ ávalidl∙ parseΣ filenamσ b∙ ZCP╥ 3.│ o≥ álate≥ ì
áááááááááááááááparsers«  Error≤ arσ duσ t∩ D╒ ou⌠ oµ range¼ illeì
ááááááááááááááága∞ nameΣ directory¼ o≥ illega∞ password.
.pa
èPRIN╘ LOA─ MODUL┼ DATA:

     Routine║  PRTTYPE
     Function║ Print load module type and address
     Entry:    A = program type (1..4)
               HL = program load address
     Exit:     None; the type and address are printed on console
     Affected: None
     Usage:    Mos⌠ ofteε useΣ iε extendeΣ processor≤ anΣ áutiliì
ááááááááááááááátie≤ át∩ ádispla∙ loaΣ information«  I⌠ áprint≤ áß ì
ááááááááááááááámessagσ t∩ thσ CON║ devicσ containinτ loaΣ ámodulσ ì
ááááááááááááááátypσ (│ o≥ 4⌐ anΣ thσ loaΣ addres≤ iε hex.
     Example:

                         EX╘       PRTTYPE        ; declare the routine
                         ...
                         JP        BEGIN          ; ZCPR 3 header structure
                         DEFB      'Z3ENV'        ; .ID string
               TYPE:     DEFB      3              ; ..module load type
               Z3EADR:   DEFW      $-$            ; ...candidate ENV address
               START:    DEFW      9800H          ; type 3 starting addr = 9800h
               BEGIN:    ...                      ; initial setup, set stack, etc
                         LD        A,(TYPE)       ; get the load module type
                         LD        HL,START       ; ..and load starting address
                         CALL      PRTTYPE        ; print them to the console
                         ...                      ; ..continue on

ZCP╥ 3.│ INTERNA╠ PROGRA═ NAME:

     Routine║  GETNAME
     Function║ Return pointer to current program name
     Entry:    None
     Exit:     A <> 0, zero clear (NZ) if external FCB exists
               A = 0, zero set (Z) if no external FCB
               H╠ á╜ addres≤ oµ interna∞ namσ buffe≥ (valiΣ áonl∙ ì
áááááááááááááááiµ externa∞ FC┬ exists)
     Affected: AF¼ DE¼ HL
     Usage:    Return≤ ß pointe≥ t∩ thσ currentl∙ executinτ áproì
ááááááááááááááágraφ b∙ accessinτ thσ externa∞ FC┬ defineΣ iε áthσ ì
áááááááááááááááEnvironmen⌠ Descriptor«  I⌠ i≤ usefu∞ fo≥ áidentiì
áááááááááááááááfyinτ thσ rea∞ prograφ namσ wheε rσ-executeΣ áwitΦ ì
áááááááááááááááß á"GOó commanΣ o≥ equivalen⌠ facility«  Fo≥ áthi≤ ì
ááááááááááááááároutinσ át∩ functioε aε externa∞ FC┬ mus⌠ ábσ ádeì
áááááááááááááááfined.

     Routine║  PRTNAME
     Function║ Print program name from internal buffer
     Entry:    None
     Exit:     None; the name is printed to console
     Affected: None
     Usage:    Print≤ thσ curren⌠ prograφ namσ froφ aε áinternalì
ááááááááááááááál∙-helΣ buffe≥ t∩ thσ CON║ device.
.pa
èHIGHES╘ USEABL┼ MEMORY:

     Routine║  GZMTOP
     Function║ Return last usable TPA memory address
     Entry:    None
     Exit:     HL = last usable memory address in TPA
     Affected: HL
     Usage:    Determine≤ thσ to≡ oµ thσ availablσ TPA«  I⌠ áuse≤ ì
áááááááááááááááthσ extendeΣ environment¼ iµ available¼ áotherwisσ ì
ááááááááááááááái⌠ ácalculate≤ áthσ CC╨ basσ froφ BIO╙ áwarφ áboo⌠ ì
áááááááááááááááaddress« á I⌠ als∩ accommodate≤ sensinτ fo≥ áresiì
áááááááááááááááden⌠ RSX's«  Thσ addres≤ returneΣ i≤ thσ las⌠ bytσ ì
ááááááááááááááábelo≈ ß pagσ boundar∙ (L=0FFh⌐ fo≥ aε addeΣ safet∙ ì
ááááááááááááááámargin«  Fo≥ example¼ iµ thσ CC╨ begin≤ a⌠ á0C000Φ ì
áááááááááááááááanΣ án∩ RSX'≤ arσ present¼ thi≤ routinσ woulΣ áreì
áááááááááááááááturε 0BFFFh«  Oε thσ othe≥ hand¼ iµ aε RS╪ áexist≤ ì
áááááááááááááááwitΦ áß áprotec⌠ addres≤ oµ á0BC6Ch¼ áGXMTO╨ áwil∞ ì
áááááááááááááááreturε 0BBFFh.
.pa
è