isc_dsql_execute_immediate()

Go Up to API Function Reference

Prepares and executes just once a DSQL statement that does not return data. There is a special case of isc_dsql_execute_immediate() for creating databases. For more information about creating and populating the XSQLDA, see Understanding the XSQLDA. To check for an InterBase error, examine the first two elements of the status vector directly. For more information about examining the status vector, see Handling Error Conditions.

Syntax

ISC_STATUS isc_dsql_execute_immediate( ISC_STATUS *status_vector, isc_db_handle *db_handle, isc_tr_handle *trans_handle, unsigned short length, char *statement, unsigned short dialect, XSQLDA *xsqlda);

Note: In the special case where the statement is CREATE DATABASE, there is no transaction, so db_handle and trans_handle must be pointers to handles whose value is NULL. When isc_dsql_execute_immediate() returns, db_handle is a valid handle, just as though you had made a call to isc_attach_database().

Parameter	Type	Description
`status_vector`	`ISC_STATUS` `*`	Pointer to the error status vector
`db_handle`	`isc_db_handle *`	If <statement> is not `CREATE DATABASE`, this is a pointer to a database handle set by a previous call to `isc_attach_database`()`; db_handle` returns an error in `status_vector` if it is `NULL`. If <statement> is `CREATE DATABASE`, this must point to a database handle whose value is `NULL`.
`trans_handle`	`isc_tr_handle *`	If <statement> is not `CREATE DATABASE`, this is a pointer to a transaction handle whose value has been set by a previous `isc_start_transaction()` call; `trans_handle` returns an error if `NULL`. If <statement> is `CREATE DATABASE` or `SET TRANSACTION`, this must point to a transaction handle whose value is `NULL`.
`length`	`unsigned short`	Length of the DSQL statement in bytes; set to 0 in C programs to indicate a null-terminated string
`statement`	`char *`	DSQL string to be executed
`dialect`	`unsigned short`	Indicates the SQL dialect of `statement` Must be less than or equal to the SQL dialect of the client
`xsqlda`	`XSQLDA` `*`	Pointer to an optional, previously allocated `XSQLDA` used for input; if you do not supply input parameters, set this value to `NULL`

Description

isc_dsql_execute_immediate() prepares the DSQL statement specified in <statement>, executes it once, and discards it. The statement must not be one that returns data (that is, it must not be a SELECT or EXECUTE PROCEDURE statement).

If <statement> requires input parameter values (that is, if it contains parameter markers), these values must be supplied in the input XSQLDA, xsqlda.

To create a database using isc_dsql_execute_immediate(), supply a CREATE DATABASE statement and have db_handle and trans_handle point to handles with a NULL value.

Tip: If statement returns data, or if it needs to be executed more than once, use isc_dsql_prepare() and isc_dsql_execute() (or isc_dsql_execute2()) instead of isc_dsql_execute_immediate().

Note: You must call isc_dsql_execute_immediate() rather than isc_dsql_prepare() and isc_dsql_execute() for CREATE DATABASE or SET TRANSACTION. To start a transaction, you also have the option of using isc_start_transaction().

Examples

The following program fragment calls isc_dsql_execute_immediate() to perform an insert:

#include <ibase.h>
ISC_STATUS status_vector[20];
char *insert_stmt = "INSERT INTO CUSTOMER(CUSTNAME, BAL, CUSTNO)
VALUES("John Smith", 299.0, 5050)";

isc_dsql_execute_immediate( status_vector,
&database_handle, /* Set in previous isc_attach_database() call. */
&tr_handle, /* Set in previous isc_start_transaction() call. */
0, insert_stmt, 1, NULL);
if (status_vector[0] == 1 && status_vector[1]) {
/* Process error. */
isc_print_status(status_vector);
return(1);
}

The following C/C++ code fragment uses isc_dsql_execute_immediate() to create a database and return a handle to the new database:

#include <ibase.h>
ISC_STATUS status_vector[20];
char *statement = "CREATE DATABASE 'C:/INVENTORY.IB' PAGE_SIZE 4096
USER 'SYSDBA' PASSWORD 'masterkey'";
isc_db_handle db_handle = NULL;
isc_tr_handle dummy_handle = NULL;

isc_dsql_execute_immediate( status_vector, &db_handle, &dummy_handle,
0, statement, 1, NULL);
if (status_vector[0] == 1 && status_vector[1]) {
/* Process error. */
isc_print_status(status_vector);
return(1);
}

Return value

isc_dsql_execute_immediate() returns the second element of the status vector. Zero indicates success. A nonzero value indicates an error. For InterBase errors, the first element of the status vector is set to 1, and the second element is set to isc_bad_db_handle, isc_bad_trans_handle, or another InterBase error code.

To check for an InterBase error, examine the first two elements of the status vector directly. For more information about examining the status vector, see Handling Error Conditions.

Advance To:

isc_dsql_exec_immed2()