Associating Entity Occurrences

IDD supports relationships between entity occurrences to enable the dictionary to correctly represent relational facts about the data resource. An example of such a relationship is the association between a user and a system.
idmscu19
IDD supports relationships between entity occurrences to enable the dictionary to correctly represent relational facts about the data resource. An example of such a relationship is the association between a user and a system.
Standard Relationships
The DDDL compiler establishes standard entity-occurrence relationships through the clauses shown in the following table.
More information: For more information on these clauses, see Entity-Type Syntax.
Clause
What it does
USER
Defines the relationship between an entity occurrence and its users. This clause is valid in all entity types except CLASS, LOAD MODULE, MESSAGE, and USER and is described under Securing the Dictionary, earlier in this section.
WITHIN SYSTEM
Defines the relationship between a destination, line, logical terminal, map, module, physical terminal, process, program, qfile, queue, table, or task and a system or subsystem.
Nesting clauses
Expresses hierarchical relationships between two users, systems, files, elements, or programs.
Standard Nesting Clauses
The standard nesting clauses are as follows:
Entity type
Clause
ELEMENT
SUBORDINATE ELEMENT
FILE
RELATED FILE
PROGRAM
PROGRAM CALLED
SYSTEM
WITHIN SYSTEM
USER
WITHIN USER
User-defined Relationships
The DDDL compiler also supports user-defined entity-occurrence relationships through the following:
  • User-defined nests
    Express relationships between entities of the same type in terms that are meaningful within the user environment. IDD supports user-defined nests through
    relational keys
    .
  • Class/attribute structures
    Relate documentation characteristics known as
    attributes
    to entity occurrences.
Relational keys and attribute/entity relationships are discussed separately in this section.
Relational Keys
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.
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
  • ENTIty type name is
    entity-type-name
    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
  • PREpared/REVised by
    user-id
    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 section.
  • PASsword is
    password
    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.
  • USER DEFINED NEST is
    relational-key
    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 section). This parameter can be repeated to add any number of relational keys.
    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.
  • TEXt is
    user-text
    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.
  • INVerse key is
    inverse-relational-key
    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.
  1. The following statement defines a relational key for the USER entity type with an inverse relational key.
    modify entity user revised by j-user include user defined nest is 'manages' inverse key is 'works for'.
  2. Three USER definitions are added to the dictionary. JOE is added without the use of relational keys. BOB is added to the dictionary, and his relationship with ANN is documented using the inverse relational key. ANN is added to the dictionary, and her relationship with JOE is documented using the primary relational key.
    add user joe. add user ann 'manages' joe. add user bob 'works for' ann.
  3. The resulting definitions are displayed.
    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
  • relational-key
    is
    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.
  • entity-occurrence-name
    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.
    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)).
  • Version is
    version-number
    /HIGhest/LOWest
    Qualifies nonunique entity-occurrence names for the relational-key clause.
  • TEXt is
    user-text
    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.
Attribute/Entity Relationships
Attributes are characteristics that can be assigned to entities.
Classes are categories of attributes.
For example, the attributes COBOL, Assembler, and PL/I are assignable to programs and are grouped into a class called LANGUAGE.
For more information on the rules for defining attributes and classes, see the ATTRIBUTE and CLASS sections.
A Class Must Exist in the Dictionary
A class must exist in the dictionary in order for attributes within that class to be related to entity occurrences. Each class definition contains qualifiers that determine how attributes within the class are added to the dictionary and govern how many attributes can be related to each entity occurrence. These qualifiers are described in the following table.
Qualifiers for Attributes
To do this
Use these qualifiers
Specify how attributes are added to the dictionary
Manual
Attributes within classes assigned the manual qualifier must be defined in the dictionary explicitly with ADD ATTRIBUTE statements before being associated with an entity occurrence. Typically, the manual qualifier applies to classes having a limited number of attributes that can be easily predefined. For example, the class SEX has only two attributes, MALE and FEMALE. These attributes must exist in the dictionary before they can be related to occurrences of the USER entity.
Automatic
Attributes within classes assigned the automatic qualifier are added to the dictionary automatically. The automatic qualifier applies to classes having an unlimited number of attributes that would be difficult to predefine. For example, the class BIRTH DATE has unlimited attributes. These attributes are added to the dictionary automatically when they are related to occurrences of the USER entity.
Specify how many attributes can be related to each entity occurrence
Singular
Only one attribute can be related to each entity occurrence. For example, if attributes within the class LANGUAGE are to be related to programs, LANGUAGE should be assigned the singular qualifier because only one language (for example, COBOL) is valid for a single program.
Plural
An unlimited number of attributes can be related to each entity occurrence. For example, if attributes within the class LANGUAGE are to be related to users, LANGUAGE should be assigned the plural qualifier because a user could be proficient in several languages.
Standard Classes - LANGUAGE and MODE
The Integrated Data Dictionary automatically creates two standard classes; these classes and their qualifiers are as follows:
  • LANGUAGE
    class -- Qualifiers are MANUAL PLURAL.
  • MODE
    class -- Qualifiers are AUTOMATIC PLURAL.
The IDD installation procedure assigns attributes to the LANGUAGE class (for example, OLQ, CULPRIT, COBOL).
Class/Attribute Clause
The repeatable
class/attribute clause
, valid in all entity-type statements, is used to establish attribute/entity relationships.
Syntax: Class/attribute Clause
┌───────────────────────────────────────────────────────────────┐ ►►──▼─┬─ LANGUAGE ───┬─ is
attribute-name
──┬─────────────────────┬─┴─────────►◄ ├─ MODE ───────┤ └─ TEXt is
user-text
─┘ └─
class-name
─┘
Parameters
  • LANGUAGE/MODE/
    class-name
    is
    Specifies the class in which the named attribute participates. Specify LANGUAGE or MODE to relate an attribute within the predefined class LANGUAGE or MODE to the requested entity occurrence. Specify
    class-name
    to relate an attribute within a user-defined class to the requested entity occurrence. The name must be 1 through 20 characters in length, must reference a class that has been defined in the dictionary with an ADD CLASS statement, and must be coded on one input line.
    Class-name
    cannot be abbreviated.
    The specification of LANGUAGE or MODE affects the processing of other CA IDMS data-management components and should be used with care.
  • attribute-name
    Specifies the attribute to be related to the named entity. The named attribute must exist in the dictionary if the named class is assigned the manual qualifier. If
    attribute-name
    includes embedded blanks or delimiters, it must be enclosed in site-standard quote characters. The specified attribute name must be unique within the named class but need not be unique within the dictionary.
  • TEXt is
    user-text
    Associates 1 through 40 characters of documentation text with this attribute/entity relationship. If the text includes embedded blanks or delimiters, it must be enclosed in site-standard quote characters.
Examples
Assuming that class DATE-OF-HIRE has been defined with the automatic qualifier, the following statement adds user JCD and attribute 2/25/87 to the dictionary and relates this attribute to both user JCD and class DATE-OF-HIRE.
add user jcd date-of-hire is 2/25/87.
Using the predefined class LANGUAGE, the following statement associates the predefined attribute COBOL with the program BILLING.
modify program billing language is cobol.