INCLUDE

The INCLUDE precompiler directive statement directs the precompiler to create host variable definitions for a specified structure or table in the application program. You can use this statement only in SQL that is embedded in a program.
idmscu19
The INCLUDE precompiler directive statement directs the precompiler to create host variable definitions for a specified structure or table in the application program. You can use this statement only in SQL that is embedded in a program.
The INCLUDE statement is a CA IDMS extension of the SQL standard.
This article describes the following information:
2
2
Authorization
To issue an INCLUDE statement that specifies:
  • A table, you must own or have the SELECT privilege on the table
  • SQLCA or SQLDA no privileges are required
Syntax
  ►►─── INCLUDE ─┬─ SQLCA ───────────────────────────────────────────────────┬──►◄                ├─ SQLDA 
sqlda-options
 ─────────────────────────────────────┤                ├─ TABLE 
table-name
 ─┬─────────────────┬────────────────────┤                │                    └─ 
table-options
 ─┘                    │                ├─┬────────────────┬─ 
function-identifier
 ─┬───────────────┬┤                │ └─ 
schema-name
. ─┘                       └─
table-options
─┘│                └─ 
module-name
 ─────────────────────────────────────────────┘  
Expansion of sqlda-options
  ►►─┬──────────────────────────────────┬─┬───────────────────────────┬─────────►◄    └─ NUMBER OF COLUMNS 
column-count
 ─┘ └─ AS 
descriptor-area-name
 ─┘  
Expansion of table-options
  ►►─┬────────────────────────────────────────────────────────────────┬─────────►    │     ┌─────── , ───────┐                                        │    └─ ( ─▼── 
column-name
 ──┴─ ) ──┬───────────────────────────────┬─┘                                   │        ┌─────── , ──────┐     │                                   └─ AS ( ─▼─ 
column-alias
 ─┴─ ) ─┘  ►─┬─────────────────────┬────────────────────────────────────────────────────►    ├─ AS 
structure-name
 ─┤    └─ NO STRUCTURE ──────┘  ►─┬────────────────────────────┬─────────────────────────────────────────────►    └─ NUMBER OF ROWS 
row-count
 ─┘  ►─┬──────────────────────────┬───────────────────────────────────────────────►    └─ PREFIX '
column-prefix
' ─┘  ►─┬──────────────────────────┬───────────────────────────────────────────────►    └─ SUFFIX '
column-suffix
' ─┘  ►─┬──────────────────────────┬───────────────────────────────────────────────►◄    └─ LEVEL  '
level-number 
' ─┘  
Parameters
  • SQLCA
    Directs the precompiler to define host variables for the fields in the SQL Communication Area (SQLCA) in the application program.
  • SQLDA
    Directs the precompiler to define host variables for the fields in the SQL descriptor area in the application program.
  • sqlda-options
    Specifies additional characteristics for the SQL descriptor area. Expanded syntax for
    sqlda-options
    is shown immediately following the INCLUDE syntax and documented directly below.
  • NUMBER OF COLUMNS
    column-count
    Directs CA IDMS to build an SQL descriptor area large enough to contain the specified number of columns.
    Column-count
    must be an integer in the range 1 through 1,024. The default is 100.
  • AS
    descriptor-area-name
    Assigns the specified name to the SQL descriptor area being defined.
    Descriptor-area-name
    must be unique within the application program and must follow the conventions for host variable names.
    If you do not specify a name for the SQL descriptor area, the name of the descriptor area is SQLDA.
  • TABLE table-name
    Directs the precompiler to define host variables corresponding to one or more columns in the named table, view, procedure or table procedure in the application program.
    Table-name
    must identify a base table, view, procedure or table procedure defined in the dictionary.
    If
    table-name
    does not include an explicit schema name, the precompiler:
    • Uses the schema name specified in the schema precompiler option, if any
    • Returns an error if the schema precompiler option is not specified
    For expanded
    table-name
    syntax, see Expansion of Table-name.
  • schema-name
    Specifies the schema with which the function identified by function-identifier is associated. If schema-name is not specified, the precompiler:
    • Uses the schema name specified in the schema precompiler option, if any
    • Returns an error if the schema precompiler option is not specified
  • function-identifier
    Directs the precompiler to define host variables corresponding to one or more columns in the named function in the application program.
  • table-options
    Specifies additional information about the host variables to be defined for the named table, view, function, procedure, or table procedure. Expanded syntax for
    table-options
    is shown above immediately following the expanded syntax for
    sqlda-options
    and documented directly below.
  • module-name
    Includes source statements from a module stored in the data dictionary into the source program.
    The unmodified module is placed into the program by the precompiler at the location of the request. The module can, but need not, contain SQL or navigational DML statements. Any such statements are examined and expanded within the context of the program as if they were coded directly.
    INCLUDE
    module-name
    is equivalent to COPY IDMS
    module-name
    as documented in the Precompiler-Directive Statements section for COBOL application programs and the DML Precompiler-Directive Statements section for Assembler application programs.
    The version of the module that is included is established as follows:
    The version defaults to the highest version number defined in the data dictionary for the language mode under which the program is being compiled (for example, BATCH or IDMS-DC).
    If no mode-specific version exists for
    module-name
    , the non-mode-specific version, if present, is included. If neither a mode-specific entry or a non-mode-specific entry for
    module-name
    has been established, an error results. The same rules apply to the module's language where
    version-number
    defaults to the highest value defined in the data dictionary for the language in which the program is written.
