Connection Infrastructure

Database Independent Abstraction Layer for C: libdbi Programmer's Guide
Prev | Chapter 7. libdbi API Reference | Next

# 7.3. Connection Infrastructure

## 7.3.1. dbi_conn_new_r

``dbi_conn dbi_conn_new_r`(const char *name, dbi_inst Inst);`

Creates a connection instance of the driver specified by "name" loaded by the given libdbi instance. This is a shortcut for calling dbi_driver_open_r and passing the result to dbi_conn_open.

Arguments

  `name`: The name of the desired driver.

  `Inst`: The instance handle.

Returns

  A connection instance of the specified driver, or NULL if there was an error.

## 7.3.2. dbi_conn_new

``dbi_conn dbi_conn_new`(const char *name);`

Creates a connection instance of the driver specified by "name". This is a shortcut for calling dbi_driver_open and passing the result to dbi_conn_open.

> Note: This function is deprecated. Use dbi_conn_new_r instead.

Arguments

  `name`: The name of the desired driver.

Returns

  A connection instance of the specified driver, or NULL if there was an error.

## 7.3.3. dbi_conn_open

``dbi_conn dbi_conn_open`(dbi_driver Driver);`

Creates a connection instance of the specified driver. This connection can be used to perform queries and set options.

Arguments

  `Driver`: The target driver.

Returns

  A connection instance of the specified driver, or NULL if there was an error.

## 7.3.4. dbi_conn_close

``void dbi_conn_close`(dbi_conn Conn);`

Disconnects the specified connection connection from the database and cleans up the connection session.

Arguments

  `Conn`: The target connection.

## 7.3.5. dbi_conn_get_driver

``dbi_driver dbi_conn_get_driver`(dbi_conn Conn);`

Returns the driver type of the specified connection.

Arguments

  `Conn`: The target connection.

Returns

  The driver type of the target connection.

## 7.3.6. dbi_conn_set_option

``int dbi_conn_set_option`(dbi_conn Conn, const char *key, char *value);`

Sets a specified connection option to a string value.

Arguments

  `Conn`: The target connection.

  `key`: The name of the target setting. Must only contain alphanumerics and the underscore character.

  `value`: The string value of the target setting.

Returns

  -1 on error, 0 on success. In case of an error, the error number is DBI_ERROR_NOMEM.

## 7.3.7. dbi_conn_set_option_numeric

``int dbi_conn_set_option_numeric`(dbi_conn Conn, const char *key, int value);`

Sets a specified connection option to a numeric value.

Arguments

  `Conn`: The target connection.

  `key`: The name of the target setting. Must only contain alphanumerics and the underscore character.

  `value`: The numeric value of the target setting.

Returns

  -1 on error, 0 on success. In case of an error, the error number is DBI_ERROR_NOMEM.

## 7.3.8. dbi_conn_get_option

``const char *dbi_conn_get_option`(dbi_conn Conn, const char *key);`

Retrieves the string value of the specified option set for a connection if available.

Arguments

  `Conn`: The target connection.

  `key`: The name of the target setting.

Returns

  A read-only string with the setting, or NULL if it is not available. It is not considered an error if the setting is not available.

## 7.3.9. dbi_conn_require_option

``const char *dbi_conn_require_option`(dbi_conn Conn, const char *key);`

Retrieves the string value of the specified option set for a connection and throws an error if the option was not set.

Arguments

  `Conn`: The target connection.

  `key`: The name of the target setting.

Returns

  A read-only string with the setting, or NULL if it is not available. In the latter case, the error number is DBI_ERROR_BADNAME.

## 7.3.10. dbi_conn_get_option_numeric

``int dbi_conn_get_option_numeric`(dbi_conn Conn, const char *key);`

Retrieves the integer value of the specified option set for a connection if available.

Arguments

  `Conn`: The target connection.

  `key`: The name of the target setting.

Returns

  The value of the setting, or 0 (zero) if it is not available. It is not considered an error if the option has not been set.

## 7.3.11. dbi_conn_require_option_numeric

``int dbi_conn_require_option_numeric`(dbi_conn Conn, const char *key);`

Retrieves the integer value of the specified option set for a connection and throws an error if it is not available.

Arguments

  `Conn`: The target connection.

  `key`: The name of the target setting.

Returns

  The value of the setting, or -1 if it is not available. In the latter case, the error number is DBI_ERROR_BADNAME.

