Section III Z3LIB REFERENCE ZCPR3: THE LIBRARIES A Reference Manual and User's Guide for SYSLIB, Z3LIB, and VLIB Written by Richard Conn Copyright 1986 Richard Conn This Page Left Blank ZCPR3: The Libraries Z3LIB Introduction 13. INTRODUCTION TO Z3LIB Z3LIB contains a host of support utilities which provide access to ZCPR3-specific features and capabilities. Z3LIB routines can be divided into four categories: 1. ZCPR3 Environment Access — Those utilities which allow the programmer to easily extract data from the Z3 Environment Descriptor and modify certain Z3 environment parameters 2. ZCPR3 Flow Control — Those utilities which permit the programmer to easily manipulate the flow control environment of ZCPR3, enabling him to raise the level or lower the level of the current IF condition and to toggle the current IF condition as desired 3. ZCPR3 Messages —~ Those utilities providing access to the ZCPR3 messages, allowing the program to read and write messages from and to the system 4. ZCPR3 Utilities — Useful utilities which relieve the programmer from constantly reprogramming some commonly-used ZCPR3 features 13-1 ZCPR3: The Libraries Z3LIB Introduction NOTES: 13-2 ZCPR3: The Libraries Z3LIB Environment Access 1 14. ENVIRONMENT ACCESS 1 CHAPTER OUTLINE Command Line APPCL CLRCL GETCL1, GETCL2 PUTCL CRT/Printer Data GETCRT, PUTCRT GETPRT, PUTPRT DU/Max DU GETDUOK, PUTDUOK GETMDISK, PUTMDISK GETMUSER, PUTMUSER External FCB GETEFCB Environment of ZCPR3 GETENV GETVID FCP Address GETFCP File Names GETFN1, GETFN2 GETFNX, PUTFNX Initialize Z3INIT Introduction to IOP Concepts IOP GETION, GETIOP, GETIOS IOMATCH PUTIOD IOP Recording IORCOPF, IORCON IORLOFF, IORLON 14-1 ZCPR3; The Libraries Z3LIB Environment Access 1 Environment Access 1 Any program running under ZCPR3 is within what can be called a ZCPR3 environment. A host of facilities and data is available to this program which a normal CP/M program does not have. For instance, a program running under the ZCPR3 environment: . can find out what name it was invoked by . can access a set of messages from ZCPR3 which tell it a number of things about how it was invoked . can send messages to ZCPR3 and programs which run after it completes . can find out many things about its environment, such as the processor speed, CRT and printer characteristics, maximum number of disks . can determine what characteristics the user's terminal has and make use of these to employ cursor addressing and other such functions All of the information outlined above and more is available to any running program thru the ZCPR3 Environment Descriptor. This is a block of memory (256 bytes) which contains addresses and other data in a precisely-defined format. At installation time, the ZCPR3 utilities can be set up to internally contain an Environment Descriptor or they can be installed with a pointer to an Environment Descriptor which resides at some fixed location in memory (this is the preferred approach). Once the routines in Z3LIB have been initialized with knowledge of the address of this environment descriptor, they can extract specific information from it for use in the application program. The following information is contained within a ZCPR3 Environment Descriptor: address of External Path address of RCP address of FCP address of IOP address of Named Dir address of Command Line address of Env Descriptor address of Shell Stack address of Z3 Messages address of External FCB address of Wheel Byte processor speed maximum disk allowed data on CRT two reserved file names size of External Path size of RCP size of FCP size of IOP size of Named Dir size of Command Line size of Env Descriptor size of Shell Stack size of Stack Entries address of External Stk quiet flag DU approval flag maximum user allowed data on Printer ZCPR3 TERMCAP (Z3TCAP) 14-2 ZCPR3: The Libraries Z3LIB Environment Access 1 The purpose of Z3LIB is to provide the programmer with easy access to the information in the ZCPR3 Environment Descriptor and to allow him to easily make use of this information. To illustrate, the some Z3LIB routines are: . GETPRT - return data on the width, number of lines, and form feed ability of the printer . GETCL2 - return the address of the first char of the next command to be run, if any . GETEFCB - return the address of the external FCB so the program can determine its name . SHPUSH - push a command line on the shell stack . SHPOP - pop a command line from the shell stk . IFT - invoke the next IF level and make it T . IFEND - back up to previous IF level This chapter 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 information is being obtained. 14.1. Command Line Routine: APPCL Function: APPCL appends the command string (ending in null) pled to by HL 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 roost cases. PUTCL inserts the command line as the next command in the buffer, while APPCL appends the command line as the last command in the buffer. This is the difference between APPCL and PUTCL. Error flag is returned, indicating overrun of buffer. If buffer is overrun, original command line is not changed. Inputs: HL = address of command string to append Outputs: A = Error Code A=0 and Zero Flag Set (Z) if command line buffer overflows (no change to command line) or no command line buffer A=OFFH and NZ if append is complete Registers Affected: PSW Side Effects: Command Line buffer is changed Special Error Conditions: None 14-3 ZCPR3: The Libraries Z3LIB Environment Access 1 Routine; CLRCL Function: CLRCL clears the command line buffer, setting it to empty. Any remaining commands in the buffer will not be executed when control is returned to ZCPR3. Inputs: None Outputs: A = Error Code A=0 and Zero Flag Set (Z) if no command line buffer (no problem, anyway) A=OFFH and NZ if command line cleared Registers Affected: PSW Side Effects: Command line buffer cleared Special Error Conditions: None Routine; GETCLl Function: Returns the address of the Command Line Buffer in HL and its size (in byte) in A. The Command Line Buffer is structured as follows: cindline: dw
db db db db 0 GETCL1 returns the address of CMDLINE in HL and the size (at CMDLINE+2) in A. Inputs: None Outputs: HL=addreas of CMDLINE, A=size Registers Affected: HL, PSW Side Effects: None Special Error Conditions: HL = 0 if there is no command line buffer Routine: GETCL2 Function: Returns the address of the first character of the next command to be executed in the Command Line Buffer in HL and the first character of the next command in A. A=0 and the Zero Flag is Set (Z) if there are no further characters in the line. The Command Line Buffer is structured as follows; crndline: dw
db db db db 0 GETCL2 returns the address contained in the first DW at the label CMDLINE in HL and the char at this address in A. Inputs: None Outputs; HL=address of next command, A=first char Registers Affected: HL, PSW Side Effects: None 14-4 ZCPR3: The Libraries Z3LIB Environment Access 1 Special Error Conditions: HL = 0 if there is no Command Line Buffer. Routine: PDTCL Function: PUTCL stores a command line as a prefix in the ZCPR3 command line buffer. The 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. Inputs: HL = Address of command line (ending in 0) Outputs: A=0 and Zero Flag Set db db For example, a conventional CRT would look like: db 80 80 cols db 24 24 lines db 22 22 text lines The number of text lines should be two less than the total number of lines. It may be made 3 or 4 less if the user wants to see wider overlap on his screen. The purpose of this record element is to tell utilities like PAGE how many lines to output before pausing to allow the user to read the screen, and this can be reduced (go to 20 or 18 lines) to allow the user to see more of the last screen he was viewing. Inputs: None Outputs: HL contains the address of the CRT record Registers Affected: HL Side Effects: None Special Error Conditions: None 14-5 ZCPR3: The Libraries Z3LIB Environment Access 1 Routine; POTORT Function: PUTCRT stores the selection (0 or 1) in the CRT selection buffer of the ZCPR3 Environment Descriptor. An error code is returned and no change to the buffer is made if the input selection is out of range (not 0..1). Inputs: A = CRT Selection value (0 or 1) Outputs: A = Error Code A=0 and Zero Flag Set (Z) if invid sel (not 0 or 1) A=OFFH and NZ if OK Registers Affected: PSW Side Effects: CRT Selection flag in Env .Desc is set Special Error Conditions: None Routine; GETPKT Function: Return the address of the Printer data record in HL. This record is structured as follows: prtdata: db db db db ; any command will execute now SCR>era *.bak No Piles 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> When any command is executed, before the execution actually begins, ZCPR3 will look to see if the state of the flow control 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 the user to be nested into IFs up to eight (8) levels deep. That is, the structure of his command sequences can take the form of something like the following which can be nested into 8 levels of IPs: 16-2 ZCPR3; The Libraries Z3LIB Plow and ZEX Control IF T IF T IF T FI ELSE IF T FI FI ELSE PI Command structures like those presented above are now possible under ZCPR3. Essentially, 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 the programmer a simple interface to control the flow control within (and outside) his program. He can, under his own control, issue commands to: . enter the next IF level in a TRUE or FALSE condition, . toggle the state of the current IF level, . drop down to the previous IF level, . determine the current IF level number, . or multiples of the above 16.1.1. End IF Routine: IFEND Function: Drop to the previous IF level. If the program is currently within one or more IFs, IFEND will drop it to the next IF level down, terminating the current IF level. For a transient to be executing, there is currently either no IF level or there is a TRUE flow control state (all preceeding IPs are TRUE). If we are at some IF level, calling IFEND drops us into the proceeding one. Inputs: None Outputs: A = Error Code A=0 and Zero Flag Set (Z) if no IF level A=OFFH and NZ if IFEND is successful Registers Affected: PSW Side Effects: None Special Error Conditions: None 16-3 ZCPR3: The Libraries Z3LIB Flow and ZEX Control 16.1.2. Raise IF Routine; IFT, IFF Function: Raise the flow control state into the next level of IF. IFT raises the state into the next level and sets it to TRUE, while IFF raises the state into the next level and sets it to FALSE. The flow control state can support eight (8) levels of IPs, and IFT and IFF return error codes indicating if an overflow (and subsequent failure to enter the next state) occurred. Inputs: None Outputs: A = Error Code A=0 and Zero Flag Set (Z) if IF level overflow A=OFFH and NZ if IF level OK Registers Affected: PSW Side Effects: None Special Error Conditions: None 16.1.3. Test IF Routine: IFTEST Function: To determine the current IF level. IFTEST returns a value from 0 to 8 in the A register, indicating the current IF level. If A=0, there is no current IF. The Zero Flag is set accordingly, so the following can be done: ext IFTEST call if test ;get IF level jz noif process if not any IF level cpi 8 test for max IF level jz atmax process if at max IF level Inputs: None Outputs: A = number of current IF level. Zero Flag set accordingly Registers Affected: PSW Side Effects: None Special Error Conditions: None 16.1.4. Toggle IF Routine: IFELSE Function: Toggle the TRUE/FALSE state of the current IF level. IF the program is currently within an IF level (then it MUST be within a TRUE IF level), calling IFELSE (an odd number of times) toggles the IF level to FALSE. Two calls to IFELSE (any even number of calls) result in the IF level remaining at TRUE. Inputs: None Outputs: A = Error Code A=0 and Zero Flag Set (Z) if no current IF A=OFFH and NZ if successful Registers Affected: PSW Side Effects: None Special Error Conditions: None 16-4 ZCPR3; The Libraries Z3LIB Flow and ZEX Control 16.2. ZEX Access and Control The ZEX Command Pile Facility (under ZCPR3 onlyl) 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. The programmer 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 PUTZNC PUTZRUN STOPZEX STRTZEX 16.2.1. ZEX Data Set the ZEX Control Message Set the next character to be returned Set ZEX Running Flag Suspend ZEX Execution Resume ZEX Execution from a STOPZEX Routine: GETZFC Function: GETZFC (Get ZEX First Character) returns the address in HL of the first character in the ZEX text buffer. Carry Flag is set if data is not available. Inputs: None Outputs: HL = Address of First Character A = Character Carry Flag Set (0 if No Data Registers Affected: HL, PSW Side Effects: None Special Error Conditions: None Routine; GETZNC Function: GETZNC (Get ZEX Next Character) returns the address in HL of the next character which ZEX will return. Carry Flag is Set if no data. Reg A contains the character. Inputs; None Outputs: HL = Address of Next Character in ZEX Text Buffer A = Next Character in ZEX Text Buffer Carry Flag Set (C) if no data Registers Affected: HL, PSW Side Effects: None Special Error Conditions: None 16-5 ZCPR3; The Libraries Z3LIB Flow and ZEX Control Routine: PUTZNC Function: PUTZNC sets the address of the next character which ZEX will return to that contained in HL. This routine provides a GOTO function for ZEX control. Inputs: HL = address of next character ZEX will return Outputs: Carry Flag Set ) Inputs: HL = address of first char Outputs: A=OPFH, NZ, and BC==DU (disk A = 0) if valid A=0 and Zero Flag Set (Z) if not valid Registers Affected: BC, PSW Side Effects: None Special Error Conditions: None Routine; DIRSCAN Function: DIRSCAN resolves the DIR form pted to by HL. The DIR string is stored in a buffer up to eight characters long, and it is terminated by a delimiter if it is under eight characters long, which may be any of the following bytes: 18-7 ZCPR3: The Libraries Z3LIB Utilities a character of value space or less an equal sign (=) an underscore (_) a period (.) a colon (:) a comma (,) a less-than sign (<) a greater-than sign (>) Inputs: HL = address of first char Outputs: A=OFFH, NZ, and BODU (disk A = 0) if valid A=0 and Zero Flag Set (Z) if not valid Registers Affected: BC, PSW Side Effects: None Special Error Conditions: None 18.10. Search for File Along Path Routine: PFIND Function: PFIND searches for the file specified in the target FCB along the ZCPR3 command search path. If found, the DU it is located in is returned. Inputs: DE = Address of FCB A=0 if do not search current directory AOO if search of current directory Outputs: BC = DU (disk A = 0) A=0 and Zero Flag Set (Z) if not found A=OFFH and NZ if found Registers Affected: BC, PSW Side Effects: FCB is affected Special Error Conditions: None 18.11. Shell Stack Manipulation 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/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 CP. This command line is copied into the Multiple Command Line Buffer for execution. 18-8 ZCPR3: The Libraries Z3LIB Utilities Routine: SHEMPTY Function: SHEMPTY determines if the shell stack is empty. If it is empty or no shell stack is available, A=0; if not empty, AOO. Inputs: None Outputs: A=0 and Zero Flag Set (Z) if empty or none AOO and NZ if not empty Registers Affected: PSW Side Effects: None Special Error Conditions: None Routine: SHPOLL Function; SHFULL determines if the shell stack is full. If the stack is full or not available, A=0; else, if the stack is not full, AOO. Inputs: None Outputs: A=0 and Zero Flag Set