Creates a relation definition.  A relation definition consists of a
 list of fields that make up an Rdb/VMS record.

 Example:

 RDO> DEFINE RELATION DEPARTMENTS.
 cont>   DEPARTMENT_CODE.
 cont>   DEPARTMENT_NAME.
 cont>   MANAGER_ID BASED ON ID_NUMBER.
 cont> END DEPARTMENTS RELATION.

Additional information available:

MoreFormatExamples

 You can copy a shareable relation definition from the data dictionary
 into the database using the FROM PATHNAME clause of the DEFINE
 RELATION statement.

 When the DEFINE RELATION statement executes, Rdb/VMS:

  o  Adds the relation definition to the physical database.  If you
     have invoked the database with the PATHNAME specification, the
     definition is also added to the data dictionary.
  o  Creates a default access control list (ACL) for the relation.

 There are several ways to use the DEFINE RELATION statement to
 specify the attributes of fields:

  o  When you define a relation, you can simply list the names of
     fields defined globally for the database, or you can define
     fields explicitly.
  o  You can also base the local field definitions on existing global
     definitions, but give them local attributes.  For example, when
     you use the BASED ON qualifier, the field takes the local name
     you give it in the DEFINE RELATION statement, but it derives its
     other attributes from the global field on which it is based.
  o  You can also use the DATATRIEVE clauses both globally and
     locally.  When you use the DATATRIEVE clauses within the DEFINE
     RELATION statement, they override the DATATRIEVE characteristics
     specified for the global definition.

 You must execute this statement in a READ_WRITE transaction.  If you
 issue this statement when there is no active transaction, Rdb/VMS
 starts a READ_WRITE transaction implicitly.

 You can have a maximum of 2000 fields in a relation.

 DEFINE RELATION ──> name ──┬─> 
F
R
O
M 
P
A
T
H
N
A
M
E path-name────────┐
                            │                                  │
                            └─┬──────────────>─────────────┬─┐ │
                              ├─> 
E
N
A
B
L
E  ─┬─>
C
O
M
P
R
E
S
S
I
O
N ─┘ │ │
                              └─> 
D
I
S
A
B
L
E ─┘                 │ │
 ┌────────────────────────────<──────────────────────────────┘ │
 │                                                             │
 └──┬───────────────>─────────────────┬───────> . ───────────┐ │
    └─> 
D
E
S
C
R
I
P
T
I
O
N typebox (I)typebox (S)  typebox (/)typebox (*)text*/ ─────┘                      │ │
 ┌────────────────────────────────<──────────────────────────┘ │
 │                                                             │
 └┬─┬─────────>──────┬───┬─> global-field-name ────┬─> . ──┬─┐ │
  │ └─> typebox (/)typebox (*) text */ ──┘   ├─> global-field-def ─────┤       │ │ │
  │                      └─> local-field-def ──────┘       │ │ │
  └──────────────────────────<─────────────────────────────┘ │ │
 ┌───────────────────────────<───────────────────────────────┘ │
 │                                                             │
 └────> 
E
N
D ───┬────>────┬─────────  typebox (R)typebox (E)typebox (L)typebox (A)typebox (T)typebox (I)typebox (O)typebox (N) ─────────────────┴───> .
               └─> name ───┘

Additional information available:

namepath-nametextCOMPRESSION clausefield-clause

 The name of the relation definition you want to create.  When
 choosing a name, follow these rules:

  o  Use a name that is unique among all relation and view names in
     the database.
  o  Use any valid VMS name.  However, the name cannot end in a dollar
     sign ($) or underscore (_).
  o  Do not use any Rdb/VMS reserved words (See the VAX Rdb/VMS
     Reference Manual appendix for reserved words).

 A full or relative data dictionary path name, enclosed in quotation
 marks, specifying the source of the shareable relation definition.
 You must invoke the database by path name if you plan to copy a
 shareable relation definition from the data dictionary.

 A text string that adds a comment to the relation definition or the
 field definition.

 The ENABLE/DISABLE COMPRESSION option in the DEFINE RELATION
 statement is obsolete.  Use the DEFINE STORAGE MAP and CHANGE STORAGE
 MAP statements to control data compression.  The COMPRESSION option
 in the DEFINE RELATION statement is maintained for compatibility with
 applications that used previous versions of Rdb/VMS.  However,
 DIGITAL recommends you use the new DEFINE STORAGE MAP statement
 rather than the DEFINE RELATION statement to control data
 compression.

 The name of a field that is part of the set of generic field
 definitions for the database.  You can use a field name in any one of
 three ways in the DEFINE RELATION statement:

  o  Refer to an existing global field by name.  This includes the
     global definition in the relation.
  o  Refer to a new global field name and include a complete
     definition, including a DATATYPE clause.  This includes the field
     definition in the relation and also enters the field definition
     in the global set of definitions for the database.
  o  Refer to an existing global field in a BASED ON clause.  This
     causes the field to have a local name and a global definition.

 Example 1

 The following example uses DEFINE RELATION to create a relation:

 DEFINE RELATION DEPARTMENTS.
    DEPARTMENT_CODE.
    DEPARTMENT_NAME.
    MANAGER_ID BASED ON ID_NUMBER.
 END DEPARTMENTS RELATION.

 This statement names the new relation, DEPARTMENTS, and specifies its
 fields.

  o  DEPARTMENT_CODE and DEPARTMENT_NAME are already defined.  The
     relation definition simply uses their names.

  o  MANAGER_ID is a local name, but it points to an existing global
     field definition.  If the definition of ID_NUMBER changes,
     MANAGER_ID changes also.


 Example 2

 The following example defines global fields in the DEFINE RELATION
 statement:

 DEFINE RELATION FAMILY
       DESCRIPTION IS /* Family information */.
   /* Employee ID * /
          EMPLOYEE_ID BASED ON ID_NUMBER
          QUERY_NAME FOR DTR IS "EMP".
   /* Married?  M or S */
          MARITAL_STATUS
                DATATYPE TEXT SIZE 1
                VALID IF MARITAL_STATUS = "M" OR
                         MARITAL_STATUS = "S".
   /* Number of dependents */
          NUMBER_DEPENDENTS
                DATATYPE SIGNED WORD SCALE 0.
   /* Amount of IRS withholding */
          WITHHOLDING
                COMPUTED BY 0.20 / NUMBER_DEPENDENTS.
 END FAMILY RELATION.

 This DEFINE RELATION statement defines several new fields:

  o  The DESCRIPTION clause and the other text fields provide
     commentary for the relation definition and for each field.

  o  EMPLOYEE_ID is a local name for the global ID_NUMBER field.  The
     QUERY_NAME clause overrides any QUERY_NAME clause on ID_NUMBER.

  o  MARITAL_STATUS uses the DATATYPE clause.  Therefore,
     MARITAL_STATUS becomes a global field definition.  MARITAL_STATUS
     is entered in the list of global fields for the database, and
     other relations can use it by name.

  o  NUMBER_DEPENDENTS also becomes a global field definition.

  o  WITHHOLDING is a local field, defined in terms of
     NUMBER_DEPENDENTS.


 Example 3

 The following example copies a shareable relation definition from the
 data dictionary into the database:

 DEFINE RELATION EMP_INFO
   FROM PATHNAME 'DISK1:[DICTIONARY]CORP.PERS.EMP_INFO'.