Use the STAX macro instruction to specify the address of an attention exit routine that is to be given control asynchronously when a user presses the attention key or when a simulated attention is specified. (See STATTN - Set Attention Simulation for a description of the simulated attention function.)

For attention interruptions that occur while a CLIST with a CLIST attention exit is processing, control passes to the last attention exit established with the CLSTATTN operand on the STAX macro (attention exits are searched in LIFO order until one is found that was established with the CLSTATTN operand). If no attention exit was established with the CLSTATTN operand, control passes to the first attention exit established.

The STAX macro instruction can also be used to cancel the last attention exit routine established by the task. To do this, specify the STAX macro instruction without any operands.

The STAX macro instruction is used only in a time sharing environment. When a task other than a TSO/E user issues the STAX macro, no action is taken. In addition, attention exits can be established only for time sharing tasks operating in the foreground.

The system routines that process attention handling require that the STAX parameter list remain unchanged for the duration of the program. Because the expansion of the STAX parameter list is usually located in an area that is reusable by the active program, you should either code the necessary protection to prevent overlays or you should make a copy of the parameter list in an area that is non-reusable.

Issue the STAX macro instruction to provide the information required by the STAX service routine. The STAX macro may be issued in either 24-, 31-, or 64-bit addressing mode, unless you are using the LINKAGE=BRANCH option. (See the LINKAGE operand description below for programming restrictions.) An attention exit routine receives control in the same addressing mode in which the STAX macro is issued.

The STAX macro instruction has a list, an execute, and a standard form.

The list form of the STAX macro instruction (MF=L) generates a STAX parameter list. The execute form of the STAX macro instruction (MF=E,address) completes or modifies that list and passes its address to the STAX service routine. The standard form does not require you to specify MF=L or MF=E.

Figure 1 shows the format of the STAX macro instruction; each of the operands is explained following the figure.

 [symbol]      STAX    [ exit address [,OBUF=(output buffer address,size)]]
                       [              [,IBUF=(input buffer address,size)] ]
                                      [,USADDR=user address]

                                      [,REPLACE={YES} ]
                                      [         {NO } ]

                                      [,DEFER={YES} ]
                                      [       {NO } ]

                                      [,LINKAGE={SVC   } ]
                                      [         {BRANCH} ]

                                      [,CLSTATTN={YES} ]
                                      [          {NO } ]

                                      [,IGNORE={YES} ]
                                      [        {NO } ]

                                      [,TOPLEVL={YES} ]
                                      [         {NO } ]

                                      {,MF=L           }
                                      {,MF=(E,address) }

exit address

Specify the entry point of the routine to be given control when an attention interruption is received. You must specify the exit address in both the list and the execute forms of the STAX macro instruction when you are establishing an attention interruption handling exit.

You do not need to specify an exit address if you are using the DEFER operand as long as you code no other operands, except the MF operand. If you exclude the exit address and code no other operands, the STAX service routine cancels the previous attention exit established by the task issuing this STAX macro instruction.

OBUF=(output buffer address,output buffer size)

Output buffer address

Supply the address of a buffer you have obtained and initialized with the message to be put out to the terminal user who enters the attention interruption. This message can identify the exit routine and request information from the terminal user. It is sent to the terminal before the attention exit routine is given control.

Output buffer size

Indicate the number of characters in the output buffer. The size can range from 0 to 32,767 (2¹⁵-1) inclusive.

IBUF=(input buffer address,input buffer size)

Input buffer address

Supply the address of a buffer you have obtained to receive responses from the terminal user. The attention exit routine is not given control until the STAX service routine has placed the terminal user's reply into this buffer.

Input buffer size

Indicate the number of bytes you have provided as an input buffer. The size can range from 0 to 32,767 (2¹⁵-1) inclusive.

USADDR=(user address)

The user address is a 24-, 31-, or 64-bit address that points to any information you want passed to your attention handling exit routine when it is given control. When the attention exit gains control, register 1 points to the attention exit parameter list described in Table 1.

Table 1. The attention exit parameter Llist

Number of bytes	Field name	Contents or meaning
4		The address of the terminal attention interrupt element (TAIE).
4		The address of the input buffer you specified as the IBUF operand of the STAX macro instruction. This field is zero if you did not include the IBUF operand in the STAX macro instruction.
4		The address of the user parameter information you specified as the USADDR operand of the STAX macro instruction. This field is zero if you did not include the USADDR operand in the STAX macro instruction.

REPLACE=YES | NO

YES

indicates that the attention exit specified by this STAX macro instruction replaces any attention exit specified by a STAX macro instruction previously issued by this task. YES is the default value. REPLACE implies establishing a new attention exit routine for the task, if no previous attention exit has been established.

NO

indicates that this attention exit be established as a new attention exit for this task, in addition to any that have been previously established for this task.

DEFER=YES | NO

The DEFER operand is optional. If the DEFER operand is coded in the STAX macro instruction, the option you request (YES or NO) applies to all tasks within the task chain in which the macro instruction was issued. Any task can issue the STAX macro instruction to specify DEFER=YES or NO; it is not necessary for the issuing task itself to have provided an attention exit routine. If the DEFER operand is not coded in the macro instruction, no action is taken by the STAX service routine regarding the deferral of attention exits.

YES

