Element Substatement

The element substatement associates an element with the record and, if the element does not already exist, adds the element description to the dictionary. Schema element descriptions cannot be modified or deleted. To change element descriptions, modify the record description and respecify all of the record's elements.
idms19
The element substatement associates an element with the record and, if the element does not already exist, adds the element description to the dictionary. Schema element descriptions cannot be modified or deleted. To change element descriptions, modify the record description and respecify all of the record's elements.
This topic contains the following information:
Syntax
Element substatement
►►─── level-number element-name ─────────────────────────────────────────────► ►─┬───────────────────────────────┬──────────────────────────────────────────► └─ REDefines base-element-name ─┘ ►─┬──────────────────────┬───────────────────────────────────────────────────► └─ PICture is picture ─┘ ►─┬──────────────────────────────────────────────────────────────────────────► │┌─────────────────────────────────────────────┐ └▼─┬─ VALue is ───┬─┬─ .───┬─ initial-value ──┴───────────────────────────► └─ VALues are ─┘ └─ ALL ─┘ ►─┬──────────────────────────────────────────────────────────────────────────► │┌──────────────────────────────────────────────────────────────────────── └▼─┬─ VALue is ───┬───── .────────────────────────────────────────────────── └─ VALues are ─┘ ─►──────────────────────────────────────────────────────────────────────────┬─► ───────────────────────────────────────────────────────────────────────┐ │ ──┬─┬────────┬─ condition-value ─────────────────────────────────────┬─┴─┘ │ └─ ALL ──┘ │ │ ┌──────────────────────────────────────────────────────────┐ │ └ (▼ ┬─────┬ condition-value ┬───────────────────────────────┬┴ ) ─┘ └ ALL ┘ └ THRu ─┬─────┬ condition-value ┘ └ ALL ┘ ►─┬──────────────────────────────────────┬───────────────────────────────────► └─ USAge is ─┬─ BIT ─────────────────┬─┘ ├─┬─ COMPUTATIONAL ─┬───┤ │ ├─ COMp ──────────┤ │ │ └─ BINary ────────┘ │ ├─┬─ COMPUTATIONAL-1 ─┬─┤ │ ├─ COMP-1 ──────────┤ │ │ └─ SHOrt-point ─────┘ │ ├─┬─ COMPUTATIONAL-2 ─┬─┤ │ ├─ COMP-2 ──────────┤ │ │ └─ LONg-point ──────┘ │ ├─┬─ COMPUTATIONAL-3 ─┬─┤ │ ├─ COMP-3 ──────────┤ │ │ └─ PACked ──────────┘ │ ├─┬─ COMPUTATIONAL-4 ─┬─┤ │ └─ COMP-4 ──────────┘ │ ├─ CONdition-name ──────┤ ├─ DISplay ─────────────┤ ├─ DISplay-1 ───────────┤ ├─ POInter ─────────────┤ └─ SQLBINary ───────────┘ ►─┬────────────────────────────┬─────────────────────────────────────────────► └─ SYNChronized ─┬─────────┬─┘ ├─ LEFt ──┤ └─ RIGht ─┘ ►─┬──────────────────────────────────────────────────────────────────────────►─ └─ OCCurs ───────────────────────────────────────────────────────────────── ─►──────────────────────────────────────────────────────────────────────────┬─► ─┬─ occurrence-count times ──────────────────────────────────────────────┬┘ └─┬─ occurrence-count ──────┬─ times DEPending on control-element-name ─┘ └─ 0 TO occurrence-count ─┘ ►─┬─────────────────┬────────────────────────────────────────────────────────► └─ JUStify RIGht ─┘ ►─┬───────────────────┬──────────────────────────────────────────────────────► └─ BLAnk when ZERo ─┘ ►─┬───────────────────────────────────────────────────┬──────────────────────► └─ SIGn is ─┬─ LEAding ──┬─┬──────────────────────┬─┘ └─ TRAiling ─┘ └─ SEParate character ─┘ ►─┬─────────────────────────────────────┬────────────────────────────────────► │ ┌─────────────────────────────────┐ │ └─▼─ element-synonym-specification ─┴─┘ ►─┬─────────────────────────────────────────┬────────────────────────────────► └─ INDexed BY ─┬─ index-name ─────────────┤ │ ┌──────────────┐ │ └─ ( ─▼─ index-name ─┴─ ) ─┘ ►─┬─────────────────────────────────────────────────────────────┬────────────► ├─ INDex KEY is ─┬─ index-name ─┬─ ASCending ──┬────────────┬─┤ │ │ └─ DEScending ─┘ │ │ │ │ ┌───────────────────────────────┐ │ │ │ └─ ( ─▼─ index-name ─┬─ ASCending ──┬─┴─) ─┘ │ │ └─ DEScending ─┘ │ └─┬─ ASCending ──┬─ key is ─┬─ index-name ───────────┬────────┘ └─ DEScending ─┘ │ ┌──────────────┐ │ └─( ─▼─ index-name ─┴ ) ─┘ ►─┬────────────────────────────────────────────────────────────────────────┬─► │ ┌────────────────────────────────────────────────────────────────────┐ │ │ │ ┌──────────────────────────┐ │ │ └─▼─ EDIt ─┬───────────┬─ TABle is ( ─▼─ 'value'─┬───────────────┴┬ ) ─┴─┘ ├─ VALid ◄──┤ └─ THRu 'value' ─┘ └─ INValid ─┘ ►─┬────────────────────────────────────────────────────────────────┬─────────► │ ┌────────────────────────────────────────────────────────────┐ │ │ │ ┌─────────────────────────────────┐ │ │ └─▼─ CODe TABle is ( ─▼─ 'encode-value' 'decode-value' ─┴─ ) ─┴─┘ ►─┬───────────────────────────────┬──────────────────────────────────────────► └─ EXTernal PICture is picture ─┘ ►─┬──────────────────────────────────────────────────┬───────────────────────►◄ │┌───────────────────────────────────────────────┐ │ └▼─┬─ OLQ header ─────┬─ is ─┬─ 'comment-text'─┬─┴─┘ ├─ CULprit header ─┤ └─ NULl ──────────┘ ├─ COMments ───────┤ ├─ DEFinitions ────┤ └─ comment-key ────┘
Expansion of
element-synonym-specification
►►─── element ─┬─ SYNonym name ─┬─────────────────────────────────────────────► └─ name SYNonym ─┘ ►─── FOR language language is synonym-name ──────────────────────────────────►◄
Parameters
  • level-number
    Indicates the level within the record to be occupied by the element. The level number must be an unsigned integer in the range 02 through 49, or 88. Level 88 applies to records used with CA ADS or COBOL only. Note that the highest level (01) in any record description is assigned by CA IDMS/DB to the record itself. The COBOL and PL/I DML precompilers can be directed to change the level numbers when the record is copied into a program (see the language-specific CA IDMS DML reference).
  • element-name
    Identifies the element to be added to the record description.
    Element-name
    must be a 1- to 32-character name. The first character must be A through Z (alphabetic), digit (0 through 9), #, $, or @ (international symbols). The hyphen can also be used except as the first or last character, or following another hyphen.
    Element-name
    must not be the same as the schema name or the name of any other component (including synonyms) within the schema, with the following exceptions:
    • An element name or synonym can be duplicated within a schema, but must be unique within the record.
    • The special element name FILLER, which can be used on as many levels and as many times as appropriate, describes an element without naming it. A FILLER element must not be the object of a REDEFINES clause (a FILLER element can, however, redefine another element).
  • REDefines
    base-element-name
    Specifies an alternative description for a previously defined place within the record structure. At runtime, when a program's storage is allocated, the redefining element description will not be allocated new storage space but will, instead, be assigned the same storage as
    base-element-name
    .
    Base-element-name
    must be the name of a preceding element of the same level within the record structure. When used, the REDEFINES clause must adhere to the following rules:
    • The element containing the REDEFINES clause must not be longer than the base element. Subordinate elements can vary in size, as necessary, within the redefining element or the base element.
    • The redefining element cannot be a CALC, sort control, or foreign key element; the base element can be.
    • Neither the redefining element nor the base element can be a level-88 description.
    • No intervening element (of the same or lower level number) that assigns space can exist between the base element and the redefining element. Other redefining elements, however, are allowed. When an element is redefined more than once, the redefining elements must refer to the name of the base element.
    • Neither the redefining element nor its subordinate elements can contain a VALUE clause, except subordinate level-88 elements.
    • Elements subordinate to the redefining element can contain REDEFINES clauses.
    • Neither the base or redefining element nor their subordinate elements can contain OCCURS DEPENDING ON clauses.
    • Elements to which the base and redefining elements are subordinate can contain OCCURS clauses (
      without
      DEPENDING ON). The base element cannot contain an OCCURS clause, but its subordinate elements can. The redefining element and its subordinate elements can contain OCCURS clauses.
  • PICture is
    picture
    Describes an element by depicting the element's length and data type. PICTURE is not valid for level-88 elements or for elements whose usage is COMPUTATIONAL-1, COMPUTATIONAL-2, or POINTER; For other types of elements, specify
    picture
    as a 1- to 30-character value that includes only those characters specific to the element's data type. The schema compiler's PICTURE specifications are similar to those for COBOL. See the "Usage" topic for a description of PICTURE specifications for valid data types.
  • VALue is/VALues are
    Assigns an initial value or a list of values to an element description in the application program's main storage at program runtime, or it assigns a conditional value or a list of conditional values to a COBOL condition name (level-88 element). All level-88 element descriptions must include the VALUE clause. Enclose listed values in parentheses.
    The VALUE clause has no effect on the database directly; the DBA is encouraged not to include
    initial-value
    in the data descriptions except as background or null values for use in main storage.
    The VALUE clause is prohibited for the following:
    • COMP-1, COMP-2, and BIT element descriptions
    • An element description containing a REDEFINES clause or an element description subordinate to one containing a REDEFINES clause
    • An element description containing an OCCURS clause or an element description subordinate to one containing an OCCURS clause
    • An element description of an external floating point number
  • ALL
    Instructs CA IDMS/DB to fill the element description with repetitions of
    initial-value
    . For example, PIC X(5) VALUE ALL '*' is the same as PIC X(5) VALUE '*****'.
  • initial-value
    Specifies the initial value assigned to the element at runtime as follows:
    • Character string literal
      -- For alphanumeric elements only: a string of characters enclosed in site-standard quote characters. The character string (including quotes) must not exceed the size of the element as defined in the PICTURE clause or 34 bytes, whichever is shorter.
    • Numeric literal
      -- For numeric elements only: a string of 1 to 18 numeric characters, optionally preceded by a plus sign (default) or minus sign and optionally containing a decimal point (use the appropriate decimal point character as required by the session option for DECIMAL-POINT).
    • Figurative constant
      -- For alphanumeric and numeric elements: ZERO, ZEROS, and ZEROES. For alphanumeric elements only: SPACE, SPACES, HIGH-VALUE, HIGH-VALUES, LOW-VALUE, LOW-VALUES, and ALL. ALL is used in conjunction with and indicates repeated occurrences of a nonnumeric literal.
  • condition-value
    Assigns a conditional value to a COBOL condition name (level-88 element). Coding rules specified for
    initial-value
    above also apply to
    condition-value
    .
    Condition-value
    must conform to the picture for the element that occupies storage.
  • THRu
    condition-value
    Specifies a range of valid condition values for COBOL condition names (level 88). When THRU is used, the first
    condition-value
    assigns the first of a range of values that the condition name will represent at runtime; the second
    condition-value
    assigns the ending value of the range. To list values or ranges of values, enclose the list in parentheses.
  • USAge is
    Specifies the storage format of data elements. USAGE defaults to CONDITION-NAME for level-88 elements and to DISPLAY for all others.
  • BIT
    Values are stored as bits containing 0s or 1s. Bit elements must always be described in multiples of 8. (CA IDMS/DB does not provide slack bits.) The multiples of 8, however, can range over adjacent elements. For example, five bits can be described in one element and three in the next.
  • COMPUTATIONAL/COMp/BINary
    Numeric values are stored in binary format with the following space requirements:
    • 1 to 4 decimal digits require 2 bytes (1 halfword).
    • 5 to 9 decimal digits require 4 bytes (1 fullword).
    • 10 to 18 decimal digits require 8 bytes (1 doubleword).
  • COMPUTATIONAL-1/COMP-1/SHOrt-point
    Numeric values are stored in internal floating point (short precision) format, requiring 4 bytes. Do not code a PICTURE clause with this usage.
    VS2 COBOL does not support COMPUTATIONAL-1.
  • COMPUTATIONAL-2/COMP-2/LONg-point
    Numeric values are stored in internal floating point (long precision) format, requiring 8 bytes. Do not code a PICTURE clause with this usage.
    VS2 COBOL does not support COMPUTATIONAL-2.
  • COMPUTATIONAL-3/COMP-3/PACked
    Numeric values are stored in packed decimal format, requiring a half byte for each decimal digit plus a half byte for a sign, rounded up to the next full byte.
  • CONdition-name
    The element does not occupy storage. CONDITION-NAME is assumed if level 88 is specified for the element. Note that CONDITION-NAME can be used in CA ADS dialogs and COBOL programs only. Do not code a PICTURE clause with this usage.
  • DISplay
    Values are stored 1 character to a byte, according to EBCDIC conventions.
  • DISplay-1
    One character occupies 2 bytes. DISPLAY-1 must be specified for double-byte character string (DBCS) data items.
  • POInter
    Values are stored as fullwords. POINTER is used for elements that are to be used as address constants. Do not code a PICTURE clause with this usage.
  • 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.
  • SYNChronized
    Documents the following alignments for usages of COMP, COMP-1, and COMP-2:
    • COMP -- Halfword (1 to 4 decimal digits) or fullword (5 to 18 decimal digits) alignment
    • COMP-1 -- Fullword alignment
    • COMP-2 -- Doubleword alignment
    The SYNCHRONIZED specification does not force alignment, but rather documents user-imposed alignment. If synchronized is specified, filler elements must be used to align numeric data according to the above rules.
  • OCCurs
    occurrence-count
    times
    Specifies the number of times that the element is to be repeated.
    Occurrence-count
    must be an unsigned integer in the range 1 through 32,767. Individual occurrences of the element are referenced in application programs by placing a subscript after the element name.
    Observe the following rules when using the OCCURS clause:
    • An element containing an OCCURS clause cannot be a CALC, sort control, or foreign key element, nor can an element subordinate to an element containing an OCCURS clause be a CALC, sort control, or foreign key element.
    • Neither an element containing an OCCURS clause nor an element subordinate to an element containing an OCCURS clause can contain a VALUE clause.
    • OCCURS clauses can be nested no more than three deep for use in COBOL programs. Otherwise, any depth of nesting is permissible.
  • 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
    must identify an elementary data element that precedes the element being defined in the record. It must be defined as a signed computational element with a picture in the range S9 through S9(9) or 9 through 9(9). Runtime values of
    control-element-name
    must be in the range 0 through 32,767 (but not exceeding
    occurrence-count
    ).
    Individual OCCURS DEPENDING ON elements are referenced in the same fashion as individual OCCURS elements. Observe the same rules as for the OCCURS clause with the following additions:
    • Only one OCCURS DEPENDING ON clause can appear in a record description. The group or elementary item description containing the clause must be the last one in the record description (that is, no element description with the same or lower level number can follow an OCCURS DEPENDING ON element).
    • Control-element-name
      cannot contain an OCCURS or REDEFINES clause, nor can it be subordinate to elements that do.
    • The element containing an OCCURS DEPENDING ON clause can have subordinate elements that contain OCCURS clauses.
  • 0 to
    occurrence-count
    times DEPending on
    control-element-name
    Indicates that the multiply-occurring group occurs from 0 to
    occurrence-count
    times depending on the value of the control-element. Rules for
    occurrence-count
    and
    control-element-name
    appear above.
  • JUStify RIGht
    Specifies that when the element's runtime value is not as long as the element's picture allows, the value will occupy the rightmost positions of the element. JUSTIFY RIGHT is valid for alphanumeric or alphabetic elements only (group item or one whose PICTURE is specified with Xs or As).
  • BLAnk when ZERo
    Specifies that when the element's runtime value is zero, the value will be changed to spaces.
  • SIGn is LEAding
    Specifies that the sign of a numeric field is to appear in the leading position. This clause is valid for numeric display elements only.
  • SIGn is TRAiling
    Specifies that the sign of a numeric field is to appear in the trailing position. This clause is valid for numeric display elements only.
  • SEParate character
    Causes the sign of a numeric field to appear as a separate byte. This clause is valid for numeric display elements only.
  • element-synonym-specification
    Associates a synonym (alternative name) with the element specified in the ELEMENT substatement. These synonyms are language dependent: each DML precompiler will automatically include the synonym associated with the compiler-specific programming language.
  • language
    Specifies the host language with which the synonym will be used. Valid values are any languages associated with the record's synonyms.
  • synonym-name
    Specifies the name of the synonym to be associated with the primary element name; it must be specified according to the rules for the host language with which the synonym is being used and must follow the rules specified above for element names.
  • INDexed BY
    index-name
    Defines an index to be used at runtime for a multiply-occurring element (that is, one whose definition contains an OCCURS or OCCURS DEPENDING ON clause). This index is used in COBOL SET and SEARCH operations, and is therefore used as a subscript when accessing the associated OCCURS or OCCURS DEPENDING ON element.
    Index-name
    must be a 1- to 30-character name; the characters can be A through Z (at least one), 0 through 9, or the hyphen (except as the first or last character or following another hyphen). It cannot duplicate any element named in the schema.
    Index-name
    is implicitly defined as a fullword binary item.
    You can specify more than one index by creating a list of names enclosed in parentheses.
  • INDex KEY is
    index-name
    Specifies one or more record-specified index keys for a multiply-occurring group record element or a subordinate record element.
    Index-name
    identifies an elementary element that is subordinate to the associated element. It must be the primary name of the subordinate element; it cannot be a synonym.
    You can specify more than one index key by creating a list enclosed in parentheses. Each key can be either ascending or descending.
    Note that the INDEX KEY clause allows a mixed collating sequence (that is, a mixture of ascending and descending keys); the ASCENDING/DESCENDING KEY IS clause does not.
  • ASCending
    Sorts the designated key in ascending order.
  • DEScending
    Sorts the designated key in descending order.
  • ASCending/DEScending KEY is
    index-name
    Specifies one or more record-specific index keys for the multiply-occurring group element or subordinate element.
    Index-name
    must be the primary name of an element that is subordinate to the named group element. ASCENDING and DESCENDING sorts the subordinate elements within a multiply-occurring field in ascending or descending order, respectively.
    You can specify more than one index key by creating a list enclosed in parentheses.
  • EDIT TABle is
    Specifies an edit table associated with the record element. An edit table contains a list of valid or invalid values for the record element used by the DC/UCF mapping facility.
  • VALid
    Indicates the edit table contains valid values for the record element. VALID is the default.
  • INValid
    Indicates the edit table contains invalid values for the record element.
  • '
    value
    '
    Specifies a value for the edit table.
    Value
    is a 1- to 34-character value enclosed in quotes. Separate one value from another with a blank or comma; for example, ('A' 'E' 'G' THRU 'M' 'X').
  • THRu '
    value
    '
    Specifies a range of values for the edit table.
  • CODe TABle is
    Specifies a translation table to be associated with the record element; for example, a record element containing state abbreviations could have a code table that identifies the name of the state:
    code table is ('ak' 'alaska' 'al' 'alabama' 'ar' 'arkansas'...)
    Code tables are used by the DC/UCF mapping facility.
  • '
    encode-value
    '
    Identifies the value to be translated.
    Encode-value
    is a 1- to 34-character value enclosed in quotes.
  • '
    decode-value
    '
    Identifies the translated value.
    Decode-value
    is a 1- to 64-character value enclosed in quotes. Null values ('') and NOT FOUND are also valid.
  • 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.
  • OLQ header
    Defines one or more column headers to be used in place of the element name in CA OLQ reports.
  • CULprit header
    Defines one or more column headers to be used in place of the element name in CA Culprit reports.
  • COMments
    Defines comments to be associated with the element description.
  • DEFinitions
    Defines a description of use or purpose for the record element
  • comment-key
    Defines a user-supplied name to be associated with comments about the record element. If
    comment-key
    contains embedded blanks or delimiters, enclose it in quotes.
  • comment-text
    Specifies text associated with headings, definitions, or comments.
    Comment-text
    can be any length; nonnumeric literals must be enclosed in quotes. Note, however, that when coding headers, the rules for header definition must be applied to
    comment-text
    . See the
    CA OLQ Reference section
    or the CA Culprit for further details.
    Comment-text
    can be continued for any number of lines. To continue a header or comment to the next line, code a hyphen in the next line, and code a quote followed by the text of the continued comment after the hyphen. Code a closing quote after the text of the final line.
    Comments appear in schema source listings and subschema dictionary listings, and in DML listings when the SCHEMA-COMMENTS option is specified to the DML precompiler.
  • NULl
    Removes text associated with headings, definitions, or comments.