## 7.3.12. dbi_conn_get_option_list

``const char *dbi_conn_get_option_list`(dbi_conn Conn, const char *current);`

Enumerates the list of available options for a connection. If current is NULL, the first available option will be returned. If current is a valid option name, the next available option will be returned.

Arguments

  `Conn`: The target connection.

  `current`: The key name of the target option.

Returns

  The key name of the next option, or NULL if there are no more options or if there was an error. In the latter case the error number is set to DBI_ERROR_BADPTR.

## 7.3.13. dbi_conn_clear_option

``void dbi_conn_clear_option`(dbi_conn Conn, const char *key);`

Removes the target option setting from a connection. It is not considered an error if the requested option was not set before.

Arguments

  `Conn`: The target connection.

  `key`: The name of the target setting.

## 7.3.14. dbi_conn_clear_options

``void dbi_conn_clear_options`(dbi_conn Conn);`

Removes all option settings from a connection.

Arguments

  `Conn`: The target connection.

## 7.3.15. dbi_conn_cap_get

``int dbi_conn_cap_get`(dbi_conn Conn, const char *capname);`

Requests the value of a driver capability associated with the current connection. The name of the capability is specified as an argument.

Arguments

  `Conn`: The target connection.

  `capname`: A pointer to a string containing the name of the driver capability to be queried.

Returns

  The numeric value of the driver capability.

## 7.3.16. dbi_conn_get_socket

``int dbi_conn_get_socket`(dbi_conn Conn);`

Obtain the file descriptor number for the backend connection socket.

Arguments

  `Conn`: The target connection

Returns

  -1 on failure, the file descriptor number on success

## 7.3.17. dbi_conn_get_encoding

``const char *dbi_conn_get_encoding`(dbi_conn Conn);`

Requests the character encoding used by the current connection. This may be different from the encoding requested when the connection was opened, most notably if the connection option was set to "auto".

Arguments

  `Conn`: The current encoding.

Returns

  A string containing the IANA name of the connection encoding. If the encoding option was set to "auto", the function returns the encoding the database was created with. In all other cases, the current connection encoding is returned, which may be different from the database encoding. Use the dbi_driver_encoding_from_iana function to translate the encoding name to that of the currently used database engine if necessary.

## 7.3.18. dbi_conn_get_engine_version_string

``char *dbi_conn_get_engine_version_string`(dbi_conn Conn, char *versionstring);`

Requests the version of the database engine that serves the current connection as a string.

Arguments

  `Conn`: The current connection.

  `versionstring`: A string buffer that can hold at least VERSIONSTRING_LENGTH bytes.

Returns

  A string representation of the version. This will be something like "4.1.10". The result is written to the buffer that `versionstring` points to. If successful, the function returns a pointer to that buffer. If the version cannot be determined, the function returns the string "0".

  > Note: This string is useful to display the version to the user. In order to check for particular version requirements in your program, dbi_conn_get_engine_version is the better choice.

Availability

  0.8.0

## 7.3.19. dbi_conn_get_engine_version

``unsigned int dbi_conn_get_engine_version`(dbi_conn Conn);`

Requests the version of the database engine that serves the current connection in a numeric form.

Arguments

  `Conn`: The current connection.

Returns

  A numeric representation of the version. String representations of the version (e.g. "4.1.10") do not lend themselves to an easy comparison in order to find out whether a particular engine feature is already implemented. For example, a string comparison would claim that "4.1.9" is a later version than "4.1.10". Therefore libdbi computes a numeric representation of the version number [[[[A.]B.]C.]D.]E[.] according to the formula E + D*100 + C*10000 + B*1000000 + A*100000000. The resulting integers (40109 and 40110 in the example above) will be sorted correctly. Returns 0 if the version number cannot be retrieved.

Availability

  0.8.0

## 7.3.20. Error Handling

### 7.3.20.1. dbi_conn_error

``int dbi_conn_error`(dbi_conn Conn, const char **errmsg_dest);`

Returns a formatted message with the error number and description resulting from the previous database operation.

Arguments

  `Conn`: The target connection.

  `errmsg_dest`: The target string pointer, which will point to the error message. If NULL, no error message will be created, but the error number will still be returned. This string is managed by libdbi, so it must not be modified or freed. The pointer to the string is only valid until the next call to this function, so make a copy in time if you need to keep the error message.

