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 / Z3LIB3.HZP / Z3LIB3.HLP
Text File  |  2000-06-30  |  15KB  |  442 lines
  1. ZCPR3 Flow Control - Intro
  2.  End IF                 - IFEND
  3.  Raise IF               - IFT, IFF
  4.  Test IF                - IFTEST
  5.  Toggle IF              - IFELSE
  6. ZEX Access and Control - Intro
  7.  ZEX Data               - GETZFC, GETZNC, GETZRUN, PUTZNC, PUTZRUN
  8.  ZEX Status & Control   - GETZEX, PUTZEX, HALTZEX, STOPZEX, STRTZEX
  9. SUBMIT and XSUB Control - Intro
  10.  SUBMIT Data & Control  - SUBON, HALTSUB, GETSRUN, GETSFCB
  11.  XSUB Data & Control    - STOPXSUB, GXSUB, PXSUB
  12. :           Introduction to ZCPR3 Flow Control 
  13.  
  14. Basic Defintion of Flow Control:
  15.  
  16. All command sequences issued under ZCPR3 can be thought to
  17. execute in a TRUE flow control state.  That is, whenever a
  18. command is executed under ZCPR3, the state of flow control is
  19. TRUE.  If the state of flow control is FALSE then no commands
  20. except flow commands will be executed until the state of flow
  21. control becomes TRUE.
  22.  
  23. Background:
  24.  
  25. When ZCPR3 first comes up, the state of flow control is always
  26. TRUE.  Any command issued will be executed.  If a Flow Command
  27. Package is installed which supports the IF/ELSE/FI (End IF)
  28. commands, then the state of flow control can be dynamically
  29. changed by user commands.  For example, the following terminal
  30. session illustrates:
  31.  
  32.  
  33. SCR>; any command will execute now
  34. SCR>era *.bak
  35. No Files
  36. SCR>dir
  37. MYFILE  .TXT  |  OBJECT  .BIN
  38. SCR>; we can set a flow control state to be false
  39. SCR>IF F
  40.  IF F
  41. SCR>; no command will execute now
  42. SCR>dir
  43. SCR>else
  44.  IF T
  45. SCR>dir
  46. MYFILE  .TXT  |  OBJECT  .BIN
  47. SCR>FI
  48.  No IF
  49. SCR>
  50.  
  51.  
  52. Hence, when any command is executed, before the execution
  53. actually begins, ZCPR3 will look to see if the state of the
  54. flow control is TRUE.  Such is the case when we are not within
  55. an IF condition or when we are within one or more IF
  56. conditions, all of which are TRUE.
  57.  
  58. ZCPR3 allows you to be nested into IFs up to eight (8) levels
  59. deep.  That is, the structure of your command sequences can
  60. take the following form which can be nested to 8 levels of IFs:
  61.  
  62.  
  63. <set of commands>
  64. IF T
  65.      <set of commands>
  66.      IF T
  67.           <set of commands>
  68.           IF T
  69.                <set of commands>
  70.           FI
  71.           <set of commands>
  72.      ELSE
  73.           <set of non-executed commands>
  74.           IF T
  75.                <set of non-executed commands>
  76.           FI
  77.      FI
  78. ELSE
  79.      <set of non-executed commands>
  80. FI
  81.  
  82.  
  83. Command structures like those presented above are now possible
  84. under ZCPR3.  In Essence, ZCPR3 commands can now take the form
  85. of a programming language in their own right.
  86.  
  87. The set of routines available in this part of Z3LIB are used to
  88. provide you with a simple interface to control the Flow Control
  89. within (and outside) your program.  You can issue commands to:
  90.  
  91.     o  Enter the next IF level in TRUE or FALSE condition,
  92.     o  Toggle the state of the current IF level,
  93.     o  Drop down to the previous IF level,
  94.     o  Determine the current IF level number,
  95.     o  Or multiples of the above
  96.  
  97. :IFEND - Drop to previous IF level
  98.  
  99.   ENTER: None
  100.   EXIT : A <> 0, Zero Flag Clear (NZ) if Successful
  101.              A = 0, Zero Flag Set (Z) if No IF level
  102.   USES : AF
  103.  
  104.  Usage:  This routine is used to terminate the current IF level
  105.   and drop to the previous IF level, if the program is within
  106.   one or more IFs.  For a transient program, there is either No
  107.   IF level, or there is a TRUE flow control state (all
  108.   preceeding IFs are TRUE).
  109.  
  110. :IFT - Raise IF level and set it to TRUE
  111.  IFF - Raise IF level and set it to FALSE
  112.  
  113.   ENTER: None
  114.   EXIT : A <> 0, Zero Flag Clear (NZ) if IF level OK
  115.              A = 0, Zero Set (Z) on IF level overflow
  116.   USES : AF
  117.  
  118.  Usage:  These routines are used to set Flow Control States and
  119.   raise the IF level.  The Flow Control State can support up to
  120.   eight (8) levels of IFs.  IFT and IFF return error codes for
  121.   overflow conditions which should be sensed to insure the
  122.   integrity of the program.
  123.  
  124. :IFTEST - Determine the current IF level
  125.  
  126.   ENTER: None
  127.   EXIT : A = Number of current IF level, Zero Flag set
  128.              accordingly
  129.   USES : AF
  130.  
  131.  Usage:  This routine is sed determine the current IF level.
  132.   The returned value ranges from 0 to 8,  indicating the
  133.   current level.  If A=0, there is no current IF.  The Zero
  134.   Flag is set accordingly to allow rapid testing.
  135.  
  136. Example:
  137.     EXT    IFTEST        ; Declare the routine
  138.     ...            ; ..preceeding code
  139.     CALL    IFTEST        ; Get current IF level
  140.     JR    Z,NOIF        ; ..jump if None
  141.     CP    8        ; Is it at Max level?
  142.     JR    Z,ATMAX        ; ..jump if at Max IF level
  143.     ...            ; Else Carry shows empty levs
  144.  
  145. :IFELSE - Toggle TRUE/FALSE state of current IF level
  146.  
  147.   ENTER: None
  148.   EXIT : A <> 0, Zero Flag Clear (NZ) if Successful
  149.              A = 0, Zero Flag Set (Z) if No current IF
  150.   USES : AF
  151.  
  152.  Usage:  This routine is used to toggle the current state of
  153.   the current IF level.  If called an even number of times, the
  154.   state is effectively unchanged.
  155.  
  156. :          Introduction to ZEX Access and Control 
  157.  
  158. The ZEX Command File Facility (under ZCPR3 only!) can be
  159. controlled by this set of Z3LIB routines.  ZEX intercepts all
  160. BIOS calls for input, and, when in intercept mode, it provides
  161. input from text contained in its memory-based text buffer
  162. rather than allowing the user to input characters from the
  163. keyboard.  These routines are used to query the status of ZEX
  164. and to instruct ZEX to continue intercepting characters or to
  165. stop intercepting characters and allow user input.
  166.  
  167. This set of routines provides access to the ZEX memory-based
  168. Command File Processor and its environment.  You can take
  169. control of ZEX through these routines.
  170.  
  171.  
  172.      Summary of Routines:
  173.  
  174.     GETZEX  - Get the ZEX Control Message
  175.     GETZFC  - Get the first character in ZEX buffer
  176.     GETZNC  - Get the next character to be returned
  177.     GETZRUN - Get ZEX Running Flag
  178.  
  179.     HALTZEX - Terminate the ZEX processor
  180.  
  181.     PUTZEX  - Set the ZEX Control Message
  182.     PUTZNC  - Set the next character to be returned
  183.     PUTZRUN - Set ZEX Running Flag
  184.  
  185.     STOPZEX - Suspend ZEX Execution
  186.     STRTZEX - Resume ZEX Execution from a STOPZEX
  187.  
  188. :ZEX Data     GETZFC, GETZNC, GETZRUN, PUTZNC, PUTZRUN 
  189.  
  190. GETZFC - Return address of first character in ZEX Buffer
  191.  
  192.   ENTER: None
  193.   EXIT : HL = Address of first char in ZEX Script Buffer
  194.           A = Char at that address, Carry Clear (NC) if data
  195.               Carry Flag Set (C) if NO text data in Buffer
  196.   USES : AF,HL
  197.  
  198.  Usage:  This routine may be used to examine the script data
  199.   for a running ZEX Script sequence.
  200.  
  201. GETZNC - Get next character ZEX will process
  202.  
  203.   ENTER: None
  204.   EXIT : HL = Addr of Next Character in ZEX Text Buffer
  205.           A = Next Char to be returned, Carry Clear if valid
  206.               Carry Flag Set (C) if No Text Data remains
  207.   USES : AF,HL
  208.  
  209.  Usage:  This routine may be used to effect changes to a
  210.   running ZEX program by examining the next character that
  211.   will be returned.
  212.  
  213. GETZRUN - Determine Run Status of ZEX from Run Message Byte
  214.  
  215.   ENTER: None
  216.   EXIT : A = Run Message, Zero Set accordingly (0=Not running)
  217.              Carry Flag Set (C) if No Message available
  218.   USES : AF
  219.  
  220.  Usage:  This routine returns the ZEX Run Message Byte and sets
  221.   flags indicating status as:
  222.     Zero  - Set (Z) if ZEX Not Running, else Clear (NZ)
  223.     Carry - Set (C) if No Message, Else Clear (NC)
  224.  
  225. PUTZNC - Set Address of next ZEX character (GOTO)
  226.  
  227.   ENTER: HL = Address of next character ZEX will return
  228.   EXIT :  Carry Flag Clear (NC) if operation Successful
  229.               Carry Set (C) if ZEX Buffers NOT available
  230.   USES : AF
  231.  
  232.  Usage:  This routine sets the address of the next character
  233.   which will be read by ZEX.  Using this routine provides a
  234.   GOTO function for ZEX control.
  235.  
  236. PUTZRUN - Set value of ZEX Running Message Byte
  237.  
  238.   ENTER: A = Value of ZEX Running Message Byte
  239.   EXIT :  Carry Flag Set (C) if No Message Buffers
  240.   USES : AF
  241.  
  242.  Usage:  This routine sets the ZEX Running Message byte to
  243.   a user-supplies value.  Its purpose is to allow running
  244.   programs to disable or suspend ZEX processing.  Set to Zero
  245.   to Stop ZEX processing.
  246.  
  247. :ZEX Status & Control  GETZEX, PUTZEX, HALTZEX, STOPZEX, STRTZEX 
  248.  
  249. GETZEX - Return ZEX Control Message Byte
  250.  
  251.   ENTER: None
  252.   EXIT : A = ZEX Control Message (0,1,2), Zero set accordingly
  253.   USES : AF
  254.  
  255.  Usage:  This routine is used to allow programs to determine
  256.   the current state of ZEX.  The Control Message Byte can
  257.   have one of the following three values:
  258.  
  259.    0 - "normal" - ZEX is running and intercepting BIOS calls
  260.    1 - "ZCPR3 Prompt" - ZEX is allowed to run and intercept
  261.         BIOS calls but ZEX thinks that it is providing input
  262.         to the ZCPR3 Command Processor directly (ZEX is not
  263.         providing input to any program)
  264.    2 - "ZEX suspended" - ZEX is not intercepting BIOS calls
  265.         and user input is allowed
  266.  
  267.   The 1 Code should never be seen by any program since it is
  268.   set by ZCPR3 and cleared to 0 after ZEX has completed the
  269.   Command Line input.
  270.  
  271.   Any ZEX control message is reset upon execution of ZCPR3 to 0
  272.   when ZCPR3 is entered and then to 1 when the ZCPR3 prompt
  273.   appears (ZCPR3 input).  When ZCPR3 completes its input, it
  274.   resets the ZEX Control Message to 0.
  275.  
  276. PUTZEX - Set ZEX Control Message Byte (Change ZEX State)
  277.  
  278.   ENTER: A = ZEX Control Message Byte (0,1,2)
  279.   EXIT : None
  280.   USES : None
  281.  
  282.  Usage:  This routine allows a program to set the state that
  283.   ZEX is in.  This Control Message byte must only be set to one
  284.   of these values:
  285.  
  286.    0 - "normal" - ZEX is running and intercepting BIOS calls
  287.    1 - "ZCPR3 Prompt" - ZEX is allowed to run and intercept
  288.     BIOS calls but ZEX thinks that it is providing input to
  289.     the ZCPR3 command Processor directly (ZEX is not
  290.     providing input to any program)
  291.    2 - "ZEX suspended" - ZEX is not intercepting BIOS calls and
  292.     user input is allowed
  293.  
  294.  
  295.   The 1 code may be set by any program if it wants ZEX to
  296.   "think" that it is providing input to ZCPR3.  If ZEX was
  297.   previously suspended, it advances to the beginning of the
  298.   next line and resumes when it sees this code.
  299.  
  300.   Any ZEX control message is reset upon execution of ZCPR3 to
  301.   0 when ZCPR3 is entered and then to 1 when the ZCPR3 prompt
  302.   appears (ZCPR3 input).  When ZCPR3 completes its input, it
  303.   resets the ZEX control message to 0.
  304.  
  305. HALTZEX - Halt ZEX completely by setting ZEX End-of-File
  306.  
  307.   ENTER: None
  308.   EXIT : A <> 0, Zero Flag Clear (NZ) if ZEX is Halted
  309.              A = 0, Zero Flag Set (Z) if ZEX NOT Running
  310.   USES : AF
  311.  
  312.  Usage:  This routine terminates execution of ZEX completely.
  313.   Other routines provide temporary execution control such as
  314.   STOPZEX (suspend execution), and STRTZEX (resume execution),
  315.   but HALTZEX causes ZEX to terminate itself completely by
  316.   setting the next character ZEX will process to the termina-
  317.   tion character of 0FFH.
  318.  
  319. STOPZEX - Temporarily Suspend ZEX Script processing
  320.  
  321.   ENTER: None
  322.   EXIT : None
  323.   USES : None
  324.   SIDE EFFECTS: ZEX Control Message Byte is set to 2
  325.  
  326.  Usage:  This routine is used to temporarily stop ZEX from
  327.   intercepting BIOS calls and allow the user to input
  328.   characters.  This is a shorthand to placing the 2 control
  329.   code into the ZEX Control Message Byte.
  330.  
  331. STRTZEX - Start processing from ZEX Script
  332.  
  333.   ENTER: None
  334.   EXIT : None
  335.   USES : None
  336.  
  337.  Usage:  Allow ZEX to intercept BIOS calls and don't allow
  338.   user to input characters.  This is a shorthand to placing
  339.   the 0 control code  into the ZEX Control Message Byte.
  340.  
  341. :           Introduction to SUBMIT/XSUB Processing 
  342.  
  343. In enhancing the ZCPR 3 Command Processors and defining the
  344. Extended Environment, provisions were also made to control
  345. program flow from SUBMIT and XSUB utilities in the same manner
  346. as the memory-based ZEX processing covered elsewhere.
  347.  
  348. SUBMIT processing is determined via flags and other data within
  349. ZCPR Version 3.3 and later.  Routines supporting its features
  350. must have access to the Command Processor.  It is your respon-
  351. sibility to insure that the Processor is not overwritten.
  352.  
  353. The combination of SUBMIT with an XSUB-like utility form the
  354. basis of a disk-based corollary to ZEX for uses where a large
  355. TPA space, or very large scripts must be processed.  "Hooks"
  356. are therefore provided with these routines to enable such a
  357. facility.
  358.  
  359. :SUBON - Determine whether SUBMIT processing is enabled        (*)
  360.  
  361.   ENTER: None
  362.   EXIT :  Zero Clear (NZ) if SUBMIT Is enabled
  363.       Zero Set (Z) if No ZCPR 3.3 or SUBMIT Disabled
  364.       A - Destroyed
  365.   USES : AF
  366.   REQUIREMENTS: The ZCPR 3.3 Command Processor or later
  367.  
  368.  Usage:  This routine is used to determine whether the SUBMIT
  369.   facility within ZCPR version 3.3 or later is enabled.  An
  370.   error status is returned if SUBMIT is disabled, or the
  371.   Command Processor is not ZCPR 3.3 or later.
  372.   NOTE: The Command Processor must NOT have been overwritten.
  373.  
  374. HALTSUB - Terminate an executing SUBMIT job                   (*)
  375.  
  376.   ENTER: None
  377.   EXIT : None.  The $$$.SUB is deleted
  378.   USES : None
  379.  
  380.  Usage:  This routine stops an executing SUBMIT job by deleting
  381.   the $$$.SUB file addressed in the ZCPR 3.3 Submit FCB.
  382.  
  383. GETSRUN - Return flag indicating SUBMIT job status            (*)
  384.  
  385.   ENTER: None
  386.   EXIT : A <> 0, Zero Clear (NZ) if SUBMIT job IS running
  387.              A = 0, Zero Set (Z) if SUBMIT is NOT running
  388.   USES : AF
  389.  
  390.  Usage:  This function is used to determine whether we are
  391.   currently running within a SUBMIT job.  This is sometimes
  392.   necessary information to determine possible actions within
  393.   a program.
  394.  
  395. GETSFCB - Return the ZCPR 3.3 or later Submit FCB address.    (*)
  396.  
  397.   ENTER: None
  398.   EXIT : DE = Address of SUBMIT FCB (Undefined if error)
  399.           A <> 0, Zero Flag Clear (NZ) if Ok
  400.               A = 0, Zero Set (Z) if NO SUBMIT or ZCPR 3.3
  401.   USES : AF,DE
  402.   REQUIREMENTS: ZCPR 3.3 or later Command Processor
  403.  
  404.  Usage:  This routine returns the SUBMIT FCB address from ZCPR
  405.   Version 3.3 or later FCB.  An Error status is returned if
  406.   SUBMIT is not enabled or the Command Processor is not of the
  407.   right type.
  408.   NOTE: The Command Processor must NOT have been overwritten
  409.  
  410. :STOPXSUB - Reset XSUB Input Redirection Flag                  (*)
  411.  
  412.   ENTER: None
  413.   EXIT : None.  XSUB is Halted
  414.   USES : None
  415.  
  416.  Usage:  This routine is used to Stop XSUB program flow for
  417.   local console input.  This is accomplished by resetting a
  418.   flag in the Message Buffer.
  419.  
  420. GXSUB - Return the value of the XSUB redirection flag        (*)
  421.  
  422.   ENTER: None
  423.   EXIT :  A = Value of the XSUB redirection flag
  424.   USES : AF
  425.  
  426.  Usage:  This routine is used to determine if input to the
  427.   running program is coming from an XSUB utility.  This is
  428.   useful in Error conditions where the normal flow of commands
  429.   and data must be altered for operator input.
  430.  
  431. PXSUB - Set the XSUB Input Redirection Flag                  (*)
  432.  
  433.   ENTER: A = value to set XSUB input redirection flag
  434.   EXIT : None.  The value is set
  435.   USES : None
  436.  
  437.  Usage:  This routine is used to activate XSUB processing from
  438.   a Command Script or SUB file.  By setting the XSUB Redirec-
  439.   tion Flag, program flow can be dynamically altered.  Until a
  440.   better definition is developed, it is suggested that the
  441.   Command bytes used for ZEX be applied (See GETZEX).
  442.