DML Precompiler-Directive Statements › @COPY IDMS

@COPY IDMS

The @COPY IDMS statement copies source data description code and modules from the dictionary into the program at the location of the @COPY IDMS statement. This statement copies CA IDMS/DB database record descriptions, the IDMS communications block, map record descriptions, or MRBs. However, any source module or record description stored in the dictionary can be copied into either a CSECT or DSECT, as specified by the DSECT parameter (discussed below).

Source code requirements differ according to the usage (DML, LR, or MIXED) defined in the program's subschema. The program should not copy components that conflict with its usage. These usages determine the types of records a program can access, as follows:

• DML allows a program that uses the named subschema to access database records only and requires the following source code components:
  • SUBSCHEMA-CTRL— The IDMS communications block through which the application program and the DBMS communicate (for further details, see IDMS Communications Block)
  • SUBSCHEMA-RECORDS— The descriptions of all records to which the subschema permits access
• LR allows a program to access logical records only and requires the following source code components
  • SUBSCHEMA-CTRL— The IDMS communications block through which the LRF and the DBMS communicate
  • SUBSCHEMA-LR-CTRL— The logical-record request control (LRC) block through which the application program and the Logical Record Facility communicate (for further details, see Logical-Record Request Control (LRC) Block)
  • SUBSCHEMA-LR-RECORDS— The descriptions of all logical records defined in the subschema
• MIXED allows a program to access both database records and logical records; this usage requires the following source code components:
  • SUBSCHEMA-CTRL— The IDMS communications block through which the application program and the LRF communicates with the DBMS, For further details, see IDMS Communications Block.
  • SUBSCHEMA-RECORDS— The descriptions of all records to which the subschema permits access
  • SUBSCHEMA-LR-CTRL— The logical-record request control (LRC) block, through which the application program and the LRF communicate (for further details, see Logical-Record Request Control (LRC) Block)
  • SUBSCHEMA-LR-RECORDS— The descriptions of all logical records defined in the subschema

The DML precompiler determines whether source record descriptions are copied into a CSECT or DSECT portion of the program, and applies the following rules:

• If the record is being copied into a CSECT, the DML precompiler defines record elements that have specified initial values by means of the Assembler DC (define constant) data definition instruction.
• If the record is being copied into a DSECT, DML defines record elements that have specified initial values by means of the Assembler DS (Define Storage) data definition instruction.

Note: The DML defines record elements using the Assembler EQU instruction if the record element is:

• created in the dictionary (IDD) with the USAGE CONDITION-NAME parameter (according to the COBOL 88-level convention)

  and

• copied into a CSECT or DSECT.

Note: If the optional keyword DSECT is coded in the @COPY IDMS statement, the record being copied is established as an individual DSECT named with the record name.

Syntax

►►─── @COPY IDMS ─────────────────────────────────────────────────────────────►

 ►─┬─ ,SUBSCHEMA-DML-LR DESCRIPTION ───────────────────────┬──────────────────►
   ├─ ,SUBSCHEMA-DESCRIPTION ──────────────────────────────┤
   ├─ ,SUBSCHEMA-CTRL ─────────────────────────────────────┤
   ├─ ,SUBSCHEMA-RECORDS ──────────────────────────────────┤
   ├─ ,RECORD=record-name ─┬──────────────────────────┬────┤
   │                       └─ VERSION=version-number ─┘    │
   ├─ ,SUBSCHEMA-LR-DESCRIPTION ───────────────────────────┤
   ├─ ,SUBSCHEMA-LR-CTRL ─┬────────────────────────┬───────┤
   │                      └─ ,SIZE=lrc-block-size ─┘       │
   ├─ ,SUBSCHEMA-LR-CONTROL ───────────────────────────────┤
   ├─ ,SUBSCHEMA-LR-RECORDS ───────────────────────────────┤
   ├─ ,LR=logical-record-name ─────────────────────────────┤
   ├─ ,MAPS ───────────────────────────────────────────────┤
   ├─ ,MAP=map-name ───────────────────────────────────────┤
   ├─ ,MAP-CONTROLS ───────────────────────────────────────┤
   ├─ ,MAP-CONTROL=map-name ───────────────────────────────┤
   ├─ ,MAP-RECORDS ────────────────────────────────────────┤
   ├─ ,MODULE=module-name ─┬──────────────────────────┬────┤
   │                       └─ VERSION=version-number ─┘    │
   ├─ ,SUBSCHEMA-BINDS ────────────────────────────────────┤
   └─ ,MAP-BINDS ──────────────────────────────────────────┘

 ►─┬──────────┬───────────────────────────────────────────────────────────────►◄
   └─ ,DSECT ─┘

Parameters

SUBSCHEMA-DML-LR-DESCRIPTION

(Subschema usage is mixed); copies all components required to access both database and logical records: SUBSCHEMA-CTRL, SUBSCHEMA-RECORDS, SUBSCHEMA-LR-CTRL, and SUBSCHEMA-LR-RECORDS.

