CP/M

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

/ CP/M / CPM_CDROM.iso / zsys / znode-12 / s / z3help13.lbr / Z3LIB2.HZP / Z3LIB2.HLP

Wrap

Text File | 1993-06-12 | 21.0 KB | 568 lines

Introducton to IOP Concepts IOP - GETION, GETIOP, GETIOS, IOMATCH, PUTIOD IOP Recording - IORCOFF, IORCON, IORLOFF, IORLON DU/Max DU - GETDUOK, GETMDISK, GETMUSER, PUTs, HIGHUSER DU from FCB - GCMDDU Messages - GETMSG, GETSHM, PUTSHM Named Dir - ADDNDR, DIRNDR, DUNDR, GETNDR, SUBNDR Path - GETPATH Processor Spd - GETSPEED, PUTSPEED Quiet Flag - GETQUIET, PUTQUIET RCP Address - GETRCP Shell Stack - GETSH1, GETSH2 Wheel Byte - GETWHL, PUTWHL : Introduction to IOP Concepts This set of routines provide access to the system I/O Package (IOP). The devices in an IOP are identified by a logical ID (referring to the generic CON, RDR, PUN, and LST devices) and a physical ID (referring 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 info on the physical IDs. 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 :IOP Address GETION - GETIOP - GETIOS - IOMATCH - PUTIOD GETION - Return Address of Name for specified device ENTER: 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 USES : AF,HL Usage: GETION (Get IO Name) 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. GETIOP - Return address and size of IOP Buffer Definition ENTER: None EXIT : HL = Address of IOP Buffer A = # of 128-byte blocks in Buffer, Zero Clear (NZ) A = 0, Zero Flag Set (Z) if No Buffer USES : AF,HL Usage: This routine simply 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 GETIOS - Return pointer to I/O Package Status Table ENTER: 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 USES : AF,HL Usage: This routine 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 IOMATCH - Search for Physical Device Name for Logical ID ENTER: 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 USES : AF,C Usage: This routine searches for the name of a physical device associated with a particular logical ID. This name is a Null-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 PUTIOD - Select the IOP device from specified Logical ID ENTER: 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) USES : AF Usage: This routine is used to select an IOP device from a set of Logical and Physical IDs. 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. :IOP Recording IORCOFF - IORCON - IORLOFF - IORLON IORCON - Turn Console I/O Recording On in Current IOP IORCOFF - Turn Console I/O Recording Off in Current IOP IORLON - Turn List I/O Recording On in Current IOP IORLOFF - Turn List I/O Recording Off in Current IOP ENTER: HL = Addr 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 USES : AF Usage: These routines enable or disable functions specified above. 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. :DU GETDUOK, GETMDISK, GETMUSER, PUTDUOK, PUTMDISK, PUTMUSER GETDUOK - Return the value of the DUOK flag ENTER: None EXIT : A <> 0, Zero Flag Clear (NZ) if DU: use Ok A = 0, Zero Flag Set (Z) if DU: use NOT Allowed USES : AF Usage: Return the DUOK flag value which tells the program 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 access ANY Disk/User area. This flag (DUOK) tells the utility if it is OK for the user to employ the DU: prefix. GETMDISK - Return the Maximum allowable Disk Number ENTER: None EXIT : A = Maximum Disk Number (A = 1,..P = 16) USES : AF Usage: This routine is used to obtain 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 and 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 disk or user area. GETMUSER - Return the Maximum allowable User Area Number ENTER: None EXIT : A = Maximum allowable User Ares (0..31) USES : AF Usage: This routine 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 Disks C and D and 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 Disk or User Area. PUTDUOK - Set the DU OK byte to specified value ENTER: A = DUOK Value (0 = DU Not Ok, 0FFH = DU is Ok) EXIT : None USES : None Usage: This routine sets the DU OK 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 specifi- cation using the DU: form is permitted. PUTMDISK - Set the Maximum Allowable Disk in the ENV ENTER: A = Maximum Allowable Disk Number (A = 1,..P = 16) EXIT : None USES : None Usage: This routine sets the maximum allowable disk in the Environment Descriptor. Valid Disk numbers range from 1 for Drive A, to 16 for Drive P. PUTMUSER - Set the Maximum Allowable User Number (0..31) ENTER: A = Maximum Allowable User Number (0..31) EXIT : None USES : None Usage: This routine sets the Maximum allowable User Area in the Environment Descriptor. Valid User numbers range from 0 through 31. HIGHUSER - Return flag showing Users > 15 Support (*) ENTER: None EXIT : F - Zero Clear (NZ) if Users > 15 supported Zero Set (Z) if No ZCPR 3.3 or NO users > 15 A - Undefined USES : AF REQUIREMENTS: Command Processor must be ZCPR 3.3 or later Usage: This routine returns a flag indicating whether User Numbers greater than 15 are supported. This definition is obtained from the ZCPR 3.3 or later Command Processor. NOTE: The Command Processor must NOT have been overwritten. :GCMDDU - Return Drive and User Number in External FCB (*) ENTER: None EXIT : BC = DU. B=Drive (A=0,..P=15), C=User (0..31) USES : BC REQUIREMENTS: FCB MUST have been parsed by ZCPR 3.3 or later which places User # in FCB+13, Drive in FCB+14. Usage: This routine returns the Drive and User for the File specified in the ZCPR 3.3 and later External FCB. It is often used to determine where the file was actually found (Shell, Path, etc) in order to log into, or save that location. :Messages GETMSG - GETSHM - PUTSHM GETMSG - Return the address of the ZCPR3 Message Buffer ENTER: 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 USES : AF,HL Usage: This routine is used in conjunction with other message routines for synchronization between programs, and status info. See Z3LIB information sections on ZCPR3 Messages. GETSHM - Get value of Shell Message for Specified Msg Number ENTER: B = Message Number (0, 1, 2) EXIT : A = Message Value (Zero Flag Set Accordingly) USES : AF Usage: This routine returns the value of the shell message whose number is specified. There are three shell messages, so 0 <= B <= 2 (you must be sure a valid value is presented). PUTSHM - Set the value of specified Shell Message Number ENTER: A = Message Value B = Message Number (0,1,2) EXIT : None USES : None Usage: This routine is used to place a message into one of the three message positions in the Shell area. :Named Dir ADDNDR - DIRNDR - DUNDR - GETNDR - SUBNDR ADDNDR - Add Directory Name to the Named Directory Buffer ENTER: A = Password Flag (0-Set to Spaces, <>0-Set from DE) DE = Addr of Password buffer if A <> 0 (8-chars) HL = Addr of FCB containing DU and Disk Name EXIT : A <> 0, Zero Flag Clear (NZ) if Name add successful A = 0, Zero Set (Z) if No Buffer, or Buff Full USES : AF Usage: This routine adds a Named Directory to the 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 addition. No check is made for duplicate names or duplicate DU references. DIRNDR - Find Named Directory Buffer entry for specified Name ENTER: HL = Addr of 8-char buffer with Name to Find EXIT : HL = Addr of NDR Entry, if found BC = DU (Disk in B - A=1,..P=16) if found A <> 0, Zero Flag Clear (NZ) if Name Fount A = 0, Zero Flag Set (Z) if No NDR or Not Found USES : AF,BC,HL Usage: This routine is used to recover 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 (A=1,..P=16), and the User in reg C (0..31). The HL register pair will point to the NDR entry which is structured around 18-byte entries as: DEFB 1 ; Disk (A=1,..P=16) DEFB 15 ; User (0 to 31) DEFB 'ROOT ' ; Name, 8-chars, space filled DEFB 'MYPASS ' ; Password, 8-char, space fill DUNDR - Find Named Directory Entry from Drive/User Spec ENTER: BC = Drive/User in DU: to locate (Disk A=1,..P=16) EXIT : HL = Address of NDR Entry if Found A <> 0, Zero Flag Clear (NZ)if Found A = 0 Zero Flag Set if No NDR Buff or Not Found USES : AF,HL Usage: This routine is used to locate a Named Directory from Drive/User specification in DU form where the Drive is in register B (drive A=1,..P=16), and User is in reg C (0..31). If found, the address of the 18-byte Named Directory Buffer entry is returned. Entries are structured as: DEFB 2 ; Disk (A=1,..P=16) DEFB 0 ; User (0..31) DEFB 'HELP ' ; Name, 8-char, space filled DEFB ' ' ; Password, 8-char, space fill GETNDR - Return Named Directory Buffer parms from ENV ENTER: 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 USES : AF,HL Usage: This routine returns the address and size of the Named Directory Buffer as defined in the Environment 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 SUBNDR - Remove Specified Named Directory entry from NDR Buffer ENTER: HL = Address of 8-char Buffer containg Name EXIT : A <> 0, Zero Flag Clear (NZ) if removal successful A = 0, Zero Flag Set if No NDR or Name Not Found USES : AF Usage: This routine 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 chars. The name is capitalized before it is checked against possible entries. If located, the entry is removed, and the remaining buffer is repacked. :GETPATH - Return Addr of the Command Search Path from the ENV ENTER: None EXIT : HL = Address of ZCPR3 Search Path from Env Descriptor A = Number of Elements, Zero Flag Clear (NZ) if Ok A = 0, Zero Set (Z) if No Path defined in ENV USES : 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 GETSPEED - PUTSPEED GETSPEED - Return Processor Speed in MHz from ENV ENTER: None EXIT : A = Processor speed in MegaHertz USES : AF Usage: This routine is most often used in Software timing loops to permit a greater amount of portability in software. The returned value in to the nearest MegaHertz, so 1 = 1 MHz, 4 = 4 MHz, etc. PUTSPEED - Set Processor Speed in ENV to Specified value ENTER: A = Processor Speed in MHz EXIT : None USES : None Usage: This routine sets the Processor Speed as defined in the Environment Descriptor to the specified value in Mega- Hertz where 1 = 1 MHz, 4 = 4 MHz. :Quiet Flag GETQUIET - PUTQUIET GETQUIET - Return value of QUIET Flag ENTER: None EXIT : A = Value of Quiet Flag from ENV. Zero Flag Set accordingly (0=Z=Not Quiet, 0FFH=NZ=Quiet) USES : AF Usage: This routine is often used in programs to suppress unneeded/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. PUTQUIET - Set the value of the Quiet Flag ENTER: A = Quiet Glag value (0=Not Quiet, 0FFH=Quiet) EXIT : None USES : None Usage: This routine sets the Quiet Flag to the specified value. While 0FFH is preferred to indicate Quiet operation, any Non-Zero value will suffice. :GETRCP - Return Address and Size of RCP defined in ENV ENTER: None EXIT : HL = Address of RCP Buffer A = Size of Bufr in 12-byte blocks, Zero Clear (NZ) A = 0, Zero Flag Set (Z) if No RCP Defined USES : AF,HL Usage: This routine simply returns the Resident Command Package buffer definitions contained in the Environment Descriptor. Your program must check for a valid package if necessary by examining the first byte of the buffer. 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 GETSH1 - GETSH2 GETSH1 - Return Defined Shell Stack Parameters from ENV ENTER: 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 USES : AF,B,HL Usage: This routine simply 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. GETSH2 - Return Defined Shell Stack Parameters from ENV ENTER: 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 USES : 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 manipulated than GETSH1 covered above. See SHPUSH and SHPOP routines for details on other facilities for dealing with Shell Stacks provided by Z3LIB. :Wheel Byte GETWHL - PUTWHL GETWHL - Return the Wheel Byte value from the ENV ENTER: None EXIT : A = Wheel Byte, Flags set accordingly (0, Z, Not Wheel; 0FFH, NZ, IS Wheel) USES : AF Usage: This routine is used to restrict users from accessing parts of programs, or affecting program flow. For example, you may not wish remote users to change the Path definition. 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 granting Wheel priveleges, any non-zero value currently suffices. PUTWHL - Set the value of the Wheel Byte in the ENV ENTER: A = Wheel Byte Value to set (0=No Wheel, 0FFH=Wheel) EXIT : None USES : None Usage: This routine is used to set the Wheel Byte to ON (0FFH) or OFF (0) thereby granting or denying Wheel priveleges to executing programs.