home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / JSAGE / ZSUS / PROGPACK / V42-DOCS.LBR / Z3LIB42.DZC / Z3LIB42.DOC
Text File  |  1990-06-07  |  124KB  |  2,589 lines
  1. .hm1
  2. .fm1
  3. .sr0
  4. .he                                 ZCPR3: THE LIBRARIES 4.2 -- Z3LIB
  5. .fo                                                            Page #
  6. .pn 85
  7.  
  8.          II«  Z3LI┬ -¡ ZCPR│ Suppor⌠ anΣ Acces≤ Routines
  9.  
  10.      Introductioε « « « « « « « « « « « « « « « « « « « « « «  87
  11.           ExtendeΣ Environmen⌠ Descriptioε  « « « « « « « « «  87
  12.      Acces≤ t∩ thσ ZCPR│ Environmen⌠  « « « « « « « « « « « «  90
  13.           Command Linσ  « « « « « « « « « « « « « « « « « « «  91
  14.                APPCL¼ CLRCL¼ GETCL1¼ GETCL2¼ PUTCL
  15.           CR╘ anΣ PRT Datß  « « « « « « « « « « « « « « « « «  92
  16.                GETCRT¼ GETPRT¼ PUTCRT¼ PUTPRT
  17.           External Filσ Contro∞ Blocδ « « « « « « « « « « « «  94
  18.                GETEFCB
  19.           Environmen⌠ « « « « « « « « « « « « « « « « « « « «  94
  20.                GETENV¼ GETVID
  21.           Flo≈ Command Packagσ (FCP) Addres≤  « « « « « « « «  95
  22.                GETFCP
  23.           Filename≤ « « « « « « « « « « « « « « « « « « « « «  95
  24.                GETFN1, GETFN2¼ GETFNX¼ PUTFNX
  25.           ╔nitializσ  « « « « « « « « « « « « « « « « « « « «  96
  26.                WHRENV¼ Z3INIT
  27.           System Datß « « « « « « « « « « « « « « « « « « « «  97
  28.                ZSYSCHK¼ Z33CHK¼ GETBDOS¼ GETCCP¼ GETECP
  29.           Input-Outpu⌠ Packagσ (IOP) Concept≤ « « « « « « « «  99
  30.                GETION¼ GETIOP¼ GETIOS¼ IOMATCH¼ PUTIOD
  31.           Input-Outpu⌠ Packagσ (IOP) Recordinτ  « « « « « « « 101
  32.                IORCOFF, IORCON, IORLOFF, IORLON
  33.           Drive/Use≥  « « « « « « « « « « « « « « « « « « « « 101
  34.                GETDUOK¼ GETMDISK¼ GETMUSER¼ PUTDUOK,
  35.                PUTMDISK¼ PUTMUSER¼ HIGHUSER¼ GCMDDU
  36.           Message≤  « « « « « « « « « « « « « « « « « « « « « 103
  37.                GETMSG¼ GETSHM¼ PUTSHM
  38.           Named Directorie≤ « « « « « « « « « « « « « « « « « 104
  39.                ADDNDR¼ DIRNDR¼ DUNDR¼ GETNDR¼ SUBNDR
  40.           PatΦ  « « « « « « « « « « « « « « « « « « « « « « « 106
  41.                GETPATH
  42.           Processor SpeeΣ « « « « « « « « « « « « « « « « « « 106
  43.                GETSPEED¼ PUTSPEED
  44.           Quiet Flaτ  « « « « « « « « « « « « « « « « « « « « 107
  45.                GETQUIET¼ PUTQUIET
  46.           Residen⌠ CommanΣ Packagσ (RCP) Addres≤  « « « « « « 107
  47.                GETRCP
  48.           Shell Stacδ « « « « « « « « « « « « « « « « « « « « 108
  49.                GETSH1¼ GETSH2
  50.           Wheel Bytσ  « « « « « « « « « « « « « « « « « « « « 108
  51.                GETWHL¼ PUTWHL
  52.      Flo≈, ZE╪¼ anΣ SUBMIT Contro∞  « « « « « « « « « « « « « 109
  53.           Flow Contro∞  « « « « « « « « « « « « « « « « « « « 109
  54.                IFEND¼ IFT, IFF¼ IFTEST¼ IFELSE
  55.           ZEX Access and Contro∞  « « « « « « « « « « « « « « 111
  56.                ZEX Datß « « « « « « « « « « « « « « « « « « « 112
  57.                     GETZFC¼ GETZNC¼ GETZRUN¼ PUTZNC¼ PUTZRUN
  58.                ZEX Status and Contro∞ « « « « « « « « « « « « 113
  59.                     GETZEX¼ PUTZEX¼ HALTZEX¼ STOPZEX¼ STRTZEX
  60. .paè          SUBMIT and XSUB Contro∞ « « « « « « « « « « « « « « 114
  61.                SUBMIT Data and Contro∞  « « « « « « « « « « « 115
  62.                     SUBON¼ HALTSUB¼ GETSRUN¼ GETSFCB
  63.                XSUB Data and Contro∞  « « « « « « « « « « « « 116
  64.                     STOPXSUB¼ GXSUB¼ PXSUB
  65.      ZCPR3 Message≤ « « « « « « « « « « « « « « « « « « « « « 116
  66.           Command Status Messagσ  « « « « « « « « « « « « « « 118
  67.                GETCST¼ PUTCST¼ QERROR¼ QSHELL
  68.           Error Flag and Error CommanΣ  « « « « « « « « « « « 119
  69.                ERRADR¼ GETER1¼ PUTER1¼ GETERC¼ PUTERC
  70.           Inter-Transient Error Codσ  « « « « « « « « « « « « 121
  71.                GETER2¼ PUTER2
  72.           Command Error Flag and Handle≥  « « « « « « « « « « 121
  73.                GETER3¼ PUTER3¼ INVERROR
  74.           Command Status Flaτ « « « « « « « « « « « « « « « « 122
  75.                SETEPB¼ RESEPB¼ RETCST
  76.           Register Acces≤ « « « « « « « « « « « « « « « « « « 123
  77.                GETREG¼ PUTREG
  78.           Default Drive/User Buffe≥ « « « « « « « « « « « « « 124
  79.                GDEFDU¼ PDEFDU
  80.      ZCPR│ Utilitie≤  « « « « « « « « « « « « « « « « « « « « 124
  81.           Named Directory-Drive/User Conversioε « « « « « « « 124
  82.                DIRTDU¼ DUTDIR
  83.           Resolve Directory Reference≤  « « « « « « « « « « « 125
  84.                DNSCAN¼ DUSCAN¼ DIRSCAN
  85.           Parse Command Linσ  « « « « « « « « « « « « « « « « 126
  86.                PARSER
  87.           Path Search for Filσ  « « « « « « « « « « « « « « « 126
  88.                PFIND
  89.           Program Loading (Chaining⌐  « « « « « « « « « « « « 126
  90.                PRGLOAD
  91.           Console Quie⌠ Outpu⌠  « « « « « « « « « « « « « « « 127
  92.                QCOUT¼ QCRLF¼ QOUT¼ QPRINT¼ QPSTR
  93.           Locate ROOT Director∙ « « « « « « « « « « « « « « « 128
  94.                ROOT
  95.           Shell Stack Routine≤  « « « « « « « « « « « « « « « 128
  96.                SHEMPTY¼ SHFULL¼ SHPOP¼ SHPUSH
  97.           Delay Routine≤  « « « « « « « « « « « « « « « « « « 129
  98.                WAIT1S¼ WAIT1MS¼ WAITP1S
  99.           Log into ZCPR3 Filσ Contro∞ Block Drive/Use≥  « « « 130
  100.                Z3LOG
  101.           Return Z3LIB Versioε  « « « « « « « « « « « « « « « 130
  102.                Z3LVER
  103.           Parse Tokeε « « « « « « « « « « « « « « « « « « « « 131
  104.                ZPRSFN, ZFNAME
  105.           ZCPR 3.3 Parser≤  « « « « « « « « « « « « « « « « « 131
  106.                Z33FNAME¼ PARSE2¼ REPARSE¼ SCAN
  107.           Check ZCP╥ 3.3 Parse Result≤  « « « « « « « « « « « 132
  108.                FCB1CHK, FCB2CHK¼ FCBCHK
  109.           Print Load Module Datß  « « « « « « « « « « « « « « 133
  110.                PRTTYPE
  111.           ZCP╥ 3.3 Internal Program Namσ  « « « « « « « « « « 133
  112.                GETNAME¼ PRTNAME
  113.           Highest Useable Memor∙  « « « « « « « « « « « « « « 134
  114.                GZMTOPè.pa
  115.  
  116.            Z3LI┬ -¡ ZCPR│ Suppor⌠ anΣ Acces≤ Routines
  117.  
  118.  
  119. INTRODUCTION:é á Z3LI┬ ácontain≤ suppor⌠ utilitie≤ áwhicΦ áprovidσ ì
  120. acces≤ t∩ ZCPR│¡ specifiπ feature≤ anΣ capabilities«  Z3LI┬ árouì
  121. tine≤ caε bσ divideΣ int∩ fou≥ categories:
  122.  
  123.      1.ZCPR│ áEnvironmen⌠ Acces≤ ¡¡ Utilitie≤ enablinτ áyo⌡ át∩ ì
  124. áááááeasil∙ áextrac⌠ datß froφ thσ Z│ Environmen⌠ Descripto≥ áanΣ ì
  125. ááááámodif∙ certaiε Z│ environmen⌠ parameters.
  126.  
  127.      2.ZCPR│ áFlo≈ Contro∞ ¡¡ Utilitie≤ allowinτ yo⌡ t∩ áeasil∙ ì
  128. ááááámanipulatσ áZCPR3'≤ Flo≈ Contro∞ environmen⌠ b∙ áraisinτ áo≥ ì
  129. ááááálowerinτ áthσ curren⌠ I╞ leve∞ anΣ togglinτ thσ ácurren⌠ áI╞ ì
  130. ááááácondition.
  131.  
  132.      3.ZCPR│ áMessage≤ ¡¡ Utilitie≤ providinτ acces≤ át∩ áZCPR│ ì
  133. ááááámessages¼ enablinτ program≤ t∩ reaΣ anΣ writσ message≤ áfroφ ì
  134. áááááanΣ t∩ thσ system.
  135.  
  136.      4.ZCPR│ áUtilitie≤ á¡¡ Utilitie≤ whicΦ árelievσ áyo⌡ áfroφ ì
  137. áááááconstantl∙ reprogramminτ somσ commonl∙-useΣ ZCPR│ features.
  138.  
  139. EXTENDE─ áENVIRONMEN╘ DESCRIPTION:é  Versioε ┤ oµ áZ3LI┬ áincorpoì
  140. rate≤ áman∙ áenhanceΣ function≤ developeΣ b∙ Joσ Wrigh⌠ áanΣ áJa∙ ì
  141. Sagσ iε NZCO═ anΣ ZCPR3│ anΣ 34«  Duσ t∩ redefinitioε oµ somσ áoµ ì
  142. thσ ábyte≤ iε thσ Environmen⌠ Descriptor¼ ß fe≈ oµ áthσ áorigina∞ ì
  143. module≤ áwil∞ no⌠ perforφ a≤ originall∙ intended« á Fo≥ áexample¼ ì
  144. onl∙ onσ consolσ (CR╘ device⌐ i≤ supported«  Thσ remaininτ áspacσ ì
  145. iε thσ EN╓ contain≤ vector≤ t∩ systeφ segments.
  146.  
  147. Somσ program≤ sucΦ a≤ Plu*Perfec⌠ Systemsº JETLD╥ anΣ Alphß áSysì
  148. temsº NZCO═ se⌠ aε existinτ Environmen⌠ Descripto≥ t∩ reflec⌠ thσ ì
  149. necessar∙ áextendeΣ ádefinitions«  Iµ yo⌡ d∩ áno⌠ ároutinel∙ áusσ ì
  150. eithe≥ áoµ thesσ products¼ yo⌡ shoulΣ creatσ ß ne≈ áSYS.EN╓ áfilσ ì
  151. fo≥ usσ witΦ you≥ existinτ ZCPR│ system«  Thσ ne≈ definition≤ arσ ì
  152. markeΣ áwitΦ aε asterisδ (*⌐ iε thσ followinτ sourcσ codσ ásamplσ ì
  153. Environmen⌠ Descriptor.
  154. 
  155.      ; Library:  NZENV.LIB
  156.      ; Author:   Joe Wright
  157.      ; Version:  1.0
  158.      ; Date:     29 Nov 87
  159.  
  160.      ; Adapted from Rick Conn's original SYSENV.LIB circa 1984
  161.  
  162.      Z3ENV║    J╨        CBIOS+╢   ;* Real BIOS Addr (+6) for your
  163.                                    ╗  system (* Was JP 0 *)
  164.                DEF┬      'Z3ENVº   ; Environment ID
  165.                DEF┬      80╚       ;* Extended Env shown by Bit 7
  166.  
  167.                DEF╫      EXPAT╚    ; External Path address
  168.                DEF┬      EXPATH╙   ; # of 2-byte elements in Path
  169. è               DEF╫      RC╨       ; RCP address
  170.                DEF┬      RCP╙      ; # of 128-byte blocks in RCP
  171.  
  172.                DEF╫      IO╨       ; IOP address
  173.                DEF┬      IOP╙      ; # of 128-byte blocks in IOP
  174.  
  175.                DEF╫      FC╨       ; FCP address
  176.                DEF┬      FCP╙      ; # of 128-byte blocks in FCP
  177.  
  178.                DEF╫      Z3NDI╥    ; NDR address
  179.                DEFB      Z3NDIRS   ; # of 18-byte entries in NDR
  180.  
  181.                DEFW      Z3CL      ; ZCPR3 Command Line
  182.                DEFB      Z3CLS     ; # of bytes in Command Line
  183.  
  184.                DEFW      Z3ENV     ; ZCPR3 Environment Descriptor
  185.                DEFB      Z3ENVS    ; # of 128-byte blks in ENV
  186.  
  187.                DEFW      SHSTK     ; Shell Stack address
  188.                DEFB      SHSTKS    ; # SHSIZE-byte entries in Stk
  189.                DEFB      SHSIZE    ; Size of a Shell Stack entry
  190.  
  191.                DEFW      Z3MSG     ; ZCPR3 Message Buffer
  192.  
  193.                DEFW      EXTFCB    ; ZCPR3 External FCB
  194.  
  195.                DEFW      EXTSTK    ; ZCPR3 External Stack
  196.  
  197.                DEFB      0         ; Quiet flag (0=not quiet)
  198.  
  199.                DEFW      Z3WHL     ; Address of Wheel Byte
  200.  
  201.                DEFB      4         ; Processor Speed in MHz
  202.  
  203.                DEFB      'P'-'@'   ; Maximum Disk
  204.                DEFB      31        ; Maximum User
  205.                DEFB      1         ; 1=Ok to accept DU:, 0=Not Ok
  206.  
  207.                DEFB      0         ;* CRT Selection   (* Unused *)
  208.                DEFB      0         ; Printer Sel (only 0 or 1)
  209.  
  210.                DEFB      80        ; Width of CRT 0
  211.                DEFB      24        ; Number of lines on CRT 0
  212.                DEFB      22        ; Number of text lines on CRT 0
  213.  
  214.      ; CRT 1 descriptor is replaced with this valid drive vector.
  215.      ; The command processor ignores 'maximum disk' above, and uses
  216.      ; this vector instead.  This allows 'holes' in the disk map.
  217.      ; A user might have drives A, B, E, F, and G for example.  In
  218.      ; this case, his vector would look like:
  219.      ;    DEFW 0000000001110011B
  220.      ; The command processor will treat drive C the same as drive H
  221.      ; (unavailable) and take appropriate action.  
  222.  
  223.                DEFW      1111111111111111B ;* Valid drive vector (16)è               DEFB      0         ;* Not used
  224.  
  225.                DEFB      80        ; Width of Printer 0
  226.                DEFB      66        ; Number of lines on Printer 0
  227.                DEFB      58        ; Number of text lines on Ptr 0
  228.                DEFB      1         ; H/W Form Feed (0=can't,1=can)
  229.  
  230.                DEFB      102       ; Width of Printer 1
  231.                DEFB      66        ; Number of lines on Printer 1
  232.                DEFB      58        ; Number of text lines on Ptr 1
  233.                DEFB      1         ; H/W Form Feed (0=can't,1=can)
  234.  
  235.      ;* Descriptors for Printers 2 and 3 replaced with System Data
  236.  
  237.                DEFW      CCP       ;* ZCPR 3.x start loc'n       3FH
  238.                DEFB      CCPS      ;* Size in records            41H
  239.  
  240.                DEFW      DOS       ;* DOS starting location      42H
  241.                DEFB      DOSS      ;* Size in records            44H
  242.  
  243.                DEFW      BIOS      ;* NZBIO starting location    45H
  244.  
  245.                DEFB      'SH      ' ; Shell Variable Filename
  246.                DEFB      'VAR'     ; Shell Variable Filetype
  247.  
  248.                DEFB      '        ' ; Filename 1
  249.                DEFB      '   '     ; Filetype 1
  250.  
  251.                DEFB      '        ' ; Filename 2
  252.                DEFB      '   '     ; Filetype 2
  253.  
  254.                DEFB      '        ' ; Filename 3
  255.                DEFB      '   '     ; Filetype 3
  256.  
  257.                DEFB      '        ' ; Filename 4
  258.                DEFB      '   '     ; Filetype 4
  259.  
  260.                DEFB      0         ;* Public drive OFF           7EH
  261.                DEFB      0         ;* Public user OFF            7FH
  262.                                    ;  (* Only defined for ZRDOS *)
  263.  
  264.      ; This dummy Terminal Capabilities description (Z3TCAP) will
  265.      ; normally be replaced with a tailored MYTERM.Z3T on start up.
  266.  
  267.      ENVORG2:  DEFB      '               ' ; Terminal Name (15 chars)
  268.                DEFB      0         ; No terminal attributes
  269.                DEFB      'E'-'@'   ; Cursor Up
  270.                DEFB      'X'-'@'   ; Cursor Down
  271.                DEFB      'D'-'@º   ; Cursor Right
  272.                DEFB      'S'-'@'   ; Cursor Left
  273.                DEFB      0         ; Cl delay
  274.                DEFB      0         ; Cm delay
  275.                DEFB      0         ; Ce delay
  276.                DEFB      0         ; Cl string
  277.                ─EFB      0         ; Cm stringè               DEFB      0         ; Ce string
  278.                DEFB      0         ; So string
  279.                DEFB      0         ; Se string
  280.                DEFB      0         ; Ti string
  281.                DEFB      0         ; Te string
  282.  
  283.      ; File filled with Zeros to end of 128-byte segment
  284. 
  285. ACCES╙ T╧ TH┼ ZCPR│ ENVIRONMENT:é  An∙ prograφ runninτ unde≥ ZCPR│ ì
  286. i≤ áwithiε áß ZCPR│ environment«  Man∙ facilitie≤ áanΣ ádatß áarσ ì
  287. availablσ át∩ áthi≤ prograφ whicΦ t∩ no⌠ exis⌠ áfo≥ ánorma∞ áCP/═ ì
  288. programs«  Fo≥ instance¼ ß prograφ runninτ unde≥ thσ ZCPR│ áenvΘì
  289. ronmen⌠ can:
  290.    o Find out what name it was invoked by
  291.    o Acces≤ áß se⌠ oµ message≤ froφ ZCPR│ whicΦ tel∞ i⌠ ß ánumbe≥ ì
  292. áááááoµ thing≤ abou⌠ ho≈ i⌠ wa≤ invoked
  293.    o SenΣ message≤ t∩ ZCPR│ anΣ program≤ whicΦ ruε afte≥ i⌠ ácomì
  294. ááááápletes
  295.    o FinΣ áou⌠ áman∙ thing≤ abou⌠ it≤ environment¼ ásucΦ áa≤ áthσ ì
  296. áááááprocesso≥ áspeed¼ CR╘ anΣ printe≥ ácharacteristics¼ ámaximuφ ì
  297. ááááánumbe≥ oµ disks
  298.    o Determinσ thσ you≥ termina∞ characteristic≤ anΣ usσ theφ át∩ ì
  299. áááááenhancσ áthσ displa∙ witΦ visua∞ attribute≤ sucΦ áa≤ ácurso≥ ì
  300. áááááaddressinτ anΣ highlighteΣ text.
  301.  
  302. Thσ informatioε outlineΣ abovσ anΣ morσ i≤ availablσ t∩ an∙ áproì
  303. graφ áthr⌡ thσ ZCPR│ Environmen⌠ Descriptor«  Thi≤ i≤ ß á25╢-bytσ ì
  304. blocδ oµ memor∙ containinτ addresse≤ anΣ othe≥ datß iε ß preciseì
  305. l∙-defineΣ format«  ZCPR│ utilitie≤ ma∙ bσ writteε witΦ aε interì
  306. na∞ áEnvironmen⌠ áDescripto≥ o≥ the∙ ma∙ áacces≤ áaε áEnvironmen⌠ ì
  307. Descripto≥ áresidinτ a⌠ somσ fixeΣ memor∙ locatioε (thi≤ ái≤ áthσ ì
  308. preferreΣ approach)«  Wheε executed¼ program≤ caε extrac⌠ áspeciì
  309. fiπ informatioε froφ thσ descripto≥ fo≥ use.
  310.  
  311. Thσ followinτ informatioε i≤ containeΣ withiε ß ZCPR│ Environmen⌠ ì
  312. Descriptor:
  313.      address of external path      size of external path
  314.      address of RCP                size of RCP
  315.      address of FCP                size of FCP
  316.      address of IOP                size of IOP
  317.      address of named directory    size of named directory
  318.      address of command line       size of command line
  319.      address of env descriptor     size of env descriptor
  320.      address of shell stack        size of shell stack
  321.      address of Z3 messages        size of stack entries
  322.      address of external FCB       address of external stack
  323.      address of wheel byte         quiet flag
  324.      processor speed               DU approval flag
  325.      maximum disk allowed          maximum user allowed
  326.      data on CRT                   data on printer
  327.      two reserved filenames        ZCPR3 TERMCAP (Z3TCAP)
  328.  
  329. Thσ purposσ oµ Z3LI┬ i≤ t∩ providσ yo⌡ witΦ eas∙ acces≤ t∩ inforì
  330. matioε áiε thσ ZCPR│ Environmen⌠ Descripto≥ anΣ t∩ allo≈ áyo⌡ át∩ ì
  331. easil∙ áusσ thi≤ information«  T∩ illustrate¼ somσ oµ áthσ áZ3LI┬ ìèroutine≤ are:
  332.  
  333.    o GETPR╘ á¡¡ áreturε datß oε thσ width¼ numbe≥ oµ álines¼ áanΣ ì
  334. áááááforφ feeΣ abilit∙ oµ thσ printer
  335.    o GETCL▓ á¡¡ returε thσ addres≤ oµ thσ firs⌠ characte≥ oµ áthσ ì
  336. ááááánex⌠ commanΣ t∩ bσ run¼ iµ any
  337.    o GETEFC┬ á¡¡ áreturε thσ addres≤ oµ thσ externa∞ FC┬ ás∩ áthσ ì
  338. áááááprograφ caε determinσ it≤ name
  339.    o SHPUSH -- push a command line on the shell stack
  340.    o SHPOP -- pop a command line from the shell stack
  341.    o IFT -- invoke the next IF level and make it T
  342.    o IFEND -- back up to previous IF level
  343.  
  344. Thi≤ filσ describe≤ thosσ Z3LI┬ routine≤ whicΦ providσ acces≤ át∩ ì
  345. thσ áZCPR│ Environmen⌠ Descripto≥ data«  Man∙ oµ áthesσ ároutine≤ ì
  346. arσ oµ thσ genera∞ name:
  347.      GETxxxxx
  348. wherσ áthσ mnemoniπ followinτ thσ GE╘ prefi° allude≤ t∩ wha⌠ áinì
  349. formatioε i≤ beinτ obtained.
  350.  
  351. COMMAND LINE:
  352.  
  353.      Routine║   APPCL
  354.      Function║ Append command string to command line buffer
  355.      Entry║    HL = address of command string to append
  356.      Exit║     A <> 0, zero flag clear (NZ) if append complete
  357.                ┴ ╜ 0¼ zer∩ flaτ se⌠ (Z⌐ iµ buffe≥ overflow≤ o≥ n∩ ì
  358. ááááááááááááááácommanΣ linσ buffe≥ (n∩ changσ t∩ commanΣ line)
  359.      Affected║ AF╗ command line buffer is changed
  360.      Usage:    Append≤ ááthσ áspecifieΣ áNU╠-terminateΣ áácommanΣ ì
  361. ááááááááááááááástrinτ t∩ thσ enΣ oµ thσ ZCPR│ commanΣ linσ buffe≥ ì
  362. áááááááááááááááfo≥ áexecution«  ┴ leadinτ semicoloε i≤ áprependeΣ ì
  363. ááááááááááááááát∩ allo≈ thi≤ linσ t∩ executσ afte≥ thσ las⌠ álinσ ì
  364. áááááááááááááááiε áthσ buffer«  Thσ commanΣ linσ buffe≥ ácontent≤ ì
  365. áááááááááááááááarσ árepackeΣ át∩ aver⌠ overflo≈ áiε ámos⌠ ácases«  ì
  366. áááááááááááááááPUTC╠ ái≤ áß complementar∙ functioε iε áwhicΦ áthσ ì
  367. ááááááááááááááácommanΣ ástrinτ i≤ addeΣ t∩ thσ beginninτ áoµ áthσ ì
  368. ááááááááááááááácommanΣ linσ buffe≥ a≤ thσ firs⌠ command.
  369.  
  370.      Routine║   CLRCL
  371.      Function║ Clear the command line buffer
  372.      Entry:    None
  373.      Exit:     A <> 0, zero flag clear (NZ) if command line cleared
  374.                A = 0, zero flag set (Z) if no command line buffer
  375.      Affected: AF
  376.      Usage:    Clear≤ áthσ commanΣ linσ buffe≥ b∙ settinτ ái⌠ át∩ ì
  377. áááááááááááááááempty«  An∙ remaininτ command≤ iε thσ buffe≥ áwil∞ ì
  378. áááááááááááááááno⌠ bσ executeΣ wheε contro∞ i≤ returneΣ t∩ ZCPR3.
  379. .paè     Routine║   GETCL1
  380.      Function║ Return pointer to command line buffer
  381.      Entry:    None
  382.      Exit:     H╠ ╜ addres≤ oµ commanΣ linσ buffe≥ (░ iµ nonexisì
  383. ááááááááááááááátent)
  384.                A = size of buffer
  385.      Affected: AF¼ HL
  386.      Usage:    Locate≤ áanΣ return≤ commanΣ linσ ábuffe≥ áparameì
  387. áááááááááááááááters«  Thσ commanΣ linσ buffe≥ i≤ structureΣ as:
  388.                     CMDLIN║   DEF╫      <address of next character to process>
  389.                               DEF┬      <size of buffer in bytes>
  390.                               DEFB      <dummy used for BDOS READLN function>
  391.                               DEFB      <....chars in command line>
  392.                               DEFB      0              ; end of command string
  393.  
  394.      Routine║   GETCL2
  395.      Function║ Return next command info from command line buffer
  396.      Entry:    None
  397.      Exit:     H╠ ╜ addres≤ oµ nex⌠ commanΣ (░ iµ n∩ commanΣ linσ ì
  398. ááááááááááááááábuffer)
  399.                ┴ ╜ firs⌠ characte≥ oµ command¼ zer∩ clea≥ (NZ⌐ iµ ì
  400. ááááááááááááááávalid
  401.                A = 0, zero flag set (Z) if no characters in line
  402.                Affected: AF¼ HL
  403.      Usage:    UseΣ áiε application≤ wherσ yo⌡ neeΣ át∩ ádirectl∙ ì
  404. áááááááááááááááacces≤ ácharacter≤ iε thσ nex⌠ commanΣ ástoreΣ áiε ì
  405. áááááááááááááááthσ commanΣ linσ buffer.
  406.  
  407.      Routine║   PUTCL
  408.      Function: Storσ ácommanΣ linσ a⌠ beginninτ oµ ácommanΣ álinσ ì
  409. ááááááááááááááábuffer
  410.      Entry:    HL = address of NUL-terminated command line
  411.      Exit:     A <> 0, zero flag clear (NZ) if OK
  412.                A = 0 zero set (Z) if overflow (no buffer change)
  413.      Affected: AF
  414.      Usage:    Add≤ ß commanΣ linσ a≤ ß prefi° iε thσ ZCPR│ ácomì
  415. ááááááááááááááámanΣ linσ buffe≥ a≤ opposeΣ t∩ APPC╠ whicΦ append≤ ì
  416. ááááááááááááááát∩ áthσ áenΣ oµ thσ commanΣ linσ ábuffer« á Buffe≥ ì
  417. ááááááááááááááácontent≤ áarσ árepackeΣ ás∩ tha⌠ áaε áoverflo≈ ái≤ ì
  418. áááááááááááááááaverteΣ áiε ámos⌠ ácases«  Iµ áß ácommanΣ áalread∙ ì
  419. áááááááááááááááexist≤ áiε thσ buffer¼ thσ ne≈ linσ ái≤ ápostfixeΣ ì
  420. áááááááááááááááwitΦ ß semicoloε s∩ continuatioε i≤ enabled.
  421.  
  422. CR╘ AN─ PRT DATA:
  423.  
  424.      Routine║   GETCRT
  425.      Function║ Return address of CRT data record from ENV
  426.      Entry:    None
  427.      Exit:     HL = address of CRT record
  428.      Affected: HL
  429.      Usage:    Determine≤ thσ parameter≤ oµ thσ installeΣ átermiì
  430. ááááááááááááááánal«  Thσ CR╘ recorΣ i≤ structureΣ as:
  431.                     CRTDAT║   DEF┬      8░        ; width of CRT in characters
  432.                               DEFB      24        ; number of lines on the screen
  433.                               DEFB      22        ; number of text lines on screenè
  434.                Thσ ánumbe≥ oµ tex⌠ line≤ shoulΣ bσ tw∩ les≤ áthaε ì
  435. áááááááááááááááthσ átota∞ numbe≥ oµ lines«  Yo⌡ ma∙ providσ ámorσ ì
  436. áááááááááááááááoverla≡ áb∙ ámakinτ i⌠ │ o≥ ┤ less« á Thi≤ árecorΣ ì
  437. áááááááááááááááelemen⌠ átell≤ utilitie≤ likσ PAG┼ ho≈ man∙ áline≤ ì
  438. ááááááááááááááát∩ outpu⌠ beforσ pausinτ t∩ allo≈ yo⌡ t∩ reaΣ áthσ ì
  439. áááááááááááááááscreen« á Thi≤ ácaε ábσ reduceΣ (g∩ t∩ á2░ áo≥ á1╕ ì
  440. ááááááááááááááálines⌐ át∩ áallo≈ áyo⌡ t∩ seσ ámorσ áoµ áthσ álas⌠ ì
  441. áááááááááááááááscreen.
  442.  
  443.      Routine║   GETPRT
  444.      Function║ Return the address of the printer data record
  445.      Entry:    None
  446.      Exit:     HL = address of printer data record
  447.      Affected: HL
  448.      Usage:    Provide≤ datß oε somσ oµ thσ printe≥ ácharacterisì
  449. ááááááááááááááátic≤ áfo≥ áusσ iε formattinτ ároutines¼ áo≥ áothe≥ ì
  450. áááááááááááááááuses« á Thσ returneΣ pointe≥ i≤ t∩ ß printe≥ ádatß ì
  451. ááááááááááááááárecorΣ as:
  452.                     PRTDAT║   DEF┬      8░        ; width of printer in characters
  453.                               DEFB      66        ; number of lines on printer page
  454.                               DEFB      58        ; number of text lines per page
  455.                               DEFB      1         ; formfeed flag (0=can't FF, 1=can)
  456.  
  457.                Program≤ ásucΦ áa≤ PRIN╘ ma∙ áusσ áthσ ádifferencσ ì
  458. ááááááááááááááábetweeε thσ thirΣ anΣ seconΣ entrie≤ t∩ ádeterminσ ì
  459. áááááááááááááááto≡ anΣ bottoφ margins¼ anΣ tes⌠ thσ las⌠ bytσ át∩ ì
  460. ááááááááááááááádeterminσ áwhethe≥ át∩ issuσ ß formfeeΣ áo≥ ácoun⌠ ì
  461. ááááááááááááááálinσ feeΣ character≤ t∩ advancσ t∩ thσ nex⌠ page.
  462.  
  463.      Routine║   PUTCRT
  464.      Function║ Stores terminal select byte (no real function)
  465.      Entry:    A = selection value (0)
  466.      Exit:     A <> 0, zero flag clear (NZ) if entry was 0
  467.                A = 0, zero flag set (Z) if invalid (not 0)
  468.      Affected: AF
  469.      Usage:    Perform≤ n∩ actua∞ functioε iε thσ extendeΣ áenviì
  470. áááááááááááááááronmen⌠ áwhicΦ support≤ onl∙ onσ defineΣ CR╘ ádatß ì
  471. áááááááááááááááblock« á Fo≥ compatibility¼ i⌠ sense≤ áthσ áselec⌠ ì
  472. ááááááááááááááávaluσ anΣ simpl∙ return≤ statu≤ baseΣ oε it.
  473.  
  474.      Routine║   PUTPRT
  475.      Function║ Store printer selection byte (0..1) in environment
  476.      Entry:    A = printer selection value (0 or 1)
  477.      Exit:     A <> 0, zero flag clear (NZ) if OK
  478.                A = 0, zero flag set (Z) if invalid (not 0 or 1)
  479.      Affected: AF
  480.      Usage:    Store≤ thσ selectioε (░ o≥ 1⌐ iε thσ PR╘ selectioε ì
  481. ááááááááááááááábuffe≥ oµ thσ ZCPR│ Environmen⌠ Descripto≥ showinτ ì
  482. ááááááááááááááátha⌠ ái⌠ i≤ thσ currentl∙ activσ áprinter« á Unde≥ ì
  483. áááááááááááááááthσ extendeΣ environment¼ onl∙ tw∩ printer≤ ma∙ bσ ì
  484. ááááááááááááááádefineΣ insteaΣ oµ thσ fou≥ originall∙ supported.
  485. .paèEXTERNA╠ FIL┼ CONTRO╠ BLOCK:
  486.  
  487.      Routine║   GETEFCB
  488.      Function: Returε áthσ áaddres≤ oµ thσ áZCPR│ áexterna∞ áfilσ ì
  489. ááááááááááááááácontro∞ blocδ (FCB)
  490.      Entry:    None
  491.      Exit:     HL = address of external FCB
  492.                A <> 0, zero flag clear (NZ) if OK
  493.                A = 0, zero flag set (Z) if not found
  494.      Affected: AF¼ HL
  495.      Usage:    Unde≥ áZCPR3¼ ß prograφ caε finΣ ou⌠ b∙ wha⌠ ánamσ ì
  496. ááááááááááááááái⌠ wa≤ invokeΣ througΦ thσ externa∞ FCB«  Byte≤ ▒-ì
  497. ááááááááááááááá╕ áoµ thσ externa∞ FC┬ (firs⌠ bytσ i≤ á0⌐ ácontaiε ì
  498. áááááááááááááááthσ namσ oµ thσ prograφ jus⌠ executeΣ b∙ ZCPR3.
  499.  
  500.                Thi≤ áfeaturσ ái≤ particularl∙ usefu∞ áfo≥ áshell≤ ì
  501. áááááááááááááááwhicΦ áhavσ át∩ pusΦ thei≥ ánamσ áanΣ áoperationa∞ ì
  502. áááááááááááááááparameter≤ áont∩ áthσ shel∞ stacδ iε orde≥ át∩ ábσ ì
  503. áááááááááááááááreinvokeΣ wheε ß commanΣ linσ completes«  ┴ áshel∞ ì
  504. ááááááááááááááácaε usσ thσ datß iε thσ externa∞ FC┬ t∩ ádeterminσ ì
  505. áááááááááááááááwha⌠ it≤ namσ i≤ withou⌠ havinτ t∩ assumσ tha⌠ ái⌠ ì
  506. áááááááááááááááha≤ ß particula≥ namσ a⌠ al∞ times.
  507.  
  508. ENVIRONMENT:
  509.  
  510.      Routine║   GETENV
  511.      Function║ Return address of the ZCPR3 Environment Descriptor
  512.      Entry:    None
  513.      Exit:     HL = address of Environment Descriptor
  514.      Affected: HL
  515.      Usage:    Fo≥ thosσ program≤ whicΦ neeΣ t∩ modif∙ thσ áZCPR│ ì
  516. áááááááááááááááEnvironmen⌠ áDescriptor«  Mos⌠ oµ thσ routine≤ áiε ì
  517. áááááááááááááááZ3LI┬ áwhicΦ acces≤ thσ Environmen⌠ Descripto≥ ád∩ ì
  518. ááááááááááááááás∩ iε ß R/╧ modσ (the∙ d∩ no⌠ allo≈ thσ prograφ t∩ ì
  519. áááááááááááááááchangσ datß iε it)«  Somσ program≤ ma∙ neeΣ t∩ ád∩ ì
  520. áááááááááááááááthis¼ s∩ GENEN╓ i≤ provided«  Z3LDR¼ fo≥ áexample¼ ì
  521. áááááááááááááááload≤ ß ne≈ Environmen⌠ Descripto≥ froφ ß filσ áoε ì
  522. ááááááááááááááádisk¼ anΣ i⌠ use≤ GETEN╓ t∩ finΣ ou⌠ wherσ t∩ loaΣ ì
  523. áááááááááááááááthσ file.
  524.  
  525.      Routine║   GETVID
  526.      Function║ Return address of the ZCPR3 TCAP (Z3TCAP)
  527.      Entry:    None
  528.      Exit:     HL = address of Z3TCAP buffer
  529.                A <> 0, zero flag clear (NZ) if OK
  530.                A = 0, zero flag set (Z) if no entry in buffer
  531.      Affected: AF¼ HL
  532.      Usage:    Fo≥ thosσ program≤ whicΦ neeΣ t∩ modif∙ thσ áZCPR│ ì
  533. áááááááááááááááTCA╨ ábuffe≥ anΣ thosσ program≤ whicΦ neeΣ t∩ ádeì
  534. áááááááááááááááterminσ áiµ thσ TCA╨ i≤ loaded«  I⌠ ma∙ bσ ádesirì
  535. áááááááááááááááablσ t∩ cal∞ thi≤ routinσ beforσ ß screeε-orienteΣ ì
  536. áááááááááááááááutilit∙ ái≤ áexecuteΣ át∩ insurσ tha⌠ áß áTCA╨ ái≤ ì
  537. áááááááááááááááavailable.
  538. .paèFLO╫ COMMAND PACKAG┼ (FCP⌐ ADDRESS:
  539.  
  540.      Routine║   GETFCP
  541.      Function║ Return address of the flow commanΣ package buffer
  542.      Entry:    None
  543.      Exit:     HL = address of FCB buffer
  544.                ┴ ╜ numbe≥ oµ 12╕-bytσ FC╨ blocks¼ zer∩ clea≥ (NZ⌐ ì
  545. áááááááááááááááiµ OK
  546.                A = 0, zero flag set (Z) if no buffer
  547.      Affected: AF¼ HL
  548.      Usage:    Return≤ áthσ FC┬ parameter≤ froφ áthσ áEnvironmen⌠ ì
  549. áááááááááááááááDescriptor«  Thσ startinτ addres≤ anΣ sizσ oµ áthσ ì
  550. áááááááááááááááFC╨ ábuffe≥ áiε term≤ oµ 12╕-bytσ block≤ áarσ áreì
  551. áááááááááááááááturned«  T∩ finΣ ou⌠ iµ aε FC╨ i≤ installed¼ álooδ ì
  552. áááááááááááááááa⌠ áthσ áfirs⌠ bytσ oµ thσ FC╨ buffer«  Iµ ái⌠ ái≤ ì
  553. ááááááááááááááázero¼ theε n∩ FC╨ i≤ present.
  554.      Example:
  555.                          EXT       GETFCP         ; declare the routine
  556.                          ...                      ; ..preliminary code
  557.                          CALL      GETFCP         ; get addr/size from ENV
  558.                          JR        Z,NOFCP        ; ..jump if no FCB buffer avail
  559.                          LD        A,(HL)         ; examine the first buffer byte
  560.                          OR        A              ; anything installed?
  561.                          JR        Z,LODFCP       ; ..jump to load an FCP if not
  562.                          ...                      ; else use existing one
  563.  
  564. FILENAMES:
  565.  
  566.      Routine║   GETFN1 ¼  GETFN2
  567.      Function: GETFN▒ áget≤ addres≤ oµ shel∞ ávariablσ áfilename¼ ì
  568. áááááááááááááááGETFN▓ get≤ addres≤ oµ firs⌠ oµ systeφ filenames
  569.      Entry:    None
  570.      Exit:     H╠ ╜ addres≤ oµ 1▒-characte≥ filσnamσ entry
  571.      Affected: HL
  572.      Usage:    Return≤ áthσ addres≤ iε H╠ oµ thσ áshel∞ ávariablσ ì
  573. áááááááááááááááfilenamσ (GETFN1⌐ anΣ thσ firs⌠ oµ thσ fou≥ systeφ ì
  574. áááááááááááááááfilename≤ á(GETFN2⌐ iε thσ ZCPR│ áEnvironmen⌠ áDeì
  575. áááááááááááááááscriptor« á Thσ filenamσ entr∙ i≤ 1▒ ábyte≤ álong¼ ì
  576. ááááááááááááááámatchinτ áthσ filenamσ anΣ filetypσ field≤ oµ áthσ ì
  577. áááááááááááááááCP/═ filσ contro∞ block.
  578.  
  579.                Thesσ filename≤ arσ useΣ t∩ pas≤ name≤ oµ áspecia∞ ì
  580. áááááááááááááááfile≤ t∩ program≤ fo≥ late≥ use«  Thei≥ exac⌠ áusσ ì
  581. ááááááááááááááái≤ áno⌠ defineΣ anΣ i≤ lef⌠ t∩ you«  Onσ áapplicaì
  582. ááááááááááááááátioε áwoulΣ bσ t∩ allo≈ GETFN▒ t∩ returε thσ ánamσ ì
  583. áááááááááááááááoµ thσ maste≥ HL╨ filσ (HELP.HLP⌐ t∩ bσ useΣ a≤ aε ì
  584. áááááááááááááááinde° int∩ thσ hel≡ system.
  585. .paè     Routine║   GETFNX
  586.      Function║ Return address of nth filename of system filenames
  587.      Entry:    A = filename number (1..4) in ENV filename buffer
  588.      Exit:     H╠ á╜ addres≤ oµ firs⌠ bytσ oµ indicateΣ filσ á(1▒ ì
  589. ááááááááááááááácharacters)
  590.                A <> 0, zero flag clear (NZ) if OK
  591.                ┴ á╜ á0¼ zer∩ flaτ se⌠ (Z⌐ iµ inpu⌠ valuσ áno⌠ áiε ì
  592. ááááááááááááááá1..┤ range
  593.      Affected: AF¼ HL
  594.      Usage:    Return≤ áthσ áaddres≤ oµ thσ ntΦ filenamσ áiε áthσ ì
  595. áááááááááááááááZCPR│ áEnvironmen⌠ áDescriptor« á Therσ áarσ áfou≥ ì
  596. ááááááááááááááásysteφ files¼ numbereΣ ▒ t∩ 4¼ anΣ the∙ arσ struπì
  597. ááááááááááááááátureΣ álikσ áthσ Fn.F⌠ field≤ oµ áß áfilσ ácontro∞ ì
  598. áááááááááááááááblocδ á(1▒ ábyte≤ each)«  Oε input¼ ┴ á╜ á1..┤ át∩ ì
  599. áááááááááááááááindicatσ áthσ filename«  Oε output¼ H╠ ápoint≤ át∩ ì
  600. áááááááááááááááthσ áfirs⌠ bytσ oµ thσ name«  ┴ validit∙ checδ ái≤ ì
  601. ááááááááááááááádonσ oε thσ valuσ oµ ┴ whicΦ mus⌠ bσ 1..4.
  602.  
  603.      Routine║   PUTFNX
  604.      Function: Se⌠ ntΦ (1..4⌐ filenamσ iε Environmen⌠ Descriptor
  605.      Entry:    A = filename number (1..4)
  606.                HL = address of FCB+1 of new filename value
  607.      Exit:     A <> 0, zero flag clear (NZ) if OK
  608.                ┴ á╜ á0¼ zer∩ flaτ se⌠ (Z⌐ iµ inpu⌠ valuσ áno⌠ áiε ì
  609. ááááááááááááááá1..┤ range
  610.      Affected: AF
  611.      Usage:    Set≤ thσ ntΦ (1..4⌐ filenamσ iε thσ ZCPR│ Environì
  612. ááááááááááááááámen⌠ Descripto≥ t∩ thσ FC┬-entr∙ pointeΣ t∩ b∙ áH╠ ì
  613. ááááááááááááááá(FCB+1¼ o≥ thσ Fε field¼ i≤ pointeΣ t∩ b∙ HL)« á ┴ ì
  614. ááááááááááááááái≤ useΣ t∩ identif∙ thσ filename.
  615.  
  616. INITIALIZE:
  617.  
  618.      Routine║   WHRENV
  619.      Function: Returε áinstalleΣ áZCPR│ áEnvironmen⌠ ááDescripto≥ ì
  620. áááááááááááááááaddress
  621.      Entry:    HL = candidate address of Environment Descriptor
  622.      Exit:     HL = points to start address of ENV (0 if not found)
  623.                A <> 0, zero flag clear (NZ) if ENV validated
  624.                A = 0, zero flag set (Z) if not found
  625.      Affected: AF¼ BC¼ DE¼ HL
  626.      Usage:    Provide≤ áß mean≤ oµ locatinτ ß ZCPR│ áEnvironmen⌠ ì
  627. áááááááááááááááDescripto≥ áwithou⌠ thσ assistancσ oµ ZCP╥ 3.│ áo≥ ì
  628. ááááááááááááááálate≥ ácommanΣ processors«  Callinτ WHREN╓ witΦ áß ì
  629. ááááááááááááááácandidatσ addres≤ oµ thσ DO╙ entr∙ addres≤ áloadeΣ ì
  630. áááááááááááááááfroφ location≤ ╢ anΣ ╖ wil∞ causσ ß searcΦ fo≥ áaε ì
  631. áááááááááááááááenvironmen⌠ áfroφ tha⌠ addres≤ u≡ áthrougΦ áFEFFh«  ì
  632. áááááááááááááááCallinτ ái⌠ áwitΦ áß paramete≥ oµ á░ ápreclude≤ áß ì
  633. ááááááááááááááásearcΦ át∩ signif∙ tha⌠ thσ aut∩-searcΦ i≤ át∩ ábσ ì
  634. ááááááááááááááádisabled.
  635.      Example:
  636.                          EX╘       WHRENV,Z3INI╘  ; declare routines
  637.                          ...                      ; ..any header info here
  638.                          LD        HL,(6)         ; load candidate location
  639.                          CALL      WHRENV         ; ..and test itè                         LD        (Z3EADR),HL    ; save any returned value
  640.                          JR        Z,NOENV        ; ..jump if no ENV validated
  641.                          CALL      Z3INIT         ; else set globals (or Z3VINIT)
  642.  
  643.      Routine║   Z3INIT
  644.      Function: Se⌠ ágloba∞ buffe≥ t∩ arbitrar∙ addres≤ fo≥ áZCPR│ ì
  645. áááááááááááááááenvironment
  646.      Entry:    HL = address of ZCPR3 environment descriptor
  647.      Exit:     None
  648.      Affected: None
  649.      Usage:    Set≤ ß globa∞ variablσ t∩ thσ ZCPR│ pointe≥ ávaluσ ì
  650. áááááááááááááááinstalleΣ áiε áthσ prograφ áheader« á Thi≤ ágloba∞ ì
  651. ááááááááááááááávariablσ i≤ useΣ b∙ othe≥ Z3LI┬ routines.
  652.      Example:
  653.                          EXT       Z3INIT         ; declare the routine
  654.                          ...                      ; ..header code
  655.                          LD        HL,Z3ENV       ; load the Env Desc address
  656.                          CALL      Z3INIT         ; ..and install!
  657.                          ...                      ; carry on!
  658.  
  659. SYSTE═ DATA:
  660.  
  661.      Routine║   ZSYSCHK
  662.      Function║ Validate ZCPR3 Environment Descriptor address
  663.      Entry:    HL = points to candidate Z3 environment
  664.      Exit:     A = 0, zero set (Z) if valid environment
  665.                A <> 0, zero clear (NZ) if environment not valid
  666.      Affected: AF
  667.      Usage:    Check≤ ávariou≤ parameter≤ iε aε áEnvironmen⌠ áDeì
  668. áááááááááááááááscripto≥ ápredicateΣ oε thσ specifieΣ áaddres≤ át∩ ì
  669. áááááááááááááááseσ áiµ i⌠ i≤ valid«  I⌠ wil∞ prin⌠ ß ámessagσ áiµ ì
  670. áááááááááááááááthσ áenvironmen⌠ i≤ invalid«  Fo≥ bes⌠ result≤ áoε ì
  671. áááááááááááááááZCP╥ á3.│ áo≥ later¼ pas≤ thσ valuσ iε H╠ áa⌠ áthσ ì
  672. ááááááááááááááátimσ áthσ prograφ starts«  Thi≤ wil∞ no⌠ áworδ áoε ì
  673. áááááááááááááááZCP╥ á3.0¼ ábu⌠ wil∞ detec⌠ áBackGrounde≥ áiΘ áanΣ ì
  674. áááááááááááááááversion≤ sincσ ZCP╥ 3.3.
  675.      Example:
  676.                     EXT       ZSYSCHK             ; declare the routine
  677.                     ...
  678.                     LD        HL,(ENVADR)         ; load candidate environment
  679.                     CALL      ZSYSCHK             ; is it valid? (message if not)
  680.                     RET       NZ                  ; ..quit if invalid
  681.                     ...                           ; else continue with valid ENV
  682.  
  683.      Routine║   Z33CHK
  684.      Function║ Check for presence of ZCPR 3.3 or later
  685.      Entry:    None
  686.      Exit:     A = 0, zero set (Z) if CCP is ZCPR 3.3 or later
  687.                A <> 0, zero clear (NZ) if not ZCPR >= 3.3
  688.      Affected: AF
  689.      Usage:    ShoulΣ ábσ useΣ iε thσ initia∞ setu≡ portioε oµ áß ì
  690. áááááááááááááááprograφ áiµ man∙ oµ thσ ne≈ Z3LI┬ routine≤ arσ át∩ ì
  691. ááááááááááááááábσ used«  Routine≤ sucΦ a≤ Z33FNAM┼ rel∙ oε speciì
  692. áááááááááááááááfiπ áentr∙ point≤ iε thσ commanΣ áprocesso≥ áwhicΦ ì
  693. áááááááááááááááonl∙ áexis⌠ iε ZCP╥ 3.│ o≥ later«  Iµ ásucΦ ácall≤ ìèáááááááááááááááarσ madσ unde≥ othe≥ commanΣ processors¼ o≥ iµ thσ ì
  694. áááááááááááááááC╨ i≤ overwritten¼ you≥ prograφ wil∞ bσ unablσ át∩ ì
  695. áááááááááááááááfunction.
  696.      Example:
  697.                          EXT       Z33CHK         ; declare the routine
  698.                          ...
  699.                          CALL      Z33CHK         ; Is CP ZCPR 3.3 or later?
  700.                          JR        NZ,NOTZ3       ; ..jump if not
  701.                          ...                      ; else we can use it
  702.  
  703.      Routine║   GETBDOS
  704.      Function║ Return BDO╙ start address
  705.      Entry:    None
  706.      Exit:     HL = calculated or loaded BDOS starting address
  707.      Affected: HL
  708.      Usage:    Return≤ áthσ ástartinτ addres≤ oµ thσ áBasiπ áDisδ ì
  709. áááááááááááááááOperatinτ Systeφ (BDOS⌐ froφ aε extendeΣ áenvironì
  710. ááááááááááááááámen⌠ iµ present¼ elsσ i⌠ wil∞ calculatσ thσ startì
  711. áááááááááááááááinτ addres≤ froφ thσ BIO╙ warφ boo⌠ vecto≥ áassumì
  712. áááááááááááááááinτ áß á3.5╦ BDO╙ size«  Yo⌡ shoulΣ no⌠ áusσ áthi≤ ì
  713. áááááááááááááááaddres≤ áa≤ thσ to≡ oµ availablσ memory¼ bu⌠ áonl∙ ì
  714. ááááááááááááááát∩ locatσ thσ DOS«  Usσ thσ addres≤ a⌠ location≤ ╢ ì
  715. áááááááááááááááanΣ ╖ o≥ GZMTO╨ t∩ finΣ thσ highes⌠ usablσ ámemor∙ ì
  716. ááááááááááááááálocatioε dependinτ oε whethe≥ o≥ no⌠ thσ CC╨ i≤ t∩ ì
  717. ááááááááááááááábσ retained.
  718.  
  719.      Routine║   GETCCP
  720.      Function║ Return command processor starting address
  721.      Entry:    None
  722.      Exit:     HL = calculated or loaded CCP starting address
  723.      Affected: HL
  724.      Usage:    Return≤ áthσ startinτ addres≤ oµ thσ commanΣ áproì
  725. ááááááááááááááácesso≥ áfo≥ usσ iε calculatinτ addresse≤ oµ áentr∙ ì
  726. ááááááááááááááápoints¼ anΣ iε locatinτ ZCPR│ configuratioε bytes«  ì
  727. áááááááááááááááThi≤ ároutinσ áfirs⌠ attempt≤ t∩ álocatσ áthσ áCC╨ ì
  728. áááááááááááááááaddres≤ áfroφ aε extendeΣ environmen⌠ iµ ápresent¼ ì
  729. áááááááááááááááotherwisσ ái⌠ wil∞ calculatσ thσ startinτ áaddres≤ ì
  730. áááááááááááááááfroφ áthσ áBIO╙ warφ boo⌠ vecto≥ assuminτ áß á3.5╦ ì
  731. áááááááááááááááBDO╙ anΣ ß 2╦ CCP.
  732.  
  733.      Routine║   GETECP
  734.      Function║ Return address of extended command processor name
  735.      Entry:    None
  736.      Exit:     HL = address of ECP name
  737.      Affected: HL
  738.      Usage:    Locate≤ thσ namσ oµ thσ ZCP╥ versioε 3.│ o≥ álate≥ ì
  739. áááááááááááááááextendeΣ commanΣ processor«  Require≤ ZCP╥ 3.│ áo≥ ì
  740. ááááááááááááááálate≥ anΣ thσ commanΣ processo≥ mus⌠ no⌠ havσ beeε ì
  741. áááááááááááááááoverwritten.
  742. .paèINPUT/OUTPU╘ áPACKAG┼ (IOP⌐ CONCEPTS:é  Thi≤ se⌠ oµ routine≤ áproì
  743. vidσ áacces≤ t∩ thσ systeφ Input/Outpu⌠ Packagσ (IOP)« á Thσ ádeì
  744. vice≤ iε aε IO╨ arσ identifieΣ b∙ ß logica∞ I─ (referrinτ t∩ áthσ ì
  745. generiπ CON¼ RDR¼ PUN¼ anΣ LS╘ devices⌐ anΣ ß physica∞ I─ (referì
  746. rinτ át∩ thσ specifiπ devicσ unde≥ thσ generic)«  B∙ áconvention¼ ì
  747. routine≤ áiε thi≤ collectioε alway≤ pas≤ thσ logica∞ I─ iε thσ á┬ ì
  748. registe≥ áanΣ thσ physica∞ I─ iε thσ ├ register« á Thσ áfollowinτ ì
  749. tablσ show≤ thσ assignments:
  750.  
  751.       logical ID
  752.        (B reg)       device
  753.           0           CON:
  754.           1           RDR:
  755.           2           PUN:
  756.           3           LST:
  757.  
  758. Thσ IO╨ statu≤ table¼ containeΣ iε ever∙ IOP¼ return≤ informatioε ì
  759. oε áthσ physica∞ ID's«  I⌠ tell≤ ho≈ man∙ physica∞ device≤ á(PID⌐ ì
  760. arσ availablσ fo≥ eacΦ logica∞ ID¼ anΣ thσ curren⌠ assignmen⌠ á(░ ì
  761. t∩ PI─-1)«  Thi≤ tablσ i≤ structureΣ as:
  762.  
  763.          offset               number of current
  764.          bytes     device    devices  assignment
  765.           0-▒       CON║      Byte ░    Byte 1
  766.           2-3       RDR:      Byte 2    Byte 3
  767.           4-5       PUN:      Byte 4    Byte 5
  768.           6-7       LST:      Byte 6    Byte 7
  769.  
  770. Fo≥ áexample¼ iµ bytσ ░ (numbe≥ oµ physica∞ consoles⌐ i≤ 5¼ átheε ì
  771. bytσ á▒ (curren⌠ physica∞ consolσ assignment⌐ caε onl∙ bσ iε áthσ ì
  772. rangσ froφ ░ t∩ 4«  GETIO╙ return≤ thσ addres≤ oµ thi≤ table.
  773.  
  774. The routines in the IOP collection are:
  775.  
  776.      GETIONÅ¡-returε áß ástrinτ givinτ thσ namσ áoµ áthσ ádevicσ ì
  777. ááááááááááidentifieΣ b∙ ß logica∞ I─ anΣ ß physica∞ ID.
  778.      GETIOP -- return the address and size of the IOP.
  779.      GETIOS -- return a pointer to the IOP status table.
  780.      IOMATCHÅ¡-searche≤ áfo≥ ß physica∞ devicσ ánamσ áassociateΣ ì
  781. ááááááááááwitΦ ß particula≥ logica∞ ID.
  782.      PUTIOD -¡ select and IOP device by logical and physical ID.
  783.  
  784.      Routine║   GETION
  785.      Function║ Return address of name for specified device
  786.      Entry:    B = logical device ID (0..3)
  787.                C = physical ID
  788.      Exit:     HL = address of string naming the indicated device
  789.                A <> 0, zero flag clear (NZ) if no error
  790.                A = 0, zero flag set (Z) if no IOP or range error
  791.      Affected: AF¼ HL
  792.      Usage:    Return≤ áß ápointe≥ t∩ thσ strinτ ádescribinτ áthσ ì
  793. ááááááááááááááádevicσ áwhosσ álogica∞ I─ (░ t∩ á3¼ áwherσ áCON=0¼ ì
  794. áááááááááááááááRDR=1¼ áPUN=2¼ anΣ LST=3⌐ i≤ iε ┬ anΣ physica∞ áI─ ì
  795. ááááááááááááááái≤ iε C.
  796. è     Routine║   GETIOP
  797.      Function║ Return address and size of IOP buffer definition
  798.      Entry:    None
  799.      Exit:     HL = address of IOP buffer
  800.                ┴ á╜ ánumbe≥ oµ 12╕-bytσ block≤ áiε ábuffer¼ ázer∩ ì
  801. áááááááááááááááclea≥ (NZ)
  802.                A = 0, zero flag set (Z) if no buffer
  803.      Affected: AF¼ HL
  804.      Usage:    Return≤ detail≤ oε thσ IO╨ buffe≥ addres≤ anΣ sizσ ì
  805. áááááááááááááááfroφ áthσ Environmen⌠ Descriptor¼ bu⌠ i⌠ doe≤ áno⌠ ì
  806. ááááááááááááááása∙ áiµ áaε IO╨ i≤ resident«  T∩ áfinΣ áthi≤ áout¼ ì
  807. áááááááááááááááexaminσ áthσ áfirs⌠ bytσ oµ thσ áIO╨ ábuffer« á Iµ ì
  808. ááááááááááááááázero¼ theε n∩ IO╨ i≤ exists.
  809.      Example:
  810.                          EX╘       GETIOP         ; declare the routine
  811.                          ...                      ; ..preceeding code
  812.                          CALL      GETIOP         ; get IOP buff data from ENV
  813.                          J╥        Z,NOIO╨        ╗ ..jum≡ iµ n∩ IO╨ buffer
  814.                          LD        A,(HL)         ; else get first byte
  815.                          OR        A              ; is anything installed?
  816.                          JR        Z,LODIOP       ; ..jump to load if not there
  817.                          ...                      ; else continue, IOP present
  818.  
  819.      Routine║   GETIOS
  820.      Function║ Return pointer to I/O package status table
  821.      Entry:    None
  822.      Exit:     HL = address of IOP status table
  823.                A <> 0, zero flag clear (NZ) if OK
  824.                A = 0 zero set (Z) if no IOP loaded
  825.      Affected: AF¼ HL
  826.      Usage:    Return≤ ß pointe≥ t∩ thσ I/╧ packagσ statu≤ átablσ ì
  827. áááááááááááááááiε HL«  Thσ tablσ i≤ structureΣ as:
  828.                    offset               number of current
  829.                    bytes     device    devices  assignment
  830.                     0-1       CON║      Byte ░    Byte 1
  831.                     2-3       RDR:      Byte 2    Byte 3
  832.                     4-5       PUN:      Byte 4    Byte 5
  833.                     6-7       LST:      Byte 6    Byte 7
  834.  
  835.      Routine║   IOMATCH
  836.      Function║ Search for physical device name for logical ID
  837.      Entry:    HL = address of device name string
  838.                B = logical ID (CON=0, RDR=1, PUN=2, LST=3)
  839.      Exit:     C = physical ID
  840.                A <> 0, zero flag clear (NZ) if OK
  841.                A = 0, zero flag clear if not found or no IOP
  842.      Affected: AF¼ C
  843.      Usage:    Searche≤ fo≥ thσ namσ oµ ß physica∞ devicσ associì
  844. áááááááááááááááateΣ witΦ ß particula≥ logica∞ ID«  Thi≤ namσ i≤ ß ì
  845. áááááááááááááááNU╠-terminateΣ ástrinτ o≥ an∙ characte≥ les≤ áthaε ì
  846. áááááááááááááááo≥ áequa∞ át∩ ß space«  Thσ ánamσ ái≤ ácapitalizeΣ ì
  847. áááááááááááááááinternally« á Iµ found¼ ├ return≤ thσ physica∞ áI─ ì
  848. áááááááááááááááoµ thσ device.
  849. .paè     Example:
  850.                          EXT       IOMATCH        ; declare the routine
  851.                          ...                      ; ..preceeding code
  852.                          LD        HL,MYCON       ; point to name string
  853.                          LD        B,0            ; select CON device
  854.                          CALL      IOMATCH        ; search for the device
  855.                          JR        Z,ERROR        ; ..jump error if bad
  856.                          ...                      ; else C=physical ID of MYCON
  857.                MYCON:    DEFB      'CRT1',0       ; name of desired CON device
  858.  
  859.      Routine║   PUTIOD
  860.      Function║ Select the IOP device from specified logical ID
  861.      Entry:    B = logical ID (CON=0, RDR=1, PUN=2, LST=3)
  862.                C = physical ID
  863.      Exit:     A <> 0, zero flag clear (NZ) if OK
  864.                ┴ ╜ 0¼ zer∩ flaτ se⌠ (Z⌐ iµ n∩ IO╨ o≥ rangσ áerro≥ ì
  865. ááááááááááááááá(physica∞ o≥ logica∞ I─ numbe≥ invalid)
  866.      Affected: AF
  867.      Usage:    Select≤ áaε IO╨ devicσ froφ ß se⌠ oµ álogica∞ áanΣ ì
  868. áááááááááááááááphysica∞ áID's« á Logica∞ I─ number≤ áarσ áiε áthσ ì
  869. ááááááááááááááárangσ oµ ░ t∩ 3¼ wherσ CO╬ ╜ 0¼ RD╥ ╜ 1¼ PU╬ ╜ á2¼ ì
  870. áááááááááááááááanΣ LS╘ ╜ 3«  Seσ thσ introductor∙ IO╨ sectioε fo≥ ì
  871. ááááááááááááááámorσ details.
  872.  
  873. INPUT/OUTPU╘ PACKAGE (IOP⌐ RECORDING:
  874.  
  875.      Routines║  IORCON ¼  IORCOFF ¼  IORLON ¼  IORLOFF
  876.      Function║ Turε oε anΣ ofµ I/╧ recordinτ iε curren⌠ IOP
  877.      Entry:    HL = address of ZCPR3 FCB for recorded information
  878.      Exit:     A <> 0, zero flag clear (NZ) if OK
  879.                ┴ á╜ 0¼ zer∩ flaτ se⌠ (Z⌐ iµ n∩ IO╨ áo≥ árecordinτ ì
  880. áááááááááááááááno⌠ supporteΣ iε IOP
  881.      Affected: AF
  882.      Usage:    IORCO╬ áturn≤ oε consolσ recording¼ IORCOF╞ áturn≤ ì
  883. áááááááááááááááofµ áconsolσ recording¼ IORLO╬ turn≤ oε ális⌠ áreì
  884. ááááááááááááááácording¼ áIORLOF╞ turn≤ ofµ lis⌠ árecording« á Thσ ì
  885. áááááááááááááááFC┬ ápasseΣ t∩ thesσ routine≤ i≤ ß standarΣ áZCPR│ ì
  886. áááááááááááááááFCB¼ áwherσ offse⌠ ░ contain≤ thσ disδ anΣ áoffse⌠ ì
  887. ááááááááááááááá1│ ácontain≤ thσ use≥ data«  ┴ particula≥ IO╨ áma∙ ì
  888. áááááááááááááááo≥ áma∙ áno⌠ pa∙ attentioε t∩ áthi≤ áFC┬ ápointer¼ ì
  889. ááááááááááááááádependinτ oε implementation.
  890.  
  891. DRIVE/USER:
  892.  
  893.      Routine║   GETDUOK
  894.      Function║ Return the value of the DUOK flag
  895.      Entry:    None
  896.      Exit:     A <> 0, zero flag clear (NZ) if DU use OK
  897.                A = 0, zero flag set (Z) if DU use not allowed
  898.      Affected: AF
  899.      Usage:    Return≤ áthσ DUO╦ flaτ valuσ whicΦ tell≤ thσ áproì
  900. ááááááááááááááágraφ iµ i⌠ i≤ permissiblσ t∩ specif∙ thσ D╒ prefi° ì
  901. ááááááááááááááát∩ changσ disδ anΣ use≥ area«  ZCPR│ utilitie≤ caε ì
  902. áááááááááááááááalway≤ áspecif∙ ß DI╥ prefi° (nameΣ directory⌐ áiε ì
  903. áááááááááááááááidentifyinτ thσ disδ anΣ use≥ areß t∩ examine¼ bu⌠ ìèáááááááááááááááiε somσ "secureó application≤ i⌠ i≤ no⌠ ádesirablσ ì
  904. ááááááááááááááát∩ áallo≈ thσ use≥ t∩ emplo∙ thσ D╒ prefi° t∩ áacì
  905. áááááááááááááááces≤ áan∙ ádisδ o≥ use≥ area« á Thi≤ áflaτ á(DUOK⌐ ì
  906. ááááááááááááááátell≤ áthσ áutilit∙ iµ i⌠ i≤ O╦ fo≥ áthσ áuse≥ át∩ ì
  907. áááááááááááááááemplo∙ thσ D╒ prefix.
  908.  
  909.      Routine║   GETMDISK
  910.      Function║ Return the maximum allowable disk
  911.      Entry:    None
  912.      Exit:     A = maximum disk number (1=A..16=P)
  913.      Affected: AF
  914.      Usage:    Obtain≤ áinformatioε áfroφ thσ áZCPR│ áEnvironmen⌠ ì
  915. áááááááááááááááDescripto≥ whicΦ ma∙ bσ useΣ t∩ restric⌠ acces≤ t∩ ì
  916. ááááááááááááááácertaiε ápart≤ áoµ thσ system« á Fo≥ áinstance¼ áß ì
  917. ááááááááááááááá"norma∞ useró ma∙ bσ denieΣ acces≤ t∩ disk≤ ├ áanΣ ì
  918. áááááááááááááááD« á ┴ á"privelegeΣ áuseró wh∩ ha≤ áthσ ápowe≥ át∩ ì
  919. áááááááááááááááchangσ áthσ ZCPR│ EnvΘronmen⌠ Descripto≥ caε ágaiε ì
  920. áááááááááááááááacces≤ t∩ an∙ desireΣ disδ.
  921.  
  922.      Routine║   GETMUSER
  923.      Function║ Return the maximum allowable user area
  924.      Entry:    None
  925.      Exit:     A = maximum allowable user area (0..31)
  926.      Affected: AF
  927.      Usage:    Provide≤ áinformatioε froφ thσ áZCPR│ áEnvironmen⌠ ì
  928. áááááááááááááááDescripto≥ whicΦ ma∙ bσ useΣ t∩ restric⌠ acces≤ t∩ ì
  929. ááááááááááááááácertaiε ápart≤ áoµ thσ system« á Fo≥ áinstance¼ áß ì
  930. ááááááááááááááá"norma∞ áuseró áma∙ bσ denieΣ acces≤ t∩ áan∙ áuse≥ ì
  931. áááááááááááááááareß ábeyonΣ 10«  ┴ "privelegeΣ useró wh∩ ha≤ áthσ ì
  932. ááááááááááááááápowe≥ át∩ changσ thσ ZCPR│ Environmen⌠ áDescripto≥ ì
  933. ááááááááááááááácaε gaiε acces≤ t∩ an∙ desireΣ use≥ area.
  934.  
  935.      Routine║   PUTDUOK
  936.      Function║ Set the DUOK byte to specified value
  937.      Entry:    A = DUOK value (0=DU not OK, 0FFh = DU is OK)
  938.      Exit:     None
  939.      Affected: None
  940.      Usage:    Set≤ áthσ áDUO╦ bytσ froφ A«  Iµ ┴ ╜ á0¼ áDUO╦ ái≤ ì
  941. áááááááááááááááfalsσ anΣ D╒ forφ oµ filσ specificatioε i≤ no⌠ OK«  ì
  942. áááááááááááááááIµ A<>░ (0FFΦ i≤ preferred)¼ DUO╦ i≤ truσ anΣ filσ ì
  943. áááááááááááááááspecificatioε usinτ thσ D╒ forφ i≤ permitted.
  944.  
  945.      Routine║   PUTMDISK
  946.      Function║ Set the maximum allowable disk in the environment
  947.      Entry:    A = maximum allowable disk numbe≥ (1=A..16=P)
  948.      Exit:     None
  949.      Affected: None
  950.      Usage:    Set≤ thσ maximuφ allowablσ disδ iε thσ Environmen⌠ ì
  951. áááááááááááááááDescriptor« á ValiΣ disδ number≤ rangσ froφ ▒ áfo≥ ì
  952. ááááááááááááááádrivσ ┴ t∩ 1╢ fo≥ drivσ P.
  953. .paè     Routine║   PUTMUSER
  954.      Function║ Set the maximum allowable user number (0..31)
  955.      Entry:    A = maximum allowable user number (0..31)
  956.      Exit:     None
  957.      Affected: None
  958.      Usage:    Set≤ thσ maximuφ allowablσ use≥ areß iε thσ áEnviì
  959. áááááááááááááááronmen⌠ Descriptor«  ValiΣ use≥ number≤ rangσ froφ ì
  960. ááááááááááááááá░ througΦ 31.
  961.  
  962.      Routine║   HIGHUSER
  963.      Function: Returε flaτ showinτ suppor⌠ fo≥ user≤ highe≥ thaε 15
  964.      Entry:    None
  965.      Exit:     Zero clear (NZ) if users highe≥ than 15 supported
  966.                Zer∩ áse⌠ á(Z⌐ iµ n∩ ZCP╥ 3.│ o≥ n∩ áuser≤ áhighe≥ ì
  967. áááááááááááááááthaε 15
  968.                A = undefined
  969.      Affected: AF
  970.      Usage:    Return≤ áß áflaτ indicatinτ whethe≥ áuse≥ ánumber≤ ì
  971. ááááááááááááááágreate≥ thaε 1╡ arσ supported«  Thi≤ definitioε i≤ ì
  972. áááááááááááááááobtaineΣ áfroφ thσ ZCP╥ 3.│ o≥ late≥ commanΣ ápr∩ì
  973. ááááááááááááááácessor«  Require≤ ZCP╥ 3.│ o≥ highe≥ anΣ thσ ácomì
  974. ááááááááááááááámanΣ processo≥ mus⌠ no⌠ havσ beeε overwritten.
  975.  
  976.      Routine║   GCMDDU
  977.      Function║ Return drive and user number in external FCB
  978.      Entry:    None
  979.      Exit:     BC = DU; B=drive (0=A..15=P), C=user (0..31)
  980.      Affected: BC
  981.      Usage:    Return≤ thσ drivσ anΣ use≥ fo≥ thσ filσ áspecifieΣ ì
  982. áááááááááááááááiε áthσ externa∞ FCB«  I⌠ i≤ ofteε useΣ t∩ ádeterì
  983. áááááááááááááááminσ áwherσ áthσ filσ wa≤ actuall∙ áfounΣ á(shell¼ ì
  984. ááááááááááááááápath¼ áetc.⌐ áiε orde≥ t∩ loτ int∩ áo≥ ásavσ átha⌠ ì
  985. ááááááááááááááálocation« á Externa∞ FC┬ mus⌠ havσ beeε parseΣ áb∙ ì
  986. áááááááááááááááZCP╥ 3.│ o≥ later¼ whicΦ place≤ thσ use≥ numbe≥ iε ì
  987. áááááááááááááááFCB+1│ anΣ thσ drivσ iε FCB+14.
  988.  
  989. MESSAGES:
  990.  
  991.      Routine║   GETMSG
  992.      Function║ Return the address of the ZCPR3 message buffer
  993.      Entry:    None
  994.      Exit:     HL = address of the ZCPR3 message buffer
  995.                A <> 0, zero flag clear (NZ) if valid
  996.                A = 0, zero flag set (Z) if no buffer
  997.      Affected: AF,HL
  998.      Usage:    Iε áconjunctioε áwitΦ othe≥ messagσ ároutine≤ áfo≥ ì
  999. ááááááááááááááásynchronizatioε ábetweeε programs¼ anΣ statu≤ áinì
  1000. áááááááááááááááformation« á Seσ áZ3LI┬ áinformatioε ásection≤ áoε ì
  1001. áááááááááááááááZCPR│ Messages.
  1002. .paè     Routine║   GETSHM
  1003.      Function: Ge⌠ ávaluσ oµ shel∞ messagσ fo≥ specifieΣ ámessagσ ì
  1004. ááááááááááááááánumber
  1005.      Entry:    B = message number (0, 1, 2)
  1006.      Exit:     A = message value (zero flag set accordingly)
  1007.      Affected: AF
  1008.      Usage:    Return≤ thσ valuσ oµ thσ shel∞ messagσ whosσ ánumì
  1009. ááááááááááááááábe≥ i≤ specified«  Therσ arσ threσ shel∞ messages¼ ì
  1010. ááááááááááááááás∩ ░ <╜ ┬ <╜ ▓ (yo⌡ mus⌠ bσ surσ ß valiΣ valuσ ái≤ ì
  1011. ááááááááááááááápresented).
  1012.  
  1013.      Routine║   PUTSHM
  1014.      Function║ Set the value of specified shell message number
  1015.      Entry:    A = message value
  1016.                B = message number (0,1,2)
  1017.      Exit:     None
  1018.      Affected: None
  1019.      Usage:    Place≤ áß ámessagσ int∩ onσ oµ thσ áthreσ ámessagσ ì
  1020. áááááááááááááááposition≤ iε thσ shel∞ area.
  1021.  
  1022. NAMED DIRECTORIES:
  1023.  
  1024.      Routine║   ADDNDR
  1025.      Function║ Add directory name to the named directory buffer
  1026.      Entry:    ┴ ╜ passworΣ flaτ (0=se⌠ t∩ spaces¼ noε-0=se⌠ froφ ì
  1027. áááááááááááááááDE)
  1028.                D┼ ╜ addres≤ oµ passworΣ buffe≥ iµ A<>░ (╕-characì
  1029. áááááááááááááááters)
  1030.                HL = address of FCB containing DU and disk name
  1031.      Exit:     ┴ á<╛ 0¼ zer∩ flaτ clea≥ (NZ⌐ iµ namσ áaddeΣ ásucì
  1032. ááááááááááááááácessfully
  1033.                A = 0, zero set (Z) if no buffer, or buffer full
  1034.      Affected: AF
  1035.      Usage:    Add≤ ß director∙ namσ t∩ thσ nameΣ director∙ (NDR⌐ ì
  1036. ááááááááááááááábuffe≥ defineΣ iε thσ Environmen⌠ Descriptor«  Thσ ì
  1037. áááááááááááááááname¼ áalonτ áwitΦ ádisδ anΣ áuse≥ álocation≤ áarσ ì
  1038. ááááááááááááááápasseΣ áiε áZCPR│ FC┬ forφ wherσ thσ ádisδ ái≤ áa⌠ ì
  1039. áááááááááááááááoffse⌠ á░ (A=1,..P=16)¼ anΣ thσ use≥ numbe≥ i≤ áa⌠ ì
  1040. áááááááááááááááoffse⌠ á1│ (0..31)«  Thσ director∙ namσ i≤ iε áthσ ì
  1041. áááááááááááááááFε áfielΣ oµ thσ FCB«  Aε optiona∞ passworΣ oµ áu≡ ì
  1042. ááááááááááááááát∩ eigh⌠ character≤ (spacσ-filleΣ oε right⌐ ma∙ bσ ì
  1043. ááááááááááááááápasseΣ áa≤ ß strinτ iε thσ D┼ registe≥ ápair« á Oε ì
  1044. áááááááááááááááinput¼ áiµ A=░ theε thσ D┼ pointe≥ i≤ ignoreΣ áanΣ ì
  1045. áááááááááááááááthσ passworΣ i≤ se⌠ empt∙ (al∞ spaces).
  1046.  
  1047.                ADDND╥ capitalize≤ thσ disδ namσ anΣ password¼ anΣ ì
  1048. ááááááááááááááásort≤ thσ nameΣ director∙ buffe≥ b∙ D╒ afte≥ addiì
  1049. ááááááááááááááátion« á N∩ áchecδ i≤ madσ fo≥ duplicatσ áname≤ áo≥ ì
  1050. áááááááááááááááduplicatσ D╒ references.
  1051. .paè     Routine║   DIRNDR
  1052.      Function║ Find named directory buffer entry for specified name
  1053.      Entry:    HL = address of 8-character buffer with name to find
  1054.      Exit:     HL = address of NDR entry, if found
  1055.                BC = DU (disk in B, 1=A..16=P) if found
  1056.                A <> 0, zero flag clear (NZ) if name found
  1057.                A = 0, zero flag set (Z) if no NDR or not found
  1058.      Affected: AF¼ BC¼ HL
  1059.      Usage:    Recover≤ áthσ drivσ anΣ use≥ datß fo≥ ß áspecifieΣ ì
  1060. ááááááááááááááánamσ áfroφ thσ nameΣ director∙ buffer«  Thσ áentr∙ ì
  1061. ááááááááááááááánamσ i≤ automaticall∙ capitalized«  Iµ found¼ áthσ ì
  1062. ááááááááááááááádrivσ ái≤ returneΣ iε registe≥ ┬ (1=A..16=P)¼ áanΣ ì
  1063. áááááááááááááááthσ áuse≥ iε registe≥ ├ (0..31)«  Thσ H╠ áregiste≥ ì
  1064. ááááááááááááááápai≥ áwil∞ poin⌠ t∩ thσ ND╥ entr∙ whicΦ i≤ ástrucì
  1065. ááááááááááááááátureΣ arounΣ 1╕-bytσ entrie≤ as:
  1066.                          DEFB      ▒              ; disk (1=A..16=P)
  1067.                          DEFB      15             ; user (0 to 31)
  1068.                          DEFB      'ROOT    º     ; name, 8-chars, space filled
  1069.                          DEFB      'MYPASS  '     ; password, 8-char, space fill
  1070.  
  1071.      Routine║   DUNDR
  1072.      Function: FinΣ nameΣ director∙ entr∙ froφ drive/use≥ áspeciì
  1073. áááááááááááááááfication
  1074.      Entry:    BC = drive/user in DU to locate (disk 1=A..16=P)
  1075.      Exit:     HL = address of NDR entry if found
  1076.                A <> 0, zero flag clear (NZ⌐ if found
  1077.                A = 0, zero flag set if no NDR buffer or not found
  1078.      Affected: AF¼ HL
  1079.      Usage:    Locate≤ áß ánameΣ director∙ áfroφ áthσ ádrive/use≥ ì
  1080. áááááááááááááááspecificatioε áiε áD╒ forφ wherσ thσ drivσ ái≤ áiε ì
  1081. áááááááááááááááregiste≥ ┬ (drivσ 1=A..16=P⌐ anΣ use≥ i≤ iε regisì
  1082. áááááááááááááááte≥ á├ (0..31)«  Iµ found¼ thσ addres≤ oµ thσ á1╕-ì
  1083. ááááááááááááááábytσ ánameΣ ádirector∙ buffe≥ entr∙ ái≤ áreturned«  ì
  1084. áááááááááááááááEntrie≤ arσ structureΣ as:
  1085.                          DEF┬      ▓              ╗ disδ (1=A..16=P)
  1086.                          DEFB      0              ; user (0..31)
  1087.                          DEFB      'HELP    '     ; name, 8-char, space filled
  1088.                          DEFB      '        '     ; password, 8-char, space fill
  1089.  
  1090.      Routine║   GETNDR
  1091.      Function║ Returε ánameΣ ádirector∙ ábuffe≥ áparameter≤ áfroφ ì
  1092. áááááááááááááááenvironment
  1093.      Entry:    None
  1094.      Exit:     HL = address of NDR buffer
  1095.                A = buffer size in 128-byte blocks, zero clear (NZ)
  1096.                A = 0, zero set (Z⌐ if no NDR buffer
  1097.      Affected: AF¼ HL
  1098.      Usage:    Thi≤ ároutinσ return≤ thσ addres≤ anΣ sizσ oµ áthσ ì
  1099. ááááááááááááááánameΣ director∙ buffe≥ a≤ defineΣ iε thσ áEnvironì
  1100. ááááááááááááááámen⌠ Descriptor«  I⌠ doe≤ no⌠ indicatσ thσ ástatu≤ ì
  1101. áááááááááááááááoµ áan∙ áentrie≤ withiε it« á T∩ ádeterminσ áthis¼ ì
  1102. áááááááááááááááexaminσ áthσ firs⌠ bytσ iε thσ buffer« á Iµ ázero¼ ì
  1103. ááááááááááááááátheε n∩ ND╥ i≤ presen⌠ iε thσ buffer.
  1104. .paè     Example:
  1105.                          EX╘       GETNDR         ; declare the routine
  1106.                          ...                      ; ..preceeding code
  1107.                          CALL      GETNDR         ; get data from ENV
  1108.                          JR        Z,NONDRBF      ; ..jump if no NDR bufr exists
  1109.                          LD        A,(HL)         ; have an NDR. Is data there?
  1110.                          OR        A
  1111.                          JR        Z,LODNDR       ; ..jump if not and load some
  1112.  
  1113.      Routine║   SUBNDR
  1114.      Function: Removσ áspecifieΣ nameΣ director∙ entr∙ áfroφ áND╥ ì
  1115. ááááááááááááááábuffer
  1116.      Entry:    HL = address of 8-character buffer containing name
  1117.      Exit:     A <> 0, zero flag clear (NZ) if removal successful
  1118.                A = 0, zero flag set if no NDR or name not found
  1119.      Affected: AF
  1120.      Usage:    Remove≤ aε entr∙ specifieΣ b∙ namσ froφ thσ ánameΣ ì
  1121. ááááááááááááááádirector∙ buffer«  Thσ namσ mus⌠ bσ provideΣ a≤ áß ì
  1122. ááááááááááááááástrinτ oµ u≡ t∩ eigh⌠ characters¼ spacσ-filleΣ áoε ì
  1123. ááááááááááááááárigh⌠ iµ les≤ thaε eigh⌠ characters«  Thσ namσ ái≤ ì
  1124. ááááááááááááááácapitalizeΣ beforσ i⌠ i≤ checkeΣ agains⌠ ápossiblσ ì
  1125. áááááááááááááááentries« á Iµ located¼ thσ entr∙ i≤ áremoved¼ áanΣ ì
  1126. áááááááááááááááthσ remaininτ buffe≥ i≤ repacked.
  1127.  
  1128. PATH:
  1129.  
  1130.      Routine║   GETPATH
  1131.      Function: Returε addres≤ oµ thσ commanΣ searcΦ patΦ froφ thσ ì
  1132. áááááááááááááááenvironment
  1133.      Entry:    None
  1134.      Exit:     H╠ ╜ addres≤ oµ ZCPR│ searcΦ patΦ froφ Environmen⌠ ì
  1135. áááááááááááááááDescriptor
  1136.                A = number of elements, zero flag clear (NZ) if OK
  1137.                A = 0, zero set (Z) if no path defined in ENV
  1138.      Affected: AF¼ HL
  1139.      Usage:    Returε áthσ áaddres≤ oµ thσ ZCPR│ ácommanΣ ásearcΦ ì
  1140. ááááááááááááááápatΦ a≤ defineΣ iε thσ Environmen⌠ Descriptor«  Iµ ì
  1141. ááááááááááááááátherσ i≤ ß ZCPR│ path¼ i⌠ wil∞ bσ structureΣ a≤ áß ì
  1142. áááááááááááááááserie≤ oµ tw∩-bytσ patΦ element≤ structureΣ as:
  1143.                          DEF┬      ▒              ; disk #1 (current='$', A=1..P=16)
  1144.                          DEFB      15             ; user #1 (current='$', 0..31)
  1145.                          DEFB      '$'            ; disk #2
  1146.                          DEFB      0              ; user #2
  1147.                          DEFB      0              ; end-of-list is drive = 0
  1148.  
  1149. PROCESSOR SPEED:
  1150.  
  1151.      Routine║   GETSPEED
  1152.      Function║ Return processor speed in MHz from environment
  1153.      Entry:    None
  1154.      Exit:     A = processor speed in megahertz
  1155.      Affected: AF
  1156.      Usage:    Mos⌠ ofteε useΣ iε softwarσ timinτ loop≤ t∩ permi⌠ ì
  1157. áááááááááááááááß greate≥ amoun⌠ oµ portabilit∙ iε software« á Thσ ì
  1158. áááááááááááááááreturneΣ valuσ i≤ t∩ thσ neares⌠ megahertz¼ s∩ ▒ ╜ ìèááááááááááááááá▒ MHz¼ ┤ ╜ ┤ MHz¼ etc.
  1159.  
  1160.      Routine║   PUTSPEED
  1161.      Function: Se⌠ áprocesso≥ speeΣ iε environmen⌠ át∩ áspecifieΣ ì
  1162. ááááááááááááááávalue
  1163.      Entry:    A = processor speed in megahertz
  1164.      Exit:     None
  1165.      Affected: None
  1166.      Usage:    Set≤ áthσ processo≥ speeΣ a≤ defineΣ iε thσ áEnviì
  1167. áááááááááááááááronmen⌠ Descripto≥ t∩ thσ specifieΣ valuσ iε Megaì
  1168. áááááááááááááááHert· wherσ ▒ ╜ ▒ MHz¼ ┤ ╜ ┤ MHz¼ etc.
  1169.  
  1170. QUIE╘ FLAG:
  1171.  
  1172.      Routine║   GETQUIET
  1173.      Function║ Return value of quiet flag
  1174.      Entry:    None
  1175.      Exit:     A = value of quiet flag from environment
  1176.                Zer∩ flaτ se⌠ accordingly║ ░ (no⌠ quiet⌐ ╜ Z¼ 0FFΦ ì
  1177. ááááááááááááááá(quiet⌐ ╜ NZ
  1178.      Affected: AF
  1179.      Usage:    Ofteε áuseΣ áiε program≤ t∩ suppres≤ áunneedeΣ áo≥ ì
  1180. áááááááááááááááunwanteΣ ástatu≤ messages«  B∙ sensinτ áthσ áquie⌠ ì
  1181. áááááááááááááááflaτ anΣ usinτ conditiona∞ prin⌠ statements¼ ámorσ ì
  1182. ááááááááááááááápleasinτ áoperatioε ácaε result«  Thσ áquie⌠ áflaτ ì
  1183. ááááááááááááááávaluσ iε storeΣ iε thσ Environmen⌠ Descriptor.
  1184.  
  1185.      Routine║   PUTQUIET
  1186.      Function║ Set the value of the quiet flag
  1187.      Entry:    A = quiet flag value (0=not quiet, 0FFh=quiet)
  1188.      Exit:     None
  1189.      Affected: None
  1190.      Usage:    Set≤ thσ quie⌠ flaτ t∩ thσ specifieΣ value«  Whilσ ì
  1191. ááááááááááááááá0FFΦ i≤ preferreΣ t∩ indicatσ quie⌠ operation¼ an∙ ì
  1192. ááááááááááááááánoε-zer∩ valuσ wil∞ suffice.
  1193.  
  1194. RESIDEN╘ COMMAN─ PACKAG┼ (RCP⌐ ADDRESS:
  1195.  
  1196.      Routine║   GETRCP
  1197.      Function: Returε addres≤ anΣ sizσ oµ residen⌠ commanΣ ápackì
  1198. áááááááááááááááagσ (RCP⌐ defineΣ iε environment
  1199.      Entry:    None
  1200.      Exit:     HL = address of RCP buffer
  1201.                A = size of buffer in 12-byte blocks, zero clear (NZ)
  1202.                A = 0, zero flag set (Z) if no RCP defined
  1203.      Affected: AF¼ HL
  1204.      Usage:    Return≤ thσ residen⌠ commanΣ packagσ buffe≥ ádefiì
  1205. ááááááááááááááánition≤ ácontaineΣ iε thσ Environmen⌠ áDescriptor«  ì
  1206. áááááááááááááááYou≥ áprograφ ámus⌠ checδ fo≥ ß valiΣ ápackagσ áiµ ì
  1207. ááááááááááááááánecessar∙ b∙ examininτ thσ firs⌠ bytσ oµ thσ ábufì
  1208. áááááááááááááááfer.
  1209. .paè     Example:
  1210.                          EX╘       GETFCP         ; declare the routine
  1211.                          ...                      ; ..preceeding code
  1212.                          CALL      GETFCP         ; get ENV definitions
  1213.                          JR        Z,NOFCPBUF     ; ..jump if no RCP exists
  1214.                          LD        A,(HL)         ; check first byte of bufr
  1215.                          OR        A              ; anything there?
  1216.                          JR        Z,LODRCP       ; ..jump if not to load
  1217.                          ...                      ; else have an RCP in place
  1218.  
  1219. SHELL STACK:
  1220.  
  1221.      Routine║   GETSH1
  1222.      Function: Returε ádefineΣ shel∞ stacδ parameter≤ froφ áenviì
  1223. áááááááááááááááronment
  1224.      Entry:    None
  1225.      Exit:     HL = address of shell stack
  1226.                B = number of bytes in each shell stack entry
  1227.                A = number of possible entries, zero clear (NZ)
  1228.                A = 0, zero flag set (Z) if no shell stack
  1229.      Affected: AF¼ B¼ HL
  1230.      Usage:    Return≤ ádatß áoε thσ overal∞ shel∞ ástacδ ásysteφ ì
  1231. áááááááááááááááfroφ áthσ Environmen⌠ Descriptor«  Seσ SHPUS╚ áanΣ ì
  1232. áááááááááááááááSHPO╨ routine≤ fo≥ detail≤ oε othe≥ facilitie≤ fo≥ ì
  1233. ááááááááááááááádealinτ witΦ shel∞ stack≤ provideΣ b∙ Z3LIB.
  1234.  
  1235.      Routine║   GETSH2
  1236.      Function: Returε ádefineΣ shel∞ stacδ parameter≤ froφ áenviì
  1237. áááááááááááááááronment
  1238.      Entry:    None
  1239.      Exit:     HL = address of shell stack
  1240.                DE = number of bytes allowed in each stack entry
  1241.                B¼ A = number of allowed entries, zero clear (NZ)
  1242.                A = 0, zero set (Z) if no shell stack defined
  1243.      Affected: AF¼ B¼ DE¼ HL
  1244.      Usage:    Thi≤ ái≤ aε alternativσ routinσ t∩ árecove≥ áshel∞ ì
  1245. ááááááááááááááástacδ parameter≤ froφ thσ Environmen⌠ áDescriptor«  ì
  1246. áááááááááááááááFo≥ somσ uses¼ thi≤ forφ i≤ morσ easil∙ manipulatì
  1247. áááááááááááááááeΣ áthaε áGETSH▒ covereΣ above« á Seσ áSHPUS╚ áanΣ ì
  1248. áááááááááááááááSHPO╨ routine≤ fo≥ detail≤ oε othe≥ facilitie≤ fo≥ ì
  1249. ááááááááááááááádealinτ witΦ shel∞ stack≤ provideΣ b∙ Z3LIB.
  1250.  
  1251. WHEEL BYTE:
  1252.  
  1253.      Routine║   GETWHL
  1254.      Function║ Return the wheel byte value from the environment
  1255.      Entry:    None
  1256.      Exit:     A = wheel byte
  1257.                Flag≤ se⌠ accordingly║ ░ (no⌠ wheel⌐ ╜ Z¼ 0FFΦ (i≤ ì
  1258. áááááááááááááááwheel⌐ ╜ NZ
  1259.      Affected: AF
  1260.      Usage:    Restrict≤ user≤ froφ accessinτ part≤ oµ áprograms¼ ì
  1261. áááááááááááááááo≥ áaffectinτ prograφ flow«  Fo≥ example¼ yo⌡ áma∙ ì
  1262. áááááááááááááááno⌠ áwisΦ remotσ user≤ t∩ changσ thσ patΦ ádefiniì
  1263. ááááááááááááááátion« á B∙ assigninτ "n∩ wheeló statu≤ át∩ áremotσ ìèáááááááááááááááusers¼ áthσ áPAT╚ áutilit∙ wil∞ árefusσ át∩ áallo≈ ì
  1264. áááááááááááááááchanges¼ sincσ i⌠ sense≤ thσ privelege≤ witΦ áthi≤ ì
  1265. ááááááááááááááároutine«  Whilσ ß 0FFΦ valuσ i≤ listeΣ fo≥ ágrantì
  1266. áááááááááááááááinτ whee∞ priveleges¼ an∙ noε-zer∩ valuσ currentl∙ ì
  1267. ááááááááááááááásuffices.
  1268.  
  1269.      Routine║   PUTWHL
  1270.      Function║ Set the value of the wheel byte in the environment
  1271.      Entry:    A = wheel byte value to set (0=no wheel, 0FFh=wheel)
  1272.      Exit:     None
  1273.      Affected: None
  1274.      Usage:    Set≤ thσ whee∞ bytσ oε (0FFh⌐ o≥ ofµ (0)¼ áthereb∙ ì
  1275. ááááááááááááááágrantinτ o≥ denyinτ whee∞ privelege≤ t∩ áexecutinτ ì
  1276. áááááááááááááááprograms.
  1277.  
  1278. FLOW¼ ZEX¼ AN─ SUBMI╘ CONTROL:
  1279.  
  1280. FLO╫ áCONTROL:é  Al∞ commanΣ sequence≤ issueΣ unde≥ ZCPR│ ácaε ábσ ì
  1281. though⌠ t∩ executσ iε ß TRU┼ flo≈ contro∞ state«  Tha⌠ is¼ áwhenì
  1282. eve≥ ß commanΣ i≤ executeΣ unde≥ ZCPR3¼ thσ statσ oµ flo≈ contro∞ ì
  1283. i≤ TRUE«  Iµ thσ statσ oµ flo≈ contro∞ i≤ FALS┼ theε n∩ ácommand≤ ì
  1284. excep⌠ áflo≈ ácommand≤ wil∞ bσ executeΣ unti∞ thσ statσ áoµ áflo≈ ì
  1285. contro∞ become≤ TRUE.
  1286.  
  1287. Background║  Wheε ZCPR│ firs⌠ come≤ up¼ thσ statσ oµ flo≈ contro∞ ì
  1288. i≤ alway≤ TRUE«  An∙ commanΣ issueΣ wil∞ bσ executed«  Iµ ß áFlo≈ ì
  1289. CommanΣ áPackagσ i≤ installeΣ whicΦ support≤ thσ IF/ELSE/F╔ á(EnΣ ì
  1290. IF⌐ ácommands¼ theε thσ statσ oµ flo≈ contro∞ caε bσ ádynamicall∙ ì
  1291. changeΣ áb∙ use≥ commands¼ a≤ thσ followinτ termina∞ sessioε ái∞ì
  1292. lustrates:
  1293. 
  1294.      SCR>; any command will execute now
  1295.      SCR>era *.bak
  1296.      No Files
  1297.      SCR>dir
  1298.      MYFILE  .TXT  |  OBJECT  .BIN
  1299.      SCR>; we can set a flow control state to be false
  1300.      SCR>IF F
  1301.       IF F
  1302.      SCR>; no command will execute now
  1303.      SCR>dir
  1304.      SCR>else
  1305.       IF T
  1306.      SCR>dir
  1307.      MYFILE  .TXT  |  OBJECT  .BIN
  1308.      SCR>FI
  1309.       No IF
  1310.      SCR>
  1311. 
  1312. Hence¼ wheε an∙ commanΣ i≤ executed¼ beforσ thσ executioε actualì
  1313. l∙ ábegins¼ ZCPR│ wil∞ looδ t∩ seσ iµ thσ statσ oµ thσ flo≈ áconì
  1314. tro∞ ái≤ áTRUE«  SucΦ i≤ thσ casσ wheε wσ arσ no⌠ áwithiε áaε áI╞ ì
  1315. conditioε o≥ wheε wσ arσ withiε onσ o≥ morσ I╞ conditions¼ al∞ oµ ì
  1316. whicΦ arσ TRUE.
  1317. èZCPR│ áallow≤ yo⌡ t∩ bσ nesteΣ int∩ IF'≤ u≡ t∩ eigh⌠ á(8⌐ álevel≤ ì
  1318. deep«  Tha⌠ is¼ thσ structurσ oµ you≥ commanΣ sequence≤ caε átakσ ì
  1319. thσ followinτ forφ whicΦ caε bσ nesteΣ t∩ ╕ level≤ oµ IF's:
  1320. 
  1321.      <set of commands>
  1322.      IF T
  1323.           <set of commands>
  1324.           IF T
  1325.                <set of commands>
  1326.                IF T
  1327.                     <set of commands>
  1328.                FI
  1329.                <set of commands>
  1330.           ELSE
  1331.                <set of non-executed commands>
  1332.                IF T
  1333.                     <set of non-executed commands>
  1334.                FI
  1335.           FI
  1336.      ELSE
  1337.           <set of non-executed commands>
  1338.      FI
  1339. 
  1340. CommanΣ ástructure≤ likσ thosσ presenteΣ abovσ arσ áno≈ ápossiblσ ì
  1341. unde≥ ZCPR3«  Iε essence¼ ZCPR│ command≤ caε no≈ takσ thσ forφ oµ ì
  1342. ß programminτ languagσ iε thei≥ owε right.
  1343.  
  1344. Thσ áse⌠ oµ routine≤ availablσ iε thi≤ par⌠ oµ Z3LI┬ arσ useΣ át∩ ì
  1345. providσ áyo⌡ witΦ ß simplσ interfacσ t∩ contro∞ thσ flo≈ ácontro∞ ì
  1346. withiε (anΣ outside⌐ you≥ program«  Yo⌡ caε issuσ command≤ to:
  1347.    o Enter the next IF level in TRUE or FALSE condition
  1348.    o Toggle the state of the current IF level
  1349.    o Drop down to the previous IF level
  1350.    o Determine the current IF level number
  1351.    o Or multiples of the above
  1352.  
  1353.      Routine║   IFEND
  1354.      Function║ Drop to previous IF level
  1355.      Entry:    None
  1356.      Exit:     A <> 0, zero flag clear (NZ) if successful
  1357.                A = 0, zero flag set (Z) if no IF level
  1358.      Affected: AF
  1359.      Usage:    Terminate≤ áthσ curren⌠ I╞ leve∞ anΣ drop≤ t∩ áthσ ì
  1360. ááááááááááááááápreviou≤ I╞ level¼ iµ thσ prograφ i≤ withiε onσ o≥ ì
  1361. ááááááááááááááámorσ áIF's« á Fo≥ ß transien⌠ áprogram¼ átherσ ái≤ ì
  1362. áááááááááááááááeithe≥ án∩ I╞ level¼ o≥ therσ i≤ ß TRU┼ flo≈ áconì
  1363. ááááááááááááááátro∞ statσ (al∞ preceedinτ IF'≤ arσ TRUE).
  1364.  
  1365.      Routines║  IFT ¼  IFF
  1366.      Function║ Raisσ anΣ se⌠ I╞ level
  1367.      Entry:    None
  1368.      Exit:     A <> 0, zero flag clear (NZ) if IF level OK
  1369.                A = 0, zero set (Z) on IF level overflow
  1370.      Affected: AF
  1371.      Usage:    IF╘ áset≤ I╞ leve∞ t∩ TRUE¼ IF╞ set≤ I╞ áleve∞ át∩ ìèáááááááááááááááFALSE« á Thesσ routine≤ arσ useΣ t∩ se⌠ flo≈ áconì
  1372. ááááááááááááááátro∞ ástate≤ áanΣ raisσ thσ I╞ álevel« á Thσ áflo≈ ì
  1373. ááááááááááááááácontro∞ ástatσ caε suppor⌠ u≡ t∩ eigh⌠ (8⌐ álevel≤ ì
  1374. áááááááááááááááoµ IF's«  IF╘ anΣ IF╞ returε erro≥ code≤ fo≥ overì
  1375. áááááááááááááááflo≈ ácondition≤ whicΦ shoulΣ bσ senseΣ t∩ áinsurσ ì
  1376. áááááááááááááááthσ integrit∙ oµ thσ program.
  1377.  
  1378.      Routine║   IFTEST
  1379.      Function║ Determine the current IF level
  1380.      Entry:    None
  1381.      Exit:     A = number of current IF level
  1382.                Zero flag i≤ se⌠ accordingly
  1383.      Affected: AF
  1384.      Usage:    Determine≤ áthσ ácurren⌠ I╞ level« á Thσ áreturneΣ ì
  1385. áááááááááááááááleve∞ valuσ range≤ froφ ░ t∩ 8«  Iµ A=0¼ therσ ái≤ ì
  1386. ááááááááááááááán∩ ácurren⌠ IF«  Thσ zer∩ flaτ i≤ se⌠ áaccordingl∙ ì
  1387. ááááááááááááááát∩ allo≈ rapiΣ testing.
  1388.      Example:
  1389.                          EX╘       IFTEST         ; declare the routine
  1390.                          ...                      ; ..preceeding code
  1391.                          CALL      IFTEST         ; get current IF level
  1392.                          JR        Z,NOIF         ; ..jump if none
  1393.                          CP        8              ; is it at max level?
  1394.                          JR        Z,ATMAX        ; ..jump if at max IF level
  1395.                          ...                      ; else carry shows empty levels
  1396.  
  1397.      Routine║   IFELSE
  1398.      Function║ Toggle TRUE/FALSE state of current IF level
  1399.      Entry:    None
  1400.      Exit:     A <> 0, zero flag clear (NZ) if successful
  1401.                A = 0, zero flag set (Z) if no current IF
  1402.      Affected: AF
  1403.      Usage:    Toggle≤ thσ curren⌠ statσ oµ thσ curren⌠ I╞ level«  ì
  1404. áááááááááááááááIµ ácalleΣ aε eveε numbe≥ oµ times¼ thσ ástatσ ái≤ ì
  1405. áááááááááááááááeffectivel∙ unchanged.
  1406.  
  1407. ZE╪ áACCES╙ áAN─ CONTROL:é  Thσ ZE╪ commanΣ filσ áfacilit∙ á(unde≥ ì
  1408. ZCPR│ only⌐ caε bσ controlleΣ b∙ thi≤ se⌠ oµ Z3LI┬ routines«  ZE╪ ì
  1409. intercept≤ al∞ BIO╙ call≤ fo≥ input¼ and¼ wheε iε intercep⌠ mode¼ ì
  1410. i⌠ áprovide≤ inpu⌠ froφ tex⌠ containeΣ iε it≤ ámemor∙-baseΣ átex⌠ ì
  1411. buffe≥ rathe≥ thaε allowinτ thσ use≥ t∩ inpu⌠ character≤ froφ thσ ì
  1412. keyboard«  Thesσ routine≤ arσ useΣ t∩ quer∙ thσ statu≤ oµ ZE╪ anΣ ì
  1413. t∩ áinstruc⌠ ZE╪ t∩ continuσ interceptinτ character≤ o≥ át∩ ásto≡ ì
  1414. interceptinτ character≤ anΣ allo≈ use≥ input.
  1415.  
  1416. Thi≤ áse⌠ áoµ routine≤ provide≤ acces≤ t∩ áthσ áZE╪ ámemor∙-baseΣ ì
  1417. commanΣ filσ processo≥ anΣ it≤ environment«  Yo⌡ caε takσ contro∞ ì
  1418. oµ ZE╪ througΦ thesσ routines.
  1419.  
  1420. Summary of Routines:
  1421.  
  1422.      GETZEX -- get the ZEX control message
  1423.      GETZFC -- get the first character in ZEX buffer
  1424.      GETZNC -- get the next character to be returned
  1425.      GETZRUN -- get ZEX running flagè     HALTZEX -- terminate the ZEX processor
  1426.      PUTZEX -- set the ZEX control message
  1427.      PUTZNC -- set the next character to be returned
  1428.      PUTZRUN -- set ZEX running flag
  1429.      STOPZEX -- suspend ZEX execution
  1430.      STRTZEX -- resume ZEX execution from a STOPZEX
  1431.  
  1432. ZEX DATA:
  1433.  
  1434.      Routine║   GETZFC
  1435.      Function║ Return address of first character in ZEX buffer
  1436.      Entry:    None
  1437.      Exit:     HL = address of first character in ZEX script buffer
  1438.                A = character at that address
  1439.                Carry clear (NC) if data
  1440.                Carry flag set (C) if no text data in buffer
  1441.      Affected: AF¼ HL
  1442.      Usage:    UseΣ t∩ examinσ thσ scrip⌠ datß fo≥ ß runninτ áZE╪ ì
  1443. áááááááááááááááscrip⌠ sequence.
  1444.  
  1445.      Routine║   GETZNC
  1446.      Function║ Get next character ZEX will process
  1447.      Entry:    None
  1448.      Exit:     HL = address of next character in ZEX text buffer
  1449.                ┴ ╜ nex⌠ characte≥ t∩ bσ returned¼ carr∙ clea≥ áiµ ì
  1450. ááááááááááááááávalid¼ carr∙ flaτ se⌠ (C⌐ iµ n∩ tex⌠ datß remains
  1451.      Affected: AF¼ HL
  1452.      Usage:    Ma∙ ábσ áuseΣ t∩ effec⌠ change≤ t∩ ß árunninτ áZE╪ ì
  1453. áááááááááááááááprograφ b∙ examininτ thσ nex⌠ characte≥ tha⌠ áwil∞ ì
  1454. ááááááááááááááábσ returned.
  1455.  
  1456.      Routine║   GETZRUN
  1457.      Function║ Determine run status of ZEX from run message byte
  1458.      Entry:    None
  1459.      Exit:     A = run message
  1460.                Zero set accordingly (0=not running)
  1461.                Carry flag set (C) if no message available
  1462.      Affected: AF
  1463.      Usage:    Return≤ áthσ ZE╪ ruε messagσ bytσ anΣ áset≤ áflag≤ ì
  1464. áááááááááááááááindicatinτ statu≤ as║  zer∩ flaτ i≤ se⌠ (Z⌐ iµ ZE╪ ì
  1465. áááááááááááááááno⌠ runninτ o≥ clea≥ (NZ⌐ iµ i⌠ is╗ carr∙ flaτ ái≤ ì
  1466. áááááááááááááááse⌠ á(C⌐ iµ therσ i≤ n∩ messagσ o≥ clea≥ á(NC⌐ áiµ ì
  1467. ááááááááááááááátherσ is.
  1468.  
  1469.      Routine║   PUTZNC
  1470.      Function║ Set address of next ZEX character (GOTO)
  1471.      Entry:    HL = address of next character ZEX will return
  1472.      Exit:     Carry flag clear (NC) if operation successful
  1473.                Carry set (C) if ZEX buffers not available
  1474.      Affected: AF
  1475.      Usage:    Set≤ thσ addres≤ oµ thσ nex⌠ characte≥ whicΦ áwil∞ ì
  1476. ááááááááááááááábσ áreaΣ áb∙ ZEX«  Usinτ thi≤ routinσ áprovide≤ áß ì
  1477. áááááááááááááááGOT╧ functioε fo≥ ZE╪ control.
  1478. .paè     Routine║   PUTZRUN
  1479.      Function║ Set value of ZEX running message byte
  1480.      Entry:    A = value of ZEX running message byte
  1481.      Exit:     Carry flag set (C) if no message buffers
  1482.      Affected: AF
  1483.      Usage:    Set≤ áthσ ZE╪ runninτ messagσ bytσ t∩ ß áuse≥-supì
  1484. áááááááááááááááplie≤ ávalue« á It≤ purposσ i≤ át∩ áallo≈ árunninτ ì
  1485. áááááááááááááááprogram≤ át∩ ádisablσ o≥ suspenΣ áZE╪ áprocessing«  ì
  1486. áááááááááááááááSe⌠ t∩ zer∩ t∩ sto≡ ZE╪ processing.
  1487.  
  1488. ZEX STATUS AND CONTROL:
  1489.  
  1490.      Routine║   GETZEX
  1491.      Function║ Return ZEX control message byte
  1492.      Entry:    None
  1493.      Exit:     A = ZEX control message (0,1,2)
  1494.                Zero set accordingly
  1495.      Affected: AF
  1496.      Usage:    Allow≤ program≤ t∩ determinσ thσ curren⌠ statσ áoµ ì
  1497. áááááááááááááááZEX«  Thσ contro∞ messagσ bytσ caε havσ onσ oµ thσ ì
  1498. áááááááááááááááfollowinτ threσ values:
  1499.                      0 = Normal«  ZE╪ i≤ runninτ anΣ interceptinτ ì
  1500. áááááááááááááááááááááááááBIO╙ calls.
  1501.                      1 = ZCPR│ Prompt«  ZE╪ i≤ alloweΣ t∩ ruε anΣ ì
  1502. áááááááááááááááááááááááááintercep⌠ áBIO╙ ácalls¼ bu⌠ áZE╪ áthink≤ ì
  1503. ááááááááááááááááááááááááátha⌠ i⌠ i≤ providinτ inpu⌠ t∩ thσ áZCPR│ ì
  1504. ááááááááááááááááááááááááácommanΣ áprocesso≥ directl∙ (ZE╪ i≤ áno⌠ ì
  1505. áááááááááááááááááááááááááprovidinτ inpu⌠ t∩ an∙ program).
  1506.                      2 = ZE╪ Suspended«  ZE╪ i≤ no⌠ áinterceptinτ ì
  1507. áááááááááááááááááááááááááBIO╙ call≤ anΣ use≥ inpu⌠ i≤ allowed.
  1508.  
  1509.                ┴ á▒ codσ shoulΣ neve≥ bσ seeε b∙ ß prograφ ásincσ ì
  1510. ááááááááááááááái⌠ i≤ se⌠ b∙ ZCPR│ anΣ cleareΣ t∩ ░ afte≥ ZE╪ áha≤ ì
  1511. ááááááááááááááácompleteΣ thσ commanΣ linσ input«  An∙ ZE╪ contro∞ ì
  1512. ááááááááááááááámessagσ i≤ rese⌠ upoε executioε oµ ZCPR│ t∩ ░ wheε ì
  1513. áááááááááááááááZCPR│ ái≤ áentereΣ anΣ theε t∩ ▒ áwheε áthσ áZCPR│ ì
  1514. ááááááááááááááápromp⌠ áappear≤ á(ZCPR│ input)«  Wheε áZCPR│ ácomì
  1515. áááááááááááááááplete≤ áit≤ input¼ i⌠ reset≤ thσ ZE╪ contro∞ ámesì
  1516. ááááááááááááááásagσ t∩ 0.
  1517.  
  1518.      Routine║   PUTZEX
  1519.      Function║ Set ZEX control message byte (change ZEX state)
  1520.      Entry:    A = ZEX control message byte (0¼ 1¼ 2)
  1521.      Exit:     None
  1522.      Affected: None
  1523.      Usage:    Allow≤ ß prograφ t∩ se⌠ thσ statσ tha⌠ ZE╪ i≤ áin«  ì
  1524. áááááááááááááááThi≤ contro∞ messagσ bytσ mus⌠ onl∙ bσ se⌠ t∩ áonσ ì
  1525. áááááááááááááááoµ thesσ values:
  1526.                      0 = Normal«  ZE╪ i≤ runninτ anΣ interceptinτ ì
  1527. áááááááááááááááááááááááááBIO╙ calls.
  1528.                      1 = ZCPR│ Prompt«  ZE╪ i≤ alloweΣ t∩ ruε anΣ ì
  1529. áááááááááááááááááááááááááintercep⌠ BIO╙ call≤ bu⌠ ZE╪ think≤ tha⌠ ì
  1530. ááááááááááááááááááááááááái⌠ i≤ providinτ inpu⌠ t∩ thσ ZCPR│ ácomì
  1531. ááááááááááááááááááááááááámanΣ áprocesso≥ ádirectl∙ á(ZE╪ ái≤ áno⌠ ì
  1532. áááááááááááááááááááááááááprovidinτ inpu⌠ t∩ an∙ program).è                     2 = ZE╪ Suspended«  ZE╪ i≤ no⌠ áinterceptinτ ì
  1533. áááááááááááááááááááááááááBIO╙ call≤ anΣ use≥ inpu⌠ i≤ allowed.
  1534.  
  1535.                ┴ ▒ codσ ma∙ bσ se⌠ b∙ an∙ prograφ iµ i⌠ want≤ ZE╪ ì
  1536. ááááááááááááááát∩ á"thinkó tha⌠ i⌠ i≤ providinτ inpu⌠ át∩ áZCPR3«  ì
  1537. áááááááááááááááIµ áZE╪ wa≤ previousl∙ suspended¼ i⌠ áadvance≤ át∩ ì
  1538. áááááááááááááááthσ beginninτ oµ thσ nex⌠ linσ anΣ resume≤ wheε i⌠ ì
  1539. ááááááááááááááásee≤ thi≤ code«  An∙ ZE╪ contro∞ messagσ i≤ árese⌠ ì
  1540. áááááááááááááááupoε executioε oµ ZCPR│ t∩ ░ wheε ZCPR│ i≤ entereΣ ì
  1541. áááááááááááááááanΣ theε t∩ ▒ wheε thσ ZCPR│ promp⌠ appear≤ (ZCPR│ ì
  1542. áááááááááááááááinput)«  Wheε ZCPR│ complete≤ it≤ input¼ i⌠ reset≤ ì
  1543. áááááááááááááááthσ ZE╪ contro∞ messagσ t∩ 0.
  1544.  
  1545.      Routine║   HALTZEX
  1546.      Function║ Halt ZEX completely by setting ZEX end-of-file
  1547.      Entry:    None
  1548.      Exit:     A <> 0, zero flag clear (NZ) if ZEX is halted
  1549.                A = 0, zero flag set (Z) if ZEX i≤ not running
  1550.      Affected: AF
  1551.      Usage:    Terminate≤ áexecutioε áoµ ZE╪ ácompletely« á Othe≥ ì
  1552. ááááááááááááááároutine≤ providσ temporar∙ executioε contro∞ ásucΦ ì
  1553. áááááááááááááááa≤ áSTOPZE╪ (suspenΣ execution)¼ anΣ STRTZE╪ á(reì
  1554. ááááááááááááááásumσ execution)¼ bu⌠ HALTZE╪ cause≤ ZE╪ t∩ átermiì
  1555. ááááááááááááááánatσ itselµ completel∙ b∙ settinτ thσ nex⌠ characì
  1556. áááááááááááááááte≥ ZE╪ wil∞ proces≤ t∩ thσ terminatioε ácharacte≥ ì
  1557. áááááááááááááááoµ 0FFh.
  1558.  
  1559.      Routine║   STOPZEX
  1560.      Function║ Temporarily suspend ZEX script processing
  1561.      Entry:    None
  1562.      Exit:     None╗ ZEX control message byte is set to 2
  1563.      Affected: None
  1564.      Usage:    Temporaril∙ stop≤ ZE╪ froφ interceptinτ BIO╙ call≤ ì
  1565. áááááááááááááááanΣ allow≤ thσ use≥ t∩ inpu⌠ characters«  Thi≤ ái≤ ì
  1566. áááááááááááááááß shorthanΣ t∩ placinτ thσ ▓ contro∞ codσ int∩ thσ ì
  1567. áááááááááááááááZE╪ contro∞ messagσ byte.
  1568.  
  1569.      Routine║   STRTZEX
  1570.      Function║ Start processing from ZEX script
  1571.      Entry:    None
  1572.      Exit:     None
  1573.      Affected: None
  1574.      Usage:    Allow≤ áZE╪ t∩ intercep⌠ BIO╙ call≤ áanΣ áprevent≤ ì
  1575. áááááááááááááááuse≥ froφ inputtinτ characters«  Thi≤ i≤ ß áshortì
  1576. áááááááááááááááhanΣ át∩ placinτ thσ ░ contro∞ codσ int∩ áthσ áZE╪ ì
  1577. ááááááááááááááácontro∞ messagσ byte.
  1578.  
  1579. SUBMI╘ AN─ XSU┬ CONTROL:é  Iε enhancinτ thσ ZCPR│ commanΣ áprocesì
  1580. sor≤ anΣ defininτ thσ extendeΣ environment¼ provision≤ werσ áals∩ ì
  1581. madσ át∩ contro∞ prograφ flo≈ froφ SUBMI╘ anΣ XSU┬ áutilitie≤ áiε ì
  1582. thσ samσ manne≥ a≤ thσ memor∙-baseΣ ZE╪ processinτ covereΣ áelseì
  1583. where.
  1584.  
  1585. SUBMI╘ áprocessinτ i≤ determineΣ viß flag≤ anΣ othe≥ datß áwithiε ì
  1586. ZCP╥ áVersioε á3.│ anΣ later«  Routine≤ supportinτ áit≤ áfeature≤ ìèmus⌠ havσ acces≤ t∩ thσ commanΣ processor«  I⌠ i≤ you≥ áresponsiì
  1587. bilit∙ t∩ insurσ tha⌠ thσ processo≥ i≤ no⌠ overwritten.
  1588.  
  1589. Thσ ácombinatioε áoµ SUBMI╘ witΦ aε XSU┬-likσ áutilit∙ áforφ áthσ ì
  1590. basi≤ oµ ß disδ-baseΣ corollar∙ t∩ ZE╪ fo≥ use≤ wherσ ß largσ TP┴ ì
  1591. space¼ áo≥ áver∙ largσ script≤ mus⌠ bσ áprocessed« á "Hooksó áarσ ì
  1592. thereforσ provideΣ witΦ thesσ routine≤ t∩ enablσ sucΦ ß facility.
  1593.  
  1594. SUBMI╘ DAT┴ AN─ CONTROL:
  1595.  
  1596.      Routine║   SUBON
  1597.      Function║ Determine whether SUBMIT processing is enabled
  1598.      Entry:    None
  1599.      Exit:     Zero clear (NZ) if SUBMIT is enabled
  1600.                Zero set (Z) if no ZCPR 3.3 or SUBMIT disabled
  1601.                A = destroyed
  1602.      Affected: AF
  1603.      Usage:    Require≤ áZCP╥ 3.│ o≥ later« á Determine≤ áwhethe≥ ì
  1604. áááááááááááááááthσ áSUBMI╘ áfacilit∙ withiε ZCP╥ versioε á3.│ áo≥ ì
  1605. ááááááááááááááálate≥ i≤ enabled«  Aε erro≥ statu≤ i≤ returneΣ áiµ ì
  1606. áááááááááááááááSUBMI╘ ái≤ disabled¼ o≥ thσ commanΣ áprocesso≥ ái≤ ì
  1607. áááááááááááááááno⌠ ZCP╥ 3.│ o≥ later«  Thσ commanΣ processo≥ mus⌠ ì
  1608. áááááááááááááááno⌠ havσ beeε overwritten.
  1609.  
  1610.      Routine║   HALTSUB
  1611.      Function║ Terminate an executing SUBMIT job
  1612.      Entry:    None
  1613.      Exit:     None; the $$$.SUB filσ is deleted
  1614.      Affected: None
  1615.      Usage:    Stop≤ áaε áexecutinτ SUBMI╘ joΓ áb∙ ádeletinτ áthσ ì
  1616. ááááááááááááááá$$$.SU┬ filσ addresseΣ iε thσ ZCP╥ 3.│ submi⌠ FCB.
  1617.  
  1618.      Routine║   GETSRUN
  1619.      Function║ Return flag indicating SUBMIT job status
  1620.      Entry:    None
  1621.      Exit:     A <> 0, zero clear (NZ) if SUBMIT job is running
  1622.                A = 0, zero set (Z) if SUBMIT is not running
  1623.      Affected: AF
  1624.      Usage:    Determine≤ whethe≥ wσ arσ currentl∙ runninτ withiε ì
  1625. áááááááááááááááß SUBMI╘ job«  Thi≤ i≤ sometime≤ necessar∙ áinforì
  1626. ááááááááááááááámatioε át∩ ádeterminσ possiblσ áaction≤ áwithiε áß ì
  1627. áááááááááááááááprogram.
  1628.  
  1629.      Routine║   GETSFCB
  1630.      Function║ Return the ZCPR 3.3 or later submit FCB address
  1631.      Entry:    None
  1632.      Exit:     DE = address of SUBMIT FCB (undefined if error)
  1633.                A <> 0, zero flag clear (NZ) if OK
  1634.                A = 0, zero set (Z) if no SUBMIT or ZCPR 3.3
  1635.      Affected: AF¼ DE
  1636.      Usage:    Require≤ ZCP╥ 3.│ o≥ later«  Thi≤ routinσ áreturn≤ ì
  1637. áááááááááááááááthσ áSUBMI╘ FC┬ addres≤ froφ ZCP╥ versioε á3.│ áo≥ ì
  1638. ááááááááááááááálate≥ FCB«  Aε erro≥ statu≤ i≤ returneΣ iµ áSUBMI╘ ì
  1639. ááááááááááááááái≤ no⌠ enableΣ o≥ thσ commanΣ processo≥ i≤ no⌠ áoµ ì
  1640. áááááááááááááááthσ árigh⌠ type«  Thσ commanΣ processo≥ ámus⌠ áno⌠ ìèáááááááááááááááhavσ beeε overwritten.
  1641.  
  1642. XSU┬ DAT┴ AN─ CONTROL:
  1643.  
  1644.      Routine║   STOPXSUB
  1645.      Function║ Reset XSUB input redirection flag
  1646.      Entry:    None
  1647.      Exit:     None; XSUB is halted
  1648.      Affected: None
  1649.      Usage:    Stop≤ áXSU┬ prograφ flo≈ fo≥ loca∞ consolσ áinput«  ì
  1650. áááááááááááááááThi≤ ái≤ accomplisheΣ b∙ resettinτ ß flaτ áiε áthσ ì
  1651. ááááááááááááááámessagσ buffer.
  1652.  
  1653.      Routine║   GXSUB
  1654.      Function║ Return the value of the XSUB redirection flag
  1655.      Entry:    None
  1656.      Exit:     A = value of the XSUB redirection flag
  1657.      Affected: AF
  1658.      Usage:    Determine≤ áiµ áinpu⌠ t∩ thσ árunninτ áprograφ ái≤ ì
  1659. ááááááááááááááácominτ áfroφ aε XSU┬ utility«  Thi≤ i≤ áusefu∞ áiε ì
  1660. áááááááááááááááerro≥ condition≤ wherσ thσ norma∞ flo≈ oµ command≤ ì
  1661. áááááááááááááááanΣ datß mus⌠ bσ altereΣ fo≥ operato≥ input.
  1662.  
  1663.      Routine║   PXSUB
  1664.      Function║ Set the XSUB input redirection flag
  1665.      Entry:    A = value to set XSUB input redirection flag
  1666.      Exit:     None; the value is set
  1667.      Affected: None
  1668.      Usage:    Activate≤ XSU┬ processinτ froφ ß commanΣ scrip⌠ o≥ ì
  1669. áááááááááááááááSU┬ áfile«  B∙ settinτ thσ XSU┬ redirectioε áflag¼ ì
  1670. áááááááááááááááprograφ flo≈ caε bσ dynamicall∙ altered«  Unti∞ áß ì
  1671. ááááááááááááááábette≥ ádefinitioε i≤ developed¼ i⌠ ái≤ ásuggesteΣ ì
  1672. ááááááááááááááátha⌠ áthσ ácommanΣ byte≤ useΣ fo≥ ZE╪ ábσ áapplieΣ ì
  1673. ááááááááááááááá(seσ GETZEX).
  1674.  
  1675. ZCPR│ áMESSAGES:é  ZCPR│ offer≤ man∙ feature≤ no⌠ founΣ áiε áCP/M¼ ì
  1676. ZCPR1¼ áo≥ áZCPR2«  Onσ ver∙ specia∞ featurσ i≤ tha⌠ áoµ ácommanΣ ì
  1677. processo≥ messages.
  1678.  
  1679. ZCPR│ ásupport≤ ß messagσ buffe≥ whicΦ contain≤ ß numbe≥ oµ ámesì
  1680. sage≤ áwhicΦ caε bσ passeΣ froφ onσ transien⌠ prograφ t∩ áanothe≥ ì
  1681. o≥ ábetweeε áZCPR│ itselµ anΣ al∞ transien⌠ áprogram≤ áwhicΦ áruε ì
  1682. unde≥ it«  Command≤ caε bσ giveε directl∙ t∩ ZCPR3¼ statu≤ inforì
  1683. matioε caε bσ passeΣ froφ ZCPR│ t∩ thσ transients¼ anΣ botΦ statì
  1684. u≤ áanΣ ácommand≤ ácaε bσ passeΣ froφ onσ átransien⌠ át∩ áanothe≥ ì
  1685. througΦ thesσ messages.
  1686.  
  1687. These message can be divided into six basic classes:
  1688.    o Messages which command ZCPR3
  1689.    o Status messages sent by ZCPR3
  1690.    o ZEX command messages
  1691.    o Statu≤ áanΣ commanΣ message≤ sen⌠ b∙ onσ prograφ t∩ áanothe≥ ì
  1692. áááááwhicΦ arσ ignoreΣ b∙ ZCPR3
  1693.    o User-defined messages
  1694.    o Reserved messagesè
  1695. Beforσ áusinτ an∙ Z3LI┬ routine≤ t∩ acces≤ thesσ ámessages¼ áyou≥ ì
  1696. prograφ shoulΣ ensurσ tha⌠ thσ messagσ buffe≥ i≤ availablσ t∩ it«  ì
  1697. Thi≤ ácaε easil∙ bσ donσ b∙ callinτ thσ GETMS╟ routinσ á(seσ áthσ ì
  1698. screeε oε thσ  ZCPR│ environment)«  GETMS╟ return≤ witΦ thσ ázer∩ ì
  1699. flaτ se⌠ (Z⌐ iµ n∩ ZCPR│ messagσ buffe≥ exists«  Hence:
  1700.                EX╘       GETMS╟              ; declare the routine
  1701.                ...
  1702.                CALL      GETMSG              ; get message buffer status
  1703.                JR        Z,NOZ3MSGS          ; ..jump if no msgs to read
  1704.                ...
  1705.  
  1706. Thσ áfollowinτ summarize≤ facilitie≤ availablσ througΦ thσ áZCPR│ ì
  1707. messagσ buffer.
  1708.  
  1709. Message≤ whicΦ CommanΣ ZCPR3:é  Somσ oµ thσ message≤ iε thσ áZCPR│ ì
  1710. messagσ ábuffe≥ arσ se⌠ b∙ externa∞ program≤ (transient≤ o≥ ácomì
  1711. manΣ ápackages⌐ áanΣ arσ reaΣ anΣ interpreteΣ áb∙ áZCPR3« á Thesσ ì
  1712. message≤ are:
  1713.    o Curren⌠ I╞ leve∞ anΣ activσ (T/F⌐ statu≤ oµ al∞ I╞ levels
  1714.    o Whethe≥ áaε erro≥ handle≥ i≤ availablσ anΣ wha⌠ thσ ácommanΣ ì
  1715. ááááálinσ t∩ invokσ i⌠ is
  1716.  
  1717. Statu≤ Message≤ Sen⌠ b∙ ZCPR3:é  Somσ oµ thσ message≤ iε thσ ZCPR│ ì
  1718. messagσ ábuffe≥ áarσ se⌠ onl∙ b∙ ZCPR│ o≥ ß ZCPR│ shel∞ áanΣ áarσ ì
  1719. intendeΣ át∩ bσ useΣ a≤ R/╧ message≤ b∙ transients« á Thesσ ámesì
  1720. sage≤ are:
  1721.    o ZCPR│ commanΣ statu≤ ¡¡ thσ transien⌠ loadeΣ i≤ o≥ i≤ no⌠ áß ì
  1722. áááááshell¼ anΣ thσ transien⌠ loadeΣ i≤ o≥ i≤ no⌠ aε erro≥ áhandì
  1723. áááááler
  1724.    o Erro≥ áaddres≤ ¡¡ iµ thσ transien⌠ loadeΣ i≤ aε erro≥ áhandì
  1725. áááááler¼ thi≤ i≤ thσ addres≤ oµ thσ firs⌠ characte≥ oµ thσ ácomì
  1726. ááááámanΣ linσ whicΦ wa≤ iε error
  1727.  
  1728. ZE╪ áCommanΣ Messages:é  Onσ messagσ iε thσ ZCPR│ messagσ ábuffer≤ ì
  1729. i≤ áintendeΣ át∩ directl∙ senΣ command≤ t∩ thσ áZE╪ ámemor∙-baseΣ ì
  1730. commanΣ áfilσ processor«  Thi≤ messagσ bytσ tell≤ ZE╪ threσ ádifì
  1731. feren⌠ things:
  1732.    o Ruε normall∙ ¡¡ ZE╪ i≤ t∩ intercep⌠ inpu⌠ call≤ anΣ áprovidσ ì
  1733. ááááácharacter≤ iε placσ oµ consolσ input
  1734.    o ZCPR│ i≤ promptinτ ¡¡ ZE╪ i≤ providinτ inpu⌠ directl∙ t∩ thσ ì
  1735. ááááácommanΣ processo≥ ZCPR3
  1736.    o SuspenΣ áintercep⌠ á¡¡ ZE╪ i≤ t∩ sto≡ áinterceptinτ áconsolσ ì
  1737. áááááinpu⌠ áanΣ allo≈ inpu⌠ froφ thσ consolσ unti∞ norma∞ áexecuì
  1738. ááááátioε o≥ thσ ZCPR│ promp⌠ appears
  1739.  
  1740. Message≤ IgnoreΣ b∙ ZCPR3:é  Tw∩ prσ-defineΣ message≤ arσ áignoreΣ ì
  1741. b∙ ZCPR3«  Thσ firs⌠ i≤ thσ prograφ erro≥ code«  Thi≤ bytσ caε bσ ì
  1742. se⌠ b∙ an∙ prograφ unde≥ ZCPR│ t∩ indicatσ ß returε statu≤ t∩ thσ ì
  1743. nex⌠ program«  Thσ conventioε ha≤ beeε adopteΣ tha⌠ iµ thi≤ ábytσ ì
  1744. i≤ á0¼ átheε thσ prograφ completeΣ successfully«  Iµ i⌠ ái≤ ánoε-ì
  1745. zero¼ áthσ prograφ faileΣ fo≥ somσ reasoε anΣ thσ valuσ áoµ áthi≤ ì
  1746. codσ indicate≤ tha⌠ reasoε t∩ ß followinτ program.
  1747.  
  1748. Thσ áseconΣ messagσ i≤ thσ registe≥ buffer«  Teε onσ-bytσ áregi≤ìèter≤ arσ availablσ anΣ caε bσ testeΣ b∙ thσ Flo≈ CommanΣ Package«  ì
  1749. Condition≤ álikσ "I╞ ░ 5ó (I╞ Registe≥ ░ ╜ 5⌐ caε bσ átesteΣ áanΣ ì
  1750. processeΣ áb∙ thσ Flo≈ Command Package¼ anΣ othe≥ transien⌠ ápr∩ì
  1751. gram≤ o≥ residen⌠ commanΣ package≤ caε manipulatσ thesσ áregiste≥ ì
  1752. values.
  1753.  
  1754. Use≥-DefineΣ áMessages:é  ┴ se⌠ oµ 1╢ message≤ arσ áavailablσ áfo≥ ì
  1755. use≥ ádefinition«  EacΦ messagσ i≤ onσ bytσ long¼ anΣ Z3LI┬ árouì
  1756. tine≤ arσ provideΣ t∩ placσ value≤ int∩ thesσ message≤ anΣ áquer∙ ì
  1757. them.
  1758.  
  1759. ReserveΣ Messages:é  ┴ se⌠ oµ 1╢ onσ-bytσ message≤ i≤ reserveΣ fo≥ ì
  1760. futurσ usσ iε thσ ZCPR│ systeφ anΣ shoulΣ no⌠ bσ useΣ b∙ applicaì
  1761. tion≤ áprogrammers«  Z3LI┬ doe≤ no⌠ providσ acces≤ t∩ thesσ ámesì
  1762. sages.
  1763.  
  1764. COMMAN─ STATU╙ MESSAGE:é  Thesσ message≤ returε thσ statu≤ oµ áthσ ì
  1765. curren⌠ átransien⌠ a≤ se⌠ b∙ ZCPR3«  An∙ transien⌠ ha≤ ábeeε áinì
  1766. vokeΣ iε onσ oµ threσ possiblσ states:
  1767.      1.A≤ ß "normaló transient¼ executeΣ a⌠ thσ reques⌠ oµ áthσ ì
  1768. use≥ o≥ anothe≥ program
  1769.      2.A≤ ß "shell"¼ invokeΣ b∙ ZCPR│ itself
  1770.      3.A≤ áaε "erro≥ handler"¼ invokeΣ b∙ ZCPR│ itselµ wheε ái⌠ ì
  1771. canno⌠ áproces≤ thσ curren⌠ commanΣ linσ (canno⌠ finΣ ß ámatchinτ ì
  1772. CO═ filσ o≥ CMDRU╬ facility)
  1773.  
  1774.      Routine║   GETCST
  1775.      Function║ Return the ZCPR3 command status message
  1776.      Entry:    None
  1777.      Exit:     A = message code (zero flag set accordingly)
  1778.      Affected: AF
  1779.      Usage:    Return≤ thσ ZCPR│ commanΣ statu≤ messagσ whicΦ ái≤ ì
  1780. áááááááááááááááalway≤ se⌠ b∙ ZCPR│ anΣ no⌠ intendeΣ t∩ bσ se⌠ áb∙ ì
  1781. áááááááááááááááan∙ program«  I⌠ caε havσ onσ oµ threσ values:
  1782.                     0 = this is a "normal" transient
  1783.                     1 = this is a "shell"
  1784.                     2 = this is an "error handler"
  1785.  
  1786.      Routine║   PUTCST
  1787.      Function║ Set the ZCPR3 command status message
  1788.      Entry:    A = ZCPR3 command status message value (0, 1, or 2)
  1789.      Exit:     None
  1790.      Affected: None
  1791.      Usage:    ProvideΣ t∩ allo≈ ß ZCPR│ shel∞ prograφ t∩ se⌠ thσ ì
  1792. áááááááááááááááZCPR│ ácommanΣ ástatu≤ messagσ byte« á I⌠ ái≤ áno⌠ ì
  1793. áááááááááááááááintendeΣ fo≥ genera∞ usσ b∙ applicatioε áprograms«  ì
  1794. áááááááááááááááAllowablσ ávalue≤ fo≥ thσ commanΣ ástatu≤ ámessagσ ì
  1795. áááááááááááááááare:
  1796.                     0 = this is a "normal" transient
  1797.                     1 = this is a "shell"
  1798.                     2 = this is an "error handler"
  1799. .paè     Routine║   QERROR
  1800.      Function║ Test command status message for error handler
  1801.      Entry:    None
  1802.      Exit:     A = message code
  1803.                Zer∩ áse⌠ á(Z⌐ iµ transien⌠ i≤ aε áerro≥ áhandler¼ ì
  1804. áááááááááááááááelsσ clea≥ (NZ)
  1805.      Affected: AF
  1806.      Usage:    UseΣ áa≤ ß quicδ tes⌠ t∩ seσ iµ thσ ZCPR│ ácommanΣ ì
  1807. ááááááááááááááástatu≤ messagσ indicate≤ tha⌠ thσ curren⌠ átransiì
  1808. áááááááááááááááen⌠ i≤ aε erro≥ handler«  Thσ ZCPR│ commanΣ statu≤ ì
  1809. ááááááááááááááámessagσ i≤ reaΣ anΣ testeΣ agains⌠ thσ erro≥ handì
  1810. ááááááááááááááále≥ codσ value«   Zer∩ flaτ i≤ se⌠ iµ thσ ácurren⌠ ì
  1811. ááááááááááááááátransien⌠ i≤ aε erro≥ handler.
  1812.  
  1813.      Routine║   QSHELL
  1814.      Function║ Test command status message for shell transient
  1815.      Entry:    None
  1816.      Exit:     A = message code
  1817.                Zero set (Z) if transient is shell
  1818.      Affected: AF
  1819.      Usage:    UseΣ áa≤ ß quicδ tes⌠ t∩ seσ iµ thσ ZCPR│ ácommanΣ ì
  1820. ááááááááááááááástatu≤ messagσ indicate≤ tha⌠ thσ curren⌠ átransiì
  1821. áááááááááááááááen⌠ i≤ ß shell«  Thσ ZCPR│ commanΣ statu≤ ámessagσ ì
  1822. ááááááááááááááái≤ áreaΣ anΣ testeΣ agains⌠ thσ shel∞ codσ ávalue«  ì
  1823. áááááááááááááááZer∩ áflaτ ái≤ se⌠ iµ thσ curren⌠ transien⌠ ái≤ áß ì
  1824. áááááááááááááááshell.
  1825.  
  1826. ERRO╥ FLA╟ AN─ ERRO╥ COMMAND:é  Thi≤ se⌠ oµ routine≤ perform≤ áthσ ì
  1827. followinτ functions:
  1828.      ERRADRÅ¡-return≤ thσ addres≤ oµ thσ firs⌠ characte≥ oµ áthσ ì
  1829. áááááááááácommanΣ linσ iε error
  1830.      GETER1 -- returns the error flag
  1831.      PUTER1 -- sets the error flag
  1832.      GETERCÅ¡-return≤ thσ addres≤ oµ thσ firs⌠ characte≥ oµ áthσ ì
  1833. ááááááááááerro≥ handle≥ commanΣ line
  1834.      PUTERC -- set the error handler command line
  1835.  
  1836.      Routine║   ERRADR
  1837.      Function: Oε erro≥ returε firs⌠ characte≥ oµ erroreΣ commanΣ ì
  1838. áááááááááááááááline
  1839.      Entry:    None
  1840.      Exit:     HL = address of first character of error line
  1841.      Affected: HL
  1842.      Usage:    Assuminτ átha⌠ thσ curren⌠ transien⌠ i≤ áaε áerro≥ ì
  1843. áááááááááááááááhandler¼ (cal∞ t∩ QERRO╥ returninτ witΦ zer∩ áflaτ ì
  1844. áááááááááááááááset)¼ áthi≤ ároutinσ return≤ thσ áaddres≤ áoµ áthσ ì
  1845. áááááááááááááááfirs⌠ ácharacte≥ oµ thσ commanΣ linσ whicΦ wa≤ áiε ì
  1846. áááááááááááááááerror«  Fo≥ example¼ iµ thσ command:
  1847.                     xxx params;dir
  1848.                i≤ áissueΣ áanΣ XXX.CO═ canno⌠ ábσ áfound¼ áERRAD╥ ì
  1849. áááááááááááááááreturn≤ áthσ addres≤ oµ thσ firs⌠ characte≥ á("X"⌐ ì
  1850. áááááááááááááááoµ thσ string:
  1851.                     DEF┬      'XXX PARAMS;DIR',0
  1852. .paè     Routine║   GETER1
  1853.      Function║ Return error flag
  1854.      Entry:    None
  1855.      Exit:     A <> 0, zero flag clear (NZ) if error present
  1856.                A = 0, zero set (Z) if no error
  1857.      Affected: AF
  1858.      Usage:    Return≤ áthσ áerro≥ flaτ iε A« á GETER▒ áha≤ ábeeε ì
  1859. áááááááááááááááredefineΣ froφ thσ origina∞ purposσ oµ determininτ ì
  1860. áááááááááááááááerro≥ áhandle≥ presencσ anΣ no≈ onl∙ áreturn≤ áthσ ì
  1861. ááááááááááááááávaluσ oµ thσ erro≥ flag.
  1862.  
  1863.      Routine║   PUTER1
  1864.      Function: Engagσ anΣ disengagσ erro≥ handle≥ flaτ [n∩ longe≥ ì
  1865. áááááááááááááááused]
  1866.      Entry:    None
  1867.      Exit:     None
  1868.      Affected: None
  1869.      Usage:    Thi≤ ároutinσ án∩ longe≥ perform≤ ß áfunctioε áanΣ ì
  1870. ááááááááááááááásimpl∙ return≤ t∩ thσ callinτ program.
  1871.  
  1872.      Routine║   GETERC
  1873.      Function║ Return address of string invoking error handler
  1874.      Entry:    None
  1875.      Exit:     HL = address of first character of string invoking error handler
  1876.                A <> 0, zero flag clear (NZ) if valid character
  1877.                A = 0 and zero flag set if string is empty
  1878.      Affected: AF¼ HL
  1879.      Usage:    Facilitate≤ erro≥ handle≥ constructioε b∙ áreturnì
  1880. áááááááááááááááinτ áthσ strinτ addres≤ anΣ firs⌠ ácharacter« á Iµ ì
  1881. áááááááááááááááthσ erro≥ handle≥ i≤ t∩ bσ invokeΣ b∙ thσ command:
  1882.                     error params
  1883.                theε GETER├ return≤ thσ addres≤ oµ thσ firs⌠ charì
  1884. áááááááááááááááacte≥ of:
  1885.                     DEF┬      'ERROR PARAMS',0
  1886.  
  1887.      Routine║   PUTERC
  1888.      Function║ Set the error handler command line
  1889.      Entry:    H╠ á╜ addres≤ oµ firs⌠ characte≥ oµ erro≥ áhandle≥ ì
  1890. ááááááááááááááácommanΣ line
  1891.      Exit:     A <> 0, zero flag clear (NZ) if OK
  1892.                ┴ ╜ 0¼ zer∩ flaτ se⌠ (Z⌐ iµ commanΣ linσ to∩ álonτ ì
  1893. ááááááááááááááá(morσ thaε 3▓ bytes)
  1894.      Affected: AF
  1895.      Usage:    Establishe≤ áß strinτ whicΦ i≤ t∩ bσ áthσ ácommanΣ ì
  1896. ááááááááááááááálinσ áexecuteΣ át∩ invokσ aε erro≥ áhandler« á Thσ ì
  1897. áááááááááááááááerro≥ ástring¼ includinτ thσ endinτ 0¼ mus⌠ bσ á3▓ ì
  1898. ááááááááááááááábyte≤ lonτ o≥ less.
  1899.      Example:
  1900.                          EX╘       PUTER├         ; declare the routine
  1901.                          ...                      ; ..preceeding code
  1902.                          LD        HL,ERSTR       ; address this string
  1903.                          CAL╠      PUTER├         ╗ se⌠ i⌠ a≤ handle≥ comnΣ line
  1904.                          JR        NZ,OK          ; ..jump if string accepted
  1905.                          ...                      ; else take other action
  1906.                ERSTR:    DEFB      'ERROR NOOPT',0è
  1907. INTE╥-TRANSIEN╘ ERRO╥ CODE:é  Thσ inte≥-transien⌠ erro≥ codσ i≤ áß ì
  1908. onσ-bytσ ámessagσ whicΦ an∙ prograφ caε se⌠ t∩ indicatσ it≤ ácomì
  1909. pletioε success«  Thσ conventioε i≤ tha⌠ iµ thi≤ messagσ bytσ ái≤ ì
  1910. se⌠ t∩ 0¼ theε thσ prograφ completeΣ successfully«  Iµ thi≤ ámesì
  1911. sagσ ábytσ i≤ no⌠ 0¼ theε thσ prograφ haΣ aε erro≥ anΣ thσ ávaluσ ì
  1912. oµ thi≤ messagσ bytσ indicate≤ thσ error.
  1913.  
  1914. GETER▓ áallow≤ áß prograφ t∩ determinσ thσ valuσ oµ áthi≤ áinte≥-ì
  1915. transien⌠ erro≥ codσ anΣ PUTER▓ allow≤ ß prograφ t∩ se⌠ thσ valuσ ì
  1916. oµ thσ inte≥-transien⌠ erro≥ code.
  1917.  
  1918.      Routine║   GETER2
  1919.      Function║ Return the value of inter-transient error code
  1920.      Entry:    None
  1921.      Exit:     A = error code, zero clear (NZ) if error
  1922.                A = 0, zero flag set (Z) if no error
  1923.      Affected: AF
  1924.      Usage:    Determine≤ iµ ß preceedinτ prograφ passeΣ aε erro≥ ì
  1925. ááááááááááááááát∩ thi≤ onσ iε thσ inte≥-transien⌠ erro≥ code.
  1926.  
  1927.      Routine║   PUTER2
  1928.      Function║ Set inter-transient error code
  1929.      Entry:    A = error code (0 for no error)
  1930.      Exit:     None
  1931.      Affected: None
  1932.      Usage:    Signal≤ áfollowinτ program≤ tha⌠ n∩ áerro≥ ástatu≤ ì
  1933. áááááááááááááááresulteΣ froφ thσ presentl∙-executinτ transient.
  1934.  
  1935. COMMAN─ ERRO╥ FLA╟ AN─ HANDLER:
  1936.  
  1937.      Routine║   GETER3
  1938.      Function║ Return the value of the command error flag
  1939.      Entry:    None
  1940.      Exit:     A <> 0, zero clear (NZ) if message exists
  1941.                A = 0, zero set (Z) if no message
  1942.      Affected: AF
  1943.      Usage:    Mos⌠ áofteε áuseΣ b∙ erro≥ áhandler≤ át∩ áidentif∙ ì
  1944. áááááááááááááááwhethe≥ o≥ no⌠ aε erro≥ occurred«  Iµ aε erro≥ ái≤ ì
  1945. ááááááááááááááádetecteΣ froφ thσ commanΣ erro≥ flag¼ thσ ámessagσ ì
  1946. ááááááááááááááábuffer≤ ma∙ bσ useΣ t∩ pas≤ additiona∞ informatioε ì
  1947. áááááááááááááááoε thσ causσ anΣ action.
  1948.  
  1949.      Routine║   PUTER3
  1950.      Function║ Set the command error flag
  1951.      Entry:    A = value to set command error flag
  1952.      Exit:     None; value is stored in command error flag
  1953.      Affected: None
  1954.      Usage:    Set≤ áthσ commanΣ erro≥ flaτ fo≥ possiblσ áinvocaì
  1955. ááááááááááááááátioε oµ aε erro≥ handler«  Additiona∞ áinformatioε ì
  1956. áááááááááááááááma∙ bσ passeΣ iε othe≥ messagσ buffers.
  1957.      Example:
  1958.                          EX╘       PUTER│         ; declare the routine
  1959.                          ...
  1960.                ISERR:    LD        A,0FFH         ; signal error occurranceè                         JR        ERRV           ; ..with command error flag
  1961.                NOERR:    XOR       A              ; enter here to set no errs
  1962.                ERRV:     CALL      PUTER3         ; ..set/clear comnd err flag
  1963.                          ...                      ; continue
  1964.  
  1965.      Routine║   INVERROR
  1966.      Function║ Invoke error handler
  1967.      Entry:    A = 0 for internal errors
  1968.                A <> 0 for external errors
  1969.                ┬ ╜ erro≥ codσ fo≥ externa∞ errors¼ undefineΣ áfo≥ ì
  1970. áááááááááááááááinterna∞ errors
  1971.      Exit:     A = ░ iµ erro≥ i≤ interna∞ t∩ ZCPR 3.3
  1972.                A <> ░ iµ erro≥ i≤ externa∞ t∩ ZCPR 3.3
  1973.      Affected: AF¼ DE¼ HL
  1974.      Usage:    Set≤ áal∞ parameter≤ fo≥ aε erro≥ handle≥ áinvocßì
  1975. ááááááááááááááátion«  I⌠ i≤ normall∙ useΣ jus⌠ prio≥ t∩ ß prograφ ì
  1976. áááááááááááááááabor⌠ t∩ eithe≥ thσ commanΣ processo≥ o≥ t∩ ß warφ ì
  1977. áááááááááááááááboot.
  1978.      Example:
  1979.                          EX╘       INVERRO╥       ; declare the routine
  1980.                          ...                      ; ..pgm flow w/detected error
  1981.                          LD        A,(ERRCODE)    ; get error code (if external)
  1982.                          LD        B,A            ; ..and put in correct register
  1983.                          LD        A,(ERRTYPE)    ; load the error type
  1984.                          CALL      INVERROR       ; call the routine
  1985.                          JP        NZ,0           ; ..jump warm boot if no ZCPR33
  1986.                          ...                      ; else return to command proc
  1987.  
  1988. COMMAN─ STATU╙ FLAG:
  1989.  
  1990.      Routine║   SETEPB
  1991.      Function║ Set external program bit in command status flag
  1992.      Entry:    None
  1993.      Exit:     None
  1994.      Affected: None
  1995.      Usage:    Set≤ thσ externa∞ prograφ bi⌠ iε thσ commanΣ statì
  1996. áááááááááááááááu≤ áflaτ t∩ signif∙ t∩ thσ ZCP╥ 3.│ o≥ late≥ ácomì
  1997. ááááááááááááááámanΣ processo≥ tha⌠ curren⌠ action≤ (sucΦ a≤ parsì
  1998. áááááááááááááááing⌐ i≤ beinτ requesteΣ b∙ aε externa∞ program.
  1999.  
  2000.      Routine║   RESEPB
  2001.      Function║ Reset external program bit in command status flag
  2002.      Entry:    None
  2003.      Exit:     None
  2004.      Affected: None
  2005.      Usage:    Reset≤ áthσ áexterna∞ prograφ bi⌠ iε áthσ ácommanΣ ì
  2006. ááááááááááááááástatu≤ áflaτ indicatinτ t∩ thσ ZCP╥ 3.│ áo≥ álate≥ ì
  2007. ááááááááááááááácommanΣ áprocesso≥ tha⌠ an∙ action≤ therσ arσ áinì
  2008. áááááááááááááááterna∞ anΣ no⌠ relateΣ t∩ aε externa∞ program.
  2009. .paè     Routine║   RETCST
  2010.      Function║ Return the address of the command status flag
  2011.      Entry:    None
  2012.      Exit:     HL = address of the command status flag
  2013.      Affected: HL
  2014.      Usage:    Return≤ áthσ addres≤ oµ thσ commanΣ ástatu≤ áflag«  ì
  2015. áááááááááááááááI⌠ ái≤ useΣ b∙ SETEPB¼ RESEPB¼ anΣ othe≥ áinterna∞ ì
  2016. ááááááááááááááámodules.
  2017.  
  2018. REGISTE╥ ACCESS:é  Thσ ZCPR│ messagσ buffe≥ provide≤ teε áonσ-bytσ ì
  2019. message≤ áwhicΦ arσ useΣ a≤ onσ-bytσ registers«  Thσ áGETRE╟ áanΣ ì
  2020. PUTRE╟ routine≤ allo≈ ß prograφ t∩ obtaiε anΣ se⌠ ß valuσ iε áan∙ ì
  2021. onσ oµ thσ teε registers.
  2022.  
  2023.      Routine║   GETREG
  2024.      Function║ Return contents of specified message buffer
  2025.      Entry:    B = number of register to access (0..9)
  2026.      Exit:     A = value of register, zero flag set accordingly
  2027.      Affected: AF
  2028.      Usage:    UseΣ át∩ obtaiε thσ content≤ oµ aε arbitrar∙ ámesì
  2029. ááááááááááááááásagσ ábuffer« á Thesσ ábuffer≤ áarσ ábytσ ávalues«  ì
  2030. áááááááááááááááGETRE╟ perform≤ n∩ validit∙ checδ oε thσ specifieΣ ì
  2031. áááááááááááááááregiste≥ number¼ merel∙ usinτ i⌠ a≤ aε inde° áint∩ ì
  2032. áááááááááááááááthσ ámessagσ buffe≥ array«  Yo⌡ mus⌠ áinsurσ átha⌠ ì
  2033. áááááááááááááááonl∙ value≤ iε thσ rangσ oµ 0..╣ arσ passed.
  2034.      Example:
  2035.                          EX╘       GETREG         ; declare the routine
  2036.                          ...                      ; ..preceeding code
  2037.                          LD        B,5            ; get the value of reg 5
  2038.                          CALL      GETREG         ; return reg 5 value byte
  2039.                          JR        Z,R5EQ0        ; ..jump to process if 0
  2040.                          ...                      ; else check more, etc
  2041.  
  2042.      Routine║   PUTREG
  2043.      Function: Se⌠ áß specifieΣ messagσ buffe≥ registe≥ t∩ ágiveε ì
  2044. ááááááááááááááávalue
  2045.      Entry:    B = register number to set (0 to 9)
  2046.                A = value to set in register (0 to 255)
  2047.      Exit:     None
  2048.      Affected: None
  2049.      Usage:    Set≤ áß áspecifieΣ messagσ buffe≥ áregiste≥ át∩ áß ì
  2050. ááááááááááááááágiveε valuσ whicΦ ma∙ bσ testeΣ b∙ othe≥ programs«  ì
  2051. áááááááááááááááN∩ checδ i≤ madσ t∩ ensurσ tha⌠ ┬ contain≤ ß valiΣ ì
  2052. áááááááááááááááregiste≥ number«  Yo⌡ mus⌠ insurσ tha⌠ iε contain≤ ì
  2053. áááááááááááááááonl∙ value≤ froφ ░ t∩ 9.
  2054.      Example:
  2055.                          EX╘       PUTREG         ; declare the routine
  2056.                          ...                      ; ..preceeding code
  2057.                          LD        B,9            ; set message register 9
  2058.                          LD        A,20           ; ..to 20
  2059.                          CALL      PUTREG         ; do it
  2060.                          ...                      ; ..and continue
  2061. .paèDEFAUL╘ DRIVE/USE╥ BUFFER:
  2062.  
  2063.      Routine║   GDEFDU
  2064.      Function║ Return current drive and user
  2065.      Entry:    None
  2066.      Exit:     BC = DU; B=drive (0=A..15=P), C = user number
  2067.      Affected: BC
  2068.      Usage:    Return≤ áthσ curren⌠ drivσ anΣ use≥ setting≤ áfroφ ì
  2069. áááááááááááááááthσ áZCP╥ á3.│ messagσ buffe≥ fo≥ usσ áb∙ áthσ áC─ ì
  2070. ááááááááááááááá(changσ directory⌐ routine¼ shells¼ o≥ wheε ß use≥ ì
  2071. ááááááááááááááánumbe≥ ágreate≥ áthaε 1╡ i≤ logged«  Thi≤ ái≤ áthσ ì
  2072. ááááááááááááááápreferreΣ ámethoΣ oµ logginτ int∩ higΦ use≥ áarea≤ ì
  2073. ááááááááááááááásincσ thσ CURDR╓ bytσ a⌠ locatioε ┤ onl∙ áaccommoì
  2074. ááááááááááááááádate≤ user≤ froφ ░ througΦ 15.
  2075.  
  2076.      Routine║   PDEFDU
  2077.      Function║ Make specified drive and user current
  2078.      Entry:    BC = DU; B=drive (0=A..15=P), C=user (0..31) to set
  2079.      Exit:     None; CURDR and CURUSR are set to specified values
  2080.      Affected: None
  2081.      Usage:    Store≤ specifieΣ drivσ anΣ use≥ value≤ int∩ áCURD╥ ì
  2082. áááááááááááááááanΣ CURUS╥ location≤ iε thσ ZCPR│ messagσ ábuffer¼ ì
  2083. áááááááááááááááthereb∙ makinτ theφ current«  I⌠ i≤ normall∙ áuseΣ ì
  2084. áááááááááááááááwheε drivσ anΣ use≥ arσ obtaineΣ froφ patΦ áspeciì
  2085. áááááááááááááááfication≤ t∩ signa∞ shell≤ o≥ erro≥ handler≤ wherσ ì
  2086. áááááááááááááááactivitie≤ occurred.
  2087.  
  2088. ZCPR│ UTILITIES:é  Thesσ utilitie≤ providσ ß numbe≥ oµ áconvenien⌠ ì
  2089. function≤ fo≥ ZCPR│ programmers«  Acces≤ t∩ directories¼ áconverì
  2090. sioε áfroφ tex⌠ strinτ name≤ t∩ director∙ referencσ values¼ ácomì
  2091. manΣ anΣ commanΣ linσ parsing¼ quie⌠ outpu⌠ routines¼ shel∞ stacδ ì
  2092. manipulation¼ dela∙ routines¼ anΣ othe≥ ZCPR│-specifiπ áfunction≤ ì
  2093. arσ provided.
  2094.  
  2095. NAME─ DIRECTORY-DRIVE/╒SER CONVERSION:
  2096.  
  2097.      Routine║   DIRTDU
  2098.      Function║ Convert specified DIR name to DU equivalent
  2099.      Entry:    HL = address of first character of DIR name
  2100.      Exit:     HL = points to delimiter at end of name
  2101.                BC = DU, B=disk (0=A..15=P), C=user (0..31)
  2102.                A <> 0, zero flag clear (NZ) if found
  2103.                A = 0, zero flag set (Z) if not found
  2104.      Affected: AF¼ BC¼ HL
  2105.      Usage:    Convert≤ áß DI╥ namσ consistinτ oµ ß strinτ oµ áu≡ ì
  2106. ááááááááááááááát∩ áeigh⌠ character≤ terminateΣ b∙ áan∙ ácharacte≥ ì
  2107. áááááááááááááááothe≥ thaε ß digi⌠ o≥ lette≥ t∩ it≤ D╒ áequivalen⌠ ì
  2108. áááááááááááááááfounΣ iε thσ nameΣ director∙ buffer.
  2109. .paè     Routine║   DUTDIR
  2110.      Function║ Convert specified DU to DIR equivalent
  2111.      Entry:    BC = DU, B=disk (0=A..15=P), C=user (0..31)
  2112.      Exit:     HL = pointer to 8-character name string
  2113.                A <> 0, zero flag clear (NZ) if found
  2114.                A = 0, zero flag set (Z) if not found
  2115.      Affected: AF¼ HL
  2116.      Usage:    Searche≤ thσ nameΣ director∙ fo≥ thσ specifieΣ DU«  ì
  2117. áááááááááááááááIµ áaε áentr∙ exist≤ fo≥ thσ correspondinτ áDU¼ áß ì
  2118. ááááááááááááááápointe≥ i≤ returneΣ t∩ thσ ╕-characte≥ namσ á(folì
  2119. áááááááááááááááloweΣ b∙ aε ╕-characte≥ password).
  2120.  
  2121. RESOLV┼ DIRECTOR┘ REFERENCES:
  2122.  
  2123.      Routine║   DNSCAN
  2124.      Function║ Resolve directory name using both DU and DIR
  2125.      Entry:    H╠ á╜ addres≤ oµ thσ firs⌠ characte≥ oµ ádirector∙ ì
  2126. áááááááááááááááname
  2127.                A = 0 (scan DU before DIR)
  2128.                A <> 0 (scan DIR before DU)
  2129.      Exit:     BC = DU, B=disk (0=A..15=P), C=user (0..31)
  2130.                A <> 0, zero flag clear (NZ) if found
  2131.                A = 0, zero flag set (Z) if not found
  2132.      Affected: AF¼ BC
  2133.      Usage:    Attempt≤ t∩ resolvσ ß candidatσ director∙ namσ áb∙ ì
  2134. ááááááááááááááácheckinτ ábotΦ áDI╥ anΣ D╒ áformat≤ áiε áspecifieΣ ì
  2135. áááááááááááááááorder« á Thσ ácandidatσ namσ ma∙ bσ áu≡ át∩ áeigh⌠ ì
  2136. ááááááááááááááácharacter≤ áterminateΣ áb∙ ß delimite≥ sucΦ áa≤ áß ì
  2137. áááááááááááááááspace¼ comma¼ period¼ dash¼ ß characte≥ les≤ áthaε ì
  2138. áááááááááááááááspace¼ etc«  Iµ found¼ thσ D╒ i≤ returneΣ iε BC.
  2139.  
  2140.      Routine║   DUSCAN
  2141.      Function║ Resolve addressed string in DU form
  2142.      Entry:    HL = address of string (up to 8 characters)
  2143.      Exit:     BC = DU, B=disk (0=A..15=P), C=user (0..31)
  2144.                A <> 0, zero flag clear (NZ) if valid DU form
  2145.                A = 0, zero flag set (Z) if not valid
  2146.      Affected: AF¼ BC
  2147.      Usage:    Resolve≤ thσ D╒ forφ oµ ß strinτ addresseΣ b∙ áHL«  ì
  2148. áááááááááááááááThσ áD╒ strinτ i≤ storeΣ iε ß buffe≥ u≡ át∩ áeigh⌠ ì
  2149. ááááááááááááááácharacter≤ long¼ anΣ i≤ terminateΣ b∙ ß delimiter¼ ì
  2150. áááááááááááááááwhicΦ ma∙ bσ ß characte≥ les≤ thaε ß space¼ áequa∞ ì
  2151. ááááááááááááááásigε á(=)¼ underscorσ (_)¼ perioΣ (.)¼ commß á(,)¼ ì
  2152. áááááááááááááááles≤ thaε (<)¼ o≥ greate≥ thaε (>).
  2153.  
  2154.      Routine║   DIRSCAN
  2155.      Function║ Resolve addressed strinτ in DIR form
  2156.      Entry:    HL = address of string (up to 8 characters)
  2157.      Exit:     BC = DU, B=disk (0=A..15=P), C=user (0..31)
  2158.                A <> 0, zero flag clear (NZ) if valid DU form
  2159.                A = 0, zero flag set (Z) if not valid
  2160.      Affected: AF¼ BC
  2161.      Usage:    Resolve≤ thσ DI╥ forφ oµ ß strinτ addresseΣ b∙ HL«  ì
  2162. áááááááááááááááThσ áD╒ strinτ i≤ storeΣ iε ß buffe≥ u≡ át∩ áeigh⌠ ì
  2163. ááááááááááááááácharacter≤ long¼ anΣ i≤ terminateΣ b∙ ß delimiter¼ ìèáááááááááááááááwhicΦ ma∙ bσ ß characte≥ les≤ thaε ß space¼ áequa∞ ì
  2164. ááááááááááááááásigε á(=)¼ underscorσ (_)¼ perioΣ (.)¼ commß á(,)¼ ì
  2165. áááááááááááááááles≤ thaε (<)¼ o≥ greate≥ thaε (>).
  2166.  
  2167. PARS┼ COMMAN─ LINE:
  2168.  
  2169.      Routine║   PARSER
  2170.      Function║ Parse complete command line
  2171.      Entry:    HL = address of command line
  2172.                A = 0 (scan DIR before DU)
  2173.                ┴ <╛ ░ (scan DU before DIR)
  2174.      Exit:     HL = address of next command (0 or leading ;)
  2175.                DE = address of FCB with command name (verb. COM)
  2176.                A = 0, zero flag set (Z) if OK
  2177.                ┴ á╜ numbe≥ oµ questioε marks¼ zer∩ clea≥ (NZ⌐ áiµ ì
  2178. áááááááááááááááverΓ contain≤ onσ o≥ morσ "?ó characters
  2179.      Affected: AF¼ DE¼ HL
  2180.      Usage:    Parse≤ áß completσ commanΣ u≡ t∩ aε endinτ NU╠ áo≥ ì
  2181. ááááááááááááááámultiplσ ácommanΣ linσ delimite≥ (usuall∙ ß ásemiì
  2182. ááááááááááááááácolon)« á I⌠ parse≤ anΣ initialize≤ áal∞ áelement≤ ì
  2183. ááááááááááááááápe≥ thσ ZCPR│ commanΣ convention≤ t∩ includσ áFCB▒ ì
  2184. áááááááááááááááa⌠ á005Ch¼ áFCB▓ a⌠ 006CΦ anΣ thσ ádefaul⌠ ábuffe≥ ì
  2185. ááááááááááááááá(TBUFF⌐ a⌠ 0080h«  Thσ commanΣ namσ i≤ returneΣ iε ì
  2186. áááááááááááááááaε FC┬ addresseΣ b∙ DE.
  2187.  
  2188. PAT╚ SEARC╚ FO╥ FILE:
  2189.  
  2190.      Routine║   PFIND
  2191.      Function║ Search for specified file along search path
  2192.      Entry:    DE = address of an FCB
  2193.                A <> 0 to search current directory
  2194.                ┴ = 0 if no current search
  2195.      Exit:     BC = DU, B=disk (0=A..15=P), C=user (0..31)
  2196.                A <> 0, zero flag clear (NZ) if found
  2197.                A = 0, zero flag set (Z) if not found
  2198.      Affected: AF¼ BC
  2199.      Usage:    Locate≤ ß filσ alonτ thσ ZCPR│ searcΦ path« á Wheε ì
  2200. ááááááááááááááálocated¼ áthσ ádisδ anΣ use≥ wherσ áthσ áfilσ áwa≤ ì
  2201. áááááááááááááááfounΣ arσ returned.
  2202.  
  2203. PROGRA═ LOADIN╟ (CHAINING):
  2204.  
  2205.      Routine║   PRGLOAD
  2206.      Function║ Load and execute specified program (chain)
  2207.      Entry:    DE = address oµ ß filσ contro∞ block
  2208.      Exit:     None
  2209.      Affected: Al∞ áregisters╗ iµ thi≤ routinσ returns¼ theε áthσ ì
  2210. áááááááááááááááloaΣ wa≤ ß failure.
  2211.      Usage:    Thi≤ routinσ i≤ ß "chainó functioε whicΦ load≤ thσ ì
  2212. áááááááááááááááprograφ indicateΣ b∙ thσ firs⌠ 1▓ byte≤ áaddresseΣ ì
  2213. áááááááááááááááb∙ D┼ int∩ memor∙ a⌠ 100Φ anΣ transfer≤ contro∞ t∩ ì
  2214. áááááááááááááááit« á Thσ áloade≥ anΣ FC┬ useΣ fo≥ áthσ áloaΣ áarσ ì
  2215. ááááááááááááááárelocateΣ át∩ ájus⌠ unde≥ áthσ ácommanΣ áprocesso≥ ì
  2216. áááááááááááááááafte≥ PRGLOA─ begin≤ execution¼ s∩ thσ TP┴ i≤ freσ ì
  2217. áááááááááááááááfo≥ thσ load«  Carσ shoulΣ bσ takeε t∩ ensurσ tha⌠ ìèáááááááááááááááthσ systeφ stacδ (locateΣ ou⌠ oµ thσ TP┴ iε ß safσ ì
  2218. áááááááááááááááarea⌐ i≤ useΣ insteaΣ oµ ß stacδ iε thσ TP┴ áwhicΦ ì
  2219. áááááááááááááááma∙ bσ overwritteε durinτ load.
  2220.  
  2221.                Iµ áPRGLOA─ áreturn≤ t∩ thσ ácallinτ áprogram¼ áaε ì
  2222. áááááááááááááááerro≥ iε loadinτ occurred«  Iµ al∞ goe≤ well¼ áthσ ì
  2223. áááááááááááááááloadeΣ prograφ execute≤ successfully.
  2224.  
  2225. CONSOL┼ QUIE╘ OUTPUT:é  Thesσ routine≤ outpu⌠ thei≥ value≤ onl∙ iµ ì
  2226. thσ quie⌠ flaτ i≤ clea≥ (0)«  Iµ thσ quie⌠ flaτ i≤ TRU┼ (no⌠ á0)¼ ì
  2227. theε n∩ value≤ arσ output.
  2228.  
  2229. This class of routines includes the following:
  2230.      QCOUT -¡ console character output with control
  2231.      QCRLF -¡ new line
  2232.      QOUT -¡ console character output
  2233.      QPRINT -- string output (return address)
  2234.      QPSTR -- string output (HL)
  2235.  
  2236.      Routine║   QCOUT
  2237.      Function║ Print character on console if not quiet
  2238.      Entry:    A = character to print
  2239.      Exit:     None
  2240.      Affected: None
  2241.      Usage:    Compariblσ t∩ thσ SYSLI┬ COU╘ routine¼ excep⌠ tha⌠ ì
  2242. ááááááááááááááái⌠ onl∙ print≤ iµ thσ quie⌠ flaτ i≤ off« á Contro∞ ì
  2243. ááááááááááááááácharacter≤ arσ printeΣ a≤ ß care⌠ (^⌐ followeΣ áb∙ ì
  2244. áááááááááááááááthσ characte≥ offse⌠ b∙ 40Φ (▒ output≤ a≤ ^A).
  2245.  
  2246.      Routine║   QCRLF
  2247.      Function║ Print a new line (CR/LF pair) if not quiet
  2248.      Entry:    None
  2249.      Exit:     Nonσ
  2250.      Affected: None
  2251.      Usage:    Correspond≤ t∩ thσ SYSLI┬ CRL╞ routinσ excep⌠ tha⌠ ì
  2252. áááááááááááááááiε ái≤ onl∙ sen⌠ t∩ thσ consolσ iµ thσ quie⌠ áflaτ ì
  2253. ááááááááááááááái≤ ofµ (0).
  2254.  
  2255.      Routine║   QOUT
  2256.      Function: Prin⌠ withou⌠ contro∞ characte≥ processinτ iµ áno⌠ ì
  2257. áááááááááááááááquiet
  2258.      Entry:    A = character to output
  2259.      Exit:     None
  2260.      Affected: None
  2261.      Usage:    Output≤ thσ characte≥ iε ┴ withou⌠ contro∞ characì
  2262. áááááááááááááááte≥ áprocessinτ á(▒ output≤ a≤ binar∙ á1⌐ áiµ áthσ ì
  2263. áááááááááááááááquie⌠ flaτ i≤ ofµ (0).
  2264.  
  2265.      Routine║   QPRINT
  2266.      Function║ Inline print of string if not quiet
  2267.      Entry:    None; string at return address
  2268.      Exit:     None
  2269.      Affected: None
  2270.      Usage:    Print≤ áß NU╠-terminateΣ strinτ whosσ áaddres≤ ái≤ ì
  2271. ááááááááááááááácontaineΣ áoε thσ stacδ to≡ iµ thσ quie⌠ áflaτ ái≤ ìèáááááááááááááááofµ (0)«  Executioε resume≤ a⌠ thσ bytσ áfollowinτ ì
  2272. áááááááááááááááthσ NU╠ afte≥ thσ strinτ i≤ printed.
  2273.  
  2274.      Routine║   QPSTR
  2275.      Function║ Print NUL-terminated string if not quiet
  2276.      Entry:    HL = address of first character of the string
  2277.      Exit:     None
  2278.      Affected: None
  2279.      Usage:    Samσ a≤ QPRIN╘ above¼ excep⌠ tha⌠ printinτ i≤ froφ ì
  2280. áááááááááááááááß registe≥ a≤ opposeΣ thσ inlinσ addres≤ froφ áthσ ì
  2281. ááááááááááááááástack.
  2282.  
  2283. LOCAT┼ ROO╘ DIRECTORY:
  2284.  
  2285.      Routine║   ROOT
  2286.      Function║ Return DU for the last directory in search path
  2287.      Entry:    None
  2288.      Exit:     BC = DU, B=disk (0=A..15=P), C=user (0..31)
  2289.      Affected: BC
  2290.      Usage:    Provide≤ ß convenien⌠ wa∙ t∩ finΣ thσ las⌠ ádirecì
  2291. ááááááááááááááátor∙ áiε ß patΦ expressioε (ROO╘ ádirectory)« á N∩ ì
  2292. ááááááááááááááápatΦ optimizatioε i≤ performed.
  2293.  
  2294.                Thi≤ routinσ i≤ sometime≤ no⌠ consisten⌠ witΦ áthσ ì
  2295. áááááááááááááááZCPR│ ácommanΣ processo≥ iµ thσ MINPAT╚ á(minimizσ ì
  2296. ááááááááááááááápatΦ áexpression⌐ áoptioε i≤ selected« á ROO╘ áadì
  2297. ááááááááááááááávance≤ át∩ áthσ las⌠ referenceΣ director∙ áiε áthσ ì
  2298. ááááááááááááááápatΦ áwithou⌠ minimization¼ whilσ ZCPR│ áminimize≤ ì
  2299. áááááááááááááááthσ ásearcΦ áanΣ ma∙ resolvσ ß patΦ t∩ áenΣ á(witΦ ì
  2300. áááááááááááááááduplication⌐ a⌠ ß director∙ othe≥ thaε thσ áphysiì
  2301. ááááááááááááááácall∙ las⌠ director∙ iε thσ path.
  2302.  
  2303. SHEL╠ STAC╦ ROUTINES:é  Thi≤ se⌠ oµ routine≤ support≤ shel∞ ástacδ ì
  2304. manipulation«  Thσ followinτ routine≤ arσ provided:
  2305.      SHEMPTY -- test to see if shell stack is empty
  2306.      SHFULL -- test to see if shell stack is full
  2307.      SHPOP -- pop top string off of shell stack
  2308.      SHPUSH -- push string onto shell stack
  2309.  
  2310. ┴ shel∞ stacδ i≤ implementeΣ a≤ ß serie≤ oµ string≤ á(recommendeΣ ì
  2311. sizσ ái≤ á3▓ byte≤ pe≥ string¼ anΣ thσ stacδ áshoulΣ ácontaiε áa⌠ ì
  2312. leas⌠ áfou≥ oµ thesσ strings)«  Thσ to≡ elemen⌠ oµ ß shel∞ ástacδ ì
  2313. specifie≤ thσ commanΣ linσ t∩ bσ executeΣ a≤ ß shel∞ b∙ thσ ZCPR│ ì
  2314. commanΣ processor«  Thi≤ commanΣ linσ i≤ copieΣ int∩ thσ multiplσ ì
  2315. commanΣ linσ buffe≥ fo≥ execution.
  2316.  
  2317.      Routine║   SHEMPTY
  2318.      Function║ Return status of shell stack
  2319.      Entry:    None
  2320.      Exit:     A <> 0, zero flag clear (NZ) if not empty
  2321.                A = 0, zero flag set (Z) if empty or none
  2322.      Affected: AF
  2323.      Usage:    Provide≤ áthσ ácurren⌠ statσ oµ thσ áshel∞ ástack«  ì
  2324. áááááááááááááááThσ zer∩ flaτ indicate≤ whethe≥ o≥ no⌠ shel∞ stacδ ì
  2325. áááááááááááááááspacσ i≤ available.è
  2326.      Routine║   SHFULL
  2327.      Function║ Determine if the shell stack is full
  2328.      Entry:    None
  2329.      Exit:     A <> 0, zero flag clear (NZ) if stack not full
  2330.                A = 0, zero set (Z) if stack full or none
  2331.      Affected: AF
  2332.      Usage:    Return≤ áß flaτ indicatinτ iµ thσ shel∞ ástacδ ái≤ ì
  2333. áááááááááááááááful∞ o≥ noε-existant.
  2334.  
  2335.      Routine║   SHPOP
  2336.      Function║ Pop top element from shell stack and discard
  2337.      Entry:    None
  2338.      Exit:     A = 0, zero flag set (Z) if OK
  2339.                A = error code, zero clear (NZ):
  2340.                     1 = no shell stack
  2341.                     2 = shell stack empty
  2342.                Affected: AF
  2343.      Usage:    Remove≤ áthσ to≡ elemen⌠ froφ thσ shel∞ stack¼ áiµ ì
  2344. ááááááááááááááápossible¼ anΣ discard≤ it«  Erro≥ code≤ repor⌠ áiµ ì
  2345. áááááááááááááááthσ áoperatioε wa≤ successful¼ o≥ thσ áreasoε áfo≥ ì
  2346. áááááááááááááááthσ error.
  2347.  
  2348.      Routine║   SHPUSH
  2349.      Function║ Push NUL-terminated string onto shell stack
  2350.      Entry:    H╠ ╜ addresse≤ NU╠-terminateΣ strinτ t∩ pusΦ áont∩ ì
  2351. ááááááááááááááástack
  2352.      Exit:     A = 0, zero flag set (Z) if successful
  2353.                A = return code¼ zer∩ clea≥ (NZ):
  2354.                     1 = no shell stack available
  2355.                     2 = shell stack is full
  2356.                     3 = string too long for entry
  2357.      Affected: AF
  2358.      Usage:    Perform≤ áneedeΣ function≤ t∩ pusΦ áNU╠-terminateΣ ì
  2359. ááááááááááááááástring≤ áont∩ áthσ shel∞ stack« á ReturneΣ ástatu≤ ì
  2360. áááááááááááááááshow≤ thσ result≤ oµ thσ action.
  2361.  
  2362. DELA┘ ROUTINES:é  Thσ followinτ routine≤ providσ ß softwarσ ádela∙ ì
  2363. baseΣ áupoε áthσ processo≥ speeΣ valuσ iε thσ áZCPR│ áEnvironmen⌠ ì
  2364. Descriptor«  Thesσ routine≤ simpl∙ dela∙ fo≥ thσ indicateΣ perioΣ ì
  2365. oµ átimσ (approximately⌐ anΣ theε return«  N∩ register≤ áarσ áafì
  2366. fected«  The routines are:
  2367.      WAIT1S -- delay for 1 second
  2368.      WAIT1MS -- delay for 0.001 second
  2369.      WAITP1S -- delay for 0.1 second
  2370.  
  2371.      Routine║   WAIT1S
  2372.      Function║ Wait for approximately one second
  2373.      Entry:    None
  2374.      Exit:     None
  2375.      Affected: None
  2376.      Usage:    Pause≤ áfo≥ approximatel∙ onσ seconΣ baseΣ oε áthσ ì
  2377. áááááááááááááááprocesso≥ áspeeΣ áiε thσ environmen⌠ anΣ áthσ áCP╒ ì
  2378. ááááááááááááááátype.
  2379. è     Routine║   WAIT1MS
  2380.      Function║ Wait for approximately one millisecond
  2381.      Entry:    None
  2382.      Exit:     None
  2383.      Affected: None
  2384.      Usage:    Pause≤ áfo≥ áapproximatel∙ onσ ámilliseconΣ á(.00▒ ì
  2385. ááááááááááááááásecond⌐ baseΣ oε thσ processo≥ speeΣ iε thσ áenviì
  2386. áááááááááááááááronmen⌠ anΣ thσ CP╒ type.
  2387.  
  2388.      Routine║   WAITP1S
  2389.      Function║ Wait for approximately one-tenth second
  2390.      Entry:    None
  2391.      Exit:     None
  2392.      Affected: None
  2393.      Usage:    Pause≤ áfo≥ áapproximatel∙ onσ-tentΦ oµ áß áseconΣ ì
  2394. ááááááááááááááábaseΣ oε thσ processo≥ speeΣ anΣ thσ CP╒ type.
  2395.  
  2396. LO╟ INT╧ ZCPR│ FIL┼ CONTRO╠ ┬LOCK DRIVE/USER:
  2397.  
  2398.      Routine║   Z3LOG
  2399.      Function: Loτ int∩ drive/use≥ containeΣ iε ß specifieΣ ZCPR│ ì
  2400. áááááááááááááááfilσ contro∞ block
  2401.      Entry:    D┼ á╜ addres≤ oµ firs⌠ bytσ oµ ZCPR│ filσ ácontro∞ ì
  2402. áááááááááááááááblock
  2403.      Exit:     None
  2404.      Affected: None
  2405.      Usage:    Log≤ int∩ thσ drivσ anΣ use≥ containeΣ iε ß speciì
  2406. áááááááááááááááfieΣ áZCPR│ filσ contro∞ block«  Thσ drivσ ái≤ áiε ì
  2407. ááááááááááááááábytσ ░ oµ thσ FC┬ (1=A..16=P⌐ anΣ thσ use≥ (0..31⌐ ì
  2408. ááááááááááááááái≤ áiε bytσ 13«  Thi≤ i≤ thσ standarΣ forma⌠ áuseΣ ì
  2409. áááááááááááááááb∙ áZCPR│ át∩ storσ ß completσ D╒ referencσ áiε áß ì
  2410. áááááááááááááááFCB.
  2411.  
  2412. RETUR╬ Z3LI┬ VERSION:
  2413.  
  2414.      Routine║   Z3LVER
  2415.      Function║ Return version number of Z3LIB.REL
  2416.      Entry:    None
  2417.      Exit:     HL = version number (H=major, L=minor) in binary
  2418.      Affected: HL
  2419.      Usage:    Record≤ thσ Z3LI┬ versioε iε linkeΣ programs¼ áfo≥ ì
  2420. ááááááááááááááádebugginτ witΦ differen⌠ versions.
  2421. .paèPARS┼ TOKEN:
  2422.  
  2423.      Routines║  ZPRSFN ¼  ZFNAME
  2424.      Function║ Parse filσ contro∞ blocδ token
  2425.      Entry:    HL = address of first character of token
  2426.                DE = address of 36-byte filσ contro∞ block
  2427.                A = flag:
  2428.                     0 = scan for DIR form before DU
  2429.                     1 = scan for DU form before DIR
  2430.      Exit:     HL = address of character after token
  2431.                A = number of question marks in filename.typ
  2432.                Zero flag set accordingly
  2433.      Affected: AF¼ HL
  2434.      Usage:    Perform≤ thσ identica∞ functioε oµ parsinτ ß ácomì
  2435. ááááááááááááááápletσ áFC┬ tokeε a≤ thσ ZCPR│ ácommanΣ áprocessor«  ì
  2436. áááááááááááááááToken≤ áma∙ takσ thσ forφ áoµ á"dir:filename.typ"¼ ì
  2437. ááááááááááááááá"du:filename.typ"¼ á"filename.typ"¼ etc«  Thσ áreì
  2438. ááááááááááááááásultinτ áFC┬ contain≤ thσ filenamσ anΣ typσ anΣ áß ì
  2439. áááááááááááááááprope≥ D╒ reference«  (Seσ PARSER¼ whicΦ i≤ relatì
  2440. áááááááááááááááed.)
  2441.  
  2442.                ZFNAM┼ ái≤ áß litera∞ interpretatioε oµ áthσ ácodσ ì
  2443. áááááááááááááááwithiε áthσ ZCPR│ commanΣ processor¼ whilσ áZPRSF╬ ì
  2444. ááááááááááááááái≤ áß ámorσ efficien⌠ bod∙ oµ codσ bu⌠ áuse≤ ámorσ ì
  2445. ááááááááááááááábuffe≥ space.
  2446.  
  2447. ZCP╥ 3.│ PARSERS:
  2448.  
  2449.      Routine║   Z33FNAME
  2450.      Function║ Parse single token from external command buffer
  2451.      Entry:    DE = address of user-defined FCB to receive token
  2452.      Exit:     HL = addres≤ oµ delimiter in command buffer
  2453.      Affected: HL
  2454.      Usage:    Require≤ ZCP╥ 3.│ o≥ later«  Thi≤ routinσ parse≤ ß ì
  2455. ááááááááááááááásinglσ tokeε froφ thσ externa∞ commanΣ buffe≥ t∩ ß ì
  2456. áááááááááááááááspecifieΣ FCB«  I⌠ use≤ thσ SCA╬ entr∙ iε ZCP╥ 3.│ ì
  2457. áááááááááááááááo≥ álater«  Yo⌡ mus⌠ insurσ tha⌠ thσ commanΣ áproì
  2458. ááááááááááááááácesso≥ ha≤ no⌠ beeε overwritteε t∩ usσ thi≤ áfuncì
  2459. ááááááááááááááátion.
  2460.  
  2461.      Routine║   PARSE2
  2462.      Function║ Parse command line using ZCPR 3.3 REPARSE entry
  2463.      Entry:    HL = address of the command line to reparse
  2464.      Exit:     None; line is reparsed and FCB's filled
  2465.      Affected: None
  2466.      Usage:    Require≤ ZCP╥ 3.│ o≥ later«  Thi≤ routinσ parse≤ ß ì
  2467. áááááááááááááááspecifieΣ commanΣ linσ t∩ thσ defaul⌠ FCB'≤ a⌠ 5CΦ ì
  2468. áááááááááááááááanΣ 6Ch«  Yo⌡ mus⌠ insurσ tha⌠ thσ commanΣ procesì
  2469. áááááááááááááááso≥ ha≤ no⌠ beeε overwritteε t∩ usσ thi≤ routine.
  2470. .paè     Routine║   REPARSE
  2471.      Function║ Reparse default command line one token later
  2472.      Entry:    None
  2473.      Exit:     None; the command line is reparsed
  2474.      Affected: None
  2475.      Usage:    Require≤ ZCP╥ 3.│ o≥ later«  Thi≤ routinσ reparse≤ ì
  2476. áááááááááááááááthσ curren⌠ commanΣ linσ startinτ onσ tokeε áafte≥ ì
  2477. ááááááááááááááácurren⌠ ásettinτ anΣ set≤ thσ defaul⌠ FCB's« á Yo⌡ ì
  2478. ááááááááááááááámus⌠ áinsurσ átha⌠ thσ commanΣ processo≥ áha≤ áno⌠ ì
  2479. ááááááááááááááábeeε overwritteε t∩ usσ thi≤ routine.
  2480.  
  2481.      Routine║   SCAN
  2482.      Function║ Scan single token from specified command line
  2483.      Entry:    HL = points to command line to scan
  2484.                DE = points to FCB to receive parsed token
  2485.      Exit:     None; token is parsed
  2486.      Affected: None
  2487.      Usage:    Require≤ ZCP╥ 3.│ o≥ later«  Thi≤ routinσ parse≤ ß ì
  2488. ááááááááááááááásinglσ átokeε froφ ß use≥-specifieΣ ácommanΣ álinσ ì
  2489. áááááááááááááááint∩ ß specifieΣ FC┬ usinτ thσ SCA╬ entr∙ iε áZCP╥ ì
  2490. ááááááááááááááá3.│ áo≥ later«  Yo⌡ mus⌠ insurσ tha⌠ áthσ ácommanΣ ì
  2491. áááááááááááááááprocesso≥ áha≤ áno⌠ beeε overwritteε t∩ áusσ áthi≤ ì
  2492. ááááááááááááááároutine.
  2493.  
  2494. CHEC╦ ZCP╥ 3.│ PARS┼ RESULTS:
  2495.  
  2496.      Routines║  FCB1CHK ¼  FCB2CHK
  2497.      Function║ Examinσ defaul⌠ filσ contro∞ block≤ fo≥ validity
  2498.      Entry:    None
  2499.      Exit:     A = 0, zero set (Z) if FCB has valid name
  2500.                A <> 0, zero clear (NZ) if error or no name
  2501.      Affected: AF
  2502.      Usage:    Require≤ áFC┬ parseΣ b∙ ZCP╥ 3.│ o≥ later« á Thesσ ì
  2503. ááááááááááááááároutine≤ áexaminσ thσ defaul⌠ FCB'≤ áa⌠ álocation≤ ì
  2504. ááááááááááááááá5CΦ (FCB1CHK⌐ anΣ 6CΦ (FCB2CHK⌐ fo≥ validl∙ parseΣ ì
  2505. áááááááááááááááfilename≤ froφ ZCP╥ 3.│ o≥ late≥ parsers« á Error≤ ì
  2506. áááááááááááááááarσ áduσ t∩ D╒ ou⌠ oµ range¼ illega∞ nameΣ ádirecì
  2507. ááááááááááááááátory¼ o≥ illega∞ password.
  2508.  
  2509.      Routine║   FCBCHK
  2510.      Function║ Examine specified filσ contro∞ block for validity
  2511.      Entry:    DE = address of an FCB to check
  2512.      Exit:     A = 0, zero set (Z) if FCB has valid name
  2513.                A <> 0, zero clear (NZ) if error or no name
  2514.      Affected: AF
  2515.      Usage:    Require≤ áFC┬ parseΣ b∙ ZCP╥ 3.│ o≥ álater« á Thi≤ ì
  2516. ááááááááááááááároutine≤ áexamine≤ thσ FC┬ a⌠ ß specifieΣ áaddres≤ ì
  2517. áááááááááááááááfo≥ ávalidl∙ parseΣ filenamσ b∙ ZCP╥ 3.│ o≥ álate≥ ì
  2518. áááááááááááááááparsers«  Error≤ arσ duσ t∩ D╒ ou⌠ oµ range¼ illeì
  2519. ááááááááááááááága∞ nameΣ directory¼ o≥ illega∞ password.
  2520. .paèPRIN╘ LOA─ MODUL┼ DATA:
  2521.  
  2522.      Routine║   PRTTYPE
  2523.      Function║ Print load module type and address
  2524.      Entry:    A = program type (1..4)
  2525.                HL = program load address
  2526.      Exit:     None; the type and address are printed on console
  2527.      Affected: None
  2528.      Usage:    Mos⌠ ofteε useΣ iε extendeΣ processor≤ anΣ áutiliì
  2529. ááááááááááááááátie≤ át∩ ádispla∙ loaΣ information«  I⌠ áprint≤ áß ì
  2530. ááááááááááááááámessagσ t∩ thσ CON║ devicσ containinτ loaΣ ámodulσ ì
  2531. ááááááááááááááátypσ (│ o≥ 4⌐ anΣ thσ loaΣ addres≤ iε hex.
  2532.      Example:
  2533.                          EX╘       PRTTYPE        ; declare the routine
  2534.                          ...
  2535.                          JP        BEGIN          ; ZCPR 3 header structure
  2536.                          DEFB      'Z3ENV'        ; .ID string
  2537.                TYPE:     DEFB      3              ; ..module load type
  2538.                Z3EADR:   DEFW      $-$            ; ...candidate ENV address
  2539.                START:    DEFW      9800H          ; type 3 starting addr = 9800h
  2540.                BEGIN:    ...                      ; initial setup, set stack, etc
  2541.                          LD        A,(TYPE)       ; get the load module type
  2542.                          LD        HL,START       ; ..and load starting address
  2543.                          CALL      PRTTYPE        ; print them to the console
  2544.                          ...                      ; ..continue on
  2545.  
  2546. ZCP╥ 3.│ INTERNA╠ PROGRA═ NAME:
  2547.  
  2548.      Routine║   GETNAME
  2549.      Function║ Return pointer to current program name
  2550.      Entry:    None
  2551.      Exit:     A <> 0, zero clear (NZ) if external FCB exists
  2552.                A = 0, zero set (Z) if no external FCB
  2553.                H╠ á╜ addres≤ oµ interna∞ namσ buffe≥ (valiΣ áonl∙ ì
  2554. áááááááááááááááiµ externa∞ FC┬ exists)
  2555.      Affected: AF¼ DE¼ HL
  2556.      Usage:    Return≤ ß pointe≥ t∩ thσ currentl∙ executinτ áproì
  2557. ááááááááááááááágraφ b∙ accessinτ thσ externa∞ FC┬ defineΣ iε áthσ ì
  2558. áááááááááááááááEnvironmen⌠ Descriptor«  I⌠ i≤ usefu∞ fo≥ áidentiì
  2559. áááááááááááááááfyinτ thσ rea∞ prograφ namσ wheε rσ-executeΣ áwitΦ ì
  2560. áááááááááááááááß á"GOó commanΣ o≥ equivalen⌠ facility«  Fo≥ áthi≤ ì
  2561. ááááááááááááááároutinσ át∩ functioε aε externa∞ FC┬ mus⌠ ábσ ádeì
  2562. áááááááááááááááfined.
  2563.  
  2564.      Routine║   PRTNAME
  2565.      Function║ Print program name from internal buffer
  2566.      Entry:    None
  2567.      Exit:     None; the name is printed to console
  2568.      Affected: None
  2569.      Usage:    Print≤ thσ curren⌠ prograφ namσ froφ aε áinternalì
  2570. ááááááááááááááál∙-helΣ buffe≥ t∩ thσ CON║ device.
  2571. .paèHIGHES╘ USEABL┼ MEMORY:
  2572.  
  2573.      Routine║   GZMTOP
  2574.      Function║ Return last usable TPA memory address
  2575.      Entry:    None
  2576.      Exit:     HL = last usable memory address in TPA
  2577.      Affected: HL
  2578.      Usage:    Determine≤ thσ to≡ oµ thσ availablσ TPA«  I⌠ áuse≤ ì
  2579. áááááááááááááááthσ extendeΣ environment¼ iµ available¼ áotherwisσ ì
  2580. ááááááááááááááái⌠ ácalculate≤ áthσ CC╨ basσ froφ BIO╙ áwarφ áboo⌠ ì
  2581. áááááááááááááááaddress« á I⌠ als∩ accommodate≤ sensinτ fo≥ áresiì
  2582. áááááááááááááááden⌠ RSX's«  Thσ addres≤ returneΣ i≤ thσ las⌠ bytσ ì
  2583. ááááááááááááááábelo≈ ß pagσ boundar∙ (L=0FFh⌐ fo≥ aε addeΣ safet∙ ì
  2584. ááááááááááááááámargin«  Fo≥ example¼ iµ thσ CC╨ begin≤ a⌠ á0C000Φ ì
  2585. áááááááááááááááanΣ án∩ RSX'≤ arσ present¼ thi≤ routinσ woulΣ áreì
  2586. áááááááááááááááturε 0BFFFh«  Oε thσ othe≥ hand¼ iµ aε RS╪ áexist≤ ì
  2587. áááááááááááááááwitΦ áß áprotec⌠ addres≤ oµ á0BC6Ch¼ áGXMTO╨ áwil∞ ì
  2588. áááááááááááááááreturε 0BBFFh.
  2589. .paè