SQLAllocStmt - Allocate a statement handle
SQLAllocStmt()
allocates a new statement
handle and associates it with the connection specified by the connection
handle. There is no defined limit to the number of statement handles
that can be allocated at any one time.
SQLConnect()
must
be called before calling this function.
This function must be
called before SQLBindParam()
, SQLPrepare()
, SQLExecute()
, SQLExecDirect()
,
or any other function that has a statement handle as one of its input
arguments.
Syntax
SQLRETURN SQLAllocStmt (SQLHDBC hdbc,
SQLHSTMT *phstmt);
Function arguments
Data type | Argument | Use | Description |
---|---|---|---|
SQLHDBC | hdbc | Input | Connection handle |
SQLHSTMT * | phstmt | Output | Pointer to statement handle |
Usage
Db2® for i CLI uses each statement handle to relate all the descriptors, result values, cursor information, and status information to the SQL statement processed. Although each SQL statement must have a statement handle, you can reuse the handles for different statements.
A call to this function requires that hdbc references an active database connection.
To process a positioned UPDATE or DELETE statement, the application must use different statement handles for the SELECT statement and the UPDATE or DELETE statement.
If the input pointer to the statement handle (phstmt)
points to a valid statement handle allocated by a previous call to SQLAllocStmt()
,
then the original value is overwritten as a result of this call. This
is an application programming error and is not detected by Db2 for
i CLI.
Return codes
- SQL_SUCCESS
- SQL_ERROR
- SQL_INVALID_HANDLE
If SQL_ERROR is returned, the phstmt argument
is set to SQL_NULL_HSTMT. The application should call SQLError()
with
the same hdbc argument and with the hstmt argument set
to SQL_NULL_HSTMT.
Diagnostics
SQLSTATE | Description | Explanation |
---|---|---|
08003 | Connection not open | The connection specified by the hdbc argument is not open. The connection must be established successfully (and the connection must be open) for the driver to allocate an hstmt. |
40003 * | Statement completion unknown | The communication link between the CLI and the data source fails before the function completes processing. |
58004 | System error | Unrecoverable system error. |
HY001 | Memory allocation failure | The driver is unable to allocate memory required to support the processing or completion of the function. |
HY009 | Argument value that is not valid | phstmt is a null pointer. |
HY013 * | Memory management problem | The driver is unable to access memory required to support the processing or completion of the function. |
Example
Refer to the example in SQLFetch - Fetch next row.