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.
To issue an INCLUDE statement that specifies:
►►─── 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 ' ─┘
Directs the precompiler to define host variables for the fields in the SQL Communication Area (SQLCA) in the application program.
Directs the precompiler to define host variables for the fields in the SQL descriptor area in the application program.
Specifies additional characteristics for the SQL descriptor area. Expanded syntax for sqlda-options is shown immediately following the INCLUDE syntax and documented directly below.
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.
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.
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:
For expanded table-name syntax, see Expansion of Table-name.
Specifies the schema with which the function identified by function-identifier is associated. If schema-name is not specified, the precompiler:
Directs the precompiler to define host variables corresponding to one or more columns in the named function in the application program.
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.
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.
Note: INCLUDE module-name is equivalent to COPY IDMS module-name as documented in the CA IDMS DML Reference manuals.
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
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.
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
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.
Directs the precompiler not to group the host variable definitions together in a single data structure.
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.
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.
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.
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.
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.
Note: 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.
Note: 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'.
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 ...
|
Copyright © 2014 CA.
All rights reserved.
|
|