Skip to content

Debugger Commands

Debugger Commands include:

break

break causes a breakpoint to be set in the location that is indicated. With the addition of the -t flag, breakpoints can be created as temporary breakpoints, which are erased after they have been reached the first time.

The break command requires a location parameter. Location parameters for the break command are:

Parameter Description
module Sets a breakpoint in a module, as identified by program-id.
label Sets a breakpoint at a paragraph name.
line-nr Sets a breakpoint at a line number.

module, label, and line-nr can be combined, with a ! notation.

break [-t] label

break [-t] label sets a breakpoint at a paragraph name.

Example: 

       (cobcdb)
       break -t para-1
       Breakpoint 1 in para-1 at C:/COBOL/COBOLIT/samples/hello.cbl
       (cobcdb)

break [-t] module!label

break [-t] module!label sets a breakpoint at a paragraph name (label) in a module. module is identified by the source file name. If no module name is specified, then the current module is used. Since module may not be loaded yet, no validation of module!label is made.

Example: 

       (cobcdb)
       break -t C:/COBOL/COBOLIT/samples/hello.cbl!para-1
       Breakpoint 2 in para-1 at C:/COBOL/COBOLIT/samples/hello.cbl
       (cobcdb)

break [-t] module!line-nr

break [-t] module!line-nr sets a breakpoint at a line number in a module. module is identified by source file name. If no module name is specified, then the current module is used. Since module may not be loaded yet, no validation of module!line-nr is made.

Example: 

       (cobcdb)
       break -t C:/COBOL/COBOLIT/samples/hello.cbl!22
       Breakpoint 3 at C:/COBOL/COBOLIT/samples/hello.cbl!22
       (cobcdb)

break [-t] module!0

break [-t] module!0 sets a breakpoint at the entry-point to module. module is identified by source file name. if no module name is specified, then the current module is used.

Example: 

       break -t c:/COBOL/COBOLit/samples/subpgm.cbl!0
       Breakpoint 1 at c:/COBOL/COBOLit/samples/subpgm.cbl ! 0
       (cobcdb)

Or

       break -t subpgm.cbl!0
       Breakpoint 1 at subpgm.cbl ! 0
       (cobcdb)

bt

bt causes a CALL/PERFORM stack trace to be generated.

The format for the stack trace display is:
#<frame-number><module>() at <source-location>

Example: 

       bt
       #0 hello () at C:/COBOL/COBOLIT/samples/hello.cbl!21
       #1 hello () at C:/COBOL/COBOLIT/samples/hello.cbl!16
       (cobcdb)

Frame-number 0 is the current program position.

continue

continue causes execution of program to be continued until the next breakpoint is encountered, or until the end of the program . An event-continue command is issued. As seen in the example below, this is interrupted when an event-breakpoint-hit event takes place.

Example: 

       break -t para-1
       Breakpoint 1 in para-1 at C:/COBOL/COBOLIT/samples/hello.cbl
       (cobcdb)
       continue
       -event-continue
       -event-breakpoint-hit (cobcdb)#0 hello () at 
       C:/COBOL/COBOLIT/samples/hello.cbl!22
       (cobcdb)

Example: 

       break -t C:/COBOL/COBOLIT/samples/hello.cbl!22
       Breakpoint 1 at C:/COBOL/COBOLIT/samples/hello.cbl ! 22
       (cobcdb)
       continue
       -event-continue
       -event-breakpoint-hit (cobcdb)#0 hello () at 
       C:/COBOL/COBOLIT/samples/hello.cbl!22

contreturn

contreturn causes execution to continue to the next PERFORM return, or break on the first breakpoint reached, which ever comes first. An event-contreturn command is issued. This is interrupted when an –event-end-stepping-range event takes place.

Example: 

       contreturn
       -event-contreturn
       (cobcdb)-event-end-stepping-range #0 hello () at 
       C:/COBOL/COBOLIT/samples/hello.
       cbl!17

delete <x>

delete <x> causes breakpoint number x to be deleted.

Example: 

       (cobcdb)
       delete 3
       ^done
       (cobcdb)

frame <frame-number>

frame <frame-number> prints the source location for the designated frame number. The frame numbers of an application run session are the points at which the application has branched either due to a PERFORM <paragraph> statement or a CALL <subprogram> statement.

Example: 

       (cobcdb)
       frame 0
       #0 hello () at C:/COBOL/COBOLIT/samples/hello.cbl!25
       (cobcdb)
       frame 1
       #1 hello () at C:/COBOL/COBOLIT/samples/hello.cbl!17
       (cobcdb)

info

info causes information to be displayed about the <info parameter> that is indicated. The info command requires an <info parameter>.

Info parameters for the info command are:

Parameter Description
locals Displays a dump of the current variables in memory.
sources Displays a list of source files corresponding to loaded modules.
target Displays the Process ID of the runtime session.

info locals

info locals displays a dump of the values of the fields in the modules currently loaded in memory.

