The ALLBASE/SQL Pascal Preprocessor

• Syntax checking of SQL commands and host variable declarations.

• Creation of compilable files: one modified source code file and four 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 Pascal preprocessor scans the source code for SQL commands. If the syntax of an SQL command is valid, the preprocessor converts the command into compilable Pascal constructs that call ALLBASE/SQL external procedures at run time. During preprocessing, for example, ALLBASE/SQL converts the following SQL command:

   EXEC SQL SELECT PartNumber, PartName, SalesPrice

      INTO :PartNumber,

           :PartName,

           :SalesPrice :SalesPriceInd

      FROM  PurchDB.Parts

     WHERE  PartNumber = :PartNumber;

The preprocessor produces the following converted modified source code constructs:

   begin

   SQLTEMPV.REC1.PartNumber1 := PartNumber;

   SQLXFET(waddress(SQLCA),SQLOWNER,SQLMODNAME,1,waddress(SQLTEMPV),

           16,64,TRUE);

   if SQLCA.SQLCODE = 0 then

     begin

     PartNumber := SQLTEMPV.REC2.PartNumber1;

     PartName := SQLTEMPV.REC2.PartName2;

     if SQLTEMPV.REC2.SalesPriceInd4 >= 0 then

     SalesPrice := SQLTEMPV.REC2.SalesPrice3;

     SalesPriceInd := SQLTEMPV.REC2.SalesPriceInd4;

     end

   else

     begin

     end;

   end;

The preprocessor converts the embedded SELECT command into a Pascal comment and Pascal constructs that enable ALLBASE/SQL to execute the command at run time. The names that appear in the inserted Pascal code identify variables ALLBASE/SQL external procedures uses; in this example, the names identify variables used by the SQLXFET 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 like this:

   :SalesPrice

Refer to the chapter, "Host Variables," for more information.

Declarations used by preprocessor-generated code are defined in the four include files the preprocessor creates in the following syntax:

From one to 100 files of the syntax ModifiedSourceFile.svnn are generated, one for each declare section; for example, ModifiedSourceFileName.sv01.

The preprocessor inserts INCLUDE statements of the following syntax that reference these files in the declaration section of the modified source code:

   $include ModifiedSourceFileName.sqlc$

   $include ModifiedSourceFileName.sqlt$

   $include ModifiedSourceFileName.sqlv$

   $include ModifiedSourceFileName.sqle$

In place of the ModifiedFileName.sqlv include statement syntax, a ModifiedSourceFile.svnn include statement is used for multiple declare sections when subprograms are used.

The chapter, "Using the ALLBASE/SQL Pascal Preprocessor," explains how ModifiedSourceFileName is derived.

	CAUTION: Never modify either the constructs 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. The preprocessor starts a DBE session for that DBEnvironment when preprocessing begins and terminates that session when preprocessing is completed.

When the preprocessor encounters a syntactically correct SQL command, it usually creates a section and stores it in the system catalog of the DBEnvironment being accessed. (Some SQL commands do not create sections.) 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 heading unless you supply a different name when you invoke the preprocessor. In the following example, mymodule is a different name than mysource:

   $ psqlpas DBEnvironmentName -m mymodule -i mysource.sql -p mysource.p

	NOTE: 300/400 Series 300 and 400 systems do not allow subprograms. The main program and the subprograms that comprise an application must each have a unique name. No two modules are allowed to have the same name.

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

The Stored Section

A section consists of ALLBASE/SQL instructions for executing an SQL command. The SQL commands that do not generate stored sections are listed in the "Stored Sections" paragraph of the "Using the ALLBASE/SQL Pascal Preprocessor." The preprocessor creates a section and assigns a unique section number for all embedded ALLBASE/SQL commands 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

                                     WHENEVER

The preprocessor assigns a number to each section and references the appropriate stored section in the generated code:

   .

   .

   .

   SQLXFET(Waddress(SQLCA),SQLOWNER,SQLMODNAME,1,Waddress(SQLTEMPV),

      16,64,true);

Purpose of Sections

A section serves the following two purposes:

By creating and storing sections at preprocessing time rather than at run time, runtime performance is improved.

Section Validity

A section is assigned one of two states at preprocessing time: valid or invalid. A section is valid when access validation criteria are satisfied. If the SQL command references objects that exist at preprocessing time and the individual doing the preprocessing is authorized to issue the command, the stored section is marked as valid. A section is invalid when access validation criteria are not satisfied. If the SQL command references an object that does not exist at preprocessing time or if the individual doing the preprocessing is not authorized to issue the command, the stored section is marked as invalid. After being stored by the preprocessor, a valid section is marked as invalid when such activities as the following occur:

At run time, ALLBASE/SQL executes valid sections and attempts to validate any section marked as invalid. If an invalid section can be validated, as when an altered table does not affect the results of a query, ALLBASE/SQL marks the section as valid and executes it. If an invalid section cannot be validated, as when a table reference is invalid because the table owner name has changed, ALLBASE/SQL returns an error indication to the application program.

When a section is validated at run time, it remains in the valid state until an event that invalidates it occurs. The program execution during which validation occurs is slightly slower than program executions following validation.