CP/M

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

/ CP/M / CPM_CDROM.iso / jsage / zsus / z3help / y.lbr / Z3LIB3.HZP / Z3LIB3.HLP

Wrap

Text File | 1989-04-08 | 15.1 KB | 442 lines

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).