Usage
Naming Elements
When naming schema element types, be sure that the selected names conflict neither with the naming conventions of the programming language(s) that will be used with the CA IDMS Data Manipulation Language (DML) nor with the DML precompilers themselves. As a rule, schema element types should bear names that coincide with the language used most often; use element synonyms to accommodate other languages (see the ELEMENT SYNONYM NAME clause later). In addition to the element naming rules stated above, consider the following points when selecting names (or synonyms) for schema element types:
  • Assembler
    names should not exceed eight bytes in length and should not contain hyphens. When the Assembler DML precompiler (IDMSDMLA) generates a DC or DSECT from a schema element description, it uses the element name as the DC or DSECT name. If the element name exceeds eight bytes in length, IDMSDMLA truncates it, possibly causing duplicate names to appear in the program.
  • COBOL
    requires names that do not exceed 30 bytes in length and do not contain the characters #, $, or @. When the COBOL DML precompiler (IDMSDMLC) generates a field description from a schema element description, it uses the element name as the field name. If the element name exceeds 30 bytes in length, IDMSDMLC truncates it, possibly causing duplicate names to appear in the program.
  • PL/I
    requires names that do not exceed 31 bytes in length and do not contain hyphens. When the PL/I DML precompiler (IDMSDMLP) generates a data field declaration from a schema element description, it changes hyphens in the element name to underscores. If the element name exceeds 31 bytes in length, IDMSDMLP truncates it, possibly causing duplicate names to appear in the program.
