SAGQPREP
Description
The SAGQPREP function prepares and describes the statement given in stmt_ptr. The result can be accessed with the statement id stmt_id_ptr.
Both static and dynamic SQLDA structures are supported.
Example
sagqprep (
int anchor,
SQL_CTR_BLOCK * sql_cb_ptr,
int statement_type,
char * stmt_id_ptr,
char * stmt_ptr
);
Static SQLDA
The input and/or output SQLDA structures of the correct size must be allocated by the application, and be appropriately initialized. The sqldaid field in the SQLDA structure may contain any value except the seven byte reserved value SQLDADA, which identifies a dynamically allocated SQLDA.
A call to SAGQPREP requires:
sql_cb_ptr->input_sqlda_ptr = API_INPUT_SQLDA ;
sql_cb_ptr->output_sqlda_ptr = API_OUTPUT_SQLDA ;
A static SQLDA cannot be freed or reallocated by ACEAPI; the application must ensure that sufficient storage has been allocated to contain the results for all input/output values returned by the call to SAGQPREP. The sqln value must not exceed the number of SQLVAR occurrences provided in the SQLDA, otherwise unpredictable results may occur.
The sqld value contains the number of columns in the referenced table or view.
If the sqln value is smaller than the number of columns required for the referenced table or view, SAGQPREP will return with SQLCODE = -9985 (Unable to allocate/free memory).
Dynamic SQLDA
Dynamic SQLDA structures are allocated by SAGQPREP and not by the application.
The sqldaid field in the SQLDA structure contains the seven byte reserved value SQLDADA. Do not change this field; it identifies a dynamically allocated SQLDA. The eighth byte of the field may be modified by the application.
The initial call to SAGQPREP requires :
sql_cb_ptr->input_sqlda_ptr = NULL
sql_cb_ptr->output_sqlda_ptr = NULL
If any of the following pointers are NULL, they will be allocated:
sql_cb_ptr->input_sqlda_ptr sql_cb_ptr->output_sqlda_ptr The sql_cb_ptr->output_sqlda_ptr pointer is allocated when statement_type = SELECT_STMT:
Once the SQLDAs have been allocated by SAGQPREP, the pointers returned can be used for subsequent calls to SAGQPREP until permanently deallocated by a call to SAGQDEAL.
Dynamic SQLDA structures are always allocated with the correct number of input/output values required by the statement. The sqln value indicates the number of SQLVAR occurrences provided in the SQLDA. The sqld value will contain the number of columns in the referenced table or view.
Use the latest input/output pointers returned by SAGQPREP for the statement because the previous pointers may have been reallocated and no longer valid.
statement_type | SELECT_STMT (5) | The statement being prepared is 'SELECT'. |
OTHER_STMT (99) or NULL | The statement being prepared is not 'SELECT'. |
sql_cb_ptr->input_sqlda_ptr | Static SQLDA - SQLDA structure allocated by the application. Dynamic SQLDA - SQLDA structure, the result of the SAGQPREP function. |
sql_cb_ptr->output_sqlda_ptr | Static SQLDA - SQLDA structure allocated by the application. Dynamic SQLDA - SQLDA structure, the result of the SAGQPREP function. |
stmt_id_ptr | The statement id for the statement to be prepared. |
stmt_ptr | The statement to be prepared and described. |
For information about anchor (required by each SAGQ* SQL function), see the
ACEAPI SQL Functions page.