STRDBG (Start Debug)
Purpose
The Start Debug (STRDBG) command puts a job into debug mode and, optionally, adds as many as 20 programs and 20 class files and 20 service programs to debug mode. It also specifies certain attributes of the debugging session. For example, it can specify whether database files in production libraries can be updated while in debug mode.
Debug can operate in two environments at the same time. They are OPM (Original Program Model) and ILE (Integrated Language Environment). Some parameters for this command are applicable for both environments. Some parameters for this command are applicable only for either OPM or ILE. There is a statement in each parameter description stating the environment in which the parameter is applicable.
The Change Debug (CHGDBG) command can be used later in the job to change the attributes of the debug mode. Also, OPM programs can be added to or removed from the debugging session if they are specified in the Add Program (ADDPGM) or Remove Program (RMVPGM) commands. OPM programs added with ADDPGM command will be in the OPM debug environment.
When one job is servicing another job, and the STRDBG command is entered, all debug commands are valid for the job being serviced. If that job is held on a job queue, no further debug commands may be entered until that job is allowed to run. When the job starts, an initial breakpoint screen is displayed. From this screen, additional debug commands may be entered. To service another job, see the STRSRVJOB (Start Service Job) command. More information about debugging one job from another job is in the CL Programming book.
Restrictions
- This command is not valid in debug mode. To end debug mode, refer to the ENDDBG (End Debug) command.
- This command cannot be used if the user is servicing another job, and that job is held, suspended, or ending.
- This command is shipped with public *EXCLUDE authority, and the QPGMR, QSRV, and QSRVBAS user profiles have private authorities to use this command.
- The user must have either *CHANGE authority to the program or *USE authority to the program and *SERVICE special authority.
Note: Do not precede an entry with an asterisk unless that entry is a special value that is shown (on the display itself or in the help information) with an asterisk.
Optional Parameters
- PGM
- Specifies the qualified names of up to 20 programs to debug in the job. Before a program can be debugged, its name must be specified on this parameter, in the Add Program (ADDPGM) command or the Display Module Source (DSPMODSRC) command.
You can enter multiple values for this parameter. If you are on an entry display and you need additional entry fields to enter these multiple values, type a plus sign (+) in the entry field opposite the phrase "+ for more" and press the Enter key.
This parameter is applicable in both OPM and ILE environment.
*NONE: No program names are specified at the start of the debugging session. The Add Program (ADDPGM) command or the Display Module Source (DSPMODSRC) command can be used to add programs later.
The name of the program can be qualified by one of the following library values:
*LIBL: All libraries in the job's library list are searched until the first match is found.
*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.
library-name: Specify the name of the library to be searched.
program-name: Specify the names of up to 20 programs to debug. The user cannot debug two programs that have the same name at the same time in the OPM debug environment. In the ILE debug environment, 2 programs with the same name can be debugged if they are in different libraries.
- DFTPGM
- Specifies the name of the OPM program to use as the default program during debug mode. The program specified here is used as the default program for any of the other debug commands that specify *DFTPGM on their PGM parameter. That is, if a default program was previously specified, this parameter can change it.
This parameter is applicable only in the OPM environment.
*PGM: The program named in the PGM parameter of this command is the default program for the job's debugging session. If PGM has more than one program name specified, the first OPM program named in the list that is added to the OPM debug environment is the default program. If PGM(*NONE) is specified or is the default, DFTPGM(*NONE) is also assumed when *PGM is specified here.
*NONE: No program is specified as the default program. If the job has no default program, *DFTPGM cannot be specified on the PGM parameter of any other debug commands.
program-name: Specify the name of the program to use as the default program during debug mode. The same qualified name must also be specified in the PGM parameter of this command. A bound program cannot be specified on this parameter.
Note: If OPMSRC(*YES) is specified, the OPM program may be added to either the OPM debug environment or the ILE debug environment. If added to the ILE debug environment, then it can not be a default program for the OPM debug environment. - MAXTRC
- Specifies the maximum number of trace statements that the system puts into the job's trace file before either stopping tracing, or wrapping around (overlaying) on the trace file. When the trace file contains the maximum number specified, the system performs the actions specified in the TRCFULL parameter.
Note: Instruction stepping can be performed on a program being debugged in an interactive environment by setting the maximum number of trace statements to 1 and specifying *STOPTRC on the TRCFULL parameter. This parameter is applicable only in the OPM environment.
200: Up to 200 trace statements can be put into the trace file before tracing is ended or wrapping on the file occurs.
maximum-trace-statements: Specify the maximum number of trace statements that can be in the trace file.
- TRCFULL
- Specifies what happens when the job's trace file is full; that is, it contains the maximum number of trace statements specified by the MAXTRC parameter.
This parameter is applicable only in the OPM environment.
*STOPTRC: In a batch environment, tracing stops but the program continues processing. In an interactive environment, control is given to the user when a breakpoint occurs. If the user continues processing, a breakpoint occurs before processing each subsequent statement within the range of statements being traced, and the trace file is extended to contain the new entry.
*WRAP: The trace file is overlaid with new trace statements as they occur, wrapping from the beginning of the file. The program completes processing without sending a message to indicate that wrapping has occurred. The trace file never has more than the maximum specified statements, and they are the most recently recorded statements.
- UPDPROD
- Specifies whether or not database files in a production library can be opened for updating records, or for adding new records, while the job is in debug mode. If not, the files must be copied into a test library before trying to run a program that uses the files.
This parameter is applicable in both OPM and ILE environment.
*NO: Database files in production libraries cannot be updated while the job is in debug mode. Database files can be opened for reading only. This protects database files from unwanted updates while a program is being debugged. The exception to this is starting debug mode after a production library is already opened. This is possible if the file is opened with SHARE(*YES) in a different program first. To prevent this, start debug mode before any files are opened, or use SHARE(*NO) on the Override Database File (OVRDBF) command for all files used in the programs being debugged. If this value is specified, some commands, which may include function keys, menu options, or pulldowns, may not work properly.
*YES: Database files in production libraries can be updated while the job is in debug mode.
- DSPMODSRC
- Specifies whether the first display of the source debug program is shown when this command is processed and no errors occur.
This parameter is applicable only in the ILE environment.
*PGMDEP: The showing of the source debug program display is dependent on the programs specified on the program prompt (PGM) parameter. If any of the programs are ILE programs, the display is shown. If any of the programs are OPM programs with source debug data, and OPMSRC(*YES) is specified, the display is shown. If all of the programs are OPM programs and OPMSRC(*NO) is specified, the display is not shown.
*NO: The first display of the source debug program is not shown.
*YES: The first display of the source debug program is shown.
- SRCDBGPGM
- Specifies the source debug program to be used.
This parameter is applicable only in the ILE environment.
*SYSDFT: The system source debug program is used.
The name of the program can be qualified by one of the following library values:
*LIBL: All libraries in the job's library list are searched until the first match is found.
*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.
library-name: Specify the name of the library to be searched.
program-name: Specify the name of the program to be used to debug programs.
- UNMONPGM
- Specifies the qualified name of the user-supplied program called when a message that is not monitored occurs in the job being debugged. When the program specified is called, it is passed parameters that identify the program name, the recursion level, the high-level language statement identifier, the machine instruction number at which the breakpoint occurred, the message that was not monitored, the message data, the length of the message data, and the message reference key.
This parameter is applicable only in the OPM environment.
The passed parameters have the following formats:
- Program name (10 bytes). Specifies the name of the program in which the breakpoint was reached.
- Recursion level (5 bytes). Specifies the recursion level number of the program in which the breakpoint was reached. This value is a 1- to 5-digit number padded on the right with blanks.
- Statement Identifier (10 bytes). Specifies the high-level language program statement identifier that was reached. This is the statement identifier specified on the Add Breakpoint (ADDBKP) command. If a machine instruction number is used to specify the breakpoint, this parameter contains a slash (/) followed by a 4-digit hexadecimal machine instruction number.
- Instruction number (5 bytes). Specifies the machine instruction number that corresponds to the high-level language statement at which the breakpoint was reached. No slash appears in front of the machine instruction number. The value consists of 1 to 4 hexadecimal characters representing the MI instruction number, followed by one or more blanks. If a machine instruction number is passed on the third parameter, the numbers in the third and fourth parameters are the same.
- Message ID (7 bytes). Specifies the ID of the message that was not monitored.
- Message data (256 bytes). Specifies the first 256 bytes of message data sent with the message not monitored.
- Message data length (5 bytes). Specifies the length of the message data sent with the message not monitored.
- Message MRK (4 bytes). Specifies the message reference key (MRK) of the message not monitored.
All the parameter values are left-adjusted and padded on the right with blanks. When control returns to the program with the message that was not monitored, processing continues.
*NONE: No program is called when a message that is not monitored occurs.
The name of the program can be qualified by one of the following library values:
*LIBL: All libraries in the job's library list are searched until the first match is found.
*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.
library-name: Specify the name of the library to be searched.
program-name: Specify the name of the user-supplied program called when a message that is not monitored occurs in the job being debugged. After the program runs, control is returned to the interrupted program.
- OPMSRC
- Specifies that OPM programs will be debugged using the system source debug support (same as ILE source debug).
This parameter is valid for OPM CL, OPM RPG and OPM COBOL programs that were created with OPTION(*SRCDBG) with CRTCLPGM, CRTRPGPGM and CRTCBLPGM commands. Additionally, this parameter is valid for OPM RPG and OPM COBOL programs that were created with OPTION(*LSTDBG) with the CRTRPGPGM, CRTCBLPGM, CRTSQLRPG, CRTSQLCBL, and CRTRPTRPG commands. If the OPM program is not CL, RPG or COBOL and was not compiled with a valid debug option, then this parameter is ignored.
This parameter is applicable in both OPM and ILE environment.
ILE functions will now operate on OPM programs. For example, source level debug.
*NO: OPM debug functions will be used for OPM programs.
*YES: ILE debug functions will be used for OPM programs.
- SRVPGM
- Specifies the qualified names of up to 20 service programs to debug in the job. Before a service program can be debugged, its name must be specified on this parameter, or in the debugger user interface.
You can enter multiple values for this parameter. If you are on an entry display and you need additional entry fields to enter these multiple values, type a plus sign (+) in the entry field opposite the phrase "+ for more" and press the Enter key.
This parameter is applicable only in the ILE environment.
*NONE: No service program names are specified at the start of the debugging session. The debugger user interface can be used to add service programs later.
The name of the program can be qualified by one of the following library values:
*LIBL: All libraries in the job's library list are searched until the first match is found.
*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.
library-name: Specify the name of the library to be searched.
service-program-name: Specify the names of up to 20 service programs to debug.
- CLASS
- Specifies class file name to debug. A maximum of twenty class file names are allowed on the STRDBG command. Each name may be up to 5000 characters long. After debug is started more class files may be added to debug through the debugger user interface.
This parameter is applicable only in the ILE environment.
*NONE: No class file names are specified at the start of the debugging session. The debugger user interface can be used to add class files later.
class-file-name: Specify the class file names to debug.
Examples for STRDBG
STRDBG PGM(TESTLIB/PAYROLL)This command starts debug mode to debug the program PAYROLL, which is in the test library TESTLIB. If tracing is used, up to 200 trace statements can be stored in the trace before tracing stops. If program PAYROLL is a bound program, the Display Module Source display will be shown, giving the source for the module that contains the program entry point. Any database files updated by the PAYROLL program must be in a test library.
STRDBG CLASS('financial.payapplet')This command starts debug mode to debug the class payapplet in the financial package.
Error messages for STRDBG
*ESCAPE Messages
- CPF1999
- Errors occurred on command.