 Introducton to IOP Concepts				29 Aug 92
 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/0, SUBNDR, IDXNDR
 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.

::Z3LIB2A.HLP
: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.