Returns

  The error number of the most recent database operation if it resulted in an error. If not, this will return DBI_ERROR_NONE. See Chapter 4 for further information.

### 7.3.20.2. dbi_conn_error_handler

``void dbi_conn_error_handler`(dbi_conn Conn, dbi_conn_error_handler_func function, void *user_argument);`

Registers an error handler callback to be triggered whenever the database encounters an error. The callback function should perform as little work as possible, since the state in which it is called can be uncertain. The actual function declaration must accept two parameters (and return nothing):

- dbi_conn Conn: the connection object that triggered the error, from which dbi_conn_error() can be called, and

- void *user_argument: a pointer to whatever data (if any) was registered along with the handler.

To remove the error handler callback, specify NULL as the function and user_argument.

Arguments

  `Conn`: The target connection.

  `function`: A pointer to the function to call when the error handler should be triggered.

  `user_argument`: Any data to pass along to the function when it is triggered. Set to NULL if unused.

### 7.3.20.3. dbi_conn_error_flag

``dbi_error_flag dbi_conn_error_flag`(dbi_conn Conn);`

The libdbi query functions set an error flag in order to distinguish e.g. the return value "0" from a "0" returned due to an error condition. Use this function after each query that may fail to read out the error status.

Arguments

  `Conn`: The target connection.

Returns

  0 means the previous query finished without errors. A value larger than zero means an error occurred.

> Note: This function is deprecated. Use dbi_conn_error instead. Both functions return the same error code to maintain backwards compatibility.

### 7.3.20.4. dbi_conn_set_error

``int dbi_conn_set_error`(dbi_conn Conn, int errnum, const char *formatstr, ...);`

Applications may set an error status and an error message which are accessible through the libdbi error API function dbi_conn_error.

Arguments

  `Conn`: The target connection.

  `errnum`: An application-defined error code. Applications should use only positive nonzero integers to indicate errors.

  The remainder of the argument list is interpreted using a printf(3)-like syntax to define an error message.

Returns

  The length of the error message in bytes, or 0 if there was an error.

## 7.3.21. Transactions and Savepoints

### 7.3.21.1. dbi_conn_transaction_begin

``int dbi_conn_transaction_begin`(dbi_conn Conn);`

Starts a transaction.

Arguments

  `Conn`: The target connection.

Returns

  0 (zero) if successful, otherwise nonzero.

### 7.3.21.2. dbi_conn_transaction_commit

``int dbi_conn_transaction_commit`(dbi_conn Conn);`

Commits a transaction, i.e. writes all changes since the transaction was started to the database.

Arguments

  `Conn`: The target connection.

Returns

  0 (zero) if successful, otherwise nonzero.

### 7.3.21.3. dbi_conn_transaction_rollback

``int dbi_conn_transaction_rollback`(dbi_conn Conn);`

Rolls back a transaction, i.e. reverts all changes since the transaction started.

Arguments

  `Conn`: The target connection.

Returns

  0 (zero) if successful, otherwise nonzero.

### 7.3.21.4. dbi_conn_savepoint

``int dbi_conn_savepoint`(dbi_conn Conn, const char *savepoint);`

Sets a savepoint named `savepoint` within the current transaction.

Arguments

  `Conn`: The target connection.

  `savepoint`: a pointer to a string containing the name of the savepoint.

Returns

  0 (zero) if successful, otherwise nonzero.

### 7.3.21.5. dbi_conn_rollback_to_savepoint

``int dbi_conn_rollback_to_savepoint`(dbi_conn Conn, const char *savepoint);`

Rolls back all changes since the savepoint named `savepoint` was established within the current transaction.

Arguments

  `Conn`: The target connection.

  `savepoint`: a pointer to a string containing the name of the savepoint.

Returns

  0 (zero) if successful, otherwise nonzero.

### 7.3.21.6. dbi_conn_release_savepoint

``int dbi_conn_release_savepoint`(dbi_conn Conn, const char *savepoint);`

Removes the savepoint named `savepoint` within the current transaction and releases all resources associated with it. Changes can no longer be rolled back to that particular savepoint. However, changes may still be rolled back to different savepoints, or to the beginning of the entire transaction.

Arguments

  `Conn`: The target connection.

  `savepoint`: a pointer to a string containing the name of the savepoint.

Returns

  0 (zero) if successful, otherwise nonzero.

Prev | Home | Next
Driver Infrastructure | Up | SQL and Database Infrastructure