Schema Statements

This section describes SCHEMA statements. Syntax, parameter descriptions, usage information, and examples are presented for each statement. Statements are presented in the order in which you use them when you are defining a schema.
idms19
This section describes SCHEMA statements. Syntax, parameter descriptions, usage information, and examples are presented for each statement. Statements are presented in the order in which you use them when you are defining a schema.
2
2
The SCHEMA statements identify the schema as a whole, and establish schema currency. In addition, SCHEMA statements can:
  • Add, modify, delete, display, or punch a schema description
  • Establish security for the schema
  • Authorize users to issue specific verbs against the schema
Syntax order
ADD/MODIFY syntax is presented first, followed by DELETE syntax. DISPLAY/PUNCH syntax is presented last.
Expansion variables
Diagrams for expansion variables (indicated by underscore and italics) are shown at the end of the current syntax diagram. Expansions for common clauses are handled in a separate section, and those expansions are referenced in the parameter description.  
Syntax
Syntax: ADD/MODIFY SCHEMA statement
►►─┬─ ADD ────┬─ SCHema name is schema-name ──────────────────────────────────►    └─ MODify ─┘    ►─┬─────────────────────────────────────────┬────────────────────────────────►    └─ Version is ─┬─ version-number ───────┬─┘                   ├─ NEXt ─┬─ HIGhest ◄──┬─┤                   │        └─ LOWest ────┘ │                   ├─ HIGhest ──────────────┤                   └─ LOWest ───────────────┘  ►─┬─────────────────────────┬────────────────────────────────────────────────►    └─ user-specification ────┘    ►─┬──────────────────────────────────────────┬───────────────────────────────►    └─ schema DEScription is description-text ─┘    ►─┬─────────────────────────┬────────────────────────────────────────────────►    └─ MEMo DATe is mm/dd/yy ─┘    ►─┬─────────────────────────────────────────────────┬────────────────────────►    └─ ASSign RECord IDS from ─┬─ 1001 ◄────────────┬─┘                               └─ record-id-number ─┘  ►─┬────────────────────────────────────────────────────────────────────────┬─►    └─ DERived from SCHema is ─┬─ old-schema-name ┬───────────────────────┬─┬┘                               │                  └ version-specification ┘ │                               └─ NULl ◄────────────────────────────────────┘    ►─┬───────────────────────────────────────────────────────────────────────┬──►    │ ┌───────────────────────────────────────────────────────────────────┐ │    └─▼─┬─ INClude ◄──┬─ USEr is user-id ─┬──────────────────────────────┬┴─┘        └─ EXClude ───┘                   └─ user-options-specification ─┘    ►─┬──────────────────────────────────────────────┬───────────────────────────►    └─ PUBlic ACCess is allowed for ─┬─ DELete ──┬─┘                                     ├─ DISplay ─┤                                     ├─ MODify ──┤                                     ├─ UPDate ──┤                                     ├─ ALL ◄────┤                                     └─ NONe ────┘  ►─┬────────────────────────────────────────────────────────────────────────┬─►    │ ┌────────────────────────────────────────────────────────────────────┐ │    └─▼─┬─────────────┬─ class-name is attribute-name ┬───────────────────┬┴─┘        ├─ INClude ◄──┤                               └ TEXT is user-text ┘        └─ EXClude ───┘    ►─┬──────────────────────────────────────────────────────────────────────────►    │  ┌───────────────────────────────────────────────────────────────────────    └──▼─┬─────────────┬─ USER DEFINED COMMENT is comment-key ─────────────────         ├─ INClude ◄──┤         └─ EXClude ───┘ ─►────────────────────────────┬───────────────────────────────────────────────►   ──────────────────────────┐ │   ──┬─────────────────────┬─┴─┘     └─ TEXt is user-text ─┘    ►─┬───────────────────────────────────────┬──────────────────────────────────►◄    └─┬─ COMments ────┬──┬─ comment-text ─┬─┘      └─ comment-key ─┘  └─ NULl ─────────┘
Syntax: DELETE SCHEMA
►►─── DELete SCHema name is schema-name ─┬─────────────────────────┬──────────►                                          └─ version-specification ─┘    ►─┬──────────────────────┬───────────────────────────────────────────────────►◄    └─ user-specification ─┘
Syntax: DISPLAY/PUNCH SCHEMA
►►─┬─ DISplay ─┬─ SCHema name is schema-name ─────────────────────────────────►    └─ PUNch ───┘    ►─┬─────────────────────────┬────────────────────────────────────────────────►    └─ version-specification ─┘    ►─┬──────────────────────────────────────────────────┬───────────────────────►    └─ PREpared by user-id ─┬────────────────────────┬─┘                            └─ PASsword is password ─┘  ►─┬─────────────────────────────────────────────────┬────────────────────────►    │ ┌─────────────────────────────────────────────┐ │    │ │                 ┌─────────────────────────┐ │ │    └─▼─┬─ WITh ──────┬─▼─┬─ ALL COMment TYPes ─┬─┴─┴─┘        ├─ ALSo WITh ─┤   ├─ AREas ─────────────┤        └─ WITHOut ───┘   ├─ ATTributes ────────┤                          ├─ COMments ──────────┤                          ├─ CULprit headers ───┤                          ├─ DETails ───────────┤                          ├─ ELements ──────────┤                          ├─ HIStory ───────────┤                          ├─ OLQ headers ───────┤                          ├─ RECords ───────────┤                          ├─ SCHemas ───────────┤                          ├─ SETs ──────────────┤                          ├─ SHAred structures ─┤                          ├─ SUBSChemas ────────┤                          ├─ SYNonyms ──────────┤                          ├─ USErs ─────────────┤                          ├─ ALL ───────────────┤                          └─ NONe ──────────────┘  ►─┬──────────────────────┬───────────────────────────────────────────────────►    └─ VERB ─┬─ ADD ─────┬─┘             ├─ MODify ──┤             ├─ DELete ──┤             ├─ DISplay ─┤             └─ PUNch ───┘    ►─┬─────────────────────┬────────────────────────────────────────────────────►    └─ AS ─┬─ COMments ─┬─┘           └─ SYNtax ───┘    ►─┬─────────────────────────────────────┬────────────────────────────────────►◄    └─ TO ─┬─ module-specification ────┬──┘           └─ SYSpch ──────────────────┘
Parameters
 
  • SCHema name is 
    schema-name
    Identifies the schema. 
    Schema-name
     must be a 1- to 8-character value. 
    Schema-name
     must not be the same as any components or synonyms within the schema.
  • Version is
    Qualifies the schema with a version number, which distinguishes this schema from others that have the same name. 
    Version-number
     specifies an explicit version number and must be an unsigned integer in the range 1 through 9999. On an ADD operation, the default is the session default for new versions; on other operations, the default is the session default for existing versions.
    • NEXt HIGhest
      On an ADD operation, specifies the highest version number assigned to 
      schema-name
       plus 1. For example, if versions 3, 5, and 8 of schema CULSCHEM exist in the dictionary, NEXT HIGHEST would define in version 9 of CULSCHEM.
    • NEXt LOWest
      On an ADD operation, specifies the lowest version number assigned to 
      schema-name
       minus 1. For example, if versions 3, 5, and 8 of schema CULSCHEM exist in the dictionary, NEXT LOWEST would define version 2 of CULSCHEM.
    • HIGhest
      On MODIFY and DELETE operations, specifies the highest version number assigned to 
      schema-name
      . For example, if versions 2, 7, and 11 of schema SOFSCHEM exist in the dictionary, HIGHEST would indicate version 11 of SOFSCHM.
    • LOWest
      On MODIFY and DELETE operations, specifies the lowest version number assigned to 
      schema-name
      . For example, if versions 2, 7, and 11 of schema SOFSCHEM exist in the dictionary, LOWEST would indicate version 2 of SOFSCHM.
  • user-specification
    Identifies the user accessing the schema description. If SIGNON OVERRIDE is not allowed, 
    user-specification
     is ignored and the user id identified as the user known to the runtime environment.
    Expanded syntax for
    user-specification
    is presented in Section13, "Parameter Expansions”.
  • schema DEScription is 
    description-text
    Optionally specifies a name that is more descriptive than the 8-character schema name required by CA IDMS/DB, but can be used to store 
    any
     type of information. This clause is purely documentational. 
    Description-text
     is a 1- to 40-character alphanumeric field; if it contains spaces or delimiters, it must be enclosed in site-standard quotes.
  • MEMo DATe is 
    mm/dd/yy
    Specifies any date the user wishes to supply; it is purely documentational. Note that the time and date of schema creation and last revision are maintained automatically, apart from MEMO DATE, by the schema compiler.
  • ASSign RECord IDS from 
    record-id-number
    Specifies the number that the schema compiler will use as a base for numbering schema records. 
    Record-id-number
     must be an unsigned integer in the range 10 through 9999; it defaults to 1001. 
    Record-id-number
     is assigned to the first record in the schema that specifies RECORD ID IS AUTO. the compiler assigns 
    record-id-number
     to that record.
    For more information on assigning IDs for subsequent records, see the description of RECORD ID IS AUTO under 14.4, “RECORD Statement”.
  • DERived from SCHema is 
    old-schema-name
    Associates the current schema with another schema (
    old-schema-name
    ). This clause is purely informational.
  • DERived from SCHema is NULl
    Dissolves such an association between the current schema and another. It is purely documentational.
  • INClude USEr is 
    user-id
    Associates a user with the schema description. 
    User-id
     must be the name of a user as defined in the dictionary.
  • user-options-specification
    Specifies options available to a user associated with the schema.
    Expanded syntax for
    user-options-specification
    is presented in Section13, "Parameter Expansions”.
  • EXClude USEr is 
    user-id
    Disassociates a user from the current schema. 
    User-id
     must be the ID of a user as defined in the dictionary.
  • PUBlic ACCess is allowed for
    For the current schema and its components, specifies which operations are available for public access (that is, to all users who can sign on to the schema compiler). When coded, the keyword ALLOWED can be abbreviated to no fewer than 4 characters (ALLO).
  • DELete
    Allows all users to DELETE, DISPLAY, and PUNCH the schema and its components.
  • DISplay
    Allows all users to DISPLAY and PUNCH the schema and its components.
  • MODify
    Allows all users to MODIFY, DISPLAY, and PUNCH the schema and its components.
  • UPDate
    Allows all users to ADD, MODIFY, DELETE, DISPLAY, and PUNCH the schema and its components. Unlike ALL, UPDATE does not allow users to change the schema's PUBLIC ACCESS specification.
  • ALL
    Allows all users to ADD, MODIFY, DELETE, DISPLAY, and PUNCH the schema and its components. Additionally, ALL allows users to change the schema's PUBLIC ACCESS specification, thus enabling them to change security for the schema. ALL is the default.
  • NONe
    Prohibits all users, except those explicitly associated with the schema, from accessing it in any way.
  • INClude 
    class-name
     is 
    attribute-name
    Classifies the schema for documentational purposes by associating an attribute with the schema. INCLUDE is the default.
    Class-name
     must be the name of a class as defined in the dictionary through the IDD DDDL compiler. If the dictionary entry for the class specifies that attributes must be added manually, 
    attribute-name
     must be the name of an attribute already associated with 
    class-name
    ; if not, 
    attribute-name
     can be any 1- to 40-character value, enclosed in site-standard quotes if it contains spaces or delimiters.
    See the
    CA IDMS IDD DDDL Reference section
    for instruction in defining classes and attributes.
  • TEXT is 
    user-text
    Supplies additional documentation of the assignment of a specific attribute to the schema. 
    User-text
     is 1 to 40 characters of text; if it contains spaces or delimiters, it must be enclosed in site-standard quotes.
  • EXClude 
    class-name
     is 
    attribute-name
    Disassociates an attribute from the schema. 
    Class-name
     must be the name of a class for which an attribute is already associated with the schema; 
    attribute-name
     names the attribute to be disassociated from the schema.
  • INClude/EXClude USER DEFINED COMMENT is 
    comment-key
    Identifies a type of comment to be associated with (INCLUDE) or disassociated from (EXCLUDE) the schema. INCLUDE is the default. 
    Comment-key
     must identify an existing user-defined comment type. Values that contain embedded blanks or special characters or that duplicate a keyword from the DDL syntax must be enclosed in site-standard quote characters. Comment text is assigned to the 
    comment-key
     using the COMMENTS clause.
  • COMments/
    comment-key
     is 
    comment-text
    /NULl
    Updates or removes schema comments. 
    Comment-key
     is the value assigned in the USER DEFINED COMMENTS clause of the IDD DDDL MODIFY ENTITY statement. NULl removes comment text from the current schema.
    Coding rules for
    comment-text
    are presented in 10.5.4, “Coding Comment Text”.
  • ALL COMment TYPes
    Displays and punches all information from the categories COMMENTS, CULPRIT HEADERS, and OLQ HEADERS.
  • AREas
    Displays and punches all areas in the schema.
  • ATTributes
    Displays and punches all attributes, and their respective classes, associated with the schema.
  • COMments
    Displays and punches all comments associated with the schema through the COMMENTS clause of the ADD or MODIFY SCHEMA statement; when RECORDS and ELEMENTS are also specified, all COMMENTS associated with the record elements.
  • CULprit headers
    When RECORDS and ELEMENTS are also specified, displays and punches all CULPRIT HEADERS specified for the record elements.
  • DETails
    Displays and punches information specified previously in the following clauses:
    • SCHEMA DESCRIPTION
    • MEMO DATE
    • ASSIGN RECORD IDS FROM
    • PUBLIC ACCESS
  • ELements
    When RECORDS is also specified, displays and punches all elements contained within the records.
  • HIStory
    Displays and punches creation and revision information:
    • Creation -- The date and time the schema was added to the dictionary and the user who added it (also known as the prepared-by user)
    • Revision -- The date and time the schema was last modified and the user who modified it (also known as the revised-by user)
  • OLQ headers
    When RECORDS and ELEMENTS are also specified, displays and punches all OLQ HEADERS specified for the record elements.
  • RECords
    Displays and punches all records in the schema, without their associated elements.
  • SCHemas
    Displays and punches the schema associated with the current schema through the DERIVED FROM SCHEMA clause.
  • SETs
    Displays and punches all sets in the schema.
  • SHAred structures
    When RECORDS and DETAILS are also specified, WITH SHARED STRUCTURES displays the SHARE STRUCTURE clause of the record definition as syntax, and the record's elements as comments. WITHOUT SHARED STRUCTURES displays a clause, USES STRUCTURE OF RECORD, as comments, and the record's elements as syntax.
  • SUBSChemas
    Displays and punches all subschemas associated with the schema.
  • SYNonyms
    When RECORDS is also specified, displays and punches the record synonyms associated with the schema; when RECORDS and ELEMENTS are also specified, displays and punches the record and element synonyms associated with the schema.
  • USErs
    Displays and punches all users associated with the schema.
  • ALL
    Displays and punches the entire schema description.
  • NONe
    Displays and punches only the schema name and version number.