Example: 

       (cobcdb)
       info locals
       @hello.WORKING-STORAGE
       @hello.WORKING-STORAGE.RETURN-CODE = [10]"+000000000"
       @hello.WORKING-STORAGE.TALLY = [10]"+000000000"
       @hello.WORKING-STORAGE.SORT-RETURN = [10]"+000000000"
       @hello.WORKING-STORAGE.NUMBER-OF-CALL-PARAMETERS = [10]"+000000000"
       @hello.WORKING-STORAGE.message-line = [11]" "
       @hello.WORKING-STORAGE.ws-dummy = [1]" "
       @hello.WORKING-STORAGE.ctr = [6]"000000"
       @hello.WORKING-STORAGE.COB-CRT-STATUS = [4]"0000"
       (cobcdb)

info is returned in a structured tree using SECTION as a header in the form:
<variable name> = [<size>]”<string>”

  • <variable name> is the full qualified variable name.
  • <size> is the number of characters in the string.
  • <string> is the data in human readable form. Strings may contain null characters.

info profiling

info profiling causes a profiling dump to be produced, dumping profiling information at the current point in the program. Profiling information is displayed, and then dumped in the .xls file format.

Example: 

       (cobcdb)
       info profiling

info sources

info sources displays source files associated with objects loaded in memory.

Example: 

       cobcdb)
       info sources
       Source files
       C:/COBOL/COBOLIT/samples/hello.cbl
       (cobcdb)

info target

info target displays the pid of the currently running process.

Example: 

       (cobcdb)
       info target
       Child PID 19012
       (cobcdb)

kill

kill kills the current process.

Example: 

       (cobcdb)
       kill
       -event-program-exited (cobcdb)#0 hello () 
       at C:/COBOL/COBOLIT/samples/hello.cbl!
       10

list

The list debugger command requires that the source file be accessible. The list debugger command allows you to expand the source you can see inside the console debugger as you execute your debugger commands:

       (cobcdb)
       s
       -event-step
       (cobcdb)
       -event-end-stepping-range #0 CUSTOMER0 () at /opt/cobol-it-64/
       samples/customer0.cbl!99
       .0000099>     CALL "C$PID" USING PID.
       list
       .0000094.
       .0000095. 
       ******************************************************************
       .0000096.      PROCEDURE DIVISION.
       .0000097.
       .0000098.     Main Section.
       .0000099>            CALL "C$PID" USING PID.
       .0000100.            DISPLAY "PID = " PID.
       .0000101.     *      CALL "C$DEBUG"
       .0000102.            ACCEPT W-SYS-DATE FROM DATE.
       .0000103.            MOVE W-SYS-YY TO CURR-YY.
       .0000104.            MOVE W-SYS-MM TO CURR-MM.
       (cobcdb)

next

next causes execution to pass to the next statement, jumping over a CALL or PERFORM statement before breaking, unless the CALL’ed paragraph or PERFORM statement contains a breakpoint. An event-next command is issued. This is interrupted when an –event-end-stepping-range event takes place. The next command can be abbreviated as “n”.

Example: 

       (cobcdb)
       next
       -event-next
       -event-end-stepping-range (cobcdb)#0 hello () at 
       C:/COBOL/COBOLIT/samples/hello.cbl!17

print <variable-name\> displays the value of the variable in human readable format.

Example: 

       print message-line
       $1 = @hello.WORKING-STORAGE.message-line [11]"XXXXXXXXXXX"
       (cobcdb)

The information returned is in the format:

$1=@module-name.section-name.variable-name[size]”[string]”

Where:

  • module-name is the program-id of the module being executed.
  • section-name is the section containing the variable being displayed.
  • size is the size, in bytes of the variable.
  • string is the contents of the variable in human-readable format.

printh <variable-name>

printh <variable-name> displays the value of the variable in hexadecimal format.

Example: 

       printh message-line
       $1 = @hello.WORKING-STORAGE.message-line [22]"5858585858585858585858"
       (cobcdb)

The information returned is in the format:

$1=@module-name.section-name.variable-name[size]”[string]”

Where:

  • module-name is the program-id of the module being executed.
  • section-name is the section containing the variable being displayed.
  • size is the size, in bytes of the variable.
  • string is the contents of the variable in hexadecimal format.

quit

quit causes an exit from the debugger.

Example: 

       (cobcdb)
       quit

       C:\COBOL\COBOLIT\samples>

replace

To locate a source file that has been moved, and associate it with an object compiled for debug, use the replace debugger command, which changes the path to the source file.

The syntax is as follows:
replace <oldprefix> : <newprefix>

The replace debugger command allows you to replace the location where the source files associated with the program being debugged are stored.

The replace debugger command replaces any prefix of the full pathname, so the command replace /dirA : /dirB will allow any program that was originally compiled in /dirA/dev/sources to have its source stored in /dirB/dev/sources.