indicates that any attention interruptions received are to be queued and are not to be processed until:

• Another STAX macro instruction is executed specifying DEFER=NO
• The request block of the program that issued STAX DEFER=YES terminates and there is no other request block on the chain with attention interruptions to be deferred.

NO

indicates that the defer option is being canceled. Any attention interruptions received while the defer option was in effect are processed, unless the task is still not eligible for attention interruptions. If the DEFER operand is omitted, the control program leaves the deferral status unchanged.

Be aware that if a program issues a STAX macro instruction specifying DEFER=YES, the program can get into a situation where an attention interruption cannot be received from the terminal. If your program enters a loop or an unending wait before it has issued a STAX macro instruction specifying DEFER=NO, you cannot regain control at the terminal by entering an attention interruption.

You do not need to specify an exit address in a STAX macro instruction issued only to change deferral status.

LINKAGE=SVC | BRANCH (For MVS/ESA SP 4.2.2 or higher)

The LINKAGE operand is optional and is valid only when used with the DEFER operand. You cannot use any STAX operands other than DEFER when you use LINKAGE=BRANCH. It may be specified only on the standard form of the macro.

SVC

specifies that the STAX macro will generate an SVC to link from the calling program to the STAX SVC service routine. SVC is the default value.

BRANCH

specifies that the STAX macro will generate a branch instruction to link to the DEFER service of the STAX service routine. Because SVCs are not valid in cross-memory mode, this option allows you to defer attention exits in cross-memory mode.

The LINKAGE=BRANCH option requires that your program be in the following states:

Authorization

Supervisor

State

Key 0

Amode

31-bit

Rmode

Any

Interrupt Status

For DEFER=NO,LINKAGE=BRANCH, the caller must be enabled and unlocked. For DEFER=YES,LINKAGE=BRANCH, the caller may be either enabled or disabled.

Serialization

None.

CLSTATTN=YES | NO

The CLSTATTN operand is optional. Code it only when you are establishing an attention exit. If you code the CLSTATTN keyword, you must provide an exit address.

YES

indicates that the attention exit being established can receive control for normal attention interruptions and for attention interruptions that occur while a CLIST with a CLIST attention exit is processing. When an attention interruption occurs while a CLIST with a CLIST attention exit is processing, the last attention exit established with the CLSTATTN=YES operand gains control to process the CLIST attention exit or pass control to the CLIST attention facility.

NO

indicates that the attention exit being established cannot process a CLIST that has a CLIST attention exit. No is the default value for the CLSTATTN operand.

IGNORE=YES | NO

The IGNORE operand is optional and is effective only when used in conjunction with the CLSTATTN=YES operand. Code the IGNORE operand only when attention interruptions are to be ignored or reestablished.

YES

When coded with the CLSTATTN operand (and an exit address) to establish an attention exit, indicates that attention interruptions are to be ignored when the attention exit being established receives control. Attention interruptions are reestablished when the attention exit returns control or issues the IGNORE=NO operand.

When coded within an attention exit established with the CLSTATTN=YES operand, IGNORE=YES also indicates that attention interruptions are to be ignored until the attention exit currently in control returns control or issues the IGNORE=NO operand. However, when coded within an attention exit, IGNORE=YES must be the only operand on the STAX macro instruction.

NO

indicates that attention interruptions are to be reestablished. An attention exit established with the CLSTATTN=YES operand can issue IGNORE=NO to indicate that attention interruptions are to be reestablished. The IGNORE=NO operand must be the only operand on the STAX macro instruction. IGNORE, without the CLSTATTN operand and an exit address, can only be issued by an attention exit that was established with the CLSTATTN=YES operand.

TOPLEVL=YES | NO

The TOPLEVL operand is optional. Code it only when you are establishing an attention exit.

If you code the TOPLEVL operand, you must provide an exit address.

If the ATTENTION key is pressed once, the first-level attention exit is given control; if pressed twice, the second-level attention exit is given control, and so forth. Use the TOPLEVL operand to control processing when the terminal user presses the attention key multiple times.

YES

indicates that when the attention key is pressed multiple times, control is not to be passed to higher-level attention exits than the exit being established. When an attention exit established with the TOPLEVL=YES operand receives control, the user cannot terminate execution of the exit by pressing the attention key. Therefore, the user cannot terminate execution of the program, and possibly see a TSO/E READY mode message.

NO

indicates that higher-level attention exits than the one being established can receive control when the attention key is pressed multiple times. For example, when the user presses the attention key two times, the second-level attention exit is given control. NO is the default value for the TOPLEVL operand.

MF=L | (E,address)

specifies the form of the STAX macro instruction.

L

specifies the list form of the STAX macro instruction. It generates a STAX parameter list.

(E,address)

specifies the execute form of the STAX macro instruction. It completes or modifies the STAX parameter list and passes the address of the parameter list to the STAX service routine. Place the address of the STAX parameter list (the address of the list form of the STAX macro instruction) into a register and specify that register number within parentheses.

You can place each of the required address and size parameters into registers and specify those registers, within parentheses, in the STAX macro instruction. Figure 2 shows how an execute form of the STAX macro instruction might look if you load all the required parameters into registers.

STAX     (2),IBUF=((3),(4)),OBUF=((5),(6)),USADDR=(7),MF=(E,(1))