DCLGEN Utility

The DCLGEN (Declaration Generator) utility is a structure-generating utility that maps the columns of a database table into a structure that you can include in a declaration section.

The DCLGEN utility can be invoked from the operating system level by executing the following command:

Defines the output file into which the structure declaration is placed.

Defines the name of the host language structure that the command generates. The structure tag is the structure name followed by an underscore character (_).

This command creates the declaration file filename, containing a structure 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 structure was generated.

When the file is generated, use an embedded SQL include statement to incorporate it into the variable declaration section. The following example demonstrates how to use DCLGEN in a C 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)
        with journaling;

Also, assume the DCLGEN system-level command is:

This command creates the employee.dcl file, which contains a comment and two statements. The first statement is the declare table description of employee, which serves as a comment. The second statement is a declaration of the C structure emprec. The contents of the employee.dcl file are:

/* Table employee description from database personnel */
exec sql declare employee table
            (eno smallint not null,
            ename char(20) not null,
            age integer1,
            job smallint,
            sal decimal(14,2) not null,
            dept smallint);

struct emprec_ {
            short eno;
            char ename[21];
            short age;
            short job;
            double sal;
            short dept;
} emprec;

The length of the ename buffer is increased by one byte to accommodate the C null terminator. Also, the integer1 data type is mapped to short rather than char.

To include this file in an embedded SQL declaration section, use the embedded SQL include statement:

exec sql begin declare section;
exec sql include 'employee.dcl';
exec sql end declare section;

You can then use the emprec structure in a select, fetch, or insert statement.

The field names in 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.

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);

Also, assume the DCLGEN system-level command is:

The contents of the jobs.dcl file would be:

/*Table job_description description from database
     personnel*/
    exec sql declare job_description table
        (job smallint,
        description long varchar);
    struct jobs_rec_ {
        short job;
        char description[0];
   } jobs_rec;