sagqprep (

int anchor,

SQL_CTR_BLOCK * sql_cb_ptr,

int statement_type,

char * stmt_id_ptr,

char * stmt_ptr

);

 

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.

 

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 following pointers are allocated when statement_type = SELECT_STMT:

sql_cb_ptr->output_sqlda_ptr

 

Once the SQLDA's have been allocated by SAGQPREP, the pointers returned may 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 About ACEAPI SQL Functions.