ODBTP Client Library

ODBTP -- Client Library

ODB Login Types

Type	Description
ODB_LOGIN_NORMAL	Login using a normal database connection. Normal connections are pooled and reusable by all clients.
ODB_LOGIN_RESERVED	Login using a reserved database connection. Reserved connections are pooled and reusable only by the clients that reserved them. This connection type is typically useed by clients that may need to reuse the same database connection after disconnecting from the server. This is usually the case for some web-based applications.
ODB_LOGIN_SINGLE	Login using a process that handles a single database connection. This login type causes the server to operate in a mullt-process mode. It should only be used for databases whose ODBC drivers are not thread safe.

ODB Attributes

Attribute	Type	Description
ODB_ATTR_CACHEPROCS	Long	Determines if prepared procedure information should be cached. If the value is set to 0, then the cache will not be used.
ODB_ATTR_DATABASENAME	String	Database name [read only].
ODB_ATTR_DBMSNAME	String	DBMS name [read only].
ODB_ATTR_DBMSVER	String	DBMS version [read only].
ODB_ATTR_DESCRIBEPARAMS	Long	Used to determine whether or not ODBTP server should try to describe parameters after preparing a query. If the value is set to 0, the server will not try to describe the parameters.
ODB_ATTR_DRIVER	Long	Driver type [read only]. Valid types are: ODB_DRIVER_UNKNOWN ODB_DRIVER_MSSQL ODB_DRIVER_JET ODB_DRIVER_FOXPRO ODB_DRIVER_ORACLE ODB_DRIVER_SYBASE ODB_DRIVER_DB2 ODB_DRIVER_MYSQL
ODB_ATTR_DRIVERNAME	String	Driver name [read only].
ODB_ATTR_DRIVERODBCVER	String	Driver ODBC version [read only].
ODB_ATTR_DRIVERVER	String	Driver version [read only].
ODB_ATTR_DSN	String	Data source name [read only].
ODB_ATTR_FETCHROWCOUNT	Long	Number of rows returned by the server per fetch row request. This attribute applies only to forward-only cursors, and is used to improve performance. Only one row per request is sent by the server for static, keyset and dynamic cursors.
ODB_ATTR_FULLCOLINFO	Long	Used to determine whether or not full column info should be sent. If the value is set to 0, then minimal column info will be sent.
ODB_ATTR_MAPCHARTOWCHAR	Long	Determines if character data types should be mapped to wide character. If the value is set to 0, then the mapping will not be performed.
ODB_ATTR_OICLEVEL	Long	ODBC interface conformance level [read only]. Possible values are: ODB_OIC_CORE ODB_OIC_LEVEL1 ODB_OIC_LEVEL2
ODB_ATTR_QUERYTIMEOUT	Long	Query execution timeout in seconds.
ODB_ATTR_RIGHTTRIMTEXT	Long	Used to determine whether or not trailing space characters should be removed from text data during retrieval. If the value is set to 0, text data will not be trimmed by the server.
ODB_ATTR_SERVERNAME	String	Database server name [read only].
ODB_ATTR_TRANSACTIONS	Long	Transaction type used for queries. Valid types are: ODB_TXN_NONE ODB_TXN_DEFAULT ODB_TXN_READUNCOMMITTED ODB_TXN_READCOMMITTED ODB_TXN_REPEATABLEREAD ODB_TXN_SERIALIZABLE
ODB_ATTR_TXNCAPABLE	Long	Indicates whether or not ODBC driver supports transactions [read only]. 1 if yes, and 0 if no.
ODB_ATTR_UNICODESQL	Long	Used to determine whether or not SQL query strings should be submitted using UTF8 encoded UNICODE characters. If the value is set to 0, then normal characters should be used.
ODB_ATTR_USERNAME	String	Database user name [read only].
ODB_ATTR_VARDATASIZE	Long	Maximum size of buffer for variable length data if it is not explicitly specified when binding a column or parameter.

ODB Data Types

Type	SQL Type	Default Type
ODB_BINARY	binary, varbinary, image	ODB_BINARY
ODB_BIGINT	bigint	ODB_BIGINT
ODB_UBIGINT
ODB_BIT	bit	ODB_BIT
ODB_CHAR	char, varchar, text	ODB_CHAR
ODB_DATE
ODB_DATETIME	smalldatetime, datetime	ODB_DATETIME
ODB_DOUBLE	float	ODB_DOUBLE
ODB_GUID	uniqueidentifier	ODB_GUID
ODB_INT	int	ODB_INT
ODB_UINT
ODB_NUMERIC	decimal, numeric	ODB_CHAR
ODB_REAL	real	ODB_REAL
ODB_SMALLINT	smallint	ODB_SMALLINT
ODB_USMALLINT
ODB_TIME
ODB_TINYINT
ODB_UTINYINT	tinyint	ODB_UTINYINT
ODB_WCHAR	nchar, nvarchar, ntext	ODB_WCHAR

NOTE: SQL Type is the corresponding SQL data type, and Default Type is the default ODB data type chosen by the server for the SQL data type. The default ODB data type for SQL data types not listed in the above table is ODB_CHAR.

ODB Parameter Types

Type	Description
ODB_PARAM_NONE	Indicates that parameter is undefined.
ODB_PARAM_INPUT	Indicates that parameter is used for input.
ODB_PARAM_OUTPUT	Indicates that parameter is used for output.
ODB_PARAM_INOUT	Indicates that parameter is used for input and output.
ODB_PARAM_RETURNVAL	Indicates that parameter is a stored procedure's return value.
ODB_PARAM_RESULTCOL	Indicates that parameter is a result column.

ODB Column Info Flags

Flag	Description
ODB_COLINFO_NOTNULL	Column does not allow nulls.
ODB_COLINFO_UNSIGNED	Column data type is an unsigned type.
ODB_COLINFO_AUTONUMBER	Auto increment or identity column.
ODB_COLINFO_PRIMARYKEY	Column is primary key
ODB_COLINFO_HIDDEN	Hidden column

ODB Cursor Types

Type	Description
ODB_CURSOR_FORWARD	Forward-only cursor. This is the default cursor type, and does not support scrolling or row operations.
ODB_CURSOR_STATIC	Static (read-only) cursor. This cursor supports scrolling, and row operations that do not modify the underlying data.
ODB_CURSOR_KEYSET	Keyset cursor. This cursor supports scrolling, and all row operations.
ODB_CURSOR_DYNAMIC	Dynamic cursor. This cursor supports scrolling, and all row operations.

ODB Cursor Concurrency Types

Type	Description
ODB_CONCUR_DEFAULT	Use to specify default concurrency for a cursor. The default concurrency for forward-only and static cursors is read-only, and row version for keyset and dynamic cursors.
ODB_CONCUR_READONLY	Use to specify read-only concurrency for a cursor.
ODB_CONCUR_LOCK	Use to specify scroll lock concurrency for a cursor.
ODB_CONCUR_ROWVER	Use to specify row version concurrency for a cursor.
ODB_CONCUR_VALUES	Use to specify value-based concurrency for a cursor.

ODB Row Status Values

Status	Description
ODB_ROWSTAT_ERROR	An error occurred for row.
ODB_ROWSTAT_SUCCESS	Successfully fetched row.
ODB_ROWSTAT_UPDATED	Row was updated.
ODB_ROWSTAT_DELETED	Row was deleted.
ODB_ROWSTAT_ADDED	Row was added.
ODB_ROWSTAT_NOROW	Not a valid row.
ODB_ROWSTAT_UNKNOWN	Status of row is unknown or could not be determined.

FUNCTIONS

odbAllocate

Allocate a connection or query object.

odbHANDLE odbAllocate (
  odbHANDLE hCon
);

Parameters

hCon: [in] Handle to a connection object.

Return Values

If successful, returns the handle to the allocated odject, or NULL if an error occurs.

Remarks

All connection and query objects must be allocated before they can be used by any other functions. This function is used to allocate both connection and query objects.

odbBindCol

Bind result column to specified data type.

odbBOOL odbBindCol (
  odbHANDLE hQry,
  odbUSHORT usCol,
  odbSHORT  sDataType,
  odbLONG   lDataLen,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).
sDataType: [in] ODB data type to be used for bind. Set this value to 0 to use the default ODB data type.
lDataLen: [in] Length of data to be used for bind. Set this value to 0 if binding to a fixed length data type.
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

Normally this function does not need to be called because all columns are automatically bound by the server. The default data type chosen for the bind is one that allows the column data to be easily used within virtually all environments. For example, ODB_CHAR is chosen for columns of type bigint, because provisions for 64-bit integers are not always available. Use this function to change the data type binding for a column.

odbBindInOutParam

Bind input/output parameter to specified data type.

odbBOOL odbBindInOutParam (
  odbHANDLE hQry,
  odbUSHORT usParam,
  odbSHORT  sDataType,
  odbLONG   lDataLen,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).
sDataType: [in] ODB data type to be used for bind. Set this value to 0 to use the default ODB data type.
lDataLen: [in] Length of data to be used for bind. Set this value to 0 if binding to a fixed length data type.
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

