Copying Record Definitions and Their Synonyms

Writing a Navigational DML Program › Copying Record Definitions and Their Synonyms

Copying Record Definitions and Their Synonyms

Typically, you copy subschema records into variable storage using the primary name that the record is known by in the schema. Synonyms are alternative names for existing dictionary entities. A given file, record, or element can have multiple names through the use of IDD synonyms. This allows all programs that use an entity such as a record to access the same entity definition but refer to it using a name that complies to the language in which the program is written.

Uses of Synonyms

Synonyms are typically used for the following reasons:

To allow you to copy schema-owned records into a program whose subschema is not associated with that schema. If a record has been copied into a schema, it can be copied only into a program that uses a subschema associated with that schema.
However, if your program uses a subschema that is not associated with that schema, you cannot copy the record definition into the program unless you do so through one of its synonyms. One way to do that is to specify a version number on the COPY IDMS statement:
```
COPY IDMS RECORD EMPLOYEE VERSION 100.
```
To allow different programming languages to access the same record definition. For example, in Assembler the EMPLOYEE record can be defined as EMPLOYE.
Note: The precompiler for PL/I automatically automatically converts hyphens to underscores. For example, if you define a record called NON-HOSP-CLAIM and copy its description into a PL/I program using the following statement:
```
INCLUDE IDMS (NON-HOSP-CLAIM);
```
The precompiler converts the hyphens to underscores:
```
DMLP         INCLUDE IDMS (NON-HOSP-CLAIM);
             DECLARE 1  NON_HOSP_CLAIM,
                     2  CLAIM_TYPECHARACTER (2);
```

Terminology for Using Synonyms

You should be familiar with the following terms:

Schema-owned refers to any record that is defined in a schema.
IDD-defined refers to any record defined using the DDDL compiler that has not been included in a schema.
Mode refers to the operating mode of your program (that is, BATCH, IDMS-DC, DC-BATCH, CICS, and so on). IDD-defined records can be assigned one of these modes, a mode of NON-MODESPECIFIC, or no mode attribute at all.
Language attribute refers to the optional attribute that can be included in IDD-defined records and synonyms. For example, LANGUAGE IS COBOL, LANGUAGE IS PL/I, or LANGUAGE IS DC.

How the Precompiler Performs COPY IDMS

When the precompiler selects which record or synonym to copy into your program, it first checks to see if you have specified a VERSION clause in the COPY command. If no VERSION clause is given, a two-fold search is undertaken, first for a record associated with the subschema and then, if the first test fails, for an IDD-defined record.

To determine if the specified record is associated with the subschema, the precompiler performs the following steps:

Forms a table of records defined in the subschema and their synonyms. This table contains all records copied into the subschema and, for every record copied, the names of its synonyms not copied into another subschema.
Searches this table to match the name of the record in the COPY statement. If a match is found, that record is copied in; if no match is found, the search continues as described below.

If you specify a VERSION clause or if the test listed above fails, the precompiler assumes that the record is an IDD-defined record and performs the following steps:

Identifies a candidate record. A record is a candidate if it has a synonym whose name matches the name specified in the COPY IDMS statement.
Checks the builder code. The candidate record is tested for being either schema-owned (builder code of S) or a subschema view (builder code of V). If either is true, the record is rejected and another candidate is examined.
Checks the VERSION clause. If a VERSION clause is specified on the COPY IDMS statement, the candidate record's version is compared to that specified. If they are not equal, the record is rejected and another candidate is examined.
Checks the language attribute. If the candidate record has a language attribute and it is different than that of the compiler being used (for example, PL/I), the record is rejected and another candidate is examined.
Checks the mode. The mode associated with the candidate record is compared with the operating mode specified in the program. If they match, the record remains a candidate. If there is no record with a match on mode and the candidate has a mode of NON-MODESPECIFIC, it remains a candidate. If there is no record with a matching mode or a mode of NON-MODESPECIFIC and the candidate has no mode associated with it, it remains a candidate. Otherwise, the record is rejected and another candidate is examined.
Rechecks the VERSION clause. If a VERSION clause is specified on the COPY IDMS statement, the candidate record is chosen as the one to be copied into the program. If no VERSION clause is specified, the candidate with the highest version meeting all the above criteria is chosen.