Invoking the C Preprocessor

You can use the preprocessor in two modes:

Full preprocessing mode: includes SQL syntax checking, creating compilable output, storing a module in a DBEnvironment, and creating a file that contains an installable copy of the stored module.
Syntax checking mode: checks your SQL syntax without doing any other preprocessor tasks.

As you develop the SQL portions of your C programs, syntax checking mode is quite useful. Preprocessing is quicker in this mode than in full preprocessing mode. In addition, you can start debugging your SQL commands before the DBEnvironment itself is in place.

Command syntax for both modes is presented below.

Full Preprocessing Mode

Use the following preprocessor command to:

Check the embedded SQL command syntax.
Create compilable output files that can be processed by the C compiler
Store a module in the DBEnvironment named.
Create a file containing an installable version of the module.

Preprocessor Syntax I

RUN PSQLC.PUB.SYS;INFO="DBEnvironmentName [ ( { MODULE(ModuleName) OWNER (OwnerName) {DROP {PRESERVE} {REVOKE}} {NODROP}} |...| )" ]

Parameters

DBEnvironmentName: Identifies the DBEnvironment in which a module is to be stored. You may use a backreference to a file defined in a file equation for this parameter.
ModuleName: Assigns a name to the stored module. Module names must follow the rules governing ALLBASE/SQL basic names as described in the ALLBASE/SQL Reference Manual. If a module name is not specified, the preprocessor uses the PROGRAM-ID as the module name.
OwnerName: Associates the stored module with a User@Account, a ClassName, or a GroupName. You can specify an owner name for the module only if you have DBA authority in the DBEnvironment where the module is to be stored. If not specified, the owner name is your log-on User@Account. Any object names in SQLIN not qualified with an owner name are qualified with the OwnerName specified by the preprocessor, or the user.
DROP: Deletes any module currently stored in the DBEnvironment by the ModuleName and OwnerName specified in the INFO string.
NODROP: Terminates preprocessing if any module currently exists in the DBEnvironment by the ModuleName and OwnerName specified in the INFO string. If not specified, NODROP is assumed.
PRESERVE: Is specified when the program being preprocessed already has a stored module and you want to preserve existing RUN authorities for that module. If not specified, PRESERVE is assumed. PRESERVE cannot be specified unless DROP is also specified.
REVOKE: Is specified when the program being preprocessed already has a stored module and you want to revoke existing RUN authorities for that module. REVOKE cannot be specified unless DROP is also specified.

Description

Before invoking the preprocessor in this mode when the program being preprocessed already has a stored module, ensure that the earlier version of the program is not being executed.
The preprocessor starts a DBE session in the DBEnvironment named in the RUN command by issuing a CONNECT TO 'DBEnvironmentName' command. If the autostart flag is OFF, the DBE session can be initiated only after a START DBE command has been processed.
If the DBEnvironment to be accessed is operating in single-user mode, preprocessing can occur only when another DBE session for the DBEnvironment does not exist.
When the preprocessor's DBE session begins, ALLBASE/SQL processes a BEGIN WORK command. When preprocessing is completed, the preprocessor submits a COMMIT WORK command, and any sections created are committed to the system catalog. If the preprocessor detects an error in SQLIN, it processes a ROLLBACK WORK command before terminating, and no sections are stored in the DBEnvironment. Preprocessor warnings do not prevent sections from being stored.
Since all preprocessor DBE sessions initiate only one transaction, any log file space used by the session is not available for re-use until after the session terminates. If rollforward logging is not in effect, you can issue the CHECKPOINT command in ISQL before preprocessing to increase the amount of available log space. Refer to the Database Administration Guide for additional information on log space management, such as using the START DBE NEWLOG command to increase the size of the log and recovering log space when rollforward logging is in effect.
During preprocessing, system catalog pages accessed for embedded commands are locked. In multiuser mode, other DBE sessions accessing the same objects must wait, and the potential for a deadlock exists. Therefore minimize competing transactions when preprocessing an application program. Refer to the appendix "Locks Held on the System Catalog by SQL Commands" in the ALLBASE/SQL Database Administration Guide for information on operations that lock system catalog pages.
For improved runtime performance, use ISQL to submit the UPDATE STATISTICS command before preprocessing for each table accessed in a data manipulation command when an index on that table has been added or dropped and when data in the table is often changed.
If you specify an OwnerName or ModuleName in a language other than NATIVE-3000 (ASCII), be sure that the language you are using is also the language of the DBEnvironment in which the module will be stored.

Authorization

