A Simple Example

Figure 22.1 shows an example of a physical file described with DDS. It is called VNDMST (vendor master).

Figure 22.1: DDS for a simple physical file.

DDS keyword UNIQUE has been coded before any record in the file is defined. That makes this keyword applicable to the whole file. Keywords that apply to the entire file are said to be file-level keywords. UNIQUE indicates that the file is keyed and that the key should be unique. No duplicate keys are allowed. If you omit UNIQUE, the file can have duplicate keys.

Two comment lines are indicated by an asterisk in 7. These lines are only used to separate groups of lines that belong together.

The third line describes a record (R in 17) named VNDREC. Note that the TEXT keyword appears on the same line, which makes TEXT a record-level keyword. In this case, it describes the purpose of the record.

The A-specs that follow describe the fields contained in record VNDREC: VNVEND (6 bytes alphanumeric); VNNAME, VNADR1, and VNADR2 (30 bytes alphanumeric); VNCITY (20 bytes alphanumeric); VNSTE (2 bytes alphanumeric); VNZIP (5 digits, no decimals, packed decimal); and VNDUE (9 digits, 2 decimals, packed decimal). Finally, the key to the file (K in 17) is defined as consisting of field VNVEND only.

Look at the definition of field VNVEND. The line contains not only the name of the field (VNVEND) and its definition, but also keyword TEXT which, in this case, is a field-level keyword because it applies to that field only. The next line also applies to field VNVEND. The line gives the field a column heading of ‘Vendor’ and ‘Number’ (stacked on two consecutive lines) when printed or displayed by Query/400 or SQL/400.

Field VNZIP also has a column heading, but it also has the DDS keyword RANGE, which indicates that the zip code must have a value between 00000 and 99999. This range excludes negative numbers, of course. Although the physical file doesn't complain if you write a zip code that is out of range, it is useful to include these keywords. When you reference VNZIP in a display file, for example, the display file will not allow the user to enter values outside of that range, and you will not have to code anything in your data entry program to make it happen.

Finally, field VNDUE has keyword EDTCDE (edit code). The first value is the edit code itself (J). The second (optional) value indicates a floating currency symbol. Again, the physical file doesn't use this information, but it is there ready for reference by display and printer files. When the amount you owe to the vendor is displayed or printed, it will automatically have a floating currency symbol and will be edited with commas and a trailing sign (edit code J). You will not have to do anything in your program. You also will not have to remember to code this in your display or printer file.

Defining by Reference

Of the variations to the basic example shown above, the most important is defining a record or a field by reference to another record or field elsewhere. For example, suppose you want to create another physical file that has the same record layout without any changes.

You can do so by coding a one-line DDS member, as seen in Figure 22.2.

Figure 22.2: Defining a file by reference.

You can call this the SUPPLIER file. Note that the record name (VNDREC) is the same. The FORMAT keyword references the name of the file serving as a model. As you can see, this method is very inflexible. You must name the new record the same as the existing one, and you must include all fields with identical names and attributes.

Another more flexible method to define by reference involves the REF and the REFFLD keywords. Suppose you need to create a file called VNDCONT (vendor contacts) that must include the vendor number, the name of a person to contact, and a phone number. Figure 22.3 reflects what the DDS could look like.

Figure 22.3: Using the REFFLD keyword to define fields in a physical file.

The REF(VNDMST) keyword indicates that this member can define fields by referencing fields contained in the VNDMST file. That technique is used to define fields VCVEND and VCNAME.

VCVEND is the vendor number. You could have kept the name VNVEND, but if you access both files with an RPG IV program, you would not be able to distinguish field VNVEND in file VNDMST from VNVEND in file VNDCONT. The R in 29 indicates that this field is defined by reference, so there is no indication of length or data type. The REFFLD(VNVEND) keyword indicates that field VNVEND serves as the model. Keywords associated with VNVEND in file VNDMST automatically apply to the new field, VCVEND. In this case, VCVEND will have the same column headings.

Field VCNAME also is defined by reference. It copies the definition of field VNNAME. Because VNNAME has column headings that read "Vendor Name," you must override that. Therefore, the COLHDG keyword follows on the next line.

The last field in the record is new, so you cannot define it by reference. Note that the key is now field VCVEND (not VNVEND). Because the UNIQUE key was not included in this file's definition, the file allows duplicate keys, which is good because more than one contact can exist for each vendor.

Tip 

Defining by reference is a powerful technique. It not only saves work, but it makes your database more consistent. You define a piece of data in only one place, then you use that definition everywhere else it is needed.