Identifying Preprocessor Output

As Figure 2-5 points out, running the C preprocessor in full preprocessing mode creates the following output files:

Modified source file.
Include files.
SQL message file.
Installable module file.

Also, a module is stored in the DBEnvironment specified in the preprocessor invocation line. Each of these is described in the following sections.

Modified Source File

As the C preprocessor parses the source file, it copies lines from it and any include files into the modified source file, inserts conditional compiler directives around the embedded SQL commands, and inserts information around each embedded SQL command.

The default modified source file name is SQLOUT.

Figure 2-9 illustrates the modified source file generated for the source file pictured in Figure 1-8. The shaded lines contain information generated by the C preprocessor.

In both preprocessing modes, the C preprocessor:

Inserts conditional compiler directives around embedded SQL commands to conditionally ignore the SQL commands.
Inserts three #INCLUDE C compiler directives within the Declaration part. These directives reference the three preprocessor generated include files. These files are included at the beginning of the modified source file created by the preprocessor.
Places comments on the line with an embedded command following the last line the embedded command generates. Note, for example, that the comment following the EXEC SQL INCLUDE SQLCA command in the source file is in the same column, but on a different line, in the modified source file.

In full preprocessing mode, the preprocessor also:

Generates a C declaration of the sqlca and the sqlda in the type include file.
Generates C statements providing conditional instructions following SQL commands encountered after one of the following SQL commands: WHENEVER SQLERROR, WHENEVER SQLWARNING, and WHENEVER NOT FOUND.
Generates C statements that call ALLBASE/SQL external procedures at run time. These calls reference the module stored by the preprocessor in the DBEnvironment for execution at run time. Parameters used by these external calls are defined in the variable and type include files.




	CAUTION: Although you can access the preprocessor output files with an editor, you should `never` change the information generated by the C preprocessor. Your DBEnvironment or your system could be damaged at run time if preprocessor generated constructs are altered.

If you change non-preprocessor-generated constructs, make the changes to the source file, re-preprocess it, and re-compile the output files before putting the application program into production.

Include Files

There are three include files, which contain declarations and definitions used by the C functions created by the preprocessor and inserted into the modified source code file:

type include file: the name for this file, which contains type declarations, is:
SQLTYPE
variable include file: the name for this file, which contains variable declarations, is:
SQLVAR
externals include file: the name for this file, which contains external procedure declarations, is:
SQLEXTN

The sqlmodulename and ownername of sections are defined as global static variables in SQLVAR. It is advised that multiple source file applications be preprocessed all at one time so that only one SQLVAR file is generated. If the source files are preprocessed and compiled separately and combined at link time, runtime errors occur because the static global sqlmodulename variable from the first source file preprocessed is used and incorrect sections are executed. Therefore, all preprocessed sections in your program must reside in the same file for input to the C compiler.

When you use file equations to redirect the include files, remember that the preprocessor always inserts the same #INCLUDE directives. Therefore, insure that the applicable file equations are in effect when you preprocess and when you compile.

When the preprocessor is invoked, the following file equations must be in effect:

   :FILE SQLTYPE = MYTYPE

   :FILE SQLVAR = MYVAR

   :FILE SQLEXTN = MYEXTN

Then when the C compiler is invoked, the following file equations must be in effect:

   :FILE SQLTYPE = MYTYPE

   :FILE SQLVAR = MYVAR

   :FILE SQLEXTN = MYEXTN

   :CC MYSQLPRG, $NEWPASS, $NULL

ALLBASE/SQL Message File

The ALLBASE/SQL message file is named sqlmsg. Messages placed in sqlmsg when you preprocess come from the ALLBASE/SQL message catalog. The default catalog is SQLCT000.PUB.SYS. For native language users, the name of the catalog is SQLCTxxx.PUB.SYS, where xxx is the number of the current language. If this catalog is not available, ALLBASE/SQL uses the default instead.

Sqlmsg messages contain four parts:

A banner:

For Series 900 systems:

   HP36216-02A.E1.02                C preprocessor/3000     ALLBASE/SQL 

   (C)COPYRIGHT HEWLETT-PACKARD CO. 1982,1983,1984,1985,1986,1987,1988,

   1989,1990,1991.  ALL RIGHTS RESERVED.

