Attention key handling program

You can identify a program as the Attention-key-handling program at a particular call level. The Attention-key-handling program runs in the same job and has the same job attributes, overrides, and group authorities as the program that issued the SETATNPGM command. However, program-adopted authority does not originate from the program that was interrupted. You may also specify an Attention-key-handling program in the user profile.

Identifying a program as attention key handling

To identify a program as the Attention-key-handling program, use the Set Attention Program (SETATNPGM) command with SET(*ON) specified. This command identifies this program at that call level in the job running the command. When the Attention key is pressed, the running job is interrupted, the display is saved, and the Attention-key-handling program is called. No parameters are passed to the Attention-key-handling program when it is called.
Note: The Pre-attention Program exit program is called when the user presses the System Attention key. The operating system calls the user-written exit program through the registration facility when the user presses the System Attention key. There are no input or output parameters. After the exit programs from the registration facility are called, the system attention program is called.

Effect of call level on attention key status

The SETATNPGM command is call-oriented. That is, a SETATNPGM command issued at one call level causes the Attention-key-handling program to be in effect at the current call level as well as lower call levels, until another SETATNPGM command is run to change the Attention-key-handling program or Attention key status. Whenever a program that issued a SETATNPGM command returns, the display is restored and the Attention-key-handling program and Attention key status are reset to what they were before the current call. If a Transfer Control (TRFCTL) command is used instead of a RETURN command, the status is not reset until the program that was transferred to returns.

When to use the attention key

Use the Attention key to call an Attention-key-handling program. In normal workstation use, the Attention key can be pressed only when the keyboard is unlocked; that is, the program is ready for input. This occurs when a read or write-read operation is issued or the UNLOCK DDS keyword is used in a write operation.

The use of the Attention key differs from that of the System Request key in that the application program has control over when it can be interrupted.

Exception

An exception to this occurs with application programs performing a get-no-wait operation on multiple device files. Pressing the Attention key causes these programs to be interrupted at any point by the Attention-key-handling program. (Even though the input inhibited light may be on, the keyboard is unlocked during a get-no-wait operation.) Application programs performing sensitive functions (especially during a get-no-wait operation) should therefore be protected by running SETATNPGM PGM(*CURRENT) SET(*OFF) before and SETATNPGM PGM(*CURRENT) SET(*ON) after sensitive code.
Note: A high-level language program can use the SETATNPGM command by calling QCMDEXC.

When not to use the attention key

The Attention key cannot be used to call an Attention-key-handling program when the following conditions exist:
  • The keyboard is locked. (Note the exception described earlier for get-no-wait operations.)
  • The System Request menu or any of its options is being used.
  • The display message display is shown.
  • The IBM i licensed program is already calling the Attention-key-handling program that makes it already active; however, if the program issues another SETATNPGM, the Attention key is enabled.

Attention key handling program coding tips

Caution is necessary when defining an Attention-key-handling program because the Attention-key-handling program runs in the same job as the program that is in progress when the Attention key is pressed. Therefore, the interrupted program is not protected by any locks it holds. If the interrupted program has an exclusive lock on an object, the Attention key program, because it runs in the same job, is part of the job that has the exclusive lock.

The following guidelines are recommended for defining Attention-key-handling programs:
  • Use simple functions such as menus that allow the workstation user to transfer to another group job or to a secondary interactive job.
  • Avoid referring to objects or functions that may be in use when the Attention key is pressed.
  • Avoid calling non-recursive functions when the Attention key is pressed. Non-recursive functions are functions that cannot be interrupted and then called again. Many functions, such as high-level language programs and utilities like DFU, are non-recursive.
  • Avoid giving an option that allows the workstation user to display the command entry display as part of the current job. For users who are programmers, it is meaningful to display a menu that includes an option for the command entry display. The command entry display should be specified as a separate group job (for example, by specifying INLGRPPGM(QCMD) on the TFRGRPJOB command). This avoids re-using objects already in use.
  • Attention-key-handling programs do not have the authority adopted by the program that was in progress before the Attention key was pressed.
  • Attention-key-handling programs do not have their own data area (*LDA). Since there is only one local data area per job, and the Attention-key-handling program runs in the same job as the interrupted program, both programs share the same local data area.
  • Be aware that a 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 on return to the program in progress. For example, if the following conditions are met, the program exits on return from the Attention key handler:
    • The WAITRCD value in the file is set to 60 seconds.
    • The program is set to exit if a key is not pressed in one minute.
    • The Attention key program is called and runs longer than that minute.
    However, caution should be used, since a check for available data is made before checking that the time-out has completed. If a key is pressed immediately after leaving the Attention key handler, data could be available that could complete the read-from-invited devices and the time-out would not be checked. This could cause unexpected results.