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.
Leave a Reply