With OS/400 Version 5 Release 1, IBM introduced QUALIFIED data structures into RPG IV. This functionality gives the programmer the ability to refer to the subfield names of the data structures, using the data structure name as a prefix or qualifier of the subfield.

In the example that's shown below, the data structure MYDS is declared with seven subfields. Note the QUALIFIED keyword; this is what causes the data structure to be considered qualified. 

The only way to access the subfields of this data structure is through what is called "qualified syntax." Qualified syntax is as follows:

"DS" is the name of the data structure, and "subfield" is the name of a subfield. They're separated by a period (.). For example, the following EVAL operation illustrates how to access the CITY subfield in the MYDS data structure.

This statement copies the word "Chicago" into the CITY subfield of the MYDS data structure.

When a data structure is qualified, the subfield names may only be referred to using this qualified syntax. The following traditional statement will not compile:

This will not compile because the field named CITY no longer exists; only MYDS.CITY exists in the program. But it's possible for you to declare an additional, standalone field named "CITY" in the program and refer to it independently of the CITY subfield in the MYDS data structure. However, you'd be creating some very confusing code.

IBM also allows qualified data structures to be used for input files. There isn't a direct syntax that says "make this input file use qualified names," but it is somewhat simple.

Duplicate I/O Formats

One challenge for RPG programmers has been what to do when the same field name is in two or more files. Specifically, what happens when you have two files with identical formats, and hence all field names are identical?

If there were a way to isolate these formats so that their fields were stored in different buffers, wouldn't that be cool? Well, there is a way.

The PREFIX keyword has been a part of RPG IV since it was introduced. Since the beginning, you could specify PREFIX(XYZ), and the compiler would automatically rename every input field by adding the XYZ prefix to the field name.

In V5R1, when IBM added qualified data structures, they also enhanced the PREFIX keyword by allowing you to include the name of a qualified data structure in the prefix. To do this, you include the period in the prefix itself. For example:

This causes all the fields to be renamed to MYDS.XXXX, where MYDS. is a constant and XXXX is the input field name.

Note that since a period is not a character allowed in normal RPG IV field names, the prefix that includes a qualifier must be enclosed in quotation marks. In addition, it must be specified in all uppercase because RPG IV does not automatically translate source code segments that are enclosed in quotes.

But the PREFIX keyword is only half the solution. The other half is declaring a qualified data structure. You have to declare the data structure with the same subfields as that of the input file, and it must be a qualified data structure.

Here's an example:

This declares the CUSTMAST file as usual but indicates that the input fields are mapped to a data structure named CUST1 and that the data structure is declared as a qualified data structure.

The second half is the qualified data structure. You declare the qualified data structure as follows:

The data structure name is the same name as the character pattern specified on the PREFIX keyword on the File specification. I used the EXTNAME keyword to import the data structure's subfields from the record format of the CUSTMAST file. This makes it extremely easy to declare the data structure with the appropriate subfields (versus hand-coding each subfield).

With this syntax, all the fields in the CUSTMAST file must now be referred to using qualified syntax. So, for example, the CUSTNO field is referred to as MYDS.CUSTNO (with a qualifier) rather than CUSTNO (without the qualifier).

Now, suppose you want to add another file to the program. This time, the file is CUSTNAME, which happens to be a logical view over the CUSTMAST database file. Like most logical files, the only thing this logical is used for is to access the CUSTMAST file by an alternate key. Therefore, the record format is identical to the CUSTMAST file. While identical formats are not a specific requirement for this example, this is a typical situation.

A logical file with a custom format will also include fields with the same name as the physical, and this technique applies to that situation as well.

To declare the second file, you need to add the following two lines of code to the above examples:

This creates the same qualified data structure as the first example, but it changes the name to MYDS2. Therefore, the subfield names are referred to as MYDS2.XXXX instead of MYDS1.XXXX as in the first example.

The complete RPG IV source code for these two files would be as follows:

When we use the PREFIX keyword to cause the input fields to be qualified, they are mapped to the corresponding qualified data structure. Therefore, any I/O operations that are performed access the subfields in this qualified data structure.

The following gives a slightly more complete example of using a qualified data structure to allow you to declare two files with the same field names in the same program and avoid field name collision.