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.

Read syntax diagramSkip visual syntax diagramONCONDITION(condition_name)ENDFILEENDPAGEKEYNAMEPENDINGRECORDTRANSMITUNDEFINEDFILE(file_reference)AREAATTENTIONCONVERSIONERRORFINISHFIXEDOVERFLOWOVERFLOWSIZESTRINGRANGESTRINGSIZESUBSCRIPTRANGEUNDERFLOWZERODIVIDEcommand;
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 z/OS® Debugger 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 z/OS Debugger 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 z/OS Debugger 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.