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.