AT LABEL command

Gives z/OS® Debugger control when execution has reached the specified statement label or group of labels. For C and PL/I, if there are multiple labels associated with a single statement, you can specify several labels and z/OS Debugger gains control at each label. For COBOL and LangX COBOL, AT LABEL lets you specify several labels, but for any group of labels that are associated with a single statement, z/OS Debugger gains control for that statement only once.

Read syntax diagramSkip visual syntax diagramATevery_clauseLABELstatement_label'statement_label'(,statement_label)(,'statement_label')*LOCAL%CUcu_speccommand;
*
Sets a breakpoint at every LABEL.
LOCAL
Specifies that the AT LABEL breakpoint is limited to all labels in the specified compile unit.
cu_spec
A valid compile unit specification.
command
A valid z/OS Debugger command.
Usage notes
  • Use the syntax of statement_label enclosed in apostrophes (') only for LangX COBOL programs. It is not supported in any other programming language.
  • z/OS Debugger does not support the AT LABEL command with VS COBOL II programs.
  • A COBOL statement_label can have either of the following forms:
    • name

      This form can be used in COBOL for reference to a section name or for a COBOL paragraph name that is not within a section or is in only one section of the block.

    • name1 OF name2 or name1 IN name2

      This form must be used for any reference to a COBOL paragraph (name1) that is within a section (name2), if the same name also exists in other sections in the same block. You can specify either OF or IN, but z/OS Debugger always uses OF for output.

    Either form can be prefixed with the usual block, compile unit, and load module qualifiers.

  • For C, C++ or PL/I, you can set a LABEL breakpoint at each label located at a statement. This is the only circumstance where you can set more than one breakpoint at the same location.
  • A LABEL breakpoint set for a nonactive compile unit (one that is not in the current enclave) is suspended until the compile unit becomes active. A LABEL breakpoint set for a compile unit that is deleted from storage is suspended until the compile unit is reloaded. A suspended breakpoint cannot be triggered until it is reactivated.
  • For a CICS® application on z/OS Debugger, this breakpoint is cleared at the end of the last process in the application. For a non-CICS application on z/OS Debugger, it is cleared at the end of a process.
  • You cannot set LABEL breakpoints at PL/I label variables.
  • LABEL breakpoints for label constants in a fetched, loaded program or DLL are removed when that program is released.
  • To be able to set LABEL breakpoints in PL/I, you must compile your program with either the PATH and SYM suboptions or the ALL suboption of the TEST compiler option.
  • For C, to be able to set LABEL breakpoints, you must compile your program in one of the following ways:
    • With either the PATH and SYM suboptions or ALL suboption of the TEST compiler option.
    • With either the PATH and SYM suboptions or ALL suboption of the DEBUG compiler option.
  • For C++, to be able to set LABEL breakpoints, you must compile your program in one of the following ways:
    • With the TEST compiler option.
    • With either the PATH and SYM suboptions or ALL suboption of the DEBUG compiler option.
  • You can set breakpoints for more than one label at the same location. z/OS Debugger is entered for each specified label.
  • To be able to set LABEL breakpoints in COBOL programs, you must compile your program with one of the following compilers and TEST compiler suboptions:
    • Specify the HOOK suboption with Enterprise COBOL for z/OS, Version 4
    • Specify the STMT, PATH, or ALL suboption and the SYM suboption with one of the following compilers:
      • any release of the Enterprise COBOL for z/OS and OS/390®, Version 3, compiler
      • any release of the COBOL for OS/390 and VM, Version 2, compiler

    When defining specific LABEL breakpoints z/OS Debugger sets a breakpoint for each label specified, unless there are several labels on the same statement. In this case, only the last LABEL breakpoint defined is set.

  • For COBOL, a reference to a label or a label constant can take either of the following forms:
    • name

      This form is used to refer to a section name or the name of a paragraph contained in not more than one section of the block.

    • name1 OF name2 or name1 IN name2

      This form is used to refer to a paragraph contained within a section if the paragraph name exists in other sections in the same block. You can use either OF or IN, but z/OS Debugger only uses OF for output to the log file.

  • For PL/I users:
    • If you are running any version of VisualAge® PL/I or Enterprise PL/I Version 3 Release 1 through Version 3 Release 3 programs, you cannot use the AT LABEL command.
    • If you are running Enterprise PL/I for z/OS, Version 3.4, or later, programs and you comply with the following requirements, you can use the AT LABEL command to set breakpoints (except at a label variable):
      • If you are running z/OS Version 1 Release 6, apply the Language Environment® PTF for APAR PQ99039.
      • If you are compiling with Enterprise PL/I Version 3 Release 4, apply PTFs for APARs PK00118 and PK00339.
  • You cannot use the AT LABEL command while you use the disassembly view.
  • The AT LABEL command cannot be used while you replay recorded statements by using the PLAYBACK commands.
  • For Enterprise COBOL for z/OS Version 5 and later, AT LABEL * highlights the labels similar to statement breakpoints:
    • When you use AT LABEL *, a global label breakpoint is created. You can use PF6 or AT LINE to remove or recreate a hook at the label.
    • When you toggle hooks, the global label breakpoint created with AT LABEL * is saved in SAVEBPS, but the removal of any individual label hook is not saved.
    • The EVERY clause is not supported, which means highlighting and use of PF6 do not work.
    • PF6 only works in the currently running CU. Using SET QUALIFY CU LOAD::>CU shows highlighted labels if the AT LABEL * command was issued, but PF6 does not work.
    • Highlighting is disabled if PLAYBACK START is issued and enabled once again when PLAYBACK STOP is issued.

Examples

  • Set a breakpoint at label create in the currently qualified block. 
    AT LABEL create;
  • At program label para OF sect1 display variable names x and y and their values, and continue program execution. The current programming language setting is COBOL. 
    AT LABEL para OF sect1 PERFORM
  LIST TITLED (x, y);
  GO;
END-PERFORM;
  • Set a breakpoint at labels label1 and label2, even though both labels are associated to the same statement. The current programming language setting is C. 
    AT LABEL label1 LIST 'Stopped at label1';  /* Label1 is first  */
AT LABEL label2 LIST 'Stopped at label2';  /* Label2 is second */

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