Schema Statements › RECORD Statement › Usage

Usage

Effect of ADD On Records

ADD creates a new schema record description in the data dictionary and associates it with the current schema. The record is known as a schema record.

Unless the SHARE clause is used, ADD also creates a record structure for the schema record. The record structure's name is the same as that of the schema record. The structure is automatically assigned a version number, which distinguishes the record from others that have the same name in the dictionary. The schema compiler uses NEXT HIGHEST when assigning record version numbers.

Effect of MODIFY on records

MODIFY modifies an existing schema record in the dictionary. All clauses associated with an ADD operation can be specified for MODIFY operations.

Note: The CA IDMS IDD DDDL Reference Guide provides instruction for replacing record elements in schema-owned records under the RECORD entity type discussion. IDD can be used to include documentary information about the record or to modify record elements.

MODIFY operations that affect the record structure

MODIFY operations that use the SHARE clause or ELEMENT substatements affect the record structure. The following considerations apply to such MODIFY operations:

• The SHARE clause and the ELEMENT substatements disassociate the schema record from its existing structure, then associate the record with the specified structure. A schema record's structure is never modified.

  If the disassociated structure becomes unused as a result of the MODIFY operation, the schema compiler deletes the structure from the dictionary unless it is used in any of the following ways:

  • Participates in a map
  • Participates in another schema
  • Participates in a subschema logical record
  • Is owned by IDD

  The schema compiler assigns the version number of the unused record to the rebuilt record.

• The schema compiler associates the new record structure with the source of all subschemas that use the record. Subschema load modules, however, must be updated explicitly with a schema REGENERATE or subschema GENERATE statement.

  Note: When a MODIFY operation affects the structure of an existing record, the schema compiler attempts to recreate all partial views of the record, in addition to full views. Subschema views are recreated without view IDs. When a MODIFY operation affects a record used as a logical record element, the logical record must be modified (through the subschema compiler) before the subschema load module can be generated.

Effect of DELETE on records

DELETE operations cause the schema compiler to:

• Remove the named record from both the current schema and the schema's associated subschema descriptions.
• If the DELETE operation causes the record structure to become unused (as described above), delete that structure from the dictionary.
• Delete all sets that the record owns, thus removing such sets from both the current schema and the schema's associated subschema descriptions.
• Remove set membership specifications for all sets in which the record is a member. To delete such a set (if it has no other member records), use the DELETE SET statement.

Defaults supplied on an ADD RECORD statement

The schema compiler defaults supply the following information:

• Record ID is automatically assigned by the compiler
• Record fragmentation (variable-length records only) defaults to a minimum root length of CONTROL LENGTH and to a minimum fragment length of four bytes

Schema record must have at least one element

Every valid schema record must have at least one element (defined in an element substatement) associated with it.

Name records with conventions of programming language in mind

When naming schema records, 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 records should bear names that coincide with the language used most often; define record synonyms to accommodate other languages. In addition to the record naming rules stated above, consider the following points when selecting names (or synonyms) for schema records:

• 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 record description, it uses the record name as the DC or DSECT name. If the record name exceeds eight bytes in length, IDMSDMLA truncates it, possibly causing duplicate names to appear in the program.
• COBOL names must not contain the characters #, $, or @.
• PL/I naming conventions coincide with valid CA IDMS/DB schema record names. When the PL/I DML precompiler (IDMSDMLP) generates data field declarations from schema record descriptions, it automatically changes hyphens in the record names to underscores.

Record name for SQL access

If using SQL to access a non-SQL defined database, each record in the non-SQL schema is accessed as a table. The name of the table is always the schema record name (i.e., the object of an ADD RECORD statement). A record synonym for language SQL, if defined, is not used as the SQL table name although element synonyms for language SQL are used as column names.

Only one record synonym for language SQL may be defined for a record.

Note: For more information, see the CA IDMS SQL Reference Guide.

Considerations for using record synonyms

Record synonyms are language-dependent: each DML precompiler automatically includes the synonym, if any, associated with the compiler-specific programming language (unless instructed otherwise, through a manual COPY or INCLUDE statement).

The following considerations apply when using record synonyms:

• Internally, the schema compiler uniquely identifies record synonyms by assigning version numbers to them.
• The subschema compiler can use any record synonym assigned to a schema record type.
• Record names and synonyms must be unique within a schema. If different schema records have identical synonyms (with different version numbers) in the dictionary, only one such record synonym can be copied into a given schema. Subschemas are independent of this restriction.
• Only one record synonym with a language of SQL may exist for a record. This synonym is used when you use SQL to access a non-SQL defined database.
• If a synonym of a schema record is associated with the language of a program being precompiled, the precompiler copies that synonym instead of the schema's primary record (unless instructed otherwise, through a manual COPY or INCLUDE statement).
• If the record copied into a program by a DML precompiler is a synonym of a schema record, the DML precompiler treats the synonym as if it were the schema record (for example, in the BIND statement).

When to use area page counts

Use area page counts (for example, the OFFSET page-count clause) under these conditions:

• For records accessed by an area sweep (for example, DIRECT records)
• To exclude an area's SMP page (if the area has only 1), from the CALC algorithm

Differences between SHARE STRUCTURE/DESCRIPTION clauses

Both SHARE STRUCTURE and SHARE DESCRIPTION cause the schema record to share the structure of an existing record. The differences between the two are:

• SHARE DESCRIPTION shares the structure of another schema record; SHARE STRUCTURE shares the structure of either a dictionary record (IDD record) or another schema record.
• SHARE DESCRIPTION additionally copies the nonstructural part of the existing schema record; SHARE STRUCTURE does not. The nonstructural part is the record ID, location mode, VSAM type, area, minimum root length, minimum fragment length, and database procedures associated with the schema record.

SHARE DESCRIPTION must appear first

SHARE DESCRIPTION must be the first clause in the ADD or MODIFY RECORD statement. Any clauses that follow SHARE DESCRIPTION are applied to the record description as modifications. Thus, the DBA can share the description of a record that is similar to the one needed, and code only those clauses that represent differences between the two records. For this usage, select as shared-record-name a record whose structure is identical to that needed: while the descriptive part of the record can be changed directly, the structural part cannot.

Percentage offsets provide most flexibility

Of the page limiting options, OFFSET with percentage specifications is the most flexible. As a database grows and must eventually be expanded, the physical areas of the database must also be expanded. If the DBA originally expresses a record type's page range as a percentage of a physical area, the schema compiler "remembers" the percentage. Consequently, when the physical area is later expanded, the DBA need not respecify the record's page range; the schema compiler will automatically assign the record type to the appropriate percentage of the new physical area.

MINIMUM ROOT/FRAGMENT clauses can apply to fixed-length records

The MINIMUM ROOT LENGTH and MINIMUM FRAGMENT LENGTH clauses also apply to fixed-length records if those records are being processed by the compression (IDMSCOMP) and decompression (IDMSDCOM) procedures or IDMS/Presspack. The schema compiler automatically generates these clauses in response to a PROCEDURE NAME or DCTABLE NAME clause.

The MINIMUM ROOT LENGTH and MINIMUM FRAGMENT LENGTH clauses are allowable, but not functional, for native VSAM records.

Storing variable-length records

CA IDMS/DB never stores a variable-length record on a page unless sufficient space exists for the minimum root, and it never stores fragments smaller than the specified minimum, except for the last fragment. If MINIMUM ROOT LENGTH IS RECORD LENGTH is specified and a record occurrence is larger than page size minus 40, CA IDMS/DB returns an error-status code of 1211 (on a STORE) or 0811 (on a MODIFY). The same is true if MINIMUM FRAGMENT LENGTH IS RECORD LENGTH is specified and a record fragment is larger than page size minus 40.

Modifying the record size can cause fragmentation

Increasing the size of the record occurrence with a runtime MODIFY operation can necessitate fragmentation even though fragmentation was not specified in the schema. For example, if MINIMUM ROOT LENGTH IS RECORD LENGTH, CA IDMS/DB stores the current length of the record without fragmentation. However, if a record occurrence is later modified to a length that exceeds available page space, it may be fragmented at that time. Similarly, if MINIMUM FRAGMENT LENGTH IS RECORD LENGTH is specified, no occurrence of the record is fragmented more than once (root plus 1 fragment) upon storage, but an occurrence can be further fragmented if its length is increased as a result of modification.

Considerations for variable-length/-compressed records

For variable and variable-compressed record types, both the MINIMUM ROOT LENGTH and MINIMUM FRAGMENT LENGTH clauses can be omitted and the defaults taken; CA IDMS/DB recognizes the record as variable from the OCCURS DEPENDING ON clause in a record element description (see 14.5, “Element Substatement”).