SQL synonyms
When using SQL to access a non-SQL defined database, each record in the non-SQL schema is accessed as a table. The name of a column of the table is either:
  • The element synonym for language SQL, if one exists
  • The element name within the schema record
In either case, hyphens within the name are converted to underscores so that it does not have to be enclosed in quotes within SQL statements.
Elements which occur a fixed number of times within the record have a suffix appended to their name to distinguish occurrences. The suffix is composed of occurrence numbers for each level of nested occurs. For example, if element QUARTERLY-QUOTA occurs 4 times, the corresponding column names are:
  • QUARTERLY_QUOTA_1
  • QUARTERLY_QUOTA_2
  • QUARTERLY_QUOTA_3
  • QUARTERLY_QUOTA_4
If QUARTERLY_QUOTA is a sub-element within element ANNUAL- SALES which occurs 3 times, the corresponding column names would be:
  • QUARTERLY_QUOTA_1_1...QUARTERLY_QUOTA_1_4
  • QUARTERLY_QUOTA_2_1...QUARTERLY_QUOTA_2_4
  • QUARTERLY_QUOTA_3_1...QUARTERLY_QUOTA_3_4
Since column names are restricted to 32 characters, it may be necessary to define an SQL synonym for a multiply occurring element so that CA IDMS/DB can append the required suffix.
Function of element level numbers
The function of level numbers 02 through 49 is to create a hierarchy among the element descriptions for a record so that a programmer can, with a single reference, access elements discretely or in groups. The technique is to follow an element description of one level with element description(s) of a higher numbered level. For example, a level 03 element is subordinate to a level 02 element.
Group items and elementary items
A
group item
contains two or more subordinate elements. A DML reference to a group item gains access to all subordinate items. A subordinate item can, in turn, be a group item, with nesting permitted until level 49 is reached (unless otherwise excepted). An item description that has no subordinate items is called an
elementary item
.
The following example outlines the element descriptions for the EMPLOYEE record:
02 EMP-ID... elementary item 02 EMP-NAME... group item 03 EMP-FNAME... elementary items subordinate 03 EMP-LNAME... to EMP-NAME 02 EMP-SEX... elementary item 02 EMP-ADDRESS... group item 03 EMP-STREET... elementary items subordinate 03 EMP-CITY... to EMP-ADDRESS 03 EMP-STATE... 03 EMP-ZIP... group item subordinate to EMP-ADDRESS 04 EMP-ZIP-FIRST-5... elementary items subordinate 04 EMP-ZIP-LAST-4... to EMP-ZIP
Minimum element substatements
The minimum element substatement required for the element to be a
valid
schema component depends on whether the element is a group or elementary item:
  • Group items
    require level number and name only.
  • Elementary items
    require level number, name, and picture (or usage, where the item usage prohibits picture specification).