To preprocess a program, you need DBA or CONNECT authority for the DBEnvironment specified in the preprocessor command line. You also need table and view authorities for the tables and views which the program will access at run time.

DBEnvironment CONNECT authority can also be explicitly GRANTed. If you have DBECreator or DBA authority or module OWNER authority, you have CONNECT authority by default.

Table authorities are implicitly specified at the time the table is CREATEd and depend on the table type (PUBLIC, PUBLICREAD, or PRIVATE). Once a table has been created, its implicit authorities can be changed by the table OWNER, the DBECreator, or another DBA. Table authorities are removed by using the REVOKE command and are added by using the GRANT command.

For example, for a PUBLIC table, you are implicitly GRANTed authority for any type of table access when the table is created. For a PUBLICREAD table, you must have explicitly GRANTed authority for any table access except READ access which is an implicit grant. For a PRIVATE table, there are no implicit grants at table creation time; only the table OWNER or a DBA can access a PRIVATE table, unless specific authorities are GRANTed to others.

Note, in the case of the sample database, PartsDBE, the creation script REVOKEs all implicit table authorities, and desired authorities must be explicitly GRANTed.




	NOTE: When preprocessing, you cannot name another user as module owner unless you are a DBA of the DBEnvironment or you are the current module owner.

Example


:FILE SQLIN=CEX2
:RUN PSQLC.PUB.SYS;INFO=&
"PartsDBE (MODULE(CEX2) OWNER(OwnerP@SomeAcct) REVOKE DROP)"

                                          WED, OCT 25, 1991,  1:38 PM
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.

 0 ERRORS     1 WARNINGS
END OF PREPROCESSING.


END OF PROGRAM
:EDITOR
HP32501A.07.20 EDIT/3000 FRI, OCT 27, 1991,  10:17 AM
(C)HEWLETT-PACKARD CO. 1990

/T SQLMSG;L ALL UNN

FILE UNNUMBERED

             .
             .
             .
SQLIN                = CEX2.SOMEGRP.SOMEACCT
DBEnvironment        = partsdbe
Module Name          = CEX2

        SELECT PARTNUMBER, PARTNAME, SALESPRICE INTO :PARTNUMBER, :PARTNAME,
        :SALESPRICE :SALESPRICEIND FROM PURCHDB.PARTS WHERE PARTNUMBER =
        :PARTNUMBER ;

******  ALLBASE/SQL warnings (DBWARN 10602)
******  in SQL statement ending in line 133
***     User SomeUser@SomeAcct does not have SELECT authority on PURCHDB.PARTS.
(DBERR 2301)

  1 Sections stored in DBEnvironment.

 0 ERRORS   1 WARNINGS
END OF PREPROCESSING

/

Syntax Checking Mode

The following command only checks the syntax of the SQL commands embedded in the source code file.

Preprocessor Syntax II


    RUN PSQLC.PUB.SYS;INFO="(SYNTAX)"

Description

The preprocessor does not access a DBEnvironment when it is run in this mode.
When performing only syntax checking, the preprocessor does not convert the SQL commands into C statements. Therefore SQLOUT does not contain any preprocessor generated calls to ALLBASE/SQL external procedures.
SQLTYPE, SQLEXTN, SQLVAR, and SQLMOD are created, but incomplete.

Authorization

You do not need ALLBASE/SQL authorization when you use the preprocessor to only check SQL syntax.

Example


   :FILE SQLIN=CEX2
   :RUN PSQLC.PUB.SYS;INFO="(SYNTAX)"

                                              WED, OCT 25, 1991,  1:38 PM
   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.

   Syntax checked.
    1 ERRORS     0 WARNINGS
   END OF PREPROCESSING.


   PROGRAM TERMINATED IN AN ERROR STATE.  (CIERR 976)
   :EDITOR
   HP32501A.07.20 EDIT/3000 FRI, OCT 27, 1991,  9:35 AM
   (C) HEWLETT-PACKARD CO. 1985

   /T SQLMSG;L ALL UNN
   FILE UNNUMBERED

              .
              .
              .
   SQLIN                = CEX2.SOMEGRP.SOMEACCT


           SELECT PARTNUMBER, PARTNAME, SALESPRICE INTO :PARTNUMBER, :PARTNAME,
           :SALESPRICE :SALESPRICEIND, FROM PURCHDB.PARTS WHERE PARTNUMBER =
           :PARTNUMBER ;

   ******  ALLBASE/SQL errors (DBERR 10977)
   ******  in SQL statement ending in line 176
   ***     Unexpected keyword.  (DBERR 1006)

   Syntax checked.

    1 ERRORS   0 WARNINGS
   END OF PREPROCESSING.

   /

        The line 176 referenced in SQLMSG is the line in
        SQLIN where the erroneous SQL command ends.