Parameters for Expansion of sqlda-options
  • (
    column-name
    )
    Specifies one or more columns for which the precompiler is to define host variables.
    Column-name
    must identify a column in the named table, view, function, procedure, or table procedure and must be unique within the list of column names.
    If you specify one or more columns, the precompiler defines host variables only for the columns you name. If you do not specify any columns, the precompiler defines host variables for all the columns in the named table, view, or table procedure.
  • AS (
    column-alias
    )
    Specifies names to be used for the host variables defined for the named columns.
    Column-alias
    must follow the conventions for host variable names.
    You must specify no column aliases or the same number of column aliases as the number of host variables defined for columns in the named table, view, or table procedure.
    If you do not specify any column aliases, the name used for each host variable is the name of the column for which the host variable is defined.
Parameters for Expansion of table-options
  • AS
    structure-name
    Assigns the specified name to the data structure made up of the host variables corresponding to the columns in the named table, view, or table procedure.
    Structure-name
    must be a 1- through 31-character name that follows the conventions for host variable names.
    If you do not specify a name for the data structure, and you do not specify NO STRUCTURE, the name of the structure is the name of the table or view used to define the structure.
  • NO STRUCTURE
    Directs the precompiler not to group the host variable definitions together in a single data structure.
  • NUMBER OF ROWS
    row-count
    Directs the precompiler to define an array, suitable for bulk processing, in which the host variables are sub-elements of a structure that occurs the specified number of times.
    Row-count
    should be an integer in the range from 2 to the largest number of entries supported for an array by the host language compiler. You must specify NUMBER OF ROWS to create a host variable array using INCLUDE.
    If you specify NO STRUCTURE, NUMBER OF ROWS is ignored.
  • PREFIX '
    column-prefix
    '
    Specifies a character string to be used as the first portion of the name of each host variable defined for a column in the named table, view, procedure or table procedure.
    Column-prefix
    must be a one- through seven-character string and must be enclosed in single quotation marks.
    The column prefix concatenated with the column name or alias and the column suffix, if specified, must follow the conventions for host variable names.
  • SUFFIX '
    column-suffix
    '
    Specifies a character string to be used as the last portion of the name of each host variable defined for a column in the named table, view, procedure or table procedure.
    Column-suffix
    must be a one- through seven-character string and must be enclosed in single quotation marks.
    The column prefix, if specified, and the column name or alias concatenated with the column suffix must follow the conventions for host variable names.
  • LEVEL
    level-number
    Directs the precompiler to assign the specified level number to the data structure as a whole or, when the INCLUDE statement specifies NO STRUCTURE, to each host variable defined for a column.
    Level-number
    must be an integer in the range 01 through 47.
    If
    level-number
    is not specified, the default is 01.
Usage
SQLCA, SQLCODE, and SQLSTATE
An application program can contain an INCLUDE SQLCA statement or a host variable definition for SQLCODE and/or SQLSTATE within an SQL declaration section. In either case, the precompiler comments out the item and inserts the host variable definitions for the fields in the SQLCA.
If you include more than one of these items in an application program, the precompiler comments out all of them, inserts the host variable definitions for the fields in the SQLCA only once, and returns a warning.
If you do not include any of the items in a COBOL application program, the precompiler automatically creates the host variable definitions for the fields in the SQLCA if the application program contains SQL statements.
This does not apply to PL/I application programs. A PL/I program must contain an INCLUDE SQLCA or a host variable definition for SQLCODE or SQLSTATE.
Multiple SQL Descriptor Areas
Each SQL descriptor area included in an application program must have a unique name. If you include multiple SQL descriptor areas, you can use the default name SQLDA for only one of the areas. You must use the AS parameter to specify a different name for each of the others.
Placement of INCLUDE TABLE
The INCLUDE TABLE statement may appear anywhere within the application program that variable declarations are allowed. However, to reference the generated variables as host variable in an SQL statement, you must place the INCLUDE TABLE statement within an SQL declaration section.
Column Names as Host Variable Names
You can use the names of the columns in an included table as host variable names only when the column names follow the conventions for host variable names. Otherwise, you must specify a column alias for each column for which you want to define a host variable.
In a COBOL application program, the precompiler automatically converts underscores to hyphens in column names used as host variable names.
Indicator Variable Names
If a column within an included table is nullable, an indicator variable is generated for the column. The name of the indicator variable is the same as that of the data variable (column name or column alias) suffixed with '-I'.
Examples
Including the SQLCA
The following INCLUDE statement directs the precompiler to define host variables for the fields in the SQL Communication Area (SQLCA):
EXEC SQL    INCLUDE SQLCA END-EXEC
Including an SQL Descriptor Area
The following INCLUDE statement directs the precompiler to define host variables for the fields in an SQL descriptor area named BUFF-1-SQLDA. The maximum number of columns that can be described using BUFF-1-SQLDA is 30.
EXEC SQL    INCLUDE SQLDA       NUMBER OF COLUMNS 30       AS BUFF-1-SQLDA END-EXEC
Including a Table
The following INCLUDE statement directs the precompiler to define host variables corresponding to the named columns in the INSURANCE_PLAN table. The host variables are defined as a 10-row array named INS-COST-BUFFER.
EXEC SQL    INCLUDE TABLE INSURANCE_PLAN       AS INS-COST-BUFFER       (PLAN_CODE, COMP_NAME, MAX_LIFE_COST, FAMILY_COST, DEP_COST)          AS (PLANCODE, COMPNAME, MAXLIFE, FAMCOST, DEPCOST)       NUMBER OF ROWS 10 END-EXEC
The previous statement generates COBOL variable declarations in this format:
01  INS-COST-BUFFER   02  INS-COST-BUFFER-BULK OCCURS 10.     03 PLANCODE ...     03 COMPNAME ...     03 MAXLIFE ...     03 FAMCOST ...     03 DEPCOST ...
More Information