Variable-length fields are used to reduce storage utilization for fields that may not always be filled with data. Good candidates for a variable-length field include a text description or a note field in an item master file. The maximum length of a variable-length field is 32,740 characters.

Declaring Variable-Length Fields in DDS

To declare a variable-length field in a database file, use the VARLEN keyword. For example:

The VARLEN keyword is used with standard character fields. When VARLEN is specified, the character field becomes a variable-length field with the capability to store up to its length in data. But rather than allocate storage in each database record for the variable-length field's data (250 bytes of data in my example), storage for these fields is not allocated. Instead, a variable-length storage area is created in the file. This area contains only enough space to store the data contained in the variable-length fields. This provides more-efficient storage for the database file.

The VARLEN keyword accepts one optional parameter that indicates the number of bytes for the initial allocation of the field. This initial allocation is actually stored in the regular area of the database file with the other fields. It provides more-efficient access to the data in the field that is not longer than this initial length. If a field is normally empty (unspecified), there is no need to specify an initial length. If a field is generally going to contain 1 to 20 characters on average, then specify an initial length of 20.

In my 250-byte variable-length field, an initial allocation of 10 bytes is specified. This initial allocation is the portion of the field that is stored in the so-called fixed portion of the file, whereas the rest of the variable-length field is stored in the variable portion of the file. If a field normally contains X bytes or less, but occasionally exceeds X bytes, declare a variable-length field with the maximum length you may need and specify an initial allocation size of X.

Using Variable-Length Fields in RPG

RPG IV has integrated support for variable-length fields, whereas RPG III support is simulated.

In RPG III, variable-length fields are not directly supported. To use them, the OPTION(*VARCHAR) keyword must be specified on the CRTRPGPGM command. This keyword option, however, only causes the compiler to translate a variable-length field from a database file to an RPG III character field. To access the field correctly, you need to create an Input specification with two subfields.

The first field, NTLEN, is the field's current length. The second field, NTDATA, is the data itself. In RPG III, it is up to the programmer to manage the current length of a variable-length field. Perhaps this is why so many RPG programmers have been put off and do not use variable-length fields.

The name of the data structure (line 1) is NOTES and must be the name of a field in a database file used in this program. That field must be declared in its DDS with the VARLEN keyword. The DDS definition would look something like this:

In RPG IV, variable-length field support is integrated, so no special data structure or manipulation is needed. To declare a variable-length field in RPG IV, use a Definition specification and add the VARYING keyword to the field definition, as follows:

This declares a variable-length field named NOTES with up to 10,000 characters.

Variable-length fields in RPG IV have data, a declared length, and a current length. The declared length is just what you might think: the length of the field as declared on the Definition specification. In my NOTES field, the declared length is 10,000 characters. The current length of the field is the length assigned to the field at any given point. If the INZ keyword is used, the data in the INZ keyword is the initial value and is used to set the current length when the program is started. In my example, the current length of NOTES is 3 when the program is started. Unlike DDS's VARLEN keyword, the RPG IV VARYING keyword does not support an initial allocation length parameter.

Variable-Length Fields and Opcodes

To assign data to a variable-length field, use the EVAL, EVALR, MOVE, or MOVEL operation codes. When you use the EVAL or EVALR operation code to move data into a variable-length field, the current length of the field adjusts to the length of the data being moved. However, the MOVE or MOVEL operation codes treat variable-length fields like fixed-length fields. That is, they do not adjust the current length of the variable-length fields.

The EVAL operation code changes the length of a variable-length field. When data is copied to the variable-length field or when a numeric value is assigned to the %LEN for the variable-length field, the EVAL operation code adjusts the current length of the variable-length field.

Line 1 copies a text string to the NOTES field. The EVAL opcode copies the data to the field and sets the variable-length field's length to 15--the string it copied. After line 1 is run, the NOTES field's length is 15.

Line 2 uses the %LEN built-in function to set the length of the field to 10. Therefore the data in the field after line 2 is performed is 'Clearance '.

Why change the current length of a variable-length field? To allow the MOVE and MOVEL operation codes to operate with these types of fields with a known length.

Variable-length fields can be used not only to save space but also to simplify passing parameters to procedures. By specifying VARYING for a character parameter of a procedure along with either CONST or VALUE, you can specify a fixed- or variable-length field for that parameter. The lengths of the values passed to the procedure may be as short as 1 position or as long as the declared parameter length. The compiler converts the data into the procedure's internally required form.

Consider the prototype for the TOUPPER procedure, as follows:

The INPUTSTG parameter is declared as 2048-byte variable-length field that is passed by value. A fixed-length value (including a field or data structure), a constant or literal, or a variable-length field may be passed on this parameter. The procedure itself receives the data as a variable-length field and can process it accordingly.