Schema Statements › Element Substatement › Usage

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's 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.
• (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:

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 ────────────────────────────────────►◄
   └─ - ─┘              └─ - ─┘

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.

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.

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
• 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:

1. Numeric edited includes any element whose usage is DISPLAY and:

• 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 will be 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.