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 information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.

Restrictions:

You cannot use this command in debug mode. To end debug mode, refer to the End Debug (ENDDBG) command.
You cannot use this command if you are 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.
You must have either *CHANGE authority to the program, or *USE authority to the program and *SERVICE special authority.

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

Top

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.

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 System API Reference information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/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:

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.

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.

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.