home *** CD-ROM | disk | FTP | other *** search
- Introduction to the ZCPR3 Environment
- Command Line -- APPCL, CLRCL, GETCL1, GETCL2, PUTCL
- CRT/PRT Data -- GETCRT, GETPRT, PUTCRT, PUTPRT
- External FCB -- GETEFCB
- Environment -- GETENV, GETVID
- FCP Address -- GETFCP
- Filenames -- GETFN1, GETFN2, GETFNX, PUTFNX
- Initialize -- WHRENV, Z3INIT
- System Data -- ZSYSCHK, Z33CHK, GETBDOS, GETCCP, GETECP
- : Introduction 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 environment 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
- completes
- 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
- program thru the ZCPR3 Environment Descriptor. This is a 256-
- byte block of memory containing addresses and other data in a
- precisely-defined format. ZCPR3 utilities may be written with
- an internal 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 specific 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 Dir - size of Named Dir
- - 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 Stk
- - 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 file names - ZCPR3 TERMCAP (Z3TCAP)
-
-
- The purpose of Z3LIB is to provide you with easy access to
- information 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 char 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 stk
- o IFT - invoke the next IF level and make it T
- o IFEND - back up to previous IF level
-
-
- This HLP file describes those Z3LIB routines which provide
- access to the ZCPR3 Environment Descriptor data. All of these
- routines are of the general name:
-
- GETxxxxx
-
- where the mnemonic following the GET prefix alludes to what
- information is being obtained.
-
- :Command Line APPCL CLRCL GETCL1 GETCL2 PUTCL
-
- APPCL - Append Command String to Command Line Buffer
-
- ENTER: 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 Buff (No change to Comnd Line)
- USES : AF
- SIDE EFFECTS: Command Line Buffer is changed
-
- Usage: APPCL appends the specified Null-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.
-
- CLRCL - Clear the Command Line Buffer
-
- ENTER: None
- EXIT : A <> 0, Zero Flag Clear (NZ) if Command Line Cleared
- A = 0 Zero Flag Set (Z) if No Command Line Buffer
- USES : AF
-
- Usage: CLRCL 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.
-
- GETCL1 - Return pointer to Command Line Buffer
-
- ENTER: None
- EXIT : HL = Address of Command Line Buffer (0 if nonexistent)
- A = Size of Buffer
- USES : AF,HL
-
- Usage: This routine is used to locate and return Command Line
- Buffer parameters. The Command Line Buffer is structured as:
-
- CMDLIN: DEFW Address of next character to process
- DEFB Size of Buffer in Bytes
- DEFB <dummy used for BDOS READLN function>
- DEFB ....(chars in command line)
- DEFB 0 ; End of Comnd String
-
- GETCL2 - Return Next Command Info from Command Line Buffer
-
- ENTER: None
- EXIT : HL = Addr of Next Command. (0 if No Comnd Line Buff)
- A = First char of Command, Zero Clear (NZ) if valid
- A = 0, Zero Flag Set (Z) if No characters in line
- USES : AF,HL
-
- Usage: This routine is used in applications where you need to
- directly access characters in the next command stored in the
- Command Line Buffer.
-
- PUTCL - Store Command line at beginning of Command Line Buff
-
- ENTER: HL = Address of Null-Terminated Command Line
- EXIT : A <> 0, Zero Flag Clear (NZ) if Ok
- A = 0 Zero Set (Z) if Overflow (No Buffer change)
- USES : AF
-
- Usage: This routine adds a Command Line as a prefix in the
- ZCPR3 Command 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 post-
- fixed with a semicolon so continuation is enabled.
-
- :CRT/PRT Data GETCRT GETPRT PUTCRT PUTPRT
-
- GETCRT - Return Address of CRT data record from ENV
-
- ENTER: None
- EXIT : HL = Address of CRT Record
- USES : HL
-
- Usage: This routine is used to determine the parameters of
- the installed terminal. 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.
-
- GETPRT - Return the address of the Printer Data Record
-
- ENTER: None
- EXIT : HL = Address of Printer Data Record
- USES : HL
-
- Usage: This routine provides data on some of the printer
- characteristics 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 ; Form Feed 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 Form
- Feed or count Line Feed chars to advance to the next page.
-
- PUTCRT - Stores Terminal select byte (* No real function *)
-
- ENTER: 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)
- USES : AF
-
- Usage: This routine performs no actual function in the
- Extended Environment which supports only one defined CRT
- Data Block. For compatibility, it senses the Select
- value and simply returns status based on it.
-
- PUTPRT - Store Printer Selection byte (0..1) in Environment
-
- ENTER: 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)
- USES : AF
-
- Usage: PUTPRT 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.
-
- :GETEFCB - Return the address of the ZCPR3 External FCB
-
- ENTER: None
- EXIT : HL = Address of External FCB
- A <> 0, Zero Flag Clear (NZ) if Ok
- A = 0, Zero Flag Set (Z) if Not Found
- USES : 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 programs like 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 GETENV GETVID
-
- GETENV - Return address of the ZCPR3 Environment Descriptor
-
- ENTER: None
- EXIT : HL = Address of Encironment Descriptor
- USES : HL
-
- Usage: This function is useful 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.
-
- GETVID - Return Address of the ZCPR3 TCAP (Z3TCAP)
-
- ENTER: 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
- USES : AF,HL
-
- Usage: This function is useful for those programs which need
- to modify the ZCPR3 TCAP Buffer and those programs which need
- to determine if the TCAP is loaded. It may be desirable to
- call this routine before a screen-oriented utility is
- executed to insure that a TCAP is available.
-
- :GETFCP - Return Address of the Flow Command Package buffer
-
- ENTER: None
- EXIT : HL = Address of FCB Buffer
- A = # of 128-byte FCP Blocks, Zero Clear (NZ) if Ok
- A = 0, Zero Flag Set (Z) if No buffer
- USES : AF,HL
-
- Usage: This routine is used to simply return the FCB parms
- from the Environment Descriptor. The starting address and
- size of the FCP Buffer in terms of 128-byte blocks are
- returned. 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 GETFN1 GETFN2 GETFNX PUTFNX
-
- GETFN1 - Return Address of Shell Variable File Name
- GETFN2 - Return Address of 1st Filename of System File Names
-
- ENTER: None
- EXIT : HL = Address of the respective 11-char Filename entry
- USES : HL
-
- Usage: These routines return the address in HL of the shell
- variable filename (GETFN1) and the first filename of the four
- System File Names (GETFN2) in the ZCPR3 Environment
- Descriptor. Each filename entry is 11 bytes long, matching
- the filename and filetype fields of the CP/M FCB.
-
- These names are used to pass names of special files to
- programs for later use. Their exact definition is not
- presented and left to you. One application of these is
- to allow GETFN1 to return the name of the master HLP file
- (HELP.HLP) to be used as an index into the Help System.
-
- GETFNX - Return Address of nth Filename of System File Names
-
- ENTER: A = File Name Number (1..4) in ENV File Name Buffer
- EXIT : HL = Addr of first byte of indicated file (11 chars)
- A <> 0, Zero Flag Clear (NZ) if Ok
- A = 0, Zero Flag Set (Z) if Input Not in 1..4
- USES : AF,HL
-
- Usage: GETFNX returns the address of the nth file name in the
- ZCPR3 Environment Descriptor. There are four system files,
- numbered 1 to 4, and they are structured like the FN.FT
- fields of an FCB (11 bytes each).
-
- On input, A=1..4 to indicate the file name. On output, HL
- points to the first byte. A validity check is done on the
- value of A which MUST be 1..4.
-
- PUTFNX - Set nth (1..4) File Name in Environment Descriptor
-
- ENTER: A = File Name Number (1..4)
- HL = Address of FCB+1 of New File Name value
- EXIT : A <> 0, Zero Flag Clear (NZ) if Ok
- A = 0, Zero Flag Set (Z) if A not in 1..4
- USES : AF
-
- Usage: PUTFNX sets the nth (1..4) file name in the ZCPR3
- Environment 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 file name.
-
- :Initialize WHRENV Z3INIT
-
- WHRENV - Return installed ZCPR3 Environment Descriptor Addr
-
- ENTER: HL = Candidate address of Environment Descriptor
- EXIT : HL = Points to start addr of ENV (0 if Not Found)
- A <> 0, Zero Flag Clear (NZ) if ENV Validated
- A = 0, Zero Flag Set (Z) if Not Found
- USES : AF,BC,DE,HL
-
- Usage: This routine 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)
-
- Z3INIT - Set Global Bufr to arbitrary address for ZCPR3 ENV
-
- ENTER: HL = Address of ZCPR3 Environment Descriptor
- EXIT : None
- USES : None
-
- Usage: This routine is used to set 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!
-
- :ZSYSCHK - Validate ZCPR3 Environment Descriptor Address (*)
-
- ENTER: HL = Points to candidate Z3 Environment
- EXIT : A = 0, Zero Set (Z) if valid Environment
- A <> 0, Zero Clear (NZ) if environment NOT valid
- USES : AF
-
- Usage: This routine checks various parameters in an Environment
- Descriptor predicated on the specified address to see if it is
- valid. It will print a message if the Environment is invalid.
- NOTE: For best results on ZCPR 3.3 or later, pass the value
- in HL when program started. This will NOT work on ZCPR
- 3.0, but will detect BG 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
-
- Z33CHK - Check for presence of ZCPR 3.3 or later (*)
-
- ENTER: 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
- USES : AF
-
- Usage: This routine 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 specific 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
-
- GETBDOS - Return Basic Disk Operating System Start Address (*)
-
- ENTER: None
- EXIT : HL = Calculated or Loaded BDOS starting address
- USES : HL
-
- Usage: This routine will return the starting address of the
- Basic Disk Operating System (BDOS) from an Extended ENV if
- present, else it will calculate the starting address from the
- BIOS Warm Boot vector assuming 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 & 7 or
- GZMTOP to find the highest usable memory location depending
- on whether or not the CCP is to be retained.
-
- GETCCP - Return Command Processor Starting Address (*)
-
- ENTER: None
- EXIT : HL = Calculated or Loaded CCP starting address
- USES : HL
-
- Usage: This routine will return the starting address of the
- Command Processor for use in calculating addresses of entry
- points, and in locating ZCPR 3 configuration bytes. This
- routine first attempts to locate the CCP address from an
- Extended ENV if present, otherwise it will calculate the
- starting address from the BIOS Warm Boot vector assuming a
- 3.5k BDOS and a 2k CCP.
-
- GETECP - Return Address of Extended Command Processor Name (*)
-
- ENTER: None
- EXIT : HL = Address of ECP Name
- USES : HL
- REQUIREMENTS: The ZCPR 3.3 or later Command Processor
-
- Usage: This routine is used to locate the name of the ZCPR
- Version 3.3 or later Extended Command Processor.
- NOTE: The Command Processor must NOT have been overwritten.