Usage
Effect of ADD on Schema
ADD creates a new schema description in the dictionary. Default values established through the SET OPTIONS statement can be used to supplement the user-supplied description.
ADD also sets the schema's status to IN ERROR. A VALIDATE statement must set the status to VALID before a subschema or CA IDMS/DB utility can reference the schema.
Effect of MODIFY on Schema
MODIFY modifies an existing schema description in the data dictionary. This verb also sets the schema's status to IN ERROR. A VALIDATE statement must set the status to VALID before a subschema or CA IDMS/DB utility can reference the schema.
Effect of DELETE on Schema
DELETE deletes an existing schema description and its associated subschema descriptions from the dictionary.
If the SET OPTIONS statement specifies DELETE IS ON, the schema compiler also:
  • Logically deletes version 1 of all subschema load modules associated with the schema from the load area of the dictionary (load modules qualified by another version number must be explicitly deleted).
  • Automatically erases version 1 of any PROG-051 dictionary record occurrence associated with the subschema load module, provided the record was built by the subschema compiler and is not related to any other entity type in the dictionary.
SCHEMA statement defaults
The schema compiler defaults to supply this information on the schema:
  • Version-number
     defaults to the current session option for new versions.
  • The record ID assignment begins with 1001.
ADD interpreted as MODIFY
If, on an ADD operation, a schema of the same name and version already exists in the dictionary, the action taken by the schema compiler varies depending on the session option for DEFAULT:
  • If DEFAULT IS ON
     was specified, the schema compiler interprets the ADD as a MODIFY for the named schema.
  • If DEFAULT IS OFF
     was specified, the schema compiler issues an error message and terminates processing of the ADD SCHEMA statement. Note that, in this case, schema currency will be null for subsequent statements.
