RECORD (REPORT/TRANSACTION)

Typically, record occurrences consist of groups of elements within a hierarchical structure required by a program or schema; however, records can also exist without elements, usually for documentation or planning purposes. When the user includes an element within a record, the DDDL compiler creates a record element and associates it with the named record. A record can have a maximum length of 32,767 characters.
19-0-03
Typically, record occurrences consist of groups of elements within a hierarchical structure required by a program or schema; however, records can also exist without elements, usually for documentation or planning purposes. When the user includes an element within a record, the DDDL compiler creates a
record element
and associates it with the named record. A record can have a maximum length of 32,767 characters.
RECORD statements establish and maintain record occurrences but do not directly relate records to elements; the RECORD ELEMENT and COBOL substatements that follow ADD RECORD or MODIFY RECORD statements establish and maintain record-element structures. These substatements are used as follows:
  • RECORD ELEMENT substatement
    Identifies existing group and elementary elements and defines filler fields for use in the requested record. The DDDL compiler assigns a level number to each element and filler based on the SET OPTIONS statement LEVEL NUMBERS specification. Optional clauses supply record-specific element synonyms, OLQ and CULPRIT column headers, and record-specific editing, value, index, and multiply-occurring element specifications for each record element.
  • COBOL substatement
    Identifies new or existing elements in a format specific to COBOL language programs. Optional clauses support record synonyms, record-specific element synonyms, comments, and COBOL 74 options; allow the user to define the element's level number, picture, value, and usage; and supply REDEFINES, INDEXED BY, and OCCURS specifications.
