This section starts with a review of file definition records and discusses how the content of these records can affect the output from jQL commands - particularly with reference to sublists.
File definition records contain information that is used when formatting reports. For example, should the key field of a file be left or right justified, and how wide a column should it occupy. You can also define sublist codes to tell the system that a particular field is multivalued.
The fields of a file definition record that affect jQL reports are:
File records which contain sublists can be accessed with the COUNT and LIST commands and the WITHIN modifier. For the commands and the modifier to function properly, you must include the V processing code in field 8 of the file definition record. See the File Specifiers topic in the jQL Command Sentence Construction topic for more details.
field-no is the number of the field which contains the sublist.
Consider the STOCK file used by a camera factory where each data record can represent either an assembly or a component part.
Take as an example the record set that defines a simple camera assembly. The data records contain the following data:
The key is the part number, field 1 contains the description, field 2 is a multivalued list of components that go to make up the part, and field 3 is the current stock level.
Record A1 represents assembled cameras. It points to the sub-assemblies (A21, A22 and A23) that are used to make each camera. The sub-assemblies in turn point to their component parts; A21 points to A210 and A211, A22 does not have any components, and A23 points to A230.
Having established the logical data relationships, we now need to ensure that the
system understands that field 2 is a multivalued sublist. We do this by updating field 8
in the file definition record to read "V;;2",
Now all we need to do is to create three data definition records in the dictionary of STOCK - one for each field. We will name them DESC, COMPONENTS, and QTY.
The final step is to issue a COUNT or LIST command which uses the WITHIN modifier:
Data definition records (sometimes known as field definition records) define the characteristics of each field in a data file. They specify the output format and the type of processing required to generate each column of a jQL report.
Data definition records can be used to:
Although they are normally used to define a single physical field in a file, the data definition records can also be used for more complex operations. For example:
The data definition records are usually located in the dictionary of the data file (but not always - see the USING Clause and the Default Output Specification topics). You can set up any number of data definition records. Often, there are several definitions for each field, each one used by a different set of reports which have different output requirements.
You associate the data definition record with a particular field in the data file by specifying the target field"s FMC (field-mark count) in field 2 of the data definition record. The FMC refers to (points to) the field number (also known as the line number) of the data within the records of the data file.
All data definition records are defined in the same way:
A marks a normal data definition record.
X forces the record to be ignored if selected as part of a default set of data definitions. Can only be used when explicitly named. See Default Output Specification later.
2 FMC (field-mark count)|A field number or special FMC (see Special Field-mark Counts later, for more details). A field number refers to the corresponding field (or line) in a record.
The special FMC codes are:
3 Column heading| Can be heading text, null, or a backslash followed by text. If more characters are entered here than the width in field 10 allows for, the width will be increased to accommodate the heading text (this field wins). Column headings are not displayed if the statement uses the COL-HDR-SUPP output modifier or the "C" option. Heading text is used as the column heading. If the text is less than the column width, it will be padded with dots. Use spaces to produce a blank heading. Value marks, (ctrl ]), can be used as NEWLINE characters to place the following text on a new line. If this field is left null, the key of the data definition record will be used as the column heading. Text following a backslash "\" character will be used as the column heading. If nothing follows the backslash, the column heading will be null.
4 - 6|Not used.
10 Width|Numeric value specifying the column width. If the number of characters in field 3 (the heading) is greater than the number entered here, the number of characters in field 3 will be used.
SPECIAL FIELD-MARK COUNTS
Three special FMCs (field-mark counts) are recognised: 0, 9998 and 9999.
FMC 0 - RECORD KEY
Setting field 2 of the data definition record to 0 (zero), causes the system to work with the record key. In this way, you could set up a data definition record which would allow a the record keys to be output in a column other than the first, and to use any column heading.
Typically, you would also use the ID-SUPP modifier or the I command option to suppress output of the record key in the first column.
FMC 9998 - RECORD COUNT/NI OPERAND
Setting field 2 of the data definition record to 9998, causes the system to return a record (or line) count equal to the number of records output so far in the report.
You could also use function operators within an A or F conversion code in field 7 or 8 of the data definition record to achieve the same result. Function code operand NI yields the same value as an FMC of 9998.
FMC 9999 - RECORD SIZE/NL OPERAND
Setting field 2 of the data definition record to 9999, causes the system to return the record size in bytes. The size does not include the key but does include all field marks within the record.
You could also use function operators within an A or F conversion code in field 7 or 8 of the data definition record to achieve the same result. Function code operand NL yields the same value as an FMC of 9999.
DEFAULT OUTPUT SPECIFICATION
Default output specifications work in two ways, depending on whether the default definitions are explicit or implicit.
If you specify a data definition record to be used for output, the system will search for it first in the implied dictionary (or the dictionary specified in a USING clause). If the data definition is not found in the implied dictionary the system look in the files specified in the JBCDEFDICTS environment variable but only if it as been assigned. If JBCDEFDICTS has not been assigned, the system will look for the data definition in the file defined by the JEDIFILENAME_MD environment variable.
If you do not explicitly specify any data definition records to be used for output, the system will search for a predefined series of records based on the search criteria outlined in the preceding section.
You can therefore set up a series of data definition records that the system will use if a jQL command sentence does not include any explicit output fields.
These "default" records must be named in a numeric sequence starting at 1 (1, 2, 3, and so on). The fields that these records define will be output in the same sequence as the keys but they do not need to follow the same sequence as the fields in the file.
When a jQL command sentence with no explicit output fields is issued, the system first looks in the dictionary for a data definition record named 1, then for a record named 2, then 3, and so on until it fails to find a record with the next number. If the record has a D/CODE of A, it will be used. If the record has a D/CODE of X, it will be ignored, but it will not break the sequence.
A record with a D/CODE of X will only be skipped if it was found as the result of a search for defaults. Under normal circumstances it can be used in the same way as any other data definition record.
This means that when you first set up a series of "default" data definition records, you should put an A in the D/CODE field of each. If you subsequently need to remove one from the sequence, you can simply change the D/CODE field to an X. This way you do not break the sequence or have to copy the remaining "default" records to new names in order to fill the gap.
A data definition record with a number for a key can still be used in the same way as any other data definition record.
PREDEFINED DATA DEFINITION RECORDS
Some predefined data definition records are automatically available so that, if appropriate data definition records are not included in a file"s dictionary, a report can still be generated. These records do not physically exist on the system but are recognised when used in a jQL command sentence.
The predefined data definition records are named *A0 to *Annn. The numeric portion of the key corresponds to the position of the field they report on and the column heading will be the same as the DDR name.