SQLPrepare--Prepare a statement

Purpose

Specification:

CLI 1.1

ODBC 1.0

ISO CLI

SQLPrepare() associates an SQL statement with the input statement handle and sends the statement to the DBMS to be prepared. The application can reference this prepared statement by passing the statement handle to other functions.

If the statement handle is previously used with a query statement (or any function that returns a result set), SQLFreeStmt() must be called before calling SQLPrepare().

Syntax

SQLRETURN   SQLPrepare       (SQLHSTMT          StatementHandle,   /* hstmt */
                              SQLCHAR      FAR  *StatementText,    /* szSqlStr */
                              SQLINTEGER        TextLength);       /* cbSqlStr */

Function arguments

Tabelle 74. SQLPrepare arguments

Data type	Argument	Use	Description
SQLHSTMT	`StatementHandle`	input	Statement handle.
SQLCHAR	`StatementText`	input	SQL statement string
SQLINTEGER	`TextLength`	input	Length of contents of `StatementText` argument. This must be set to either the exact length of the SQL statement in `szSqlstr`, or to SQL_NTS if the statement text is null-terminated.

Usage

After a statement is prepared using SQLPrepare(), the application can request information about the format of the result set (if the statement is a query) by calling either:

SQLNumResultCols()
SQLDescribeCol()

The SQL statement string might contain parameter markers. A parameter marker is represented by a ? character and is used to indicate a position in the statement in which an application-supplied value is to be substituted when SQLExecute() is called. The bind parameter function, SQLBindParameter(), binds (associates) application values with each parameter marker and indicates if any data conversion should be performed at the time the data is transferred.

All parameters must be bound before calling SQLExecute(). For more information, refer to SQLExecute--Execute a statement.

Refer to the section on the PREPARE statement in the DB2 Universal Database SQL Reference for information on rules related to parameter markers.

After the application processes the results from the SQLExecute() call, the application can execute the statement again with new (or the same) parameter values.

Return codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

Tabelle 75. SQLPrepare SQLSTATEs

SQLSTATE	Description	Explanation
42nnn	Syntax Error.	42nnn SQLSTATEs indicate a variety of syntax or access problems with the statement. The characters nnn refer to any SQLSTATE with that class code. Example: 42nnn refers to any SQLSTATE in the 42 class.
58004	Unexpected system failure.	Unrecoverable system error.
HY001	Memory allocation failure.	DB2 CLI is unable to allocate memory required to support execution or completion of the function.
HY009	Invalid argument value.	`StatementText` is a null pointer.
HY013	Unexpected memory handling error.	DB2 CLI is unable to access memory required to support execution or completion of the function.
HY014	No more handles.	DB2 CLI is unable to allocate a handle due to internal resources.
HY090	Invalid string or buffer length.	The argument `TextLength` is less than one, but not equal to SQL_NTS.

Restrictions

None.

Zugehörige Referenzen