SQLAllocStmt() allocates a new statement handle and associates it with the connection specified by the connection handle. There is no defined limit on 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.
SQLRETURN SQLAllocStmt (SQLHDBC hdbc,
SQLHSTMT *phstmt);
| Data type | Argument | Use | Description |
|---|---|---|---|
| SQLHDBC | hdbc | Input | Connection handle |
| SQLHSTMT * | phstmt | Output | Pointer to statement handle |
DB2® UDB 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, 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 UDB CLI.
If SQL_ERROR is returned, the phstmt argument is set to SQL_NULL_HSTMT. The application should call SQLError() with the same hdbc and with the hstmt argument set to SQL_NULL_HSTMT.
| 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. |
Refer to the example in SQLFetch - Fetch next row.