When the Eval debug command is used to display the contents of a variable, the system uses a default data format commensurate to the variable type. For example, the contents of a character field are displayed using character format. The contents of a numeric field are displayed using numeric format. However, you can direct the system to display the data in other formats as well, with the hexadecimal format being one of the most useful.
How hexadecimal formatting is helpful
There are many instances when hexadecimal formatting is not only helpful, it is downright necessary. I use hexadecimal formatting so frequently that I used to change the default value for the output format (OUTFMT) parameter to *HEX on the old OPM debugger commands ADDBKP and DSPPGMVAR. (Unfortunately, the same cannot be done in the ILE debugger.) Here are a couple of specific examples of how hexadecimal formatting can help you:
- Many APIs return information in either hexadecimal and/or binary bit-wise format. (Binary bit-wise format is when each specific bit in a variable contains its own autonomous information.)
- When looking at a character field that does not contain alphanumeric data. For example, when we use character variables in CL to hold binary-formatted numeric data (before V5R3 came along).
How to display a variable in hex
To display the value of any variable in hexadecimal format, simply specify :x (a colon followed by an 'x') at the end of the Eval debug statement. For example, the screen shot below shows the following program in debug mode.
D TestDS DS
D Fld1 23
D Fld2 4
D Fld3 10i 0
D Fld4 5i 0
D Fld5 9p 2
D Fld6 5s 0
D Fld7 3
D Diff S 9b 0
* Calculate the number of bytes between Fld2 & Fld6.
C Eval Diff = %addr(Fld6) - %addr(Fld2)
c Return
The program is stopped at a breakpoint right after calculating the offset from the beginning of Fld2 to the beginning of Fld6 (i.e., the number of bytes separating the two variables). The Eval command on the debug command line will display the value of Diff in hexadecimal format. The output from running the Eval command is shown on the bottom line of the display (normally the message line on most displays).
Notice that the output seems much longer that 4 bytes (Diff is a 4-byte binary variable). The first five zeros is the offset of the first byte of the data shown. (For longer fields, say a 64-byte character field, the hexadecimal output must be split up among several lines and in front of each line is the offset of the first byte of that line from the beginning of the field.)
The data following the offset is the value of the variable in hexadecimal format. The system always displays 16 bytes worth (or 32 hex digits). If the field is smaller than 16 bytes, as is the case here with Diff, the remainder of the 32 hex digits are displayed as dots (i.e., periods). Here, the display shows a value of 0000000F for Diff, which translates into 15 decimal. Then there are 24 dots, which are "filler" and would be hexadecimal digits if the variable were longer.
Finally, there is a dash and then 16 dots at the end of the line, which are the character representation of the data (a dot is used when a character is non-displayable -- x'00' and x'0F' are both non-displayable).
Tip: Displaying character variables with the :x option can be especially useful because, as we just discussed, you will get both the hexadecimal representation and the character representation of the data in the variable.
Character formatting also available
You can force the contents of a numeric field, for example, to be displayed using character format. Instead of using :x at the end of the Eval command, use :c (a colon followed by a 'c').
Note: Using :c does not convert the data from numeric to character. It simply causes the system to interpret the data in the field as character -- that is, treat the data in the field as though the field was a character field.
Other formatting options available
If you have variables containing data in ASCII or Unicode format (e.g., a sockets program communicating with a PC), there are formatting options specifically for it. Use the :a option to have the data in the variable formatted in ASCII, and use the :u option to have the data in the variable formatted in Unicode.
For C, C++, and Java programs and modules, there are two additional formatting options for the Eval debug command. Both are for displaying null-terminated strings. The :s option displays a string up to its null-terminator, without regard for or interpretation of newline and carriage-return characters. The :f option is just like the :s option except that newline and carriage-return characters are interpreted.
-----------------------------------
About the author: Ron Turull is editor of Inside Version 5. He has more than 20 years' experience programming for and managing AS/400-iSeries systems.
