4.1 Introduction
In DATATRIEVE, you define a logical record with the DEFINE RECORD com-mand. The logical record is the basic unit that helps you store and interpret data.
To define the logical record, you combine field definition clauses that specify the characteristics of each field. This combination of fields determines the structure of the record and represents the relationships among the items of data you store in the fields.
For simple records, you can use the interactive Application Design Tool (ADT).
Chapter 3 of the Introduction toDATATRIEVE-ll explains the use of ADT. ADT does not allow you to use all the available field definition clauses, however, so you cannot use it to define all types of records.
This chapter briefly explains the elements of a record definition and the record and field definition clauses you can use to define records for DAT ATRIEVE domains. For more information about definition clauses, see the alphabetic list-ing for each clause in Chapter 5 in this manual. For more information on record and field definitions, see Chapter 5 oftheDATATRIEVE-ll User's Guide.
4.2 Components of a Record Definition
A record definition consists of one or more field definitions. Each field definition describes the field and its relationship to other fields in the record.
Every field definition consists of three parts:
• A level number that determines the relationship between the field and other fields in the record
• A field name that identifies the field
• A period (.) that signals the end of the field definition
Most field definitions also contain one or more field definition clauses.
4.3 Types of Fields
A record definition can contain both elementary and group fields. An elementary field is the basic unit of data. It contains no other field within it. A group field, on the other hand, contains elementary or group fields.
Every record definition must conform to the following rules for including elemen-tary and group fields:
• A record definition must contain at least one elementary field.
• If a record contains more than one elementary field, it must contain a group field that includes all other fields in the record.
• A group field must contain at least one other field.
4.3.1 Field Levels
Level numbers determine the relationship among fields in a record definition.
The YACHT record definition is shown in Figure 4-1.
Figure 4-1 The YACHT Record Definition
01 BOAT
03 TYPE
06 MANUFACTURER 06 MODEL
03 SPECIFICATIONS 06 RIG
06 LENGTH_OVER_ALL 06 DISPLACEMENT 06 BEAM
06 PRICE
A group field that contains all other fields in a record is at the first or top level. In the YACHT record, the group field BOAT contains all other fields in the record and is the top level field.
Second level fields are contained only in a top level field and in no other group field. TYPE and SPECIFICATIONS are both second level fields contained in and subordinate to the top level field BOAT. TYPE and SPECIFICATIONS are also group fields because they contain elementary fields. Fields subordinate only to a second level field are third level fields, and so on. MANUFACTURER and MODEL in the YACHT record, for example, are third level fields.
MANUFACTURER and MODEL are also elementary fields since they do not contain any lower-level fields. RIG, LENGTH_OVER_ALL, DISPLACEMENT,
4.3.2 Level Numbers
Every field in a record definition must have a level number that specifies its rela-tionship to the other fields in the record. DAT ATRIEVE recognizes field levels in a record definition according to the level numbers you assign to each field. Thus, the level number must be the first element of a field definition. The number of the highest possible level is 1, and the number of the lowest possible level is 65.
Leading zeros, as in 01 and 05, do not affect the value of the level number.
The top level field must have the smallest level number assigned to any field in the record definition. No other field in the record can have the same level number as the top level field. The level number usually assigned to the top level field is 01. Any field with a higher level number is subordinate to the top level field.
In the YACHT record definition, BOAT is the top level field and is the only field with the level number 01. TYPE and SPECIFICATIONS are second level group fields and have the same 03 level number. The seven elementary fields are all third level fields and have a level number of 06. MANUFACTURER and MODEL are subordinate to the TYPE field, while the other five elementary fields are sub-ordinate to SPECIFICATIONS.
The level numbers in the YACHT record definition illustrate several rules about assigning level numbers to fields:
• Only level numbers determine the relationships among fields.
• Level numbers need not be consecutive. Only the relative value of level num-bers determines the relationship between fields. TYPE and
SPECIFICATIONS, for example, could have level numbers of 02, 04, or 05 and the YACHT record structure would still be the same as defined in Figure 4-1.
• Differences in level numbers mean differences in levels and differences in rela-tionship. Fields must have the same level number to be equivalent. If, for example, the elementary field LENGTH_OVER_ALL in the
SPECIFICATIONS field had a level number of 07, the field immediately pre-ceding it, RIG, would become a group field containing LENGTH_OVER_ALL.
Fields in the YACHTS record definition and in other examples in this book are indented to show their relationship to other fields. Indenting fields helps clarify the structure of the record, but has no effect on the relationship among fields.
4.4 Field Names
In addition to a level number, every field in a record must have a field name. You use the field name to identify the field in DAT ATRIEVE statements and
DATATRIEVE uses the field name when printing the contents of the field. A field name must conform to DATATRIEVE's rules for names:
• A name can consist offrom 1 to 31 letters, digits, hyphens (-), and underscores
(-)
.
• A name must begin with a letter and must end with a letter or digit.
• A name cannot duplicate a DATATRIEVE keyword. See Appendix A for a list / ofDATATRIEVE keywords.
• A name can be continued from one line to another only by using a hyphen (-), the DATATRIEVE continuation character.
• A name can duplicate another field name in the same record definition only if the duplicate field names are in different group fields. Duplicating field names in a record is not a good data management practice.
See Chapter 5 oftheDATATRIEVE-ll User's Guide for a more detailed list of rules for DATA TRIEVE names.
4.4.1 QUERY_NAME and QUERY_HEADER Clauses
By using the QUERY _NAME clause in a field definition, you can specify an alternate name for a field. You can then use the query name in place of the field name in DATATRIEVE statements. The YACHT record definition, for example, specifies the query name BUILDER for the MANUFACTURER field and the query name SPECS for the SPECIFICATIONS field. See Chapter 5 for more information on the QUERY _NAME clause.
You can also specify a QUERY _HEADER for a field. If you do not include a QUERY _HEADER clause, DATATRIEVE uses the field name as the column header for the field when displaying data. If you include a QUERY _HEADER clause in the field definition, DATATRIEVE uses the query header, instead of the field name, for the column header. You can override the printing of the field name or query header by specifying a column header modifier as part of a print list element in the PRINT, SUM, and REPORT statements. See the sections in Chapter 5 on these statements for more information.
4.4.2 FILLER Field Name
By using the FILLER keyword as the name of an elementary or group field, you can mask fields in a data file:
• Use FILLER as an elementary field to reserve space in the physical record of the data file or to suppress the display of fields that you do not want to lose, but do not want or need to display.
• Use FILLER as a group field to access elementary fields in the group and to suppress display of the entire group field.
You cannot retrieve data from or store data in a FILLER field.
Like other fields, a field named FILLER must have a level number. It can also contain field definition clauses. You can use the name FILLER for more than one field at the same level in a group field. When you use the PRINT, MODIFY, STORE, REPORT, and SUM statements to retrieve, update, or store the contents of a record, DATATRIEVE ignores values in FILLER fields.
Do not use FILLER fields, however, to protect sensitive information stored in physical records. The DISPLAY statement displays all the contents of a group field, regardless of the field names in the record definition.
If the FILLER field is an elementary field, you cannot get access to data in the field with any statement except DISPLAY. If FILLER is the name ofa group field, you can access data in the physical record by specifying the name of an ele-mentary or group field in the FILLER group field. Each of those fields has its own valid name, and you can retrieve the value by specifying that name in a record selection expression, a print list, or a field list. You cannot access data in the physical record by using the group name (FILLER) or by retrieving for output whole records or group fields containing the group field named FILLER.
DATATRIEVE stops accessing fields in a group when it encounters the name FILLER and moves to the next field at the same level or at a higher level.
The following example shows the use of FILLER fields to mask two elementary fields of the PERSONNEL data file, EMPLOYEE_STATUS and SALARY, for two different types of retrieval from the same data file:
DTR> SHOW PERSONNEL(@) DOMAIN PERSONNEL
USING PERSONNEL_REC ON PERSON.DAT;
DTR> SHOW PERSONNEL_M~
DOMAIN PERSONNEL_M
USING PERSONNEL_MASK ON PERSON.DAT;
DTR) SHOW PERSONNEL_REC~
RECORD PERSONNEL_REC USING
01 PERSON.
05 ID PIC IS 8(5).
05 EMPLOYEE_STATUS PIC IS X(ll)
QUERY_NAME IS STATUS
05 EMPLOYEE_NAME
DTR> SHOW PERSONNEL_MASK~
RECORD PERSONNEL_MASK
QUERY_HEADER IS IISTATUSII
1.'ALID IF STATUS EQ IITRAINEEII tIlE}-{PERIENCED Il • QUERY_NAME IS NAME.
PIC IS }-{(10)
QUERY_NAME IS F_NAME.
PIC IS }-{(10)
QUERY_NAME IS L_NAME.
PIC IS }onc
QUERY_NAME IS STATUS QUERY_HEADER IS IISTATUS II
1.IALID IF STATUS EQ IITRAINEEII tIlE}-{PERIENCED Il • QUERY_NAME IS NAME.
PIC IS }-{(10)
QUERY_NAME IS F_NAME.
PIC IS }-{(10)
QUERY_NAME IS L_NAME.
PIC IS }OO{.
4.5
DTR> READY PERSONNEL(8Dl DTR> READY PERSONNEL_M(8Dl
DTR> FIND FIRST 5 A IN PERSONNEL(8Dl
00012 CHARLOTTE SPlI.JA TOP 12-Sep-72
00891 FRED HOWL F11 9-Apr-78
DAT ATRIEVE classifies fields in a record by the type of data contained in the field and by the way data is stored. Table 4-1 summarizes field classes and their content.
Table 4-1: Field Classes and Content
Field Type Class Content
Elementary Alphanumeric Any valid ASCII character Numeric Any combination of digits and an
optional sign ( + or -)
DATE A date
COMPUTED BY None; the field definition specifies a value expression, but no value is stored in the record Group Alphanumeric The values of the fields
contained in the group field