Chapter 15:  PM DEBUG

This facility assists in debugging compiled Process Module (PM) objects.  PM DEBUG (much like that of a symbolic debugger provided with the operating system and third generation languages) has functions that:

• Set up to 16 breakpoints at lines of routines where execution of the PM suspends.
• Set up to 16 watch points at fields where a change in value causes execution to suspend and the statement causing the change to be reported.
• Display and clear breakpoints and watch points.
• Display the contents of Declare Section fields, Global Storage (GS) fields, record fields and system fields.
• Set values into any of the above mentioned fields which are modifiable.
• Step through the execution of the PM, statement by statement.
• Trace PM statements as they are executed, showing the text and line numbers or the line number only.
• Display a PM statement or a range of statements.
• Search for the occurrence of a text string in the text of the PM.

Using PM DEBUG

PM DEBUG cannot be started if the text of the PM has been removed.  This prevents users from viewing a PM that is protected.

If a user wishes to debug a PM with a Code Segment (CS), the COMPOSE facility should be used before starting PM DEBUG.  COMPOSE will make the INCLUDE statement a comment and load the text so that the CS becomes part of the PM text.

There are two ways to start PM DEBUG:

1.     In order to use PM DEBUG with every PM in the application, use:

*ENABLE PM DEBUG<CR>

If the PM DEBUG option is enabled, PM DEBUG always starts when any PM is executed.  The default for the PM DEBUG option is disabled.

2.     In order to debug a specific PM object, enter the name of the PM and the DBL in which it resides in the system field @DEBUG_PM_NAME:

*SET "PAYCHECKS" TO @DEBUG_PM_NAME<CR>

If the system field @DEBUG_PM_NAME has a value in it and the PM DEBUG option is disabled, PM DEBUG still starts when the PM name in the @DEBUG_PM_NAME system field is executed.

Once the PM is executing, PM DEBUG stops at the first executable statement and displays the PM DEBUG prompts.  PM DEBUG commands can be entered at this point.

DBG*

To disable PM DEBUG, the following:

Enter the command:

*DISABLE PM DEBUG<CR>

Clear the System Field @DEBUG_PM_NAME:

*SET "" TO @DEBUG_PM_NAME<CR>

PM DEBUG Commands

The PM DEBUG commands are described next.  The commands are defined in alphabetical order.  A summary of commands appears at the end of this section.

Break COMMAND

PURPOSE:  BREAK specifies a line number or a routine name where execution of the PM is to be suspends (breakpoints).  When a line with a breakpoint is about to be executed, PM DEBUG suspends execution prints the text of the line and waits for a command.  Use the TYPE command to examine fields or the SET command to modify fields in the PM.  Optionally, the statement can be executed a specified number of times before breaking.

SYNTAX

B/REAK/ \\{line_number; routine_name}\\ [AFTER integer]

Example

1.     Sets breakpoints at PM line 510 and 600.

DBG* BREAK 510,600

2.     Sets a breakpoint at line 800 and indicates to stop after every tenth execution.

DBG* B 800 AFTER 10

3.      Sets breakpoints at line 90 and to stop only after every fifth execution and at line 200 and to stop only after every fifth execution.

DBG* B 90,200 AFTER 5

4.     Sets breakpoints at lines 100, 200 and at routine PART_LOOK_UP.

DBG* BREAK 100, PART_LOOK_UP, 200

NOTES:  A routine defined in a CS cannot be used as a breakpoint.  An attempt to do so will display an error message.

SEE ALSO:  CLEAR, SET, TYPE Commands

Clear COMMAND

PURPOSE:  CLEAR removes breakpoints or watch points.

SYNTAX

C/LEAR/ {B/REAK/ \\line_number\\; WATCH \\field_name\\; ALL BREAK; ALL WATCH}

Example

1.     Clears breakpoints at lines 100, 510 and 800.

DBG* CLEAR BREAK 100,510,800

2.     Clears all breakpoints.

DBG* CLEAR ALL BREAK

3.     Clears all watch points.

DBG* CLEAR ALL WATCH

4.     Removes the watch points on the fields GROSS, TAX_RATE, and PERCENT.

DBG* CLEAR WATCH GROSS, TAX_RATE, PERCENT<CR>

SEE ALSO:  BREAK and WATCH Command

Find COMMAND

PURPOSE:  The FIND command finds any character string in the text of the PM being debugged.  (This function is not case sensitive.)  The search is done in the specified line range of the PM.  The line(s) within the specified range that has the search string is displayed to the terminal.

SYNTAX

F/IND/ line_range "string"

Example

DBG* FIND 5:10 "DATE"

DBG* F ^:* "NAME"

DBG* FIND .+2 "LOCATION"

NOTES:  Special characters can be used in the line range specification.  Their meanings are explained below:

circumflex (^) - first line

asterisk (*) - last line

period (.) - current line

plus (+n) - to n lines after current position

minus (-n) - from n lines before current position

SEE ALSO:  PRINT Command

Go COMMAND

PURPOSE:  GO starts PM execution or continues from the point that PM execution was suspended for a break point or watch point.

SYNTAX

G/O/

Example

*DBG GO<CR>

