AT CALL command

Gives z/OS® Debugger control when the application code attempts to call the specified entry point. Using CALL breakpoints, you can simulate the execution of unfinished subroutines, create dummy or stub programs, or set variables to mimic resultant values, allowing you to test sections of code before the whole is complete.

Read syntax diagramSkip visual syntax diagramATevery_clauseCALLentry_name(,entry_name)*command;
entry_name
A valid external entry point name constant or zero (0); however, 0 can only be specified if the current programming language setting is C or PL/I.
*
Sets a breakpoint at every CALL of any entry point.
command
A valid z/OS Debugger command.

Usage notes

  • AT CALL intercepts the call itself, not the subroutine entry point. C, COBOL, and PL/I programs compiled with the PATH suboption of the TEST or DEBUG compiler option identify call targets even if they are unresolved.
  • A breakpoint set with AT CALL for a call to a C, C++, or PL/I built-in function is never triggered.
  • AT CALL intercepts calls to entry points known to z/OS Debugger at compile time. Calls to entry variables are not intercepted, except when the current programming language setting is either C or COBOL (compiled with the TEST run-time option).
  • AT CALL 0 intercepts calls to unresolved entry points when the current programming language setting is C or PL/I (compiled with the TEST run-time option).
  • AT CALL allows you to intercept or bypass the target program by using GO BYPASS or GOTO. If resumed by a normal GO or STEP, execution resumes by performing the call.
  • If you set a breakpoint in a parent enclave, the breakpoint can be triggered and operated on with breakpoint commands while the application is in a child enclave.
  • While debugging a CICS® application, the breakpoint is cleared at the end of the last process in the CICS application. While debugging a non-CICS application, the breakpoint is cleared at the end of a process.
  • The AT CALL command cannot be used while you replay recorded statements by using the PLAYBACK commands.
  • You cannot use the AT CALL command while you debug a disassembly program.
  • z/OS Debugger does not support the AT CALL command while you debug a LangX COBOL or any VS COBOL II program.
  • For C and C++ only: The following usage notes apply:
    • If your C and C++ program has unresolved entry points or entry variables, enter the command AT CALL 0.
    • To be able to set breakpoints in a C program using the AT CALL command, you must compile your program in one of the following ways:
      • With either the PATH or ALL suboption of the TEST compiler option.
      • With either the PATH or ALL suboption of the DEBUG compiler option.
    • To be able to set breakpoints in a C++ program using the AT CALL command, you must compile your program in one of the following ways:
      • With the TEST compiler option.
      • With either the PATH or ALL suboption of the DEBUG compiler option.
  • For COBOL only: The following usage notes apply:
    • entry_name can refer to a method as well as a procedure.
    • If entry_name is case sensitive, enclose it in quotation marks (") or apostrophes (').
    • To be able to set breakpoints in a COBOL program by using the AT CALL command, you must compile your program with the correct TEST compiler suboptions. The following list describes the TEST compiler suboptions to use for the corresponding version of the COBOL compiler:
      • Specify the HOOK or NOHOOK suboption of the TEST compiler option for Enterprise COBOL for z/OS, Version 4
      • Specify the PATH, ALL, or NONE suboption of the TEST compiler option for the following compilers:
        • Enterprise COBOL for z/OS and OS/390®, Version 3
        • COBOL for OS/390 & VM, Version 2
      If you compile your program with one of the following compilers and suboptions, you cannot use the AT CALL entry_name command:
      • It is not supported for Enterprise COBOL for z/OS Version 5.
      • NOHOOK suboption of the TEST compiler option for Enterprise COBOL for z/OS, Version 4.
      • NONE suboption of the TEST compiler option for the following compilers:
        • Enterprise COBOL for z/OS and OS/390, Version 3.
        • COBOL for OS/390 & VM, Version 2.
      Instead, use AT CALL *.
    • AT CALL 0 is not supported for use with COBOL programs. However, COBOL is able to identify CALL targets even if they are unresolved, and also identify entry variables and intercept them. Therefore, not all external references need be resolved for COBOL programs.
  • For PL/I only: The following usage notes apply:
    • To be able to set CALL breakpoints in PL/I, you must compile your program with either the PATH or ALL suboptions of the TEST compiler option. AT CALL 0 is supported and is called for unresolved external references.
    • CALL statements within an INITIAL attribute on a PL/I variable declaration will not trigger AT CALL breakpoints.
  • For assembler only: A CALL statement can be a call to an internal or external routine. A CALL statement is defined to be one of the following opcodes: BALR, BASR, BASSM, BAL, BAS, BRASL, SVC, or PC. You can use the command AT CALL MVS to give z/OS Debugger control at any SVC or PC instruction.

Examples

  • Intercept all calls and request input from the terminal. 
    AT CALL *;
  • If the program starts function badsubr, intercept the call, set variable varbl to 50, and then bypass the target function. The current programming language setting is C. 
    AT CALL badsubr {
  varbl = 50;
  GO BYPASS;
}

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