ZCPR3 Flow Control - Intro
 End IF                 - IFEND
 Raise IF               - IFT, IFF
 Test IF                - IFTEST
 Toggle IF              - IFELSE
ZEX Access and Control - Intro
 ZEX Data               - GETZFC, GETZNC, GETZRUN, PUTZNC, PUTZRUN
 ZEX Status & Control   - GETZEX, PUTZEX, HALTZEX, STOPZEX, STRTZEX
SUBMIT and XSUB Control - Intro
 SUBMIT Data & Control  - SUBON, HALTSUB, GETSRUN, GETSFCB
 XSUB Data & Control    - STOPXSUB, GXSUB, PXSUB
:           Introduction to ZCPR3 Flow Control 

Basic Defintion of Flow Control:

All command sequences issued under ZCPR3 can be thought to
execute in a TRUE flow control state.  That is, whenever a
command is executed under ZCPR3, the state of flow control is
TRUE.  If the state of flow control is FALSE then no commands
except flow commands will be executed until the state of flow
control becomes TRUE.

Background:

When ZCPR3 first comes up, the state of flow control is always
TRUE.  Any command issued will be executed.  If a Flow Command
Package is installed which supports the IF/ELSE/FI (End IF)
commands, then the state of flow control can be dynamically
changed by user commands.  For example, the following terminal
session illustrates:


SCR>; any command will execute now
SCR>era *.bak
No Files
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>


Hence, 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 you to be nested into IFs up to eight (8) levels
deep.  That is, the structure of your command sequences can
take the following form which can be nested to 8 levels of IFs:


<set of commands>
IF T
     <set of commands>
     IF T
          <set of commands>
          IF T
               <set of commands>
          FI
          <set of commands>
     ELSE
          <set of non-executed commands>
          IF T
               <set of non-executed commands>
          FI
     FI
ELSE
     <set of non-executed commands>
FI


Command structures like those presented above are now possible
under ZCPR3.  In Essence, 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 you with a simple interface to control the Flow Control
within (and outside) your program.  You can issue commands to:

    o  Enter the next IF level in TRUE or FALSE condition,
    o  Toggle the state of the current IF level,
    o  Drop down to the previous IF level,
    o  Determine the current IF level number,
    o  Or multiples of the above

:IFEND - Drop to previous IF level

  ENTER: None
  EXIT : A <> 0, Zero Flag Clear (NZ) if Successful
             A = 0, Zero Flag Set (Z) if No IF level
  USES : AF

 Usage:  This routine is used to terminate the current IF level
  and drop to the previous IF level, if the program is within
  one or more IFs.  For a transient program, there is either No
  IF level, or there is a TRUE flow control state (all
  preceeding IFs are TRUE).

:IFT - Raise IF level and set it to TRUE
 IFF - Raise IF level and set it to FALSE

  ENTER: None
  EXIT : A <> 0, Zero Flag Clear (NZ) if IF level OK
             A = 0, Zero Set (Z) on IF level overflow
  USES : AF

 Usage:  These routines are used to set Flow Control States and
  raise the IF level.  The Flow Control State can support up to
  eight (8) levels of IFs.  IFT and IFF return error codes for
  overflow conditions which should be sensed to insure the
  integrity of the program.

:IFTEST - Determine the current IF level

  ENTER: None
  EXIT : A = Number of current IF level, Zero Flag set
             accordingly
  USES : AF

 Usage:  This routine is sed determine the current IF level.
  The returned value ranges from 0 to 8,  indicating the
  current level.  If A=0, there is no current IF.  The Zero
  Flag is set accordingly to allow rapid testing.

Example:
	EXT	IFTEST		; Declare the routine
	...			; ..preceeding code
	CALL	IFTEST		; Get current IF level
	JR	Z,NOIF		; ..jump if None
	CP	8		; Is it at Max level?
	JR	Z,ATMAX		; ..jump if at Max IF level
	...			; Else Carry shows empty levs

:IFELSE - Toggle TRUE/FALSE state of current IF level

  ENTER: None
  EXIT : A <> 0, Zero Flag Clear (NZ) if Successful
             A = 0, Zero Flag Set (Z) if No current IF
  USES : AF

 Usage:  This routine is used to toggle the current state of
  the current IF level.  If called an even number of times, the
  state is effectively unchanged.

:          Introduction to ZEX Access and Control 

The ZEX Command File Facility (under ZCPR3 only!) 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.  You 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  - Set the ZEX Control Message
	PUTZNC  - Set the next character to be returned
	PUTZRUN - Set ZEX Running Flag

	STOPZEX - Suspend ZEX Execution
	STRTZEX - Resume ZEX Execution from a STOPZEX

:ZEX Data     GETZFC, GETZNC, GETZRUN, PUTZNC, PUTZRUN 

