File Definitions

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.

RECORD STRUCTURE

The fields of a file definition record that affect jQL reports are:

Field 7

Conversion code for key, if required. For date, time, etc.

Field 8

V code to notify a multivalued (sublist) field, if required. See Sublists - V Code.

Field 9

Justification for key. Can be one of the following (see Data Definition Records):

L	Left justified
R	Right justified
T	Text
U	Unlimited

Field 10

Column width for key. Default is 14 characters. Also see JBCIDLEN.

SUBLISTS - V CODE

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.

SYNTAX

V;;field-no

SYNTAX ELEMENTS

field-no is the number of the field which contains the sublist.

EXAMPLE

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:

Key	A1	Key	A21
001	CAMERA ASSY	001	LENS ASSY
002	A21]A22]A23	002	A210]A211
003	10	003	15

Key	A22	Key	A23
001	BODY	001	SHUT ASSY
002		002	A230]A231
003	10	003	11

Key	A210	Key	A211
001	OPTICS	001	BARREL
002		002
003	19	003	21

Key	A230	Key	A231
001	IRIS MECH	001	IRIS HOUSNG
002		002
003	13	003	14

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",
like this:

STOCK 001 D 002 003 004 005 006 007 008 V;;2 009 L 010 10

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:





:LIST WITHIN STOCK "A1" DESC COMPONENTS QTY



PAGE 1 Time Date



LEVEL STOCK Description.... Components Qty





1     A1    CAMERA ASSY     A21

        10


                           

A22


                           

A23


2     A21   LENS ASSY      

A210        15


                           

A211


3     A210  OPTICS

                    

19


3     A211  BARREL

                    

21


2     A22   BODY

                      

10


2     A23   SHUTTER ASSY    A230

       11


                           

A231


3     A230  IRIS MECH

                 

13


3     A231  FILM MECH

                 

14



8 RECORDS LISTED

DATA DEFINITION RECORDS

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:

Specify default output.
Associate field names with field numbers (column headings).
Perform output formatting.
Calculate new values based on the source data
Perform processing via conversion codes.

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:

to "join" or derive data from other fields or files.
to verify the presence (or absence) of records in other files.
to format their output in the most easily understood manner (to convert numeric 0 and 1 flags to "Yes" or "No", for example, or to output text like "Overdue" if one date field is older than another).
to generate statistical data like record sizes or counters.

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.

RECORD LAYOUT

All data definition records are defined in the same way:

Field|Description

1 D/CODE|Defines the record as a data definition record. Must be one of the following codes:

A marks a normal data definition record.

S obsolete but still supported. Was like the A type, but suppressed default column headings when field 3 was blank. Replaced by the A type with a backslash in field 3 to defeat heading.

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:

0	Refers to the record key - field number 0 (zero).
9998	Ordinal number of record at output (used for numbering or counting).
9999	Size of the record in bytes (excluding the key).

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.

7 Input/Output conversion codes|Used for processing the data after sort and selection but before output. See Conversion Codes.

Multiple conversion codes, separated by a value marks, will be processed from left to right.

8 Pre-process conversion codes|Used for processing the data before sort and selection and before field 7 codes. See Conversion Codes later.

Multiple conversion codes, separated by a value marks, will be processed from left to right.

9 Format|Specifies the layout of the data within the column. Can be any of the following:
L Left justified. If the data exceeds the column width specified in field 10, the data is broken at column width without respect to blank spaces.
R Right justify. If the data exceeds the column width specified in field 10, the data will be truncated.
T Text. Word wrap - like L (left justified) but, where possible, lines will be broken at the blank space between words.
U Unlimited. Data is output on one line ignoring column boundaries.

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.

EXPLICIT DEFAULTS

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.

IMPLICIT DEFAULTS

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.

jQL