ftp.barnyard.co.uk

home *** CD-ROM | disk | FTP | other *** search

/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / BEEHIVE / ZSUS / Z3HELP-6.LBR / ZA.LBR / Z3LIB1.HZP / Z3LIB1.HLP

Wrap

Text File | 2000-06-30 | 19KB | 478 lines

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.