DBEnvironment Access

When you invoke the preprocessor in full preprocessing mode, 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. The preprocessor derives the name of the module from the source code file name unless you supply a different name when you invoke the preprocessor:

   : RUN PSQLC.PUB.SYS; INFO="DBEnvironment (MODULE (ModuleName))"

When the preprocessor terminates its DBEnvironment session, it issues a COMMIT WORK command if it encountered no errors. Created sections are stored in the DBEnvironment and associated with the module name. See Figure 2-6 later in this chapter.

ALLBASE/SQL accesses the DBEnvironment you specify during preprocessing, even if your program does not use SQL statements that store sections in this DBEnvironment. Therefore, you must specify the name of a valid DBEnvironment.

In some cases an ALLBASE/SQL progam is used with one or more DBEnvironments in addition to the DBEnvironment accessed at preprocessing time. In these cases, use ISQL to install the installable module created by the preprocessor into each additional DBEnvironment accessed by your program. See the section "Installable Module File" in this chapter.

An alternative method of accessing more than one DBEnvironment from the same program would be to divide the program into separate compilable files. Each source file would access a DBEnvironment. In each file, start and terminate a DBE session for the DBEnvironment accessed. Then preprocess and compile each file separately. When you invoke the preprocessor, identify the DBEnvironment accessed by the source file being preprocessed. After a file is preprocessed, it must be either saved under a different file name than the usual preprocessor output, or compiled with no linking before the next source file is preprocessed. When all source files have been preprocessed and compiled, link them together to create an executable program.

For example if you want to preprocess several ALLBASE/SQL application programs in the same group and account and compile and link the programs later, or you plan to compile a preprocessed program during a future session, you should do the following for each program:

Before running the preprocessor, equate SQLIN to the name of the file containing the application you want to preprocess:
```
   :FILE SQLIN = InFile
```

After running the preprocessor, save and rename the output files if you do not want them overwritten. For example:


   :SAVE SQLOUTPUT
   :RENAME SQLOUT, OutFile
   :SAVE SQLMOD
   :RENAME SQLMOD, ModFile
   :SAVE SQLVAR
   :RENAME SQLVAR, VarFile

When you are ready to compile the program, you must equate the include file name to its standard ALLBASE/SQL name (SQLVAR).




	NOTE: A program that accesses more than one DBEnvironment must do so in sequence since only one DBEnvironment can be accessed at a time. Such program design may adversely affect performance and requires special consideration.

To preprocess a program, or to use an already preprocessed ALLBASE/SQL application program, you must satisfy the authorization requirements for each DBEnvironment accessed.

Compiling and Linking

Figure 2-1 shows the process of compiling and linking an embedded SQL C program.

Figure 2-1 Compiling and Linking

As shown in the figure, you submit to the C compiler one or more modified source code files and the related include files created by the preprocessor. The compiler then generates object code.

To convert these object code files into an executable program, link them after compilation by invoking the link editor. This step creates an executable program file.

To expedite the process of compiling and linking your embedded SQL programs, use the preprocessor UDCs described below.

Using the Preprocessor UDCs

Two UDC's for invoking the C preprocessor are provided with ALLBASE/SQL in the HPSQLUDC.PUB.SYS file:

PC, illustrated in Figure 2-2, invokes the preprocessor in full preprocessing mode. You specify the source file name, a DBEnvironment name, and a name for SQLMSG (if you do not want preprocessor messages to go to $STDLIST).
:PC SourceFileName,DBEnvironment
The PC UDC uses the following preprocessor INFO string parameters:
- ModuleName is the name of the source file.
- OwnerName is the log-on User@Account.
- PRESERVE and DROP are in effect.
PPC, illustrated in Figure 2-3, invokes the preprocessor in full preprocessing mode, then invokes the C compiler if preprocessing is successful and the linker if compilation is successful.

To use this UDC, you specify the source file name, a DBEnvironment name, and an executable file name. You can specify a name for SQLMSG if you do not want preprocessor messages to go to $STDLIST:

   :PPC SourceFileName,DBEnvironment,ExecutableFileName

This UDC uses the following preprocessor INFO string parameters:

ModuleName is the source file name.
OwnerName is the log-on User@Account.
PRESERVE and DROP are in effect.

If you make your own version of the UDC's, do not modify the record attributes for any of the preprocessor output files. Only modify the file limit (disc=FileLimit) if required.




	NOTE: Because the UDC's purge the preprocessor message file, if messages are sent to $STDLIST an error message appears when you use the UDC's, but preprocessing continues.

