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

4.3.1. Main Functions

FQexec

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.

FQexecParams

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:

conn

The connection object to send the command through.

command

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.

nParams

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.

paramTypes[]

(currently unused)

paramValues[]

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

paramLengths[]

(currently unused)

paramFormats[]

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.

resultFormat

(currently unused)

FQprepare

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:

conn

The connection object to send the command through.

command

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.

nParams

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.

paramTypes[]

(currently unused)

FQexecPrepared

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

FQdeallocatePrepared

Deallocate a prepared statement previously created with FQprepare >.

void FQdeallocatePrepared(FBconn *conn, FBresult *result)

Call before executing FQclear >.

FQexecTransaction

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.

FQclear

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

4.3.2. Result Handling Functions

FQresultStatus

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"

FQresStatus

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

char *FQresStatus(FQexecStatusType status);

FQsqlCode

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.

FQntuples

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

int FQntuples(const FBresult *res);

FQnfields

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

int FQnfields(const FBresult *res);

FQgetvalue

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 .

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.

FQfhasNull

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.

FQfmaxwidth

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

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

FQfname

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

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

FQgetlength

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.

FQgetdsplen

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.

FQfformat

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.

FQftype

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.

4.3.3. Transaction Handling Functions

FQsetAutocommit

Set the connection's autocommit status.

void FQsetAutocommit(FBconn *conn, bool autocommit);

FQstartTransaction

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

FQcommitTransaction

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

FQtransactionStatusType FQcommitTransaction(FBconn *conn);

FQrollbackTransaction

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

FQtransactionStatusType FQrollbackTransaction(FBconn *conn);

FQisActiveTransaction

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

bool FQisActiveTransaction(FBconn *conn);

4.3.4. Error Handling Functions

FQerrorMessage

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

char *FQerrorMessage(const FBconn *conn);

FQresultErrorMessage

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

char *FQresultErrorMessage(const FBresult *result);

FQresultErrorField

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.

FQresultErrorFieldsAsString

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.