SQLPrepare

SQLPrepare

This prepares a SQL string for execution.

SQLPrepareW() as a Unicode string supports same execution as SQLPrepare().

Syntax

SQLRETURN  SQLPrepare (
    SQLHSTMT        stmt,
    SQLCHAR *       sql,
    SQLSMALLINT         sqlLength );

Arguments

Data Type	Argument	In/Out	Description
SQLHSTMT	stmt	Input	Statement handle
SQLCHAR *	sql	Input	SQL text string column
SQLSMALLINT	sqlLength	Input	The length, in bytes, of the contents of the sql argument

Return Values

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR

Description

An application calls SQLPrepare() to send a SQL statement to the database. The application may include more than one parameter markers (?) in the SQL statement. To include the parameter marker, an application inserts the parameter marker in the SQL character string at a proper position.

Once the statement is ready, an application calls the function. To refer to the statement, use the statement handle. The statements related to the statement handle can be executed again when an application calls SQLFreeStmt() using SQL_DROP option to release the statement or when the statement handle is used again to call SQLPrepare(), SQLExecDirect(), or catalog function such like SQLColumns(), SQLTables(). Once an application prepares the statement, an application an request information about the result set format. Calling SQLDescribeCol() after SQLPrepare() may not be as effective as calling it after SQLExecute() or SQLExecDirect().

The ODBC data type will be inspected when the command is executed (in case not all parameters are bound.) For maximum inter-operation, an application must unbound all parameters applied to the previous SQL statement before the same command prepares a new SQL statement. This prevents errors that occur due to pervious parameters applied to new information.

Diagnosis

SQLSTATE	Description	Comments
08003		When stmt is not connected or the connection is released
08S01	Communication channel error	Communication channel failure before the function processing is completed between the Altibase CLI driver and the database
HY000	General error
HY001	Memory allocation error	Cannot allocate the requested memory for the Altibase CLI driver to execute the function and complete execution.
HY009	Use an invalid pointer (null pointer)	sql is a NULL pointer

Related Functions

SQLAllocHandle
SQLBindCol
SQLBindParameter
SQLEndTran
SQLExecDirect
SQLExecute
SQLRowCount

Example

< Refer to: $ALTIBASE_HOME/sample/SQLCLI/demo_ex2.cpp >

sprintf(query,"INSERT INTO DEMO_EX2 VALUES( ?, ?, ?, ?, ?, ? )");

/*  Prepare for a statement and bind the variable.  */
if (SQLPrepare(stmt, query, SQL_NTS) != SQL_SUCCESS)
{
    execute_err(dbc, stmt, query);
    SQLFreeStmt(stmt, SQL_DROP);
    return SQL_ERROR;
}