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.