HP 3000 Manuals

ALLBASE/SQL COBOL Application Programming Guide

The ALLBASE/SQL COBOL Preprocessor 

The ALLBASE/SQL COBOL preprocessor is specifically for COBOL II/XL
programs.

Figure 1-2 summarizes the four main preprocess-time events:

   *   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:

   *   SQLCONST, a file that defines variables requiring VALUE clauses

   *   SQLVAR, a file that defines the remaining variables

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.

MPE/iX 5.0 Documentation