SUBSCHEMA-DESCRIPTION

(Subschema usage is DML); copies the source data description code for the IDMS communications block (SUBSCHEMA-CTRL) and for all records (SUBSCHEMA-RECORDS) defined in the subschema specified in the @INVOKE statement.

SUBSCHEMA-CTRL

Copies the IDMS communications block into the program.

SUBSCHEMA-RECORDS

Copies the source data description code for all records defined in the subschema into the program. You can copy Assembler synonyms defined for the subschema records in the data dictionary into the program according to the rules of synonym usage.

RECORD=

Copies the description of an individual record defined in the dictionary.

record-name

Can be the primary name or a synonym for a record or module stored in the dictionary.

A record that has been copied into a schema can only be copied into a program that uses a subschema associated with the schema. In other words, schema-owned records cannot be copied into non-IDMS programs (that is, programs that do not use a subschema and that do not access the database). However, a synonym defined for the schema-owned record can be copied into a non-IDMS program (use the VERSION clause to identify the synonym).

VERSION=version-number

Optional; can be used to qualify IDD records (but not schema-owned records) with a version number. If no version number is specified, CA IDMS/DB first assumes that record-name identifies a record that is included in the subschema named in the @INVOKE statement, and looks for it in that subschema. If the record is not associated with a subschema, version defaults to the highest version number of the record defined in the dictionary for the operating mode under which the program is being compiled.

SUBSCHEMA-LR-DESCRIPTION

Copies all components required to access logical records: SUBSCHEMA-CTRL, SUBSCHEMA-LR-CTRL, and SUBSCHEMA-LR-RECORDS.

SUBSCHEMA-LR-CTRL

Copies the LRC block data description.

SIZE=lrc-block-size

Optional; specifies the size of that portion of the LRC block that contains information about the logical-record request's WHERE clause. Lrc-block-size defaults to 576 bytes. If included, it should specify a size large enough to accommodate the most complex WHERE clause in the program. Lrc-block-size is calculated as follows:

1. Multiply the greatest number of operands and operators that will be included in a single WHERE clause by 16 bytes.
2. Add the number of bytes, rounded up to the nearest multiple of 8, associated with the data field for each operand; that is:
   • The number of characters in a keyword
   • The number of characters in a field described by a program variable or by a logical-record field named in the OF LR clause.
3. Add the length, rounded up to the nearest multiple of 8, of each operand that is a character literal.
4. Add 12 bytes for each operand that is a numeric literal.
5. Add 64 bytes for fixed logical-record request control (LRC) overhead.

Lrc-block-size must be a positive integer in the range 64 through 9999. Note that 64 can be specified if none of the logical-record requests issued by the program include WHERE clauses.

• SUBSCHEMA-LR-CONTROL copies the SUBSCHEMA-CTRL and SUBSCHEMA-LR-CTRL components. Do not include SUBSCHEMA-LR-CONTROL if the subschema's usage is DML.
• SUBSCHEMA-LR-RECORDS copies the descriptions of all logical records defined in the subschema.
• LR=logical-record-name copies the description of an individual logical record defined in the subschema.
• MAPS copies the #MRB statements required to establish the MRBs for all maps specified in the @INVOKE statement. Additionally, the @COPY IDMS,MAPS statement copies the source data description code for map records associated with all maps specified in the @INVOKE statement.
• MAP=map-name copies the #MRB statement and map records associated with the named map. Map-name is the 1- to 8-character name of the map. The version number of the map defaults to the version number specified for the map in the @INVOKE statement.
• MAP-CONTROLS copies the #MRB statements for all maps specified in the @INVOKE statement.
• MAP-CONTROL=map-name copies the #MRB statement for the named map. Map-name is the 1- to 8-character name of the requested map. The version number of the map defaults to the version number specified in the @INVOKE statement.
• MAP-RECORDS copies the map records associated with all maps specified in the @INVOKE statement.
• MODULE=module-name,VERSION=version copies a sequence of Assembler source statements stored in the dictionary. Module-name is the 1- to 8-character name of the requested module; it can be optionally qualified by version. The version number defaults to the highest version number defined in the dictionary for the requested module.

  The @COPY IDMS,MODULE statement copies a module from the dictionary into the source program. The DBA must have previously added this module to the data dictionary by means of the IDD DDDL compiler.

  The DML precompiler places the module into the program at the location of the request. The module may contain DML statements. If DML statements are present, they are treated as if the programmer had coded them directly. @COPY IDMS,MODULE statements can be nested (that is, code invoked by an @COPY IDMS,MODULE statement can itself contain a @COPY IDMS,MODULE statement). However, you must ensure that a copied module does not, in turn, copy itself.

