SETATNPGM (Set Attention Program)

SETATNPGM Command syntax diagram

 

Purpose

The Set Attention Program (SETATNPGM) command causes the specified program to become the attention key handler at the current recursion level in the job running the command. If the ATTN key handler's status is SET(*ON), the specified program is called when the ATTN key is pressed. No parameters are passed to the ATTN key handler when it is called. The attention handling program runs in the same process with the same job attributes, overrides, and group authorities as the program that issued the SETATNPGM command. However, program adopted authority is not carried over.

This command is call-oriented; that is, a SETATNPGM command issued at one recursion level causes the attention handling program to be in effect at the current recursion level as well as deeper recursion levels, until another SETATNPGM command occurs which changes the attention handling program. More information is in the Work Management book.

Pressing the ATTN key under the following conditions does not call the ATTN key handler (that is, it appears as if SET(*OFF) were the status of the ATTN key):

Note: Caution is necessary when defining an attention handling program. Attention handling is similar to system request option 1 (transfer to secondary job), but there are special considerations for its use. When a transfer to secondary job occurs, processing continues in another job; however, when the ATTN key is pressed, the ATTN key handler runs in the same job. The program in progress when the ATTN key is pressed is not protected by any locks held. This means that the attention handler can get a lock on any object, even if a program it interrupted already had an exclusive lock. Be aware that read from invited devices operation could time-out during the time that the attention key handling program is running. Therefore, if a time-out were to complete in the program in progress while the attention key handling program is running, whatever action taken as a result of that time-out occurs upon return to the program in progress.

For example, if the WAITRCD value in the file is set to 60 seconds, the program is set to exit if a key is not pressed in 1 minute, and the attention key program is invoked and runs longer than 1 minute, the program exits when it returns from the attention key handler.

However, caution should be used because a check for data available is made before checking to see that the time-out completes. If a key is pressed immediately after leaving the attention key handler, data could be available which could complete the read from invited devices and the time-out is not checked. This could cause unexpected results.

Applications that perform Get-No-Wait operations can be interrupted at any point where the ATTN key is pressed. Attention handlers therefore should:

  • Use simple functions like a menu which transfers to a group job or secondary job.

  • Avoid referring to objects or functions that may be in use when the ATTN key is pressed.

  • Avoid calling nonrecursive functions (many non-OS/400 system functions) that are going to be interrupted by the ATTN key. (This is especially true of high-level languages and utilities, because they are not designed to be used recursively.)

Restriction: To use this command the program specified must exist and have object operational authority or one of the data authorities to it. You must also have read authority to the program's library.

 

Required Parameters

PGM
Specifies the qualified name of the program to be the ATTN key handler at this recursion level.

*CURRENT: The program name of the ATTN key handler currently in effect is used as the value of this parameter. An error does not occur if an ATTN key handler is not currently in effect.

*PRVINVLVL: The ATTN key handler in effect at the previous recursion level is reinstated as the ATTN key handler at this recursion level. The SET parameter is not allowed if this special value is specified, because the SET status of the previous recursion level is also reinstated. This option is used when a program has specified an attention program and wants to revert back to a previous level.

The name of the program can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

program-name: Specify the name of the program that is the ATTN key handler.

 

Optional Parameters

SET
Specifies whether the ATTN key handler indicated in the program (PGM) parameter should be called when the ATTN key is pressed. This parameter is not allowed if PGM(*PRVINVLVL) is specified.

*ON: The ATTN key handler specified in the program (PGM) parameter is called when the ATTN key is pressed.

*OFF: The ATTN key handler specified in the program (PGM) parameter is not called when the ATTN key is pressed.

Examples for SETATNPGM

Example 1: Setting the ATTN Key Handler 

SETATNPGM  PGM(QGPL/ATTN)  SET(*ON)

This command causes the program QGPL/ATTN to become the ATTN key handler. Because SET(*ON) is specified, the program is called when the ATTN key is pressed.

Example 2: Setting the Attention Key Off 

SETATNPGM  PGM(*CURRENT)  SET(*OFF)

The current attention handling program has its status changed to SET(*OFF). Because the status is SET(*OFF) when the ATTN key is pressed, the attention handling program is not called.

Example 3: Previous Recursion-Level Support 

SETATNPGM  PGM(*PRVINVLVL)

The attention handling program and status that was in effect at the previous recursion level is reinstated at this recursion level. If no attention handler is in effect, after this command is run nothing happens when the ATTN key is pressed.

Example 4: Emulating the System Request Key 

SETATNPGM  PGM(QWSSYSRQ)

The system-supplied program QWSSYSRQ will be called when the ATTN key is pressed. This system program allows the ATTN key to act as a system request key by showing the system request menu on the display when the ATTN key is pressed.

Error messages for SETATNPGM

*ESCAPE Messages

CPF1318
Attention key program &1 in &2 not set.