Banners are displayed when ISQL, SQLUtil, or a preprocessor is invoked.

A summary of the preprocessor invocation conditions:

   DBEnvironment        = PARTSDBE.SOMEGRP.SOMEACCT



   Module Name          = CEX2

Warnings and errors encountered during preprocessing:

      32       SalesPriceInd     : SQLID;

                                  |

   ******Unsupported type syntax for host variable.  (DBERR 10933)





          SELECT PartNumber, PartName, SalesPrice INTO :PartNumber, :PartName,

           :SalesPrice :SalesPriceInd FROM PurchDB.Parts WHERE PartNumber =

           :PartNumber;



   ******ALLBASE/SQL query processing errors.  (DBERR 10952)

   ******in SQL statement ending in line 128

   ***ALLBASE/SQL alignment error on column 3 in buffer 5.  (DBERR 4200)



There are errors.  No sections stored.

A summary of the results of preprocessing:

   2 ERRORS   0 WARNINGS

   END OF PREPROCESSING.

Both the banner and the preprocessing summary results are also echoed to the terminal.

As illustrated in Figure 2-6, a line number is often provided in sqlmsg. This line number references the line in the program source file containing the command in question. A message accompanied by a number may also appear. You can refer to the ALLBASE/SQL Message Manual for additional information on the exception condition when these numbered messages appear.

Figure 2-6 Sample sqlmsg Showing Errors

: print sqlmsg

HP36216-02A.E1.02                 C preprocessor/3000     ALLBASE/SQL 

(C)COPYRIGHT HEWLETT-PACKARD CO.  1982,1983,1984,1985,1986,1987,1988,

1989,1990,1991.  ALL RIGHTS RESERVED.



DBEnvironment        = PARTSDBE.SOMEGRP.SOMEACCT

Module Name          = CEX2



     32       SalesPriceInd   : SQLID

                                |

******  Unsupported type syntax for host variable.  (DBERR 10933)





        SELECT PartNumber, PartName, SalesPrice INTO :PartNumber, :PartName,

         :SalesPrice :SalesPriceInd FROM PurchDB.Parts WHERE PartNumber=

         :PartNumber;



******  ALLBASE/SQL query processing errors. (DBERR 10952)

******  in SQL statement ending in line 128

*** ALLBASE/SQL alignment error on column 3 in buffer 5.  (DBERR 4200)



There are errors.  No sections stored.

  2 ERRORS   0 WARNINGS

 END OF PROCESSING.

 :

As Figure 2-7 illustrates, the preprocessor can terminate with the warning message

      ****** ALLBASE/SQL warnings. (DBWARN 10602)

when the name of an object in the source file does not match the name of any object in the system catalog. Although a section is stored for the semantically incorrect command, the section is marked as invalid and will not execute at run time if it cannot be validated.

Figure 2-7 Sample sqlmsg Showing Warning

: ppc cex2,partsdbe,cex2p

HP36216-02A.20.00.00             C preprocessor/3000      ALLBASE/SQL

(C)COPYRIGHT HEWLETT-PACKARD CO.  1982,1983,1984,1985,1986,1987,1988,

1989,1990,1991.  ALL RIGHTS RESERVED.



  0 ERRORS    1 WARNINGS

END OF PREPROCESSING



: print sqlmsg



HP36216-02A.E1.02                 C preprocessor/3000     ALLBASE/SQL 

(C)COPYRIGHT HEWLETT-PACKARD CO.  1982,1983,1984,1985,1986,1987,1988,

1989,1990,1991.  ALL RIGHTS RESERVED.



DBEnvironment        = PARTSDBE.SOMEGRP.SOMEACCT

Module Name          = CEX2



       SELECT PartNumber, PartName, SalesPrice INTO :PartNumber, PartName,

        :SalesPrice :SalesPriceInd FROM PurchDB.Parts WHERE ParNumber =

        :PartNumber;



****** ALLBASE/SQL warnings. (DBWARN 10602)

****** in SQL statement ending in line 128

*** Column PARNUMBER not found. (DBERR 2211)



  1 Sections stored in DBEnvironment.



  0 ERRORS   1 WARNINGS