• SUBSCHEMA-BINDS copies @BIND SUBSCH and @BIND REC statements for each CA IDMS/DB database record accessed by the program.

  The @COPY IDMS,SUBSCHEMA-BINDS statement instructs the precompiler to bring into the source program a standard @BIND SUBSCH statement and appropriate standard @BIND REC statements for each CA IDMS/DB subschema record explicitly copied into the program variable storage by means of @COPY IDMS statements. @COPY IDMS does not automatically generate BINDS for all subschema records; it also does not generate BINDS for logical records.

  All @COPY IDMS,RECORD statements must precede any @COPY IDMS,SUBSCHEMA-BINDS statement, because the DML precompiler is a one-pass precompiler. The DML precompiler will not generate BINDS for any record-type descriptions copied into the program after the @COPY IDMS,SUBSCHEMA-BINDS statement.

  Instead of issuing an @COPY IDMS,SUBSCHEMA-BINDS statement, you can issue @BIND SUBSCH and @BIND REC statements. Separately issued @BIND READY and @BIND REC statements allow the program to perform the following:

  • Check the ERRSTAT field after each @BIND REC statement
  • Bind several records to the same location by including a DML @BIND statement for each record (see @BIND REC)

  Note: The subschema registration feature requires the @COPY IDMS,SUBSCHEMA-BINDS statement to properly assign the programs to the subschema control block. Individual @BIND SUBSCH and @BIND REC statements should not be used if program registration is in effect.

  Note: If a record or a synonym of the record has been copied in twice, an @BIND REC statement will not be automatically generated for the record due to the ambiguity.

• MAP-BINDS copies appropriate #MAPBIND statements for all maps specified in the @INVOKE statement. (#MAPBIND statements are discussed later in this chapter.) The @COPY IDMS,MAPS statement must be coded before this statement in order to generate binds for the map records.
• DSECT copies the source data description code and source modules defined in any of the above @COPY IDMS statements into a DSECT. Records can be individually copied into a DSECT by including the DSECT parameter in each @COPY IDMS statement. Several records can be copied into a single DSECT by explicit use of the Assembler DSECT instruction followed by the individual @COPY IDMS statements; in this case, the DSECT parameter is not specified in the @COPY IDMS statements. When specifying a DSECT, the program is responsible for designating the end of the DSECT storage area.

The following example illustrates the use of the DSECT parameter to create individual dummy control sections for the IDMS communications block and for a map request block:

         @MODE MODE=IDMSDC
         @INVOKE SUBSCHEMA=XYZ,SCHEMA=ABC,
               PROGRAM=TESTXYZ,MAP=DEFMAP

*  THE FOLLOWING @COPY IDMS STATEMENT COPIES THE SOURCE DATA
*  DESCRIPTION CODE FOR THE IDMS COMMUNICATION BLOCK (SUBSCHEMA-CTRL):

         @COPY IDMS,SUBSCHEMA-CTRL,DSECT

*  THE DML PRECOMPILER GENERATES THE DSECT INSTRUCTION FOR THE DUMMY
*  CONTROL SECTION TO CONTAIN THE SOURCE DATA DESCRIPTION CODE OF THE
*  IDMS COMMUNICATIONS BLOCK:

         DSECT
SSCTRL   DS
         .
         .
         .

*  THE FOLLOWING @COPY IDMS STATEMENT COPIES THE SOURCE DATA
*  DESCRIPTION CODE FOR THE REQUIRED MAP REQUEST BLOCK (MAP-CONTROLS):

          @COPY IDMS,MAP-CONTROL=DEFMAP,DSECT

*  THE DML PRECOMPILER GENERATES THE DSECT INSTRUCTION FOR THE DUMMY
*  CONTROL SECTION TO CONTAIN THE SOURCE DATA DESCRIPTION CODE FOR
*  THE MRB:

         DSECT
         DS
         .
         .
         .

*  THE END OF EACH DSECT MUST BE DESIGNATED EITHER BY AN ASSEMBLER
*  END, CSECT, OR ANOTHER DSECT INSTRUCTION.

A single DSECT is created for the IDMS communications block, CA IDMS/DB record descriptions, MRB, and map record description.

         @MODE MODE=IDMSDC
         @INVOKE SUBSCHEMA=XYZ,SCHEMA=ABC,                             *
               PROGRAM=TESTXYZ,MAP=DEFMAP

*  THE FOLLOWING ASSEMBLER DSECT INSTRUCTION IS CODED BY THE
*  PROGRAMMER TO DEFINE THE BEGINNING OF A DUMMY CONTROL SECTION:

IDMSSTG  DSECT

*  COPY STATEMENTS WITHIN A DSECT ENABLE RECORD DESCRIPTIONS TO BE
*  COPIED INTO THE DUMMY CONTROL SECTION.  NOTE THAT THE DSECT
*  PARAMETER IS NOT INCLUDED IN THE @COPY IDMS STATEMENTS:

         @COPY IDMS,SUBSCHEMA-DESCRIPTION
SSCTRL   DS
         .
         .
         .
         DS
         .
         .
         @COPY IDMS,MAPS
         DS
         .
         .
         .
         DS
         .
         .
         .

*  THE END OF THE DSECT MUST BE DESIGNATED BY AN ASSEMBLER END,
*  CSECT, OR ANOTHER DSECT INSTRUCTION.