Debugging variable length ILE RPG fields
Author: Craig Pelkie
In ILE RPG, you can define a variable-length character field by adding the keyword VARYING to the D-spec definition for the field. When you define a variable length field, you also specify its maximum length. Variable length fields are generally useful when you need to use the field in string operations, particularly when you concatenate several strings.
Figure 1 shows a variable-length field defined as a subfield of a qualified data structure in the iSeries debugger. The name of the data structure is STRING_token and the subfield name is token. Because the data structure is defined as qualified (a V5R1 feature), you refer to the field as STRING_token.token in your code. In the debugger, you use the debug command EVAL token of string_token to display the value, as shown in the figure.
Figure 1: The varying length data structure subfield is displayed in the debugger.
You can't tell what the current length of the field is from this display.
The subfield is defined as a VARYING field with a maximum length of 128. When you look at it in the debugger, the current value is displayed (sourceFile), but you can't tell how long the field is. Knowing the current length of a varying field can be important when you debug a program. For example, if you move a fixed-length field to a varying field, the length is set to the length of the fixed-length field. If the value in the fixed-length field is shorter than the length of the fixed-length field, the field is padded with blanks. When you move that field into a varying field with a maximum length that is at least as big as the fixed-length field, the blanks are moved also and the length of the varying field is set to include the blanks. Once in the varying field, you can use the %trim or %trimr built-in functions (BIF) to remove the trailing blanks and set the length of the varying field. Or you can directly set its length with the %len BIF.
A varying field is preceded by two bytes that contain the length of the field. As you can see in Figure 1, you normally won't see the length bytes. However, you can use the :x suffix (display hexadecimal) on the debug EVAL command to display the two-byte length field, as shown in Figure 2. The EVAL command is circled in the figure and the two-byte length field value of 000A is highlighted (the hexadecimal value A is 10, the number of characters in the string sourceFile). Even though the debug display in Figure 2 shows that the field is followed by blanks (the 40 characters), the blanks are not part of the string, as its length is 10.
If you don't "do hex", you can use the Windows Calculator (in the Accessories menu) to convert a hex value to decimal.
Figure 2: Use the :x debug suffix to display the hexadecimal value of a field.
You can now see the two byte length field.