Creating a commands file

A commands file is a convenient method of reproducing debug sessions or resuming interrupted sessions. Use one of the following methods to create a commands file:

  • Record your debug session in a log file and then use the log file as a commands file. This is the fastest way to create a valid commands file.
  • Create a commands file manually. Data sets used by z/OS Debugger describes the requirements for this file and when z/OS® Debugger processes it.

When you create a commands file that might be used in an application program that was created with several different programming languages, you might want to use z/OS Debugger commands that are programming language neutral. The following guidelines can help you write commands that are programming language neutral:

  • Write conditions with the %IF command.
  • Delimit strings and long compile unit names with quotation marks (").
  • Prefix a hexadecimal constant with an X or x, followed by an apostrophe ('), then suffix the constant with an apostrophe ('). For example, you can write the hexadecimal constant C1C2C3C4 as x'C1C2C3C4'.
  • Group commands together with the BEGIN and END commands.
  • Check the IBM® z/OS Debugger Reference and Messages to determine if a command works with only specific programming languages.
  • Type in comments beginning at column 2 and not extending beyond column 72. Begin comments with "/*" and end them with "*/".

For PL/I programs, if your commands file has sequence numbers in columns 73 through 80, you must enter the SET SEQUENCE ON command as the first command in the commands file or before you use the commands file. After you enter this command, z/OS Debugger does not interpret the data in columns 73 through 80 as a command. Later, if you want z/OS Debugger to interpret the data in columns 73 through 80 as a command, enter the command SET SEQUENCE OFF.

For C and C++ programs, if you use commands that reference blocks, the block names can differ if the same program is compiled with either the ISD or DWARF compiler option. If your program is compiled with the ISD compiler option, z/OS Debugger assigns block names in a sequential manner. If your program is compiled with the DWARF compiler option, z/OS Debugger assigns block names in a non-sequential manner. Therefore, the names might differ. If you switch compiler options, check the block names in commands you use in your commands file.

At runtime, a commands file can be specified through one of the following methods:
  • Directly, for example, through the TEST runtime option.
  • Through the EQAOPTS COMMANDSDSN command. If that file has a member in it that matches the name of the initial load module in the first enclave, z/OS Debugger reads that member as a commands file.
To learn how to specify EQAOPTS commands, see the topic EQAOPTS commands in the IBM z/OS Debugger Reference and Messages or IBM z/OS Debugger Customization Guide. To learn about what format to use for the commands file, see Data sets used by z/OS Debugger.

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

  • Related references
  • BEGIN command in IBM z/OS Debugger Reference and Messages
  • %IF command in IBM z/OS Debugger Reference and Messages