Attention Interruption Handling -- The STAX Service Routine

The STAX service routine creates the control blocks and queues necessary for the system to recognize and schedule user exits due to attention interruptions. Your terminal monitor program, your command processors, or the problem program provide the address of an attention exit to the STAX service routine by issuing the STAX macro instruction. You should provide attention exit routines within the terminal monitor program and any command processors that accept

subcommands. Simple command or subcommand procedures should not issue a ST AX macro instruction unless the ST AX routine specified by the TMP or the calling command processor cannot process an attention interruption adequately.

The STAX service routine may be invoked in either 24- or 31-bit addressing mode. The attention exit routine receives control in the same addressing mode in which the respective STAX macro is issued.

With the exception of the TPUT ASID buffers for TeAM, when the user enters an attention interruption from the terminal, the TGET, TPUT, and TPG buffers are flushed. Any data contained in these buffers is lost. If the user then attempts to continue processing from the point of interruption, he may have lost an input or an output record, or an output message from the system.

Attention processing gives the user the ability to specify exit routines that receive control asynchronously when the attention key is struck or when an interruption occurs as a result of the simulated attention facility (ST ATTN macro). The mechanism used to request attention exits is the STAX macro. When the ST AX macro is issued, a TAXE (terminal attention exit element) is created and placed on a queue. The T AXE queue is ordered according to the attention level, and the attention level determines the order in which the attention exits are given control.

If the ATTENTION key is struck once, the first level attention exit is given control. If the key is struck twice, the second level attention exit is given control.

When placing a TAXE on the TAXE queue, two rules apply:

1. An attention exit routine for a task will always occupy a higher attention level than the attention exit of any of its subtasks.

2. The attention exit routine is placed at the lowest possible attention level, without violating the first rule.

In other words, the placement at an attention level is determined by the position of the task in the subtask queue relative to the position of the other tasks creating attention exits. The lower the subtask the lower the attention level assigned. The subtask queue is considered to be the mother-daughter queue only. If for any reason a complex task structure is created that would have a mother task with

Chapter 9. Attention Interruption Handling -- The STAX Service Routine 9-1

multiple daughter tasks, then the order in which the daughters issue STAX macros must be synchronized in order to ensure predictability from day to day.

Note that the order in which the daughters issue ST AX macros, not the order in which the daughters are attached, determines the order in which the associated TAXEs are placed on the TAXE queue.

If a task has issued multiple ST AX macros, the order in which the associated T AXE is placed on the T AXE queue is determined by the second rule.

Attention levels can change during execution of the session for three reasons:

1. A task has issued STAX and its daughter then issues ST AX. In this case the attention exit for the first task would have an attention level of one until its subtask had issued ST AX. The daughter task would then have an attention level of one and the original task would have a level of two.

2. A task that has established an attention exit environment abnormally

terminates or exits. When this occurs the TAXEs for that task are freed. The remaining TAXEs then assume the new attention level relative to its position on the TAXE queue.

3. The STAX macro is used to cancel the last attention exit established by a task.

When generating an attention interruption by striking the ATTENTION key, the A TTENTION level is recorded by counting the number of times the

ATTENTION key has been struck. If the number of times the key is struck exceeds the number of available attention levels, an "!I" message is sent to the terminal. If the attention has been accepted, an ''1'' message is sent to the terminal to indicate that the attention exit is being scheduled. If an attention interruption is received while a previously requested (lower attention level) attention exit is in the process of being scheduled, the first attention exit is canceled and the new attention exit is scheduled. This will be true until control has been passed to the user's attention exit.

Prior to passing control to the attention exit, the task under which the attention exit is running will have all its subtasks stopped. Note, however, that if a system routine (SVRB on RB chain) is executing for one of the TCBs and has not specified STAX DEFER = NO (see below for expanded explanation), then the scheduling of the attention exit will be deferred until the completion of such system routines. All SVRBs start execution in a STAX DEFER = YES state and all other RBs start execution in a STAX DEFER=NO state. Consequently, the presence of an SVRB on a TCB's RB chain normally means attention exits will be deferred. When the user's attention exit completes processing the subtasks are automatically restarted. If, for any reason, the attention routine requires one of the subtasks to be restarted, it is the responsibility of the attention exit to restart the task through the use of the status start facility. If the subtasks should not be restarted, it is the responsibility of the attention exit to use the status stop facility to ensure that the sub tasks will not become dispatchable when the attention exit completes processing. See Supervisor Services and M aero Instructions for additional information.

9-2

The attention level at which the attention exit is running and all of the lower attention levels are considered unavailable as soon as scheduling of the exit takes place. Therefore, once the attention scheduling has begun, only higher attention levels are available for use until the attention exit completes processing.

You can use the ST AX macro not only to specify and cancel attention exits, but also to defer the dispatching of attention exits. The DEFER operand of ST AX can be specified to set an indicator that will postpone the dispatching of attention exits for a TCB and all of the TCBs above it on the mother-daughter TCB chain.

When STAX with the DEFER = YES option is specified, a bit in the RB that represents the issuer's routine is set (or reset). The indicator in the TCB, which allows or defers the dispatching of attention exits, is set equal to the result of ORing all of these bits in the RBs on the TCB RB chain. When the TCB defer indicator is off for a TCB and all of its sub tasks, then attention exits will be dispatched. If the defer indicator is on for a TCB or any of its subtasks, then attention exits will be deferred until the defer indicator(s) for the TCB and all of its subtasks are off. When an attention exit can once again be dispatched, the DEFER = NO operand can be used to enable it to be dispatched.

The deferral bit setting of a routine (RB) can be changed or propagated to other routines (RBs) which are used by the original RB. There are three cases to be considered.

1. A new RB is created and placed on the RB queue along with the original RB.

This can occur if the original RB issues a LINK. In this situation, the routine that has been linked maintains its own deferral bit setting. The deferral bit setting of the original RB is not passed to the new RB, nor is the deferral bit setting of the new RB passed back to the original RB.

2. A new RB is created and placed on the RB queue and the original RB is destroyed. This can occur if the original RB issues an XCTL macro. The routine receiving control under the new RB receives the deferral bit setting of the original RB.

3. No new RB is created but control is passed to a routine running under the original RB. This can occur if the original RB issues a CALL or LOAD macro. The called or loaded routine runs under the original RB. If the called or loaded routine issues a STAX macro instruction with the DEFER option, then the deferral bit setting is changed for the original RB.

Note: Tasks within a tree structure being stopped for the attention exit scheduling will be stopped in an indeterminate order when any are deferring attention exits. As a result, care must be taken to control intertask dependencies and dependencies on scheduling attention exits. Failure to do so may result in an intertask deadlock that can only be relieved by canceling the TSO user.

Chapter 9. Attention Interruption Handling -- The STAX Service Routine

9-3

Specifying a Terminal Attention Exit -- The STAX Macro