PICTURE formats for alphanumeric data
Alphanumeric data is described by the following characters:
  • X
    -- The character X represents one alphanumeric character. Note, however, that if USAGE IS BIT (see the USAGE clause in this section), X represents one bit. If USAGE IS SQLBINARY (see the USAGE clause in this section), X represents one byte.
  • (n)
    -- An integer in parentheses can be placed after an X to represent
    n
    repetitions of the alphanumeric character (for example, X(4) means XXXX).
PICTURE formats for alphabetic data
Alphabetic data is described by the following characters:
  • A
    -- The character A represents one alphabetic character (A through Z and space only).
  • (n)
    -- An integer in parentheses can be placed after an A to represent
    n
    repetitions of the alphabetic character (for example, A(4) means AAAA).
PICTURE formats for DBCS edited data
For DBCS edited data, the PICTURE character string can contain these symbols:
Symbols
Description
G
Each G represents a single DBCS character position (two bytes). When you use this picture, the element USAGE clause must specify DISPLAY-1. Any associated VALUE clause must specify a GRAPHIC literal or the figurative constant SPACES.
B
Each B represents the position used for a space character.
In the following example, the DBCS value represents a string of up to five characters.
So
and
si
represent the shift-out and shift-in characters, respectively:
02 zip-code pic g(5) usage display-1 value g'sodbcs-valuesi'.
PICTURE formats for fixed decimal data
Fixed decimal data is described by the following characters:
  • 9
    -- The character 9 represents one numeric character.
  • (n)
    -- An integer in parentheses can be placed after a 9 to represent
    n
    repetitions of the numeric character (for example, 9(4) means 9999).
  • V
    -- The character V represents an assumed decimal point. No more than one V can appear in an element picture. If the V is omitted and P is not used, the assumed decimal point is after the rightmost 9.
  • P
    -- The character P represents an assumed zero. Any number of Ps can be placed in the leftmost or rightmost (but not both) positions of an element picture. An assumed decimal point is automatically placed before the first P when the Ps are leftmost and after the last P when the Ps are rightmost.
  • S
    -- The character S indicates that the number is maintained as either 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 considered positive.