After preparing a query and before executing it, call this function to bind an input/output parameter.

odbBindInputParam

Bind input parameter to specified data type.

odbBOOL odbBindInputParam (
  odbHANDLE hQry,
  odbUSHORT usParam,
  odbSHORT  sDataType,
  odbLONG   lDataLen,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).
sDataType: [in] ODB data type to be used for bind. Set this value to 0 to use the default ODB data type.
lDataLen: [in] Length of data to be used for bind. Set this value to 0 if binding to a fixed length data type.
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

After preparing a query and before executing it, call this function to bind an input parameter.

odbBindOutputParam

Bind output parameter to specified data type.

odbBOOL odbBindOutputParam (
  odbHANDLE hQry,
  odbUSHORT usParam,
  odbSHORT  sDataType,
  odbLONG   lDataLen,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).
sDataType: [in] ODB data type to be used for bind. Set this value to 0 to use the default ODB data type.
lDataLen: [in] Length of data to be used for bind. Set this value to 0 if binding to a fixed length data type.
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

After preparing a query and before executing it, call this function to bind an output parameter.

odbBindParam

Bind parameter to specified data type.

odbBOOL odbBindParam (
  odbHANDLE hQry,
  odbUSHORT usParam,
  odbUSHORT usType,
  odbSHORT  sDataType,
  odbLONG   lDataLen,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).
usType: [in] ODB parameter type.
sDataType: [in] ODB data type to be used for bind. Set this value to 0 to use the default ODB data type.
lDataLen: [in] Length of data to be used for bind. Set this value to 0 if binding to a fixed length data type.
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

After preparing a query and before executing it, call this function to bind a parameter. Parameter binding should normally be performed with odbBindInOutParam, odbBindInputParam, and/or odbBindOutputParam.

odbBindParamEx

Bind parameter to specified data type.

odbBOOL odbBindParamEx (
  odbHANDLE hQry,
  odbUSHORT usParam,
  odbUSHORT usType,
  odbSHORT  sDataType,
  odbLONG   lDataLen,
  odbSHORT  sSqlType,
  odbULONG  ulColSize,
  odbSHORT  sDecDigits,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).
usType: [in] ODB parameter type.
sDataType: [in] ODB data type to be used for bind. Set this value to 0 to use the default ODB data type.
lDataLen: [in] Length of data to be used for bind. Set this value to 0 if binding to a fixed length data type.
sSqlType: [in] SQL type of parameter.
ulColSize: [in] The size of the column or expression of the corresponding parameter marker.
sDecDigits: [in] The decimal digits of the column or expression of the corresponding parameter marker
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

After preparing a query and before executing it, call this function to bind a parameter. Use this function if the paramter was not automatically described by the ODBTP service.

odbColActualLen

Obtain actual length of fetched column.

