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 include files.

• Creation of an installable module.

• Storage of a module in the system catalog.

Figure 1-2 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.

   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 "SQLXFETO" USING 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. Note also that the paragraph named SQLMVS2 is not shown, but appears later in the modified source code file.

The names that appear in the inserted COBOL code (italicized in the above example) identify variables used by the ALLBASE/SQL external procedures; in this example, the names identify variables used by the SQLXFETO 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:

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

   $INCLUDE SQLCONST

   $INCLUDE SQLVAR

	CAUTION: Never modify either the statements inserted by the preprocessor or the include 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 a preprocessing session 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:

   :RUN PSQLCOB.PUB.SYS; INFO = 'DBEnvironmentName

   (MODULE(ModuleName))'

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.