The ALLBASE/SQL COBOL Preprocessor

• Syntax checking of SQL commands and host variable declarations.

• Creation of compilable files: one modified source code file and two copy files.

• Creation of an installable module.

• Storage of a module in the system catalog.

Figure 1-3 Preprocess Time Events

Effect of Preprocessing on Source Code

The COBOL preprocessor scans the source code for SQL commands. If the syntax of an SQL command is correct, the preprocessor converts the command into compilable COBOL statements that call ALLBASE/SQL external procedures at run time. During preprocessing, for example, the following SQL command is converted to modified source code. The shaded lines highlight the boundaries of the code generated by the preprocessor. Note that your original code is commented out and replaced by the code generated by the preprocessor.

   EXEC SQL SELECT PARTNUMBER, PARTNAME, SALESPRICE

   	     INTO :PARTNUMBER,

	          :PARTNAME,

	          :SALESPRICE :SALESPRICEIND

	     FROM  PURCHDB.PARTS

	    WHERE  PARTNUMBER = :PARTNUMBER;

   END-EXEC.

The modified source code is as follows:

   **** Start SQL Preprocessor ****

   *    EXEC SQL

   *         SELECT PARTNUMBER, PARTNAME, SALESPRICE

   *           INTO :PARTNUMBER,

   *                :PARTNAME,

   *                :SALESPRICE :SALESPRICEIND

   *           FROM PURCHDB.PARTS

   *          WHERE PARTNUMBER = :PARTNUMBER

   *    END-EXEC

   **** Start Inserted Statements ****

        MOVE PARTNUMBER

          TO SQLREC1-FIELD1

        MOVE 1 TO SQLSECNUM

        MOVE 16 TO SQLINLEN

        MOVE 54 TO SQLOUTLEN

        CALL SQLXCBL USING SQLXFET, SQLCA, SQLOWNER, SQLMODNAME, 

          SQLSECNUM, SQLTEMPV, SQLINLEN, SQLOUTLEN, SQLTRUE

        IF SQLCODE IS ZERO

          MOVE SQLREC2-FIELD1

            TO PARTNUMBER

          MOVE SQLREC2-FIELD2

            TO PARTNAME

          MOVE SQLREC2-FIELD3-IND

            TO SALESPRICEIND

          IF SQLREC2-FIELD3-IND IS NOT NEGATIVE

            MOVE SQLREC2-FIELD3

              TO SALESPRICE

          END-IF

          IF SQLWARN0 IS EQUAL TO "W"

            GO TO S500-SQL-WARNING

          END-IF

        ELSE

          IF SQLCODE IS EQUAL TO 100

            GO TO S600-NOT-FOUND

          END-IF

          IF SQLCODE IS NEGATIVE

            GO TO S400-SQL-ERROR

          END-IF

          CONTINUE

        END-IF

   **** End SQL Preprocessor ****

   		     .

The embedded SELECT command has been converted into a COBOL comment, and COBOL statements that enable ALLBASE/SQL to execute the SELECT command at run time have been inserted. Note that the period following the END-EXEC now follows the last preprocessor-generated line shown.

The names that appear in the inserted COBOL code identify variables used by the ALLBASE/SQL external procedures; in this example, the names identify variables used by the SQLXCBL external procedure. Some of these variables are derived from host variables. As shown in the embedded SELECT command above, you precede a host variable with a colon when you use it in SQL commands:

        :SALESPRICE

Declarations used by preprocessor generated code are defined in the two copy files which the preprocessor creates with the following syntax:

The preprocessor inserts COPY directives that reference these files in the WORKING-STORAGE SECTION of the modified source code:

   COPY "mysource.sqlc".

   COPY "mysource.sqlv".

The COBOL compiler INCLUDE directive works the same as COPY.

Note the following coding rules for compiler directives:

Refer to the COBOL/HP-UX Operating Manual for a more detailed explanation of the function of compiler directives.

	CAUTION: Never modify either the statements inserted by the preprocessor or the copy files the preprocessor creates. Changes to preprocessor-generated information could damage your DBEnvironment or your system.

Effect of Preprocessing on DBEnvironments

When you invoke the preprocessor, you name an ALLBASE/SQL DBEnvironment. When preprocessing begins, the preprocessor starts a DBE session for that DBEnvironment. When preprocessing is completed, the preprocessor terminates the session.

When the preprocessor encounters a syntactically correct SQL command, it usually creates an ALLBASE/SQL section and stores it in the system catalog of the DBEnvironment being accessed. An ALLBASE/SQL section is a group of stored ALLBASE/SQL instructions for executing one SQL command.

All sections created during the preprocessing of a single unit (main program or subprogram) constitute a module. The preprocessor derives the name of the module from the PROGRAM-ID unless you supply a different name when you invoke the preprocessor:

   $ psqlcbl DBEnvironmentName -i mysource.sql -m mymodule

When the preprocessor terminates the DBEnvironment session, it issues a COMMIT WORK command if no errors were encountered. Created sections are stored in the system catalog and associated with the module name.