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.

*

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 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.