DB2 Version 9.7 for Linux, UNIX, and Windows

sqlaprep API - Precompile application program

Processes an application program source file containing embedded SQL statements. A modified source file is produced containing host language calls for the SQL statements and, by default, a package is created in the database.

Scope

This API can be called from any database partition server in db2nodes.cfg. It updates the database catalogs on the catalog partition. Its effects are visible to all database partition servers.

Authorization

One of the following authorizations:

DBADM authority
If EXPLAIN ONLY is specified, EXPLAIN authority or an authority that implicitly includes EXPLAIN is sufficient.
If SQLERROR CHECK or EXPLAIN ONLY is specified, either EXPLAIN or SQLADM authority is sufficient.
If a package does not exist, BINDADD authority and:
- If the schema name of the package does not exist, IMPLICIT_SCHEMA authority on the database.
- If the schema name of the package does exist, CREATEIN privilege on the schema.
If the package exists, one of the following privileges:
- ALTERIN privilege on the schema
- BIND privilege on the package

In addition, if capturing explain information using the EXPLAIN or the EXPLSNAP clause, one of the following authorizations is required:

INSERT privilege on the explain tables
DATAACCESS authority

The user also needs all privileges required to compile any static SQL statements in the application. Privileges granted to groups are not used for authorization checking of static statements.

Required connection

Database

API include file

sql.h

API and data structure syntax

SQL_API_RC SQL_API_FN
  sqlaprep (
        _SQLOLDCHAR * pProgramName,
        _SQLOLDCHAR * pMsgFileName,
        struct sqlopt * pPrepOptions,
        struct sqlca * pSqlca);

SQL_API_RC SQL_API_FN
  sqlgprep (
        unsigned short MsgFileNameLen,
        unsigned short ProgramNameLen,
        struct sqlca * pSqlca,
        struct sqlopt * pPrepOptions,
        _SQLOLDCHAR * pMsgFileName,
        _SQLOLDCHAR * pProgramName);

sqlaprep API parameters

pProgramName

Input. A string containing the name of the application to be precompiled. Use the following extensions:

.sqb: for COBOL applications
.sqc: for C applications
.sqC: for UNIX C++ applications
.sqf: for FORTRAN applications
.sqx: for C++ applications

When the TARGET option is used, the input file name extension does not have to be from this predefined list.

The preferred extension for C++ applications containing embedded SQL on UNIX based systems is sqC; however, the sqx convention, which was invented for systems that are not case sensitive, is tolerated by UNIX based systems.

pMsgFileName

Input. A string containing the destination for error, warning, and informational messages. Can be the path and the name of an operating system file, or a standard device. If a file already exists, it is overwritten. If it does not exist, a file is created.

pPrepOptions

Input. A structure used to pass precompile options to the API. For more information about this structure, see SQLOPT.

pSqlca

Output. A pointer to the sqlca structure.

sqlgprep API-specific parameters

MsgFileNameLen: Input. Length in bytes of the pMsgFileName parameter.
ProgramNameLen: Input. Length in bytes of the pProgramName parameter.

Usage notes

A modified source file is produced, which contains host language equivalents to the SQL statements. By default, a package is created in the database to which a connection has been established. The name of the package is the same as the program file name (minus the extension and folded to uppercase), up to a maximum of 8 characters.

Following connection to a database, sqlaprep executes under the transaction that was started. PRECOMPILE PROGRAM then issues a COMMIT or a ROLLBACK operation to terminate the current transaction and start another one.

Precompiling stops if a fatal error or more than 100 errors occur. If a fatal error does occur, PRECOMPILE PROGRAM stops precompiling, attempts to close all files, and discards the package.

The Precompile option types and values are defined in sql.h.

When using the PRECOMPILE command or sqlaprep API, the name of the package can be specified with the PACKAGE USING option. When using this option, up to 128 bytes may be specified for the package name. When this option is not used, the name of the package is generated by the precompiler. The name of the application program source file (minus extension and folded to uppercase) is used up to a maximum of 8 characters. The name generated will continue to have a maximum of 8 bytes to be compatible with previous versions of DB2®.

REXX API syntax

This API can be called from REXX through the SQLDB2 interface.