Subsequent commands are stacked, so when typing two more commands as follows:

  replace /dirC : /dirD
  replace /dirE : /dirF

you will end up with a list of three possible replacements. Only the first matching replacement will be executed.

Further usages include:

  • replace <no arguments> Resets the list, removing active replacements
  • replace ? Produces a list of active replacements.

Note

The replace debugger command only affects the output of the list command. The list debugger command allows you to expand the source you can see inside the console debugger as you execute your debugger commands.

set

set allows the user to set a <set parameter> to a different value.

The set command requires a <parameter>.

Parameters for the set command are:

Parameter Description
prompt <prompt-string> Sets the debugger prompt to <prompt-string>.
var <variable-name> <variable-value> Sets the value of <variable-name>.
varh <variable-name> <variable-value> Sets the value of <variable-name> in hex notation.

set prompt <prompt string>

set prompt <prompt string> sets the COBOL-IT Debugger prompt. The default setting for the COBOL-IT Debugger prompt is (cobcdb).

Example: 

       (cobcdb)
       event:13556
       -event-end-stepping-range #0 hello () at C:/COBOL/COBOLIT/samples/hello.cbl!9
       set prompt >>>
       >>>

set var <variable-name> <variable-value>

set var <variable-name> <variable-value> sets variable content for variable-name to variable-value. Values are converted to the appropriate type. A number stored in a PIC 999 field will be converted before storing.

Example: 

       (cobcdb)
       set var message-line "hello hello"
       $1 = @hello.WORKING-STORAGE.message-line [11]"hello hello"
       (cobcdb)

set varh <variable-name> <variable-value-hex>

set varh <variable-name> <variable-value-hex> sets variable content for variable-name to variable-value-hex.

<variable-value-hex> must be a valid hexadecimal string. Note that in a valid hexadecimal string, a single character space is recorded with two characters, so the total string length of <variable-value-hex> must be exactly two times the length of <variable-name>.

Example: 

       (cobcdb)
       set varh ws-dummy 41
       $1 = @hello.WORKING-STORAGE.ws-dummy [1]"A"
       (cobcdb)

step

step causes execution of the program to execute a single step, and then break. An event-step command is issued. This is interrupted when an –event-end-stepping-range event takes place. The step command can be abbreviated as “s”.

Example: 

       (cobcdb)
       step
       -event-step
       (cobcdb)-event-end-stepping-range #0 hello () at 
       C:/COBOL/COBOLIT/samples/hello.cbl!14

stop

stop causes execution to stop (break) at the next statement.

up -[n]

up -[n] changes the current frame. When you have several levels of CALLs, the info functions relate to the current module. In a CALL’ed subprogram, up –[n] can be used to change the frame back to a previous CALL’ing module. Info locals can then be viewed for that calling module.

In the example below, the bt command shows 3 frames, with frame 0 being the current frame in a called sub-program, and the info locals command showing the state of the variables in the subprogram. up -1 sets the frame to the calling program, so that info locals can be viewed for the calling program.

       bt
       #0 subpgm () at C:/COBOL/COBOLIT/samples/subpgm.cbl!7
       #1 hello () at C:/COBOL/COBOLIT/samples/hello.cbl!25
       #2 hello () at C:/COBOL/COBOLIT/samples/hello.cbl!17
       (cobcdb)
       info locals
       @subpgm.WORKING-STORAGE
              @subpgm.WORKING-STORAGE.RETURN-CODE = [10]"+000000000"
              @subpgm.WORKING-STORAGE.TALLY = [10]"+000000000"
              @subpgm.WORKING-STORAGE.SORT-RETURN = [10]"+000000000"
              @subpgm.WORKING-STORAGE.NUMBER-OF-CALL-PARAMETERS = [10]"+000000000"
              @subpgm.WORKING-STORAGE.COB-CRT-STATUS = [4]" "
       (cobcdb)
       up -1
       #1 hello () at C:/COBOL/COBOLIT/samples/hello.cbl!25
       (cobcdb)
       info locals
       @hello.WORKING-STORAGE
              @hello.WORKING-STORAGE.RETURN-CODE = [10]"+000000000"
              @hello.WORKING-STORAGE.TALLY = [10]"+000000000"
              @hello.WORKING-STORAGE.SORT-RETURN = [10]"+000000000"
              @hello.WORKING-STORAGE.NUMBER-OF-CALL-PARAMETERS = [10]"+000000000"
              @hello.WORKING-STORAGE.message-line = [11]"XXXXXXXXXXX"
              @hello.WORKING-STORAGE.ws-dummy = [1]" "
              @hello.WORKING-STORAGE.ctr = [6]"000000"
              @hello.WORKING-STORAGE.COB-CRT-STATUS = [4]"0000"
       (cobcdb)

version

version returns the version of the cobcdb/COBOL-IT runtime.

Example: 

       (cobcdb)
       version
       ~"COBOL-IT cobcdb 3.6.4\n"
       ^done
       (cobcdb)
Back to top