HP 3000 Manuals HP 3000 Manuals
Branch-During-Input Keys
By defining a branch-during-input key you provide a method of altering
program flow from within an input statement. For example, you can write
a help facility that is accessed by pressing a branch-during-input key
while the program is executing an input statement. Statements and
functions used to define the branch-during-input keys are described
below:
* ON KEY and OFF KEY - Activation and deactivation, respectively, of a
single key or set of keys defined as branch-during-input keys.
* ENABLE - Specifies that any key-generated branch in the interrupt
queue is to be processed. If the queue is empty, branch-during-input
keys are processed immediately when pressed.
* DISABLE - Specifies that any key-generated branches are to be added
to the interrupt queue without processing.
* PRESS KEY - Allows the simulation of pressing a branch-during-input
key from within the program.
* CURKEY - A function that returns the number of the last
branch-during-input key pressed.
* RESPONSE - A function that returns how input was terminated,
including which softkey was pressed.
These statements are defined in chapter 4. CURKEY and RESPONSE are
defined in chapter 5.
Branch-during-input keys are active only during program execution and
only when pressed following an input prompt (that is, while INPUT,
TINPUT, ACCEPT, or LINPUT statements execute) and before pressing RETURN.
They are also active during execution of a READ FORM statement. Any
input characters typed between the input prompt and the pressing of the
user-definable key defined as a branch-during-input key are lost. Only
one branch-during-input key can be pressed during a given input
statement.
The resulting branch ( GOTO, GOSUB or CALL ) to be taken is specified in
the ON KEY statement used to define the branch-during-input key. The
definition of the branch-during-input key overwrites the current typing
aid definition for that key. However, the HP Business BASIC/XL
interpreter remembers the last previous typing aid definition for that
key. When an OFF KEY statement for that user-definable key is executed,
the typing aid definition is restored.
SAVE KEY fname and RESAVE KEY fname save only the typing aid definitions
for the keys. If a key is currently defined as a branch-during-input
key, the last previous typing aid definition is written to the file if
either of these statements execute. Remember that the last previous
typing aid definition is set by either a SAVE KEY, SAVE or RESAVE KEY
fname, GET KEY fname, or SCRATCH KEY.
Priority of Handling the Branch after Pressing Branch-During-Input Keys.
The branching that is performed in response to the ON KEY statement can
be considered a restricted interrupt of the normal program flow. As
such, the order it is handled in depends on the number of higher priority
interrupts that must be handled when the branch-during-input key is
pressed. Chapter 4 contains the statements for interrupt handling for
DBERROR, EOF (end of file), run-time errors, and HALT ( CONTROL Y). The
priority for handling these interrupts is:
HALT 16
SHIFT HALT 17
EOF (end of file) 17
run-time errors 17
The priority level for the branch-during-input keys can be set to any
integer between 1 and 15, inclusive. If a priority level is not
specified in the ON KEY statement, the priority is set to 1. The
branches specified by the interrupt handlers and the branch-during-input
keys are added to the interrupt queue. The branch with the highest
associated priority is processed first. If there is more than one
key-generated branch in the interrupt queue with the same priority, the
branch resulting from pressing the highest numbered key is processed
first.
There are now two conditions to consider:
* If the specified branch is a GOSUB or CALL, then the interrupt queue
for the program unit that the key was pressed in is checked
immediately following the execution of the RETURN statement that
returns control to the calling program unit.
* If the branch is a GOTO, then the statement that is the target of the
branch is executed. Following execution of the target statement, the
interrupt queue is checked again.
In either case, if the interrupt queue is not empty, then the next branch
in the queue with equal priority to that just executed or the branch with
the highest remaining priority executes. The process continues until
there are no more branches to execute remaining in the queue. At this
point, program execution continues at the next executable statement in
the program.
If only one GOSUB or CALL branch generated by a branch-during-input key
is in the interrupt queue when the ENABLE statement executes, the GOSUB
or CALL executes and then execution resumes at the statement following
the input statement.
Execution of RUN, STOP, END, SCRATCH PROG, or SCRATCH ALL clears the
interrupt queue of any key generated branches remaining to be executed.
The DISABLE statement lets the program add branches to the interrupt
queue, but delays execution of the branches. The ENABLE statement allows
the handling of queued branch information to continue or begin.
Subunits
The ON KEY CALL statement is active in all subunits called by the subunit
that the statement is in unless the user-definable key is redefined
within the called subunit. If the key is redefined, the definition on
exit from the called subunit is restored to the ON KEY call that it had
upon entry. ON KEY GOTO and ON KEY GOSUB are active only within the
subunit that they are in. Similarly, an OFF KEY restores the typing aid
key definitions to those keys specified only for the subunit that the OFF
KEY is in. When you exit from the subunit, the values that the fields
of the keys had upon entry to the subunit are restored. If a
branch-during-input key is pressed within a compiled subunit called from
a program running in the interpreter, the specified branch is added to
the interrupt queue and handled when you return to the interpreter.