HP 3000 Manuals HP 3000 Manuals
Invoking the C Preprocessor
You can use the preprocessor in two modes:
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.
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
{MODULE(ModuleName)}
{OWNER (OwnerName) }
RUN PSQLC.PUB.SYS;INFO= "DBEnvironmentName [({{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
1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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.
8. 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
1. The preprocessor does not access a DBEnvironment when it is run in
this mode.
2. 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.
3. 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.
![[]](../../pic3k/M011754/FFN153c50.gif)
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.
________________________________________________________
| |
| 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-2. UDC for Preprocessing 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 |
________________________________________________________
Figure 2-3. UDC for Preprocessing, Compiling, and Preparing SQLIN
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.
___________________________________________________________________________
| |
| :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 |
| : |
___________________________________________________________________________
Figure 2-4. Sample UDC Invocation
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.
!JOB JIM,MGR.HPDB,CPROG;OUTCLASS=,1
!ppc cexp01,PartsDBE,cexp01p
!ppc cexp01a,PartsDBE,cexp01ap
!ppc cexp02,PartsDBE,cexp02p
.
.
!ppc cexp50,PartsDBE,cexp50p
!TELL JIM,MGR.HPDB; C Preprocessing is complete!
!EOJ''
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:
: run someprog
To make the program executable by other users in other DBEnvironments:
* Load the executable program file onto the machine where the
production DBEnvironment resides.
* Install any related module in the production DBEnvironment.
* Ensure necessary module owner authorities exist.
* Grant required authorities to program users.
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:
:RUN PSQLC.PUB.SYS;INFO="DBEnvironment1 (MODULE (ModuleName))"
:CCXL SQLOUT, SQLOBJ1
.
.
:RUN PSQLC.PUB.SYS;INFO="DBEnvironment2 (MODULE (ModuleName))"
:CCXL SQLOUT, SQLOBJ2
.
.
:LINK FROM=SQLOBJ1,SQLOBJ2;RL=STDRL.LIB.SYS;TO=SOMEPROG
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.