Note: For documentation purposes, the best practice is to always include both the MINIMUM ROOT LENGTH and MINIMUM FRAGMENT LENGTH clauses in the description of all variable-length records if you specify CALL statements for record compression and decompression.

Considerations for fixed-compressed record types

For fixed-compressed record types, MINIMUM ROOT LENGTH IS CONTROL LENGTH must be specified explicitly if you use CALL statements to specify IDMSCOMP and IDMSDCOM for compression and decompression. This will ensure the proper result from the IDMSCOMP and IDMSDCOM procedures. If neither of the two clauses is specified, the compression procedures will compress data; however, the record will consume its full, fixed length in storage.

MINIMUM ROOT and MINIMUM FRAGMENT examples

EXAMPLE 1:                   CALC and sort control items
                             │    │
                             ▼    ▼
ADD RECORD NAME IS SKILL     ┌─┬────┬────────────────────────────┐
  LOCATION MODE IS CALC      └─┴────┴────────────────────────────┘ Total record
     USING SKILL-CODE                      ┌─┐ ┌─────────────┐     length:
  DUPLICATES NOT ALLOWED                   └─┘ └─────────────┘     76 bytes
  WITHIN ORG-DEMO-REGION AREA               ▲         ▲
  MINIMUM ROOT LENGTH IS CONTROL LENGTH     │         │
  MINIMUM FRAGMENT LENGTH IS RECORD LENGTH. │         │
                                      ┌─────┘         │
                                      │               │
                                   Minimum root     Minimum fragment


 
                                         Total record length: 900 bytes
 EXAMPLE 2:                        ┌───────────────────────────────────────────┐
                                   └───────────────────────────────────────────┘
                                   ┌──────────────┐ ┌─────────────┐ ┌──────────┐
 ADD RECORD NAME IS DENTAL-CLAIM   └──────────────┘ └─────────────┘ └──────────┘
    LOCATION MODE IS VIA           ┌──────────────┐ ┌─────────────┐ ┌──────────┐
      COVERAGE-CLAIMS SET          └──────────────┘ └─────────────┘ └──────────┘
    WITHIN INS-DEMO-REGION AREA    ┌──────────────┐ ┌─────────────┐ ┌──────────┐
    MINIMUM ROOT LENGTH IS 0       └──────────────┘ └─────────────┘ └──────────┘
    MINIMUM FRAGMENT LENGTH IS 80. ┌──────────────┐ ┌─────────────┐ ┌───┐
                                   └──────────────┘ └─────────────┘ └───┘
                                                     Minimum fragments

Minimum root and fragment lengths assigned to compressed records

The schema compiler assigns the following minimum root and fragment lengths to the record definition when it processes a DCTABLE clause or a PROCEDURE NAME clause:

• MINIMUM ROOT LENGTH IS CONTROL LENGTH
• MINIMUM FRAGMENT LENGTH IS 4 for variable compressed records
• MINIMUM FRAGMENT LENGTH IS the lesser of 40 and (record-length - control-length) for fixed compressed records

You can override the defaults by explicitly coding the MINIMUM ROOT and MINIMUM FRAGMENT clauses.

Respecify procedure statements if procedure is updated/deleted

If you want to add, modify, or delete a DCT, a standard compression or decompression procedure or other CALL procedures for a record, all DCTABLE, PROCEDURE, and CALL clauses must be respecified when you modify the record.

Area procedures needed for IDMSCOMP compression

If any record in the area uses IDMSCOMP and IDMSDCOM for compression and decompression, the area should have the following database procedure specifications:

CALL IDMSCOMP BEFORE FINISH.
CALL IDMSCOMP BEFORE ROLLBACK.
CALL IDMSDCOM BEFORE FINISH.
CALL IDMSDCOM BEFORE ROLLBACK.

This ensures that the work areas used by the compression and decompression routines are freed when a rununit terminates.

Implied CALL statements generated by PROCEDURE NAME

The PROCEDURE NAME clause generates the equivalent of the following CALL statements, depending on whether the clause specifies COMPRESSION or DECOMPRESSION:

Code as many CALL clauses as necessary

Any number of CALL clauses for as many DML functions as necessary can be specified for a record, as shown in the following example. If more than one BEFORE, AFTER, or ERROR procedure is specified for the same function, the procedures are executed in the order specified.

add record name is insurance-plan
    location mode is calc using code
        duplicates are not allowed
    within area ins-demo-region
    call inrecs after get
    call error-check after get.