Start Debug (STRDBG)

The Start Debug (STRDBG) command puts a job into debug mode and, optionally, adds as many as 20 programs and 20 service programs and 20 class files 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.

The graphical system debugger will be launched instead of the traditional system debugger if the STRDBG command is issued by a user registered for graphical debugging.

Debug can operate in three environments at the same time. They are OPM (Original Program Model), ILE (Integrated Language Environment), and JAVA. Some parameters for this command are applicable for all three environments. Some parameters for this command are applicable only for OPM, ILE, or JAVA. There will be 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 the ADDPGM command will be in the OPM debug environment.

When one job is servicing another job, and STRDBG 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 topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.

Restrictions:

Parameters

Keyword Description Choices Notes
PGM Program Single values: *NONE
Other values (up to 20 repetitions): Qualified object name
Optional, Positional 1
Qualifier 1: Program Name
Qualifier 2: Library Name, *LIBL, *CURLIB
DFTPGM Default program Name, *PGM, *NONE Optional
MAXTRC Maximum trace statements Integer, 200 Optional
TRCFULL Trace full *STOPTRC, *WRAP Optional
UPDPROD Update production files *NO, *YES Optional
OPMSRC OPM source level debug *NO, *YES Optional
SRVPGM Service program Single values: *NONE
Other values (up to 20 repetitions): Qualified object name
Optional
Qualifier 1: Service program Name
Qualifier 2: Library Name, *LIBL, *CURLIB
CLASS Class file Values (up to 20 repetitions): Path name, *NONE Optional
DSPMODSRC Display module source *PGMDEP, *NO, *YES Optional
SRCDBGPGM Source debug program Single values: *SYSDFT
Other values: Qualified object name
Optional
Qualifier 1: Source debug program Name
Qualifier 2: Library Name, *LIBL, *CURLIB
UNMONPGM Unmonitored message program Single values: *NONE
Other values: Qualified object name
Optional
Qualifier 1: Unmonitored message program Name
Qualifier 2: Library Name, *LIBL, *CURLIB
DBGENCKEY Decryption key Character value, *NONE Optional

Program (PGM)

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

This parameter is applicable in both OPM and ILE environments.

Single values

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

Other values (up to 20 repetitions)

Qualifier 1: Program

name
Specify the name of the program to debug. You cannot debug two programs that have the same name at the same time in the OPM debug environment. In the ILE debug environment, two programs with the same name can be debugged if they are in different libraries.

Qualifier 2: Library

*LIBL
All libraries in the library list for the current thread are searched until the first match is found.
*CURLIB
The current library for the job is used to locate the program. If no library is specified as the current library for the job, QGPL is used.
name
Specify the library where the program is located.

Default program (DFTPGM)

Specifies the original program model (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 for which the user specified a value of *DFTPGM for the Program (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 on the PGM parameter of this command is to be the default program for the job's debugging session. If there is more than one program name specified on the PGM parameter, the first OPM program named in the list that is added to the OPM debug environment is the default program. If *NONE is specified on the PGM parameter, or is the default, *NONE is also assumed when this value (*PGM) is specified.
*NONE
No program is specified as the default program; if a program was specified as a default program, it is no longer the default program. If the job has no default program, *DFTPGM cannot be specified on the PGM parameter of any other debug commands.
name
Specify the name of the program to use as the default program during debug mode. The same name (in qualified form) must also be specified for the PGM parameter of this command. You cannot specify a bound program 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 cannot be a default program for the OPM debug environment.

Maximum trace statements (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 specified, the system performs the actions specified by the value supplied for the Trace full (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 the value for the TRCFULL parameter to *STOPTRC.

This parameter is applicable only in the OPM environment.

200
Two hundred trace statements can be put into the file before tracing is stopped or wrapping occurs.
integer
Specify the maximum number of trace statements that can be in the trace file.

Trace full (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 value supplied for the Maximum trace statements (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 will complete processing with no 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.

Update production files (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 environments.

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

OPM source level debug (OPMSRC)

Specifies that original program model (OPM) programs are 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 CL, OPM RPG and OPM COBOL programs that were created with OPTION(*LSTDBG) with the CRTCLPGM, 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 are used for OPM programs.
*YES
ILE debug functions are used for OPM programs.

Service program (SRVPGM)

Specifies 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 the Display Module Source (DSPMODSRC) command.

This parameter is applicable only in the ILE environment.

Single values

*NONE
No service program names are specified at the start of the debugging session. The Display Module Source (DSPMODSRC) command can be used to add service programs later.

Other values (up to 20 repetitions)

Qualifier 1: Service program

name
Specify the name of the service program to debug.

Qualifier 2: Library

*LIBL
All libraries in the library list for the current thread are searched until the first match is found.
*CURLIB
The current library for the job is used to locate the service program. If no library is specified as the current library for the job, QGPL is used.
name
Specify the library where the service program is located.

Class file (CLASS)

Specifies up to 20 class files to debug in the job. Before a class file can be debugged, its name must be specified on this parameter or the Display Module Source (DSPMODSRC) command.

This parameter is applicable only in the ILE environment.

*NONE
No class files are specified at the start of the debugging session. The Display Module Source (DSPMODSRC) command can be used to add class files later.
path-name
Specify the path names of the class file to debug.

Display module source (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 (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.

Source debug program (SRCDBGPGM)

Specifies the source debug program to be used. See the APIs topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/ for an explanation of this parameter.

This parameter is applicable only in the ILE environment.

Single values

*SYSDFT
The system source debug program is used.

Qualifier 1: Source debug program

name
Specify the name of the program to be used to debug programs.

Qualifier 2: Library

*LIBL
All libraries in the library list for the current thread 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.
name
Specify the name of the library to be searched.

Unmonitored message program (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:

  1. Program name (10 bytes). Specifies the name of the program in which the breakpoint was reached.
  2. 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.
  3. 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.
  4. 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.
  5. Message ID (7 bytes). Specifies the ID of the message that was not monitored.
  6. Message data (256 bytes). Specifies the first 256 bytes of message data sent with the message not monitored.
  7. Message data length (5 bytes). Specifies the length of the message data sent with the message not monitored.
  8. 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.

Single values

*NONE
No program is called when a message that is not monitored occurs.

Qualifier 1: Unmonitored message 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.

Qualifier 2: Library

*LIBL
All libraries in the library list for the current thread 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.
name
Specify the name of the library to be searched.

Decryption key (DBGENCKEY)

Enter the key that was specified as the encryption key when the program was compiled. A specified key value of less than 16 bytes will be padded to 16 bytes with x'40'.

If the key contains any characters which are not invariant over all code pages, ensure that the job CCSID is the same as the job CCSID used when the program was compiled, otherwise the key may not match, and the decryption will fail.

Single values

*NONE
No decryption key is specified at the start of the debugging session. A decryption key can be specified later using Enter decryption key panel.

Other values

Qualifier 1: Decryption key.

key
Specifies the 16 byte key to be used in the decryption of encrypted debug text views.A specified key value of less than 16 bytes will be padded to 16 bytes with x'40'.

Examples

Example 1: Start Debug for Program

STRDBG   PGM(TESTLIB/PAYROLL)  UPDPROD(*NO)

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.

Example 2: Start Debug for Class File

STRDBG   CLASS('financial.payapplet')

This command starts debug mode to debug the class payapplet in the financial package.

Error messages

*ESCAPE Messages

CPF1999
Errors occurred on command.