COBOL substatements can be followed by RECORD ELEMENT substatements to modify an existing record-element structure. Note, however, that if a COBOL substatement follows a RECORD ELEMENT substatement, the DDDL compiler creates a new record-element structure that replaces the structure associated with the RECORD ELEMENT substatement.
Additional substatements allow the user to rebuild and remove record elements and define restricted record-element structures (called
views
) for use within subschemas and files.
Optional RECORD statement clauses relate records to existing files, users, and other records. (Record occurrences can be related to programs by means of the RECORD COPIED clause of the PROGRAM statement and the DML precompilers.) The RECORD statement also supports comments, attribute/entity relationships, and record synonyms.
If the keyword REPORT or TRANSACTION is used in place of RECORD, the DDDL compiler creates a special entity occurrence to document the report or transaction in the dictionary. These reports and transactions appear as distinct entity types on dictionary reports.
This article includes the following information:
2
2
RECORD Statement
Syntax
RECORD (REPORT) (TRANSACTION) statement
►►─┬─ ADD ─────┬─┬─ RECord ──────┬─ name is
record-name
──────────────────────► ├─ MODify ──┤ ├─ REPort ──────┤ ├─ REPlace ─┤ └─ TRAnsaction ─┘ └─ DELete ──┘ ►─┬────────────────────────────────────────────┬─────────────────────────────► └─ Version is ─┬─
version-number
──────────┬─┘ └─┬─────────┬─┬───────────┬─┘ └─ NEXt ──┘ ├─ HIGhest ─┤ └─ LOWest ──┘ ►─┬─────────────────────────────────────────────────────────┬────────────────► └─┬─ PREpared ─┬─ by
user-id
──┬────────────────────────┬─┘ └─ REVised ──┘ └─ PASsword is
password
─┘ ►─┬────────────────────────────────────┬─────────────────────────────────────► └─ ENTIty type is ─┬─ RECord ──────┬─┘ ├─ REPort ──────┤ └─ TRAnsaction ─┘ ┌────────────────────────────────────────────────────────────────────────┐ ►─▼┬──────────────────────────────────────────────────────────────────────┬┴─► └ SAMe as ┬ RECord ─────┬
record-name
┬───────────────────────────────┬┘ ├ REPort ─────┤ └ Version is ┬
version-number
─┬┘ └ TRAnsaction ┘ ├ HIGhest ────────┤ └ LOWest ─────────┘ ┌────────────────────────────────────────────────────────────────────────── ►─▼─┬────────────────────────────────────────────────────────────────────────►─ └─ COPY ─┬─ ALL COMments TYPes ─┬──────────────────────────────────────── ├─ COMments ───────────┤ ├─ DEFinition ─────────┤ ├─ ATTributes ─────────┤ ├─ USERS ──────────────┤ ├─ RECords ────────────┤ ├─ REPorts ────────────┤ ├─ TRAnsactions ───────┤ ├─
comment-key
────────┤ └─
relational-key
─────┘ ─────────────────────────────────────────────────────────────────────────┐ ─►───────────────────────────────────────────────────────────────────────┬─┴──► ── FROm ┬───────────────┬
record-name
┬───────────────────────────────┬┘ ├─ RECord ──────┤ └ Version is ┬
version-number
─┬┘ ├─ REPort ──────┤ ├─ HIGhest ───────┤ └─ TRAnsaction ─┘ └─ LOWest ────────┘ ►─┬─────────────────────────────┬─┬──────────────────────────────────────┬───► └ NEW NAMe is
new-record-name
┘ └ Version is ─┬─
version-number
─────┬─┘ └─ NEXt ─┬─ HIGhest ─┬─┘ └─ LOWest ──┘ ►─┬───────────────────────────────────────────┬──────────────────────────────► └─ NEW Version is ─┬─
new-version-number
─┬─┘ └─ NEXt ─┬─ HIGhest ─┬─┘ └─ LOWest ──┘ ►─┬──────────────────────────────────────────────────────┬───────────────────► └─┬───────────────┬─ DEScription is
description-text
──┘ ├─ record ──────┤ ├─ report ──────┤ └─ transaction ─┘ ┌─────────────────────────────────────────────────────────────────┐ ►─▼─┬─────────────────────────────────────────────────────────────┬─┴────────► └─┬─ INClude ◄ ─┬─ USEr is
user-id
──┬──────────────────────┬─┘ └─ EXClude ───┘ └─
user-specification
─┘ (for complete
user-specification
syntax, see USER clause) ►─┬──────────────────────────────────────────────────────┬───────────────────► └─ PUBlic access is ─┬───────────┬─ for ─┬─ ALL ◄ ───┬─┘ └─ ALLOwed ─┘ ├─ NONe ────┤ ├─ UPDate ──┤ ├─ MODify ──┤ ├─ REPlace ─┤ ├─ DELete ──┤ └─ DISplay ─┘ ►─┬────────────────────────────────────────────────────┬─────────────────────► └──┬─ RECord ──────┬─ STOrage is
storage-indicator
──┘ ├─ REPort ──────┤ └─ TRAnsaction ─┘ ►─┬─────────────────────────────────────────────┬────────────────────────────► └─ FORmat is ─┬─ PRIMAry ◄ ─────────────────┬─┘ └─
alternate-format-keyword
──┘ ►─┬────────────────────────────────────┬─────────────────────────────────────► └─ OCCurrences are
occurrence-count
─┘ ►─┬──────────────────────────────────────────────────────────────────────────►─ └─┬ INClude ◄ ─┬ WIThin FILe
file-name
┬───────────────────────────────┬─── └ EXClude ───┘ └ Version is ┬
version-number
─┬┘ ├ HIGhest ────────┤ └ LOWest ─────────┘ ─►──────────────────────────────────────────────────┬─────────────────────────► ───┬────────────────────────────────────────────┬─┘ │ ┌────────────────────────────────────────┐ │ └─▼─ KEY is
element-name
─┬──────────────┬─┴─┘ ├─ ASCending ──┤ └─ DEScending ─┘ ┌────────────────────────────────────────────────────────────────────────┐ ►─▼┬──────────────────────────────────────────────────────────────────────┬┴─► └┬─ INClude ◄ ┬┬ LANguage ──┬ is
attribute-name
─┬────────────────────┬┘ └─ EXClude ──┘├ MODe ──────┤ └ TEXt is
user-text
─┘ └
class-name
┘ ┌────────────────────────────────────────────────────────────────────────── ►─▼─┬────────────────────────────────────────────────────────────────────────►─ └┬ INClude ◄ ─┬┬─ RECord ─────┬ name SYNonym is ───────────────────────── └ EXClude ───┘├─ REPort ─────┤ └─ TRAnsaction ┘ ───────────────────────────────────────┐ ─►─────────────────────────────────────┬─┴────────────────────────────────────► ─┬─────────────────────────────────┬─┘ └─
record-synonym-specification
──┘ (expanded
record-synonym-specification
syntax follows this syntax diagram) ┌────────────────────────────────────────────────────────────────────────── ►─▼─┬────────────────────────────────────────────────────────────────────┬───►─ └─┬ INClude ◄ ─┬─
relational-key
is ─┬─ RECord ──────┬─
record-name
─┘ └ EXClude ───┘ ├─ REPort ──────┤ └─ TRAnsaction ─┘ ───────────────────────────────────────────────────────────────────┐ ─►─────────────────────────────────────────────────────────────────┬─┴────────► ─┬────────────────────────────────────┬──┬─────────────────────┬─┘ └─ Version is ─┬─
version-number
─┬──┘ └─ TEXt is
user-text
─┘ ├─ HIGhest ────────┤ └─ LOWest ─────────┘ ┌───────────────────────────────────────────────────────────────┐ ►─▼─┬───────────────────────────────────────────────────────────┬─┴──────────► │ ┌────────────────────┐ │ └─ EDIt ─┬─ COMments ──────┬─▼─
edit-instruction
─┴─ QUIT ──┘ ├─ DEFinition ────┤ ├─ OLQ header ────┤ ├─ CULprit header │ └─
comment-key
───┘ ┌──────────────────────────────────────────────────┐ ►─▼─┬──────────────────────────────────────────────┬─┴───────────────────────►◄ └─┬─ COMments ───────┬─ is ─┬─ NULl ─────────┬─┘ ├─ DEFinition ─────┤ └─
comment-text
─┘ ├─ OLQ header ─────┤ ├─ CULprit header ─┤ └─
comment-key
────┘
Expansion of
record-synonym-specification
►►───
record-synonym-name
────────────────────────────────────────────────────► ►─┬───────────────────────────────────────────┬──────────────────────────────► └─ Version is ─┬─
version-number
─────────┬─┘ └─┬────────┬─┬─ HIGhest ─┬─┘ └─ NEXt ─┘ └─ LOWest ──┘ ►─┬──────────────────────────────────────────────────────────────────────────►─ └─┬─ INClude ◄ ─┬─ FOR FILe synonym
file-synonym
────────────────────────── └─ EXClude ───┘ ─►───────────────────────────────────────┬────────────────────────────────────► ─┬───────────────────────────────────┬─┘ └─ Version is ─┬─
version-number
─┬─┘ ├─ HIGhest ────────┤ └─ LOWest ─────────┘ ►─┬──────────────────────────────────┬───────────────────────────────────────► └──┬─ PREfix ─┬─ is ─┬─
prefix
─┬──┘ └─ SUFfix ─┘ ├─
suffix
─┤ └─ NULl ───┘ ►─┬────────────────────────────────────────────────────────────────┬─────────►◄ └─┬─ INClude ◄ ─┬─ LANguage is
language
─┬─────────────────────┬─┘ └─ EXClude ───┘ └─ TEXt is
user-text
─┘
DISPLAY/PUNCH RECORD (REPORT) (TRANSACTION) statement (for a single record)
►►─┬─ DISplay ─┬──┬─ RECord ──────┬─ name is
record-name
─────────────────────► └─ PUNch ───┘ ├─ REPort ──────┤ └─ TRAnsaction ─┘ ►─┬───────────────────────────────────┬──────────────────────────────────────► └─ Version is ─┬─
version-number
─┬─┘ ├─ HIGhest ────────┤ └─ LOWest ─────────┘ ►─┬───────────────────────────────────────────────────┬──────────────────────► └─ PREpared by
user-id
─┬─────────────────────────┬─┘ └─ PASsword is
password
──┘ ┌────────────────────────────────────────────────────────┐ ►─▼─┬────────────────────────────────────────────────────┬─┴─────────────────► │ ┌───────────────────────────────┐ │ └─┬─ WITh ──────┬──▼─┬─ ALL ─────────────────────┬─┴─┘ ├─ ALSo WITh ─┤ ├─ ALL COMment TYPes ───────┤ └─ WITHOut ───┘ ├─ ATTRibutes ──────────────┤ ├─ COBol ───────────────────┤ ├─ COMments ────────────────┤ ├─ DEFinitions ─────────────┤ ├─ CULprit headers ─────────┤ ├─ DETails ─────────────────┤ ├─ ELements ────────────────┤ ├─ FILes ───────────────────┤ ├─ HIStory ─────────────────┤ ├─ MAPs ────────────────────┤ ├─ NONe ────────────────────┤ ├─ OLQ headers ─────────────┤ ├─ PICture OVErrides ───────┤ ├─ PROgrams ────────────────┤ ├─ RECELems ────────────────┤ ├─ RECords ─────────────────┤ ├─ REPorts ─────────────────┤ ├─ SAMe AS ─────────────────┤ ├─ SCHemas ─────────────────┤ ├─ SUBOrdinate ELements ────┤ ├─ SUBSChemas ──────────────┤ ├─ SYNonyms ────────────────┤ ├─ TRAnsactions ────────────┤ ├─ USErs ───────────────────┤ ├─┬─ USEr DEFINED COMments ─┤ │ └─ UDCs ──────────────────┤ ├─┬─ USEr DEFINED NESts ─┬──┤ │ └─ UDNs ───────────────┘ │ ├─ VIEws ───────────────────┤ └─ WHEre USED ──────────────┘ ►─┬──────────────────────────────────────────────────────────────────────────►─ └─ TO ─┬─ SYSpch ────────────────────────────────────────────────────────── └─ MODule
module-name
─┬───────────────────────────────────┬──────── └─ Version is ─┬─
version-number
─┬─┘ ├─ HIGhest ────────┤ └─ LOWest ─────────┘ ─►──────────────────────────────────────────────────────────────────────────┬─► ─────────────────────────────────────────────────────────────────────────┬┘ ─┬──────────────────────┬┬──────────────────────────────────────────────┬┘ └ LANguage is
language
┘└ PREpared by
user-id
┬───────────────────────┬┘ └ PASsword is
password
─┘ ►─┬──────────────────────┬──┬─────────────────────┬──────────────────────────►◄ └─ VERB ─┬─ DISplay ─┬─┘ └─ AS ─┬─ SYNtax ───┬─┘ ├─ PUNch ───┤ └─ COMments ─┘ ├─ ADD ─────┤ ├─ MODify ──┤ ├─ REPlace ─┤ └─ DELete ──┘
DISPLAY/PUNCH RECORD (REPORT) (TRANSACTION) statement (for multiple records)
►►─── DISplay ──┬─ ALL ──────────────────────────┬──┬─ RECords ──────┬────────► └─┬─ FIRst ─┬─┬─ 1 ◄ ──────────┬─┘ ├─ REPorts ──────┤ ├─ NEXt ──┤ └─
entity-count
─┘ └─ TRAnsactions ─┘ ├─ LASt ──┤ └─ PRIor ─┘ ►─┬──────────────────────────────────────────────────┬───────────────────────► └─ PREpared by
user-id
─┬────────────────────────┬─┘ └─ PASsword is
password
─┘ ►─┬─────────────────────────────────┬────────────────────────────────────────► └─ WHEre
conditional-expression
──┘ (for complete
conditional-expression
syntax, see WHERE clause) ►─┬──────────────────┬───────────────────────────────────────────────────────► └─ BY ─┬─ SET ◄ ─┬─┘ └─ AREa ──┘ ►─┬──────────────────────────────────────────────────────────────────────────►─ └─ TO ─┬─ SYSpch ────────────────────────────────────────────────────────── └─ MODule
module-name
─┬───────────────────────────────────┬──────── └─ Version is ─┬─
version-number
─┬─┘ ├─ HIGhest ────────┤ └─ LOWest ─────────┘ ─►──────────────────────────────────────────────────────────────────────────┬─► ─────────────────────────────────────────────────────────────────────────┬┘ ─┬──────────────────────┬┬──────────────────────────────────────────────┬┘ └ LANguage is
language
┘└ PREpared by
user-id
┬───────────────────────┬┘ └ PASsword is
password
─┘ ►─┬──────────────────────┬──┬──────────────────────────────────────┬─────────►◄ └─ VERB ─┬─ DISplay ─┬─┘ └─ AS ─┬─ SYNtax ───┬──┬─────────────┬─┘ ├─ PUNch ───┤ └─ COMments ─┘ └─ RECursive ─┘ ├─ ADD ─────┤ ├─ MODify ──┤ ├─ REPlace ─┤ └─ DELete ──┘
Parameters
  • RECord/REPort/TRAnsaction name is
    record-name
    Identifies a new record (report, transaction) to be established in the dictionary, or an existing record to be modified, replaced, deleted, displayed, or punched.
    Record-name
    must be a 1- through 32-character alphanumeric value.
    The combination of the record name and version number must be unique in the dictionary; that is, it must not duplicate the primary or synonym name of an existing record, report, or transaction.
  • ENTIty type is RECord/REPort/TRAnsaction
    Changes the entity-type name to RECORD, REPORT, or TRANSACTION. This clause is meaningful only with a MODIFY statement.
  • SAMe AS RECord/REPort/TRAnsaction
    record-name
    Copies all entries associated with the specified record occurrence, with the exception of the NAME, WITHIN FILE, RECORD NAME SYNONYM and associated options, ELEMENT NAME SYNONYM, INDEXED BY FOR RECORD SYNONYM, and VIEW ID specifications.
  • NEW NAMe is
    new-record-name
    Specifies a new name for the requested record. This clause changes the name of the record occurrence only; it does not alter or delete any relationships in which the record participates. Subsequent references to the record must specify the new name.
    New-record-name
    must be a 1- through 32-character alphanumeric value. The combination of the new record name and version number must not duplicate that of an existing record, report, transaction, or synonym in the dictionary. If the requested record participates in a schema, the NEW NAME clause is not valid.
  • NEW Version is
    new-version
    /NEXt HIGhest/NEXt LOWest
    Specifies a new version number for the named record. The combination of the record name and new version number must not duplicate that of an existing record, report, transaction, or synonym in the dictionary.
  • RECord/REPort/TRAnsaction STOrage is
    storage-indicator
    Documents the named record's storage medium or method; for example, tape or disk.
    Storage-indicator
    must be a 1- through 16-character alphanumeric value.
  • FORmat is
    Specifies the format to be assigned to every element that participates in the named record-element structure.
    This specification applies only to elements that are included in the named record by means of the RECORD ELEMENT substatement.
  • PRIMary
    Specifies that the primary format is to be used.
  • alternate-format-keyword
    Specifies that an alternative format is to be used.
    Alternate-format-keyword
    must reference a valid alternative picture keyword as defined in the SET OPTIONS statement. If an element within the record does not have a corresponding alternative format, the DDDL compiler assigns the primary format to that element. For further discussion of alternative formats, see ELEMENT, earlier in this section. Also see SET OPTIONS Statement.
  • OCCurrences are
    occurrence-count
    Specifies the actual or estimated number of times the record will occur in files or databases.
    Occurrence-count
    must be in the range 0 through 2,147,483,647. This clause is documentation only.
  • WITHIN FILE
    file-name
    Associates (INCLUDE) or disassociates (EXCLUDE) a file in which the named record occurs.
    File-name
    must be the primary name of an existing file. This clause creates a record-synonym/for-file-synonym relationship between the primary record synonym and primary file synonym established by means of the FOR FILE SYNONYM parameter (described below). WITHIN FILE is documentation only. The KEY parameter is not valid with EXCLUDE.
  • KEY is
    element-name
    Specifies that the named record is sequenced on keys within the file.
    Element-name
    specifies the names of fields to be used for sort control; the specified element need not participate in the named record. Each record definition can include up to five KEY parameters.
  • ASCending
    Specifies that the records in the file are sorted by
    element-name
    in sequence from lowest to highest value.
  • DEScending
    Specifies that the records in the file are sorted by
    element-name
    in sequence from highest to lowest value.
  • LANguage/MODe/
    class-name
    is
    attribute-name
    Relates the named record to the named attribute by means of the specified class. The following considerations apply if the LANGUAGE or MODE class is specified:
    • LANGUAGE
      identifies the language of programs in which the named record will be used. If LANGUAGE is specified,
      attribute-name
      must identify an existing attribute within the LANGUAGE class.
    • MODE
      identifies the operating mode of programs in which the named record will be used.
    For additional rules pertaining to this clause, see Attribute/Entity Relationships.
  • RECord/REPort/TRAnsaction NAMe synonym is
    Establishes (INCLUDE) or removes (EXCLUDE) a synonym (alternative name) for the record or modifies an existing synonym. When a record is added to the dictionary, the DDDL compiler builds a record synonym using the record's primary name and version number. This synonym is known as the primary record synonym. Any number of synonyms can be defined for the primary record synonym. If EXCLUDE is specified, only the RECORD NAME SYNONYM parameter is valid.
  • record-synonym
    Specifies the 1- through 32-character name of a record synonym or the primary record name. If the optional VERSION parameter is not specified, the DDDL compiler uses the default version number established in the SET OPTIONS statement DEFAULT FOR EXISTING VERSION clause; if no record synonym exists with the default existing version, the DDDL compiler uses the default version number established in the SET OPTIONS statement DEFAULT FOR NEW VERSION clause.
  • FOR FILe synonym
    file-synonym
    Associates (INCLUDE) the primary file or file synonym with, or disassociates it from (EXCLUDE), the record synonym. In the CA IDMS COBOL environment, this relationship determines which record synonyms are copied into a program when the DMLC precompiler performs an FD COPY function. In the CA Culprit environment, this relationship determines which record synonyms are associated with the CA Culprit file.
  • PREfix/SUFfix is
    prefix
    /
    suffix
    /NULl
    Specifies a prefix or suffix for use with all elements that participate in the named record-element structure or removes an existing prefix or suffix. The specified prefix or suffix does not become part of the record synonym. However, the DDDL compiler adds the prefix/suffix to the beginning/end of the element or element synonym to form the record-specific element synonym.
    Prefix
    /
    suffix
    must be a 1- to 10-character value. The combined length of the element name and the prefix or suffix must not exceed 32 characters. If the resulting element-synonym name exceeds 32 characters, the DDDL compiler truncates the element name before adding the prefix or suffix.
  • LANguage is
    language
    Associates a language defined as an attribute of the LANGUAGE class with, or disassociates it from, the record synonym. The DML precompilers use the LANGUAGE specification to determine the correct record synonyms to be copied into programs written in various languages.
  • WITh/ALSo WITh/WITHOut
    Includes or excludes the specified options when the named record is displayed or punched. Detailed information for each DISPLAY/PUNCH option is under SET OPTIONS Syntax. The options that are listed below present special considerations for this entity type.
  • DETails
    Includes the DESCRIPTION, RECORD STORAGE, FORMAT, OCCURRENCES, VIEW ID, and RECORD LENGTH (displayed as comments) specifications.
  • ELements
    Includes the specifications that describe the record-element format. ELEMENTS displays the names of record elements that are not subordinate to any other elements. To exclude elements from the display, specify WITHOUT ELEMENTS.
  • RECords
    Includes all user-defined nests defined for the named record.
  • REPorts
    Includes all user-defined nests defined for the named report.
  • TRAnsactions
    Includes all user-defined nests defined for the named transaction.
  • COBol
    Includes all COBOL format record elements associated with the named record. Note that ELEMENTS is the overriding option if a display of both ELEMENTS and COBOL is requested.
  • RECELems
    Includes all COBOL format record elements associated with the named record. RECELEMS displays only the record-element name; the names and version numbers of the elements that participate in the record are not displayed. Note that ELEMENTS is the overriding option if a display of both ELEMENTS and RECELEMS is requested.
  • SUBOrdinate ELements
    Includes subordinate elements. SUBORDINATE ELEMENTS is valid only with the RECORD ELEMENT format; to display or punch a COBOL format, specify the DISPLAY WITH COBOL option. To exclude subordinate elements from the display, specify WITH ELEMENTS PICTURE OVERRIDES WITHOUT SUBORDINATE ELEMENTS.
  • VIEws
    Includes subschema or IDD views.
  • SYNonyms
    Includes all synonyms associated with the record. Specify SYNONYMS to display programs, schemas, subschemas, and maps that are connected to the record synonym. For example, to display the programs with which the CUSTOMER record is associated, specify DISPLAY RECORD CUSTOMER WITH PROGRAMS SYNONYMS.
  • PICture OVErrides
    Includes element picture definitions for the record, including the start position of the element within the record and the length of the element, in bytes.
