ON command (PL/I)

The ON command establishes the actions to be executed when the specified PL/I condition is raised. This command is equivalent to AT OCCURRENCE.

>>-ON--+-CONDITION--(--condition_name--)---------+-------------->
       +-+-ENDFILE-------+--(--file_reference--)-+   
       | +-ENDPAGE-------+                       |   
       | +-KEY-----------+                       |   
       | +-NAME----------+                       |   
       | +-PENDING-------+                       |   
       | +-RECORD--------+                       |   
       | +-TRANSMIT------+                       |   
       | '-UNDEFINEDFILE-'                       |   
       +-AREA------------------------------------+   
       +-ATTENTION-------------------------------+   
       +-CONVERSION------------------------------+   
       +-ERROR-----------------------------------+   
       +-FINISH----------------------------------+   
       +-FIXEDOVERFLOW---------------------------+   
       +-OVERFLOW--------------------------------+   
       +-SIZE------------------------------------+   
       +-STRINGRANGE-----------------------------+   
       +-STRINGSIZE------------------------------+   
       +-SUBSCRIPTRANGE--------------------------+   
       +-UNDERFLOW-------------------------------+   
       '-ZERODIVIDE------------------------------'   

>--command--;--------------------------------------------------><

condition_name

A valid PL/I CONDITION condition name.

file_reference

A valid PL/I file constant, file variable (can be qualified), or an asterisk (*). If you use an asterisk (*), the breakpoint is activated for all file references associated with the condition used in the ON command.

command

A valid Debug Tool command.

Usage notes

• You must abide by the PL/I restrictions for the particular condition.
• An ON action for a specified PL/I condition remains established until:
  • Another ON command establishes a new action for the same condition. In other words, the breakpoint is replaced.
  • A CLEAR command removes the ON definition.
• For Enterprise PL/I, you cannot use file variables in the file_reference field.
• The ON command occurs before any existing ON-unit in your application program. The ON-unit is processed after Debug Tool returns control to the language.
• The following are accepted PL/I abbreviations for the PL/I condition constants:
  • ATTENTION or ATTN
  • FIXEDOVERFLOW or FOFL
  • OVERFLOW or OFL
  • STRINGRANGE or STRG
  • STRINGSIZE or STRZ
  • SUBSCRIPTRANGE or SUBRG
  • UNDEFINEDFILE([file_reference]) or UNDF([file_reference])
  • UNDERFLOW or UFL
  • ZERODIVIDE or ZDIV
• The preferred form of the ON command is AT OCCURRENCE. For compatibility with PLITEST and INSPECT, however, it is recognized and processed. ON should be considered a synonym of AT OCCURRENCE. Any ON commands entered are logged as AT OCCURRENCE commands.
• The ON command cannot be used while you replay recorded statements by using the PLAYBACK commands.

Examples

• Display a message if a division by zero is detected.

  ON ZERODIVIDE BEGIN;
    LIST 'A zero divide has been detected';
  END;

• Display and patch the error character when converting character data to numeric.
  Given a PL/I program that contains the following statements:

  DECLARE i FIXED BINARY(31,0);
    .
    ..
    ..
  i = '1s3';

  The following Debug Tool command would display and patch the error character when converting the character data to numeric:

  ON CONVERSION
    BEGIN;
      LIST (%STATEMENT, ONCHAR);
      ONCHAR = '0';
      GO;
    END;

  '1s3' cannot be converted to a binary number so CONVERSION is raised. The ON CONVERSION command lists the offending statement number and the offending character: 's'. The data will be patched by replacing the 's' with a character zero, 0, and processing will continue.

Refer to the following topics for more information related to the material discussed in this topic.

• Related references
• AT OCCURRENCE command
• Enterprise PL/I for z/OS Language Reference