3.3. Command Execution Functions

Once a connection to a database server has been successfully established, the functions described here are used to execute SQL queries and commands, and retrieve the results.

3.3.1. Main 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:


The connection object to send the command through.


The SQL command string to be executed. If parameters are used, they are provided in command string as ? placeholders, which will be replaced sequentially by the provided parameter values.


The number of parameters supplied; it is the length of the arrays paramTypes[], paramValues[], paramLengths[], and paramFormats[].

Note: currently this argument is advisory, however it may be used in a future release.


(currently unused)


Specifies the actual values of the parameters. A NULL pointer in this array means the corresponding parameter is NULL; otherwise the pointer points to a zero-terminated text string (for text format).


(currently unused)


Optional array to specify whether parameters are passed as text strings (array entry is 0) or a text string to be converted to an RDB$DB_KEY value (array entry is -1).

Binary formats may be supported in the future.


(currently unused)


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);

3.3.2. Result Handling Functions


Returns the result status of the previously execute command.

FQexecStatusType FQresultStatus(const FBresult *res);

Following status values are defined:



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

Note: The SQL codes are usually negative values, and each code covers a wide range of errors. A more precise GDSCODE is also available, it is hoped to make this available if feasible.


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.

Note: This function will return NULL if invalid row/column parameters are provided, as well as when the tuple value is actually NULL. To definitively determine if a tuple value is NULL, use FQgetisnull .


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:


Column numbers start at 0.

3.3.3. Transaction Handling Functions


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:



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);

3.3.4. Error Handling Functions


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_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.