END OF PREPROCESSING

Stored Module Containing Sections

In full preprocessing mode, the preprocessor stores a module in the DBEnvironment you specify at preprocessing time. By default, the preprocessor uses the source file name as the name for the module it stores. You can specify a module name with the MODULE option of the preprocessor command.

The module contains a section for each embedded SQL command in your program except:

   BEGIN DECLARE SECTION             INCLUDE

   BEGIN WORK                        OPEN

   CLOSE                             PREPARE

   COMMIT WORK                       RELEASE

   CONNECT                           ROLLBACK WORK

   DECLARE CURSOR                    SAVEPOINT

   DELETE WHERE CURRENT              START DBE

   DESCRIBE                          STOP DBE

   END DECLARE SECTION               SQLEXPLAIN

   EXECUTE                           TERMINATE USER

   EXECUTE IMMEDIATE                 UPDATE WHERE CURRENT

   FETCH                             WHENEVER

The commands listed above either require no authorization to execute or are executed based on information contained in the compilable preprocessor output files.

When the preprocessor stores a section, it actually stores what are known as an input tree and a run tree. The input tree consists of the uncompiled command. The run tree is the compiled, executable form of the command. If at run time a section is valid, ALLBASE/SQL executes the appropriate run tree when the SQL command is encountered in the application program. If a section is invalid, ALLBASE/SQL determines whether the objects referenced in the section exist and whether current authorization criteria are satisfied. When an invalid section can be validated, ALLBASE/SQL dynamically recompiles the input tree to create an executable run tree and executes the command. When a section cannot be validated, the command is not executed, and an error condition is returned to the program.

There are three types of sections:

Sections for executing the SELECT command associated with a DECLARE CURSOR command.
Sections for executing the SELECT command associated with a CREATE VIEW command.
Sections for all other commands for which the preprocessor stores a section.

Figure 2-8 illustrates the kind of information in the system catalog. All stored sections for each module in the DBEnvironment are referenced here. The query result illustrated was extracted from the system view named SYSTEM.SECTION by using ISQL. The columns in Figure 2-8 have the following meanings:

NAME: This column contains the name of the module to which a section belongs. You can specify a module name when you invoke the preprocessor; or the module name will default to the source code file name of the C program. If you are supplying a module name in a native language other than NATIVE-3000 (ASCII), be sure it is in the same language as that of the DBEnvironment.
OWNER: This column identifies the owner of the module. You can specify an owner name when you invoke the preprocessor,or the owner name will default to the login name associated with the preprocessing session. If you are supplying an owner name in a native language other than NATIVE-3000 (ASCII), be sure it is in the same language as that of the DBEnvironment.
DBEFILESET: This column indicates the DBEFileSet which contains the DBEFile(s) which in turn contains the section(s).
SECTION: This column gives the section number. Each section associated with a module is assigned a number by the preprocessor as it parses the related SQL command at preprocessing time.

TYPE: This column identifies the type of section:

   1 = SELECT associated with a cursor

   2 = SELECT defining a view

   0 = All other sections

VALID: This column identifies whether a section is valid or invalid:
0 = invalid 1 = valid

Figure 2-8 Information in SYSTEM.SECTION on Stored Sections

isql=>  SELECT NAME,OWNER,DBEFILESET,SECTION,TYPE,VALID FROM SYSTEM.SECTION;



SELECT NAME,OWNER,DBEFILESET,SECTION,TYPE,VALID FROM SYSTEM.SECTION;

--------------------------------------------------------------------------

NAME              |OWNER        |DBEFILESET       |SECTION  |TYPE  |VALID

--------------------------------------------------------------------------

TABLE             |SYSTEM       |SYSTEM           |        0|     2|     0

COLUMN            |SYSTEM       |SYSTEM           |        0|     2|     0

INDEX             |SYSTEM       |SYSTEM           |        0|     2|     0

SECTION           |SYSTEM       |SYSTEM           |        0|     2|     0

DBEFILESET        |SYSTEM       |SYSTEM           |        0|     2|     0

DBEFILE           |SYSTEM       |SYSTEM           |        0|     2|     0

SPECAUTH          |SYSTEM       |SYSTEM           |        0|     2|     0

