Relational keys are user-defined keywords that relate entities of the same type. The user can associate any number of relational keys with occurrences of the ATTRIBUTE, ELEMENT, FILE, MODULE, PROGRAM, RECORD, SYSTEM, USER, and user-defined entity types by including a relational-key clause within the applicable entity-type statement. Relational-key clauses are functionally similar to standard DDDL nesting clauses; however, the use of a relational key allows the user to express the relationship in more precise terms.
Defining Relational Keys
To define a relational key, the user must issue a MODIFY ENTITY statement to modify the standard ENTITY definition established during IDD installation.
Note: Do not use the MODIFY ENTITY statement to add user-defined entities to the dictionary; the result of such use is unpredictable.
Syntax: MODIFY ENTITY Statement (for user-defined nests)
►►─── MODify ENTIty type name is entity-type-name ────────────────────────────► ►─┬─────────────────────────────────────────────────────────┬────────────────► └─┬─ PREpared ─┬─ by user-id ─┬─────────────────────────┬─┘ └─ REVised ──┘ └─ PASsword is password ──┘ ┌────────────────────────────────────────────────────────────────────────── ►─▼─┬─ INClude ◄ ─┬─ USER DEFINED NEST is relational-key ────────────────────►─ └─ EXClude ───┘ ─────────────────────────────────────────────┐ ─►─┬─────────────────────────────────────────┬─┴──────────────────────────────►◄ ├─ TEXt is user-text ─────────────────────┤ └─ INVerse key is inverse-relational-key ─┘
Parameters
Specifies the entity type that is the object of the modification. Entity-type-name can be any standard IDD entity-type name; however, several entity types cannot appear in this clause. A list of the substitute names to be used for these entity types follows:
|
Entity type |
Substitute name |
|---|---|
|
ENTRY POINT |
PROGRAM |
|
PROCESS |
MODULE |
|
QFILE |
MODULE |
|
REPORT |
RECORD |
|
SCREEN |
PANEL |
|
SUBSYSTEM |
SYSTEM |
|
TABLE |
MODULE |
|
TRANSACTION |
RECORD |
|
User-defined entity |
ATTRIBUTE |
Identifies the user requesting the operation. The PREPARED BY clause can be used when a new comment key definition is added to the dictionary; REVISED BY can be used when a comment key is changed. For the rules pertaining to the PREPARED/REVISED BY clause, refer to Securing the Dictionary, earlier in this chapter.
Specifies the password of the user named in the PREPARED BY/REVISED BY clause. If the named user has been assigned a password, this parameter must be specified.
Identifies the relational key to be associated with (INCLUDE) or dissociated from (EXCLUDE) the object entity type; INCLUDE is the default. Relational-key must be a unique 1- through 40-character value. Values that contain embedded blanks or delimiters, or that duplicate a keyword from the DDDL syntax must be enclosed in site-standard quote characters. The same relational key can be defined for multiple entity types; however, a keyword defined as a comment key for the object entity cannot be defined as a relational key for the same entity (see COMMENTS Clause, earlier in this chapter). This parameter can be repeated to add any number of relational keys.
Note: Use the EXCLUDE option with care. If a relational key is excluded from an entity type, relationships between occurrences of that entity that are based on the excluded relational key cannot be deleted, reported on, or reestablished with the INCLUDE option. First, delete the relationship from all entity occurrences; then exclude it from the ENTITY definition.
Associates documentation text with the relational key. User-text must be 1 through 40 characters in length and, if it includes delimiters or embedded blanks, must be enclosed in site-standard quote characters.
Associates a second relational key with the primary relational key. Inverse-relational-key is a unique 1- through 40-character value. Values that contain embedded blanks or delimiters or that duplicate a keyword from the DDDL syntax must be enclosed in site-standard quote characters.
When two entity occurrences are associated with the primary relational key, the DDDL compiler automatically maintains the logical connections implied by the secondary (inverse) key as well as those associated with the primary key. The DDDL compiler also maintains primary and secondary connections when two entity occurrences are associated with an inverse relational key. The user can modify the inverse relational key without affecting all occurrences of the primary relational key.
Example
The following 3-step example illustrates the use of relational keys and inverse relational keys.
modify entity user
revised by j-user
include user defined nest is 'manages'
inverse key is 'works for'.
add user joe.
add user ann
'manages' joe.
add user bob
'works for' ann.
display user joe.
*+ add
*+ user name is joe
*+ 'works for' is ann
*+ .
display user bob.
*+ add
*+ user name is bob
*+ 'works for' is ann
*+ .
display user ann.
*+ add
*+ user name is ann
*+ 'manages' is joe
*+ 'manages' is bob
*+ .
Using Relational-key Clauses
The user can include a relational-key clause within the applicable entity-type statement to associate an entity occurrence with an occurrence of the same entity type. The relational-key clause can be repeated using the same or different relational keys to associate the entity occurrence with additional occurrences of the same entity type. The DDDL compiler rejects any relational-key clauses that attempt to duplicate existing relationships.
Syntax: RELATIONAL-KEY Clause
┌────────────────────────────────────────────────────────────────────────── ►►─▼─ relational-key is entity-occurrence-name ───────────────────────────────►─ ─────────────────────────────────────────────────────────────────┐ ─►─┬───────────────────────────────────┬──┬──────────────────────┬─┴──────────►◄ └─ Version is ─┬─ version-number ─┬─┘ └─ TEXT is user-text ──┘ ├─ HIGhest ────────┤ └─ LOWest ─────────┘
Parameters
Names an existing relational key. The specified value must be enclosed in site-standard quote characters if it contains embedded blanks or delimiters, or if it duplicates a DDDL compiler keyword. Because the DDDL compiler recognizes relational keys as keywords, the specified relational key can be abbreviated.
Names the entity occurrence to which the object entity occurrence is being related. If entity-occurrence-name is qualified by multiple versions, the optional VERSION clause must be specified.
Note: The user can supply a LANGUAGE parameter to uniquely identify occurrences of the MODULE entity type in relational-key clauses (see MODULE (PROCESS/QFILE/TABLE)).
Qualifies nonunique entity-occurrence names for the relational-key clause.
Associates 1 through 40 characters of documentation text with the nested structure being defined. If the text contains embedded blanks or delimiters, it must be enclosed in site-standard quote characters.
Examples
The following statement associates the previously-defined file WEEKLY-SALES with the new file, INVOICES, by means of the relational key SIMILAR FILE.
add file invoices
'similar file' is weekly-sales.
The following statements establish a relationship between users. Both departments and individuals are documented as users.
modify entity type name is user
user defined nest is department-number.
add user name is 122.
add user name is wmc
department-number is 122.
|
Copyright © 2014 CA.
All rights reserved.
|
|