The ODBC Driver supports SQL_C_GUID and SQL_GUID data types for the following DBMS data types:

The ODBC data type called GUID for "Globally Unique Identifier" is mapped to the DBMS data type of UUID for "Universally Unique Identifier". They are roughly equivalent. They have the same display format and the same internal binary length.

The display format is 36 characters long:

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

where x's are alphanumeric (0-9, a-f) hex representations of the internal fields within the GUID.

The internal format is 16 bytes of binary values, consisting of a few integer type fields followed by a binary array of 8 bytes. The ODBC SQLGUID structure defines the integer and binary fields within this structure.

There is a subtle difference in the internal format for ODBC GUID versus DBMS UUID. The ODBC GUID (structure SQLGUID) contains 3 integer fields at the beginning which are in platform-endianness format, whereas the DBMS UUID internal format exposed to applications is simply a 16-byte binary object and the 3 integer fields are always in big-endian format regardless of the platform.

For ODBC applications that wish to access the internal format, it is recommended to use the ODBC SQLGUID structure and map the C type to SQL_C_GUID. This will provide consistent results across different DBMS's. This pertains to both sending parameters for a query as well as selecting results. The SQL (DBMS) data type in general would be SQL_GUID, which is an Ingres or Vector column defined as UUID.

The GUID/UUID data type can also be handled in the display format. A conversion is done between the internal and display formats when the C and the SQL data types are different; specifically, if one is a character data type and the other is the GUID or UUID data type. For example, if a DBMS character column contains a valid UUID display format string, it can be selected into a SQL_C_GUID data type in the application. Conversely, an application with a SQL_C_CHAR data type containing a GUID display format string can be sent to the DBMS to update a UUID column, by binding the SQL type to SQL_GUID.

The default C type for a SQL type of SQL_GUID (that is, UUID in the database) is SQL_C_GUID.

In the rare case that the raw binary value of the DBMS internal format of a UUID column is desired, then the column (or parameter) should be bound to a C type of SQL_C_BINARY. This will copy the internal DBMS value, without accounting for platform endianness.

Conversions to or from GUID/UUID and other data types besides the above are not supported and will result in a conversion error. For example, a DBMS UUID column cannot be selected into a C date or integer data type.

Sometimes an ODBC application needs to know information about items in the database, such as tables, permissions, primary keys, and so on. The ODBC Driver supports all ODBC functions pertaining to this information. The following table summarizes the functions available:

All ODBC functions return an error code. Both the ODBC Driver and the Driver Manager cache a list of any errors encountered. The list of errors is deleted when the next ODBC function is called.

A return of SQL_SUCCESS means that the function completed successfully. A return of SQL_ERROR means that an error occurred. A return of SQL_SUCCESS_WITH_INFO can be considered a warning or informational status code. SQL_INVALID_HANDLE means that the handle passed to the function was invalid.

More information on a status of SQL_ERROR or SQL_SUCCESS_WITH_INFO can be retrieved from the SQLGetDiagRec() function. The following example code snippet returns error information on a call to SQLConnect().

If ingPWD was an invalid password, the following errors would be displayed from the above code:

The SQLSTATE reference is specific to ODBC and does not correlate to SQLSTATE in Ingres. The Native Error Code is an Ingres error code, viewable from the errhelp utility:

An ODBC application can simply terminate after executing its queries, but this is considered poor programming practice. The DBMS server cannot distinguish between a program that exited without cleaning up and a program that aborted due to a serious error. As a result, spurious errors are reported in the error log.

To disconnect gracefully from the database, call SQLDisconnect():

The ODBC function SQLFreeStmt() is used to close a cursor or free all resources associated with a statement handle:

A call to SQLFreeStmt() with an argument of SQL_DROP implicitly closes the cursor before freeing resources.

The generic SQLFreeHandle() function can be used with all types of handles:

A call to SQLFreeHandle() with a handle type argument of SQL_HANDLE_STMT is the equivalent of calling SQLFreeStmt() with an argument of SQL_DROP.

Once a handle has been freed, the corresponding allocate function must be re-invoked to initialize resources associated with the handle.

ODBC connection pooling is a method of sharing active database connections with similar or identical connection characteristics. When a connection is released through a call to SQLDisconnect(), the connection is left open and added to a pool of active connections.

When an ODBC application opens a new connection, the application searches the pool for a connection with matching connection characteristics. If a match is found, the connection from the pool is used "under the covers" instead of creating a new connection. If a match is not found, a new connection is opened.

ODBC connection pooling can improve performance significantly because an ODBC application can take a long time to connect relative to the time it takes to process data.

ODBC pooled connections can be shared with single or multi-threaded ODBC applications, but are not shared between separate ODBC applications.

ODBC connection pooling is activated by invoking SQLSetEnvAttr() with the attribute SQL_ATTR_CONNECTION_POOLING, and with the directives SQL_CP_ONE_PER_DRIVER or SQL_CP_ONE_PER_HENV.

SQL_CP_ONE_PER_DRIVER means that there is only one connection pool for the entire ODBC application, regardless of the number of connections. If only one environment handle is allocated, SQL_CP_ONE_PER_DRIVER is essentially the same as SQL_CP_ONE_PER_HENV.

If multiple environment handles are allocated, it may make more sense to specify SQL_CP_ONE_PER_HENV, especially if the connections associated with each environment have similar characteristics. This directive will create multiple pools, each with a smaller number of connections to search through.

The SQLSetEnvAttr() function allows the ODBC application to specify match criteria for objects in the connection pool.

Connection objects with "strict" criteria must have identical connection specifiers for connection attributes specified in the connection string from SQLDriverConnect(). "Strict" is the only option supported, and other specifications are ignored.

"Relaxed" match criteria do not apply to SQLDriverConnect() in the Ingres ODBC CLI. If a relaxed match criterion is specified, only key connection attributes must match. For the ODBC CLI, the following minimum attributes must match, if specified:

The following connection string attributes are ignored for relaxed match criteria:

ODBC pooled connections can be configured to time out to prevent an unmanageable number of connections in the pool.

By default, the Ingres ODBC CLI allows connections to remain in the pool as long as the ODBC application is active. You can override the default connection pool timeout value using the Ingres ODBC Administrator (iiodbcadmin) on Linux.