PICTURE formats for external floating point data
External floating point data is described in two parts: the
mantissa
, which represents the decimal part (fractional part) of the element, and the
exponent
, which represents the power of 10 to which the base of one (1) must be raised before being multiplied by the mantissa to determine the element's actual value.
Syntax for the floating point picture is shown next:
►►─┬─ + ─┬─ mantissa E ─┬─ + ─┬─ exponent ────────────────────────────────────►◄ └─ - ─┘ └─ - ─┘
Symbol
Description
+/-
The plus sign or the minus sign indicates whether the mantissa is positive or negative.
mantissa
The numeric part of the mantissa is described by the following characters:
9
, which represents one numeric character;
(n)
, following a 9, which represents n repetitions of the numeric character; and V, which represents an assumed decimal point.
At least one 9 is required. No more than one V can appear in the mantissa; if the V is omitted, the assumed decimal point is after the rightmost 9.
E
The character E signifies the beginning of the exponential portion of the picture.
+/-
The plus sign or the minus sign indicates whether the exponent is positive or negative.
exponent
The numeric part of the exponent is described by the following characters:
9
, which represents one numeric character; and
(n)
, following a 9, which represents n repetitions of the numeric character.
At least one 9 is required; no more than two 9s (or the equivalent 9(2)) can be coded.
PICTURE formats for numeric edited data
Numeric edited data is described by using the numeric data characters described above, along with the following editing characters:
Z + , B CR - 0 DB * $ .
These characters represent edit symbols used in reporting data; quotes are not required. For the individual interpretations of these symbols, refer to the appropriate programming language manual.
Note that if the current decimal point default is DECIMAL-POINT IS COMMA, a period (.) is interpreted as an insertion character and a comma (,) is interpreted as a decimal point.
Data formats described only in elementary items
The actual formats of data can be described only in elementary items. Consequently, the PICTURE, USAGE (except BIT), SYNCHRONIZED, BLANK WHEN ZERO, and SIGN clauses are prohibited in group element descriptions. During programming operations, however, data is accessible not only through its elementary item description, but also through all group items under which it falls. The element EMP-ADDRESS, for example, could be referred to directly in a program.
COBOL condition names
The function of level number 88 is to assign COBOL condition names to specific runtime values of an element. A level 88 element does not occupy storage at runtime: it merely provides a name for a particular value that the preceding element's (level 02 through 49) runtime storage may contain. The name of the level-88 element is known as a condition name. A level-88 ELEMENT substatement must immediately follow either the substatement describing the element for which the level-88 element provides a condition name or another level 88 ELEMENT substatement. The following example illustrates the description of a level-88 element; see the presentation of the VALUE clause for further details:
add record name is expertise . . . 02 skill-level-0425 picture is xx. 88 expert-0425 usage is condition-name value is '04'. 88 proficient-0425 usage is condition-name value is '04'. 88 competent-0425 usage is condition-name value is '04'. 88 elementary-0425 usage is condition-name value is '04'.
Usage clause restrictions for PICTURE clause data types
Alphanumeric, alphabetic, external floating point, and numeric edited descriptions must always have a usage of DISPLAY. Fixed decimal element descriptions can have a usage of DISPLAY, COMP, COMP-3, or COMP-4.
The exact runtime characteristics of an element depend not only on the PICTURE specification, but also on other specifications for the element's format, such as USAGE. The following table illustrates several PICTURE specifications in combination with VALUE specifications.
Usage
Picture
Sample Value
Storage Requirements
DISPLAY
X(5)
T0241
5 bytes
X(10)
JUNE
10 bytes -- Padded on right with blanks
9(7)
2376600
7 bytes
9(10)
2376600
10 bytes -- Padded on left with zeros
9(7)V99
2376600.59
9 bytes -- Assumed decimal point requires no space
9(5)PP
2376600
5 bytes -- Assumed zeros require no space
+99E-9
.0000059
6 bytes
DISPLAY-1
G(5)
DBCS
character
string
10 bytes
COMP
9(4)
2376
2 bytes
9(7)V99
2376600.59
4 bytes
COMP-1
none
2376600.59
4 bytes
COMP-2
none
2376600.59
8 bytes
COMP-3
9(7)
2376600
4 bytes
9(7)V99
2376600.59
5 bytes
BIT
X
1
1 byte
X(7)
FILLER
How the COBOL DML precompiler handles bit elements
When a COBOL program copies a record that contains a bit element, the DML precompiler does the following:
  • If the bit element starts on a byte boundary, it assigns a usage of DISPLAY and a picture of X(
    n
    );
    n
    is the number of bytes before the next bit item that starts on a byte boundary.
  • If the bit element does not start on a byte boundary, it is not reflected in the COBOL program.