NOTES:  The GO and STEP commands are the only commands that can continue execution of the PM after a break.

SEE ALSO:  STEP and PRINT Command

Print COMMAND

PURPOSE:  PRINT displays a specified PM line or a specified range of lines.

SYNTAX

FORM 1: displays a single line or a range of lines.

P/RINT/ {line_no; ^; *; .} [ : {line_no; ^; *; .}]

FORM 2: displays a line relative to the breakpoint.

P/RINT/ [{+; -} n]

Example

PURPOSE:  SET moves the contents of a field (or a literal value) to another field.  If an error occurs, the SET command aborts and the contents of the destination field are unchanged.

SYNTAX

SE/T/ value; field_name TO field_name

Example

Example 1:  sets 10 to field FI.

DBG* SET 10 to FI

Example 2:  sets the content of @INTEGER (1) to FN.

DBG* SET @INTEGER(1) to FN

NOTES:  To assign a constant value to a date field, an integer of form YYYYMMDD must be used.  The following command moves August, 5 1991 to the field INV_DATE.

DBG* SET 19910805 TO INV_DATE<CR>

The value of a Record Field cannot be set (such as @DS_NAME, @QUALIFIED, and @NEW_RECORDS) to a field with the SET command.

Show COMMAND

PURPOSE:  SHOW displays breakpoint line numbers, watch point field names, source mode setting, and trace mode setting.  SHOW can set the trace mode and source mode.  SHOW can also display the screen for a specified time without the debug information.

SYNTAX

SH/OW/ [B/REAK/; W/ATCH/; [NO] S/OURCE/; [NO] T/RACE/; SCREEN /FOR/ n

/SECONDS/]

Example

DBG* SHOW

Source display is enabled

Trace display is disabled

DBG* BREAK 3300

DBG* SHOW BREAK

Breakpoint at line 3300

DBG* SH SCREEN 10

(If there is an active screen, it will be displayed for 10 seconds then control is returned to the debugger.)

DBG* WATCH HEADCTR

DBG* SHOW WATCH

Watch point at HEADCTR:D

SEE ALSO:  BREAK and WATCH Command

Spawn COMMAND

PURPOSE:  SPAWN creates a sub-process so DCL commands can be executed inside the PM DEBUG facility.  Control is returned to the same point in the PM DEBUG facility when the sub-process is finished.

SYNTAX

SPAWN

Example

DBG* SPAWN<CR>

NOTES:  SPAWN can be used to confirm the existence of files by executing the Digital Command Language (DCL) directory command.  Enter LOGOUT at DCL prompt to end the sub-process.

SEE ALSO:  GO and STEP Command (earlier in this section)

Step COMMAND

PURPOSE:  STEP executes the next PM line(s).  Execution is then suspended again.  It is possible to "single-step" through the PM and display or modify fields after each single statement executes.

An optional step value can be specified to execute more than one line at a time before suspending execution again.

SYNTAX

S/TEP/ [n]

Example

DBG* STEP 5<CR>

DBG* S<CR>

NOTES:  The GO and STEP commands are the only commands that can continue execution of the PM after a breakpoint.

SEE ALSO:  GO Command (earlier in this section)

Stop COMMAND

PURPOSE:  STOP ends execution of the PM.  All files opened by the PM are closed and control returns to ACCENT R.  If a Command Module (CM) or System File (SF) was active when PM DEBUG was invoked, execution continues at the next statement in the CM or SF.

SYNTAX

S/TOP/

Example

DBG* STOP

Type COMMAND

PURPOSE:  TYPE displays field values at the terminal.

SYNTAX

T/YPE/ \\field_name\\

Example

DBG* TYPE HEADCTR

HEADCTR:D = 0

NOTES:  The value of Record Fields (such as @DS_NAME, @QUALIFIED, and @NEW_RECORDS) cannot be TYPEd.

Watch COMMAND

PURPOSE:  WATCH specifies fields where a change in value is reported (watch point).  When a different value is stored in the field, PM DEBUG suspends execution.  It displays the new value of the field and the PM line that caused the modification.

For character array fields, PM DEBUG breaks and indicates the specific element in the array that has been set to a new value.

SYNTAX

W/ATCH/ \\field_name\\

Example

DBG* WATCH HEADCTR

DBG* GO

Break in PM execution due to watch point on field:

HEADCTR:D = 1

Watch point break caused by:

01260 INCR HEADCTR

Break in PM execution at line 1270

01270 SCREEN PUT_CHARS USING VIEW_ID,@RTRIM PAGEHEAD(ICTR),&

HEADCTR,1,@SCN_NOERASE,@SCN_NORMAL

NOTES:  PM DEBUG only breaks when the new value is different from the old value.

If a WATCH is set on a DS field that is read through a GET statement, PM DEBUG breaks and displays the statement following the GET.

A WATCH set on a field of the master or transaction DS will be ignored. PM DEBUG always stops on the next executable statement following a watch point.  For this reason, PM DEBUG cannot identify a field that has been modified in the last executable statement.

A watch point cannot be set for Record Fields (such as @DS_NAME, @QUALIFIED, and @NEW_RECORDS).

SEE ALSO:  SET, TYPE Commands, GET Statement

Command Summary