Invoking the C Preprocessor

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

2. Syntax checking mode: checks your SQL syntax without doing any other preprocessor tasks.

Full Preprocessing Mode

Use the following preprocessor command to:

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.

Syntax Checking Mode

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

Syntax

Authorization

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

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.

	$ psqlc DBEnvironment -m ModuleName 

	      -i SourceFileName.sql -p ModifiedSourceFileName.c

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.

Running the Preprocessor in the Background

You can run the C preprocessor in the background to free your terminal for performing other processes. In the following example, the C preprocessor is run in the background in the C shell to check the syntax of a program, and any messages usually sent to the terminal are redirected to an output file:

        $ psqlc -s -i myprogram >& myprogram.out &

The syntax for this statement may not be the same if the command is not entered in the C shell.

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. By default, any object code file name consists of the source code file name with a .o file extension.

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.

The linker is automatically invoked after compilation unless the -c compile only option is used. If you want to link multiple object code modules together to form one executable program, list the object code modules following the C compiler command, followed by the library options.

If each of the object code modules has a .o file extension, the module will not be recompiled. If you do not use the -o compiler option to specify a specific output file name for the linked output, a file named a.out is created by default.

In the following example, an executable program named someprog.r is created after a module named somemod is stored by the C preprocessor in a DBEnvironment named somedbe:

	login: pgmr1

              .

              .

              .

	$ psqlc somedbe -m somemod -i mysource.sql -p mysource.c

              .

              .

              .

	$ cc mysource.c -lsql -lcl -lportnls -o someprog.r

The options used are:

	300/400: login: pgmr1 . . . $ psqlc somedbe -m somemod -i mysource.sql -p mysource.c . . . $ cc mysource.c -lsql -lheap2 -lportnls -lpc -o someprog.r The options used are: -lsql, to link the ALLBASE/SQL runtime library, in /usr/lib/libsql.a -lheap2, to link the random heap space management routines, in /usr/lib/libheap2.a -lportnls, to link the native language routines, in /usr/lib/libprotnls.a -lpc, to link the Pascal runtime library, in /usr/lib/libpc.a -o, to create the executable output file someprog.r

Running the Program

When an ALLBASE/SQL program is first created, it can only be executed by the module OWNER or a DBA. In addition, it can only operate on the DBEnvironment used at preprocessing time if a module was generated. If no module was generated because the SQL commands embedded in the program are only commands for which no sections are created, the program can be run against any DBEnvironment.

The program created in the previous example can be executed as follows by the module owner:

	$ someprog.r

To make the program executable by other users in other DBEnvironments:

Accessing Multiple DBEnvironments

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 compiled so that no linking is performed before the next source file is preprocessed. When all source files have been preprocessed and compiled, link them together to create an executable program. An example of this technique follows:

	$ psqlc DBEnvironment1 -i SourceFileName1.sql -p 				ModifiedSourceFileName1.c

	      .

	      .

	$ cc -c ModifiedSourceFileName1.c

	      .

	      .

	$ psqlc DBEnvironment2 -i SourceFileName2.sql -p 		ModifiedSourceFileName2.c

	      .

	      .

	$ cc -c ModifiedSourceFileName2.c

                              .

                              .

	$ cc ModifiedSourceFileName1.o ModifiedSourceFileName2.o -lsql -lcl -lportnls

  -o ExecutableFileName

	300/400: $ cc ModifiedSourceFileName1.o ModifiedSourceFileName2.o -lsql -lheap2 -lportnls -lpc -o ExecutableFileName

Note that a program which 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.