iSeries Source Debugger – Advanced Debugging Tips

Not too long ago, a friend of mine was having a problem with a program that he had just finished. We were using the source debugger to find out what was causing his problem. We figured out the problem eventually, but in the course of our work, we came across some debugger commands and options that I was previously unaware of. Now I am not going to say that I know everything about the IBM source debugger but I have been using it for a good long while. I was surprised to discover something new, so I thought I’d share what I learned with you.

%INDEX Built-In Function

The %INDEX function is one of the functions that up until recently I was unaware of. It is really handy when you are manipulating multiple-occurrence data structures. It is even more useful when used in conjunction with the _QRNU_DSI_xxxx built-in value (where xxxx = the name of a multi-occurrence data structure). The command EVAL _QRNU_DSI_xxxx will return the current occurrence of a multiple-occurrence data structure. This is often a very useful thing to know during program execution and as far as I know this is the only way to get it. By using the %INDEX function you can also change the current occurrence of a multiple-occurrence data structure. See below.

d WorkMultDS1 ds occurs(30)

d StringA 10a

d StringB 25a

To find the current occurrence of the data structure without changing it:

Command: EVAL _QRNU_DSI_WorkMultDS1

Result: 1 (or whatever the current occurrence of WorkMultDS1 is)

To change the current occurrence:

Command: WorkMultDS1 = %INDEX(12)

Result: WorkMultDS1 = %INDEX(12) = 12

After issuing the above command interrogated subfields will reflect the values of the twelfth occurrence of the data structure.

%SUBSTR Built-In Function

This function is really convenient when you are working with large strings. Using the EVAL function by itself will only display only the first 500 characters of a field. As a side note, the easy solution to that problem is to append the type and length to the EVAL function as shown below:

This command will display the first 2000 characters of the variable Long_String_Name in character format:

Command: EVAL Long_String_Name:C 2000

This command will display the first 2000 characters of the variable Long_String_Name in hexadecimal format:

Command: EVAL Long_String_Name:X 2000

The hexadecimal display is important when displaying data that contains packed or binary decimal data. But we are not talking about the EVAL function. The SUBSTR function will do exactly what the name implies; it will display a substring or a portion of a string value. See the examples below.

Assume that StringFldA = ‘Now is the time for all good men…’

Command: EVAL %SUBSTR(StringFldA 12 4)

Result: %SUBSTR(StringFldA 12 4) = ‘time’

Not surprisingly, you can also use the %SUBSTR function to set the value of a specific portion of a string. Sometimes this is a far more helpful way to use this function. An example of this usage is shown below.

Assume that StringFldA = ‘Now is the time for all good men…’

Command: EVAL %SUBSTR(StringFldA 12 4) = ‘blah’

Result: %SUBSTR(StringFldA 12 4) = ‘blah’

To see the complete string use the following command:

Command: EVAL StringFldA

Result: StringFldA = ‘Now is the blah for all good men…’

The %SUBSTR function can also be used to set a conditional breakpoint or watch condition. As an example, the code shown below will stop the execution only when positions 12 through 15 of StringFldA are ‘blah’:

Command: BREAK 100 when %SUBSTR(StringFldA 12 4) = ‘blah’

Or you could watch for those same positions to change by using this watch condition:

Command: WATCH %SUBSTR(StringFldA 12 4)

After issuing the command above, anytime the contents of positions 12 through 15 change, program execution stops and you are notified.

EQUATE function

More and more often I run into field names that are really long. Now don’t get me wrong here, I think this is great. But I don’t type so good so a 25 character field name has a much greater chance of being mis-keyed than an old 6 character one (even if the 25 character one is way more understandable). So if you don’t type well (or just don’t like to type, like me), then use the EQUATE debug function. This function allows you to define an “alias” for a field name, expression, or command. Take the example below.

Command: EQUATE SmName This_is_a_really_long_field_name

You can then find the value of “This_is_a_really_long_field_name” by keying the command shown below:

Command: EVAL SmName

The EQUATE command can also be used to create a macro…sort of. This can be done by assigning an “alias” to a complete debug command.

Command: EQUATE SmCmd EVAL %substr(StringA,5,5)

Now by simply keying SmCmd and pressing Enter, you can display the value of positions 5 through 9 of the StringA variable.

So the next time you start testing a program or chasing a bug, remember these, and you might save yourself some headaches.

Source by Jeff Olen