GETZFC - Return address of first character in ZEX Buffer

  ENTER: None
  EXIT : HL = Address of first char in ZEX Script Buffer
          A = Char at that address, Carry Clear (NC) if data
              Carry Flag Set (C) if NO text data in Buffer
  USES : AF,HL

 Usage:  This routine may be used to examine the script data
  for a running ZEX Script sequence.

GETZNC - Get next character ZEX will process

  ENTER: None
  EXIT : HL = Addr of Next Character in ZEX Text Buffer
          A = Next Char to be returned, Carry Clear if valid
              Carry Flag Set (C) if No Text Data remains
  USES : AF,HL

 Usage:  This routine may be used to effect changes to a
  running ZEX program by examining the next character that
  will be returned.

GETZRUN - Determine Run Status of ZEX from Run Message Byte

  ENTER: None
  EXIT : A = Run Message, Zero Set accordingly (0=Not running)
             Carry Flag Set (C) if No Message available
  USES : AF

 Usage:  This routine returns the ZEX Run Message Byte and sets
  flags indicating status as:
	Zero  - Set (Z) if ZEX Not Running, else Clear (NZ)
	Carry - Set (C) if No Message, Else Clear (NC)

PUTZNC - Set Address of next ZEX character (GOTO)

  ENTER: HL = Address of next character ZEX will return
  EXIT :  Carry Flag Clear (NC) if operation Successful
              Carry Set (C) if ZEX Buffers NOT available
  USES : AF

 Usage:  This routine sets the address of the next character
  which will be read by ZEX.  Using this routine provides a
  GOTO function for ZEX control.

PUTZRUN - Set value of ZEX Running Message Byte

  ENTER: A = Value of ZEX Running Message Byte
  EXIT :  Carry Flag Set (C) if No Message Buffers
  USES : AF

 Usage:  This routine sets the ZEX Running Message byte to
  a user-supplies value.  Its purpose is to allow running
  programs to disable or suspend ZEX processing.  Set to Zero
  to Stop ZEX processing.

:ZEX Status & Control  GETZEX, PUTZEX, HALTZEX, STOPZEX, STRTZEX 

GETZEX - Return ZEX Control Message Byte

  ENTER: None
  EXIT : A = ZEX Control Message (0,1,2), Zero set accordingly
  USES : AF

 Usage:  This routine is used to allow programs to determine
  the current state of ZEX.  The Control Message Byte can
  have one of the following three values:

   0 - "normal" - ZEX is running and intercepting BIOS calls
   1 - "ZCPR3 Prompt" - ZEX is allowed to run and intercept
        BIOS calls but ZEX thinks that it is providing input
        to the ZCPR3 Command Processor directly (ZEX is not
        providing input to any program)
   2 - "ZEX suspended" - ZEX is not intercepting BIOS calls
        and user input is allowed

  The 1 Code should never be seen by any program since it is
  set by ZCPR3 and cleared to 0 after ZEX has completed the
  Command Line input.

  Any ZEX control message is reset upon execution of ZCPR3 to 0
  when ZCPR3 is entered and then to 1 when the ZCPR3 prompt
  appears (ZCPR3 input).  When ZCPR3 completes its input, it
  resets the ZEX Control Message to 0.

PUTZEX - Set ZEX Control Message Byte (Change ZEX State)

  ENTER: A = ZEX Control Message Byte (0,1,2)
  EXIT : None
  USES : None

 Usage:  This routine allows a program to set the state that
  ZEX is in.  This Control Message byte must only be set to one
  of these values:

   0 - "normal" - ZEX is running and intercepting BIOS calls
   1 - "ZCPR3 Prompt" - ZEX is allowed to run and intercept
	BIOS calls but ZEX thinks that it is providing input to
	the ZCPR3 command Processor directly (ZEX is not
	providing input to any program)
   2 - "ZEX suspended" - ZEX is not intercepting BIOS calls and
	user input is allowed


  The 1 code may be set by any program if it wants ZEX to
  "think" that it is providing input to ZCPR3.  If ZEX was
  previously suspended, it advances to the beginning of the
  next line and resumes when it sees this code.

  Any ZEX control message is reset upon execution of ZCPR3 to
  0 when ZCPR3 is entered and then to 1 when the ZCPR3 prompt
  appears (ZCPR3 input).  When ZCPR3 completes its input, it
  resets the ZEX control message to 0.

HALTZEX - Halt ZEX completely by setting ZEX End-of-File

  ENTER: None
  EXIT : A <> 0, Zero Flag Clear (NZ) if ZEX is Halted
             A = 0, Zero Flag Set (Z) if ZEX NOT Running
  USES : AF

 Usage:  This routine terminates execution of ZEX completely.
  Other routines provide temporary execution control such as
  STOPZEX (suspend execution), and STRTZEX (resume execution),
  but HALTZEX causes ZEX to terminate itself completely by
  setting the next character ZEX will process to the termina-
  tion character of 0FFH.