odbLONG odbColActualLen (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns the actual length of the column data.

Remarks

This function can be used to determine the actual length of a truncated column.

odbColBaseName

Get column base name.

odbPCSTR odbColBaseName (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns a pointer to the column base name text, or returns NULL if an error occurs.

Remarks

Call this function to get the base name of a column. The returned value is a pointer to data stored in the column buffer, and will be invalid if the buffer is reinitialized.

odbColCatalog

Get column's catalog.

odbPCSTR odbColCatalog (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns a pointer to the column's catalog name, or returns NULL if an error occurs.

Remarks

Call this function to get the catalog, or database, corresponding to the column. The returned value is a pointer to data stored in the column buffer, and will be invalid if the buffer is reinitialized.

odbColData

Obtain fetched column data.

odbPVOID odbColData (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns a pointer to the column data. Note, that while NULL is a legitimate return value, it will also be returned if an error occurs.

Remarks

This function is used to obtain the data from a column regardless of the ODB data type to which it is bound. The returned value is a pointer to data stored in the row buffer, and will be invalid if the buffer is reinitialized.

odbColDataByte

Obtain fetched column data as byte.

odbBYTE odbColDataByte (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns the byte value of the column. Note, that while 0 is a legitimate return value, it will also be returned if the column value is NULL or an error occurs.

Remarks

This function should be used to obtain data from columns bound to ODB data types ODB_BIT, ODB_TINYINT or ODB_UTINYINT.

odbColDataDouble

Obtain fetched column data as double.

odbDOUBLE odbColDataDouble (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns the double value of the column. Note, that while 0.0 is a legitimate return value, it will also be returned if the column value is NULL or an error occurs.

Remarks

This function should be used to obtain data from columns bound to ODB data type ODB_DOUBLE.

odbColDataFloat

Obtain fetched column data as float.

odbFLOAT odbColDataFloat (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns the float value of the column. Note, that while 0.0 is a legitimate return value, it will also be returned if the column value is NULL or an error occurs.

Remarks

This function should be used to obtain data from columns bound to ODB data type ODB_REAL.

odbColDataLen

Obtain fetched column data length.

odbLONG odbColDataLen (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns the byte length of the column data. It will return ODB_NULL if the column value is NULL or an error occurs.

Remarks

This function is usually used to determine whether or not a column's data value is NULL. If the value of a column is NULL, then the data length is equal to ODB_NULL.

odbColDataLong

Obtain fetched column data as long.

odbULONG odbColDataLong (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns the long value of the column. Note, that while 0 is a legitimate return value, it will also be returned if the column value is NULL or an error occurs.

Remarks

This function should be used to obtain data from columns bound to ODB data types ODB_INT or ODB_UINT.

odbColDataLongLong

Obtain fetched column data as long long (64-bit integer).

odbULONGLONG odbColDataLongLong (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns the long long value of the column. Note, that while 0 is a legitimate return value, it will also be returned if the column value is NULL or an error occurs.

Remarks

This function should be used to obtain data from columns bound to ODB data types ODB_BIGINT or ODB_UBIGINT.

odbColDataShort

Obtain fetched column data as short.

odbUSHORT odbColDataShort (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns the short value of the column. Note, that while 0 is a legitimate return value, it will also be returned if the column value is NULL or an error occurs.

Remarks

This function should be used to obtain data from columns bound to ODB data types ODB_SMALLINT or ODB_USMALLINT.

odbColDataText

Obtain fetched column data as text.

odbPSTR odbColDataText (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns a pointer to the text value of the column. Note, that while a pointer to zero length text ("") is a legitimate return value, it will also be returned if the column value is NULL or an error occurs.

Remarks

This function should be used to obtain data from columns bound to ODB data types ODB_CHAR or ODB_WCHAR. The returned value is a pointer to data stored in the row buffer, and will be invalid if the buffer is reinitialized.

odbColDataTimestamp

Obtain fetched column data as ODB timestamp.

odbPTIMESTAMP odbColDataTimestamp (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns a pointer to the ODB timestamp value of the column. Note, a zeroed ODB timestamp will be returned if the column value is NULL or an error occurs.

Remarks

This function should be used to obtain data from columns bound to ODB data type ODB_DATETIME. The returned value is a pointer to data stored in the row buffer, and will be invalid if the buffer is reinitialized.

odbColDataType

Get column data type.

odbSHORT odbColDataType (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns the column's ODB data type or 0 if an error occurs.

Remarks

This function is used to determine the ODB data type to which a column is bound. This value will be the same as the value returned by odbColDefaultDataType, unless it is changed with odbBindCol.

odbColDecDigits

Get decimal digits or precision of column.

odbSHORT odbColDecDigits (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns the column's decimal digits.

Remarks

This function is used to determine a column's decimal digits or precision.

odbColDefaultDataType

Get column default data type.

odbSHORT odbColDefaultDataType (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns the column's default ODB data type, or 0 if an error occurs.

Remarks

This is the default ODB data type that was used when the column was automatically bound by the server. This is also the ODB data type that will be used if it is not explicitly specified when calling odbBindCol.

odbColFlags

Get column info flags.

odbULONG odbColFlags (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns the ODB column info flags of the specified column.

Remarks

ODB column info flags can be used to determine additional details about a column.

odbColName

Get column name.

odbPCSTR odbColName (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns a pointer to the column name text, or returns NULL if an error occurs.

Remarks

Call this function to get the name of a column. The returned value is a pointer to data stored in the column buffer, and will be invalid if the buffer is reinitialized.

odbColNum

Get column number corresponding to name.

odbUSHORT odbColNum (
  odbHANDLE hQry,
  odbPCSTR  pszName
);

Parameters

hQry: [in] Handle to a query object.
pszName: [in] Name of column.

Return Values

Returns column number corresponding to the specified name, or returns 0 if an error occurs.

Remarks

Call this function to get the column number corresponding to a column name.

odbColSchema

Get column's schema.

odbPCSTR odbColSchema (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns a pointer to the column's schema name, or returns NULL if an error occurs.

Remarks

Call this function to get the schema, or owner, corresponding to the column. The returned value is a pointer to data stored in the column buffer, and will be invalid if the buffer is reinitialized.

odbColSize

Get column size.

odbULONG odbColSize (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns the max character size of the column, or returns 0 if an error occurs.

Remarks

This value is the maximum character size of the column if it is bound to the ODB data type ODB_CHAR.

odbColSqlType

Get SQL type of column.

odbSHORT odbColSqlType (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns the column's SQL type.

Remarks

This function is used to determine a column's SQL type.

odbColSqlTypeName

Get SQL type name of column.

odbSHORT odbColSqlTypeName (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns the column's SQL type name. The returned value is a pointer to data stored in the column buffer, and will be invalid if the buffer is reinitialized.

Remarks

This function is used to determine a column's SQL type name.

odbColTable

Get column's table.

odbPCSTR odbColTable (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns a pointer to the column's table name, or returns NULL if an error occurs.

Remarks

Call this function to get the table corresponding to the column. The returned value is a pointer to data stored in the column buffer, and will be invalid if the buffer is reinitialized.

odbColTruncated

Determine if column was truncated.

odbBOOL odbColTruncated (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns non-zero if column data was truncated.

Remarks

Use this function to determine if a column's data was truncated.

odbColUserData

Get column's user defined data.

odbPVOID odbColUserData (
  odbHANDLE hQry,
  odbUSHORT usCol
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).

Return Values

Returns the pointer representing the column's user defined data.

Remarks

This function is used to return a column's user defined data. Use odbSetColUserData to assign user defined data for a column.

odbCommit

Commit current transaction.

odbBOOL odbCommit (
  odbHANDLE hCon
);

Parameters

hCon: [in] Handle to a connection object.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

If transactions have been enabled, call this function to commit any transactions since the last commit or rollback. Transactions are enabled by setting the ODB attribute ODB_ATTR_TRANSACTIONS to a value other than ODB_TXN_NONE.

odbConvertAll

Convert all column data to character format.

odbBOOL odbConvertAll (
  odbHANDLE hCon,
  odbBOOL   bConvert
);

Parameters

hCon: [in] Handle to a connection object.
bConvert: [in] Set to TRUE to convert column data, or FALSE to not convert column data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function determines whether or not all result column data from subsequent queries will be converted to character format. This is achieved by binding all columns to the ODB data type ODB_CHAR.

odbConvertDatetime

Convert all datetime column data to character format.

odbBOOL odbConvertDatetime (
  odbHANDLE hCon,
  odbBOOL   bConvert
);

Parameters

hCon: [in] Handle to a connection object.
bConvert: [in] Set to TRUE to convert column data, or FALSE to not convert column data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function determines whether or not all result datetime column data from subsequent queries will be converted to character format. This is achieved by binding all columns to the ODB data type ODB_CHAR.

odbConvertGuid

Convert all GUID (uniqueindentifier) column data to character format.

odbBOOL odbConvertGuid (
  odbHANDLE hCon,
  odbBOOL   bConvert
);

Parameters

hCon: [in] Handle to a connection object.
bConvert: [in] Set to TRUE to convert column data, or FALSE to not convert column data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function determines whether or not all result GUID column data from subsequent queries will be converted to character format. This is achieved by binding all columns to the ODB data type ODB_CHAR.

odbCTimeToTimestamp

Convert C time to ODB timestamp.

void odbCTimeToTimestamp (
  odbPTIMESTAMP ptsTime,
  odbLONG       lTime
);

Parameters

ptsTime: [out] Pointer to ODB timestamp variable to store conversion of C time.
lTime: [in] C time value to be converted to ODB timestamp.

Return Values

This function does not return a value.

Remarks

Use this function to convert a C time value to an ODB timestamp value. This function is provided so that datetime data can be processed with C time functions.

odbDescribeSqlType

Describe SQL type.

odbBOOL odbDescribeSqlType (
  odbPCSTR  pszSqlTypeName,
  odbPSHORT psSqlType,
  odbPULONG pulColSize,
  odbPSHORT psDecDigits
);

Parameters

pszSqlTypeName: [in] Pointer to string containing name of SQL type to be described.
psSqlType: [out] Pointer to variable to store numeric equivalent of SQL type name.
pulColSize: [out] Pointer to variable to store column size of SQL type.
psDecDigits: [out] Pointer to variable to store decimal digits or precision of SQL type.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to describe a SQL type from its name. The returned data can be then be used with odbBindParamEx.

odbDetachQry

Detach query object from its connection object.

odbBOOL odbDetachQry (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

Use this function to detach a query object from its connection object. This allows cached results (see odbUseRowCache) associated with the query object to be retained offline. The detached object cannot be used to execute another query, and must be explicitly freed with odbFree.

odbDropQry

Drop query resource maintained by server.

odbBOOL odbDropQry (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function can be used to drop the underlying remote query resource maintained by the ODBTP service. The state of the local query object is not changed by this function.

odbExecute

Execute query.

odbBOOL odbExecute (
  odbHANDLE hQry,
  odbPCSTR  pszSQL
);

Parameters

hQry: [in] Handle to a query object.
pszSQL: [in] SQL (Query) string to be executed. Set this value to NULL to execute a previosly prepared query or procedure.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to execute a query. This function reinitializes the column and row buffers during its operation. The parameter and parameter info buffers will also be reinitialized if the value of pszSQL is not NULL. If the query returns a result set, the corresponding column info is stored in the column buffer.

odbFetchNextResult

Fetch next query result.

odbBOOL odbFetchNextResult (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to fetch the next result from a previously executed query. This function reinitializes the column and row buffers during its operation. If the next result returns a result set, the corresponding column info is stored in the column buffer.

odbFetchRow

Fetch query result row.

odbBOOL odbFetchRow (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to fetch a row from a result set. The function reinitializes the row buffer, and then stores the fetched data, if any, into the buffer. This function is typically used when a cursor has not been specified with odbSetCursor.

odbFetchRowAbs

Fetch query result row absolutely.

odbBOOL odbFetchRowAbs (
  odbHANDLE hQry,
  odbLONG   lRow
);

Parameters

hQry: [in] Handle to a query object.
lRow: [in] Row to be fetched.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to fetch a row absolutely from a result set. The function reinitializes the row buffer, and then stores the fetched data, if any, into the buffer. This function can only be used if a static, keyset or dynamic cursor was specified with odbSetCursor.

odbFetchRowBookmark

Fetch query result row relative to bookmarked row.

odbBOOL odbFetchRowBookmark (
  odbHANDLE hQry,
  odbLONG   lRowOffset
);

Parameters

hQry: [in] Handle to a query object.
lRowOffset: [in] Offset of row to be fetched relative to bookmarked row.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to fetch a row relative to a bookmarked row from a result set. The function reinitializes the row buffer, and then stores the fetched data, if any, into the buffer. This function can only be used if bookmark support was enabled when a static, keyset or dynamic cursor was specified with odbSetCursor.

odbFetchRowFirst

Fetch first query result row.

odbBOOL odbFetchRowFirst (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to fetch the first row from a result set. The function reinitializes the row buffer, and then stores the fetched data, if any, into the buffer. This function can only be used if a static, keyset or dynamic cursor was specified with odbSetCursor.

odbFetchRowLast

Fetch last query result row.

odbBOOL odbFetchRowLast (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to fetch the last row from a result set. The function reinitializes the row buffer, and then stores the fetched data, if any, into the buffer. This function can only be used if a static, keyset or dynamic cursor was specified with odbSetCursor.

odbFetchRowNext

Fetch next query result row.

odbBOOL odbFetchRowNext (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to fetch the next row from a result set. The function reinitializes the row buffer, and then stores the fetched data, if any, into the buffer. This function can only be used if a static, keyset or dynamic cursor was specified with odbSetCursor.

odbFetchRowPrev

Fetch previous query result row.

odbBOOL odbFetchRowPrev (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to fetch the previous row from a result set. The function reinitializes the row buffer, and then stores the fetched data, if any, into the buffer. This function can only be used if a static, keyset or dynamic cursor was specified with odbSetCursor.

odbFetchRowRel

Fetch query result row relative to current row.

odbBOOL odbFetchRowRel (
  odbHANDLE hQry,
  odbLONG   lRowOffset
);

Parameters

hQry: [in] Handle to a query object.
lRowOffset: [in] Offset of row to be fetched relative to current row.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to fetch a row relative to the current row from a result set. The function reinitializes the row buffer, and then stores the fetched data, if any, into the buffer. This function can only be used if a static, keyset or dynamic cursor was specified with odbSetCursor.

odbFetchRowReread

Reread last fetched query result row.

odbBOOL odbFetchRowReread (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to reread the last fetched row from a result set. The function reinitializes the row buffer, and then stores the fetched data, if any, into the buffer. This function can only be used if a static, keyset or dynamic cursor was specified with odbSetCursor or if the value of the ODB attribute ODB_ATTR_FETCHROWCOUNT is set to 1.

odbFetchRowsIntoCache

Fetch rows into memory.

odbBOOL odbFetchRowsIntoCache (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function can be used to fetch multiple rows from the current result set into the row cache. The row cache must be enabled with odbUseRowCache prior to executing this function. Cached rows can be scrolled even if a cursor was not enabled or is not supported.

odbFinalizeRequest

Finalize client request.

odbBOOL odbFinalizeRequest (
  odbHANDLE hOdb
);

Parameters

hOdb: [in] Handle to a connection or query object.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to finalize a batched client request. Batched client requests are made with functions like odbBindCol, odbSetCol, odbBindParam and odbSetParam.

odbFree

Free previously allocated connection or query object.

void odbFree (
  odbHANDLE hOdb
);

Parameters

hOdb: [in] Handle to a connection or query object.

Return Values

This function does not return a value.

Remarks

Use this function to free any connection or query objects that were allocated with odbAllocate. If the object to be freed is a connection object, then any associated query objects will also be freed.

odbGetAttrLong

Get long ODB attribute value.

odbBOOL odbGetAttrLong (
  odbHANDLE hCon,
  odbLONG   lAttr,
  odbPULONG pulVal
);

Parameters

hCon: [in] Handle to a connection object.
lAttr: [in] ODB attribute.
pulVal: [out] Pointer to long variable to store long attribute value.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

Use this function to retrieve any ODB attribute whose value is a number.

odbGetAttrText

Get text ODB attribute value.

odbBOOL odbGetAttrText (
  odbHANDLE hCon,
  odbLONG   lAttr,
  odbPSTR   pszVal,
  odbULONG  ulValLen
);

Parameters

hCon: [in] Handle to a connection object.
lAttr: [in] ODB attribute.
pszVal: [out] Pointer to text buffer to store text attribute value.
ulValLen: [in] Length of text buffer to store text value.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

Use this function to retrieve any ODB attribute whose value is a text string.

odbGetConnection

Get connection object associated with query object.

odbHANDLE odbGetConnection (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns a handle to a connection object, or returns NULL if an error occurs.

Remarks

This function returns the connection object that was used to allocate the specified query object with odbAllocate.

odbGetConnectionId

Get connection Id.

odbPCSTR odbGetConnectionId (
  odbHANDLE hCon
);

Parameters

hCon: [in] Handle to a connection object.

Return Values

Returns a pointer to the retrieved connection id text, or returns NULL if an error occurs.

Remarks

The Id of a connection object is assigned by the server. Use this function to retrieve this value. The value returned is a pointer to the ODBTP response, and will be invalid upon the next ODBTP request. This value should be used as the database connection string when reconnecting to a reserved connection with odbLogin.

odbGetError

Get last error code.

odbULONG odbGetError (
  odbHANDLE hOdb
);

Parameters

hOdb: [in] Handle to a connection or query object.

Return Values

Returns the numeric value of the current error.

Remarks

This is the numerical value of the error generated by the last function. If no error occurred, then this value is equal to 0.

odbGetErrorText

Get last error text.

odbPCSTR odbGetErrorText (
  odbHANDLE hOdb
);

Parameters

hOdb: [in] Handle to a connection or query object.

Return Values

Returns a pointer to the text corresponding to the current error.

Remarks

This is the text value of the error generated by the last function. If the numeric value of the error is ODBTPERR_SERVER, then the return value is a pointer to the ODBTP response. If this is the case, then the value will be invalid upon the next ODBTP request.

odbGetFirstQry

Get first query object associated with connection object.

odbHANDLE odbGetFirstQry (
  odbHANDLE hCon
);

Parameters

hCon: [in] Handle to a connection object.

Return Values

Returns the handle to the first query object allocated with connection object. It returns NULL if no query objects have been allocated or an error occurs.

Remarks

Call this function to begin iterating the query objects associated with a connection object. Call odbGetNextQry to obtain the remaining query objects.

odbGetNextQry

Get next query object associated with connection object.

odbHANDLE odbGetNextQry (
  odbHANDLE hCon
);

Parameters

hCon: [in] Handle to a connection object.

Return Values

Returns the handle to the next query object allocated with connection object. It returns NULL if there are no more allocated query objects or an error occurs.

Remarks

After calling odbGetFirstQry, call this function to obtain the subsequent query objects associated with a connection object.

odbGetOutputParams

Get output parameter values.

odbBOOL odbGetOutputParams (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to retrieve all output parameter data values from the server. The parameter buffer is reinitialized, and the retrieved data is placed in the buffer. To obtain the parameter data values, use odbParamData and/or its variants.

odbGetParam

Get parameter value.

odbBOOL odbGetParam (
  odbHANDLE hQry,
  odbUSHORT usParam,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to retrieve any parameter data values from the server. The parameter buffer is reinitialized upon the completion of this request, and the retrieved data is placed in the buffer. To obtain the parameter data values, use odbParamData and/or its variants.

odbGetQuery

Get query object associated with connection object.

odbHANDLE odbGetQuery (
  odbHANDLE hCon,
  odbULONG  ulQryId
);

Parameters

hCon: [in] Handle to a connection object.
ulQryId: [in] Id of query object.

Return Values

Returns the handle to the query object corresponding to the specified Id. It returns NULL if an error occurs.

Remarks

This function is used to restore a query that is still being maintained by the server. If a reserved connection is closed without disconnecting the database, the states of all open queries are maintained by the server. After reconnecting to the server with a reserved connection, call this function to allocate and reestablish the query object.

odbGetQueryId

Get query Id.

odbULONG odbGetQueryId (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns the query object's Id. It returns 0xFFFFFFFF if an error occurs.

Remarks

This value should be obtained if the associated query object needs to be reestablished after reconnecting to the server. This is only useful when using reserved connections.

odbGetResponse

Get current response data.

odbPVOID odbGetResponse (
  odbHANDLE hOdb
);

Parameters

hOdb: [in] Handle to a connection or query object.

Return Values

Returns a pointer to the buffer containing the current response data.

Remarks

The value returned is a pointer to the current ODBTP response, and will be invalid upon the next ODBTP request. Under normal circumstances, this function would never be called.

odbGetResponseCode

Get current response code.

odbULONG odbGetResponseCode (
  odbHANDLE hOdb
);

Parameters

hOdb: [in] Handle to a connection or query object.

Return Values

Returns the current ODBTP response code.

Remarks

The value returned is the current ODBTP response code, Under normal circumstances, this function would never be called.

odbGetResponseSize

Get current response data size.

odbULONG odbGetResponseSize (
  odbHANDLE hOdb
);

Parameters

hOdb: [in] Handle to a connection or query object.

Return Values

Returns the size of the current response data.

Remarks

The value returned is the size in bytes of the current ODBTP response. Under normal circumstances, this function would never be called.

odbGetRowCacheSize

Get current size of row cache.

odbULONG odbGetRowCacheSize (
  odbHANDLE hCon
);

Parameters

hCon: [in] Handle to a connection object.

Return Values

Returns the maximum number rows that can be stored from a query's result set into its row cache. Returns 0xFFFFFFFF if an error occurs.

Remarks

Gets the maximum number of rows that can be stored in the row cache of uery objects attached to the specified connection object. This value is set when enabling row cache usage with odbUseRowCache.

odbGetRowCount

Get query result affected row count.

odbLONG odbGetRowCount (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns the number of affected rows. It returns 0 if there are no rows or an error occurs.

Remarks

This value is normally valid after all rows have been fetched from a result set, or if the query does not generate a result set.

odbGetRowStatus

Get the ODB row status of the currently fetched query result row.

odbULONG odbGetRowStatus (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns the ODB row status value. It returns ODB_ROWSTAT_UNKNOWN if the status cannot be determined or an error occurs.

Remarks

This function is used to obtain the status of a row in cursor-based result set.

odbGetSockError

Get last socket error code.

odbULONG odbGetSockError (
  odbHANDLE hOdb
);

Parameters

hOdb: [in] Handle to a connection or query object.

Return Values

Returns the numeric value of the current socket error.

Remarks

This is the system-specific numerical value of the socket error generated by the last function. If no error occurred, then this value is equal to 0.

odbGetSockErrorText

Get last socket error text.

odbPCSTR odbGetSockErrorText (
  odbHANDLE hOdb
);

Parameters

hOdb: [in] Handle to a connection or query object.

Return Values

Returns a pointer to the text corresponding to the current socket error.

Remarks

This is the text value of the socket error generated by the last function.

odbGetTotalCols

Get total query result columns.

odbUSHORT odbGetTotalCols (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns the total number of result columns. It returns 0 if there are no colums or an error occurs.

Remarks

If a query generates a result set, the value returned by this function is the number of columns in the result set. The value will be 0 if no result set is generated.

odbGetTotalParams

Get total prepared parameters.

odbUSHORT odbGetTotalParams (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns the total number of prepared parameters. It returns 0 if there are no parameters or an error occurs.

Remarks

After preparing a query, call this function to determine the number of designated parameters.

odbGetTotalRows

Get total rows retrieved from query result.

odbLONG odbGetTotalRows (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns the total rows retrieved from query result. It returns 0 if there are no rows or an error occurs.

Remarks

This function returns the cumulative retrieved row total when not using a cursor or row cache. It returns 0 if a cursor is being used, or the total rows stored into the cache after calling odbFetchRowsIntoCache.

odbGetUserData

Get user defined data.

odbPVOID odbGetUserData (
  odbHANDLE hOdb
);

Parameters

hOdb: [in] Handle to a connection or query object.

Return Values

Returns a pointer to the user defined data. It returns NULL if no data has been specified.

Remarks

This function is used to retrieve user defined data that was previously set with odbSetUserData.

odbGetUserDataLong

Get user defined data as long.

odbULONG odbGetUserDataLong (
  odbHANDLE hOdb
);

Parameters

hOdb: [in] Handle to a connection or query object.

Return Values

Returns the user defined long data value.

Remarks

This function is used to retrieve user defined data that was previously set with odbSetUserDataLong.

odbGetVersion

Get protocol version.

odbPCSTR odbGetVersion (
  odbHANDLE hCon
);

Parameters

hCon: [in] Handle to a connection object.

Return Values

Returns a pointer to the protocol version text string, or returns NULL if an error occurs.

Remarks

This function returns the ODBTP connection's protocol version.

odbGotParam

Determine if parameter was retrieved.

odbBOOL odbGotParam (
  odbHANDLE hQry,
  odbUSHORT usParam
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).

Return Values

Returns a nonzero value if the parameter was retrieved and can be read.

Remarks

Use this function to determine whether or not the value of a parameter is in the parameter buffer.

odbGuidToStr

Convert ODB GUID value to a GUID character string.

odbPSTR odbGuidToStr (
  odbPSTR  pszStr,
  odbPGUID pguidVal
);

Parameters

pszStr: [out] Pointer to character buffer whare GUID string will be stored.
pguidVal: [in] Pointer to ODB GUID data to be converted to string.

Return Values

Returns the pointer to the character buffer containing the resulting GUID string.

Remarks

Use this function to convert an ODB GUID value to a GUID character string in the form "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX."

odbIsConnected

Determine if object is connected to an ODBTP server.

odbBOOL odbIsConnected (
  odbHANDLE hOdb
);

Parameters

hOdb: [in] Handle to a connection or query object.

Return Values

Returns nonzero if specified object is connected to an ODBTP server.

Remarks

This function is used to determine whether or not the specified object is still connected to an ODBTP server. If a disconnect response is received from the server, the connection will automatically be disconnected. This function is useful for situations where the state of an object's connection is uncertain.

odbIsConnection

Determine if object is a connection object.

odbBOOL odbIsConnection (
  odbHANDLE hOdb
);

Parameters

hOdb: [in] Handle to a connection or query object.

Return Values

Returns nonzero if specified handle is a handle to a connection object.

Remarks

This function is used to determine whether or not the specified handle is that of a connection object.

odbIsTextAttr

Determine if attribute's type is text.

odbBOOL odbIsTextAttr (
  odbLONG lAttr
);

Parameters

lAttr: [in] ODB attribute.

Return Values

Returns TRUE if attribute's type is text, otherwise returns FALSE.

Remarks

This function can be used to determine whether or not an ODB attribute is a text (string) attribute.

odbIsUsingRowCache

Determines if row cache usage has been enabled.

odbBOOL odbIsUsingRowCache (
  odbHANDLE hCon
);

Parameters

hCon: [in] Handle to a connection object.

Return Values

Returns nonzero if row caching has been enabled, otherwise returns zero.

Remarks

This function can be used to determine whether or not row cache usage has been enabled. See odbUseRowCache for more details.

odbLoadDataTypes

Load data type information.

odbBOOL odbLoadDataTypes (
  odbHANDLE hCon
);

Parameters

hCon: [in] Handle to a connection object.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function loads information about data types. The retrieved information will be used by odbColSqlTypeName, odbParamSqlTypeName and odbDescribeSqlType.

odbLogin

odbBOOL odbLogin (
  odbHANDLE hCon,
  odbPSTR   pszServer,
  odbUSHORT usPort,
  odbUSHORT usType,
  odbPCSTR  pszDbConnect
);

Parameters

hCon: [in] Handle to a connection object.
pszServer: [in] ODBTP Server hostname or IP address.
usPort: [in] ODBTP server port number. This value is normally set to 2799.
usType: [in] ODB login type.
pszDbConnect: [in] Database (ODBC) connect string.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to establish a connection to an ODBTP server. After successfully connecting to the server, the DB connect string will be used by the server to login to the desired database. The DB connect string is either an ODBC connection string or the Id of a reserved connection.

odbLoginInterface

odbBOOL odbLoginInterface (
  odbHANDLE hCon,
  odbPSTR   pszFile,
  odbPCSTR  pszInterface,
  odbPCSTR  pszUsername,
  odbPCSTR  pszPassword,
  odbPCSTR  pszDatabase,
  odbUSHORT usType
);

Parameters

hCon: [in] Handle to a connection object.
pszFile: [in] File path name of file containing interfaces.
pszInterface: [in] Name of interface to be used.
pszUsername: [in] Username to be used if authentication is required for interface.
pszPassword: [in] Password to be used if authentication is required for interface.
pszDatabase: [in] Database to be accessed via the interface .
usType: [in] ODB login type.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to establish a connection to an ODBTP server using an interface file.

odbLogout

Logout from database.

odbBOOL odbLogout (
  odbHANDLE hCon,
  odbBOOL   bDisconnectDb
);

Parameters

hCon: [in] Handle to a connection object.
bDisconnectDb: [in] Set` to TRUE to disconnect database, otherwise set to FALSE so that database connection can be reused.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to close the connection to an ODBTP server. If bDisconnectDb is set to FALSE, the server will maintain its connection to the database. When closing a reserved connection, set this value to TRUE if it is no longer necessary for the server to maintain its connection to the database.

odbLongLongToStr

Convert long long (64-bit integer) value to numeric text string.

odbPSTR odbLongLongToStr (
  odbLONGLONG llVal,
  odbPSTR     pszStrEnd
);

Parameters

llVal: [in] Long long value to be converted.
pszStrEnd: [out] Pointer to end of text string buffer in which converted value will be placed.

Return Values

Pointer to the numeric text string resulting from the conversion.

Remarks

The size of the string buffer must be large enough to store the required number of characters needed to represent the long long value and a null terminator.

odbNoData

Determine if data was fetched.

odbBOOL odbNoData (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns nonzero if no data was fetched by a row or result fetch.

Remarks

After executing a query, fetching a row, or fetching a result, call this function to determine whether or not any data was returned.

odbParamActualLen

Obtain actual length of retrieved parameter.

odbLONG odbParamActualLen (
  odbHANDLE hQry,
  odbUSHORT usParam
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).

Return Values

Returns the actual length of the parameter data.

Remarks

This function can be used to determine the actual length of a truncated parameter.

odbParamData

Obtain retrieved parameter data.

odbPVOID odbParamData (
  odbHANDLE hQry,
  odbUSHORT usParam
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).

Return Values

Returns a pointer to the parameter data. Note, that while NULL is a legitimate return value, it will also be returned if an error occurs.

Remarks

This function is used to obtain the data from a parameter regardless of the ODB data type to which it is bound. The returned value is a pointer to data stored in the parameter buffer, and will be invalid if the buffer is reinitialized.

odbParamDataByte

Obtain retrieved parameter data as byte.

odbBYTE odbParamDataByte (
  odbHANDLE hQry,
  odbUSHORT usParam
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).

Return Values

Returns the byte value of the parameter. Note, that while 0 is a legitimate return value, it will also be returned if the parameter value is NULL or an error occurs.

Remarks

This function should be used to obtain data from parameters bound to ODB data types ODB_BIT, ODB_TINYINT or ODB_UTINYINT.

odbParamDataDouble

Obtain retrieved parameter data as double.

odbDOUBLE odbParamDataDouble (
  odbHANDLE hQry,
  odbUSHORT usParam
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).

Return Values

Returns the double value of the parameter. Note, that while 0.0 is a legitimate return value, it will also be returned if the parameter value is NULL or an error occurs.

Remarks

This function should be used to obtain data from parameters bound to ODB data type ODB_DOUBLE.

odbParamDataFloat

Obtain retrieved parameter data as float.

odbFLOAT odbParamDataFloat (
  odbHANDLE hQry,
  odbUSHORT usParam
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).

Return Values

Returns the float value of the parameter. Note, that while 0.0 is a legitimate return value, it will also be returned if the parameter value is NULL or an error occurs.

Remarks

This function should be used to obtain data from parameters bound to ODB data type ODB_REAL.

odbParamDataLen

Obtain retrieved parameter data length.

odbLONG odbParamDataLen (
  odbHANDLE hQry,
  odbUSHORT usParam
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).

Return Values

Returns the byte length of the parameter data. It will return ODB_NULL if the parameter value is NULL or an error occurs.

Remarks

This function is usually used to determine whether or not a parameter's data value is NULL. If the value of a parameter is NULL, then the data length is equal to ODB_NULL.

odbParamDataLong

Obtain retrieved parameter data as long.

odbULONG odbParamDataLong (
  odbHANDLE hQry,
  odbUSHORT usParam
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).

Return Values

Returns the long value of the parameter. Note, that while 0 is a legitimate return value, it will also be returned if the parameter value is NULL or an error occurs.

Remarks

This function should be used to obtain data from parameters bound to ODB data types ODB_INT or ODB_UINT.

odbParamDataLongLong

Obtain retrieved parameter data as long long (64-bit integer).

odbULONGLONG odbParamDataLongLong (
  odbHANDLE hQry,
  odbUSHORT usParam
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).

Return Values

Returns the long long value of the parameter. Note, that while 0 is a legitimate return value, it will also be returned if the parameter value is NULL or an error occurs.

Remarks

This function should be used to obtain data from parameters bound to ODB data types ODB_BIGINT or ODB_UBIGINT.

odbParamDataShort

Obtain retrieved parameter data as short.

odbUSHORT odbParamDataShort (
  odbHANDLE hQry,
  odbUSHORT usParam
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).

Return Values

Returns the short value of the parameter. Note, that while 0 is a legitimate return value, it will also be returned if the parameter value is NULL or an error occurs.

Remarks

This function should be used to obtain data from parameters bound to ODB data types ODB_SMALLINT or ODB_USMALLINT.

odbParamDataText

Obtain retrieved parameter data as text.

odbPSTR odbParamDataText (
  odbHANDLE hQry,
  odbUSHORT usParam
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).

Return Values

Returns a pointer to the text value of the parameter. Note, that while a pointer to zero length text ("") is a legitimate return value, it will also be returned if the parameter value is NULL or an error occurs.

Remarks

This function should be used to obtain data from parameters bound to ODB data types ODB_CHAR or ODB_WCHAR. The returned value is a pointer to data stored in the parameter buffer, and will be invalid if the buffer is reinitialized.

odbParamDataTimestamp

Obtain retrieved parameter data as ODB timestamp.

odbPTIMESTAMP odbParamDataTimestamp (
  odbHANDLE hQry,
  odbUSHORT usParam
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).

Return Values

Returns a pointer to the ODB timestamp value of the parameter. Note, a zeroed ODB timestamp will be returned if the parameter value is NULL or an error occurs.

Remarks

This function should be used to obtain data from parameters bound to ODB data type ODB_DATETIME. The returned value is a pointer to data stored in the parameter buffer, and will be invalid if the buffer is reinitialized.

odbParamDataType

Get parameter data type.

odbSHORT odbParamDataType (
  odbHANDLE hQry,
  odbUSHORT usParam
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).

Return Values

Returns the parameter's ODB data type or 0 if an error occurs.

Remarks

This function is used to determine the ODB data type to which a parameter is bound.

odbParamDecDigits

Get decimal digits or precision of parameter.

odbSHORT odbParamDecDigits (
  odbHANDLE hQry,
  odbUSHORT usParam
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).

Return Values

Returns the parameter's decimal digits.

Remarks

This function is used to determine a parameter's decimal digits or precision.

odbParamDefaultDataType

Get parameter default data type.

odbSHORT odbParamDefaultDataType (
  odbHANDLE hQry,
  odbUSHORT usParam
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).

Return Values

Returns the parameter's default ODB data type, or 0 if an error occurs.

Remarks

This is the ODB data type that will be used if it is not explicitly specified when calling odbBindParam, odbBindInputParam, odbBindInOutParam, or odbBindOutputParam.

odbParamName

Get parameter name.

odbPCSTR odbParamName (
  odbHANDLE hQry,
  odbUSHORT usParam
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).

Return Values

Returns a pointer to the parameter name text, or returns NULL if an error occurs.

Remarks

Call this function to get the name of a parameter. The returned value is a pointer to data stored in the parameter info buffer, and will be invalid if the buffer is reinitialized.

odbParamNum

Get parameter number corresponding to name.

odbUSHORT odbParamNum (
  odbHANDLE hQry,
  odbPCSTR  pszName
);

Parameters

hQry: [in] Handle to a query object.
pszName: [in] Name of parameter.

Return Values

Returns parameter number corresponding to the specified name, or returns 0 if an error occurs.

Remarks

Call this function to get the parameter number corresponding to a parameter name.

odbParamSize

Get parameter size.

odbULONG odbParamSize (
  odbHANDLE hQry,
  odbUSHORT usParam
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).

Return Values

Returns the max character size of the parameter, or returns 0 if an error occurs.

Remarks

This value is the maximum character size of the parameter if it is bound to the ODB data type ODB_CHAR.

odbParamSqlType

Get SQL type of parameter.

odbSHORT odbParamSqlType (
  odbHANDLE hQry,
  odbUSHORT usParam
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).

Return Values

Returns the parameter's SQL type. The returned value is a pointer to data stored in the parameter info buffer, and will be invalid if the buffer is reinitialized.

Remarks

This function is used to determine a parameter's SQL type.

odbParamSqlTypeName

Get SQL type name of parameter.

odbSHORT odbParamSqlTypeName (
  odbHANDLE hQry,
  odbUSHORT usParam
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).

Return Values

Returns the parameter's SQL type name.

Remarks

This function is used to determine a parameter's SQL type name.

odbParamTruncated

Determine if parameter was truncated.

odbBOOL odbParamTruncated (
  odbHANDLE hQry,
  odbUSHORT usParam
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).

Return Values

Returns non-zero if parameter data was truncated.

Remarks

Use this function to determine if a parameter's data was truncated.

odbParamType

Get parameter type.

odbUSHORT odbParamType (
  odbHANDLE hQry,
  odbUSHORT usParam
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).

Return Values

Returns the parameter's ODB parameter type. It will return ODB_PARAM_NONE if parameter has not been bound or an error occurs.

Remarks

This is the ODB parameter type that was specified when the parameter was bound to an ODB data type.

odbParamUserData

Get parameter's user defined data.

odbPVOID odbParamUserData (
  odbHANDLE hQry,
  odbUSHORT usParam
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).

Return Values

Returns the pointer representing the parameter's user defined data.

Remarks

This function is used to return a parameter's user defined data. Use odbSetParamUserData to assign user defined data for a parameter.

odbPrepare

Prepare a parameterized query for later execution.

odbBOOL odbPrepare (
  odbHANDLE hQry,
  odbPCSTR  pszSQL
);

Parameters

hQry: [in] Handle to a query object.
pszSQL: [in] SQL (Query) string to be prepared for later execution.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to prepare a query for later execution. This function reinitializes the parameter, parameter info, column, and row buffers. If the prepared query contains parameters, the corresponding parameter info is stored in the parameter info buffer. All parameters must be bound prior to executing the query with odbExecute.

odbPrepareProc

Prepare a stored procedure for later execution.

odbBOOL odbPrepareProc (
  odbHANDLE hQry,
  odbPCSTR  pszProcedure
);

Parameters

hQry: [in] Handle to a query object.
pszProcedure: [in] Name of procedure to be prepared for later execution.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to prepare a stored procedure for later execution. This function reinitializes the parameter, parameter info, column, and row buffers. All parameters, if any, are automatically binded, and all input parameters are set to use their default values. Use odbExecute to execute the procedure.

odbRollback

Rollback current transaction.

odbBOOL odbRollback (
  odbHANDLE hCon
);

Parameters

hCon: [in] Handle to a connection object.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

If transactions have been enabled, call this function to rollback any transactions since the last commit or rollback. Transactions are enabled by setting the ODB attribute ODB_ATTR_TRANSACTIONS to a value other than ODB_TXN_NONE.

odbRowAdd

Add row to query result set.

odbBOOL odbRowAdd (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

When using a keyset or dynamic cursor, this function can be used to add a new row to the result set.

odbRowBookmark

Bookmark currently fetched query result row.

odbBOOL odbRowBookmark (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

When using a static, keyset or dynamic cursor, this function can be used to bookmark the currently fetched row. This function requires bookmarks support to be enabled when calling odbSetCursor.

odbRowDelete

Delete currently fetched query result row.

odbBOOL odbRowDelete (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

When using a keyset or dynamic cursor, this function can be used to delete the currently fetched row.

odbRowLock

Lock currently fetched query result row.

odbBOOL odbRowLock (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

When using a keyset or dynamic cursor, this function can be used to lock the currently fetched row.

odbRowRefresh

Refresh currently fetched query result row.

odbBOOL odbRowRefresh (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

When using a static, keyset or dynamic cursor, this function can be used to refresh the currently fetched row.

odbRowUnlock

Unlock currently fetched query result row.

odbBOOL odbRowUnlock (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

When using a keyset or dynamic cursor, this function can be used to unlock the currently fetched row.

odbRowUpdate

Update currently fetched query result row.

odbBOOL odbRowUpdate (
  odbHANDLE hQry
);

Parameters

hQry: [in] Handle to a query object.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

When using a keyset or dynamic cursor, this function can be used to update the currently fetched row.

odbSeekRow

Seek a cached row.

odbBOOL odbSeekRow (
  odbHANDLE hQry,
  odbLONG   lRow
);

Parameters

hQry: [in] Handle to a query object.
lRow: [in] Row to be seeked.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

If a row cache is being used, this function can be used to seek to a row that can subsequently be fetched from the cache.

odbSetAttrLong

Set long ODB attribute value.

odbBOOL odbSetAttrLong (
  odbHANDLE hCon,
  odbLONG   lAttr,
  odbULONG  ulVal
);

Parameters

hCon: [in] Handle to a connection object.
lAttr: [in] ODB attribute.
ulVal: [in] Long value to which attribute will be set.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

Use this function to set any ODB attribute whose value is a number.

odbSetAttrText

Set text ODB attribute value.

odbBOOL odbSetAttrText (
  odbHANDLE hCon,
  odbLONG   lAttr,
  odbPCSTR  pszVal
);

Parameters

hCon: [in] Handle to a connection object.
lAttr: [in] ODB attribute.
pszVal: [out] Pointer to text buffer containing value to which attribute will be set.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

Use this function to set any ODB attribute whose value is a text string.

odbSetCol

Set result column to data value.

odbBOOL odbSetCol (
  odbHANDLE hQry,
  odbUSHORT usCol,
  odbPVOID  pData,
  odbLONG   lDataLen,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).
pData: [in] Pointer to data to which column will be set.
lDataLen: [in] Length of data. Set this value to 0 if column is bound to a fixed length data type.
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to set the value of a column regardless of the ODB data type to which it is bound. Only the column data on the server is changed. Call odbFetchRowReread to update the data on the client.

odbSetColByte

Set result column to byte value.

odbBOOL odbSetColByte (
  odbHANDLE hQry,
  odbUSHORT usCol,
  odbBYTE   byData,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).
byData: [in] Byte value to which column will be set.
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function should be used to set the value of columns bound to ODB data types ODB_BIT, ODB_TINYINT or ODB_UTINYINT. Only the column data on the server is changed. Call odbFetchRowReread to update the data on the client.

odbSetColDouble

Set result column to double value.

odbBOOL odbSetColDouble (
  odbHANDLE hQry,
  odbUSHORT usCol,
  odbDOUBLE dData,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).
dData: [in] Double value to which column will be set.
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function should be used to set the value of columns bound to ODB data type ODB_DOUBLE. Only the column data on the server is changed. Call odbFetchRowReread to update the data on the client.

odbSetColFloat

Set result column to float value.

odbBOOL odbSetColFloat (
  odbHANDLE hQry,
  odbUSHORT usCol,
  odbFLOAT  fData,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).
fData: [in] Float value to which column will be set.
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function should be used to set the value of columns bound to ODB data type ODB_REAL. Only the column data on the server is changed. Call odbFetchRowReread to update the data on the client.

odbSetColIgnore

Set result column value to be ignored.

odbBOOL odbSetColIgnore (
  odbHANDLE hQry,
  odbUSHORT usCol,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to tell the server to ignore a column when performing a row update or add.

odbSetColLong

Set result column to long value.

odbBOOL odbSetColLong (
  odbHANDLE hQry,
  odbUSHORT usCol,
  odbULONG  ulData,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).
ulData: [in] Long value to which column will be set.
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function should be used to set the value of columns bound to ODB data types ODB_INT or ODB_UINT. Only the column data on the server is changed. Call odbFetchRowReread to update the data on the client.

odbSetColLongLong

Set result column to long long (64-bit integer) value.

odbBOOL odbSetColLongLong (
  odbHANDLE    hQry,
  odbUSHORT    usCol,
  odbULONGLONG ullData,
  odbBOOL      bFinal
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).
ullData: [in] Long long value to which column will be set.
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function should be used to set the value of columns bound to ODB data types ODB_BIGINT or ODB_UBIGINT. Only the column data on the server is changed. Call odbFetchRowReread to update the data on the client.

odbSetColNull

Set result column value to NULL.

odbBOOL odbSetColNull (
  odbHANDLE hQry,
  odbUSHORT usCol,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to set the value of a column to NULL. Only the column data on the server is changed. Call odbFetchRowReread to update the data on the client.

odbSetColShort

Set result column to short value.

odbBOOL odbSetColShort (
  odbHANDLE hQry,
  odbUSHORT usCol,
  odbUSHORT usData,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).
usData: [in] Short value to which column will be set.
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function should be used to set the value of columns bound to ODB data types ODB_SMALLINT or ODB_USMALLINT. Only the column data on the server is changed. Call odbFetchRowReread to update the data on the client.

odbSetColText

Set result column to text value.

odbBOOL odbSetColText (
  odbHANDLE hQry,
  odbUSHORT usCol,
  odbPCSTR  pszData,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).
pszData: [in] Pointer to text value to which column will be set.
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function should be used to set the value of columns bound to ODB data types ODB_CHAR or ODB_WCHAR. Only the column data on the server is changed. Call odbFetchRowReread to update the data on the client.

odbSetColTimestamp

Set result column to ODB timestamp value.

odbBOOL odbSetColTimestamp (
  odbHANDLE     hQry,
  odbUSHORT     usCol,
  odbPTIMESTAMP ptsData,
  odbBOOL       bFinal
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).
ptsData: [in] Pointer to ODB timestamp value to which column will be set.
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function should be used to set the value of columns bound to ODB data type ODB_DATETIME. Only the column data on the server is changed. Call odbFetchRowReread to update the data on the client.

odbSetColUserData

Set column's user defined data.

odbBOOL odbSetColUserData (
  odbHANDLE hQry,
  odbUSHORT usCol,
  odbPVOID  pVal
);

Parameters

hQry: [in] Handle to a query object.
usCol: [in] Column number (1-based).
pVal: [in] Pointer to user defined data value.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to associate user defined data with a column. Use odbColUserData to retrieve the data.

odbSetConnectTimeout

Set connection timeout.

odbULONG odbSetConnectTimeout (
  odbHANDLE hOdb,
  odbULONG  ulTimeout
);

Parameters

hOdb: [in] Handle to a connection or query object.
ulTimeout: [in] Timeout in seconds.

Return Values

Returns the previous timeout value.

Remarks

Use this function change the timeout for connecting to an ODBTP server. This value pertains only to the time when connecting to the server, and not when connecting to the database.

odbSetCursor

Set cursor type.

odbBOOL odbSetCursor (
  odbHANDLE hQry,
  odbUSHORT usType,
  odbUSHORT usConcurrency,
  odbBOOL   bEnableBookmarks
);

Parameters

hQry: [in] Handle to a query object.
usType: [in] ODB cursor type.
usConcurrency: [in] ODB cursor concurrency type.
bEnableBookmarks: [in] Set` to TRUE to enable bookmark support, otherwise set to FALSE if this feature is not desired.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

Use this function to enable the use of cursors when executing queries that generate a result set. Cursor support and capabilities are dependent on the underlying ODBC driver for the database.

odbSetParam

Set prepared parameter to data value.

odbBOOL odbSetParam (
  odbHANDLE hQry,
  odbUSHORT usParam,
  odbPVOID  pData,
  odbLONG   lDataLen,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).
pData: [in] Pointer to data to which parameter will be set.
lDataLen: [in] Length of data. Set this value to 0 if parameter is bound to a fixed length data type.
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to set the value of a parameter regardless of the ODB data type to which it is bound.

odbSetParamByte

Set prepared parameter to byte value.

odbBOOL odbSetParamByte (
  odbHANDLE hQry,
  odbUSHORT usParam,
  odbBYTE   byData,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).
byData: [in] Byte value to which parameter will be set.
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function should be used to set the value of parameters bound to ODB data types ODB_BIT, ODB_TINYINT or ODB_UTINYINT.

odbSetParamDefault

Set prepared parameter to default value.

odbBOOL odbSetParamDefault (
  odbHANDLE hQry,
  odbUSHORT usParam,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to tell the server to use a parameter's default value when executing a prepared query.

odbSetParamDouble

Set prepared parameter to double value.

odbBOOL odbSetParamDouble (
  odbHANDLE hQry,
  odbUSHORT usParam,
  odbDOUBLE dData,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).
dData: [in] Double value to which parameter will be set.
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function should be used to set the value of parameters bound to ODB data type ODB_DOUBLE.

odbSetParamFloat

Set prepared parameter to float value.

odbBOOL odbSetParamFloat (
  odbHANDLE hQry,
  odbUSHORT usParam,
  odbFLOAT  fData,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).
fData: [in] Float value to which parameter will be set.
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function should be used to set the value of parameters bound to ODB data type ODB_REAL.

odbSetParamLong

Set prepared parameter to long value.

odbBOOL odbSetParamLong (
  odbHANDLE hQry,
  odbUSHORT usParam,
  odbULONG  ulData,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).
ulData: [in] Long value to which parameter will be set.
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function should be used to set the value of parameters bound to ODB data types ODB_INT or ODB_UINT.

odbSetParamLongLong

Set prepared parameter to long long (64-bit integer) value.

odbBOOL odbSetParamLongLong (
  odbHANDLE    hQry,
  odbUSHORT    usParam,
  odbULONGLONG ullData,
  odbBOOL      bFinal
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).
ullData: [in] Long long value to which parameter will be set.
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function should be used to set the value of parameters bound to ODB data types ODB_BIGINT or ODB_UBIGINT.

odbSetParamNull

Set prepared parameter value to NULL.

odbBOOL odbSetParamNull (
  odbHANDLE hQry,
  odbUSHORT usParam,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to set the value of a parameter to NULL.

odbSetParamShort

Set prepared parameter to short value.

odbBOOL odbSetParamShort (
  odbHANDLE hQry,
  odbUSHORT usParam,
  odbUSHORT usData,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).
usData: [in] Short value to which parameter will be set.
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function should be used to set the value of parameters bound to ODB data types ODB_SMALLINT or ODB_USMALLINT.

odbSetParamText

Set prepared parameter to text value.

odbBOOL odbSetParamText (
  odbHANDLE hQry,
  odbUSHORT usParam,
  odbPCSTR  pszData,
  odbBOOL   bFinal
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).
pszData: [in] Pointer to text value to which parameter will be set.
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function should be used to set the value of parameters bound to ODB data types ODB_CHAR or ODB_WCHAR.

odbSetParamTimestamp

Set prepared parameter to ODB timestamp value.

odbBOOL odbSetParamTimestamp (
  odbHANDLE     hQry,
  odbUSHORT     usParam,
  odbPTIMESTAMP ptsData,
  odbBOOL       bFinal
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).
ptsData: [in] Pointer to ODB timestamp value to which parameter will be set.
bFinal: [in] Set to FALSE if more request data of the same type needs to be sent to server. Set to TRUE if it is the final request data, upon which the server will send the response data.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function should be used to set the value of parameters bound to ODB data type ODB_DATETIME.

odbSetParamUserData

Set parameter's user defined data.

odbBOOL odbSetParamUserData (
  odbHANDLE hQry,
  odbUSHORT usParam,
  odbPVOID  pVal
);

Parameters

hQry: [in] Handle to a query object.
usParam: [in] Parameter number (1-based).
pVal: [in] Pointer to user defined data value.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is used to associate user defined data with a parameter. Use odbParamUserData to retrieve the data.

odbSetReadTimeout

Set read timeout.

odbULONG odbSetReadTimeout (
  odbHANDLE hOdb,
  odbULONG  ulTimeout
);

Parameters

hOdb: [in] Handle to a connection or query object.
ulTimeout: [in] Timeout in seconds.

Return Values

Returns the previous timeout value.

Remarks

Use this function change the timeout for reading responses from an ODBTP server.

odbSetSendTimeout

Set send timeout.

odbULONG odbSetSendTimeout (
  odbHANDLE hOdb,
  odbULONG  ulTimeout
);

Parameters

hOdb: [in] Handle to a connection or query object.
ulTimeout: [in] Timeout in seconds.

Return Values

Returns the previous timeout value.

Remarks

Use this function change the timeout for sending requests from an ODBTP server.

odbSetUserData

Set user defined data.

void odbSetUserData (
  odbHANDLE hOdb,
  odbPVOID  pVal
);

Parameters

hOdb: [in] Handle to a connection or query object.
pVal: [in] Pointer to user defined data.

Return Values

This function does not return a value.

Remarks

This function allows user defined data to be attached to a connection or query object. Call odbGetUserData to retrieve the data.

odbSetUserDataLong

Set user defined data to long value.

void odbSetUserDataLong (
  odbHANDLE hOdb,
  odbULONG  ulVal
);

Parameters

hOdb: [in] Handle to a connection or query object.
ulVal: [in] Long value to which user defined data will be set.

Return Values

This function does not return a value.

Remarks

This function allows a user defined value of type odbULONG to be attached to a connection or query object. Call odbGetUserDataLong to retrieve the value.

odbStrToGuid

Convert GUID character string to ODB GUID.

odbPGUID odbStrToGuid (
  odbPGUID pguidVal,
  odbPCSTR pszStr
);

Parameters

pguidVal: [out] Pointer to ODB GUID variable to store conversion of string.
pszStr: [in] Pointer to GUID character string to be converted to ODB GUID.

Return Values

Returns the pointer to the ODB GUID.

Remarks

Use this function to convert a GUID character string of the form "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" to an ODB GUID.

odbStrToLongLong

Convert numeric text string to long long (64-bit integer) value.

odbLONGLONG odbStrToLongLong (
  odbPCSTR pszStr
);

Parameters

pszStr: [in] Pointer to buffer containing numeric text string.

Return Values

Long long value resulting from the conversion of numeric text string.

Remarks

The numeric text string can contain leading spaces. The conversion process will terminate if a non-numeric or non-leading "-" character is detected.

odbStrToTimestamp

Convert ISO formatted character string to ODB timestamp.

odbPTIMESTAMP odbStrToTimestamp (
  odbPTIMESTAMP ptsTime,
  odbPCSTR      pszStr
);

Parameters

ptsTime: [out] Pointer to ODB timestamp variable to store conversion of string.
pszStr: [in] Pointer to ISO formatted string to be converted to ODB timestamp.

Return Values

Returns the pointer to the ODB timestamp.

Remarks

Use this function to convert an ISO formatted, YYYY-MM-DD HH:MM:SS.MMM, character string to an ODB timestamp.

odbStrToULongLong

Convert numeric text string to unsigned long long (64-bit integer) value.

odbULONGLONG odbStrToULongLong (
  odbPCSTR pszStr
);

Parameters

pszStr: [in] Pointer to buffer containing numeric text string.

Return Values

Unsigned long long value resulting from the conversion of numeric text string.

Remarks

The numeric text string can contain leading spaces. The conversion process will terminate if a non-numeric or non-leading "-" character is detected.

odbTimestampToCTime

Convert ODB timestamp to C time.

odbLONG odbTimestampToCTime (
  odbPTIMESTAMP ptsTime
);

Parameters

ptsTime: [in] Pointer to ODB timestamp data to be converted to C time.

Return Values

Returns the C time value corresponding to the specified ODB timestamp value.

Remarks

Use this function to convert an ODB timestamp value to a C time value. This function is provided so that datetime data can be processed with C time functions.

odbTimestampToStr

Convert ODB timestamp to ISO formatted character string.

odbPSTR odbTimestampToStr (
  odbPSTR       pszStr,
  odbPTIMESTAMP ptsTime,
  odbBOOL       bIncludeFraction
);

Parameters

pszStr: [out] Pointer to character buffer whare ISO formatted string will be stored.
ptsTime: [in] Pointer to ODB timestamp data to be converted to ISO string.
bIncludeFraction: [in] Determines whether or not to include millisecond fraction.

Return Values

Returns the pointer to the character buffer containing the resulting ISO string.

Remarks

Use this function to convert an ODB timestamp value to an ISO formatted string. If bIncludeFraction is TRUE, then the result will be of the form "YYYY-MM-DD HH:MM:SS.MMM", otherwise it is "YYYY-MM-DD HH:MM:SS."

odbULongLongToStr

Convert unsigned long long (64-bit integer) value to numeric text string.

odbPSTR odbULongLongToStr (
  odbULONGLONG ullVal,
  odbPSTR      pszStrEnd
);

Parameters

ullVal: [in] Unsigned long long value to be converted.
pszStrEnd: [out] Pointer to end of text string buffer in which converted value will be placed.

Return Values

Pointer to the numeric text string resulting from the conversion.

Remarks

The size of the string buffer must be large enough to store the required number of characters needed to represent the unsigned long long value and a null terminator.

odbUseRowCache

Enable or disable row cache usage.

odbBOOL odbUseRowCache (
  odbHANDLE hCon,
  odbBOOL   bUse,
  odbULONG  ulSize
);

Parameters

hCon: [in] Handle to a connection object.
bUse: [in] Set to TRUE to enable row cache usage, or FALSE to disable usage.
ulSize: [in] The maximum row storage size of the cache.

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

A row cache can be used to store some or all of the rows from a query result set. Cached rows can be scrolled, and accessed offline after executing odbDetachQry. If enabled, odbFetchRowsInfoCache can be used to place the rows from a query result into the cache. odbFetchRowsIntoCache will store up to ulSize rows into the cache. If ulSize is set to 0, then all rows will be stored in the cache.

odbWinsockCleanup

Terminates use of winsock subsystem.

void odbWinsockCleanup (
);

Parameters

None

Return Values

This function does not return a value.

Remarks

This function is only required for Win32-based client applications. It has no effect on non-Win32 systems.

odbWinsockStartup

Initiates use of winsock subsystem.

odbBOOL odbWinsockStartup (
);

Parameters

None

Return Values

Returns nonzero if the function is successful, otherwise returns zero if an error occurs.

Remarks

This function is only required for Win32-based client applications. It has no effect on non-Win32 systems.