Element storage characteristics due to usage and picture
The following table illustrates how values are stored with different usages.
Usage
Alphanumeric Value
Internal Representation in hexadecimal
DISPLAY
BILL BALL
C2 C9 D3 D3 40 C2 C1 D3 D3
DISPLAY
4857964
F4 F8 F5 F7 F9 F6 F4
COMP
4857964
00 4A 20 6C
COMP-1
4857964
40 4A 20 6C
COMP-2
4857964
40 00 00 00 00 4A 20 6C
COMP-3
4857964
48 57 96 4C
BIT
B'11110000'
F0
POINTER
4857964
00 4A 20 6C
OCCURS DEPENDING ON creates variable-length records
The OCCURS DEPENDING ON clause makes a record variable in length. If the MINIMUM ROOT LENGTH and/or MINIMUM FRAGMENT LENGTH clauses are not included in the record description, the defaults (CONTROL LENGTH and four bytes) are assigned. The total space required in main storage for a variable-length record is:
main storage space = F + (V * M) where F = the length of the record's fixed portion V = the length of one occurrence of the record's variable portion M = the maximum number of times the control element can occur
For example, the total main storage required for the ABRIDGED-DENTAL-CLAIM record described next under "Examples" is 20 + 15 + 2 + 9 + 2 + ((2 + 2 + 2 + 2) * 10) = 128 bytes. The actual size of a specific occurrence of the record (data portion) as stored in the database, however, is as follows:
database storage space = F + (V * C) where F = the length of the record's fixed portion V = the length of one occurrence of the record's variable portion C = the value of the control element in the specific record occurrence.
A value of 2 for DC-NUMBER-OF-PROCEDURES, for example, indicates two DC-DENTIST elements and a record length of 20 + 15 + 2 + 9 + 2 + ((2 + 2 + 2 + 2) * 2) = 64 bytes.
SQL Considerations
If you intend to use SQL to access the data described by a non-SQL schema record, consider the following when designing your record elements:
  • Group elements are not visible as columns in SQL, but elementary items within group elements are visible
  • Fillers, condition names, redefining elements and elements subordinate to redefining elements are not visible as columns
  • Elements containing an OCCURS DEPENDING ON clause and elements subordinate to such an element are not visible as columns
  • The datatype of a column is derived from the picture and usage of the corresponding element as follows:
Picture and Usage
Data Type
PIC X(n) usage DISPLAY
CHAR(n)
PIC A(n) usage DISPLAY
CHAR(n)
Numeric edited1
CHAR(l), l=byte length
External floating point2
CHAR(l), l=byte length
PIC G(n) usage DISPLAY
GRAPHIC(n)
PIC S9(t)V9(s) usage DISPLAY
NUMERIC(t+s,s)
PIC SP..9(p) usage DISPLAY3
NUMERIC(p,p)
PIC S9(p)P.. usage DISPLAY3
NUMERIC(p,0)
PIC 9(t)V9(s) usage DISPLAY
UNSIGNED NUMERIC(t+s,s)
PIC P..9(p) usage DISPLAY3
UNSIGNED NUMERIC(p,p)
PIC 9(p)P.. usage DISPLAY3
UNSIGNED NUMERIC(p,0)
PIC S9(t)V9(s) usage COMP-3
DECIMAL(t+s,s)
PIC SP..9(p) usage COMP-33
DECIMAL(p,p)
PIC S9(p)P.. usage COMP-33
DECIMAL(p,0)
PIC 9(t)V9(s) usage COMP-3
UNSIGNED DECIMAL(t+s,s)
PIC P..9(p) usage COMP-33
UNSIGNED DECIMAL(p,p)
PIC 9(p)P.. usage COMP-33
UNSIGNED DECIMAL(p,0)
PIC S9(n), n<5 usage COMP4
SMALLINT
PIC S9(n), 4<n<10 usage COMP4
INTEGER
PIC S9(n), 9<n usage COMP4
LONGINT
PIC 9(n) usage COMP4
BINARY(l), l=byte length
PIC X(n) usage BIT
BINARY(l), l=byte length
PIC X(n) usage SQLBINARY
BINARY(n)
USAGE POINTER
BINARY(4)
USAGE COMP-1
REAL
USAGE COMP-2
DOUBLE PRECISION
Notes:
  1. Numeric edited
    includes any element with the following:
    • Whose usage is DISPLAY
    • Whose picture contains any of the editing symbols: + - Z B 0 $ CR DB . , *
    • Whose picture clause contains only the symbols: 9 (n) V S P, but whose element description also includes the SIGN LEADING or SEPARATE CHARACTER specification
  2. External floating point includes any element whose usage is DISPLAY and whose picture is: +/- mantissa E +/- exponent.
  3. The scaling character "P" in a picture clause is ignored in value representations of associated columns. This has the effect of representing values of such columns as a power of 10 greater than or smaller than their actual value. For example, if an element is described as PIC S9(5)PPP, a value of 123000 will be represented in SQL as 123. If an element is described as PIC SPPP9(5), a value of .000123 will be represented in SQL as .123.
  4. Computational elements also include those whose USAGE is BINARY and COMP-4. If the picture of a computational item includes an implied decimal point, it is ignored in determining the data type of the column. This has the effect of representing values of such columns as a power of 10 greater than their actual values. For example, if an element is described as PIC S9(5)V99 USAGE COMP, a value of 123.56 is represented in SQL as 12345.
Elements whose usage is BIT are not represented by columns except as noted.
Group elements in which all subordinate elements have a usage of BIT and which start on a byte boundary are represented by columns with a data type of BINARY. The length of the column is the length in bytes from the start of the group element to the start of the next element at the same level which begins on a byte boundary. If groups are nested within groups, the group element with the lowest level number in which all subordinate elements are bits is the element represented by a column. Intervening and subordinate elements are not represented by columns.
  • BIT elements occurring a fixed number of times and beginning on a byte boundary are represented by columns with a data type of BINARY. The length of the column is the length in bytes from the start of the element to the start of the next element at the same level which also begins on a byte boundary. Intervening elements are not represented by columns.
  • Other BIT elements which begin on a byte boundary are represented by columns with a data type of BINARY. The length of the column is the length in bytes from the start of the element to the start of the next element at the same level which also begins on a byte boundary. Intervening elements are not represented by columns.
