Q: I'm having trouble passing a parameter between ILE CL and RPG IV. The RPG IV procedure being called accepts a variable-length field (the VARYING keyword is "use"). When I call the procedure as follows, I get an error that says the length of the field is incorrect. What am I doing wrong?

A: The problem you are having is that CL--unlike RPG IV--does not support variable-length fields. So when you pass a fixed-length character field, like the &NAME variable in your example, to an RPG IV procedure that expects a variable-length field, the field's length attribute is not included. So the RPG IV program thinks (and rightly so) that the data is corrupted.

In your example, a procedure call (the CALLPRC command) attempts to call an RPG IV procedure whose procedure interface is as follows:

This procedure accepts a parameter that is defined as a variable-length field. When the CALLPRC command is run, the procedure MakeLower is called and immediately fails, generating an "invalid field length" message. To explain why this is happening, let me first review variable-length fields.

Variable-Length Fields

When an RPG procedure accepts a variable-length field, it assumes the field will be formatted properly. Calling the procedure from RPG IV is easy, since you have to have a prototype and the compiler ensures that the data is formatted properly. But when you call a procedure (RPG or otherwise) from CL, no prototype is involved, and you have to ensure that the variable passed as a parameter is properly formatted.

Variable-length fields are unique in that their storage is prefixed with two extra bytes. This means that the field's internal storage size is two bytes longer than the field's declared length. So a 20-position field ends up using 22 bytes of storage. Those extra bytes are a two-byte binary value, or 5i0 in RPG IV syntax, that prefixes the data in the field and contains the current length of the field's contents. The two-byte prefix is automatically inserted and maintained by the RPG compiler. For example, if the field contained 'Bob Cozzi', its current length would be nine, and the two-byte prefix would contain X'0009'. The following figure illustrates the positions, character values, and hexadecimal symbols for a 20-position, variable-length field containing the value 'Bob Cozzi'.

Figure 1: Hex dump of a variable-length field

The field's length attribute is hidden by RPG IV because of RPG's integrated support for variable-length fields. The field length is stored internally as a two-byte binary prefix. All RPG IV operation codes have been enhanced to accommodate variable-length fields. RPG opcodes automatically adjust the length prefix as appropriate.

The length of a variable-length field is, of course, identified when the field is declared. A field whose length is 20A, for example, is a simple 20-position character field. If you add the VARYING keyword, the field becomes a variable-length field with a length potential of 0 to 20. For example:

The current length of a variable-length field may be set implicitly or explicitly. The current length is different from the declared length in that it is variable--from 0 up to the declared length. To set the current length of a variable-length field implicitly, copy a value to the field, as follows:

In this example, the string 'Bob Cozzi' is copied to the NAME field. The length of the NAME field is automatically adjusted to the length of the string copied to it by the EVAL opcode. This is an implicit field-length assignment. The EVAL opcode does not automatically trim off trailing blanks. If a fixed-length field is moved into a variable-length field, the variable-length field's current length is the same as the declared length of the fixed-length field. For example:

In this example, the variable-length field NAME is assigned the concatenated value of the FIRST and LAST fields. Since FIRST and LAST fields are fixed-length, the value of NAME is as follows:

Since trailing blanks are not automatically truncated, the current length of NAME ends up being set to 20. To get a more appropriate result, use the %TRIMR built-in function when assigning values to variable length fields, as follows:

The NAME field's current length is set to 15. Of course, you'll still have an issue of too many blanks between the first and last names, but that's another issue entirely.

To set a variable-length field's current length explicitly, use the %LEN built-in function, as follows:

In this example, the length of the variable-length field is adjusted to 3. A subsequent MOVE or EVAL of the NAME field's data to another field would return just the first three characters of the field. In this example, 'Bob' would be all that is returned.

To retrieve the current length of a variable-length field, use the %LEN built-in function on the right side of the operator. For example:

This can be particularly useful in a DOx or FOR loop. The %LEN built-in function is very efficient because all it does is return the value stored in the two-byte binary prefix of the variable length field.

CL Support for Variable Length Fields

CL does not have integrated support for variable-length fields. In fact, it has no built-in support for this type of field at all. In order to properly pass a variable-length field from CL to RPG IV, the two-byte binary prefix must be managed by the CL module. This is accomplished by storing the length of the field's data in the first two positions in the field. Consequently, it's a good idea to increase the field length by two bytes.

In the example that follows, the field named &NAME was a 20-position character variable in this CL module. In order to accommodate the variable-length field parameter required by the MAKELOWER routine, I've added two bytes to the field's length. The field's length is now 22 (line 2 in Figure 2).

Figure 2: CL module correctly calling an RPG IV procedure

In order to embed a two-byte, binary-length prefix into the &NAME variable, the %BIN CL built-in function is used (see line 3 in Figure 2). The syntax of %BIN is similar to %SST in that it accepts a field name, a starting position, and a length. The length indicates the number of characters that will be modified or extracted as a binary (i.e., integer) value. Once the length (9 in this example) is embedded in the two-byte prefix, you can copy the data into the field. But you cannot copy it into position 1 and 2 of the field because that would overwrite the field's length. By using the %SST (substring) built-in function (line 4 in Figure 2), you bypass the two-byte, binary-length prefix and copy the data into the field starting in position 3.

When the MAKELOWER procedure is called (line 5 in Figure 2), the variable &NAME becomes a properly formatted variable-length field and should pass through properly.

The source code for the MAKELOWER procedure in RPG IV is listed in Figure 3.

Figure 3: RPG IV source for the MAKELOWER procedure

Upon return from the call to MAKELOWER, the CL program should inspect the two-byte binary prefix and figure out how long the data is in the field. Figure 4 illustrates this technique. Lines 8 and 9 extract the current length of the variable-length field and then use that length with the %SST built-in function to extract the modified data from the &NAME field.

Figure 4: Modified CL source to extract a variable-length field's current length