DCLGEN Utility
DCLGEN (Declaration Generator) is a utility that maps the columns of a database table into a Fortran structure that can be included in a declaration section. The following command invokes DCLGEN from the operating system level:
dclgen language dbname tablename filename structurename
language
Defines the embedded SQL host language, in this case, Fortran.
dbname
Defines the name of the database containing the table.
tablename
Defines the name of the database table.
filename
Defines the output file into which the structure declaration is placed.
structurename
Defines the name of the host language structure (COBOL record) that the command generates.
The command generates a structure definition named structurename followed by an underscore character (_). It also generates a RECORD statement for the structure variable of structurename.
The DCLGEN utility creates the declaration file filename, containing a structure or a series of Fortran variables, if the -f77 flag is used, corresponding to the database table. The file also includes a declare table statement that serves as a comment and identifies the database table and columns from which the variables were generated.
UNIX:
DCLGEN has the option to map the columns of a database table into a series of Fortran variables rather than into a Fortran structure. This is useful if your Fortran compiler does not support structures. Specify the -f77 flag to indicate this DCLGEN option as follows:
dclgen -f77 language dbname tablename filename prefixname
The
prefixname is required when
-f77 is used. This prefix is appended to the column names of the table to produce the Fortran variables.
After the file is generated, you can use an Embedded SQL INCLUDE statement to incorporate it into the variable declaration section. The following example demonstrates how to use DCLGEN in a Fortran program.
Assume the "employee" table was created in the "personnel" database as:
exec sql create table employee
(eno smallint not null,
ename char(20) not null,
age integer1,
job smallint,
sal decimal(14,2) not null,
dept smallint)
When the DCLGEN system-level command is:
dclgen fortran personnel employee employee.dcl emprec
the "employee.dcl" file created by this command contains a comment, and three statements. The first statement is the declare table description of "employee," which serves as a comment. The second statement is a declaration of the Fortran structure "emprec_". The last statement is a record statement for "emprec".
The contents of the "employee.dcl" file are:
c Description of table employee from database personnel
exec sql declare employee table
1 (eno smallint not null,
1 ename char(20) not null,
1 age integer1,
1 job smallint,
1 sal decimal(14,2) not null,
1 dept smallint)
structure /emprec_/
integer*2 eno
character*20 ename
integer*2 age
integer*2 job
real*8 sal
integer*2 dept
end structure
record /emprec_/ emprec
UNIX:
For this example the DCLGEN system-level command is:
dclgen -f77 fortran personnel employee employee.dcl emp
The "employee.dcl" file created by this command contains a comment, a DECLARE TABLE statement and the variable declarations. The DECLARE TABLE statement describes the employee table and serves as a comment. The exact contents of the "employee.dcl" file are:
C Description of table employee from database personnel
exec sql declare employee table
1 (eno smallint not null,
1 ename char(20) not null,
1 age integer1,
1 job smallint,
1 sal decimal(14,2) not null,
1 dept smallint)
integer*2 empeno
character*20 empename
integer*2 empage
integer*2 empjob
real*8 empsal
integer*2 empdept
The Ingres integer1 data type is mapped to the Fortran integer*2 data type, rather than to byte.
Include this file, by means of the Embedded SQL INCLUDE statement, in an Embedded SQL declaration section:
exec sql begin declare section
exec sql include 'employee.dcl'
exec sql end declare section
You can then use the variables in data manipulation statements.
The field names of the structure that DCLGEN generates are identical to the column names in the specified table. Therefore, if the column names in the table contain any characters that are illegal for host language variable names you must modify the name of the field before attempting to use the variable in an application.
DCLGEN and Large Objects
When a table contains a large object column, DCLGEN will issue a warning message and map the column to a zero length character string variable. You must modify the length of the generated variable before attempting to use the variable in an application.
For example, assume that the "job_description" table was created in the "personnel" database as:
create table job_description
(job smallint, description long varchar))
and the DCLGEN system-level command is:
dclgen fortran personnel job_description jobs.dcl jobs_rec
The contents of the "jobs.dcl" file would be:
C Description of table job_description from database
C personnel
exec sql declare job_description table
1 (job smallint not null,
description long varchar)
structure /jobs_rec_/
integer*2 job
character*0 description
end structure
record /jobs_rec/ blobs_rec
The table definition when used with the -f77 flag (assuming the prefix of "b_" was specified) results in the following DCLGEN generated output in "jobs.dcl":
exec sql declare job_description table
1 (job smallint,
description long varchar)
character*0 b_description