4.3. Command Execution Functions

Submits a command to the server and waits for the result. Note that only one query can be provided.

FBresult *FQexec(FBconn *conn, const char *stmt);

Returns a FBresult pointer, or NULL when no server connection available.

See FQexecParams for executing a parameterized query.

Execute a parameterized query.

Note that this query's function signature matches that of PostgreSQL's PQexecParams(), but not all arguments are currently used.

FBresult *
FQexecParams(FBconn *conn,
			 const char *stmt,
			 int nParams,
			 const int *paramTypes,
			 const char * const *paramValues,
			 const int *paramLengths,
			 const int *paramFormats,
			 int resultFormat);

The function arguments are:

Creates a prepared statement with the given parameters for later execution with FQexecPrepared >.

FBresult *FQprepare(FBconn *conn, const char *stmt, int nParams, const int *paramTypes)

Execute FQclear > to deallocate the statement.

The function arguments are:

Executes a prepared statement previously created with FQprepare >. using the provided parameter values.

FBresult *FQexecPrepared(FBconn *conn, FBresult *result, int nParams, const char * const *paramValues, const int *paramLengths, const int *paramFormats, int resultFormat)

FQexecPrepared is like FQexecParams >, but the command to be executed is specified by passing a FBresult object previously created with FQprepare >, instead of passing a query string. This feature allows commands that will be used repeatedly to be parsed and planned just once, rather than each time they are executed.

The parameters are identical to FQexecParams >, except thata FBresult object is provided instead of a query string, and the paramTypes[] parameter is not present.

Once the prepared statement is no longer required, execute FQdeallocatePrepared > before executing FQclear >.

Deallocate a prepared statement previously created with FQprepare >.

void FQdeallocatePrepared(FBconn *conn, FBresult *result)

Call before executing FQclear >.

Convenience function to execute a query using the internal transaction handle

FBresult *FQexecTransaction(FBconn *conn, const char *stmt)

This is primary useful for client applications which accept queries as user input, and need to execute their own internal queries without disturbing the user transaction.

Free the storage attached to an FBresult object. Never free() the object itself as that will result in dangling pointers and memory leaks.

void FQclear(FBresult *res);

Returns the result status of the previously execute command.

FQexecStatusType FQresultStatus(const FBresult *res);

Following status values are defined:

	"FBRES_NO_ACTION",
	"FBRES_EMPTY_QUERY",
	"FBRES_COMMAND_OK",
	"FBRES_TUPLES_OK",
	"FBRES_TRANSACTION_START",
	"FBRES_TRANSACTION_COMMIT",
	"FBRES_TRANSACTION_ROLLBACK",
	"FBRES_BAD_RESPONSE",
	"FBRES_NONFATAL_ERROR",
	"FBRES_FATAL_ERROR"

Converts the enumerated type returned by FQresultStatus into a string constant describing the status code.

char *FQresStatus(FQexecStatusType status);

Returns the Firebird SQL code associated with the query result as an integer.

int FQsqlCode(const FBresult *res);

See here for a full list: https://firebirdsql.org/file/documentation/reference_manuals/fblangref25-en/html/fblangref25-appx02-sqlcodes.html

In addition, libfq defines following additional codes:

• -1: query OK
• -2: no result

Returns the number of tuples (rows) in the provided result. If no query has been executed, -1 is returned.

int FQntuples(const FBresult *res);

Returns the number of columns (fields) in the provided result. If no query has been executed, -1 is returned.

int FQnfields(const FBresult *res);

Returns a single field of an FBresult.

char *FQgetvalue(const FBresult *res, int row_number, int column_number);

Row and column numbers start at 0.

Tests a field for a NULL value. Row and column numbers start at 0. This function returns 1 if the field is NULL and 0 if it contains a non-NULL value.

int FQgetisnull(const FBresult *res, int row_number, int column_number);

Note that libpq's PQgetvalue() returns an empty string if the field contains a NULL value; FQgetvalue() returns NULL, but will also return NULL if invalid parameters are provided, so FQgetisnull() will provide a definitive result.

Determine if for the provided column number, the result set contains at least one NULL.

bool FQfhasNull(const FBresult *res, int column_number);

Not to be confused with FQgetisnull , which determines the NULL status for the given column of a particular result tuple.

Provides the maximum width of a column in single character units.

int FQfmaxwidth(const FBresult *res, int column_number);

Provides the name (or alias, if set) of a particular field (column).

char *FQfname(const FBresult *res, int column_number);

Get length in bytes of a particular tuple column.

int FQgetlength(const FBresult *res, int row_number, int column_number);

Row and column numbers start at 0.

Returns the display length in single characters of the specified FBresult field.

int FQgetdsplen(const FBresult *res, int row_number, int column_number);

Row and column numbers start at 0.

Returns the format code indicating the format of the given column.

short FQfformat(const FBresult *res, int column_number);

Following values can be returned:

   0 - text
   1 - binary
  -1 - invalid column specification

Column numbers start at 0.

Returns the data type associated with the given column number.

short FQftype(const FBresult *res, int column_number);

The data type will be an integer corresponding to one of the SQL_* constants defined in ibase.h (and repeated in libfq.h), extended with the following pseudo-types for convenience:

   - SQL_INVALID_TYPE
   - SQL_DB_KEY

Column numbers start at 0.

Set the connection's autocommit status.

void FQsetAutocommit(FBconn *conn, bool autocommit);

Start a transaction using the connection's default transaction handle.

FQtransactionStatusType FQstartTransaction(FBconn *conn);

FQtransactionStatusType can be one of two values:

• TRANS_OK
• TRANS_ERROR

Commit a transaction using the connection's default transaction handle.

FQtransactionStatusType FQcommitTransaction(FBconn *conn);

Roll back a tranaction using the connection's default transaction handle.

FQtransactionStatusType FQrollbackTransaction(FBconn *conn);

Indicates whether the provided connection has been marked as being in a user-initiated transaction.

bool FQisActiveTransaction(FBconn *conn);

Returns the most recent error message associated with the connection, or an empty string.

char *FQerrorMessage(const FBconn *conn);

Returns the error message associated with the result, or an empty string.

char *FQresultErrorMessage(const FBresult *result);

Returns an individual field of an error report, or NULL.

char *FQresultErrorField(const FBresult *res, FQdiagType fieldcode);

Valid fieldcode values are:

• FB_DIAG_MESSAGE_TYPE
• FB_DIAG_MESSAGE_PRIMARY
• FB_DIAG_MESSAGE_DETAIL
• FB_DIAG_OTHER
• FB_DIAG_DEBUG

FB_DIAG_DEBUG will not normally be displayed; it will contain a message generated by libfq with details about the context where the error was encountered.

Return all error fields formatted as a multiline string, each line prefixed with the provided value.

char *FQresultErrorFieldsAsString(const FBresult *res, char *prefix);

Caller must free the returned pointer.