II. Z3LIB -- ZCPR3 Support and Access Routines
Introduction . . . . . . . . . . . . . . . . . . . . . . 87
Extended Environment Description . . . . . . . . . 87
Access to the ZCPR3 Environment . . . . . . . . . . . . 90
Command Line . . . . . . . . . . . . . . . . . . . 91
APPCL, CLRCL, GETCL1, GETCL2, PUTCL
CRT and PRT Data . . . . . . . . . . . . . . . . . 92
GETCRT, GETPRT, PUTCRT, PUTPRT
External File Control Block . . . . . . . . . . . . 94
GETEFCB
Environment . . . . . . . . . . . . . . . . . . . . 94
GETENV, GETVID
Flow Command Package (FCP) Address . . . . . . . . 95
GETFCP
Filenames . . . . . . . . . . . . . . . . . . . . . 95
GETFN1, GETFN2, GETFNX, PUTFNX
Initialize . . . . . . . . . . . . . . . . . . . . 96
WHRENV, Z3INIT
System Data . . . . . . . . . . . . . . . . . . . . 97
ZSYSCHK, Z33CHK, GETBDOS, GETCCP, GETECP
Input-Output Package (IOP) Concepts . . . . . . . . 99
GETION, GETIOP, GETIOS, IOMATCH, PUTIOD
Input-Output Package (IOP) Recording . . . . . . . 101
IORCOFF, IORCON, IORLOFF, IORLON
Drive/User . . . . . . . . . . . . . . . . . . . . 101
GETDUOK, GETMDISK, GETMUSER, PUTDUOK,
PUTMDISK, PUTMUSER, HIGHUSER, GCMDDU
Messages . . . . . . . . . . . . . . . . . . . . . 103
GETMSG, GETSHM, PUTSHM
Named Directories . . . . . . . . . . . . . . . . . 104
ADDNDR, DIRNDR, DUNDR, GETNDR, SUBNDR
Path . . . . . . . . . . . . . . . . . . . . . . . 106
GETPATH
Processor Speed . . . . . . . . . . . . . . . . . . 106
GETSPEED, PUTSPEED
Quiet Flag . . . . . . . . . . . . . . . . . . . . 107
GETQUIET, PUTQUIET
Resident Command Package (RCP) Address . . . . . . 107
GETRCP
Shell Stack . . . . . . . . . . . . . . . . . . . . 108
GETSH1, GETSH2
Wheel Byte . . . . . . . . . . . . . . . . . . . . 108
GETWHL, PUTWHL
Flow, ZEX, and SUBMIT Control . . . . . . . . . . . . . 109
Flow Control . . . . . . . . . . . . . . . . . . . 109
IFEND, IFT, IFF, IFTEST, IFELSE
ZEX Access and Control . . . . . . . . . . . . . . 111
ZEX Data . . . . . . . . . . . . . . . . . . . 112
GETZFC, GETZNC, GETZRUN, PUTZNC, PUTZRUN
ZEX Status and Control . . . . . . . . . . . . 113
GETZEX, PUTZEX, HALTZEX, STOPZEX, STRTZEX
SUBMIT and XSUB Control . . . . . . . . . . . . . . 114
SUBMIT Data and Control . . . . . . . . . . . 115
SUBON, HALTSUB, GETSRUN, GETSFCB
XSUB Data and Control . . . . . . . . . . . . 116
STOPXSUB, GXSUB, PXSUB
ZCPR3 Messages . . . . . . . . . . . . . . . . . . . . . 116
Command Status Message . . . . . . . . . . . . . . 118
GETCST, PUTCST, QERROR, QSHELL
Error Flag and Error Command . . . . . . . . . . . 119
ERRADR, GETER1, PUTER1, GETERC, PUTERC
Inter-Transient Error Code . . . . . . . . . . . . 121
GETER2, PUTER2
Command Error Flag and Handler . . . . . . . . . . 121
GETER3, PUTER3, INVERROR
Command Status Flag . . . . . . . . . . . . . . . . 122
SETEPB, RESEPB, RETCST
Register Access . . . . . . . . . . . . . . . . . . 123
GETREG, PUTREG
Default Drive/User Buffer . . . . . . . . . . . . . 124
GDEFDU, PDEFDU
ZCPR3 Utilities . . . . . . . . . . . . . . . . . . . . 124
Named Directory-Drive/User Conversion . . . . . . . 124
DIRTDU, DUTDIR
Resolve Directory References . . . . . . . . . . . 125
DNSCAN, DUSCAN, DIRSCAN
Parse Command Line . . . . . . . . . . . . . . . . 126
PARSER
Path Search for File . . . . . . . . . . . . . . . 126
PFIND
Program Loading (Chaining) . . . . . . . . . . . . 126
PRGLOAD
Console Quiet Output . . . . . . . . . . . . . . . 127
QCOUT, QCRLF, QOUT, QPRINT, QPSTR
Locate ROOT Directory . . . . . . . . . . . . . . . 128
ROOT
Shell Stack Routines . . . . . . . . . . . . . . . 128
SHEMPTY, SHFULL, SHPOP, SHPUSH
Delay Routines . . . . . . . . . . . . . . . . . . 129
WAIT1S, WAIT1MS, WAITP1S
Log into ZCPR3 File Control Block Drive/User . . . 130
Z3LOG
Return Z3LIB Version . . . . . . . . . . . . . . . 130
Z3LVER
Parse Token . . . . . . . . . . . . . . . . . . . . 131
ZPRSFN, ZFNAME
ZCPR 3.3 Parsers . . . . . . . . . . . . . . . . . 131
Z33FNAME, PARSE2, REPARSE, SCAN
Check ZCPR 3.3 Parse Results . . . . . . . . . . . 132
FCB1CHK, FCB2CHK, FCBCHK
Print Load Module Data . . . . . . . . . . . . . . 133
PRTTYPE
ZCPR 3.3 Internal Program Name . . . . . . . . . . 133
GETNAME, PRTNAME
Highest Useable Memory . . . . . . . . . . . . . . 134
GZMTOP.pa
Z3LIB -- ZCPR3 Support and Access Routines
INTRODUCTION: Z3LIB contains support utilities which provide
access to ZCPR3- specific features and capabilities. Z3LIB rou
tines can be divided into four categories:
1.ZCPR3 Environment Access -- Utilities enabling you to
easily extract data from the Z3 Environment Descriptor and
modify certain Z3 environment parameters.
2.ZCPR3 Flow Control -- Utilities allowing you to easily
manipulate ZCPR3's Flow Control environment by raising or
lowering the current IF level and toggling the current IF
condition.
3.ZCPR3 Messages -- Utilities providing access to ZCPR3
messages, enabling programs to read and write messages from
and to the system.
4.ZCPR3 Utilities -- Utilities which relieve you from
constantly reprogramming some commonly-used ZCPR3 features.
EXTENDED ENVIRONMENT DESCRIPTION: Version 4 of Z3LIB incorpo
rates many enhanced functions developed by Joe Wright and Jay
Sage in NZCOM and ZCPR33 and 34. Due to redefinition of some of
the bytes in the Environment Descriptor, a few of the original
modules will not perform as originally intended. For example,
only one console (CRT device) is supported. The remaining space
in the ENV contains vectors to system segments.
Some programs such as Plu*Perfect Systems' JETLDR and Alpha Sys
tems' NZCOM set an existing Environment Descriptor to reflect the
necessary extended definitions. If you do not routinely use
either of these products, you should create a new SYS.ENV file
for use with your existing ZCPR3 system. The new definitions are
marked with an asterisk (*) in the following source code sample
Environment Descriptor.
; Library: NZENV.LIB
; Author: Joe Wright
; Version: 1.0
; Date: 29 Nov 87
; Adapted from Rick Conn's original SYSENV.LIB circa 1984
Z3ENV: JP CBIOS+6 ;* Real BIOS Addr (+6) for your
; system (* Was JP 0 *)
DEFB 'Z3ENV' ; Environment ID
DEFB 80H ;* Extended Env shown by Bit 7
DEFW EXPATH ; External Path address
DEFB EXPATHS ; # of 2-byte elements in Path
DEFW RCP ; RCP address
DEFB RCPS ; # of 128-byte blocks in RCP
DEFW IOP ; IOP address
DEFB IOPS ; # of 128-byte blocks in IOP
DEFW FCP ; FCP address
DEFB FCPS ; # of 128-byte blocks in FCP
DEFW Z3NDIR ; NDR address
DEFB Z3NDIRS ; # of 18-byte entries in NDR
DEFW Z3CL ; ZCPR3 Command Line
DEFB Z3CLS ; # of bytes in Command Line
DEFW Z3ENV ; ZCPR3 Environment Descriptor
DEFB Z3ENVS ; # of 128-byte blks in ENV
DEFW SHSTK ; Shell Stack address
DEFB SHSTKS ; # SHSIZE-byte entries in Stk
DEFB SHSIZE ; Size of a Shell Stack entry
DEFW Z3MSG ; ZCPR3 Message Buffer
DEFW EXTFCB ; ZCPR3 External FCB
DEFW EXTSTK ; ZCPR3 External Stack
DEFB 0 ; Quiet flag (0=not quiet)
DEFW Z3WHL ; Address of Wheel Byte
DEFB 4 ; Processor Speed in MHz
DEFB 'P'-'@' ; Maximum Disk
DEFB 31 ; Maximum User
DEFB 1 ; 1=Ok to accept DU:, 0=Not Ok
DEFB 0 ;* CRT Selection (* Unused *)
DEFB 0 ; Printer Sel (only 0 or 1)
DEFB 80 ; Width of CRT 0
DEFB 24 ; Number of lines on CRT 0
DEFB 22 ; Number of text lines on CRT 0
; CRT 1 descriptor is replaced with this valid drive vector.
; The command processor ignores 'maximum disk' above, and uses
; this vector instead. This allows 'holes' in the disk map.
; A user might have drives A, B, E, F, and G for example. In
; this case, his vector would look like:
; DEFW 0000000001110011B
; The command processor will treat drive C the same as drive H
; (unavailable) and take appropriate action.
DEFW 1111111111111111B ;* Valid drive vector (16) DEFB 0 ;* Not used
DEFB 80 ; Width of Printer 0
DEFB 66 ; Number of lines on Printer 0
DEFB 58 ; Number of text lines on Ptr 0
DEFB 1 ; H/W Form Feed (0=can't,1=can)
DEFB 102 ; Width of Printer 1
DEFB 66 ; Number of lines on Printer 1
DEFB 58 ; Number of text lines on Ptr 1
DEFB 1 ; H/W Form Feed (0=can't,1=can)
;* Descriptors for Printers 2 and 3 replaced with System Data
DEFW CCP ;* ZCPR 3.x start loc'n 3FH
DEFB CCPS ;* Size in records 41H
DEFW DOS ;* DOS starting location 42H
DEFB DOSS ;* Size in records 44H
DEFW BIOS ;* NZBIO starting location 45H
DEFB 'SH ' ; Shell Variable Filename
DEFB 'VAR' ; Shell Variable Filetype
DEFB ' ' ; Filename 1
DEFB ' ' ; Filetype 1
DEFB ' ' ; Filename 2
DEFB ' ' ; Filetype 2
DEFB ' ' ; Filename 3
DEFB ' ' ; Filetype 3
DEFB ' ' ; Filename 4
DEFB ' ' ; Filetype 4
DEFB 0 ;* Public drive OFF 7EH
DEFB 0 ;* Public user OFF 7FH
; (* Only defined for ZRDOS *)
; This dummy Terminal Capabilities description (Z3TCAP) will
; normally be replaced with a tailored MYTERM.Z3T on start up.
ENVORG2: DEFB ' ' ; Terminal Name (15 chars)
DEFB 0 ; No terminal attributes
DEFB 'E'-'@' ; Cursor Up
DEFB 'X'-'@' ; Cursor Down
DEFB 'D'-'@' ; Cursor Right
DEFB 'S'-'@' ; Cursor Left
DEFB 0 ; Cl delay
DEFB 0 ; Cm delay
DEFB 0 ; Ce delay
DEFB 0 ; Cl string
DEFB 0 ; Cm string DEFB 0 ; Ce string
DEFB 0 ; So string
DEFB 0 ; Se string
DEFB 0 ; Ti string
DEFB 0 ; Te string
; File filled with Zeros to end of 128-byte segment
ACCESS TO THE ZCPR3 ENVIRONMENT: Any program running under ZCPR3
is within a ZCPR3 environment. Many facilities and data are
available to this program which to not exist for normal CP/M
programs. For instance, a program running under the ZCPR3 envi
ronment can:
o Find out what name it was invoked by
o Access a set of messages from ZCPR3 which tell it a number
of things about how it was invoked
o Send messages to ZCPR3 and programs which run after it com
pletes
o Find out many things about its environment, such as the
processor speed, CRT and printer characteristics, maximum
number of disks
o Determine the your terminal characteristics and use them to
enhance the display with visual attributes such as cursor
addressing and highlighted text.
The information outlined above and more is available to any pro
gram thru the ZCPR3 Environment Descriptor. This is a 256-byte
block of memory containing addresses and other data in a precise
ly-defined format. ZCPR3 utilities may be written with an inter
nal Environment Descriptor or they may access an Environment
Descriptor residing at some fixed memory location (this is the
preferred approach). When executed, programs can extract speci
fic information from the descriptor for use.
The following information is contained within a ZCPR3 Environment
Descriptor:
address of external path size of external path
address of RCP size of RCP
address of FCP size of FCP
address of IOP size of IOP
address of named directory size of named directory
address of command line size of command line
address of env descriptor size of env descriptor
address of shell stack size of shell stack
address of Z3 messages size of stack entries
address of external FCB address of external stack
address of wheel byte quiet flag
processor speed DU approval flag
maximum disk allowed maximum user allowed
data on CRT data on printer
two reserved filenames ZCPR3 TERMCAP (Z3TCAP)
The purpose of Z3LIB is to provide you with easy access to infor
mation in the ZCPR3 Environment Descriptor and to allow you to
easily use this information. To illustrate, some of the Z3LIB routines are:
o GETPRT -- return data on the width, number of lines, and
form feed ability of the printer
o GETCL2 -- return the address of the first character of the
next command to be run, if any
o GETEFCB -- return the address of the external FCB so the
program can determine its name
o SHPUSH -- push a command line on the shell stack
o SHPOP -- pop a command line from the shell stack
o IFT -- invoke the next IF level and make it T
o IFEND -- back up to previous IF level
This file describes those Z3LIB routines which provide access to
the ZCPR3 Environment Descriptor data. Many of these routines
are of the general name:
GETxxxxx
where the mnemonic following the GET prefix alludes to what in
formation is being obtained.
COMMAND LINE:
Routine: APPCL
Function: Append command string to command line buffer
Entry: HL = address of command string to append
Exit: A <> 0, zero flag clear (NZ) if append complete
A = 0, zero flag set (Z) if buffer overflows or no
command line buffer (no change to command line)
Affected: AF; command line buffer is changed
Usage: Appends the specified NUL-terminated command
string to the end of the ZCPR3 command line buffer
for execution. A leading semicolon is prepended
to allow this line to execute after the last line
in the buffer. The command line buffer contents
are repacked to avert overflow in most cases.
PUTCL is a complementary function in which the
command string is added to the beginning of the
command line buffer as the first command.
Routine: CLRCL
Function: Clear the command line buffer
Entry: None
Exit: A <> 0, zero flag clear (NZ) if command line cleared
A = 0, zero flag set (Z) if no command line buffer
Affected: AF
Usage: Clears the command line buffer by setting it to
empty. Any remaining commands in the buffer will
not be executed when control is returned to ZCPR3.
Routine: GETCL1
Function: Return pointer to command line buffer
Entry: None
Exit: HL = address of command line buffer (0 if nonexis
tent)
A = size of buffer
Affected: AF, HL
Usage: Locates and returns command line buffer parame
ters. The command line buffer is structured as:
CMDLIN: DEFW
DEFB
DEFB
DEFB <....chars in command line>
DEFB 0 ; end of command string
Routine: GETCL2
Function: Return next command info from command line buffer
Entry: None
Exit: HL = address of next command (0 if no command line
buffer)
A = first character of command, zero clear (NZ) if
valid
A = 0, zero flag set (Z) if no characters in line
Affected: AF, HL
Usage: Used in applications where you need to directly
access characters in the next command stored in
the command line buffer.
Routine: PUTCL
Function: Store command line at beginning of command line
buffer
Entry: HL = address of NUL-terminated command line
Exit: A <> 0, zero flag clear (NZ) if OK
A = 0 zero set (Z) if overflow (no buffer change)
Affected: AF
Usage: Adds a command line as a prefix in the ZCPR3 com
mand line buffer as opposed to APPCL which appends
to the end of the command line buffer. Buffer
contents are repacked so that an overflow is
averted in most cases. If a command already
exists in the buffer, the new line is postfixed
with a semicolon so continuation is enabled.
CRT AND PRT DATA:
Routine: GETCRT
Function: Return address of CRT data record from ENV
Entry: None
Exit: HL = address of CRT record
Affected: HL
Usage: Determines the parameters of the installed termi
nal. The CRT record is structured as:
CRTDAT: DEFB 80 ; width of CRT in characters
DEFB 24 ; number of lines on the screen
DEFB 22 ; number of text lines on screen
The number of text lines should be two less than
the total number of lines. You may provide more
overlap by making it 3 or 4 less. This record
element tells utilities like PAGE how many lines
to output before pausing to allow you to read the
screen. This can be reduced (go to 20 or 18
lines) to allow you to see more of the last
screen.
Routine: GETPRT
Function: Return the address of the printer data record
Entry: None
Exit: HL = address of printer data record
Affected: HL
Usage: Provides data on some of the printer characteris
tics for use in formatting routines, or other
uses. The returned pointer is to a printer data
record as:
PRTDAT: DEFB 80 ; width of printer in characters
DEFB 66 ; number of lines on printer page
DEFB 58 ; number of text lines per page
DEFB 1 ; formfeed flag (0=can't FF, 1=can)
Programs such as PRINT may use the difference
between the third and second entries to determine
top and bottom margins, and test the last byte to
determine whether to issue a formfeed or count
line feed characters to advance to the next page.
Routine: PUTCRT
Function: Stores terminal select byte (no real function)
Entry: A = selection value (0)
Exit: A <> 0, zero flag clear (NZ) if entry was 0
A = 0, zero flag set (Z) if invalid (not 0)
Affected: AF
Usage: Performs no actual function in the extended envi
ronment which supports only one defined CRT data
block. For compatibility, it senses the select
value and simply returns status based on it.
Routine: PUTPRT
Function: Store printer selection byte (0..1) in environment
Entry: A = printer selection value (0 or 1)
Exit: A <> 0, zero flag clear (NZ) if OK
A = 0, zero flag set (Z) if invalid (not 0 or 1)
Affected: AF
Usage: Stores the selection (0 or 1) in the PRT selection
buffer of the ZCPR3 Environment Descriptor showing
that it is the currently active printer. Under
the extended environment, only two printers may be
defined instead of the four originally supported.
EXTERNAL FILE CONTROL BLOCK:
Routine: GETEFCB
Function: Return the address of the ZCPR3 external file
control block (FCB)
Entry: None
Exit: HL = address of external FCB
A <> 0, zero flag clear (NZ) if OK
A = 0, zero flag set (Z) if not found
Affected: AF, HL
Usage: Under ZCPR3, a program can find out by what name
it was invoked through the external FCB. Bytes 1-
8 of the external FCB (first byte is 0) contain
the name of the program just executed by ZCPR3.
This feature is particularly useful for shells
which have to push their name and operational
parameters onto the shell stack in order to be
reinvoked when a command line completes. A shell
can use the data in the external FCB to determine
what its name is without having to assume that it
has a particular name at all times.
ENVIRONMENT:
Routine: GETENV
Function: Return address of the ZCPR3 Environment Descriptor
Entry: None
Exit: HL = address of Environment Descriptor
Affected: HL
Usage: For those programs which need to modify the ZCPR3
Environment Descriptor. Most of the routines in
Z3LIB which access the Environment Descriptor do
so in a R/O mode (they do not allow the program to
change data in it). Some programs may need to do
this, so GENENV is provided. Z3LDR, for example,
loads a new Environment Descriptor from a file on
disk, and it uses GETENV to find out where to load
the file.
Routine: GETVID
Function: Return address of the ZCPR3 TCAP (Z3TCAP)
Entry: None
Exit: HL = address of Z3TCAP buffer
A <> 0, zero flag clear (NZ) if OK
A = 0, zero flag set (Z) if no entry in buffer
Affected: AF, HL
Usage: For those programs which need to modify the ZCPR3
TCAP buffer and those programs which need to de
termine if the TCAP is loaded. It may be desir
able to call this routine before a screen-oriented
utility is executed to insure that a TCAP is
available.
FLOW COMMAND PACKAGE (FCP) ADDRESS:
Routine: GETFCP
Function: Return address of the flow command package buffer
Entry: None
Exit: HL = address of FCB buffer
A = number of 128-byte FCP blocks, zero clear (NZ)
if OK
A = 0, zero flag set (Z) if no buffer
Affected: AF, HL
Usage: Returns the FCB parameters from the Environment
Descriptor. The starting address and size of the
FCP buffer in terms of 128-byte blocks are re
turned. To find out if an FCP is installed, look
at the first byte of the FCP buffer. If it is
zero, then no FCP is present.
Example:
EXT GETFCP ; declare the routine
... ; ..preliminary code
CALL GETFCP ; get addr/size from ENV
JR Z,NOFCP ; ..jump if no FCB buffer avail
LD A,(HL) ; examine the first buffer byte
OR A ; anything installed?
JR Z,LODFCP ; ..jump to load an FCP if not
... ; else use existing one
FILENAMES:
Routine: GETFN1, GETFN2
Function: GETFN1 gets address of shell variable filename,
GETFN2 gets address of first of system filenames
Entry: None
Exit: HL = address of 11-character filename entry
Affected: HL
Usage: Returns the address in HL of the shell variable
filename (GETFN1) and the first of the four system
filenames (GETFN2) in the ZCPR3 Environment De
scriptor. The filename entry is 11 bytes long,
matching the filename and filetype fields of the
CP/M file control block.
These filenames are used to pass names of special
files to programs for later use. Their exact use
is not defined and is left to you. One applica
tion would be to allow GETFN1 to return the name
of the master HLP file (HELP.HLP) to be used as an
index into the help system.
Routine: GETFNX
Function: Return address of nth filename of system filenames
Entry: A = filename number (1..4) in ENV filename buffer
Exit: HL = address of first byte of indicated file (11
characters)
A <> 0, zero flag clear (NZ) if OK
A = 0, zero flag set (Z) if input value not in
1..4 range
Affected: AF, HL
Usage: Returns the address of the nth filename in the
ZCPR3 Environment Descriptor. There are four
system files, numbered 1 to 4, and they are struc
tured like the Fn.Ft fields of a file control
block (11 bytes each). On input, A = 1..4 to
indicate the filename. On output, HL points to
the first byte of the name. A validity check is
done on the value of A which must be 1..4.
Routine: PUTFNX
Function: Set nth (1..4) filename in Environment Descriptor
Entry: A = filename number (1..4)
HL = address of FCB+1 of new filename value
Exit: A <> 0, zero flag clear (NZ) if OK
A = 0, zero flag set (Z) if input value not in
1..4 range
Affected: AF
Usage: Sets the nth (1..4) filename in the ZCPR3 Environ
ment Descriptor to the FCB-entry pointed to by HL
(FCB+1, or the Fn field, is pointed to by HL). A
is used to identify the filename.
INITIALIZE:
Routine: WHRENV
Function: Return installed ZCPR3 Environment Descriptor
address
Entry: HL = candidate address of Environment Descriptor
Exit: HL = points to start address of ENV (0 if not found)
A <> 0, zero flag clear (NZ) if ENV validated
A = 0, zero flag set (Z) if not found
Affected: AF, BC, DE, HL
Usage: Provides a means of locating a ZCPR3 Environment
Descriptor without the assistance of ZCPR 3.3 or
later command processors. Calling WHRENV with a
candidate address of the DOS entry address loaded
from locations 6 and 7 will cause a search for an
environment from that address up through FEFFh.
Calling it with a parameter of 0 precludes a
search to signify that the auto-search is to be
disabled.
Example:
EXT WHRENV,Z3INIT ; declare routines
... ; ..any header info here
LD HL,(6) ; load candidate location
CALL WHRENV ; ..and test it LD (Z3EADR),HL ; save any returned value
JR Z,NOENV ; ..jump if no ENV validated
CALL Z3INIT ; else set globals (or Z3VINIT)
Routine: Z3INIT
Function: Set global buffer to arbitrary address for ZCPR3
environment
Entry: HL = address of ZCPR3 environment descriptor
Exit: None
Affected: None
Usage: Sets a global variable to the ZCPR3 pointer value
installed in the program header. This global
variable is used by other Z3LIB routines.
Example:
EXT Z3INIT ; declare the routine
... ; ..header code
LD HL,Z3ENV ; load the Env Desc address
CALL Z3INIT ; ..and install!
... ; carry on!
SYSTEM DATA:
Routine: ZSYSCHK
Function: Validate ZCPR3 Environment Descriptor address
Entry: HL = points to candidate Z3 environment
Exit: A = 0, zero set (Z) if valid environment
A <> 0, zero clear (NZ) if environment not valid
Affected: AF
Usage: Checks various parameters in an Environment De
scriptor predicated on the specified address to
see if it is valid. It will print a message if
the environment is invalid. For best results on
ZCPR 3.3 or later, pass the value in HL at the
time the program starts. This will not work on
ZCPR 3.0, but will detect BackGrounder ii and
versions since ZCPR 3.3.
Example:
EXT ZSYSCHK ; declare the routine
...
LD HL,(ENVADR) ; load candidate environment
CALL ZSYSCHK ; is it valid? (message if not)
RET NZ ; ..quit if invalid
... ; else continue with valid ENV
Routine: Z33CHK
Function: Check for presence of ZCPR 3.3 or later
Entry: None
Exit: A = 0, zero set (Z) if CCP is ZCPR 3.3 or later
A <> 0, zero clear (NZ) if not ZCPR >= 3.3
Affected: AF
Usage: Should be used in the initial setup portion of a
program if many of the new Z3LIB routines are to
be used. Routines such as Z33FNAME rely on speci
fic entry points in the command processor which
only exist in ZCPR 3.3 or later. If such calls are made under other command processors, or if the
CP is overwritten, your program will be unable to
function.
Example:
EXT Z33CHK ; declare the routine
...
CALL Z33CHK ; Is CP ZCPR 3.3 or later?
JR NZ,NOTZ3 ; ..jump if not
... ; else we can use it
Routine: GETBDOS
Function: Return BDOS start address
Entry: None
Exit: HL = calculated or loaded BDOS starting address
Affected: HL
Usage: Returns the starting address of the Basic Disk
Operating System (BDOS) from an extended environ
ment if present, else it will calculate the start
ing address from the BIOS warm boot vector assum
ing a 3.5K BDOS size. You should not use this
address as the top of available memory, but only
to locate the DOS. Use the address at locations 6
and 7 or GZMTOP to find the highest usable memory
location depending on whether or not the CCP is to
be retained.
Routine: GETCCP
Function: Return command processor starting address
Entry: None
Exit: HL = calculated or loaded CCP starting address
Affected: HL
Usage: Returns the starting address of the command pro
cessor for use in calculating addresses of entry
points, and in locating ZCPR3 configuration bytes.
This routine first attempts to locate the CCP
address from an extended environment if present,
otherwise it will calculate the starting address
from the BIOS warm boot vector assuming a 3.5K
BDOS and a 2K CCP.
Routine: GETECP
Function: Return address of extended command processor name
Entry: None
Exit: HL = address of ECP name
Affected: HL
Usage: Locates the name of the ZCPR version 3.3 or later
extended command processor. Requires ZCPR 3.3 or
later and the command processor must not have been
overwritten.
INPUT/OUTPUT PACKAGE (IOP) CONCEPTS: This set of routines pro
vide access to the system Input/Output Package (IOP). The de
vices in an IOP are identified by a logical ID (referring to the
generic CON, RDR, PUN, and LST devices) and a physical ID (refer
ring to the specific device under the generic). By convention,
routines in this collection always pass the logical ID in the B
register and the physical ID in the C register. The following
table shows the assignments:
logical ID
(B reg) device
0 CON:
1 RDR:
2 PUN:
3 LST:
The IOP status table, contained in every IOP, returns information
on the physical ID's. It tells how many physical devices (PID)
are available for each logical ID, and the current assignment (0
to PID-1). This table is structured as:
offset number of current
bytes device devices assignment
0-1 CON: Byte 0 Byte 1
2-3 RDR: Byte 2 Byte 3
4-5 PUN: Byte 4 Byte 5
6-7 LST: Byte 6 Byte 7
For example, if byte 0 (number of physical consoles) is 5, then
byte 1 (current physical console assignment) can only be in the
range from 0 to 4. GETIOS returns the address of this table.
The routines in the IOP collection are:
GETION--return a string giving the name of the device
identified by a logical ID and a physical ID.
GETIOP -- return the address and size of the IOP.
GETIOS -- return a pointer to the IOP status table.
IOMATCH--searches for a physical device name associated
with a particular logical ID.
PUTIOD -- select and IOP device by logical and physical ID.
Routine: GETION
Function: Return address of name for specified device
Entry: B = logical device ID (0..3)
C = physical ID
Exit: HL = address of string naming the indicated device
A <> 0, zero flag clear (NZ) if no error
A = 0, zero flag set (Z) if no IOP or range error
Affected: AF, HL
Usage: Returns a pointer to the string describing the
device whose logical ID (0 to 3, where CON=0,
RDR=1, PUN=2, and LST=3) is in B and physical ID
is in C.
Routine: GETIOP
Function: Return address and size of IOP buffer definition
Entry: None
Exit: HL = address of IOP buffer
A = number of 128-byte blocks in buffer, zero
clear (NZ)
A = 0, zero flag set (Z) if no buffer
Affected: AF, HL
Usage: Returns details on the IOP buffer address and size
from the Environment Descriptor, but it does not
say if an IOP is resident. To find this out,
examine the first byte of the IOP buffer. If
zero, then no IOP is exists.
Example:
EXT GETIOP ; declare the routine
... ; ..preceeding code
CALL GETIOP ; get IOP buff data from ENV
JR Z,NOIOP ; ..jump if no IOP buffer
LD A,(HL) ; else get first byte
OR A ; is anything installed?
JR Z,LODIOP ; ..jump to load if not there
... ; else continue, IOP present
Routine: GETIOS
Function: Return pointer to I/O package status table
Entry: None
Exit: HL = address of IOP status table
A <> 0, zero flag clear (NZ) if OK
A = 0 zero set (Z) if no IOP loaded
Affected: AF, HL
Usage: Returns a pointer to the I/O package status table
in HL. The table is structured as:
offset number of current
bytes device devices assignment
0-1 CON: Byte 0 Byte 1
2-3 RDR: Byte 2 Byte 3
4-5 PUN: Byte 4 Byte 5
6-7 LST: Byte 6 Byte 7
Routine: IOMATCH
Function: Search for physical device name for logical ID
Entry: HL = address of device name string
B = logical ID (CON=0, RDR=1, PUN=2, LST=3)
Exit: C = physical ID
A <> 0, zero flag clear (NZ) if OK
A = 0, zero flag clear if not found or no IOP
Affected: AF, C
Usage: Searches for the name of a physical device associ
ated with a particular logical ID. This name is a
NUL-terminated string or any character less than
or equal to a space. The name is capitalized
internally. If found, C returns the physical ID
of the device.
Example:
EXT IOMATCH ; declare the routine
... ; ..preceeding code
LD HL,MYCON ; point to name string
LD B,0 ; select CON device
CALL IOMATCH ; search for the device
JR Z,ERROR ; ..jump error if bad
... ; else C=physical ID of MYCON
MYCON: DEFB 'CRT1',0 ; name of desired CON device
Routine: PUTIOD
Function: Select the IOP device from specified logical ID
Entry: B = logical ID (CON=0, RDR=1, PUN=2, LST=3)
C = physical ID
Exit: A <> 0, zero flag clear (NZ) if OK
A = 0, zero flag set (Z) if no IOP or range error
(physical or logical ID number invalid)
Affected: AF
Usage: Selects an IOP device from a set of logical and
physical ID's. Logical ID numbers are in the
range of 0 to 3, where CON = 0, RDR = 1, PUN = 2,
and LST = 3. See the introductory IOP section for
more details.
INPUT/OUTPUT PACKAGE (IOP) RECORDING:
Routines: IORCON, IORCOFF, IORLON, IORLOFF
Function: Turn on and off I/O recording in current IOP
Entry: HL = address of ZCPR3 FCB for recorded information
Exit: A <> 0, zero flag clear (NZ) if OK
A = 0, zero flag set (Z) if no IOP or recording
not supported in IOP
Affected: AF
Usage: IORCON turns on console recording, IORCOFF turns
off console recording, IORLON turns on list re
cording, IORLOFF turns off list recording. The
FCB passed to these routines is a standard ZCPR3
FCB, where offset 0 contains the disk and offset
13 contains the user data. A particular IOP may
or may not pay attention to this FCB pointer,
depending on implementation.
DRIVE/USER:
Routine: GETDUOK
Function: Return the value of the DUOK flag
Entry: None
Exit: A <> 0, zero flag clear (NZ) if DU use OK
A = 0, zero flag set (Z) if DU use not allowed
Affected: AF
Usage: Returns the DUOK flag value which tells the pro
gram if it is permissible to specify the DU prefix
to change disk and user area. ZCPR3 utilities can
always specify a DIR prefix (named directory) in
identifying the disk and user area to examine, but in some "secure" applications it is not desirable
to allow the user to employ the DU prefix to ac
cess any disk or user area. This flag (DUOK)
tells the utility if it is OK for the user to
employ the DU prefix.
Routine: GETMDISK
Function: Return the maximum allowable disk
Entry: None
Exit: A = maximum disk number (1=A..16=P)
Affected: AF
Usage: Obtains information from the ZCPR3 Environment
Descriptor which may be used to restrict access to
certain parts of the system. For instance, a
"normal user" may be denied access to disks C and
D. A "priveleged user" who has the power to
change the ZCPR3 Environment Descriptor can gain
access to any desired disk.
Routine: GETMUSER
Function: Return the maximum allowable user area
Entry: None
Exit: A = maximum allowable user area (0..31)
Affected: AF
Usage: Provides information from the ZCPR3 Environment
Descriptor which may be used to restrict access to
certain parts of the system. For instance, a
"normal user" may be denied access to any user
area beyond 10. A "priveleged user" who has the
power to change the ZCPR3 Environment Descriptor
can gain access to any desired user area.
Routine: PUTDUOK
Function: Set the DUOK byte to specified value
Entry: A = DUOK value (0=DU not OK, 0FFh = DU is OK)
Exit: None
Affected: None
Usage: Sets the DUOK byte from A. If A = 0, DUOK is
false and DU form of file specification is not OK.
If A<>0 (0FFh is preferred), DUOK is true and file
specification using the DU form is permitted.
Routine: PUTMDISK
Function: Set the maximum allowable disk in the environment
Entry: A = maximum allowable disk number (1=A..16=P)
Exit: None
Affected: None
Usage: Sets the maximum allowable disk in the Environment
Descriptor. Valid disk numbers range from 1 for
drive A to 16 for drive P.
Routine: PUTMUSER
Function: Set the maximum allowable user number (0..31)
Entry: A = maximum allowable user number (0..31)
Exit: None
Affected: None
Usage: Sets the maximum allowable user area in the Envi
ronment Descriptor. Valid user numbers range from
0 through 31.
Routine: HIGHUSER
Function: Return flag showing support for users higher than 15
Entry: None
Exit: Zero clear (NZ) if users higher than 15 supported
Zero set (Z) if no ZCPR 3.3 or no users higher
than 15
A = undefined
Affected: AF
Usage: Returns a flag indicating whether user numbers
greater than 15 are supported. This definition is
obtained from the ZCPR 3.3 or later command pro
cessor. Requires ZCPR 3.3 or higher and the com
mand processor must not have been overwritten.
Routine: GCMDDU
Function: Return drive and user number in external FCB
Entry: None
Exit: BC = DU; B=drive (0=A..15=P), C=user (0..31)
Affected: BC
Usage: Returns the drive and user for the file specified
in the external FCB. It is often used to deter
mine where the file was actually found (shell,
path, etc.) in order to log into or save that
location. External FCB must have been parsed by
ZCPR 3.3 or later, which places the user number in
FCB+13 and the drive in FCB+14.
MESSAGES:
Routine: GETMSG
Function: Return the address of the ZCPR3 message buffer
Entry: None
Exit: HL = address of the ZCPR3 message buffer
A <> 0, zero flag clear (NZ) if valid
A = 0, zero flag set (Z) if no buffer
Affected: AF,HL
Usage: In conjunction with other message routines for
synchronization between programs, and status in
formation. See Z3LIB information sections on
ZCPR3 Messages.
Routine: GETSHM
Function: Get value of shell message for specified message
number
Entry: B = message number (0, 1, 2)
Exit: A = message value (zero flag set accordingly)
Affected: AF
Usage: Returns the value of the shell message whose num
ber is specified. There are three shell messages,
so 0 <= B <= 2 (you must be sure a valid value is
presented).
Routine: PUTSHM
Function: Set the value of specified shell message number
Entry: A = message value
B = message number (0,1,2)
Exit: None
Affected: None
Usage: Places a message into one of the three message
positions in the shell area.
NAMED DIRECTORIES:
Routine: ADDNDR
Function: Add directory name to the named directory buffer
Entry: A = password flag (0=set to spaces, non-0=set from
DE)
DE = address of password buffer if A<>0 (8-charac
ters)
HL = address of FCB containing DU and disk name
Exit: A <> 0, zero flag clear (NZ) if name added suc
cessfully
A = 0, zero set (Z) if no buffer, or buffer full
Affected: AF
Usage: Adds a directory name to the named directory (NDR)
buffer defined in the Environment Descriptor. The
name, along with disk and user locations are
passed in ZCPR3 FCB form where the disk is at
offset 0 (A=1,..P=16), and the user number is at
offset 13 (0..31). The directory name is in the
Fn field of the FCB. An optional password of up
to eight characters (space-filled on right) may be
passed as a string in the DE register pair. On
input, if A=0 then the DE pointer is ignored and
the password is set empty (all spaces).
ADDNDR capitalizes the disk name and password, and
sorts the named directory buffer by DU after addi
tion. No check is made for duplicate names or
duplicate DU references.
Routine: DIRNDR
Function: Find named directory buffer entry for specified name
Entry: HL = address of 8-character buffer with name to find
Exit: HL = address of NDR entry, if found
BC = DU (disk in B, 1=A..16=P) if found
A <> 0, zero flag clear (NZ) if name found
A = 0, zero flag set (Z) if no NDR or not found
Affected: AF, BC, HL
Usage: Recovers the drive and user data for a specified
name from the named directory buffer. The entry
name is automatically capitalized. If found, the
drive is returned in register B (1=A..16=P), and
the user in register C (0..31). The HL register
pair will point to the NDR entry which is struc
tured around 18-byte entries as:
DEFB 1 ; disk (1=A..16=P)
DEFB 15 ; user (0 to 31)
DEFB 'ROOT ' ; name, 8-chars, space filled
DEFB 'MYPASS ' ; password, 8-char, space fill
Routine: DUNDR
Function: Find named directory entry from drive/user speci
fication
Entry: BC = drive/user in DU to locate (disk 1=A..16=P)
Exit: HL = address of NDR entry if found
A <> 0, zero flag clear (NZ) if found
A = 0, zero flag set if no NDR buffer or not found
Affected: AF, HL
Usage: Locates a named directory from the drive/user
specification in DU form where the drive is in
register B (drive 1=A..16=P) and user is in regis
ter C (0..31). If found, the address of the 18-
byte named directory buffer entry is returned.
Entries are structured as:
DEFB 2 ; disk (1=A..16=P)
DEFB 0 ; user (0..31)
DEFB 'HELP ' ; name, 8-char, space filled
DEFB ' ' ; password, 8-char, space fill
Routine: GETNDR
Function: Return named directory buffer parameters from
environment
Entry: None
Exit: HL = address of NDR buffer
A = buffer size in 128-byte blocks, zero clear (NZ)
A = 0, zero set (Z) if no NDR buffer
Affected: AF, HL
Usage: This routine returns the address and size of the
named directory buffer as defined in the Environ
ment Descriptor. It does not indicate the status
of any entries within it. To determine this,
examine the first byte in the buffer. If zero,
then no NDR is present in the buffer.
Example:
EXT GETNDR ; declare the routine
... ; ..preceeding code
CALL GETNDR ; get data from ENV
JR Z,NONDRBF ; ..jump if no NDR bufr exists
LD A,(HL) ; have an NDR. Is data there?
OR A
JR Z,LODNDR ; ..jump if not and load some
Routine: SUBNDR
Function: Remove specified named directory entry from NDR
buffer
Entry: HL = address of 8-character buffer containing name
Exit: A <> 0, zero flag clear (NZ) if removal successful
A = 0, zero flag set if no NDR or name not found
Affected: AF
Usage: Removes an entry specified by name from the named
directory buffer. The name must be provided as a
string of up to eight characters, space-filled on
right if less than eight characters. The name is
capitalized before it is checked against possible
entries. If located, the entry is removed, and
the remaining buffer is repacked.
PATH:
Routine: GETPATH
Function: Return address of the command search path from the
environment
Entry: None
Exit: HL = address of ZCPR3 search path from Environment
Descriptor
A = number of elements, zero flag clear (NZ) if OK
A = 0, zero set (Z) if no path defined in ENV
Affected: AF, HL
Usage: Return the address of the ZCPR3 command search
path as defined in the Environment Descriptor. If
there is a ZCPR3 path, it will be structured as a
series of two-byte path elements structured as:
DEFB 1 ; disk #1 (current='$', A=1..P=16)
DEFB 15 ; user #1 (current='$', 0..31)
DEFB '$' ; disk #2
DEFB 0 ; user #2
DEFB 0 ; end-of-list is drive = 0
PROCESSOR SPEED:
Routine: GETSPEED
Function: Return processor speed in MHz from environment
Entry: None
Exit: A = processor speed in megahertz
Affected: AF
Usage: Most often used in software timing loops to permit
a greater amount of portability in software. The
returned value is to the nearest megahertz, so 1 = 1 MHz, 4 = 4 MHz, etc.
Routine: PUTSPEED
Function: Set processor speed in environment to specified
value
Entry: A = processor speed in megahertz
Exit: None
Affected: None
Usage: Sets the processor speed as defined in the Envi
ronment Descriptor to the specified value in Mega
Hertz where 1 = 1 MHz, 4 = 4 MHz, etc.
QUIET FLAG:
Routine: GETQUIET
Function: Return value of quiet flag
Entry: None
Exit: A = value of quiet flag from environment
Zero flag set accordingly: 0 (not quiet) = Z, 0FFh
(quiet) = NZ
Affected: AF
Usage: Often used in programs to suppress unneeded or
unwanted status messages. By sensing the quiet
flag and using conditional print statements, more
pleasing operation can result. The quiet flag
value in stored in the Environment Descriptor.
Routine: PUTQUIET
Function: Set the value of the quiet flag
Entry: A = quiet flag value (0=not quiet, 0FFh=quiet)
Exit: None
Affected: None
Usage: Sets the quiet flag to the specified value. While
0FFh is preferred to indicate quiet operation, any
non-zero value will suffice.
RESIDENT COMMAND PACKAGE (RCP) ADDRESS:
Routine: GETRCP
Function: Return address and size of resident command pack
age (RCP) defined in environment
Entry: None
Exit: HL = address of RCP buffer
A = size of buffer in 12-byte blocks, zero clear (NZ)
A = 0, zero flag set (Z) if no RCP defined
Affected: AF, HL
Usage: Returns the resident command package buffer defi
nitions contained in the Environment Descriptor.
Your program must check for a valid package if
necessary by examining the first byte of the buf
fer.
Example:
EXT GETFCP ; declare the routine
... ; ..preceeding code
CALL GETFCP ; get ENV definitions
JR Z,NOFCPBUF ; ..jump if no RCP exists
LD A,(HL) ; check first byte of bufr
OR A ; anything there?
JR Z,LODRCP ; ..jump if not to load
... ; else have an RCP in place
SHELL STACK:
Routine: GETSH1
Function: Return defined shell stack parameters from envi
ronment
Entry: None
Exit: HL = address of shell stack
B = number of bytes in each shell stack entry
A = number of possible entries, zero clear (NZ)
A = 0, zero flag set (Z) if no shell stack
Affected: AF, B, HL
Usage: Returns data on the overall shell stack system
from the Environment Descriptor. See SHPUSH and
SHPOP routines for details on other facilities for
dealing with shell stacks provided by Z3LIB.
Routine: GETSH2
Function: Return defined shell stack parameters from envi
ronment
Entry: None
Exit: HL = address of shell stack
DE = number of bytes allowed in each stack entry
B, A = number of allowed entries, zero clear (NZ)
A = 0, zero set (Z) if no shell stack defined
Affected: AF, B, DE, HL
Usage: This is an alternative routine to recover shell
stack parameters from the Environment Descriptor.
For some uses, this form is more easily manipulat
ed than GETSH1 covered above. See SHPUSH and
SHPOP routines for details on other facilities for
dealing with shell stacks provided by Z3LIB.
WHEEL BYTE:
Routine: GETWHL
Function: Return the wheel byte value from the environment
Entry: None
Exit: A = wheel byte
Flags set accordingly: 0 (not wheel) = Z, 0FFh (is
wheel) = NZ
Affected: AF
Usage: Restricts users from accessing parts of programs,
or affecting program flow. For example, you may
not wish remote users to change the path defini
tion. By assigning "no wheel" status to remote users, the PATH utility will refuse to allow
changes, since it senses the priveleges with this
routine. While a 0FFh value is listed for grant
ing wheel priveleges, any non-zero value currently
suffices.
Routine: PUTWHL
Function: Set the value of the wheel byte in the environment
Entry: A = wheel byte value to set (0=no wheel, 0FFh=wheel)
Exit: None
Affected: None
Usage: Sets the wheel byte on (0FFh) or off (0), thereby
granting or denying wheel priveleges to executing
programs.
FLOW, ZEX, AND SUBMIT CONTROL:
FLOW CONTROL: All command sequences issued under ZCPR3 can be
thought to execute in a TRUE flow control state. That is, when
ever a command is executed under ZCPR3, the state of flow control
is TRUE. If the state of flow control is FALSE then no commands
except flow commands will be executed until the state of flow
control becomes TRUE.
Background: When ZCPR3 first comes up, the state of flow control
is always TRUE. Any command issued will be executed. If a Flow
Command Package is installed which supports the IF/ELSE/FI (End
IF) commands, then the state of flow control can be dynamically
changed by user commands, as the following terminal session il
lustrates:
SCR>; any command will execute now
SCR>era *.bak
No Files
SCR>dir
MYFILE .TXT | OBJECT .BIN
SCR>; we can set a flow control state to be false
SCR>IF F
IF F
SCR>; no command will execute now
SCR>dir
SCR>else
IF T
SCR>dir
MYFILE .TXT | OBJECT .BIN
SCR>FI
No IF
SCR>
Hence, when any command is executed, before the execution actual
ly begins, ZCPR3 will look to see if the state of the flow con
trol is TRUE. Such is the case when we are not within an IF
condition or when we are within one or more IF conditions, all of
which are TRUE.
ZCPR3 allows you to be nested into IF's up to eight (8) levels
deep. That is, the structure of your command sequences can take
the following form which can be nested to 8 levels of IF's:
IF T
IF T
IF T
FI
ELSE
IF T
FI
FI
ELSE
FI
Command structures like those presented above are now possible
under ZCPR3. In essence, ZCPR3 commands can now take the form of
a programming language in their own right.
The set of routines available in this part of Z3LIB are used to
provide you with a simple interface to control the flow control
within (and outside) your program. You can issue commands to:
o Enter the next IF level in TRUE or FALSE condition
o Toggle the state of the current IF level
o Drop down to the previous IF level
o Determine the current IF level number
o Or multiples of the above
Routine: IFEND
Function: Drop to previous IF level
Entry: None
Exit: A <> 0, zero flag clear (NZ) if successful
A = 0, zero flag set (Z) if no IF level
Affected: AF
Usage: Terminates the current IF level and drops to the
previous IF level, if the program is within one or
more IF's. For a transient program, there is
either no IF level, or there is a TRUE flow con
trol state (all preceeding IF's are TRUE).
Routines: IFT, IFF
Function: Raise and set IF level
Entry: None
Exit: A <> 0, zero flag clear (NZ) if IF level OK
A = 0, zero set (Z) on IF level overflow
Affected: AF
Usage: IFT sets IF level to TRUE, IFF sets IF level to FALSE. These routines are used to set flow con
trol states and raise the IF level. The flow
control state can support up to eight (8) levels
of IF's. IFT and IFF return error codes for over
flow conditions which should be sensed to insure
the integrity of the program.
Routine: IFTEST
Function: Determine the current IF level
Entry: None
Exit: A = number of current IF level
Zero flag is set accordingly
Affected: AF
Usage: Determines the current IF level. The returned
level value ranges from 0 to 8. If A=0, there is
no current IF. The zero flag is set accordingly
to allow rapid testing.
Example:
EXT IFTEST ; declare the routine
... ; ..preceeding code
CALL IFTEST ; get current IF level
JR Z,NOIF ; ..jump if none
CP 8 ; is it at max level?
JR Z,ATMAX ; ..jump if at max IF level
... ; else carry shows empty levels
Routine: IFELSE
Function: Toggle TRUE/FALSE state of current IF level
Entry: None
Exit: A <> 0, zero flag clear (NZ) if successful
A = 0, zero flag set (Z) if no current IF
Affected: AF
Usage: Toggles the current state of the current IF level.
If called an even number of times, the state is
effectively unchanged.
ZEX ACCESS AND CONTROL: The ZEX command file facility (under
ZCPR3 only) can be controlled by this set of Z3LIB routines. ZEX
intercepts all BIOS calls for input, and, when in intercept mode,
it provides input from text contained in its memory-based text
buffer rather than allowing the user to input characters from the
keyboard. These routines are used to query the status of ZEX and
to instruct ZEX to continue intercepting characters or to stop
intercepting characters and allow user input.
This set of routines provides access to the ZEX memory-based
command file processor and its environment. You can take control
of ZEX through these routines.
Summary of Routines:
GETZEX -- get the ZEX control message
GETZFC -- get the first character in ZEX buffer
GETZNC -- get the next character to be returned
GETZRUN -- get ZEX running flag HALTZEX -- terminate the ZEX processor
PUTZEX -- set the ZEX control message
PUTZNC -- set the next character to be returned
PUTZRUN -- set ZEX running flag
STOPZEX -- suspend ZEX execution
STRTZEX -- resume ZEX execution from a STOPZEX
ZEX DATA:
Routine: GETZFC
Function: Return address of first character in ZEX buffer
Entry: None
Exit: HL = address of first character in ZEX script buffer
A = character at that address
Carry clear (NC) if data
Carry flag set (C) if no text data in buffer
Affected: AF, HL
Usage: Used to examine the script data for a running ZEX
script sequence.
Routine: GETZNC
Function: Get next character ZEX will process
Entry: None
Exit: HL = address of next character in ZEX text buffer
A = next character to be returned, carry clear if
valid, carry flag set (C) if no text data remains
Affected: AF, HL
Usage: May be used to effect changes to a running ZEX
program by examining the next character that will
be returned.
Routine: GETZRUN
Function: Determine run status of ZEX from run message byte
Entry: None
Exit: A = run message
Zero set accordingly (0=not running)
Carry flag set (C) if no message available
Affected: AF
Usage: Returns the ZEX run message byte and sets flags
indicating status as: zero flag is set (Z) if ZEX
not running or clear (NZ) if it is; carry flag is
set (C) if there is no message or clear (NC) if
there is.
Routine: PUTZNC
Function: Set address of next ZEX character (GOTO)
Entry: HL = address of next character ZEX will return
Exit: Carry flag clear (NC) if operation successful
Carry set (C) if ZEX buffers not available
Affected: AF
Usage: Sets the address of the next character which will
be read by ZEX. Using this routine provides a
GOTO function for ZEX control.
Routine: PUTZRUN
Function: Set value of ZEX running message byte
Entry: A = value of ZEX running message byte
Exit: Carry flag set (C) if no message buffers
Affected: AF
Usage: Sets the ZEX running message byte to a user-sup
plies value. Its purpose is to allow running
programs to disable or suspend ZEX processing.
Set to zero to stop ZEX processing.
ZEX STATUS AND CONTROL:
Routine: GETZEX
Function: Return ZEX control message byte
Entry: None
Exit: A = ZEX control message (0,1,2)
Zero set accordingly
Affected: AF
Usage: Allows programs to determine the current state of
ZEX. The control message byte can have one of the
following three values:
0 = Normal. ZEX is running and intercepting
BIOS calls.
1 = ZCPR3 Prompt. ZEX is allowed to run and
intercept BIOS calls, but ZEX thinks
that it is providing input to the ZCPR3
command processor directly (ZEX is not
providing input to any program).
2 = ZEX Suspended. ZEX is not intercepting
BIOS calls and user input is allowed.
A 1 code should never be seen by a program since
it is set by ZCPR3 and cleared to 0 after ZEX has
completed the command line input. Any ZEX control
message is reset upon execution of ZCPR3 to 0 when
ZCPR3 is entered and then to 1 when the ZCPR3
prompt appears (ZCPR3 input). When ZCPR3 com
pletes its input, it resets the ZEX control mes
sage to 0.
Routine: PUTZEX
Function: Set ZEX control message byte (change ZEX state)
Entry: A = ZEX control message byte (0, 1, 2)
Exit: None
Affected: None
Usage: Allows a program to set the state that ZEX is in.
This control message byte must only be set to one
of these values:
0 = Normal. ZEX is running and intercepting
BIOS calls.
1 = ZCPR3 Prompt. ZEX is allowed to run and
intercept BIOS calls but ZEX thinks that
it is providing input to the ZCPR3 com
mand processor directly (ZEX is not
providing input to any program). 2 = ZEX Suspended. ZEX is not intercepting
BIOS calls and user input is allowed.
A 1 code may be set by any program if it wants ZEX
to "think" that it is providing input to ZCPR3.
If ZEX was previously suspended, it advances to
the beginning of the next line and resumes when it
sees this code. Any ZEX control message is reset
upon execution of ZCPR3 to 0 when ZCPR3 is entered
and then to 1 when the ZCPR3 prompt appears (ZCPR3
input). When ZCPR3 completes its input, it resets
the ZEX control message to 0.
Routine: HALTZEX
Function: Halt ZEX completely by setting ZEX end-of-file
Entry: None
Exit: A <> 0, zero flag clear (NZ) if ZEX is halted
A = 0, zero flag set (Z) if ZEX is not running
Affected: AF
Usage: Terminates execution of ZEX completely. Other
routines provide temporary execution control such
as STOPZEX (suspend execution), and STRTZEX (re
sume execution), but HALTZEX causes ZEX to termi
nate itself completely by setting the next charac
ter ZEX will process to the termination character
of 0FFh.
Routine: STOPZEX
Function: Temporarily suspend ZEX script processing
Entry: None
Exit: None; ZEX control message byte is set to 2
Affected: None
Usage: Temporarily stops ZEX from intercepting BIOS calls
and allows the user to input characters. This is
a shorthand to placing the 2 control code into the
ZEX control message byte.
Routine: STRTZEX
Function: Start processing from ZEX script
Entry: None
Exit: None
Affected: None
Usage: Allows ZEX to intercept BIOS calls and prevents
user from inputting characters. This is a short
hand to placing the 0 control code into the ZEX
control message byte.
SUBMIT AND XSUB CONTROL: In enhancing the ZCPR3 command proces
sors and defining the extended environment, provisions were also
made to control program flow from SUBMIT and XSUB utilities in
the same manner as the memory-based ZEX processing covered else
where.
SUBMIT processing is determined via flags and other data within
ZCPR Version 3.3 and later. Routines supporting its features must have access to the command processor. It is your responsi
bility to insure that the processor is not overwritten.
The combination of SUBMIT with an XSUB-like utility form the
basis of a disk-based corollary to ZEX for uses where a large TPA
space, or very large scripts must be processed. "Hooks" are
therefore provided with these routines to enable such a facility.
SUBMIT DATA AND CONTROL:
Routine: SUBON
Function: Determine whether SUBMIT processing is enabled
Entry: None
Exit: Zero clear (NZ) if SUBMIT is enabled
Zero set (Z) if no ZCPR 3.3 or SUBMIT disabled
A = destroyed
Affected: AF
Usage: Requires ZCPR 3.3 or later. Determines whether
the SUBMIT facility within ZCPR version 3.3 or
later is enabled. An error status is returned if
SUBMIT is disabled, or the command processor is
not ZCPR 3.3 or later. The command processor must
not have been overwritten.
Routine: HALTSUB
Function: Terminate an executing SUBMIT job
Entry: None
Exit: None; the $$$.SUB file is deleted
Affected: None
Usage: Stops an executing SUBMIT job by deleting the
$$$.SUB file addressed in the ZCPR 3.3 submit FCB.
Routine: GETSRUN
Function: Return flag indicating SUBMIT job status
Entry: None
Exit: A <> 0, zero clear (NZ) if SUBMIT job is running
A = 0, zero set (Z) if SUBMIT is not running
Affected: AF
Usage: Determines whether we are currently running within
a SUBMIT job. This is sometimes necessary infor
mation to determine possible actions within a
program.
Routine: GETSFCB
Function: Return the ZCPR 3.3 or later submit FCB address
Entry: None
Exit: DE = address of SUBMIT FCB (undefined if error)
A <> 0, zero flag clear (NZ) if OK
A = 0, zero set (Z) if no SUBMIT or ZCPR 3.3
Affected: AF, DE
Usage: Requires ZCPR 3.3 or later. This routine returns
the SUBMIT FCB address from ZCPR version 3.3 or
later FCB. An error status is returned if SUBMIT
is not enabled or the command processor is not of
the right type. The command processor must not have been overwritten.
XSUB DATA AND CONTROL:
Routine: STOPXSUB
Function: Reset XSUB input redirection flag
Entry: None
Exit: None; XSUB is halted
Affected: None
Usage: Stops XSUB program flow for local console input.
This is accomplished by resetting a flag in the
message buffer.
Routine: GXSUB
Function: Return the value of the XSUB redirection flag
Entry: None
Exit: A = value of the XSUB redirection flag
Affected: AF
Usage: Determines if input to the running program is
coming from an XSUB utility. This is useful in
error conditions where the normal flow of commands
and data must be altered for operator input.
Routine: PXSUB
Function: Set the XSUB input redirection flag
Entry: A = value to set XSUB input redirection flag
Exit: None; the value is set
Affected: None
Usage: Activates XSUB processing from a command script or
SUB file. By setting the XSUB redirection flag,
program flow can be dynamically altered. Until a
better definition is developed, it is suggested
that the command bytes used for ZEX be applied
(see GETZEX).
ZCPR3 MESSAGES: ZCPR3 offers many features not found in CP/M,
ZCPR1, or ZCPR2. One very special feature is that of command
processor messages.
ZCPR3 supports a message buffer which contains a number of mes
sages which can be passed from one transient program to another
or between ZCPR3 itself and all transient programs which run
under it. Commands can be given directly to ZCPR3, status infor
mation can be passed from ZCPR3 to the transients, and both stat
us and commands can be passed from one transient to another
through these messages.
These message can be divided into six basic classes:
o Messages which command ZCPR3
o Status messages sent by ZCPR3
o ZEX command messages
o Status and command messages sent by one program to another
which are ignored by ZCPR3
o User-defined messages
o Reserved messages
Before using any Z3LIB routines to access these messages, your
program should ensure that the message buffer is available to it.
This can easily be done by calling the GETMSG routine (see the
screen on the ZCPR3 environment). GETMSG returns with the zero
flag set (Z) if no ZCPR3 message buffer exists. Hence:
EXT GETMSG ; declare the routine
...
CALL GETMSG ; get message buffer status
JR Z,NOZ3MSGS ; ..jump if no msgs to read
...
The following summarizes facilities available through the ZCPR3
message buffer.
Messages which Command ZCPR3: Some of the messages in the ZCPR3
message buffer are set by external programs (transients or com
mand packages) and are read and interpreted by ZCPR3. These
messages are:
o Current IF level and active (T/F) status of all IF levels
o Whether an error handler is available and what the command
line to invoke it is
Status Messages Sent by ZCPR3: Some of the messages in the ZCPR3
message buffer are set only by ZCPR3 or a ZCPR3 shell and are
intended to be used as R/O messages by transients. These mes
sages are:
o ZCPR3 command status -- the transient loaded is or is not a
shell, and the transient loaded is or is not an error hand
ler
o Error address -- if the transient loaded is an error hand
ler, this is the address of the first character of the com
mand line which was in error
ZEX Command Messages: One message in the ZCPR3 message buffers
is intended to directly send commands to the ZEX memory-based
command file processor. This message byte tells ZEX three dif
ferent things:
o Run normally -- ZEX is to intercept input calls and provide
characters in place of console input
o ZCPR3 is prompting -- ZEX is providing input directly to the
command processor ZCPR3
o Suspend intercept -- ZEX is to stop intercepting console
input and allow input from the console until normal execu
tion or the ZCPR3 prompt appears
Messages Ignored by ZCPR3: Two pre-defined messages are ignored
by ZCPR3. The first is the program error code. This byte can be
set by any program under ZCPR3 to indicate a return status to the
next program. The convention has been adopted that if this byte
is 0, then the program completed successfully. If it is non-
zero, the program failed for some reason and the value of this
code indicates that reason to a following program.
The second message is the register buffer. Ten one-byte registers are available and can be tested by the Flow Command Package.
Conditions like "IF 0 5" (IF Register 0 = 5) can be tested and
processed by the Flow Command Package, and other transient pro
grams or resident command packages can manipulate these register
values.
User-Defined Messages: A set of 16 messages are available for
user definition. Each message is one byte long, and Z3LIB rou
tines are provided to place values into these messages and query
them.
Reserved Messages: A set of 16 one-byte messages is reserved for
future use in the ZCPR3 system and should not be used by applica
tions programmers. Z3LIB does not provide access to these mes
sages.
COMMAND STATUS MESSAGE: These messages return the status of the
current transient as set by ZCPR3. Any transient has been in
voked in one of three possible states:
1.As a "normal" transient, executed at the request of the
user or another program
2.As a "shell", invoked by ZCPR3 itself
3.As an "error handler", invoked by ZCPR3 itself when it
cannot process the current command line (cannot find a matching
COM file or CMDRUN facility)
Routine: GETCST
Function: Return the ZCPR3 command status message
Entry: None
Exit: A = message code (zero flag set accordingly)
Affected: AF
Usage: Returns the ZCPR3 command status message which is
always set by ZCPR3 and not intended to be set by
any program. It can have one of three values:
0 = this is a "normal" transient
1 = this is a "shell"
2 = this is an "error handler"
Routine: PUTCST
Function: Set the ZCPR3 command status message
Entry: A = ZCPR3 command status message value (0, 1, or 2)
Exit: None
Affected: None
Usage: Provided to allow a ZCPR3 shell program to set the
ZCPR3 command status message byte. It is not
intended for general use by application programs.
Allowable values for the command status message
are:
0 = this is a "normal" transient
1 = this is a "shell"
2 = this is an "error handler"
Routine: QERROR
Function: Test command status message for error handler
Entry: None
Exit: A = message code
Zero set (Z) if transient is an error handler,
else clear (NZ)
Affected: AF
Usage: Used as a quick test to see if the ZCPR3 command
status message indicates that the current transi
ent is an error handler. The ZCPR3 command status
message is read and tested against the error hand
ler code value. Zero flag is set if the current
transient is an error handler.
Routine: QSHELL
Function: Test command status message for shell transient
Entry: None
Exit: A = message code
Zero set (Z) if transient is shell
Affected: AF
Usage: Used as a quick test to see if the ZCPR3 command
status message indicates that the current transi
ent is a shell. The ZCPR3 command status message
is read and tested against the shell code value.
Zero flag is set if the current transient is a
shell.
ERROR FLAG AND ERROR COMMAND: This set of routines performs the
following functions:
ERRADR--returns the address of the first character of the
command line in error
GETER1 -- returns the error flag
PUTER1 -- sets the error flag
GETERC--returns the address of the first character of the
error handler command line
PUTERC -- set the error handler command line
Routine: ERRADR
Function: On error return first character of errored command
line
Entry: None
Exit: HL = address of first character of error line
Affected: HL
Usage: Assuming that the current transient is an error
handler, (call to QERROR returning with zero flag
set), this routine returns the address of the
first character of the command line which was in
error. For example, if the command:
xxx params;dir
is issued and XXX.COM cannot be found, ERRADR
returns the address of the first character ("X")
of the string:
DEFB 'XXX PARAMS;DIR',0
Routine: GETER1
Function: Return error flag
Entry: None
Exit: A <> 0, zero flag clear (NZ) if error present
A = 0, zero set (Z) if no error
Affected: AF
Usage: Returns the error flag in A. GETER1 has been
redefined from the original purpose of determining
error handler presence and now only returns the
value of the error flag.
Routine: PUTER1
Function: Engage and disengage error handler flag [no longer
used]
Entry: None
Exit: None
Affected: None
Usage: This routine no longer performs a function and
simply returns to the calling program.
Routine: GETERC
Function: Return address of string invoking error handler
Entry: None
Exit: HL = address of first character of string invoking error handler
A <> 0, zero flag clear (NZ) if valid character
A = 0 and zero flag set if string is empty
Affected: AF, HL
Usage: Facilitates error handler construction by return
ing the string address and first character. If
the error handler is to be invoked by the command:
error params
then GETERC returns the address of the first char
acter of:
DEFB 'ERROR PARAMS',0
Routine: PUTERC
Function: Set the error handler command line
Entry: HL = address of first character of error handler
command line
Exit: A <> 0, zero flag clear (NZ) if OK
A = 0, zero flag set (Z) if command line too long
(more than 32 bytes)
Affected: AF
Usage: Establishes a string which is to be the command
line executed to invoke an error handler. The
error string, including the ending 0, must be 32
bytes long or less.
Example:
EXT PUTERC ; declare the routine
... ; ..preceeding code
LD HL,ERSTR ; address this string
CALL PUTERC ; set it as handler comnd line
JR NZ,OK ; ..jump if string accepted
... ; else take other action
ERSTR: DEFB 'ERROR NOOPT',0
INTER-TRANSIENT ERROR CODE: The inter-transient error code is a
one-byte message which any program can set to indicate its com
pletion success. The convention is that if this message byte is
set to 0, then the program completed successfully. If this mes
sage byte is not 0, then the program had an error and the value
of this message byte indicates the error.
GETER2 allows a program to determine the value of this inter-
transient error code and PUTER2 allows a program to set the value
of the inter-transient error code.
Routine: GETER2
Function: Return the value of inter-transient error code
Entry: None
Exit: A = error code, zero clear (NZ) if error
A = 0, zero flag set (Z) if no error
Affected: AF
Usage: Determines if a preceeding program passed an error
to this one in the inter-transient error code.
Routine: PUTER2
Function: Set inter-transient error code
Entry: A = error code (0 for no error)
Exit: None
Affected: None
Usage: Signals following programs that no error status
resulted from the presently-executing transient.
COMMAND ERROR FLAG AND HANDLER:
Routine: GETER3
Function: Return the value of the command error flag
Entry: None
Exit: A <> 0, zero clear (NZ) if message exists
A = 0, zero set (Z) if no message
Affected: AF
Usage: Most often used by error handlers to identify
whether or not an error occurred. If an error is
detected from the command error flag, the message
buffers may be used to pass additional information
on the cause and action.
Routine: PUTER3
Function: Set the command error flag
Entry: A = value to set command error flag
Exit: None; value is stored in command error flag
Affected: None
Usage: Sets the command error flag for possible invoca
tion of an error handler. Additional information
may be passed in other message buffers.
Example:
EXT PUTER3 ; declare the routine
...
ISERR: LD A,0FFH ; signal error occurrance JR ERRV ; ..with command error flag
NOERR: XOR A ; enter here to set no errs
ERRV: CALL PUTER3 ; ..set/clear comnd err flag
... ; continue
Routine: INVERROR
Function: Invoke error handler
Entry: A = 0 for internal errors
A <> 0 for external errors
B = error code for external errors, undefined for
internal errors
Exit: A = 0 if error is internal to ZCPR 3.3
A <> 0 if error is external to ZCPR 3.3
Affected: AF, DE, HL
Usage: Sets all parameters for an error handler invoca
tion. It is normally used just prior to a program
abort to either the command processor or to a warm
boot.
Example:
EXT INVERROR ; declare the routine
... ; ..pgm flow w/detected error
LD A,(ERRCODE) ; get error code (if external)
LD B,A ; ..and put in correct register
LD A,(ERRTYPE) ; load the error type
CALL INVERROR ; call the routine
JP NZ,0 ; ..jump warm boot if no ZCPR33
... ; else return to command proc
COMMAND STATUS FLAG:
Routine: SETEPB
Function: Set external program bit in command status flag
Entry: None
Exit: None
Affected: None
Usage: Sets the external program bit in the command stat
us flag to signify to the ZCPR 3.3 or later com
mand processor that current actions (such as pars
ing) is being requested by an external program.
Routine: RESEPB
Function: Reset external program bit in command status flag
Entry: None
Exit: None
Affected: None
Usage: Resets the external program bit in the command
status flag indicating to the ZCPR 3.3 or later
command processor that any actions there are in
ternal and not related to an external program.
Routine: RETCST
Function: Return the address of the command status flag
Entry: None
Exit: HL = address of the command status flag
Affected: HL
Usage: Returns the address of the command status flag.
It is used by SETEPB, RESEPB, and other internal
modules.
REGISTER ACCESS: The ZCPR3 message buffer provides ten one-byte
messages which are used as one-byte registers. The GETREG and
PUTREG routines allow a program to obtain and set a value in any
one of the ten registers.
Routine: GETREG
Function: Return contents of specified message buffer
Entry: B = number of register to access (0..9)
Exit: A = value of register, zero flag set accordingly
Affected: AF
Usage: Used to obtain the contents of an arbitrary mes
sage buffer. These buffers are byte values.
GETREG performs no validity check on the specified
register number, merely using it as an index into
the message buffer array. You must insure that
only values in the range of 0..9 are passed.
Example:
EXT GETREG ; declare the routine
... ; ..preceeding code
LD B,5 ; get the value of reg 5
CALL GETREG ; return reg 5 value byte
JR Z,R5EQ0 ; ..jump to process if 0
... ; else check more, etc
Routine: PUTREG
Function: Set a specified message buffer register to given
value
Entry: B = register number to set (0 to 9)
A = value to set in register (0 to 255)
Exit: None
Affected: None
Usage: Sets a specified message buffer register to a
given value which may be tested by other programs.
No check is made to ensure that B contains a valid
register number. You must insure that in contains
only values from 0 to 9.
Example:
EXT PUTREG ; declare the routine
... ; ..preceeding code
LD B,9 ; set message register 9
LD A,20 ; ..to 20
CALL PUTREG ; do it
... ; ..and continue
DEFAULT DRIVE/USER BUFFER:
Routine: GDEFDU
Function: Return current drive and user
Entry: None
Exit: BC = DU; B=drive (0=A..15=P), C = user number
Affected: BC
Usage: Returns the current drive and user settings from
the ZCPR 3.3 message buffer for use by the CD
(change directory) routine, shells, or when a user
number greater than 15 is logged. This is the
preferred method of logging into high user areas
since the CURDRV byte at location 4 only accommo
dates users from 0 through 15.
Routine: PDEFDU
Function: Make specified drive and user current
Entry: BC = DU; B=drive (0=A..15=P), C=user (0..31) to set
Exit: None; CURDR and CURUSR are set to specified values
Affected: None
Usage: Stores specified drive and user values into CURDR
and CURUSR locations in the ZCPR3 message buffer,
thereby making them current. It is normally used
when drive and user are obtained from path speci
fications to signal shells or error handlers where
activities occurred.
ZCPR3 UTILITIES: These utilities provide a number of convenient
functions for ZCPR3 programmers. Access to directories, conver
sion from text string names to directory reference values, com
mand and command line parsing, quiet output routines, shell stack
manipulation, delay routines, and other ZCPR3-specific functions
are provided.
NAMED DIRECTORY-DRIVE/USER CONVERSION:
Routine: DIRTDU
Function: Convert specified DIR name to DU equivalent
Entry: HL = address of first character of DIR name
Exit: HL = points to delimiter at end of name
BC = DU, B=disk (0=A..15=P), C=user (0..31)
A <> 0, zero flag clear (NZ) if found
A = 0, zero flag set (Z) if not found
Affected: AF, BC, HL
Usage: Converts a DIR name consisting of a string of up
to eight characters terminated by any character
other than a digit or letter to its DU equivalent
found in the named directory buffer.
Routine: DUTDIR
Function: Convert specified DU to DIR equivalent
Entry: BC = DU, B=disk (0=A..15=P), C=user (0..31)
Exit: HL = pointer to 8-character name string
A <> 0, zero flag clear (NZ) if found
A = 0, zero flag set (Z) if not found
Affected: AF, HL
Usage: Searches the named directory for the specified DU.
If an entry exists for the corresponding DU, a
pointer is returned to the 8-character name (fol
lowed by an 8-character password).
RESOLVE DIRECTORY REFERENCES:
Routine: DNSCAN
Function: Resolve directory name using both DU and DIR
Entry: HL = address of the first character of directory
name
A = 0 (scan DU before DIR)
A <> 0 (scan DIR before DU)
Exit: BC = DU, B=disk (0=A..15=P), C=user (0..31)
A <> 0, zero flag clear (NZ) if found
A = 0, zero flag set (Z) if not found
Affected: AF, BC
Usage: Attempts to resolve a candidate directory name by
checking both DIR and DU formats in specified
order. The candidate name may be up to eight
characters terminated by a delimiter such as a
space, comma, period, dash, a character less than
space, etc. If found, the DU is returned in BC.
Routine: DUSCAN
Function: Resolve addressed string in DU form
Entry: HL = address of string (up to 8 characters)
Exit: BC = DU, B=disk (0=A..15=P), C=user (0..31)
A <> 0, zero flag clear (NZ) if valid DU form
A = 0, zero flag set (Z) if not valid
Affected: AF, BC
Usage: Resolves the DU form of a string addressed by HL.
The DU string is stored in a buffer up to eight
characters long, and is terminated by a delimiter,
which may be a character less than a space, equal
sign (=), underscore (_), period (.), comma (,),
less than (<), or greater than (>).
Routine: DIRSCAN
Function: Resolve addressed string in DIR form
Entry: HL = address of string (up to 8 characters)
Exit: BC = DU, B=disk (0=A..15=P), C=user (0..31)
A <> 0, zero flag clear (NZ) if valid DU form
A = 0, zero flag set (Z) if not valid
Affected: AF, BC
Usage: Resolves the DIR form of a string addressed by HL.
The DU string is stored in a buffer up to eight
characters long, and is terminated by a delimiter, which may be a character less than a space, equal
sign (=), underscore (_), period (.), comma (,),
less than (<), or greater than (>).
PARSE COMMAND LINE:
Routine: PARSER
Function: Parse complete command line
Entry: HL = address of command line
A = 0 (scan DIR before DU)
A <> 0 (scan DU before DIR)
Exit: HL = address of next command (0 or leading ;)
DE = address of FCB with command name (verb. COM)
A = 0, zero flag set (Z) if OK
A = number of question marks, zero clear (NZ) if
verb contains one or more "?" characters
Affected: AF, DE, HL
Usage: Parses a complete command up to an ending NUL or
multiple command line delimiter (usually a semi
colon). It parses and initializes all elements
per the ZCPR3 command conventions to include FCB1
at 005Ch, FCB2 at 006Ch and the default buffer
(TBUFF) at 0080h. The command name is returned in
an FCB addressed by DE.
PATH SEARCH FOR FILE:
Routine: PFIND
Function: Search for specified file along search path
Entry: DE = address of an FCB
A <> 0 to search current directory
A = 0 if no current search
Exit: BC = DU, B=disk (0=A..15=P), C=user (0..31)
A <> 0, zero flag clear (NZ) if found
A = 0, zero flag set (Z) if not found
Affected: AF, BC
Usage: Locates a file along the ZCPR3 search path. When
located, the disk and user where the file was
found are returned.
PROGRAM LOADING (CHAINING):
Routine: PRGLOAD
Function: Load and execute specified program (chain)
Entry: DE = address of a file control block
Exit: None
Affected: All registers; if this routine returns, then the
load was a failure.
Usage: This routine is a "chain" function which loads the
program indicated by the first 12 bytes addressed
by DE into memory at 100h and transfers control to
it. The loader and FCB used for the load are
relocated to just under the command processor
after PRGLOAD begins execution, so the TPA is free
for the load. Care should be taken to ensure that the system stack (located out of the TPA in a safe
area) is used instead of a stack in the TPA which
may be overwritten during load.
If PRGLOAD returns to the calling program, an
error in loading occurred. If all goes well, the
loaded program executes successfully.
CONSOLE QUIET OUTPUT: These routines output their values only if
the quiet flag is clear (0). If the quiet flag is TRUE (not 0),
then no values are output.
This class of routines includes the following:
QCOUT -- console character output with control
QCRLF -- new line
QOUT -- console character output
QPRINT -- string output (return address)
QPSTR -- string output (HL)
Routine: QCOUT
Function: Print character on console if not quiet
Entry: A = character to print
Exit: None
Affected: None
Usage: Comparible to the SYSLIB COUT routine, except that
it only prints if the quiet flag is off. Control
characters are printed as a caret (^) followed by
the character offset by 40h (1 outputs as ^A).
Routine: QCRLF
Function: Print a new line (CR/LF pair) if not quiet
Entry: None
Exit: None
Affected: None
Usage: Corresponds to the SYSLIB CRLF routine except that
in is only sent to the console if the quiet flag
is off (0).
Routine: QOUT
Function: Print without control character processing if not
quiet
Entry: A = character to output
Exit: None
Affected: None
Usage: Outputs the character in A without control charac
ter processing (1 outputs as binary 1) if the
quiet flag is off (0).
Routine: QPRINT
Function: Inline print of string if not quiet
Entry: None; string at return address
Exit: None
Affected: None
Usage: Prints a NUL-terminated string whose address is
contained on the stack top if the quiet flag is off (0). Execution resumes at the byte following
the NUL after the string is printed.
Routine: QPSTR
Function: Print NUL-terminated string if not quiet
Entry: HL = address of first character of the string
Exit: None
Affected: None
Usage: Same as QPRINT above, except that printing is from
a register as opposed the inline address from the
stack.
LOCATE ROOT DIRECTORY:
Routine: ROOT
Function: Return DU for the last directory in search path
Entry: None
Exit: BC = DU, B=disk (0=A..15=P), C=user (0..31)
Affected: BC
Usage: Provides a convenient way to find the last direc
tory in a path expression (ROOT directory). No
path optimization is performed.
This routine is sometimes not consistent with the
ZCPR3 command processor if the MINPATH (minimize
path expression) option is selected. ROOT ad
vances to the last referenced directory in the
path without minimization, while ZCPR3 minimizes
the search and may resolve a path to end (with
duplication) at a directory other than the physi
cally last directory in the path.
SHELL STACK ROUTINES: This set of routines supports shell stack
manipulation. The following routines are provided:
SHEMPTY -- test to see if shell stack is empty
SHFULL -- test to see if shell stack is full
SHPOP -- pop top string off of shell stack
SHPUSH -- push string onto shell stack
A shell stack is implemented as a series of strings (recommended
size is 32 bytes per string, and the stack should contain at
least four of these strings). The top element of a shell stack
specifies the command line to be executed as a shell by the ZCPR3
command processor. This command line is copied into the multiple
command line buffer for execution.
Routine: SHEMPTY
Function: Return status of shell stack
Entry: None
Exit: A <> 0, zero flag clear (NZ) if not empty
A = 0, zero flag set (Z) if empty or none
Affected: AF
Usage: Provides the current state of the shell stack.
The zero flag indicates whether or not shell stack
space is available.
Routine: SHFULL
Function: Determine if the shell stack is full
Entry: None
Exit: A <> 0, zero flag clear (NZ) if stack not full
A = 0, zero set (Z) if stack full or none
Affected: AF
Usage: Returns a flag indicating if the shell stack is
full or non-existant.
Routine: SHPOP
Function: Pop top element from shell stack and discard
Entry: None
Exit: A = 0, zero flag set (Z) if OK
A = error code, zero clear (NZ):
1 = no shell stack
2 = shell stack empty
Affected: AF
Usage: Removes the top element from the shell stack, if
possible, and discards it. Error codes report if
the operation was successful, or the reason for
the error.
Routine: SHPUSH
Function: Push NUL-terminated string onto shell stack
Entry: HL = addresses NUL-terminated string to push onto
stack
Exit: A = 0, zero flag set (Z) if successful
A = return code, zero clear (NZ):
1 = no shell stack available
2 = shell stack is full
3 = string too long for entry
Affected: AF
Usage: Performs needed functions to push NUL-terminated
strings onto the shell stack. Returned status
shows the results of the action.
DELAY ROUTINES: The following routines provide a software delay
based upon the processor speed value in the ZCPR3 Environment
Descriptor. These routines simply delay for the indicated period
of time (approximately) and then return. No registers are af
fected. The routines are:
WAIT1S -- delay for 1 second
WAIT1MS -- delay for 0.001 second
WAITP1S -- delay for 0.1 second
Routine: WAIT1S
Function: Wait for approximately one second
Entry: None
Exit: None
Affected: None
Usage: Pauses for approximately one second based on the
processor speed in the environment and the CPU
type.
Routine: WAIT1MS
Function: Wait for approximately one millisecond
Entry: None
Exit: None
Affected: None
Usage: Pauses for approximately one millisecond (.001
second) based on the processor speed in the envi
ronment and the CPU type.
Routine: WAITP1S
Function: Wait for approximately one-tenth second
Entry: None
Exit: None
Affected: None
Usage: Pauses for approximately one-tenth of a second
based on the processor speed and the CPU type.
LOG INTO ZCPR3 FILE CONTROL BLOCK DRIVE/USER:
Routine: Z3LOG
Function: Log into drive/user contained in a specified ZCPR3
file control block
Entry: DE = address of first byte of ZCPR3 file control
block
Exit: None
Affected: None
Usage: Logs into the drive and user contained in a speci
fied ZCPR3 file control block. The drive is in
byte 0 of the FCB (1=A..16=P) and the user (0..31)
is in byte 13. This is the standard format used
by ZCPR3 to store a complete DU reference in a
FCB.
RETURN Z3LIB VERSION:
Routine: Z3LVER
Function: Return version number of Z3LIB.REL
Entry: None
Exit: HL = version number (H=major, L=minor) in binary
Affected: HL
Usage: Records the Z3LIB version in linked programs, for
debugging with different versions.
PARSE TOKEN:
Routines: ZPRSFN, ZFNAME
Function: Parse file control block token
Entry: HL = address of first character of token
DE = address of 36-byte file control block
A = flag:
0 = scan for DIR form before DU
1 = scan for DU form before DIR
Exit: HL = address of character after token
A = number of question marks in filename.typ
Zero flag set accordingly
Affected: AF, HL
Usage: Performs the identical function of parsing a com
plete FCB token as the ZCPR3 command processor.
Tokens may take the form of "dir:filename.typ",
"du:filename.typ", "filename.typ", etc. The re
sulting FCB contains the filename and type and a
proper DU reference. (See PARSER, which is relat
ed.)
ZFNAME is a literal interpretation of the code
within the ZCPR3 command processor, while ZPRSFN
is a more efficient body of code but uses more
buffer space.
ZCPR 3.3 PARSERS:
Routine: Z33FNAME
Function: Parse single token from external command buffer
Entry: DE = address of user-defined FCB to receive token
Exit: HL = address of delimiter in command buffer
Affected: HL
Usage: Requires ZCPR 3.3 or later. This routine parses a
single token from the external command buffer to a
specified FCB. It uses the SCAN entry in ZCPR 3.3
or later. You must insure that the command pro
cessor has not been overwritten to use this func
tion.
Routine: PARSE2
Function: Parse command line using ZCPR 3.3 REPARSE entry
Entry: HL = address of the command line to reparse
Exit: None; line is reparsed and FCB's filled
Affected: None
Usage: Requires ZCPR 3.3 or later. This routine parses a
specified command line to the default FCB's at 5Ch
and 6Ch. You must insure that the command proces
sor has not been overwritten to use this routine.
Routine: REPARSE
Function: Reparse default command line one token later
Entry: None
Exit: None; the command line is reparsed
Affected: None
Usage: Requires ZCPR 3.3 or later. This routine reparses
the current command line starting one token after
current setting and sets the default FCB's. You
must insure that the command processor has not
been overwritten to use this routine.
Routine: SCAN
Function: Scan single token from specified command line
Entry: HL = points to command line to scan
DE = points to FCB to receive parsed token
Exit: None; token is parsed
Affected: None
Usage: Requires ZCPR 3.3 or later. This routine parses a
single token from a user-specified command line
into a specified FCB using the SCAN entry in ZCPR
3.3 or later. You must insure that the command
processor has not been overwritten to use this
routine.
CHECK ZCPR 3.3 PARSE RESULTS:
Routines: FCB1CHK, FCB2CHK
Function: Examine default file control blocks for validity
Entry: None
Exit: A = 0, zero set (Z) if FCB has valid name
A <> 0, zero clear (NZ) if error or no name
Affected: AF
Usage: Requires FCB parsed by ZCPR 3.3 or later. These
routines examine the default FCB's at locations
5Ch (FCB1CHK) and 6Ch (FCB2CHK) for validly parsed
filenames from ZCPR 3.3 or later parsers. Errors
are due to DU out of range, illegal named direc
tory, or illegal password.
Routine: FCBCHK
Function: Examine specified file control block for validity
Entry: DE = address of an FCB to check
Exit: A = 0, zero set (Z) if FCB has valid name
A <> 0, zero clear (NZ) if error or no name
Affected: AF
Usage: Requires FCB parsed by ZCPR 3.3 or later. This
routines examines the FCB at a specified address
for validly parsed filename by ZCPR 3.3 or later
parsers. Errors are due to DU out of range, ille
gal named directory, or illegal password.
PRINT LOAD MODULE DATA:
Routine: PRTTYPE
Function: Print load module type and address
Entry: A = program type (1..4)
HL = program load address
Exit: None; the type and address are printed on console
Affected: None
Usage: Most often used in extended processors and utili
ties to display load information. It prints a
message to the CON: device containing load module
type (3 or 4) and the load address in hex.
Example:
EXT PRTTYPE ; declare the routine
...
JP BEGIN ; ZCPR 3 header structure
DEFB 'Z3ENV' ; .ID string
TYPE: DEFB 3 ; ..module load type
Z3EADR: DEFW $-$ ; ...candidate ENV address
START: DEFW 9800H ; type 3 starting addr = 9800h
BEGIN: ... ; initial setup, set stack, etc
LD A,(TYPE) ; get the load module type
LD HL,START ; ..and load starting address
CALL PRTTYPE ; print them to the console
... ; ..continue on
ZCPR 3.3 INTERNAL PROGRAM NAME:
Routine: GETNAME
Function: Return pointer to current program name
Entry: None
Exit: A <> 0, zero clear (NZ) if external FCB exists
A = 0, zero set (Z) if no external FCB
HL = address of internal name buffer (valid only
if external FCB exists)
Affected: AF, DE, HL
Usage: Returns a pointer to the currently executing pro
gram by accessing the external FCB defined in the
Environment Descriptor. It is useful for identi
fying the real program name when re-executed with
a "GO" command or equivalent facility. For this
routine to function an external FCB must be de
fined.
Routine: PRTNAME
Function: Print program name from internal buffer
Entry: None
Exit: None; the name is printed to console
Affected: None
Usage: Prints the current program name from an internal
ly-held buffer to the CON: device.
HIGHEST USEABLE MEMORY:
Routine: GZMTOP
Function: Return last usable TPA memory address
Entry: None
Exit: HL = last usable memory address in TPA
Affected: HL
Usage: Determines the top of the available TPA. It uses
the extended environment, if available, otherwise
it calculates the CCP base from BIOS warm boot
address. It also accommodates sensing for resi
dent RSX's. The address returned is the last byte
below a page boundary (L=0FFh) for an added safety
margin. For example, if the CCP begins at 0C000h
and no RSX's are present, this routine would re
turn 0BFFFh. On the other hand, if an RSX exists
with a protect address of 0BC6Ch, GXMTOP will
return 0BBFFh.