STOPZEX - Temporarily Suspend ZEX Script processing

  ENTER: None
  EXIT : None
  USES : None
  SIDE EFFECTS: ZEX Control Message Byte is set to 2

 Usage:  This routine is used to temporarily stop ZEX from
  intercepting BIOS calls and allow the user to input
  characters.  This is a shorthand to placing the 2 control
  code into the ZEX Control Message Byte.

STRTZEX - Start processing from ZEX Script

  ENTER: None
  EXIT : None
  USES : None

 Usage:  Allow ZEX to intercept BIOS calls and don't allow
  user to input characters.  This is a shorthand to placing
  the 0 control code  into the ZEX Control Message Byte.

:           Introduction to SUBMIT/XSUB Processing 

In enhancing the ZCPR 3 Command Processors and defining the
Extended Environment, provisions were also made to control
program flow from SUBMIT and XSUB utilities in the same manner
as the memory-based ZEX processing covered elsewhere.

SUBMIT processing is determined via flags and other data within
ZCPR Version 3.3 and later.  Routines supporting its features
must have access to the Command Processor.  It is your respon-
sibility to insure that the Processor is not overwritten.

The combination of SUBMIT with an XSUB-like utility form the
basis of a disk-based corollary to ZEX for uses where a large
TPA space, or very large scripts must be processed.  "Hooks"
are therefore provided with these routines to enable such a
facility.

:SUBON - Determine whether SUBMIT processing is enabled        (*)

  ENTER: None
  EXIT :  Zero Clear (NZ) if SUBMIT Is enabled
	  Zero Set (Z) if No ZCPR 3.3 or SUBMIT Disabled
	  A - Destroyed
  USES : AF
  REQUIREMENTS: The ZCPR 3.3 Command Processor or later

 Usage:  This routine is used to determine whether the SUBMIT
  facility within ZCPR version 3.3 or later is enabled.  An
  error status is returned if SUBMIT is disabled, or the
  Command Processor is not ZCPR 3.3 or later.
  NOTE: The Command Processor must NOT have been overwritten.

HALTSUB - Terminate an executing SUBMIT job                   (*)

  ENTER: None
  EXIT : None.  The $$$.SUB is deleted
  USES : None

 Usage:  This routine stops an executing SUBMIT job by deleting
  the $$$.SUB file addressed in the ZCPR 3.3 Submit FCB.

GETSRUN - Return flag indicating SUBMIT job status            (*)

  ENTER: None
  EXIT : A <> 0, Zero Clear (NZ) if SUBMIT job IS running
             A = 0, Zero Set (Z) if SUBMIT is NOT running
  USES : AF

 Usage:  This function is used to determine whether we are
  currently running within a SUBMIT job.  This is sometimes
  necessary information to determine possible actions within
  a program.

GETSFCB - Return the ZCPR 3.3 or later Submit FCB address.    (*)

  ENTER: None
  EXIT : DE = Address of SUBMIT FCB (Undefined if error)
          A <> 0, Zero Flag Clear (NZ) if Ok
              A = 0, Zero Set (Z) if NO SUBMIT or ZCPR 3.3
  USES : AF,DE
  REQUIREMENTS: ZCPR 3.3 or later Command Processor

 Usage:  This routine returns the SUBMIT FCB address from ZCPR
  Version 3.3 or later FCB.  An Error status is returned if
  SUBMIT is not enabled or the Command Processor is not of the
  right type.
  NOTE: The Command Processor must NOT have been overwritten

:STOPXSUB - Reset XSUB Input Redirection Flag                  (*)

  ENTER: None
  EXIT : None.  XSUB is Halted
  USES : None

 Usage:  This routine is used to Stop XSUB program flow for
  local console input.  This is accomplished by resetting a
  flag in the Message Buffer.

GXSUB - Return the value of the XSUB redirection flag        (*)

  ENTER: None
  EXIT :  A = Value of the XSUB redirection flag
  USES : AF

 Usage:  This routine is used to determine if input to the
  running program is coming from an XSUB utility.  This is
  useful in Error conditions where the normal flow of commands
  and data must be altered for operator input.

PXSUB - Set the XSUB Input Redirection Flag                  (*)

  ENTER: A = value to set XSUB input redirection flag
  EXIT : None.  The value is set
  USES : None

 Usage:  This routine is used to activate XSUB processing from
  a Command Script or SUB file.  By setting the XSUB Redirec-
  tion Flag, program flow can be dynamically altered.  Until a
  better definition is developed, it is suggested that the
  Command bytes used for ZEX be applied (See GETZEX).