Examples
Minimum element substatement
Minimal ELEMENT substatements are illustrated next:
02 claim-date. 03 claim-year picture 99. 03 claim-month picture 99. 03 claim-day picture 99.
A valid element description also requires usage information. In the above example, the schema compiler defaults to assign USAGE IS DISPLAY to each element.
Redefining the same element storage area
In the following example, one record type holds data relating to four different types of facilities and, accordingly, requires four definitions of the same storage area:
modify record name is facility. 02 fc-id pic x(4). 02 fc-lunchroom. 03 fc-l1-length pic 99. 03 fc-l1-width pic 99. 03 fc-l1-tables pic 99. 03 fc-l1-seats pic 9(4). 03 fc-l1-pots pic 99. 02 fc-lounge redefines fc-lunchroom. 03 fc-l2-chairs pic 99. 03 fc-l2-ashtrays pic 99. 03 fc-l2-tables pic 99. 03 filler pic 9(6). 02 fc-emp-library redefines fc-lunchroom. 03 fc-l3-desks pic 99. 03 fc-l3-tables pic 99. 03 fc-l3-bookcases pic 99. 03 fc-l3-mag-racks pic 99. 03 filler pic 9(4). 02 fc-hallway redefines fc-lunchroom. 03 fc-h-length pic 99. 03 fc-h-width pic 99. 03 filler pic 9(8).
Base-element-name cannot contain OCCURS clause
In the following example, any element
except EXP-SKILL-DATE-N
can contain an OCCURS clause:
05 exp-skill-date. 10 exp-skill-date-n. 15 exp-skill-year-n pic 99. 15 exp-skill-month-n pic 99. 15 exp-skill-day-n pic 99. 10 exp-skill-date-x redefines exp-skill-date-n. 15 exp-skill-year-x pic 99. 15 exp-skill-month-x pic 99. 15 exp-skill-day-x pic 99.
Group elements have implied pictures
In this example, group elements, COV-SELECT-DATE and COV-TERMIN-DATE have implied pictures of X(6). Group elements have implied pictures of X(
n
), where
n
equals the total number of bytes required by all subordinate elements.
modify record name is coverage. 02 cov-select-date. 02 cov-select-year pic 99. 02 cov-select-month pic 99. 02 cov-select-day pic 99. 02 cov-termin-date. 02 cov-termin-year pic 99. 02 cov-termin-month pic 99. 02 cov-termin-day pic 99. 02 cov-type pic x. 02 cov-insplan-code pic xxx.
Assigning condition values to level-88 elements
These two examples show different ways of assigning condition values for the same record definition:
  • Example 1:
modify record name is structure. 02 struct-code pic xx. 88 president value 'a1'. 88 sr-vice-president value 'a2'. 88 vice-president value 'a3'. 88 sr-manager value 'b1'. 88 mid-manager value 'b2'. 88 lower-manager value 'b3'. 88 supervisor value 'c1'. 88 senior value 'd1'. 88 regular value 'd2'. 88 trainee value 'd3'. 02 struct-effective-date. 03 struct-effect-year pic 99. 03 struct-effect-month pic 99. 03 struct-effect-day pic 99.
  • Example 2:
modify record name is structure. 02 struct-code pic xx. 88 president value 'a1'. 88 vice-presidents value ('a2' 'a3'). 88 managers value 'b1' thru 'b3'. 88 supervisor value 'c1'. 88 technicians value ('d1' 'd2' 'd3'). 02 struct-effective-date. 03 struct-effect-year pic 99. 03 struct-effect-month pic 99. 03 struct-effect-day pic 99.
In a COBOL program using this record description, the following statements have the same meaning:
if president then perform 0500-bigwig. if struct-code = 'a1' then perform 0500-bigwig.
Variable-length record description
The following example describes a variable number of DC-DENTIST-CHARGES elements within the ABRIDGED-DENTAL-CLAIM record type:
modify record name is abridged-dental-claim. 02 dc-dentist-address. 03 dc-dent-street pic x(20). 03 dc-dent-city pic x(15). 03 dc-dent-state pic xx. 03 dc-dent-zip pic x(9). 02 dc-number-of-procedures pic 99 comp. 02 dc-dentist-charges occurs 0 to 10 times depending on dc-number-of-procedures. 03 dc-tooth-number pic 99. 03 dc-service-date. 03 dc-serv-year pic 99. 03 dc-serv-month pic 99. 03 dc-serv-day pic 99.
Repeating group items
The following example defines eight occurrences of the DC-CLAIM-DATE element:
02 dc-claim-date occurs 8 times. 03 dc-claim-year pic 99. 03 dc-claim-month pic 99. 03 dc-claim-day pic 99.
The total length of all DC-CLAIM-DATE elements is 8 * (2 + 2 + 2) = 48 bytes. To reference the second DC-CLAIM-DATE element, the programmer can code DC-CLAIM-DATE(2) or DC-CLAIM- DATE(
subscript
), where
subscript
is an elementary item that contains the value 2. To reference only the DC-CLAIM-MONTH element of the second DC-CLAIM-DATE element, the programmer can code DC-CLAIM-MONTH(2) or DC-CLAIM-MONTH(
subscript
).
The previous example can be expanded as follows to include a second level of multiply-occurring elements:
02 dc-claim-date occurs 8 times. 03 dc-claim-year pic 99. 03 dc-claim-month pic 99. 03 dc-claim-day pic 99. 03 dc-claim-time occurs 6 times. 05 dc-claim-hour pic 9. 05 dc-claim-am-or-pm pic xxxx.
The total length of the DC-CLAIM-DATE element now is 8 * ((2 + 2 + 2) + (6 * (1 + 4))) = 288 bytes. To refer to the fourth DC-CLAIM-TIME element subordinate to the second DC-CLAIM-DATE element, the programmer can code DC-CLAIM-TIME(2,4) or DC-CLAIM-TIME(
subscript-1, subscript-2
), where
subscript-1
is an elementary item that contains the value 2 and
subscript-2
is an elementary item that contains the value 4.
Indexing a multiply-occurring element
In the following example, the DC-DENTIST-CHARGES element defines an index named DCX:
02 dentist-charges-0405 occurs 0 to 10 times depending on number-of-procedures-0405 indexed by dcx.
Associating comments with element descriptions
The following example illustrates the use of element comments in the COVERAGE record:
modify record name is coverage. 02 cov-select-date. 02 cov-select-year pic 99. 02 cov-select-month pic 99. 02 cov-select-day pic 99. 02 cov-termin-date. 02 cov-termin-year pic 99. 02 cov-termin-month pic 99. 02 cov-termin-day pic 99. 02 cov-type pic x. comments 'this is the type assigned to the coverage by - 'our company''s insurance professionals'. 02 cov-insplan-code pic xxx. comments 'this is the code assigned to the coverage by - 'the insurance company'.