Figure 2-2 UDC for Preprocessing SQLIN


PC srcfile,dbefile,msgfile=$stdlist
continue
setvar _savefence hpmsgfence
setvar hpmsgfence 2
continue
purge !msgfile
purge sqlout
purge sqlmod
purge sqlvar
purge sqltype
purge sqlextn
setvar hpmsgfence _savefence
deletevar _savefence
file sqlin  = !srcfile
file sqlmsg = !msgfile; rec=-80,16,f,ascii
file sqlout;   disc=10000,32;  rec=-80,16,f,ascii
file sqlmod;   disc=1023,10,1; rec=250,,f,binary
file sqlvar;   disc=2048,32;   rec=-80,16,f,ascii
file sqltype;  disc=2048,32;   rec=-80,16,f,ascii
file sqlextn;  disc=2048,32;   rec=-80,16,f,ascii
continue
run psqlc.pub.sys;info="!dbefile (drop)"
reset sqlin
reset sqlmsg
reset sqlout
reset sqlmod
reset sqlvar
reset sqltype
reset sqlextn

Figure 2-3 UDC for Preprocessing, Compiling, and Preparing SQLIN


PPC srcfile,dbefile,pgmfile,msgfile=$stdlist
continue
setvar _savefence hpmsgfence
setvar hpmsgfence 2
continue
purge !msgfile
purge sqlout
purge sqlmod
purge sqlvar
purge sqltype
purge sqlextn
setvar hpmsgfence _savefence
deletevar _savefence
file sqlin  = !srcfile
file sqlmsg = !msgfile; rec=-80,16,f,ascii
file sqlout;   disc=10000,32;  rec=-80,16,f,ascii
file sqlmod;   disc=1023,10,1; rec=250,,f,binary
file sqlvar;   disc=2048,32;   rec=-80,16,f,ascii
file sqltype;  disc=2048,32;   rec=-80,16,f,ascii
file sqlextn;  disc=2048,32;   rec=-80,16,f,ascii
continue
run psqlc.pub.sys;info="!dbefile (drop)"
if jcw <= warn  then
   continue
   ccxllk sqlout,!pgmfile,$null
endif
reset sqlin
reset sqlmsg
reset sqlout
reset sqlmod
reset sqlvar
reset sqltype
reset sqlextn

The example in Figure 2-4 illustrates the use of PPC on an SQLIN that could be successfully preprocessed, but failed to compile because a C error exists in the file. In addition to generating an error message for the C error, the C compiler generates several warning messages. The warning messages are normal and will not cause runtime problems; they are due to the way the C preprocessor declares some of the variables in SQLVAR.

Figure 2-4 Sample UDC Invocation


:PPC CEX2,PARTSDBE,CEX2P

                                        WED, OCT 25, 1991,  1:38 PM
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.

 SQLIN                = CEX2.SOMEGRP.SOMEACCT
 DBEnvironment        = partsdbe

 Module Name          = CEX2
1 Sections stored in DBEnvironment.

 0 ERRORS     0 WARNINGS
END OF PREPROCESSING.

END OF PROGRAM

END OF COMPILE

HP Link Editor/XL (HP30315A.04.04) Copyright Hewlett-Packard Co 1986

LinkEd> LINK FROM=$OLDPASS;RL= CCSTDRL.LIB.SYS;TO=c2p

END OF PROGRAM
:

The line number referenced in the compiler output messages is the C statement number in the compiler output listing. Because PPC sends the compiler output listing to $null, you must reinvoke the compiler, sending the compiler listing to an output file, to identify the line in error:


   :BUILD CLIST;DISC=10000,32;REC=-80,16,F,ASCII
   :CCXL SQLOUT,$OLDPASS,CLIST

The C syntax error flagged in the example under "Syntax Checking Mode" appears as follows in CLIST:


   00261             DISPAY "SELECT PartNumber, PartName and SalesPrice".

Using the Preprocessor in Job Mode

You can preprocess, compile, and prepare C ALLBASE/SQL programs in job mode. The following example illustrates a job file that uses the PPC UDC to preprocess several sample programs.

Invoking the C Preprocessor

Technical documentation

» Table of Contents

» Index

Full Preprocessing Mode

Preprocessor Syntax I

Parameters

Description

Authorization

Example

Syntax Checking Mode

Preprocessor Syntax II

Description

Authorization

Example

DBEnvironment Access

Compiling and Linking

Using the Preprocessor UDCs

Using the Preprocessor in Job Mode

Running the Program

Accessing Multiple DBEnvironments