Usage
Restrictions on the RECORD statement
The following restrictions apply to the RECORD statement:
  • If the SET OPTIONS statement specifies SECURITY FOR IDD IS ON, the user must be assigned the proper authority to issue RECORD statements.
  • Records that participate in schemas
    require special consideration when they are deleted or replaced.
    Records that participate in schemas
    cannot be
    deleted
    by the DDDL compiler; documentation entries can, however, be submitted.
    Within records that participate in schemas, record elements can be
    replaced
    by one or more record elements; optionally, one or more record elements that follow the replaced record elements in the record structure can be
    removed
    . The following considerations apply:
    • To modify record elements, use the RECORD ELEMENT substatement, described later in this section. It is recommended that the LINE option be used to accurately position the record element.
    • The primary replacement record element must have the same RECORD ELEMENT NAME as the original record element; however, a different version number is valid.
    • After issuing the REPLACE command for a particular record element, the user can
      insert
      or
      remove
      record elements immediately following the replaced record element, subject to the length restrictions described below.
    • Record elements to be inserted into the record structure following the replacement record elements must be previously defined in the dictionary.
    • The record elements to be replaced cannot be defined as the
      schema control field
      (CALC-key, sorted set key, or index set key), nor can they contain a subordinate element defined as the schema control field.
    • The
      total length
      of the replacement record elements must equal the length of the element being replaced. The logical position of the elements following the replaced element cannot be altered; the overall record length cannot be changed. When the DDDL compiler detects a change in the replacement record length, it rejects the request; the compiler restores the original elements in the record, removes replacement elements, and displays an error message.
    • A
      filler field
      (RECORD ELEMENT IS 'FIL
      nnnn
      ') can be replaced by any element previously defined in the dictionary.
    • Elements defined as
      COBOL level-88 items
      (USAGE IS CONDITION-NAME) can be inserted, replaced, or removed from the record structure without restriction.
  • Records that participate in maps
    can be modified; the following considerations apply:
    • To modify record elements
      , use the RECORD ELEMENT substatement, described later in this section. It is recommended that the LINE option be used to accurately position the record element.
    • When a REPLACE RECORD ELEMENT command specifies that the length of the replacement elements is equal to the length of the original element, the DDDL compiler removes the original element from the record and inserts the new elements in its place. Recompilation of maps in which the record participates and programs that use the maps is not necessary.
    • When a record element is removed from or inserted into the record structure, or is replaced with a
      record element of unequal length
      , the DDDL compiler updates the record and flags the maps and programs associated with the record for recompilation.
    • Record elements and group record elements with subordinate record elements that are identified as
      map fields
      cannot be removed from or replaced in the record. The same restriction applies to record elements that are the object of the following statements that implicitly remove or replace record elements: REMOVE/REBUILD/REPLACE RECORD ELEMENTS, REMOVE ALL, and COBOL.
    • An
      occurrence count
      for a multiply-occurring record element cannot be decreased if it makes a field in a map obsolete. For example, a MODIFY RECORD statement followed by a RECORD ELEMENT substatement that specifies OCCURS 11 TIMES produces an error if the 12th occurrence of the field was mapped.
    • A
      record synonym
      that participates in a map cannot be excluded.
    • Modifications
      to the RECORD statement clauses listed in the following table may necessitate regeneration of all maps in which the record participates and, in some cases, recompilation of the programs that use those maps. To obtain a list of such programs, issue a DISPLAY MAP statement for each map in which the named record participates; the output lists the programs compiled against that map.
    • Elements defined as
      COBOL level-88 items
      (USAGE IS CONDITION-NAME) can be inserted, replaced, or removed from the record structure without restriction.
Regenerate and recompile requirements
Modified RECORD clause
Map regeneration required?
Program recompilation required?
BLANK WHEN ZERO
NO
NO
CODE TABLE
YES
NO
COMMENTS/DEFINITION
NO
NO
EDIT
NO
NO
EDIT TABLE
YES
NO
ELEMENT NAME SYNONYM
NO
NO
EXTERNAL PICTURE
YES
NO
INDEX KEY
NO
NO
INDEXED BY
NO
NO
JUSTIFY
NO
NO
NEW RECORD NAME/VERSION
NO
NO
OCCURS
YES
YES
OCCURS DEPENDING ON name
NO
NO
PICTURE
YES
YES
REMOVE RECORD ELEMENT
YES1
YES1
REPLACE RECORD ELEMENT
YES1
YES1
ADD RECORD ELEMENT
YES1
YES1
RECORD NAME
SYNONYM PREFIX/SUFFIX
NO
NO
REDEFINES
YES
YES
SIGN
YES
YES
SYNC/NOSYNC
NO
NO
USAGE
YES
YES
VALUE
NO
NO
1 Only necessary if displacements are affected
If you specify REPLACE
If you specify REPLACE, the DDDL compiler initializes to defaults and/or excludes the following clauses:
  • DESCRIPTION
  • USER REGISTERED FOR
  • PUBLIC ACCESS
  • STORAGE
  • FORMAT
  • OCCURRENCES
  • WITHIN FILE
  • COMMENTS/DEFINITIONS/OLQ HEADER/CULPRIT HEADER/
    comment-key
  • ATTRIBUTES
  • RECORD SYNONYMS (except as noted below)
  • RECORD ELEMENT
  • VIEW
  • PREFIX/SUFFIX
  • Related records, reports, transactions
  • LANGUAGE
The following relationships are not affected:
  • Primary record synonyms
  • Records to which the named record is related
  • Programs that have copied or access the named record
  • Map records associated with the named record
  • Record synonyms that are copied or accessed by programs or maps or that have not been built by the DDDL compiler
Record synonyms (sites using CA IDMS SQL)
If the language specified is SQL, no other record synonym associated with the record may have a language of SQL associated. The language of SQL is associated with record synonyms to be used (at sites with CA IDMS SQL) in SQL to access non-SQL databases.
Displaying records
If you display a record:
  • WITH ELEMENTS -- the names of record elements that are
    not
    subordinate to any other elements are displayed
  • WITH ELEMENTS ALSO WITH SUBORDINATE ELEMENTS -- the names of subordinate record elements are displayed
  • WITH ELEMENTS ALSO WITH PICTURE OVERRIDES -- the element definitions for the specified record are displayed, including: the start position of the element within the record and the length of the element, in bytes
The message RECORD CONTAINS CRITICAL ERRORS applies only to CA products and appears when you display any record, report, or transaction that contains a critical error (for example, a record or record element with a length of 0).
If WITHOUT PICTURE OVERRIDES is specified
If WITHOUT PICTURE OVERRIDES is requested, the displayed output includes the record elements, subordinate elements, element synonyms, and all information that can be specified only at the record-element or subordinate-record-element level rather than in the element definition (for example, SYNC, OCCURS, INDEXED BY, and INDEX KEY). The LINE IS, SUBORDINATE ELEMENT REDEFINES, and SUBORDINATE ELEMENT OCCURS specifications and picture-related information are excluded from the display.
This option is useful in an online environment for rebuilding a record, modifying portions of a record, or building a new record, as follows:
  • To rebuild a record
    , issue a DISPLAY request, specifying the WITHOUT PICTURE OVERRIDES, WITHOUT SYNONYMS, VERB IS MODIFY, and AS SYNTAX options. Insert a REMOVE ALL substatement immediately following the MODIFY RECORD statement. Resubmit the displayed definition to the DDDL compiler, which rebuilds the record as if it were performing an ADD operation (using the current element definitions to build the record-element structure). The displayed record definition can be replaced by specifying the VERB IS REPLACE parameter on the DISPLAY/PUNCH request.
  • To rebuild portions of a record
    , issue a DISPLAY request, specifying the WITHOUT PICTURE OVERRIDES, VERB IS MODIFY, and AS SYNTAX options. Specify the REPLACE option for each displayed record element to be changed. Resubmit the displayed definition to the DDDL compiler. The DDDL compiler uses the current definition of each element named in the record (for which REPLACE has been specified) to rebuild the record.
  • To build a new record using an existing element structure
    , issue a DISPLAY request, specifying the WITHOUT PICTURE OVERRIDES and AS SYNTAX options. Supply the new record name and/or version number, and resubmit the record definition to the DDDL compiler. The DDDL compiler uses the picture-related information and group-to-subordinate-element structure from the current definition of each element named in the record to build the new record.
If a subordinate record element is defined with both a REDEFINES and an OCCURS clause, the REDEFINES specification is supplied from the element and the OCCURS specification is supplied from the subordinate record element when the record is built or rebuilt.
Example 1
This example shows:
  1. Definition of two elements
  2. Definition of a group element
  3. Association of the group element with a record
  4. Display of the entire record
1) Defining elements
The following two ADD ELEMENT statements establish the elements CUSTOMER-NUMBER and CUSTOMER-NAME in the dictionary. Element names are used when the elements appear with the record having the primary record name. Element synonyms provide language-specific names.
add element name is
customer-number
version is 1 element synonym is customer_number for group synonym customer_group element synonym is custnum for group synonym custgrup element synonym is custno for group synonym custgp picture is 9(6) . add element name is
customer-name
version is 1 element synonym is customer_name for group synonym customer_group element synonym is custname for group synonym custgrup element synonym is custnm for group synonym custgp picture is x(30) .
2) Defining a group element
The following ADD ELEMENT statement establishes the
group
element CUSTOMER-GROUP. The SUBORDINATE ELEMENT clause incorporates the elements CUSTOMER-NAME and CUSTOMER-NUMBER. ELEMENT SYNONYM clauses are used to establish a connection between the ELEMENT definition and a RECORD definition.
add element name is
customer-group
version is 1 element synonym is customer_group for group synonym customer_record element synonym is custgrup for group synonym custrecd element synonym is custgp for group synonym custrc subordinate elements are
customer-number
version is 1
customer-name
version is 1 .
3) Associating the group element with a record
The following ADD RECORD statement adds the record CUSTOMER-RECORD to the dictionary and includes the group element CUSTOMER-GROUP.
The DDDL compiler compares the record synonyms with the group synonyms in the element definition. When a match is found, the element synonym associated with that group synonym is automatically copied into the record for that record synonym.
add record name is
customer-record
version is 1 record name synonym is customer_record version 1 record name synonym is custrecd version 1 record name synonym is custrc version 1. record element is
customer-group
.
4) Displaying the record
The following DISPLAY RECORD statement displays the CUSTOMER-RECORD structure defined in steps 1 through 3.
display record customer-record. *+ add *+ record name is customer-record version is 1 *+ date created is mm/dd/yy *+ prepared by mjj *+ record length is 36 *+ record name synonym is customer-record version 1 *+ record name synonym is customer_record version 1 *+ record name synonym is custrecd version 1 *+ record name synonym is custrc version 1 *+ . *+ record element is customer-group version 1 line is 000100 *+ level number is 02 *+ usage is display *+ element name synonym for record synonym customer_record version 1 is *+ customer_group *+ element name synonym for record synonym custrecd version 1 is custgrup *+ element name synonym for record synonym custrc version 1 is custgp *+ . *+ subordinate element is customer-number version 1 line is 000200 *+ level number is 03 *+ picture is 9(6) usage is display *+ element name synonym for record synonym customer_record version 1 is *+ customer_number *+ element name synonym for record synonym custrecd version 1 is custnum *+ element name synonym for record synonym custrc version 1 is custno *+ . *+ subordinate element is customer-name version 1 line is 000300 *+ level number is 03 *+ picture is x(30) usage is display *+ element name synonym for record synonym customer_record version 1 is *+ customer_name *+ element name synonym for record synonym custrecd version 1 is custname *+ element name synonym for record synonym custrc version 1 is custnm *+ .
Example 2
The following example illustrates the modification of a record that participates in a schema. It shows:
  1. The original record layout
  2. The DDDL statements that modify the record
  3. The final record layout