Security enforcement
If either authority for SCHEMA is on or the schema being operated on is secured in the dictionary, the user issuing the schema statement must hold the necessary authority to perform the operation. The user issuing the statement is established by:
  • user-specification
     in the SCHEMA statement
  • user-specification
     in the SET OPTIONS statement
  • The user identified in a compiler SIGNON statement
  • The user known to the runtime environment in which the compiler is executing
If SIGNON OVERRIDE is not allowed, the user is always the one known to the runtime environment.
USER DEFINED COMMENTS clause
To associate a user-defined comment with a schema:
  1. Specify a 
    comment-key
     in the USER DEFINED COMMENTS clause
  2. Associate 
    comment-text
     with the key in the COMMENTS clause
If a COMMENTS clause appears in a MODIFY statement, the compiler edits or removes existing comment text.
To remove user-defined comments:
  1. Specify NULL in a COMMENTS clause
  2. Specify EXCLUDE in a USER DEFINED COMMENTS clause
Use DISPLAY ALL to list all schema names
To list the names of all schemas, issue a DISPLAY ALL statement.
Examples
Minimum SCHEMA statement
The following example supplies the minimum SCHEMA statement required for the purpose of later establishing a functional database:
add schema name is sampschm.
Using the TEXT clause to document schema revisions
In the following example, the DBA documents schema revisions and the purposes for those revisions; note that the DBA first defined REVISION NUMBER as a class in the dictionary with auto attributes.
modify schema name is culschem  version 6     revision number is '6.5'         text is 'accommodate new billing procedures'.
For more information on the DISPLAY ALL statement, see Section11, “Compiler-Directive Statements".