TABAUTH           |SYSTEM       |SYSTEM           |        0|     2|     0

COLAUTH           |SYSTEM       |SYSTEM           |        0|     2|     0

MODAUTH           |SYSTEM       |SYSTEM           |        0|     2|     0

GROUP             |SYSTEM       |SYSTEM           |        0|     2|     0

VIEWDEF           |SYSTEM       |SYSTEM           |        0|     2|     0

HASH              |SYSTEM       |SYSTEM           |        0|     2|     0

CONSTRAINT        |SYSTEM       |SYSTEM           |        0|     2|     0

CONSTRAINTCOL     |SYSTEM       |SYSTEM           |        0|     2|     0

CONSTRAINTINDEX   |SYSTEM       |SYSTEM           |        0|     2|     0

COLDEFAULT        |SYSTEM       |SYSTEM           |        0|     2|     0

TEMPSPACE         |SYSTEM       |SYSTEM           |        0|     2|     0

PARTINFO          |PURCHDB      |SYSTEM           |        0|     2|     0

VENDORSTATISTICS  |PURCHDB      |SYSTEM           |        0|     2|     0

CEX2              |PGMR1@ACCT2  |SYSTEM           |        1|     0|     1

CEX7              |PGMR1@ACCT2  |SYSTEM           |        1|     1|     1

CEX7              |PGMR1@ACCT2  |SYSTEM           |        2|     0|     1

--------------------------------------------------------------------------

Number of rows selected is 16.

U[p], d[own], l[eft], r[ight], t[op], b[ottom], pr[int] <n>,or e[nd]>

The first eleven rows in the query result shown in Figure 2-8 describe the sections stored for the system views. The next two rows describe the two views in the sample database: PurchDB.PartInfo and PurchDB.VendorStatistics. Views are always stored as invalid sections, because the run tree is always generated at run time.

The remaining rows describe sections associated with two preprocessed programs. CEX2 contains only one section, for executing the SELECT command in the program illustrated in Figure 2-9. CEX7 contains two sections, one for executing the SELECT command associated with a DECLARE CURSOR command and one for executing a FETCH command.

Stored sections remain in the DBEnvironment until they are deleted by using the ISQL DROP MODULE command:

   isql=> DROP MODULE cex2;

or by invoking the preprocessor with the DROP option:

   : RUN PSQLC.PUB.SYS;INFO="PARTSDBE (DROP)"

Stored sections are marked invalid when:

The UPDATE STATISTICS command is executed.
Tables accessed in the program are dropped, altered, or assigned new owners.
Indexes or DBEFileSets related to tables accessed in the program are changed.
Module owner authorization changes are made that affect the execution of embedded commands.

When an invalid section is validated at run time, the validated section is committed when the program issues a COMMIT WORK command. If a COMMIT WORK command is not executed, ALLBASE/SQL must re-validate the section again the next time the program is executed. For this reason, you should embed COMMIT WORK commands even following SELECT commands, since the COMMIT WORK command may be needed even when data is not changed by a program.

Installable Module File

When the preprocessor stores a module in the DBEnvironment you named at preprocessing time, it places a copy of the module in an installable module file. The module in this file can be installed into a DBEnvironment different from the DBEnvironment accessed at preprocessing time by using the INSTALL command in ISQL. In order to install the module, you need CONNECT or DBA authority in the target DBEnvironment.

The installable module file is named SQLMOD. The module also has an internal, SQL name, in this case PGMR1@ACCT2.CEX2 which is saved as part of the module at preprocessing time. PGMR1@ACCT2 is the login of the user who preprocessed source file cex2, and PGMR1@ACCT2 is the owner of the module.

   : isql



   isql=> CONNECT TO 'PARTSDBE.SOMEGRP.SOMEACCT';

   isql=> INSTALL;



   File name> SQLMOD;

   Name of module in this file:  PGMR1@ACCT2.CEX2

   Number of sections installed:  1

   COMMIT WORK to save to DBEnvironment.



   isql=> COMMIT WORK;

   isql=>

Identifying Preprocessor Output

Technical documentation

» Table of Contents

» Index

Modified Source File

Include Files

ALLBASE/SQL Message File

Stored Module Containing Sections

Installable Module File