1) The original record layout
The CUSTOMER record has been previously defined in the dictionary. The length of CUST-ADDRESS is 40 bytes.
The COBOL layout and version numbers of the elements are for illustrative purposes only. Each of these elements must be defined in the dictionary using RECORD ELEMENT syntax.
Line
Num Record Element
100 05 cust-number ver 1 pic x(10). 200 05 cust-name ver 1 pic x(20). 300 05 cust-ssn ver 1 pic x(09). 400 05 cust-address ver 1. 500 10 cust-addr1 ver 1 pic x(20). 600 10 cust-addr2 ver 1. 700 15 cust-city ver 1 pic x(15). 800 15 cust-zip-code ver 1 pic x(05). 900 15 cust-zipcode ver 1 redefines cust-zip-code pic 9(05). 1000 05 filler pic x(05). 1100 05 cust-credit ver 1 pic x(03). 1200 88 cust-credit-exec ver 1 value 'aaa'. 1300 88 cust-credit-good ver 1 value ' '. 1400 88 cust-credit-poor ver 1 value 'xxx'. 1500 05 cust-sales-info ver 1. 1600 10 cust-sales-qtr ver 1 occurs 4 indexed by cuix. 1700 10 cust-num-sales ver 1 pic 9(05) comp-3. 1800 10 cust-amt-sales ver 1 pic 9(07) comp-3. 1900 05 filler pic x(03).
The user defines four new elements in the dictionary, using the DDDL compiler. The length of CUST-ADDRESS VERSION 2 is 44 bytes:
The COBOL layout and version numbers of the elements are for illustrative purposes only. Each of these elements must be defined in the dictionary using RECORD ELEMENT syntax.
Record Element
05 cust-nr-numeric ver 1 pic 9(10). 05 cust-ssn ver 2. 10 cust-ssn-3 ver 1 pic x(03). 10 cust-ssn-2 ver 1 pic x(02). 10 cust-ssn-4 ver 1 pic x(04). 88 cust-credit-unkn ver 1 value'unk'. 05 cust-address ver 2. 10 cust-street ver 1 pic x(20). 10 cust-addr2 ver 2. 15 cust-city ver 2 pic x(13). 15 cust-state ver 1 pic x(02). 15 cust-zip-code ver 2. 20 filler pic x(04). 20 cust-zip-5 ver 1 pic x(05). 15 cust-zipcode ver 2 redefines cust-zip-code ver 2 pic 9(09).
2) The DDDL statements that modify the record
The user issues a MODIFY RECORD command and RECORD ELEMENT substatements to the DDDL compiler to place the newly defined elements into the CUSTOMER record.
CUST-NUMBER is replaced by the new element definition CUST-NR-NUMERIC.
replace record customer. replace record element cust-number version 1 line 100 . record element cust-nr-numeric version 1 line 110 redefines cust-number .
CUST-SSN and CUST-ADDRESS are replaced using a new element with the same name but a different version number. Because CUST-ADDRESS VERSION 2 is four bytes longer than VERSION 1, a new one-byte filler field is inserted following CUST-ADDRESS, and the original five-byte filler field is removed. A new COBOL level-88 item is inserted.
replace record element cust-ssn version 2 line 300 . replace record element cust-address version 2 line 400 . record element 'fil 0001' line 910 . remove record element 'fil 0005' line 1000 . record element cust-credit-unkn line 1110 .
3) The final record layout
The record elements associated with the newly modified CUSTOMER record are shown below. The schema definition is automatically adjusted to reflect the changes.
Line
Num Record Element
100 05 cust-number ver 1 pic x(10). 200 05 cust-nr-numeric ver 1 redefines cust-number pic 9(10). 300 05 cust-name ver 1 pic x(20). 400 05 cust-ssn ver 2. 500 10 cust-ssn-3 ver 1 pic x(03). 600 10 cust-ssn-2 ver 1 pic x(02). 700 10 cust-ssn-4 ver 1 pic x(04). 800 05 cust-address ver 2. 900 10 cust-street ver 1 pic x(20). 1000 10 cust-addr2 ver 2. 1100 15 cust-city ver 2 pic x(13). 1200 15 cust-state ver 1 pic x(02). 1300 15 cust-zip-code ver 2. 1400 20 filler pic x(04). 1500 20 cust-zip-5 ver 1 pic x(05). 1600 15 cust-zipcode ver 2 redefines cust-zip-code ver 2 pic 9(09). 1700 05 filler pic x(01). 1800 05 cust-credit ver 1 pic x(03). 1900 88 cust-credit-unkn ver 1 value 'unk'. 2000 88 cust-credit-exec ver 1 value 'aaa'. 2100 88 cust-credit-good ver 1 value ' '. 2200 88 cust-credit-poor ver 1 value 'xxx'. 2300 05 cust-sales-info ver 1. 2400 10 cust-sales-qtr ver 1 occurs 4 indexed by cuix. 2500 10 cust-num-sales ver 1 pic 9(05) comp-3. 2600 10 cust-amt-sales ver 1 pic 9(07) comp-3. 2700 05 filler pic x(03).
Syntax and parameter descriptions for the RECORD ELEMENT, COBOL, REMOVE ALL, and VIEW substatements, and the DISPLAY/PUNCH RECORD SYNONYM statement follow.
RECORD ELEMENT Substatement
RECORD ELEMENT substatements associate existing elements with records and update existing record-element structures. To include an element within a record-element structure, specify a RECORD statement followed by the keywords RECORD ELEMENT. After the RECORD ELEMENT identification, enter optional clauses that define record-specific characteristics for the element.
Syntax
RECORD ELEMENT substatement
►►─┬───────────┬─ RECord ELEment is
element-name
─────────────────────────────►─ ├─ REMove ──┤ └─ REPlace ─┘ ─►─┬───────────────────────────────────┬──┬───────────────────────┬───────────►─ └─ Version is ─┬─
version-number
─┬─┘ └─ LINe is
line-number
─┘ ├─ HIGhest ────────┤ └─ LOWest ─────────┘ ─►── SUBordinate ELement is
element-name
─┬────────────────────────────────┬──►─ └ Version is ─┬
version-number
─┬┘ ├ HIGhest ────────┤ └ LOWest ─────────┘ ─►─┬───────────────────────┬──────────────────────────────────────────────────► └─ LINe is
line-number
─┘ ►─┬──────────────────────────────────────────────────────────────────────────►─ └─ ELement name SYNonym is
element-synonym
──────────────────────────────── ─►─┬────────────────────────────────────────────────────────────────────────┬─► └ FOR RECord synonym
record-synonym
┬─────────────────────────────────┬──┘ └ Version is ─┬─
version-number
─┬┘ ├─ HIGhest ────────┤ └─ LOWest ─────────┘ ►─┬────────────────────────────┬─────────────────────────────────────────────► └─ PICture is ─┬─
picture
─┬─┘ ├─ NULL ────┤ └─ BUILT ───┘ ►─┬───────────────────────────────────────┬──────────────────────────────────► └─ USAge is ─┬─ DISplay ──────────────┬─┘ ├─┬─ COMPUTATIONAL ───┬──┤ │ ├─ COMP ────────────┤ │ │ ├─ COMPUTATIONAL-4 ─┤ │ │ ├─ COMP-4 ──────────┤ │ │ └─ BINary ──────────┘ │ ├─┬─ COMPUTATIONAL-1 ─┬──┤ │ ├─ COMP-1 ──────────┤ │ │ └─ SHOrt-point ─────┘ │ ├─┬─ COMPUTATIONAL-2 ─┬──┤ │ ├─ COMP-2 ──────────┤ │ │ └─ LONg-point ──────┘ │ ├─┬─ COMPUTATIONAL-3 ─┬──┤ │ ├─ COMP-3 ──────────┤ │ │ └─ PACked ──────────┘ │ ├─ POInter ──────────────┤ ├─ BIT ──────────────────┤ └┬ CONdition-name ┬──────┘ └─ SQLBINARY ────┘ ►─┬────────────────────────────────┬─────────────────────────────────────────► └─ REDefines ─┬─
element-name
─┬─┘ ├─ * ────────────┤ └─ NULl ─────────┘ ►─┬──────────────────────────────────────────────────────────────────────────►─ └─┬─ INClude ◄ ─┬─ VALues ─┬─ is ──┬─┬───────┬───────────────────────────── └─ EXClude ───┘ └─ are ─┘ └─ ALL ─┘ ─►─────────────────────────────────────────────────────────────────────────┬──► ┌───────────────────────────────────────────────────────────┐ │ ─┬───┬▼─┬
initial-value
──┬┬────────────────────────────────────┬─┴┬───┬─┘ └ ( ┘ └
condition-value
┘└─ THRu ─┬───────┬─
condition-value
─┘ └ ) ┘ └─ ALL ─┘ ►─┬───────────────────────┬──────────────────────────────────────────────────► └─ EXClude ALL VALues ──┘ ►─┬──────────────────────────────────────────────────────────────────────────►─ └─ OCCurs ───────────────────────────────────────────────────────────────── ─►─────────────────────────────────────────────────────────────────────┬──────► ─┬─
occurrence-count
times ────────────────────────────────────────┬─┘ ├─
occurrence-count
times DEPending on
control-element-name
──────┤ ├─ 0 TO
occurrence-count
times DEPending on
control-element-name
─┤ └─ NULl ──────────────────────────────────────────────────────────┘ ►─┬─────────────────────────────────────────────────────────────────────┬────► └─ INDexed by ─┬─
index-element-name
───────────────────────────────┬─┘ │ ┌──────────────────────┐ │ ├─ ( ─▼─
index-element-name
─┴─ ) ───────────────────┤ ├─ NULl ─────────────────────────────────────────────┤ └─ FOR RECord synonym
record-synonym-specification
──┘ (expanded
record-synonym-specification
syntax follows this syntax diagram) ►─┬───────────────────────────────────────────────────────────────────────┬──► └─ INDex KEY is ─┬─
index-element-name
─┬─ ASCending ──┬──────────────┬─┘ │ └─ DEScending ─┘ │ │ ┌───────────────────────────────────────┐ │ ├┬───┬─▼─
index-element-name
─┬─ ASCending ──┬─┴┬───┬┤ │└─(─┘ └─ DEScending ─┘ └─)─┘│ └─ NULl ─────────────────────────────────────────────┘ ►─┬───────────┬──────────────────────────────────────────────────────────────► ├─ SYNC ────┤ └─ NO SYNC ─┘ ►─┬────────────────────────┬─────────────────────────────────────────────────► └─ JUStify is ─┬─ ON ──┬─┘ └─ OFF ─┘ ►─┬────────────────────────────────┬─────────────────────────────────────────► └─ BLAnk when ZERo is ─┬─ ON ──┬─┘ └─ OFF ─┘ ►─┬───────────────────────────────────────────────────────┬──────────────────► └─ SIGn is ─┬─ NULl ──────────────────────────────────┬─┘ └─┬─ LEAding ──┬─┬──────────────────────┬─┘ └─ TRAiling ─┘ └─ SEParate character ─┘ ┌─────────────────────────────────────────────────────────────────┐ ►─▼─┬─────────────────────────────────────────────────────────────┬─┴────────► │ ┌────────────────────┐ │ └─ EDIt ─┬─ COMments ───────┬──▼─
edit-instruction
─┴─ QUIT ──┘ ├─ DEFinitions ────┤ ├─ OLQ header ─────┤ ├─ CULprit header ─┤ └─
comment-key
────┘ ┌────────────────────────────────────────────────────┐ ►─▼─┬────────────────────────────────────────────────┬─┴─────────────────────► └─┬─ COMments ───────┬─ is ─┬─ NULl ───────────┬─┘ ├─ DEFinitions ────┤ └─
comment-text
───┘ ├─ OLQ header ─────┤ ├─ CULprit header ─┤ └─
comment-key
────┘ ┌────────────────────────────────────────────────────────────────────────── ►─▼─┬────────────────────────────────────────────────────────────────────────►─ └─┬─ INClude ◄ ─┬─ EDIT ─┬─ VALid ◄ ─┬─ TABle is ──────────────────────── └─ EXClude ───┘ └─ INValid ─┘ ───────────────────────────────────────────┐ ─►─────────────────────────────────────────┬─┴────────────────────────────────► ─┬─ LISt ──────────────────────────────┬─┘ │ ┌─────────────────────────┐ │ ├─ ( ─▼─
value
┬──────────────┬─┴─ ) ─┤ │ └─ THRu
value
─┘ │ └─ NULl ──────────────────────────────┘ ┌────────────────────────────────────────────────────────────────────────┐ ►─▼─┬─────────────────────────────────────────────────────────────────────┬┴─► └┬ INClude ◄ ┬ CODe TABle is ┬ LISt ────────────────────────────────┬─┘ └ EXClude ──┘ │ ┌─────────────────────────────┐ │ ├ ( ─▼─
encode-value
decode-value
┴ )─┤ └ NULl ────────────────────────────────┘ ►─┬─────────────────────────────────────┬────────────────────────────────────►◄ └─ EXTernal PICture is ─┬─
picture
─┬─┘ └─ NULl ────┘
Expansion of
record-synonym-specification
►►─┬──────────────────────────────────────────────────────────────────────────►─ └─
record-synonym-name
─┬──────────────────────────────────┬─────────────── └─ Version is ─┬
version-number
┬──┘ ├ HIGhest ───────┤ └ LOWest ────────┘ ─►───────────────────────────────────────────┬────────────────────────────────►◄ ─── is ─┬─
index-element-name
───────────┬─┘ │ ┌─────────────────────┐ │ ├─ ( ─▼─
index-element-name
┴─ )─┤ └─ NULl ─────────────────────────┘
Parameters
  • RECord ELEment is
    element-name
    Specifies the element that is the object of the RECORD ELEMENT substatement.
    Element-name
    must be the primary name of an existing element; the named element must be the highest level element within a record (usually an 02 level), or a level-88 item. If the named element is not in the record-element structure, the DDDL compiler adds the existing element definition and any record-specific characteristics to the end of the record-element structure. If the optional LINE parameter (described below) is not specified, the element definition is placed at the end of the record-element structure. If the named element already participates in the record-element structure, the DDDL compiler modifies the record-element definition based on the optional clauses specified.
  • LINe is
    line-n
    Qualifies nonunique record-element names or specifies where the DDDL compiler is to insert a new element definition in the record-element structure.
    Line-n
    must be an integer in the range 1 through 999,999.
    This parameter must be specified unless the requested record element is the first nonunique element within the structure. Following compilation of the RECORD statement, the DDDL compiler assigns sequence numbers to all record elements; the default sequence number specified in the SET OPTIONS statement SEQUENCE clause is the starting and increment value. The assigned numbers appear on record reports and in DISPLAY/PUNCH output. If the LINE parameter in a MODIFY RECORD RECORD ELEMENT statement references the line number of an existing record element, but that element has a different name than the requested record element, the DDDL compiler issues an error message, unless the REPLACE parameter has been specified.
    If you do
    not
    specify a LINE clause in a RECORD ELEMENT substatement (one that doesn't use REPLACE or REMOVE) the compiler adds the record element to the end of the record definition.
  • REMove/REPlace
    Deletes or replaces the specified record element and its subordinate elements. If REMOVE or REPLACE is specified,
    element-name
    must match the name of an element in the named record-element structure.
  • SUBordinate ELement is
    element-name
    Identifies an existing subordinate element that is to be modified for use within the named record-element structure. All clauses between this substatement and another SUBORDINATE ELEMENT or RECORD ELEMENT substatement apply to the named subordinate element or level-88 item.
    The SUBORDINATE ELEMENT specification is used to change record-element characteristics such as picture and usage; it is
    not
    used to create group-element/subordinate-element structures. These structures must be defined by means of the ELEMENT entity statement (described under ELEMENT, earlier in this section).
  • ELement name SYNonym is
    element-synonym
    Establishes a synonym (alternative name) for the element when it participates in the named record-element structure.
    Element-synonym
    is the 1- to 32-character synonym name. If this clause appears following a SUBORDINATE ELEMENT substatement, the synonym is associated with the subordinate element.
    This clause can be coded once for each synonym to be associated with the named record. Any prefix or suffix defined for the record synonym with which the element synonym is associated will be appended to the element-synonym name.
  • FOR RECord synonym
    record-synonym-specification
    Associates the element (or subordinate element) synonym with the designated record synonym.
    If the FOR RECORD SYNONYM clause is not specified, the named record element (or subordinate element) is associated with the primary record synonym only.
  • PICture is
    Specifies a record-specific PICTURE clause for the record element or subordinate element.
  • picture
    Creates a record-specific PICTURE clause for the named record element. If the named record element is an elementary element,
    picture
    becomes the record-specific picture for the element. If the named record element is a group element,
    picture
    becomes the record-specific picture for the group element; the DDDL compiler removes from the record any subordinate elements defined for the group.
    The maximum length of a record element (including its usage) is 32,767 characters.
    Picture
    must be a 1- through 30-character value that describes alphanumeric, alphabetic, numeric, or numeric-edited data, as shown in the table under
    Usage
    .
  • NULL
    Removes a record-specific PICTURE clause from the named record element.
  • BUILT
    Creates an alphanumeric display PICTURE clause for the requested group record element. The DDDL compiler deletes the subordinate elements from the group description and uses the combined lengths of all subordinate elements in the group to form the group picture.
  • USAge is
    Specifies a record-specific USAGE clause for the named record element.
  • DISplay
    Alphabetic, alphanumeric, zoned decimal, edited, or display floating point
  • COMPUTATIONAL
    Binary; COMP, COMPUTATIONAL-4, COMP-4, and BINary are synonyms for COMPUTATIONAL.
  • COMPUTATIONAL-1
    Short-precision floating point; COMP-1 and SHOrt-point are synonyms for COMPUTATIONAL-1.
  • COMPUTATIONAL-2
    Long-precision floating point; COMP-2 and LONG-point are synonyms for COMPUTATIONAL-2.
  • COMPUTATIONAL-3
    Packed decimal; COMP-3 and PACked are synonyms for COMPUTATIONAL-3.
  • POInter
    Fullword address constant
  • BIT
    Bit string definition
  • CONdition-name
    COBOL level-88 item; the level number is generated by the DDDL compiler.
  • SQLBINARY
    An SQL BINARY data type; Identifies a fixed-length array of bytes and should be defined with PIC X(n) where n is in the range 1 through 32,760. The maximum length of an element with a data type of SQL BINARY is limited by the page size and the total length of other elements in the record.
  • REDefines
    Specifies a record-specific REDEFINES clause for the named record element. A redefined element (
    element-name
    or the element referenced by
    *
    ) cannot include an OCCURS clause; the element can, however, be subordinate to an element with an OCCURS clause.
  • element-name
    Identifies the element being redefined. The specified element must be at the same level as the element that is the object of the RECORD ELEMENT substatement and must immediately precede that element in the record-element structure.
  • *
    Instructs the DDDL compiler to automatically redefine the previous element at the same level in the record-element structure. The user need not specify the element name.
  • NULl
    Removes a previously established REDEFINES clause.
  • VALue is/are ALL
    initial-value
    /
    condition-value
    THRu ALL
    condition-value
    Specifies a record-specific VALUE clause for the named record element.
    Initial-value/condition-value
    specifies a value, range of values, or a list of values assigned to a COBOL level-88 condition name. A list of values must be enclosed in parentheses. Each value in the list must be separated from the next by a space or a comma. The value must be a figurative constant, a numeric literal, or an alphanumeric literal enclosed in quotation marks; alphanumeric literals cannot exceed 32 characters.
    The optional THRU parameter is valid only with COBOL condition names (level-88 items). To specify a new value for a new or existing record element, first issue an EXCLUDE ALL VALUES clause. Note that if the SET OPTIONS statement specifies DECIMAL-POINT IS COMMA and the VALUE clause specifies a numeric literal, periods (.) are interpreted as insertion characters and commas (,) are interpreted as decimal points.
  • EXClude ALL VALues
    Removes all VALUE clauses associated with the named record element. This clause is required to remove existing values.
  • OCCurs
    Specifies a record-specific OCCURS clause for the named record element.
  • occurrence-count
    times
    Specifies the number of times the element can occur within the record.
    Occurrence-count
    must be an integer in the range 0 through 32,767.
  • occurrence-count
    times/0 TO
    occurrence-count
    times DEPending on
    control-element-name
    Defines a control element within the record, that determines the actual number of times the element will occur.
    Occurrence-count
    must be an integer in the range 1 through 32,767.
    Control-element-name
    specifies a previously defined field in the record; this field must be a halfword or fullword binary item if the record is to be used in a schema or by CA ADS.
  • NULL
    Removes an existing OCCURS clause.
  • INDexed by
    Specifies one or more INDEXED BY clauses for the named multiply-occurring record element or record-element synonym, or removes an existing INDEXED BY clause.
    This clause applies only to records used in COBOL programs and can be specified once for each record element, subordinate element, and record synonym associated with the element. Each specified index is prefixed or suffixed for each record synonym associated with the record element.
    Within one INDEXED BY clause, the user can specify either a multiply-occurring record element or a record-element synonym (the clause cannot contain both elements and synonyms).
  • index-element-name
    Specifies a 1- through 32-character index name that cannot duplicate an element or element-synonym name in the record.
  • NULl
    Removes an existing INDEXED BY clause.
  • FOR RECord synonym
    record-synonym
    is
    index-element-name
    /NULl
    Specifies an INDEXED BY name for a record synonym associated with the record element.
    Index-element-name
    is a 1- through 32-character index name that must not duplicate the name of an existing element or element synonym in the record. Multiple index names must be enclosed in parentheses and separated by blanks. The COBOL precompiler copies the specified index names into the program's DATA DIVISION as part of the COPY IDMS function.
    NULl removes an existing INDEXED BY clause.
  • INDex KEY is
    Specifies one or more record-specified index keys for a multiply-occurring group record element or a subordinate record element. The INDEX KEY clause applies only to records used in COBOL programs. Only one INDEX KEY clause can be specified for each record element or subordinate element.
  • index-element-name
    Identifies an elementary element that is subordinate to the associated element.
    Index-element-name
    must be the primary name of the subordinate element; it cannot be a synonym. The specified element name is appended with a prefix or suffix assigned to the record synonym associated with the element.
  • ASCending/DEScending
    Specifies the order of the subordinate elements within the multiply-occurring element.
  • NULl
    Removes an existing INDEX KEY clause.
  • SYNC/NO SYNC
    Determines whether boundary alignment is to be defined for the named record element. The correct alignment is determined by the USAGE specification. If the element's usage is COMP or COMP-4, the DDDL compiler issues a warning message when the element is not on the proper boundary alignment. This clause is documentation only, unless the COBOL precompiler is used to copy the record; in this case, the specified boundary alignment will be applied by the COBOL precompiler. If the record element is copied into a schema, it causes a critical schema error.
  • JUStify is
    Supplies a justification specification for the named record element. The JUSTIFY clause applies only to records used in COBOL programs.
  • ON
    Specifies that a COBOL JUSTIFIED clause is to be generated.
  • OFF
    Specifies that a COBOL JUSTIFIED clause is
    not
    to be generated.
  • BLAnk when ZERo is
    Supplies a BLANK WHEN ZERO specification for the named record element.
  • ON
    Specifies that blanks are automatically placed in the element when it contains all zeroes.
  • OFF
    Specifies that the element's value will not be changed when it contains all zeroes.
  • SIGn is
    Specifies whether the sign is to be removed from a numeric field or whether it is to appear in the leading or trailing position.
  • NULl
    Removes existing sign specifications (for signed DISPLAY numeric fields only).
  • LEAding/TRAiling
    Places the sign in the leading or trailing position. If SEPARATE CHARACTER is specified, the sign will appear as a separate byte.
  • EDIt VALid/INValid TABle is
    Specifies whether edit table values are to be listed, inserted, or removed (for DC/UCF tables only).
  • LISt
    Edit table values in the dictionary are listed on the Integrated Data Dictionary Activity List or in the online IDD work file.
  • value
    THRu
    value
    Inserts (INCLUDE) or removes (EXCLUDE) single values or ranges of values in the edit table. Each value can have a maximum size of 34 characters. The specified values must be enclosed in parentheses; for example:
    ('A' 'C' 'F' 'H' 'R' THRU 'Z')
  • NULl
    All values are removed from the table.
  • VALid/INValid
    Specifies whether the edit table contains a list of valid or invalid values; the default is VALID.
  • CODe TABle is
    Specifies whether code table values are to be listed, inserted, or removed (for DC/UCF tables only). For the rules for defining the values for edit and code tables, refer to the
    CA IDMS Reference section
    .
  • LISt
    Specifies that code table values that are in the dictionary are to be listed in pairs. The first value is the encoded value; the second value is the decoded value.
  • encode-value
    decode-value
    Specifies that pairs of values are inserted in the table. The first or
    encoded
    value can have a maximum size of 34 characters; the second or
    decoded
    value can have a maximum of 64 characters. Null values ('') and the keywords NOT FOUND are also valid. The specified values must be enclosed in parentheses.
  • NULl
    Specifies that all values are removed from the table.
  • EXTernal PICture is
    picture
    /NULl
    Defines the display format for record-element data (
    picture
    ) or removes an existing external picture specification (NULL). The picture is available to all map fields that use the record element. For the rules for defining external pictures, refer to the
    CA IDMS Reference section
    .
Usage
RECORD ELEMENT considerations
The following considerations apply to the RECORD ELEMENT substatement:
  • A record element can have a maximum length of 32,767 characters.
  • Any number of record elements can be associated with one record.
  • Clauses in a RECORD ELEMENT substatement request the DDDL compiler to change the
    record-element
    structure; the element definition in the dictionary remains unchanged.
  • When MODIFY RECORD is specified and the named element exists, the DDDL compiler modifies only those portions of the record element definition that are referenced by RECORD ELEMENT substatement clauses.
  • When the requested record element is not in the record, the DDDL compiler adds the definition to the end of the record.
  • When a RECORD ELEMENT substatement names a group element, the DDDL compiler automatically copies all of the group's subordinate elements into the definition.
  • The RECORD ELEMENT substatement does
    not
    build group-to-subordinate-element relationships. These relationships must be established using ELEMENT entity statements (see ELEMENT, earlier in this section.
  • RECORD ELEMENT statements are used to define record elements as tables that are used by the DC/UCF mapping facility for automatic editing and error handling. Tables defined by means of the RECORD ELEMENT substatement are called
    built-in tables
    .
    The TABLE statement (see TABLE, later in this section) is used to define stand-alone tables. For a complete description of built-in and stand-alone tables, refer to the
    CA IDMS Reference section
    .
Adding a filler field to a record-element structure
To add a filler field to a record-element structure, specify RECORD ELEMENT IS 'FIL
nnnn
'.
Nnnn
is a 4-digit value that represents the number of characters of filler; the specified value must be separated from the keyword FIL by one blank and must contain leading zeros, if appropriate. For example, to generate the filler described as FILLER PIC X(7), specify RECORD ELEMENT 'FIL 0007'.
If you specify REPLACE
The following considerations apply to the REPLACE option:
  • If REPLACE RECORD ELEMENT is specified with no optional clauses, the DDDL compiler removes and rebuilds the definition of the named record element from the current ELEMENT definition. Any record-specific modifications that have been made to the named element must be respecified; record-specific modifications for each subordinate element in a group must also be respecified.
  • A record element that is replaced will be removed from any views in which it participates. The replacement record element will not automatically be included in any views.
  • If REPLACE is specified with a line number, the DDDL compiler replaces the contents of the specified line number, whether or not the record element at that line has the same name as the element named in the REPLACE statement.
    For information about using the REPLACE command to modify map-owned or schema-owned
    records
    , see the previous discussion under RECORD Statement.
SUBORDINATE ELEMENT considerations
The following considerations apply to the SUBORDINATE ELEMENT clause:
  • If no RECORD ELEMENT substatement has been specified, the search for the SUBORDINATE ELEMENT starts at the beginning of the record.
  • A SUBORDINATE ELEMENT substatement cannot reference an element at the highest level in the record. Use the RECORD ELEMENT substatement to reference the highest level.
  • Only one subordinate element can be referenced in each SUBORDINATE ELEMENT substatement.
  • Multiple SUBORDINATE ELEMENT substatements must be specified in the order that the record elements appear within the group or within the record if no RECORD ELEMENT substatement has been specified.
  • Each RECORD ELEMENT substatement that references a group element can be followed by one SUBORDINATE ELEMENT substatement for each subordinate element within the named group, and one or more of the optional clauses described below.
Specifying a
picture
variable
Picture
must be a 1- through 30-character value that describes the types of data shown in the following table.
Category
Character
Description
Alphanumeric data
X
Represents one alphanumeric character. If USAGE IS BIT, X represents one bit; the USAGE clause is described in the parameters list.
(n)
An integer in parentheses after an X
Represents
n
repetitions of the alphanumeric character; for example, X(4) is equivalent to XXXX.
Alphabetic data
A
Represents one alphabetic character (A-Z).
(n)
An integer in parentheses after an A
Represents
n
repetitions of the alphabetic character
Numeric data
9
Represents one numeric character.
(n)
An integer in parentheses after a 9
Represents
n
repetitions of the numeric character.
Numeric elements with a usage clause of packed or zoned decimal cannot exceed a maximum length of 31 digits.
V
Represents an assumed decimal point. No more than one V can appear in an element picture. If the V is omitted and the P option (described below) is not used, the assumed decimal point is after the rightmost 9.
P
Represents an assumed zero. Any number of Ps can appear in the leftmost or the rightmost positions of an element picture. An assumed decimal point is automatically placed before the first P or after the last P. The character P does not occupy a storage position (for example, PP9999 has a data length of 4).
S
Identifies the number as positive or negative. When used, the S must be the first character in the element picture. When the S is omitted, values for the element description are assumed to be positive.
Numeric- edited data
(Includes the numeric data characters described above, along with the editing characters shown at the right)
Z
+
,
B
CR
-
0
DB
*
$
.
Represent edit symbols used in reporting data; quotation marks are not required. Refer to the appropriate programming language manual for the individual interpretations of these symbols.
If the SET OPTIONS statement specifies DECIMAL-POINT IS COMMA, a period (.) is interpreted as an insertion character and a comma (,) is interpreted as a decimal point.
Examples
The following example shows the creation of the record PARTS-RECORD using the RECORD ELEMENT substatement. The statement:
  • Defines the record PARTS-RECORD with a language of COBOL, an alternative format of DISPLAY, and an occurrence count of 20,000
  • Uses RECORD NAME SYNONYM to define the record synonym ST3PARTS for use with Assembler, and relate the synonym to the file synonym STK3FIL
  • Uses RECORD ELEMENT substatements to add:
    • Two elementary elements -- PARTNUMBER and DESIGN-DATE
    • Two group elements -- INVENTORY-DATA and INVENTORY-DATE
add record parts-record record storage is database language is cobol format is display occurrences are 20000 record name synonym is st3parts for file synonym stk3fil language is assembler. record element partnumber. record element design-date. record element inventory-data. record element inventory-date.
The following MODIFY statement:
  • Changes the record storage and occurrence specifications
  • Inserts a new element, HISTORY, that redefines INVENTORY-DATA
  • Identifies synonyms for the various record elements and their subordinate elements
modify record parts-record record storage is file occurrences are 80000. record element history line 810 redefines inventory-data element name synonym hstry for record st3parts. subordinate element discontinue-date element name synonym dscdt for record st3parts. subordinate element discontinue-month element name synonym dscmo for record st3parts. subordinate element discontinue-day element name synonym dscdy for record st3parts. subordinate element discontinue-year element name synonym dscyr for record st3parts. subordinate element lower-limit element name synonym lowlt for record st3parts. subordinate element quantity-on-hand element name synonym qtyhld for record st3parts. record element partnumber element name synonym partno for record st3parts. record element design-date element name synonym dsndt for record st3parts. record element inventory-data element name synonym invdata for record st3parts. subordinate element in-process element name synonym nrproc for record st3parts. subordinate element quantity1 element name synonym quone for record st3parts. subordinate element quantity2 element name synonym qutwo for record st3parts. subordinate element quantity3 element name synonym quthree for record st3parts.
COBOL Substatement
The COBOL substatement creates a record-element structure using an approximation of standard COBOL syntax. Elements named in COBOL substatements need not exist in the dictionary.
Syntax
COBOL element substatement
►►───
level-number
element-name
─────────────────────────────────────────────► ►─┬────────────────────────────────┬─────────────────────────────────────────► └─ REDefines
base-element-name
──┘ ►─┬───────────────────────┬──────────────────────────────────────────────────► └─ PICture is
picture
──┘ ┌────────────────────────────────────────────────────────────────────────── ►─▼─┬────────────────────────────────────────────────────────────────────────►─ └─┬─ VALue is ───┬─┬───────┬───────────────────────────────────────────── └─ VALues are ─┘ └─ ALL ─┘ ─────────────────────────────────────────────────────────────────────────┐ ─►───────────────────────────────────────────────────────────────────────┬─┴──► ─┬─────┬┬
initial-value
──────────────────────────────────────┬┬─────┬─┘ └─ ( ─┘└
condition-value
─┬────────────────────────────────┬─┘└─ ) ─┘ └ THRu ─┬─────┬
condition-value
─┘ └ ALL ┘ ►─┬───────────────────────────────────────┬──────────────────────────────────► └─ USAge is ─┬─ DISplay ◄ ────────────┬─┘ ├─┬─ COMPUTATIONAL ───┬──┤ │ ├─ COMP ────────────┤ │ │ ├─ COMPUTATIONAL-4 ─┤ │ │ ├─ COMP-4 ──────────┤ │ │ └─ BINary ──────────┘ │ ├─┬─ COMPUTATIONAL-1 ─┬──┤ │ ├─ COMP-1 ──────────┤ │ │ └─ SHOrt-point ─────┘ │ ├─┬─ COMPUTATIONAL-2 ─┬──┤ │ ├─ COMP-2 ──────────┤ │ │ └─ LONg-point ──────┘ │ ├─┬─ COMPUTATIONAL-3 ─┬──┤ │ ├─ COMP-3 ──────────┤ │ │ └─ PACked ──────────┘ │ ├─ POInter ──────────────┤ ├─ BIT ──────────────────┤ ├─ CONdition-name ───────┤ └─ SQLBINary ────────────┘ ┌────────────────────────────────────────────────────────────────────────── ►─▼─┬────────────────────────────────────────────────────────────────────────►─ └─ ELement name SYNonym is
element-synonym
────────────────────────────── ──────────────────────────────────────────────────────────────────────────┐ ─►─────────────────────────────────────────────────────────────────────────┬┴─► ─┬─────────────────────────────────────────────────────────────────────┬─┘ └ FOR RECord synonym
record-synonym
─┬───────────────────────────────┬┘ └ Version is ┬
version-number
─┬┘ ├ HIGhest ────────┤ └ LOWest ─────────┘ ►─┬─────────────────────────┬────────────────────────────────────────────────► └─┬─ JUStify ───┬─ right ─┘ └─ JUStified ─┘ ►─┬───────────────────┬──────────────────────────────────────────────────────► └─ BLAnk when ZERo ─┘ ►─┬───────────────────────────────────────────────────┬──────────────────────► └─ SIGn is ─┬─ LEAding ──┬─┬──────────────────────┬─┘ └─ TRAiling ─┘ └─ SEParate character ─┘ ►─┬─────────────────────────────┬────────────────────────────────────────────► └─ SYNChronized ──┬─ LEFt ──┬─┘ └─ RIGht ─┘ ►─┬──────────────────────────────────────────────────────────────────────────►─ └─ OCCurs ───────────────────────────────────────────────────────────────── ─►───────────────────────────────────────────────────────────────────┬────────► ─┬─
occurrence-count
times ────────────────────────────────────────┤ ├─
occurrence-count
times DEPending on
control-element-name
──────┤ └─ 0 TO
occurrence-count
times DEPending on
control-element-name
─┘ ►─┬─────────────────────────────────────────────────────────────────────┬────► └─ INDexed by ─┬─
index-element-name
───────────────────────────────┬─┘ │ ┌──────────────────────┐ │ ├─ ( ─▼─
index-element-name
─┴─ ) ───────────────────┤ └─ FOR RECord synonym
record-synonym-specification
──┘ (expanded
record-synonym-specification
syntax follows this syntax diagram) ►─┬──────────────────────────────────────────────────────────────────────────►─ └─ INDex KEY is ─┬─
index-element-name
─┬─ ASCending ──┬─────────────┬───── │ └─ DEScending ─┘ │ │ ┌───────────────────────────────────────┐ │ └┬───┐▼─
index-element-name
─┬─ ASCending ──┬─┴┬───┬┘ └─(─┘ └─ DEScending ─┘ └─)─┘ ─►─┬────────────────────────────────────────────────────────────────┬─────────► └─┬─ ASCending ──┬─ key is ─┬─
index-element-name
─────────────┬─┘ └─ DEScending ─┘ │ ┌──────────────────────┐ │ └─ ( ─▼─
index-element-name
─┴─ ) ─┘ ►─┬───────────────────────────────────────────────────────────────────┬──────► │ ┌────────────────────────┐ │ └─ EDIt ─┬─ VALid ◄ ─┬─ TABle is ( ─▼─
value
┬─────────────┬─┴─ ) ──┘ └─ INValid ─┘ └ THRu
value
─┘ ┌─────────────────────────────────────────────────────────────┐ ►─▼─┬─────────────────────────────────────────────────────────┬─┴────────────► │ ┌──────────────────────────────┐ │ └─ CODe TABle is ( ─▼─
encode-value
decode-value
─┴─ ) ──┘ ►─┬────────────────────────────────┬─────────────────────────────────────────► └─ EXTernal PICture is
picture
──┘ ┌───────────────────────────────────────────────────────────────┐ ►─▼─┬───────────────────────────────────────────────────────────┬─┴──────────► │ ┌────────────────────┐ │ └─ EDIt ─┬─ COMments ──────┬─▼─
edit-instruction
─┴─ QUIT ──┘ ├─ DEFinition ────┤ ├─ OLQ header ────┤ ├─ CULprit header ┤ └─
comment-key
───┘ ┌──────────────────────────────────────────────────┐ ►─▼─┬──────────────────────────────────────────────┬─┴───────────────────────►◄ └─┬─ COMments ───────┬─ is ─┬─ NULl ─────────┬─┘ ├─ DEFinition ─────┤ └─
comment-text
─┘ ├─ OLQ header ─────┤ ├─ CULprit header ─┤ └─
comment-key
────┘
Expansion of
record-synonym-specification
►►─┬──────────────────────────────────────────────────────────────────────────►─ └─
record-synonym-name
─┬──────────────────────────────────┬─────────────── └─ Version is ─┬
version-number
┬──┘ ├ HIGhest ───────┤ └ LOWest ────────┘ ─►───────────────────────────────────────────┬────────────────────────────────►◄ ─── is ─┬─
index-element-name
───────────┬─┘ │ ┌─────────────────────┐ │ └─ ( ─▼─
index-element-name
┴─ )─┘
Parameters
  • level-number
    element-name
    Specifies the level number and name of the COBOL element.
    Level-n
    must be an unsigned integer in the range 02 through 49, or 88. Note that the 01-level name is the record name itself or a synonym.
    Element-name
    must be the 1- through 32-character name of the element. The specified name will be appended with a prefix or suffix if any record synonyms associated with the record have been assigned prefixes or suffixes.
  • REDefines
    base-element-name
    Specifies an alternative description for a previously defined element. The requested element is assigned the same storage space as
    base-element-name
    . Note that a redefined element cannot be defined with an OCCURS clause; it can, however, be subordinate to an element defined with an OCCURS clause.
  • PICture is
    picture
    Describes the format of the COBOL element. The maximum length of a COBOL element (including its usage) is 32,767 characters.
    Picture
    must be a 1- through 30-character value specified as shown in the table under
    Usage
    .
  • VALue is/VALues are
    initial-value
    /
    condition-value
    Specifies a value, range of values, or a list of values assigned to a COBOL level-88 condition-name. A list of values must be enclosed in parentheses. Each value in the list must be separated from the next value by a space or comma. A value can be a 1- through 32-character value specified as shown in the list under the bold heading
    Usage
    .
  • USAge is
    Specifies the method of storing elementary item values at program runtime.
  • DISplay
    Specifies that values are stored one character to a byte according to EBCDIC conventions. DISPLAY is the default.
  • COMPUTATIONAL
    Numeric values are stored in binary format; COMP, COMPUTATIONAL-4, COMP-4, and BINary are synonyms for COMPUTATIONAL.
  • COMPUTATIONAL-1
    Numeric values are stored in internal floating point (short precision) format; COMP-1 and SHOrt-point are synonyms for COMPUTATIONAL-1.
  • COMPUTATIONAL-2
    Numeric values are stored in internal floating point (long precision) format. COMP-2 and LONg-point are synonyms for COMPUTATIONAL-2.
  • COMPUTATIONAL-3
    Numeric values are stored in packed decimal format; COMP-3 and PACked are synonyms for COMPUTATIONAL-3.
  • BIT
    Values are stored one bit at a time as 0s or 1s. BIT cannot be used in COBOL programs.
  • POInter
    Fullword address constant.
  • CONdition-name
    COBOL level-88 values. CONDITION-NAME is assumed if the level number specified for the record element is 88.
  • SQLBINARY
    An SQL BINARY datatype; Identifies a fixed length array of bytes and should be defined with PIC X(n) where n is in the range 1 through 32,760.The maximum length ofan element with a data type of SQL BINARY is limited by page size and the total length of other elements in the record.
  • ELement name SYNonym is
    element-synonym
    Establishes a synonym (alternative name) for the COBOL element.
    Element-synonym
    is the 1- to 32-character synonym name. The specified name will be appended with a prefix or suffix if a prefix or suffix has been defined for the associated record-synonym name. This clause can be specified once for each record synonym associated with the record.
  • FOR RECord synonym
    record-synonym
    Associates the element synonym with the designated record synonym.
    If the FOR RECORD SYNONYM parameter is not specified, the ELEMENT NAME SYNONYM clause applies only to the primary record name.
  • JUStify right
    Specifies that the COBOL element's value is to be right-justified at runtime.
  • BLAnk when ZERo
    Specifies that when the COBOL element's values contains all zeroes it is to be changed to spaces at runtime.
  • SIGn is LEAding/TRAiling
    Specifies whether the sign for a numeric field is to appear in the leading or trailing position.
  • SEParate character
    Specifies that the sign is to appear as a separate byte.
  • SYNChronized LEFt/RIGht
    Determines whether boundary alignment is to be defined for the named COBOL element. The correct alignment is determined by the USAGE specification. If the element's usage is COMP or COMP-4, the DDDL compiler issues a warning message if the element is not on the proper boundary alignment. This clause is documentation only, unless the DMLC precompiler is used to copy the record; in this case, the specified boundary alignment will be applied by the COBOL compiler. If the COBOL element is copied into a schema, it causes a critical schema error.
  • OCCurs
    Specifies a record-specific OCCURS clause for the named COBOL element.
  • occurrence-count
    times
    Specifies the number of times the element can occur within the record.
    Occurrence-count
    must be an integer in the range 0 through 32,767.
  • occurrence-count
    times/0 TO
    occurrence-count
    times DEPending on
    control-element-name
    Defines a control element within the record that determines the actual number of times the COBOL element will occur.
    Occurrence-count
    must be an integer in the range 1 through 32,767.
    Control-element-name
    specifies a previously defined field in the record; this field must be a halfword or fullword binary item if the record is to be used in a schema or by CA ADS.
  • INDexed by
    Specifies one or more indexes for a multiply-occurring element or for a record synonym associated with the named COBOL element.
    The INDEXED BY clause can be specified once for each record element or subordinate element and record synonym; the index element name is appended with a prefix or suffix as appropriate. The INDEXED BY clause applies only to records used in COBOL programs and should be specified only when the named element definition contain on OCCURS or OCCURS DEPENDING ON clause. The specified index name is copied into the program's DATA DIVISION by the DMLC precompiler as part of the COPY IDMS function.
  • index-element-name
    Specifies an INDEXED BY name for the named COBOL element. The specified value must be a 1- through 32-character name that does not duplicate an existing element or element-synonym name.
  • FOR REcord synonym
    record-synonym
    is
    index-element-name
    Specifies an INDEXED BY name for a record synonym associated with the record element.
    Index-element-name
    is a 1- through 32-character name that cannot duplicate an element or element-synonym name in the record.
  • INDex KEY is
    Specifies one or more index keys through one of the following options; note that each option is functionally the same.
  • INDex KEY is
    index-element-name
    ASCending/DEScending
    Specifies a record-specific index key for the record element or subordinate record element.
    Index-element-name
    identifies an elementary element that is subordinate to the associated element and must be the primary name of the record element. ASCENDING or DESCENDING specifies the manner in which the subordinate element values will be ordered within the multiply-occurring group.
  • ASCending/DEScending key is
    index-element-name
    Specifies one or more record-specific index keys for the multiply-occurring group element or subordinate element and defines the manner in which subordinate element values will be ordered within the multiply-occurring group.
    Index-element-name
    must be the primary name of an element that is subordinate to the named group element. The named element and the ASCENDING/DESCENDING specification govern the ordering of values of the subordinate element within the multiply-occurring group. Each index element name is prefixed or suffixed for each record synonym associated with the element.
  • EDIt VALid/INValid TABle is
    value
    THRu
    value
    Specifies a single value or range of values to be inserted in the edit table (for DC/UCF tables only). Each value can have a maximum size of 34 characters and must be enclosed in parentheses; for example:
    ('A' 'B' 'D' 'F' 'R' THRU 'T' 'V' 'X' THRU 'Z')
  • VALid/INValid
    Identifies the supplied list as a list of valid values or a list of invalid values. The default is VALID.
  • CODe TABle is
    encode-value
    decode-value
    Specifies values to be inserted in the table in pairs (for DC/UCF tables only). The first or
    encoded
    value can have a maximum size of 34 characters; the second or
    decoded
    value can have a maximum of 64 characters. Null values ('') and the keywords NOT FOUND are also valid. The specified values must be enclosed in parentheses. For example:
    ('CA' 'CALIFORNIA' 'NY' 'NEW YORK')
    For detailed information about defining code tables, refer to the
    CA IDMS Reference section
    manual.
  • EXTernal PICture is
    picture
    Defines the display format for record-element data. The picture is available to all map fields that use the record element. For more information about external pictures, refer to the
    CA IDMS Reference section
    manual.
Usage
COBOL substatement considerations
The following considerations apply to the COBOL substatement:
  • The named record element is validated against elements in the dictionary, as follows:
    • If identical primary or synonym names are found, the DDDL compiler examines each element for identical PICTURE, USAGE, BLANK WHEN ZERO, JUSTIFY, and SIGN specifications, and for identical group structures (if any); level-88 elements are also examined. If the definition of the named COBOL element matches the definition of an existing element, the DDDL compiler copies the definition of the existing element into the named record. If the two elements have matching names only, a new element is added to the dictionary and is automatically assigned the highest existing version number plus 1.
      Differences in the entry formats for COBOL PIC are resolved (for example, pic x(2) is recognized as equivalent to pic xx).
    • If identical primary or synonym names are not found, a new element is added to the dictionary and automatically assigned a version number of 1.
  • Elementary fillers are treated the same way as elementary elements. If the PICTURE, USAGE, BLANK WHEN ZERO, JUSTIFY, and SIGN specifications match those associated with an existing filler, that filler is used; otherwise, a new filler is added to the dictionary. Note that when a filler with a VALUE clause is copied into the record-element structure, the value itself is not copied; rather, a value of NO VALUES is assigned to the filler.
  • Fillers can be group elements; in this case, the rules for forming group elements apply.
  • COBOL substatements are used to define record elements as tables that are used by the DC/UCF mapping facility for automatic editing and error handling. Tables defined by means of the COBOL substatement are called
    built-in tables
    .
    The TABLE statement (described under TABLE, later in this section) is used to define stand-alone tables. For a complete description of built-in and stand-alone tables, refer to the
    CA IDMS Reference section
    .
Specifying a
picture
variable
Picture
must be a 1- through 30-character value that describes the types of data shown in the following table.
Category
Character
Description
Alphanumeric data
X
Represents one alphanumeric character. If USAGE IS BIT, X represents one bit; f USAGE IS SQLBINARY, X represents one byte; the USAGE clause is described in the parameters list.
(n)
An integer in parentheses after an X
Represents
n
repetitions of the alphanumeric character; for example, X(4) is equivalent to XXXX.
Alphabetic data
A
Represents one alphabetic character (A-Z).
(n)
An integer in parentheses after an A
Represents
n
repetitions of the alphabetic character
Numeric data
9
Represents one numeric character.
(n)
An integer in parentheses after a 9
Represents
n
repetitions of the numeric character.
V
Represents an assumed decimal point. No more than one V can appear in an element picture. If the V is omitted and the P option (described below) is not used, the assumed decimal point is after the rightmost 9.
P
Represents an assumed zero. Any number of Ps can appear in the leftmost or the rightmost positions of an element picture. An assumed decimal point is automatically placed before the first P or after the last P. The character P does not occupy a storage position (for example, PP9999 has a data length of 4).
S
Identifies the number as positive or negative. When used, the S must be the first character in the element picture. When the S is omitted, values for the element description are assumed to be positive.
Numeric- edited data
(Includes the numeric data characters described above, along with the editing characters shown at the right)
Z
+
,
B
CR
-
0
DB
*
$
.
Represent edit symbols used in reporting data; quotation marks are not required. Refer to the appropriate programming language manual for the individual interpretations of these symbols.
If the SET OPTIONS statement specifies DECIMAL-POINT IS COMMA, a period (.) is interpreted as an insertion character and a comma (,) is interpreted as a decimal point.
Valid values for the VALUE clause
Valid types of values for the VALUE clause are as follows:
  • Figurative constant
    -- For alphanumeric and numeric data items, ZERO, ZEROS, ZEROES. For alphanumeric data items only: SPACE, SPACES, HIGH-VALUE, HIGH-VALUES, LOW-VALUE, LOW-VALUES.
  • Nonnumeric literal
    -- For alphanumeric data items only, a string of characters enclosed in single quotation marks. The character string must not exceed the size specified in the element's PICTURE clause.
  • Numeric literal
    -- For numeric items only, a string of numeric characters, optionally preceded by a plus (default value) or minus sign and optionally containing a decimal point. The numeric string must not exceed the size of the data item as defined in the PICTURE clause.
REMOVE ALL Substatement
The REMOVE ALL substatement is used in conjunction with an ADD RECORD or MODIFY RECORD statement to delete the record-element structure associated with the named record. You can create a new record-element structure by coding RECORD ELEMENT substatements immediately following the REMOVE ALL substatement; the rules for ADD RECORD apply. REMOVE ALL also removes any IDD-built subschema views (see VIEW ID Substatement below).
Syntax
REMOVE ALL substatement
►►─── REMove ALL ─────────────────────────────────────────────────────────────►◄
VIEW ID Substatement
The VIEW ID substatement establishes or removes a view of record elements. Once established, this view can be copied into one or more CA IDMS subschemas. Before issuing a VIEW ID substatement, you should ensure that all record elements identified in the view are present in the record. The following rules apply to the VIEW ID substatement:
  • VIEW ID must be the last substatement coded in the RECORD statement.
  • Record elements named in the view must be identified by their primary names.
  • All record elements named in the view must be at the same level.
  • A record element that is subordinate to an OCCURS clause cannot be included in the view.
  • A REDEFINES element cannot be included in the view. If a redefined element is included, all redefining elements are automatically included in the view.
  • An OCCURS DEPENDING ON record element must be the last record element in the view.
  • Bit fields cannot be named.
  • A record element can be named only once.
  • If a group element is included, all subordinate elements are automatically included in the view. The order of group/subordinate record elements is retained.
Syntax
VIEW ID substatement
┌──────────────────────────────────────────────────────────────────────── ►►──▼─┬──────────┬─ VIEw ID is
view-identifier
──────────────────────────────►─ └─ REMove ─┘ ──────────────────────────────────────────────────┐ ─►──┬─────────────────────────────────────────────┬─┴────────────────────────►◄ │ ┌─────────────────────────────────────────┐ │ └─▼─ RECord ELement is
record-element-name
─┴─┘
Parameters
  • VIEw ID is
    view-identifier
    Identifies a list of record elements that is to comprise a view.
    View-identifier
    must be a 1- through 32-character alphanumeric value. The VIEW ID substatement can appear any number of times in one RECORD statement. If the optional REMOVE parameter is specified, the named view is deleted.
  • RECord ELement is
    record-element-name
    Identifies a record element to be added to the view.
    Record-element-name
    must be an element that exists in the named record-element structure. This clause can appear any number of times in one VIEW ID substatement.