Chapter 3. tbCLI Functions

Table of Contents

3.1. SQL-99 Standard API

3.1.1. SQLAllocConnect (Deprecated)
3.1.2. SQLAllocEnv (Deprecated)
3.1.3. SQLAllocHandle
3.1.4. SQLAllocStmt (Deprecated)
3.1.5. SQLBindCol
3.1.6. SQLBindParameter
3.1.7. SQLCancel
3.1.8. SQLCloseCursor
3.1.9. SQLColAttribute
3.1.10. SQLColAttributes (Deprecated)
3.1.11. SQLColumnPrivileges
3.1.12. SQLColumns
3.1.13. SQLConnect
3.1.14. SQLCopyDesc
3.1.15. SQLDescribeCol
3.1.16. SQLDescribeParam
3.1.17. SQLDisconnect
3.1.18. SQLDriverConnect
3.1.19. SQLEndTran
3.1.20. SQLError (Deprecated)
3.1.21. SQLExecDirect
3.1.22. SQLExecute
3.1.23. SQLExtendedFetch (Deprecated)
3.1.24. SQLExtProcRaiseError
3.1.25. SQLExtProcRaiseErrorWithMsg
3.1.26. SQLFetch
3.1.27. SQLFetchScroll
3.1.28. SQLForeignKeys
3.1.29. SQLFreeConnect (Deprecated)
3.1.30. SQLFreeEnv (Deprecated)
3.1.31. SQLFreeHandle
3.1.32. SQLFreeStmt
3.1.33. SQLGetConnectAttr
3.1.34. SQLGetConnectOption (Deprecated)
3.1.35. SQLGetCursorName
3.1.36. SQLGetData
3.1.37. SQLGetDescField
3.1.38. SQLGetDescRec
3.1.39. SQLGetDiagField
3.1.40. SQLGetDiagRec
3.1.41. SQLGetEnvAttr
3.1.42. SQLGetExtProcAllocMemory
3.1.43. SQLGetExtProcConnect
3.1.44. SQLGetFunctions
3.1.45. SQLGetInfo
3.1.46. SQLGetStmtAttr
3.1.47. SQLGetStmtOption (Deprecated)
3.1.48. SQLGetTypeInfo
3.1.49. SQLMoreResults
3.1.50. SQLNativeSql
3.1.51. SQLNumParams
3.1.52. SQLNumResultCols
3.1.53. SQLParamData
3.1.54. SQLParamOptions (Deprecated)
3.1.55. SQLPrepare
3.1.56. SQLPrimaryKeys
3.1.57. SQLProcedureColumns
3.1.58. SQLProcedures
3.1.59. SQLPutData
3.1.60. SQLRowCount
3.1.61. SQLSetConnectAttr
3.1.62. SQLSetConnectOption (Deprecated)
3.1.63. SQLSetCursorName
3.1.64. SQLSetDescField
3.1.65. SQLSetDescRec
3.1.66. SQLSetEnvAttr
3.1.67. SQLSetParam (Deprecated)
3.1.68. SQLSetPos
3.1.69. SQLSetScrollOptions (Deprecated)
3.1.70. SQLSetStmtAttr
3.1.71. SQLSetStmtOption (Deprecated)
3.1.72. SQLSpecialColumns
3.1.73. SQLStatistics
3.1.74. SQLTablePrivileges
3.1.75. SQLTables
3.1.76. SQLTransact (Deprecated)

3.2. Tibero API

3.2.1. SQLAllocEnv2 (Deprecated)
3.2.2. SQLAllocHandle2
3.2.3. SQLGetWarningMsg
3.2.4. SQLGetWarningMsgLength
3.2.5. SQLLobClose
3.2.6. SQLLobFreeLoc
3.2.7. SQLLobGetData (Deprecated)
3.2.8. SQLLobGetData2
3.2.9. SQLLobGetLength
3.2.10. SQLLobOpen
3.2.11. SQLLobPutData
3.2.12. SQLLobTruncate

This chapter describes functions supported by tbCLI.

3.1. SQL-99 Standard API

3.1.1. SQLAllocConnect (Deprecated)

The SQLAllocConnect function is replaced by the SQLAllocHandle function in ODBC 3.x.

3.1.2. SQLAllocEnv (Deprecated)

An application program can use a single environment at a time. This function allocates and initializes the environment handle and related memory.

To receive the environment handle, the SQLAllocEnv function should be called before the SQLAllocConnect function is called. After the function is called, the handle is sent to all functions that require the environment handle.

For reference, if the SQLFreeEnv function is called, the existing environment handle is returned.

Related Function

The SQLAllocEnv function is replaced by the SQLAllocHandle function in ODBC 3.x.

3.1.3. SQLAllocHandle

This function is used to allocate environment, connection and statement handles.

ISO 92 CLI/ODBC 3.0 supports the function. The function initializes resources, environment, and command handles, and allocates memory.

Details of the SQLAllocHandle function are as follows.

Syntax

SQLRETURN SQLAllocHandle (SQLSMALLINT   HandleType,
                          SQLHANDLE     InputHandle,
                          SQLHANDLE     *OutputHandle);

Parameter

Parameter	Purpose	Description
HandleType	Input	Handle type to be allocated. Has one value among the types below. - SQL_HANDLE_ENV - SQL_HANDLE_DBC - SQL_HANDLE_STMT
InputHandle	Input	Input handle. Has a different value depending on the handle type. - SQL_HANDLE_ENV: SQL_NULL_HANDLE - SQL_HANDLE_DBC: Environment handle - SQL_HANDLE_STMT: Connection handle
OutputHandle	Output	Handle pointer to be allocated. If SQL_ERROR is returned when allocating a handle other than the environment handle, SQL_NULL_HDBC and SQL_NULL_HSTMT are allocated to OutputHandle parameters.

Purpose

Description

HandleType

Input

Handle type to be allocated.

Has one value among the types below.

- SQL_HANDLE_ENV

- SQL_HANDLE_DBC

- SQL_HANDLE_STMT

InputHandle

Input

Input handle.

Has a different value depending on the handle type.

- SQL_HANDLE_ENV: SQL_NULL_HANDLE

- SQL_HANDLE_DBC: Environment handle

- SQL_HANDLE_STMT: Connection handle

OutputHandle

Output

Handle pointer to be allocated.

If SQL_ERROR is returned when allocating a handle other than the environment handle, SQL_NULL_HDBC and SQL_NULL_HSTMT are allocated to OutputHandle parameters.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully but there is a warning message.
SQL_INVALID_HANDLE	The handle given to the input parameter is invalid.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
08003	Database connection does not exist.
HY000	General error
HY001	Memory allocation error
HY009	NULL pointer is incorrectly used. .
HY010	Function sequence error
HY013	Memory management error
HY014	The number of handles exceeds the limited range.
HY092	Invalid property and option identifier
HYC00	Optional feature is not implemented.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLAllocHandle` function.

Related Functions

SQLAllocHandle replaces SQLAllocConnect, SQLAllocEnv, and SQLAllocstmt.

For application programs which use ODBC 2.x driver, to work properly, the SQLAllocHandle function should be replaced by SQLAllocConnect, SQLAllocEnv, or SQLAllocstmt functions accordingly.

3.1.4. SQLAllocStmt (Deprecated)

This function gets the allocation of statement handle to process the descriptor, result value, cursor information, and status information in tbCLI. If the function is called, it allocates and initializes memory for statements. For one database connection, 1,024 statements can be allocated.

Related Function

SQLAllocStmt is replaced by the SQLAllocHandle in ODBC 3.x.

3.1.5. SQLBindCol

Supported by ISO 92 CLI/ODBC 1.0. The function sets up the buffer and data type to receive the columns of a result set.

For all data types, the function relates the columns of result set to application program variables. The position referenced by the function is not updated and remains valid until the SQLFetch function is called.

If the SQLFetch function is called, data is transferred from database server to application program. Therefore this function should be called before the SQLFetch function is used.

Details of the SQLBindCol function are as follows.

Syntax

SQLRETURN SQLBindCol (SQLHSTMT       StatementHandle,
                      SQLUSMALLINT   ColumnNumber,
                      SQLSMALLINT    TargetType,
                      SQLPOINTER     TargetValue,
                      SQLINTEGER     BufferLength,
                      SQLINTEGER     *StrLen_or_Ind);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle
ColumnNumber	Input	Column number
TargetType	Input	C data type
TargetValue	Input/Output	Pointer of the buffer to receive the columns
BufferLength	Input	Buffer size on unit of byte
StrLen_or_IndPtr	Input/Output	Length data stored in the buffer

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to the input parameter is invalid.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
07006	Violation of limited data type property
07009	Invalid descriptor index
HY000	General error
HY001	Memory allocation error
HY003	Invalid application buffer type
HY010	Function sequence error
HY013	Memory management error
HY090	Invalid character string or buffer length
HYC00	Optional feature is not implemented.
HYT01	Database connection time limit exceeded.
IM001	The database connection time out exceeded.

3.1.6. SQLBindParameter

Supported by ISO 92 CLI/ODBC 2.0. This function binds SQL statement's parameters to application program variables.

Details of the SQLBindParameter function are as follows.

Syntax

SQLRETURN SQLBindParameter (SQLHSTMT        StatementHandle
                            SQLUSMALLINT    ParameterNumber,
                            SQLSMALLINT     InputOutputType,
                            SQLSMALLINT     ValueType,
                            SQLSMALLINT     ParameterType,
                            SQLULEN         ColumnSize,
                            SQLSMALLINT     DecimalDigits,
                            SQLPOINTER      ParameterValue,
                            SQLLEN          BufferLength,
                            SQLLEN          *StrLen_or_IndPtr);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle
ParameterNumber	Input	Parameter position
InputOutputType	Input	Parameter types
ValueType	Input	C data type
ParameterType	Input	SQL data type
ColumnSize	Input	Precision Varies depending on the data type: SQL_CHAR: The maximum length SQL_NUMERIC: The maximum decimal precision
DecimalDigits	Input	If SQL_NUMERIC, the number of digits below the decimal point.
ParameterValue	Input/Output	Parameter pointer
BufferLength	Input	The maximum buffer size
StrLen_or_Ind	Input/Output	Input/Output data size

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
07006	Violation of limited data type property
07009	Invalid descriptor index
HY000	General error
HY001	Memory allocation error
HY003	Invalid application buffer type
HY004	Invalid SQL data type
HY009	NULL pointer is incorrectly used. .
HY010	Function sequence error
HY013	Memory management error
HY021	Inconsistent descriptor information
HY090	Invalid character string or buffer length
HY104	Invalid precision or scale value
HY105	Invalid parameter type
HYC00	Optional feature is not implemented.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLBindParameter` function.

3.1.7. SQLCancel

Supported by ISO 92 CLI/ODBC 3.0. This function cancels the operation of the SQL statement that is currently running.

Details of the SQLCancel function are as follows.

Syntax

SQLRETURN SQLCancel (SQLHSTMT StatementHandle);

Parameter

Parameter Purpose Description
StatementHandle Input Statement handle

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to the input parameter is invalid.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
HY000	General error
HY001	Memory allocation error
HY010	Function sequence error
HY013	Memory management error
HY018	Operation is canceled
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLCancel` function.

3.1.8. SQLCloseCursor

Supported by ISO 92 CLI/ODBC 3.0. This function cancels the cursor. In other words, the function closes the currently executing SQL statement and cancels the result.

Details of the SQLCloseCursor function are as follows.

Syntax

SQLRETURN SQLCloseCursor (SQLHSTMT StatementHandle);

Parameter

Parameter Purpose Description
StatementHandle Input Statement handle

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to the input parameter is invalid.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
24000	Invalid cursor status
HY000	General error
HY001	Memory allocation error
HY010	Function sequence error
HY013	Memory management error
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLCloseCursor` function.

3.1.9. SQLColAttribute

Supported by ISO 92 CLI/ODBC 3.0. This function sets up a property to a certain column of the result set and checks the information. If the information to be checked is a character string, the information is returned to the CharacterAttribute parameter, and if it is a number, it is returned to the NumericAttribute parameter.

Before this function is called, the SQLPrepare or SQLExecDirect function should be called.

Details of the SQLColAttribute function are as follows.

Syntax

SQLRETURN SQLColAttribute (SQLHSTMT      StatementHandle,
                           SQLUSMALLINT  ColumnNumber,
                           SQLUSMALLINT  FieldIdentifier,
                           SQLPOINTER    CharacterAttribute,
                           SQLSMALLINT   BufferLength,
                           SQLSMALLINT   *StringLength,
                           SQLPOINTER    NumericAttribute);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle
ColumnNumber	Input	Column position
FieldIdentifier	Input	Information to check
CharacterAttribute	Output	Buffer pointer
BufferLength	Input	The maximum size of buffer
StringLength	Output	Returned character string length
NumericAttribute	Output	Returned number

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to the input parameter is invalid.
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
01004	Character string is truncated from the right.
07005	Prepared statement is out of cursor range.
7009	Invalid descriptor index
HY000	General error
HY001	Memory allocation error
HY008	Operation is canceled
HY010	Function sequence error
HY013	Memory management error
HY090	Invalid character string or buffer length
HY091	Invalid descriptor field identifier
HYC00	Optional feature is not implemented
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLColAttribute` function.

3.1.10. SQLColAttributes (Deprecated)

The SQLColAttributes function is replaced by the SQLColAttribute function in ODBC 3.x.

3.1.11. SQLColumnPrivileges

Supported by ISO 92 CLI/ODBC 1.0. This function searches or returns authorities related to certain table's column list. The returned information is represented as a result set.

Details of the SQLColumnPrivileges function are as follows.

Syntax

SQLRETURN SQLColumnPrivileges (SQLHSTMT        StatementHandle,
                               SQLCHAR         *CatalogName,
                               SQLSMALLINT     NameLength1,
                               SQLCHAR         *SchemaName,
                               SQLSMALLINT     NameLength2,
                               SQLCHAR         *TableName,
                               SQLSMALLINT     NameLength3,
                               SQLCHAR         *ColumnName,
                               SQLSMALLINT     NameLength4);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle
CatalogName	Input	Catalog name
NameLength1	Input	Catalog name length
SchemaName	Input	Schema name
NameLength2	Input	Schema name length
TableName	Input	Table name
NameLength3	Input	Table name length
ColumnName	Input	Column name
NameLength4	Input	Column name length

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to the input parameter is invalid.
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
08S01	Failed to connect server for communication
24000	Invalid cursor state
40001	Serialization failure
40003	The execution has not finished and the transaction state is unknown.
HY000	General error.
HY001	Memory allocation error.
HY008	Operation is canceled.
HY009	NULL pointer is incorrectly used. .
HY010	Function sequence error.
HY013	Memory management error.
HY090	Invalid character string or buffer length.
HYC00	Optional feature is not implemented.
HYT00	Limit time exceeded.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLColumnPrivileges` function.

3.1.12. SQLColumns

Supported by XopenCLI/ISO 92 CLI/ODBC 1.0. This function searches the information of a certain column or list, and returns the result set.

Details of the SQLColumns function are as follows.

Syntax

SQLRETURN SQLColumns (SQLHSTMT       StatementHandle,
                      SQLCHAR        *CatalogName,
                      SQLSMALLINT    NameLength1,
                      SQLCHAR        *SchemaName,
                      SQLSMALLINT    NameLength2,
                      SQLCHAR        *TableName,
                      SQLSMALLINT    NameLength3,
                      SQLCHAR        *ColumnName,
                      SQLSMALLINT    NameLength4);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle
CatalogName	Input	Catalog name
NameLength1	Input	Catalog name length
SchemaName	Input	Schema name to search
NameLength2	Input	Schema name length
TableName	Input	Table name to search
NameLength3	Input	Table name length
ColumnName	Input	Column ID to search
NameLength4	Input	Length of the column ID to search

Return column

The following are columns returned by the SQLColumns function.

Column number	Column name	Data type	Description
1	TABLE_CAT	VARCHAR	Catalog name
2	TABLE_SCHEM	VARCHAR	Schema name
3	TABLE_NAME	VARCHAR(NOT NULL)	Table or view name
4	COLUMN_NAME	VARCHAR(NOT NULL)	Column ID
5	DATA_TYPE	NUMERIC(NOT NULL)	SQL data type for column
6	TYPE_NAME	VARCHAR(NOT NULL)	Character string representing DATA_TYPE column
7	COLUMN_SIZE	NUMERIC	The maximum size of a column
8	BUFFER_LENGTH	NUMERIC	The maximum size of a buffer to store data
9	DECIMAL_DIGITS	NUMERIC	The number of digits after the decimal point, of a column
10	NUM_PREC_RADIX	NUMERIC	One value among 10, 2, or NULL - If DATA_TYPE column is a number: 2 - COLUMN_SIZE column: The number of bits allowed to insert
11	NULLABLE	NUMERIC(NOT NULL)	Whether NULL value can be used.
12	REMARKS	VARCHAR	Column description
13	COLUMN_DEF	VARCHAR	Default value of a column
14	SQL_DATA_TYPE	NUMERIC(NOT NULL)	SQL data type
15	SQL_DATETIME_SUB	NUMERIC	Internal data type
16	CHAR_OCTET_LENGTH	NUMERIC	The maximum number of bytes in a column
17	ORDINAL_POSITION	NUMERIC(NOT NULL)	The original position of table column
18	IS_NULLABLE	VARCHAR	Whether the row contains NULL

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_STILL_EXECUTING	Previously executed SQL statement is not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
08S01	Failed to connect to server for communication.
24000	Invalid cursor state
40001	Serialization failure
40003	The execution is not finished and the transaction state is unknown.
HY000	General error
HY001	Memory allocation error
HY008	Operation is canceled.
HY009	NULL pointer is incorrectly used. .
HY010	Function sequence error
HY013	Memory management error
HY090	Invalid character string or buffer length
HYC00	Optional feature is not implemented.
HYT00	Timeout exceeded.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLColumns` function.

3.1.13. SQLConnect

Supported by ISO 92 CLI/ODBC 1.0. This function configures the database to be connected. Application program provides the database with SQL, and can selectively offer the information related to authority and authentication.

Before this function, the SQLAllocConnect function should be called.

Details of the SQLConnect function are as follows.

Syntax

SQLRETURN SQLConnect(SQLHDBC      ConnectionHandle,
                     SQLCHAR      *ServerName,
                     SQLSMALLINT  NameLength1,
                     SQLCHAR      *UserName,
                     SQLSMALLINT  NameLength2,
                     SQLCHAR      *Authentication,
                     SQLSMALLINT  NameLength3);

Parameter

Parameter	Purpose	Description
ConnectionHandle	Input	Connection handle
ServerName	Input	Database name pointer
NameLength1	Input	Database name length
UserName	Input	User ID pointer
NameLength2	Input	User ID length
Authentication	Input	Password pointer related to authentication
NameLength3	Input	Password pointer related to authentication

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to the input parameter is invalid.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
01S02	Option value has changed.
08001	Client cannot connect to server.
08002	The database connection name is already used.
08004	Server denied the connection.
08S01	Failed to connect to server for communication.
28000	Invalid authority is configured.
HY000	General error
HY001	Memory allocation error
HY013	Memory management error
HY090	Invalid character string or buffer length
HYT00	Timeout exceeded.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLConnect` function.
IM002	Unable to find the datasource name or default driver does not exist.
IM003	Unable to load the configured driver.
IM004	Failed to allocate an environment handle to the driver by using the SQLAllocHandle function.
IM005	Failed to allocate a connection handle to the driver by using the SQLAllocHandle function.
IM006	Failed to configure the database connection properties to the driver by using the SQLSetConnectAttr function.
IM009	Unable to connect to translation DLL.
IM010	Datasource name is longer than the value configured in the SQL_MAX_DSN_LENGTH parameter.

3.1.14. SQLCopyDesc

Supported by ISO 92 CLI/ODBC 3.0. This function copies the descriptor information to other descriptor handles.

Details of the SQLCopyDesc function are as follows.

Syntax

SQLRETURN SQLCopyDesc (SQLHDESC  SourceDescHandle,
                       SQLHDESC  TargetDescHandle);

Parameter

Parameter Purpose Description
SourceDescHandle Input Original descriptor handle
TargetDescHandle Input Target descriptor handle

Parameter	Purpose	Description
SourceDescHandle	Input	Original descriptor handle
TargetDescHandle	Input	Target descriptor handle

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to the input parameter is invalid.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
01S02	Option value has changed.
08001	Client cannot connect to the server.
08002	The database connection name is already used.
08004	Server denied the connection.
08S01	Failed to connect to server for communication.
28000	Invalid authority is configured.
HY000	General error
HY001	Memory allocation error
HY013	Memory management error
HY090	Invalid character string or buffer length
HYT00	Connection timeout.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLCopyDesc` function.
IM002	Unable to find the datasource name or default driver does not exist.
IM003	Unable to load the configured driver.
IM004	Failed to allocate an environment handle to the driver by using the SQLAllocHandle function.
IM005	Failed to allocate a connection handle to the driver by using the SQLAllocHandle function.
IM006	Failed to configure the database connection properties to driver by using the SQLSetConnectAttr function.
IM009	Unable to connect to translation DLL.

3.1.15. SQLDescribeCol

Supported by ISO 92 CLI/ODBC 1.0. This function checks the information of certain column name, data type, precision, scale, and whether NULL is used in the result set.

Before the function is called, SQLPrepare or SQLExecDirect function should be called.

Details of the SQLDescribeCol function are as follows.

Syntax

SQLRETURN SQLDescribeCol (SQLHSTMT       StatementHandle,
                          SQLUSMALLINT   ColumnNumber,
                          SQLCHAR        *ColumnName,
                          SQLSMALLINT    BufferLength,
                          SQLSMALLINT    *NameLength,
                          SQLSMALLINT    *DataType,
                          SQLUINTEGER    *ColumnSize,
                          SQLSMALLINT    *DecimalDigits,
                          SQLSMALLINT    *Nullable);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle
ColumnNumber	Input	Column position
ColumnName	Output	Column name pointer
BufferLength	Input	Buffer size to store the column name
NameLength	Output	Column name length
DataType	Output	Column data type
ColumnSize	Output	Column precision
DecimalDigits	Output	Column scale
Nullable	Output	Whether to allow NULL for the column

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function is finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to the input parameter is invalid.
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
01004	Character string is truncated from the right.
07005	Prepared statement is out of cursor range.
07009	Invalid descriptor index.
08S01	Failed to connect server for communication.
HY000	General error.
HY001	Memory allocation error.
HY008	Operation is canceled.
HY010	Function sequence error.
HY013	Memory management error.
HY090	Invalid character string or buffer length.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLDescribeCol` function.

3.1.16. SQLDescribeParam

Supported by ODBC 1.0. This function returns the descriptor of parameter symbol related to the prepared SQL statement.

Details of the SQLDescribeParam function are as follows.

Syntax

SQLRETURN SQLDescribeParam (SQLHSTMT       StatementHandle,
                            SQLUSMALLINT   ParameterNumber,
                            SQLSMALLINT    *DataType,
                            SQLUINTEGER    *ParameterSize,
                            SQLSMALLINT    *DecimalDigits,
                            SQLSMALLINT    *Nullable);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle.
ParameterNumber	Input	Parameter marker number.
DataType	Output	SQL data type for parameter.
ParameterSize	Output	Buffer pointer to which column size will be returned
DecimalDigits	Output	Buffer pointer to which column precision will be returned
Nullable	Output	Buffer pointer to which the option whether NULL is allowed for the parameter will be returned. Has one value among the following. - SQL_NO_NULLS: NULL is not allowed. - SQL_NULLABLE: NULL is allowed. - SQL_NULLABLE_UNKNOWN: Cannot decide whether NULL is allowed or not.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
07009	Invalid descriptor index.
08S01	Failed to connect server for communication.
21S01	The list to be inserted and the column do not match.
HY000	General error
HY001	Memory allocation error
HY008	Operation is canceled.
HY010	Function sequence error
HY013	Memory management error
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLDescribeParam` function.

3.1.17. SQLDisconnect

Supported by ISO 92 CLI/ODBC 1.0. This function ends the database connection related to a connection handle. If this function is called, the database connection is ended and the handle is canceled. After the handle is successfully canceled, if the SQLConnect function is called, the application program cannot use the connection handle again.

To connect to another database, after calling the function, use SQLConnect or SQLFreeConnect function.

Details of the SQLDisconnect function is as follows.

Syntax

SQLRETURN SQLDisconnect (SQLHDBC ConnectionHandle);

Parameter

Parameter Purpose Description
ConnectionHandle Input Connection handle

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to the input parameter is invalid.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
01002	An error occurred while disconnecting database.
08003	Database connection does not exist.
25000	Invalid transaction state.
HY000	General error.
HY001	Memory allocation error.
HY010	Function sequence error.
HY013	Memory management error.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLDisconnect` function.

3.1.18. SQLDriverConnect

Supported in CLI/ODBC 1.0. This function specifies the target database (to be connected to). This function is used when information, not including the three parameters provided by the SQLConnect function, is required.

SQLAllocConnect must be called before this function.

The following describes the SQLDriverConnect function details.

Syntax

SQLRETURN SQLDriverConnect (SQLHDBC        ConnectionHandle,
                            SQLHWND        WindowHandle,
                            SQLCHAR        *InConnectionString,
                            SQLSMALLINT    StringLength1,
                            SQLCHAR        *OutConnectionString,
                            SQLSMALLINT    BufferLength,
                            SQLSMALLINT    *StringLength2Ptr,
                            SQLUSMALLINT   DriverCompletion);

Parameter

Parameter	Purpose	Description
ConnectionHandle	Input	Connection handle
WindowHandle	Input	Not used. (NULL)
InConnectionString	Input	Connection character string. This string consists of a series of `keyword=value` pairs separated by semicolons. Windows provides DSN, DESC(=Description), UID(=User), PWD(=Password), Server, Port, DB(=Database), SID, Connection Method, and Option as keywords. UNIX series provideDSN, DESC(=Description), UID(=User), PWD(=Password), SID and Option as keywords.
StringLength1	Input	Length of the connection character string.
OutConnectionString	Output	Pointer that saves the completed connection string. Buffer must be a minimum of 1024 bytes. If set to NULL, BufferLength and StringLength2Ptr are also ignored.
BufferLength	Input	Byte length of the buffer.
StringLength2Ptr	Output	Length of the data that is saved in the buffer.
DriverCompletion	Input	Not used. (Input SQL_DRIVER_NOPROMPT)

Return Code

Return Code	Description
SQL_SUCCESS	Function completed successfully.
SQL_SUCCESS_WITH_INFO	Function completed successfully, but a warning message exists.
SQL_INVALID_HANDLE	Handle given to the input parameter is invalid.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
01004	Character string is truncated from the right.
01S02	Option value has changed.
08001	Client cannot connect to server.
08002	Database connection name is already used.
08004	Connected denied by server.
08S01	Failed to connect to server for communication
28000	Invalid authority is configured.
HY000	General error.
HY001	Memory allocation error.
HY013	Memory management error.
HY090	Invalid character string or buffer length.
HYT00	Connection timeout.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLDriverConnect` function.
IM002	Unable to find the datasource name or default driver does not exist.
IM003	Unable to load the configured driver.
IM004	Failed to allocate an environment handle to the driver by using the SQLAllocHandle function.
IM005	Failed to allocate a connection handle to the driver by using the SQLAllocHandle function.
IM006	Failed to configure the database connection properties to the driver by using the SQLSetConnectAttr function.
IM009	Unable to connect to translation DLL.
IM010	Datasource name is longer than the value configured in SQL_MAX_DSN_LENGTH.

3.1.19. SQLEndTran

Supported by ISO 92 CLI/ODBC 3.0. This function commits or rolls back the current transaction. Whether to commit or roll back is decided by the CompletionType Parameter of the SQLEndTran function.

If there is currently no working transaction, the function returns SQL_SUCCESS without accessing database server.

Details of the SQLEndTran function are as follows.

Syntax

SQLRETURN SQLEndTran (SQLSMALLINT   HandleType,
                      SQLHANDLE     Handle,
                      SQLSMALLINT   CompletionType);

Parameter

Parameter	Purpose	Description
HandleType	Input	Handle type to be allocated. Has one value among the following. - SQL_HANDLE_ENV - SQL_HANDLE_DBC
Handle	Input	Handle pointer.
CompletionType	Input	Type which presents whether to commit or to rollback. Has one value among the following. - SQL_COMMIT - SQL_ROLLBACK

Purpose

Description

HandleType

Input

Handle type to be allocated.

Has one value among the following.

- SQL_HANDLE_ENV

- SQL_HANDLE_DBC

Handle

Input

Handle pointer.

CompletionType

Input

Type which presents whether to commit or to rollback.

Has one value among the following.

- SQL_COMMIT

- SQL_ROLLBACK

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to the input parameter is invalid.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
08003	Database connection does not exist.
08007	Failed to connect to the database while processing the transaction.
25S01	Transaction state.
25S02	Transaction has not been activated.
25S03	Transaction has been rolled back.
40001	Serialization failure.
40002	Violation of integrity constraint.
HY000	General error.
HY001	Memory allocation error.
HY010	Function sequence error.
HY012	Invalid transaction operation code.
HY013	Memory management error.
HY092	Invalid property and option identifier.
HYC00	Optional feature is not implemented.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLEndTran` function.

3.1.20. SQLError (Deprecated)

This function returns the information about error and state of the recently called function for a certain command, database connection or environment handle.

Related Function

SQLError is replaced by SQLGetDiagRec in ODBC 3.x.

3.1.21. SQLExecDirect

Supported by ISO 92 CLI/ODBC 1.0. This function directly executes SQL statements except transaction related statements such as commit and rollback.

In order to execute commit or rollback, the SQLTransact function should be called. Before the SQLExecDirect function is called, all parameters should be bound, and the database server to be connected to should be prepared in an SQL statement, in advance. The SQL statements are executed only once.

Details of the SQLExecDirect function are as follows.

Syntax

SQLRETURN SQLExecDirect (SQLHSTMT    StatementHandle,
                         SQLCHAR     *StatementText,
                         SQLINTEGER  TextLength);

Parameter

Parameter Purpose Description
StatementHandle Input Statement handle.
StatementText Input SQL statement.
TextLength Input SQL statement text length.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_NO_DATA	Function has completed, but related data cannot be found. (Ex: No row is updated by the given SQL statement.)
SQL_INVALID_HANDLE	The handle given to the input parameter is invalid.
SQL_NEED_DATA	More data is required to execute the SQL statement. (Ex: Parameter)
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
01001	Cursor operation is conflicted.
01003	NULL is deleted in the configured function.
01004	Character string is truncated from the right.
01006	Unreturned privilege.
01007	Not granted privilege.
01S02	Option value is changed.
01S07	Part of information of numeric type or date type is truncated.
07002	Error in the COUNT field.
07006	Violation of limited data type property.
07S01	Default parameter is incorrectly used.
08S01	Failed to connect server for communication.
21S01	The list to be inserted and the column do not match.
21S02	Table's degree and column do not match.
22001	Character string is truncated from the right.
22002	Indicator variable is required but not offered.
22003	The numeric value is out of range.
22007	Invalid DATETIME type format.
22008	Overflow occurred to the DATETIME field.
22012	Divided by 0.
22015	Overflow occurred to the INTERVAL field.
22018	Invalid character value for cast configuration.
22019	Invalid escape character.
22025	Invalid escape sequence.
23000	Violation of integrity constraint.
24000	Invalid cursor state.
34000	Invalid cursor name.
3D000	Invalid catalog name.
3F000	Invalid schema name.
40001	Serialization failure.
40003	The execution has not finished and the transaction state is unknown.
42000	Syntax error or access violation occurred.
42S01	Base table or view already exists.
42S02	Unable to find the base table or view.
42S11	Index already exists.
42S12	Unable to find the index.
42S21	Column already exists.
42S22	Unable to find the column.
44000	Violation of WITH CHECK OPTION.
HY000	General error.
HY001	Memory allocation error.
HY008	Operation is canceled.
HY009	NULL pointer is incorrectly used. .
HY010	Function sequence error.
HY013	Memory management error.
HY090	Invalid character string or buffer length.
HY105	Invalid parameter type.
HY109	Invalid cursor position.
HYC00	Optional feature is not implemented.
HYT00	Connection timeout.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLExecDirect` function.

3.1.22. SQLExecute

Supported by ISO 92 CLI/ODBC 1.0. This function executes the prepared SQL statements once or multiple times. SQL statements use the SQLBindParameter function to apply the current values to the application program variables which are bound by parameter maker.

If an application program uses the SQLExecute function to process the call result, the SQL statement can be executed again by applying new values to application program variables.

Details of the SQLExecute function are as follows.

Syntax

SQLRETURN SQLExecute (SQLHSTMT StatementHandle);

Parameter

Parameter Purpose Description
StatementHandle Input Statement handle

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_NO_DATA	Function has completed, but related data cannot be found. (Ex: No row is updated by the given SQL statement)
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_NEED_DATA	More data is required to execute the SQL statement. (Ex: Parameter)
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
01001	Cursor operation is conflicted.
01003	NULL is deleted in the configured function.
01004	Character string is truncated from the right.
01006	Unreturned privilege.
01007	Not granted privilege.
01S02	Option value is changed.
01S07	Part of information of numeric type or date type is truncated.
07002	Error in the COUNT field.
07006	Violation of limited data type property.
07S01	Default parameter is incorrectly used.
08S01	Failed to connect server for communication.
21S01	The list to be inserted and the columns do not match.
21S02	Table's degree and column do not match.
22001	Character string is truncated from the right.
22002	Indicator variable is required but not offered.
22003	The numeric value is out of range.
22007	Invalid DATETIME type format.
22008	Overflow occurred to the DATETIME field.
22012	Divided by 0.
22015	Overflow occurred to the INTERVAL field.
22018	Invalid character value for cast configuration.
22019	Invalid escape character.
22025	Invalid escape sequence.
23000	Violation of integrity constraint.
24000	Invalid cursor state.
40001	Serialization failure.
40003	The execution is not finished and the transaction state is unknown.
42000	Syntax error or access violation occurred.
44000	Violation of WITH CHECK OPTION.
HY000	General error.
HY001	Memory allocation error.
HY008	Operation is canceled.
HY010	Function sequence error.
HY013	Memory management error.
HY090	Invalid character string or buffer length.
HY105	Invalid parameter type.
HY109	Invalid cursor position.
HYC00	Optional feature is not implemented.
HYT00	Connection Timeout.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLExecute` function.

3.1.23. SQLExtendedFetch (Deprecated)

The SQLExtendedFetch function is replaced by the SQLFetchScroll function in ODBC 3.x.

3.1.24. SQLExtProcRaiseError

Supported for the external procedure module, this function generates an error.

Details of the SQLExtProcRaiseError function are as follows.

Syntax

void SQL_API SQLExtProcRaiseError(ExtProcContext *Context, 
                                  int            ErrorCode);

Parameter

Parameter Purpose Description
Context Input Context
ErrorCode Input Error code

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	Invalid handle given to the input parameter.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE Description
01000 General warning.
HY000 General error.
HY001 Memory allocation error.

3.1.25. SQLExtProcRaiseErrorWithMsg

Supported for the external procedure module, this function generates an error with a message.

Details of the SQLExtProcRaiseErrorWithMsg function are as follows.

Syntax

void SQL_API SQLExtProcRaiseErrorWithMsg(ExtProcContext    *Context,
                                         int               ErrorCode,
                                         char              *ErrorMessage);

Parameter

Parameter Purpose Description
Context Input Context
ErrorCode Input Error code
ErrorMessage Input Error Message

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	Invalid handle given to the input parameter.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE Description
01000 General warning.
HY000 General error.
HY001 Memory allocation error.

3.1.26. SQLFetch

Supported by ISO 92 CLI/ODBC 1.0. This function executes fetch for the execution result of an SQL statement, and returns data from all the selected columns. In other words, the function moves the cursor to the next row in the result set, and brings bound columns. If no column is bound, no data is returned to the application program, and only the cursor is moved to the next row. After the cursor is moved, unbound column data is deleted.

The SQLFetch function can be called only when the previously executed SQL statement is a SELECT statement.

Details of the SQLFetch function are as follows.

Syntax

SQLRETURN SQLFetch (SQLHSTMT StatementHandle);

Parameter

Parameter Purpose Description
StatementHandle Input Statement handle

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_NO_DATA	Function is completed but related data cannot be found. (Ex: No row is updated by the given SQL statement)
SQL_INVALID_HANDLE	The handle given to the input parameter is invalid.
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
01004	Character string is truncated from the right.
01S01	Error in a row.
01S07	Part of information of numeric type or date type is truncated.
07006	Violation of limited data type property.
07009	Invalid descriptor index.
08S01	Failed to connect server for communication.
22001	Character string is truncated from the right.
22002	Indicator variable is required but not offered.
22003	The numeric value is out of range.
22007	Invalid DATETIME type format.
22012	Divided by 0.
22015	Overflow occurred to the INTERVAL field.
22018	Invalid character value for cast configuration.
24000	Invalid cursor state.
40001	Serialization failure.
40003	The execution is not finished and the transaction state is unknown.
HY000	General error.
HY001	Memory allocation error.
HY008	Operation is canceled.
HY010	Function sequence error.
HY013	Memory management error.
HY090	Invalid character string or buffer length.
HY107	Tried to refer to a row number which does not exist in the result set.
HYC00	Optional feature is not implemented.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLFetch` function.

3.1.27. SQLFetchScroll

Supported by ISO 92 CLI/ODBC 3.0. This function fetches a set of certain rows in the result set, and returns all the selected columns. The set of rows is inserted to either absolute or relative position.

Details of the SQLFetchScroll function are as follows.

Syntax

SQLRETURN SQLFetchScroll (SQLHSTMT     StatementHandle,
                          SQLSMALLINT  FetchOrientation,
                          SQLINTEGER   FetchOffset);

Parameter

Purpose

Description

StatementHandle

Input

Statement handle

FetchOrientation

Input

Scroll type

- SQL_FETCH_NEXT: The next row

- SQL_FETCH_PRIOR: The previous row

- SQL_FETCH_FIRST: The first row

- SQL_FETCH_LAST: The last row

- SQL_FETCH_ABSOLUTE: The FetchOffset th(st,nd,rd) row from the start point

- SQL_FETCH_RELATIVE: The FetchOffset th(st, nd, rd) row from the current row

FetchOffset

Input

The row number to be fetched

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_NO_DATA	Function has completed but related data cannot be found. (Ex: No row is updated by the given SQL statement.)
SQL_INVALID_HANDLE	The handle given to the input parameter is invalid.
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
01004	Character string is truncated from the right.
01S01	Error in a row.
01S06	Tried to fetch before the result set returns the first row set.
01S07	Part of information of numeric type or date type is truncated.
07006	Violation of limited data type property
07009	Invalid descriptor index
08S01	Failed to connect server for communication.
22001	Character string is truncated from the right.
22002	Indicator variable is required but not offered.
22003	The numeric value is out of range.
22007	Invalid DATETIME type format
22012	Divided by 0
22015	Overflow occurred to the INTERVAL field.
22018	Invalid character value for cast configuration
24000	Invalid cursor state
40001	Serialization failure
40003	The execution is not finished and the transaction state is unknown.
HY000	General error
HY001	Memory allocation error
HY008	Operation is canceled.
HY010	Function sequence error
HY013	Memory management error
HY090	Invalid character string or buffer length
HY106	Fetch type is out of range.
HY107	Tried to refer to a row number which does not exist in the result set.
HY111	Invalid bookmark value
HYC00	Optional feature is not implemented.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLFetchScroll` function.

3.1.28. SQLForeignKeys

Supported by ISO 92 CLI/ODBC 1.0. This function searches the information about foreign keys of tables. In other words, the function searches the column of the table that refers to the primary key of other tables or the list of foreign keys that refer to the primary key of the table.

Details of the SQLForeignKeys function are as follows.

Syntax

SQLRETURN SQLForeignKeys (SQLHSTMT       StatementHandle,
                          SQLCHAR        *PKCatalogName,
                          SQLSMALLINT    NameLength1,
                          SQLCHAR        *PKSchemaName,
                          SQLSMALLINT    NameLength2,
                          SQLCHAR        *PKTableName,
                          SQLSMALLINT    NameLength3,
                          SQLCHAR        *FKCatalogName,
                          SQLSMALLINT    NameLength4,
                          SQLCHAR        *FKSchemaName,
                          SQLSMALLINT    NameLength5,
                          SQLCHAR        *FKTableName,
                          SQLSMALLINT    NameLength6);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle
PKCatalogName	Input	Primary key's catalog name
NameLength1	Input	Primary key's catalog name length
PKSchemaName	Input	Primary key's schema name
NameLength2	Input	Primary key's schema name length
PKTableName	Input	Primary key's table name
NameLength3	Input	Primary key's table name length
FKCatalogName	Input	Foreign key's catalog name
NameLength4	Input	Foreign key's catalog name length
FKSchemaName	Input	Foreign key's schema name
NameLength5	Input	Foreign key's schema name length
FKTableName	Input	Foreign key's table name
NameLength6	Input	Foreign key's table name length

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
08S01	Failed to connect server for communication.
24000	Invalid cursor state
40001	Serialization failure
40003	The execution has not finished and the transaction state is unknown.
HY000	General error
HY001	Memory allocation error
HY008	Operation is canceled.
HY009	NULL pointer is incorrectly used. .
HY010	Function sequence error
HY013	Memory management error
HY090	Invalid character string or buffer length
HYC00	Optional feature is not implemented.
HYT00	Timeout exceeded.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLForeignKeys` function.

3.1.29. SQLFreeConnect (Deprecated)

This function invalidates the connection handle, and cancels all related resources. If the SQLFreeConnect function is called when database connection is valid, SQL_ERROR is returned and the connection handle is validated.

Related Function

SQLFreeConnect is replaced by SQLDisconnect in ODBC 3.x.

3.1.30. SQLFreeEnv (Deprecated)

This function invalidates the environment handle, and cancels all related resources. If the SQLFreeEnv function is called when the connection handle is valid, SQL_ERROR is returned and the environment handle is validated.

Before the function is called, the SQLFreeConnect function should be called.

Related Function

SQLFreeEnv is replaced by SQLFreeHandle in ODBC 3.x.

3.1.31. SQLFreeHandle

Supported by ISO 92 CLI/ODBC 3.0. This function cancels the memories allocated to connection, handle, and command statement.

Details of the SQLFreeHandle function are as follows.

Syntax

SQLRETURN SQLFreeHandle (SQLSMALLINT  HandleType,
                         SQLHANDLE    Handle);

Parameter

Purpose

Description

HandleType

Input

Handle type to be canceled.

Has one value among the types below.

- SQL_HANDLE_ENV

- SQL_HANDLE_DBC

- SQL_HANDLE_STMT

Handle

Input

Handle to be canceled.

Return Code

Return Code Description
SQL_SUCCESS Function has finished successfully
SQL_INVALID_HANDLE The handle given to input parameter is invalid
SQL_ERROR Critical error has occurred

SQLSTATE

SQLSTATE	Description
HY000	General error
HY001	Memory allocation error
HY010	Function sequence error
HY013	Memory management error
HY017	Automatically allocated descriptor handle is incorrectly used.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLFreeHandle` function.

3.1.32. SQLFreeStmt

Supported by ISO 92 CLI/ODBC 1.0. This function cancels the memory allocated to a command statement.

After processing an SQL statement, call the SQLFreeStmt function. The function closes the open cursor and reconfigures the parameters. The function also cancels the binding of columns, invalidates the statement handle, and cancels handle related resources. Also, the method to cancel the handle can be configured by the option parameter.

Details of the SQLFreeStmt function are as follows.

Syntax

SQLRETURN SQLFreeStmt (SQLHSTMT      StatementHandle,
                       SQLUSMALLINT  Option);

Parameter

Parameter Purpose Description
StatementHandle Input Statement handle
Option Input Method of canceling the handle

Return Code

Return Code	Description
SQL_SUCCESS	Function has finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
HY000	General error
HY001	Memory allocation error
HY010	Function sequence error
HY013	Memory management error
HY092	Invalid property and option identifier
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLFreeStmt` function.

3.1.33. SQLGetConnectAttr

Supported by ISO 92 CLI/ODBC 3.0. This function returns the properties of the currently configured database connection.

Details of the SQLGetConnectAttr function are as follows.

Syntax

SQLRETURN SQLGetConnectAttr (SQLHDBC       ConnectionHandle,
                             SQLINTEGER    Attribute,
                             SQLPOINTER    Value,
                             SQLINTEGER    BufferLength,
                             SQLINTEGER    *StringLength);

Parameter

Parameter	Purpose	Description
ConnectionHandle	Input	Connection handle
Attribute	Input	Column to be searched
Value	Output	Memory pointer that stores the current value of the column
BufferLength	Input	Buffer size that will store the execution result
StringLength	Output	Value parameter length - In case of the NULL pointer, the length is not returned.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_NO_DATA	Function has completed, but related data cannot be found. (Ex: No row is updated by the given SQL statement.)
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
01004	Character string is truncated from the right.
08003	Database connection does not exist.
08S01	Failed to connect server for communication.
HY000	General error
HY001	Memory allocation error
HY010	Function sequence error
HY013	Memory management error
HY090	Invalid character string or buffer length
HY092	Invalid property and option identifier
HYC00	Optional feature is not implemented.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLGetConnectAttr` function.

3.1.34. SQLGetConnectOption (Deprecated)

The SQLGetConnectOption function is replaced by the SQLGetConnectAttr function in ODBC 3.x.

3.1.35. SQLGetCursorName

Supported by ISO 92 CLI/ODBC 1.0. This function returns the name of the cursor related to the specified statement.

Details of the SQLGetCursorName function are as follows.

Syntax

SQLRETURN SQLGetCursorName (SQLHSTMT       StatementHandle,
                            SQLCHAR        *CursorName,
                            SQLSMALLINT    BufferLength,
                            SQLSMALLINT    *NameLength);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle
CursorName	Output	Buffer pointer that stores cursor name
BufferLength	Input	Buffer pointer that will store the execution result
NameLength	Output	Length of the cursor name

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to the input parameter is invalid.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
01004	Character string is truncated from the right.
HY000	General error
HY001	Memory allocation error
HY010	Function sequence error
HY013	Memory management error
HY015	No available cursor name
HY090	Invalid character string or buffer length
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLGetCursorName` function.

3.1.36. SQLGetData

Supported by ISO 92 CLI/ODBC 1.0. This function searches data for a single column from the current row of the result set. This function can be used instead of the SQLBinCol function that calls the SQLFetch function to send data directly to application program variables.

Details of the SQLGetData function are as follows.

Syntax

SQLRETURN SQLGetData (SQLHSTMT        StatementHandle,
                      SQLUSMALLINT    ColumnNumber,
                      SQLSMALLINT     TargetType,
                      SQLPOINTER      TargetValue,
                      SQLINTEGER      BufferLength,
                      SQLINTEGER      *StrLen_or_Ind);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle
ColumnNumber	Input	Column position to be searched.
TargetType	Input	Buffer's C type to which the searched data will be inserted.
TargetValue	Output	Buffer pointer to which the searched data will be inserted.
BufferLength	Input	Buffer length
StrLen_or_Ind	Output	Length of indicator of the searched data

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_NO_DATA	Function has completed, but related data cannot be found. (Ex: No row is updated by the given SQL statement.)
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_STILL_EXECUTING	Previously executed SQL statement is not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
01004	Character string is truncated from the right.
01S07	Part of information of numeric type or date type is truncated.
07006	Violation of limited data type property
07009	Invalid descriptor index
08S01	Failed to connect server for communication.
22002	Indicator variable is required but not offered.
22003	The numeric value is out of range.
22007	Invalid DATETIME type format
22012	Divided by 0
22015	Overflow occurred to the INTERVAL field.
22018	Invalid character value for cast configuration
24000	Invalid cursor state
HY000	General error
HY001	Memory allocation error
HY003	Invalid application buffer type
HY008	Operation canceled.
HY009	NULL pointer is incorrectly used.
HY010	Function sequence error
HY013	Memory management error
HY090	Invalid character string or buffer length
HY109	Invalid cursor position
HYC00	Optional feature is not implemented.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLGetData` function.

3.1.37. SQLGetDescField

Supported by ISO 92 CLI/ODBC 3.0. This function returns the column value or the currently configured settings of the descriptor record.

Details of the SQLGetDescField function are as follows.

Syntax

SQLRETURN SQLGetDescField (SQLHDESC        DescriptorHandle,
                           SQLSMALLINT     RecNumber,
                           SQLSMALLINT     FieldIdentifier,
                           SQLPOINTER      Value,
                           SQLINTEGER      BufferLength,
                           SQLINTEGER      *StringLength);

Parameter

Parameter	Purpose	Description
DescriptorHandle	Input	Descriptor handle
RecNumber	Input	Descriptor record
FieldIdentifier	Input	Descriptor value column
Value	Output	Buffer pointer that stores the descriptor information
BufferLength	Input	Buffer size that stores the descriptor information
StringLength	Output	The execution result information length

Return Code

Return Code	Description
SQL_SUCCESS	Function is finished successfully.
SQL_SUCCESS_WITH_INFO	Function is successfully finished but there is a warning message.
SQL_NO_DATA	Function is completed but related data cannot be found. (Ex: RecNumber Parameter is bigger than the current number of descriptor record.) Or the descriptor handle is IRD but the cursor does not open.
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
01004	Character string is truncated from the right
07009	Invalid descriptor index
08S01	Failed to connect server for communication
HY000	General error
HY001	Memory allocation error
HY007	SQL statement is not prepared
HY010	Function sequence error
HY013	Memory management error
HY021	Inconsistent descriptor information
HY090	Invalid character string or buffer length
HY091	Invalid descriptor field identifier
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLGetDescField` function

3.1.38. SQLGetDescRec

Supported by ISO 92 CLI/ODBC 3.0. This function returns multiple column values or the currently configured settings of the descriptor record. The column returns the specified name, data type, column, and parameter data storage.

Details of the SQLGetDescRec function are as follows.

Syntax

SQLRETURN SQLGetDescRec (SQLHDESC        DescriptorHandle,
                         SQLSMALLINT     RecNumber,
                         SQLCHAR         *Name,
                         SQLSMALLINT     BufferLength,
                         SQLSMALLINT     *StringLength,
                         SQLSMALLINT     *Type,
                         SQLSMALLINT     *SubType,
                         SQLINTEGER      *Length,
                         SQLSMALLINT     *Precision,
                         SQLSMALLINT     *Scale,
                         SQLSMALLINT     *Nullable);

Parameter

Parameter	Purpose	Description
DescriptorHandle	Input	Descriptor handle
RecNumber	Input	Descriptor record
Name	Output	Buffer pointer that stores column SQL_DESC_NAME
BufferLength	Input	Name Parameter's buffer length
StringLength	Output	The length of returned SQL_DESC_NAME column
Type	Output	Buffer pointer that stores column SQL_DESC_TYPE
SubType	Output	Buffer pointer to which the SQL_DESC_DATETIME_INTERVAL_CODE field value will be returned for SQL_DATETIME type record
Length	Output	Descriptor record length information
Precision	Output	Descriptor record precision information
Scale	Output	Descriptor record scale information
Nullable	Output	Information about whether to allow NULL for descriptor record

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_NO_DATA	Function has completed, but related data cannot be found. (Ex: RecNumber Parameter is bigger than the current number of descriptor record.) Or, descriptor handle is IRD but the cursor does not open.
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
01004	Character string is truncated from the right.
07009	Invalid descriptor index
08S01	Failed to connect server for communication.
HY000	General error
HY001	Memory allocation error
HY007	SQL statement is not prepared.
HY010	Function sequence error
HY013	Memory management error
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLGetDescRec` function.

3.1.39. SQLGetDiagField

Supported by ISO 92 CLI/ODBC 3.0. This function returns a current value of a field in the diagnostic data structure containing state information, error, and warning related a specific handle.

Details of the SQLGetDiagField function are as follows.

Syntax

SQLRETURN SQLGetDiagField (SQLSMALLINT      HandleType,
                           SQLHANDLE        Handle,
                           SQLSMALLINT      RecNumber,
                           SQLSMALLINT      DiagIdentifier,
                           SQLPOINTER       DiagInfo,
                           SQLSMALLINT      BufferLength,
                           SQLSMALLINT      *StringLength);

Parameter

Parameter	Purpose	Description
HandleType	Input	Handle type
Handle	Input	Handle
RecNumber	Input	State record
DiagIdentifier	Input	Diagnostic column of the value to be returned
DiagInfo	Output	Buffer pointer that stores Diagnostic information
BufferLength	Input	Buffer length
StringLength	Output	The execution result information length

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_NO_DATA	Function has completed, but related data cannot be found. (Ex: No row is updated by the given SQL statement.)
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE Description
HY009 NULL pointer is incorrectly used.
HY001 Memory allocation error

3.1.40. SQLGetDiagRec

Supported by ISO 92 CLI/ODBC 3.0. This function returns a current value of a field in the diagnostic data structure containing; state information, error, and warning related a specific handle. Unlike the SQLGetDiagField function that returns only a single column, the function returns SQLSATE, error code, diagnostic message text, etc.

Details of the SQLGetDiagRec function are as follows.

Syntax

SQLRETURN SQLGetDiagRec (SQLSMALLINT      HandleType,
                         SQLHANDLE        Handle,
                         SQLSMALLINT      RecNumber,
                         SQLCHAR          *Sqlstate,
                         SQLINTEGER       *NativeError,
                         SQLCHAR          *MessageText,
                         SQLSMALLINT      BufferLength,
                         SQLSMALLINT      *TextLength);

Parameter

Parameter	Purpose	Description
HandleType	Input	Handle type
Handle	Input	Handle
RecNumber	Input	State record
Sqlstate	Output	SQLSTATE code
NativeError	Output	Default error code
MessageText	Output	Text string of a diagnostic message
BufferLength	Input	Buffer length to store text string of a diagnostic message
TextLength	Output	Length of text string of a diagnostic message

Return Code

Return Code	Description
SQL_SUCCESS	Function is finished successfully.
SQL_SUCCESS_WITH_INFO	Function is successfully finished but there is a warning message.
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_ERROR	Function is completed but related data cannot be found. (Ex: RecNumber Parameter is 0 or negative number.) Or, buffer length is smaller than 0.

SQLSTATE

SQLSTATE Description
HY009 NULL pointer is incorrectly used.
HY001 Memory allocation error

3.1.41. SQLGetEnvAttr

Supported by ISO 92 CLI/ODBC 3.0. This function returns the current value of a column that is related to the environment handle.

Details of the SQLGetEnvAttr function are as follows.

Syntax

SQLRETURN SQLGetEnvAttr (SQLHENV        EnvironmentHandle,
                         SQLINTEGER     Attribute,
                         SQLPOINTER     Value,
                         SQLINTEGER     BufferLength,
                         SQLINTEGER     *StringLength);

Parameter

Parameter	Purpose	Description
EnvironmentHandle	Input	Environment handle
Attribute	Input	Column to be searched.
Value	Output	Current value of column
BufferLength	Input	The maximum length if a value parameter is a character string.
StringLength	Output	The execution result information length

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_NO_DATA	Function is completed but related data cannot be found. (Ex: No row is updated by the given SQL statement.)
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
01004	Character string is truncated from the right.
HY000	General error
HY001	Memory allocation error
HY013	Memory management error
HY092	Invalid property and option identifier
HYC00	Optional feature is not implemented.
IM001	Driver does not support the `SQLGetEnvAttr` function.

3.1.42. SQLGetExtProcAllocMemory

Supported for the external procedure module, this function allocates a statement handle using the context of the extproc.

Details of the SQLGetExtProcAllocMemory function are as follows.

Syntax

SQLPOINTER SQL_API SQLExtProcAllocMemory(ExtProcContext     *Context,
                                         SQLUINTEGER        AllocSize);

Parameter

Parameter Purpose Description
Context Input Context
AllocSize Input Allocation size

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE Description
01000 General warning
HY000 General error
HY001 Memory allocation error

3.1.43. SQLGetExtProcConnect

Supported for the external procedure module, this function allocates environment variables and connections using the context and connect of the extproc.

Details of the SQLGetExtProcConnect function are as follows.

Syntax

SQLRETURN SQL_API SQLGetExtProcConnect(ExtProcContext  *Context,
                                       SQLHENV         *EnvironmentHandle,
                                       SQLHDBC         *ConnectionHandle,
                                       SQLSMALLINT     *ErrorHandleType,
                                       SQLHANDLE       *ErrorHandle);

Parameter

Parameter Purpose Description
Context Input Context
EnvironmentHandle Input Environment handle
ConnectionHandle Output Connection handle
ErrorHandleType Output Error handle type
ErrorHandle Output Error handle

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE Description
01000 General warning
HY000 General error
HY001 Memory allocation error

3.1.44. SQLGetFunctions

Supported by ISO 92 CLI/ODBC 1.0. This function is used to know whether a driver supports a certain function. The function can be used both in the driver manager and the driver. If the function is used within a driver, driver manager calls functions within the driver.

Details of the SQLGetFunctions function are as follows.

Syntax

SQLRETURN SQLGetFunctions (SQLHDBC         ConnectionHandle,
                           SQLUSMALLINT    FunctionId,
                           SQLUSMALLINT    *Supported);

Parameter

Purpose

Description

ConnectionHandle

Input

Connection handle

FunctionId

Input

Defined value which will call a ODBC function

Supported

Output

Buffer pointer that will store the information whether the requested function is supported

- SQL_TRUE

- SQL_FALSE

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
08S01	Failed to connect to server for communication.
HY000	General error
HY001	Memory allocation error
HY010	Function sequence error
HY013	Memory management error
HY095	Function out of range
HYT01	Database connection time limit exceeded.

3.1.45. SQLGetInfo

Supported by ISO 92 CLI/ODBC 1.0. This function returns general information about a datasource related to driver connection.

Details of the SQLGetInfo function are as follows.

Syntax

SQLRETURN SQLGetInfo (SQLHDBC        ConnectionHandle,
                      SQLUSMALLINT   InfoType,
                      SQLPOINTER     InfoValue,
                      SQLSMALLINT    BufferLength,
                      SQLSMALLINT    *StringLength);

Parameter

Parameter	Purpose	Description
ConnectionHandle	Input	Connection handle
InfoType	Input	Information type
InfoValue	Output	Buffer pointer to store information
BufferLength	Input	Buffer length
StringLength	Output	Returned information length

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
01004	Character string is truncated from the right.
08003	Database connection does not exist.
08S01	Failed to connect server for communication.
HY000	General error
HY001	Memory allocation error
HY013	Memory management error
HY024	Invalid property value
HY090	Invalid character string or buffer length
HY096	Information type out of range
HYC00	Optional feature is not implemented.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLGetInfo` function.

3.1.46. SQLGetStmtAttr

Supported by ISO 92 CLI/ODBC 3.0. This function returns the current value of SQL statement properties.

Details of the SQLGetStmtAttr function are as follows.

Syntax

SQLRETURN SQLGetStmtAttr (SQLHSTMT       StatementHandle,
                          SQLINTEGER     Attribute,
                          SQLPOINTER     Value,
                          SQLINTEGER     BufferLength,
                          SQLINTEGER     *StringLength);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle
Attribute	Input	Property to be searched
Value	Output	Buffer pointer to which the current value of the specified property will be returned
BufferLength	Input	Buffer length
StringLength	Output	Returned result length

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
01004	Character string is truncated from the right.
24000	Invalid cursor state
HY000	General error
HY001	Memory allocation error
HY010	Function sequence error
HY013	Memory management error
HY090	Invalid character string or buffer length
HY092	Invalid property and option identifier
HY109	Invalid cursor position
HYC00	Optional feature is not implemented.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLGetStmtAttr` function.

3.1.47. SQLGetStmtOption (Deprecated)

The SQLGetStmtOption function is replaced by the SQLGetStmtAttr function in ODBC 3.x.

3.1.48. SQLGetTypeInfo

Supported by ISO 92 CLI/ODBC 1.0. This function returns the information of data types supported by a datasource. The information is returned as a result set of an SQL statement execution.

If the function is called in ALTER TABLE or CREATE TABLE statements, application program uses the name of type that is returned as TYPE_NAME column of result set.

Details of the SQLGetTypeInfo function are as follows.

Syntax

SQLRETURN SQLGetTypeInfo (SQLHSTMT     StatementHandle,
                          SQLSMALLINT  DataType);

Parameter

Parameter Purpose Description
StatementHandle Input Statement handle
DataType Input SQL data type

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
01S02	Option value has changed.
08S01	Failed to connect to server for communication
24000	Invalid cursor state
40001	Serialization failure
40003	The execution has not finished and the transaction state is unknown.
HY000	General error
HY001	Memory allocation error
HY004	Invalid SQL data type
HY008	Operation is canceled.
HY010	Function sequence error
HY013	Memory management error
HYC00	Optional feature is not implemented.
HYT00	Timeout exceeded.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLGetTypeInfo` function.

3.1.49. SQLMoreResults

Supported by ISO 92 CLI/ODBC 1.0. This function decides whether an SQL statement, which includes SELECT, UPDATE, INSERT, and DELETE statements, additionally uses the execution result. If the execution result is additionally used, the function initializes the result.

Details of the SQLMoreResults function are as follows.

Syntax

SQLRETURN SQLMoreResults(SQLHSTMT StatementHandle);

Parameter

Parameter Purpose Description
StatementHandle Input Statement handle

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_NO_DATA	Function has completed, but related data cannot be found. (Ex: No row is updated by the given SQL statement.)
SQL_INVALID_HANDLE	The handle given to the input parameter is invalid.
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning
01S02	Option value has changed.
08S01	Failed to connect server for communication.
40001	Serialization failure
40003	The execution has not finished and the transaction state is unknown.
HY000	General error
HY001	Memory allocation error
HY008	Operation is canceled.
HY010	Function sequence error
HY013	Memory management error
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLMoreResults` function.

3.1.50. SQLNativeSql

Supported by ODBC 1.0. This function returns SQL character string that is changed by the driver. The SQL statement is not executed.

Details of the SQLNativeSql function are as follows.

Syntax

SQLRETURN SQLNativeSql (SQLHDBC       ConnectionHandle,
                        SQLCHAR       *InStatementText,
                        SQLINTEGER    TextLength1,
                        SQLCHAR       *OutStatementText,
                        SQLINTEGER    BufferLength,
                        SQLINTEGER    *TextLength2Ptr);

Parameter

Parameter	Purpose	Description
ConnectionHandle	Input	Connection handle
InStatementText	Input	SQL character string to be changed
TextLength1	Input	SQL character string length to be changed
OutStatementText	Output	Returned SQL character string
BufferLength	Input	Buffer length to store a returned SQL character string
TextLength2Ptr	Output	Length of a returned result

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to an input parameter is invalid.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
01004	Character string is truncated from the right.
08003	Database connection does not exist.
08S01	Failed to connect server for communication.
22007	Invalid DATETIME type format.
24000	Invalid cursor state.
HY000	General error.
HY001	Memory allocation error.
HY009	NULL pointer is incorrectly used.
HY013	Memory management error.
HY090	Invalid character string or buffer length.
HY109	Invalid cursor position.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLNativeSql` function.

3.1.51. SQLNumParams

Supported by ODBC 1.0. This function returns the number of parameters within an SQL statement.

Details of the SQLNumParams function are as follows.

Syntax

SQLRETURN SQLNumParams (SQLHSTMT       StatementHandle,
                        SQLSMALLINT    *ParameterCountPtr);

Parameter

Parameter Purpose Description
StatementHandle Input Statement handle.
ParameterCountPtr Output Buffer pointer to store the return information.

Return Code

Return Code	Description
SQL_SUCCESS	Function is finished successfully.
SQL_SUCCESS_WITH_INFO	Function is successfully finished but there is a warning message.
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_STILL_EXECUTING	Previously executed SQL statement is not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
08S01	Failed to connect server for communication.
HY000	General error.
HY001	Memory allocation error.
HY008	Operation is canceled.
HY010	Function sequence error.
HY013	Memory management error.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLNumParams` function.

3.1.52. SQLNumResultCols

Supported by ISO 92 CLI/ODBC 1.0. This function returns the number of columns of a result set related to an input statement handle. If the recently executed SQL statement is not a SELECT statement, the function returns 0.

Before the function is called, SQLPrepare or SQLExecDirect function should be called.

Details of the SQLNumResultCols function are as follows.

Syntax

SQLRETURN SQLNumResultCols (SQLHSTMT        StatementHandle,
                            SQLSMALLINT     *ColumnCount);

Parameter

Parameter Purpose Description
StatementHandle Input Statement handle.
ColumnCount Output Pointer to store the result.

Return Code

Return Code	Description
SQL_SUCCESS	Function is finished successfully.
SQL_SUCCESS_WITH_INFO	Function is successfully finished but there is a warning message.
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
08S01	Failed to connect server for communication.
HY000	General error.
HY001	Memory allocation error.
HY008	Operation is canceled.
HY010	Function sequence error.
HY013	Memory management error.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLNumResultCols` function.

3.1.53. SQLParamData

Supported by ISO 92 CLI/ODBC 1.0. This function supports parameter data when executing an SQL statement. This function is used along with the SQLPutData function.

Details of the SQLParamData function are as follows.

Syntax

SQLRETURN SQLParamData (SQLHSTMT       StatementHandle,
                        SQLPOINTER     *Value);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle
Value	Output	Buffer pointer to store the ParameterValue parameter of the `SQLBindParameter` function, or the TargetValue parameter of the `SQLBindCol` function.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_NO_DATA	Function has completed, but related data cannot be found. (Ex: No row is updated by the given SQL statement.)
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_NEED_DATA	More data is required to execute the SQL statement. (Ex: Parameter)
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
07006	Violation of limited data type property.
08S01	Failed to connect server for communication.
22026	Character string data with invalid length.
40001	Serialization failure.
40003	The execution has not finished and the transaction state is unknown.
HY000	General error.
HY001	Memory allocation error.
HY008	Operation is canceled.
HY010	Function sequence error.
HY013	Memory management error.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLParamData` function.

3.1.54. SQLParamOptions (Deprecated)

The SQLParamOptions function is replaced by the SQLSetStmtAttr function in ODBC 3.x.

3.1.55. SQLPrepare

Supported by ISO 92 CLI/ODBC 1.0. This function prepares the SQL statements to be executed. In other words, the function connects an SQL statement with an input command handle, and sends the command to the database to be prepared.

Details of the SQLPrepare function are as follows.

Syntax

SQLRETURN SQLPrepare (SQLHSTMT     StatementHandle,
                      SQLCHAR      *StatementText,
                      SQLINTEGER   TextLength);

Parameter

Parameter Purpose Description
StatementHandle Input Statement handle
StatementText Input SQL statement
TextLength Input SQL statement length

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to the input parameter is invalid.
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
01S02	Option value is changed.
08S01	Failed to connect server for communication.
21S01	The list to be inserted and the columns do not match.
21S02	Table's degree and column do not match.
22018	Invalid character value for cast configuration.
22019	Invalid escape character.
22025	Invalid escape sequence.
24000	Invalid cursor state.
34000	Invalid cursor name.
3D000	Invalid catalog name.
3F000	Invalid schema name.
42000	Syntax error or access violation occurred.
42S01	Base table or view already exists.
42S02	Unable to find the base table or view.
42S11	Index already exists.
42S12	Unable to find the index.
42S21	Column already exists.
42S22	Unable to find the column.
HY000	General error.
HY001	Memory allocation error.
HY008	Operation is canceled.
HY009	NULL pointer is incorrectly used.
HY010	Function sequence error.
HY013	Memory management error.
HY090	Invalid character string or buffer length.
HYC00	Optional feature is not implemented.
HYT00	Timeout exceeded.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLPrepare` function.

3.1.56. SQLPrimaryKeys

Supported by ISO 92 CLI/ODBC 1.0. This function returns the information about the primary key of a certain table, as a list.

Details of the SQLPrimaryKeys function are as follows.

Syntax

SQLRETURN SQLPrimaryKeys (SQLHSTMT      StatementHandle,
                          SQLCHAR       *CatalogName,
                          SQLSMALLINT   NameLength1,
                          SQLCHAR       *SchemaName,
                          SQLSMALLINT   NameLength2,
                          SQLCHAR       *TableName,
                          SQLSMALLINT   NameLength3);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle.
CatalogName	Input	Catalog name.
NameLength1	Input	Catalog name length.
SchemaName	Input	Schema name.
NameLength2	Input	Schema name length.
TableName	Input	Table name.
NameLength3	Input	Table name length.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully but there is a warning message.
SQL_INVALID_HANDLE	The handle given to the input parameter is invalid.
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
08S01	Failed to connect server for communication.
24000	Invalid cursor state.
40001	Serialization failure.
40003	The execution has not finished and the transaction state is unknown.
HY000	General error.
HY001	Memory allocation error.
HY008	Operation is canceled.
HY009	NULL pointer is incorrectly used.
HY010	Function sequence error.
HY013	Memory management error.
HY090	Invalid character string or buffer length.
HYC00	Optional feature is not implemented.
HYT00	Limit time exceeded.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLPrimaryKeys` function.

3.1.57. SQLProcedureColumns

Supported by ODBC 1.0. This function returns not only the columns that compose specified procedure result set but also the list of input/output parameters. They are returned as a result set of specified statements.

Details of the SQLProcedureColumns function are as follows.

Syntax

SQLRETURN SQLProcedureColumns (SQLHSTMT      StatementHandle,
                               SQLCHAR       *CatalogName,
                               SQLSMALLINT   NameLength1,
                               SQLCHAR       *SchemaName,
                               SQLSMALLINT   NameLength2,
                               SQLCHAR       *ProcName,
                               SQLSMALLINT   NameLength3,
                               SQLCHAR       *ColumnName,
                               SQLSMALLINT   NameLength4);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle.
CatalogName	Input	Catalog name.
NameLength1	Input	Catalog name length.
SchemaName	Input	Schema name.
NameLength2	Input	Schema name length.
ProcName	Input	Procedure name.
NameLength3	Input	Procedure name length.
ColumnName	Input	Column name.
NameLength4	Input	Column name length.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to the input parameter is invalid.
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
08S01	Failed to connect server for communication.
24000	Invalid cursor state.
40001	Serialization failure.
40003	The execution has not finished and the transaction state is unknown.
HY000	General error
HY001	Memory allocation error.
HY008	Operation is canceled.
HY009	NULL pointer is incorrectly used.
HY010	Function sequence error.
HY090	Invalid character string or buffer length.
HYC00	Optional feature is not implemented.
HYT00	Timeout exceeded.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLProcedureColumns` function.

3.1.58. SQLProcedures

Supported by ODBC 1.0. This function returns the list of procedure names stored in the specified datasource.

Details of the SQLProcedures function are as follows.

Syntax

SQLRETURN SQLProcedures (SQLHSTMT      StatementHandle,
                         SQLCHAR       *CatalogName,
                         SQLSMALLINT   NameLength1,
                         SQLCHAR       *SchemaName,
                         SQLSMALLINT   NameLength2,
                         SQLCHAR       *ProcName,
                         SQLSMALLINT   NameLength3);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle.
CatalogName	Input	Catalog name.
NameLength1	Input	Catalog name length.
SchemaName	Input	Schema name.
NameLength2	Input	Schema name length.
ProcName	Input	Procedure name.
NameLength3	Input	Procedure name length.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to the input parameter is invalid.
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
08S01	Failed to connect server for communication.
24000	Invalid cursor state.
40001	Serialization failure.
40003	The execution has not finished and the transaction state is unknown.
HY000	General error.
HY001	Memory allocation error.
HY008	Operation is canceled.
HY009	NULL pointer is incorrectly used.
HY010	Function sequence error.
HY013	Memory management error.
HY090	Invalid character string or buffer length.
HYC00	Optional feature is not implemented.
HYT00	Limit time exceeded.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLProcedures` function.

3.1.59. SQLPutData

Supported by ISO 92 CLI/ODBC 1.0. This function allows parameter or column data to be sent to the driver when the application program executes an SQL statement. The function is used to send character or binary data values to a column that has the data type used in a character, binary or a certain datasource.

The function supports the unicode C data type to be bound, even when the current driver does not support the unicode data.

Details of the SQLPutData function are as follows.

Syntax

SQLRETURN SQLPutData (SQLHSTMT      StatementHandle,
                      SQLPOINTER    Data,
                      SQLINTEGER    StrLen_or_Ind);

Parameter

Parameter Purpose Description
StatementHandle Input Statement handle.
Data Input Buffer pointer to store actual data of parameter or column.
StrLen_or_Ind Input Data length.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to the input parameter is invalid.
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
01004	Character string is truncated from the right.
07006	Violation of limited data type property.
07S01	Default parameter is incorrectly used.
08S01	Failed to connect server for communication.
22001	Character string is truncated from the right.
22003	The numeric value is out of range.
22007	Invalid DATETIME type format.
22008	Overflow occurred to the DATETIME field.
22012	Divided by 0.
22015	Overflow occurred to the INTERVAL field.
22018	Invalid character value for cast configuration.
HY000	General error.
HY001	Memory allocation error.
HY008	Operation is canceled.
HY009	NULL pointer is incorrectly used.
HY010	Function sequence error.
HY013	Memory management error.
HY019	Data that is neither character nor binary was sent by being divided.
HY020	Tried on union of NULL value.
HY090	Invalid character string or buffer length.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLPutData` function.

3.1.60. SQLRowCount

Supported by ISO 92 CLI/ODBC 1.0. This function returns the number of rows of tables which were affected by UPDATE, INSERT, and DELETE statements, or views related to the tables. The function returns 0 if the recently executed SQL statement is not an UPDATE, INSERT, or DELETE statement, or the execution has failed.

Before the function is executed, the SQLExecute function or the SQLExecDirect function should be called.

Details of the SQLRowCount function are as follows.

Syntax

SQLRETURN SQLRowCount (SQLHSTMT     StatementHandle,
                       SQINTEGER    *RowCount);

Parameter

Parameter Purpose Description
StatementHandle Input Statement handle.
RowCount Output Pointer to store the rows of execution result.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to an input parameter is invalid.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
HY000	General error.
HY001	Memory allocation error.
HY010	Function sequence error.
HY013	Memory management error.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLRowCount` function.

3.1.61. SQLSetConnectAttr

Supported by ISO 92 CLI/ODBC 3.0. This function configures the connection property values for a certain database connection. All the configured database connections and command options are kept until the SQLFreeConnect function is called or they are reconfigured by the SQLSetConnectAttr function.

Details of the SQLSetConnectAttr function are as follows.

Syntax

SQLRETURN SQLSetConnectAttr (SQLHDBC       ConnectionHandle,
                             SQLINTEGER    Attribute,
                             SQLPOINTER    Value,
                             SQLINTEGER    StringLength);

Parameter

Parameter	Purpose	Description
ConnectionHandle	Input	Connection handle.
Attribute	Input	Properties to be configured.
Value	Input	Buffer pointer that contains the property values to be configured.
StringLength	Input	Buffer length.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
01S02	Option value is changed.
08002	The database connection name is already used.
08003	Database connection does not exist.
08S01	Failed to connect server for communication.
24000	Invalid cursor state.
3D000	Invalid catalog name.
HY000	General error.
HY001	Memory allocation error.
HY009	NULL pointer is incorrectly used.
HY010	Function sequence error.
HY011	The property cannot be currently configured.
HY013	Memory management error.
HY024	Invalid property value.
HY090	Invalid character string or buffer length.
HY092	Invalid property and option identifier.
HYC00	Optional feature is not implemented.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLSetConnectAttr` function.
IM009	Unable to load translation DDL.

3.1.62. SQLSetConnectOption (Deprecated)

The SQLSetConnectOption function is replaced by the SQLSetConnectAttr function in ODBC 3.x.

3.1.63. SQLSetCursorName

Supported by ISO 92 CLI/ODBC 1.0. This function relates the currently executing SQL statement with a cursor name. If the application program does not call the function, the driver creates a cursor name required to execute the SQL statement.

Details of the SQLSetCursorName function are as follows.

Syntax

SQLRETURN SQLSetCursorName (SQLHSTMT     StatementHandle,
                            SQLCHAR      *CursorName,
                            SQLSMALLINT  NameLength);

Parameter

Parameter Purpose Description
StatementHandle Input Statement handle.
CursorName Input Cursor name.
NameLength Input Cursor name length.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully but there is a warning message.
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
01004	Character string is truncated from the right.
24000	Invalid cursor state.
34000	Invalid cursor name.
3C000	Duplicated cursor name.
HY000	General error.
HY001	Memory allocation error.
HY009	NULL pointer is incorrectly used.
HY010	Function sequence error.
HY013	Memory management error.
HY090	Invalid character string or buffer length.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLSetCursorName` function.

3.1.64. SQLSetDescField

Supported by ISO 92 CLI/ODBC 3.0. This function configures a field value of a descriptor record.

Details of the SQLSetDescField function are as follows.

Syntax

SQLRETURN SQLSetDescField (SQLHDESC       DescriptorHandle,
                           SQLSMALLINT    RecNumber,
                           SQLSMALLINT    FieldIdentifier,
                           SQLPOINTER     Value,
                           SQLINTEGER     BufferLength);

Parameter

Parameter	Purpose	Description
DescriptorHandle	Input	Descriptor handle.
RecNumber	Input	The field record number in the descriptor. (Record number starts from 1.)
FieldIdentifier	Input	Field identifier to be configured.
Value	Input	Buffer pointer which stores the value to be configured.
BufferLength	Input	Buffer length.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
01S02	Option value is changed.
07009	Invalid descriptor index.
08S01	Failed to connect server for communication.
22001	Character string is truncated from the right.
HY000	General error.
HY001	Memory allocation error.
HY010	Function sequence error.
HY013	Memory management error.
HY016	Implementation row descriptor cannot be edited.
HY021	Inconsistent descriptor information.
HY090	Invalid character string or buffer length.
HY091	Invalid descriptor field identifier.
HY092	Invalid property and option identifier.
HY105	Invalid parameter type.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLSetDescField` function.

3.1.65. SQLSetDescRec

Supported by ISO 92 CLI/ODBC 3.0. This function configures multiple descriptor columns for a buffer and data types that are used in a column or parameter data.

Details of the SQLSetDescRec function are as follows.

Syntax

SQLRETURN SQLSetDescRec (SQLHDESC       DescriptorHandle,
                         SQLSMALLINT    RecNumber,
                         SQLSMALLINT    Type,
                         SQLSMALLINT    SubType,
                         SQLINTEGER     Length,
                         SQLSMALLINT    Precision,
                         SQLSMALLINT    Scale,
                         SQLPOINTER     Data,
                         SQLINTEGER     *StringLength,
                         SQLINTEGER     *Indicator);

Parameter

Parameter	Purpose	Description
DescriptorHandle	Input	Descriptor handle.
RecNumber	Input	Descriptor record that includes the columns to be configured.
Type	Input	Descriptor record types.
SubType	Input	Descriptor record sub types.
Length	Input	Descriptor record's length column.
Precision	Input	Descriptor record's precision column.
Scale	Input	Descriptor record's scale column.
Data	In/output	Descriptor record's data pointer column.
StringLength	In/output	Descriptor record's character string length column.
Indicator	In/output	Descriptor record's indicator pointer column.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to an input parameter is invalid.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
07009	Invalid descriptor index.
08S01	Failed to connect server for communication.
HY000	General error.
HY001	Memory allocation error.
HY010	Function sequence error.
HY013	Memory management error.
HY016	Implementation row descriptor cannot be edited.
HY021	Inconsistent descriptor information.
HY090	Invalid character string or buffer length.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLSetDescRec` function.

3.1.66. SQLSetEnvAttr

Supported by ISO 92 CLI/ODBC 3.0. This function configures property values of the current environment handle.

Details of the SQLSetEnvAttr function are as follows.

Syntax

SQLRETURN SQLSetEnvAttr (SQLHENV      EnvironmentHandle,
                         SQLINTEGER   Attribute,
                         SQLPOINTER   Value,
                         SQLINTEGER   StringLength);

Parameter

Parameter	Purpose	Description
EnvironmentHandle	Input	Environment handle.
Attribute	Input	Environment handle property to be configured.
Value	Input	Environment handle property value to be configured.
StringLength	Input	The length if the environment handles property value to be configured, is a string.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to an input parameter is invalid.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
01S02	Option value is changed.
HY000	General error.
HY001	Memory allocation error.
HY009	NULL pointer is incorrectly used.
HY010	Function sequence error.
HY013	Memory management error.
HY024	Invalid property value.
HY090	Invalid character string or buffer length.
HY092	Invalid property and option identifier.
HYC00	Optional feature is not implemented.

3.1.67. SQLSetParam (Deprecated)

The SQLSetParam function is replaced by the SQLBindParameter function in ODBC 3.x.

3.1.68. SQLSetPos

Supported by ODBC 1.0. This function configures the cursor position or allows application program to refresh data within a row set. The function can also update or delete the data in the result set.

Details of the SQLSetPos function are as follows.

Syntax

SQLRETURN SQLSetPos (SQLHSTMT       StatementHandle,
                     SQLUSMALLINT   RowNumber,
                     SQLUSMALLINT   Operation,
                     SQLUSMALLINT   LockType);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle.
RowNumber	Input	Row position in the row set.
Operation	Input	Operations to be executed.
LockType	Input	Lock types for rows after operation is executed.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully but there is a warning message.
SQL_INVALID_HANDLE	The handle given to an input parameter is invalid.
SQL_NEED_DATA	More data is required to execute the SQL statement. (Ex: Parameter)
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
01001	Cursor operation is conflicted.
01004	Character string is truncated from the right.
01S01	Error in a row.
01S07	The fractional part of the number of a numeric type or date type is truncated.
07006	Violation of limited data type property.
07009	Invalid descriptor index.
21S02	Table's degree and column do not match.
22001	Character string is truncated from the right.
22003	The numeric value is out of range.
22007	Invalid DATETIME type format.
22008	Overflow occurred to the DATETIME field.
22015	Overflow occurred to the INTERVAL field.
22018	Invalid character value for cast configuration.
23000	Violation of integrity constraint.
24000	Invalid cursor state.
40001	Serialization failure.
40003	The execution has not finished and the transaction state is unknown.
42000	Syntax error or access violation occurred.
44000	Violation of WITH CHECK OPTION.
HY000	General error.
HY001	Memory allocation error.
HY008	Operation is canceled.
HY010	Function sequence error.
HY011	The property cannot be configured currently.
HY013	Memory management error.
HY090	Invalid character string or buffer length.
HY092	Invalid property identifier.
HY107	Tried to refer to a row number which does not exist in the result set.
HY109	Invalid cursor position.
HYC00	Optional feature is not implemented.
HYT00	Timeout exceeded.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLSetPos` function.

3.1.69. SQLSetScrollOptions (Deprecated)

The SQLSetScrollOptions function is replaced by the SQLGetInfo function and the SQLSetStmtAttr function in ODBC 3.x.

3.1.70. SQLSetStmtAttr

Supported by ISO 92 CLI/ODBC 3.0. This function configures properties of a certain statement handle. Unless the properties are reconfigured by a new SQLSetStmtAttr function or the statement handle is deleted, the configured properties remain.

Details of the SQLSetStmtAttr function are as follows.

Syntax

SQLRETURN SQLSetStmtAttr (SQLHSTMT      StatementHandle,
                          SQLINTEGER    Attribute,
                          SQLPOINTER    Value,
                          SQLINTEGER    StringLength);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle.
Attribute	Input	Statement handle property to be configured.
Value	Input	Statement handle property value to be configured.
StringLength	Input	The length, if the statement handle property value to be configured is a string

Return Code

Return Code	Description
SQL_SUCCESS	Function is finished successfully.
SQL_SUCCESS_WITH_INFO	Function is successfully finished but there is a warning message.
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
01S02	Option value is changed.
08S01	Failed to connect server for communication.
24000	Invalid cursor state.
HY000	General error.
HY001	Memory allocation error.
HY009	NULL pointer is incorrectly used.
HY010	Function sequence error.
HY011	The property cannot be configured currently.
HY013	Memory management error.
HY017	Automatically allocated descriptor handle is incorrectly used.
HY024	Invalid property value.
HY090	Invalid character string or buffer length.
HY092	Invalid property and option identifier.
HYC00	Optional feature is not implemented.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLSetStmtAttr` function.

3.1.71. SQLSetStmtOption (Deprecated)

The SQLSetStmtOption function is replaced by the SQLSetStmtAttr function in ODBC 3.x.

3.1.72. SQLSpecialColumns

Supported by Xopen CLI/ISO 92 CLI/ODBC 1.0. This function searches information of a certain column in a table.

The searched column information includes the optimal set of columns that configure only a single row in the table, and the automatically changed columns when a transaction changes a value of a row.

Details of the SQLSpecialColumns function are as follows.

Syntax

SQLRETURN SQLSpecialColumns (SQLHSTMT        StatementHandle,
                             SQLUSMALLINT    IdentifierType,
                             SQLCHAR         *CatalogName,
                             SQLSMALLINT     NameLength1,
                             SQLCHAR         *SchemaName,
                             SQLSMALLINT     NameLength2,
                             SQLCHAR         *TableName,
                             SQLSMALLINT     NameLength3,
                             SQLUSMALLINT    Scope,
                             SQLUSMALLINT    Nullable);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle.
IdentifierType	Input	Column type to be returned.
CatalogName	Input	Catalog name.
NameLength1	Input	Catalog name length.
SchemaName	Input	Schema name.
NameLength2	Input	Schema name length.
TableName	Input	Table name.
NameLength3	Input	Table name length.
Scope	Input	Minimum range of ROWID.
Nullable	Input	Whether to allow NULL value

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to an input parameter is invalid.
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
08S01	Failed to connect server for communication.
24000	Invalid cursor state.
40001	Serialization failure.
40003	The execution has not finished and the transaction state is unknown.
HY000	General error.
HY001	Memory allocation error.
HY008	Operation is canceled.
HY009	NULL pointer is incorrectly used.
HY010	Function sequence error.
HY013	Memory management error.
HY090	Invalid character string or buffer length.
HY097	The column is out of range.
HY098	The type is out of scope.
HY099	Nullable type out of range.
HYC00	Optional feature is not implemented.
HYT00	Limit time exceeded.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLSpecialColumns` function.

3.1.73. SQLStatistics

Supported by Xopen CLI/ODBC 1.0. This function returns index statistics of a certain table. The information is returned as a result set.

Details of the SQLStatistics function are as follows.

Syntax

SQLRETURN SQLStatistics (SQLHSTMT      StatementHandle,
                         SQLCHAR       *CatalogName,
                         SQLSMALLINT   NameLength1,
                         SQLCHAR       *SchemaName,
                         SQLSMALLINT   NameLength2,
                         SQLCHAR       *TableName,
                         SQLSMALLINT   NameLength3,
                         SQLUSMALLINT  Unique,
                         SQLUSMALLINT  Reserved);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle.
CatalogName	Input	Catalog name.
NameLength1	Input	Catalog name length.
SchemaName	Input	Schema name.
NameLength2	Input	Schema name length.
TableName	Input	Table name.
NameLength3	Input	Table name length.
Unique	Input	Index types.
Reserved	Input	If set to SQL_EMSURE, brings the statistics information from database, unconditionally. Cannot be used under any other condition.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to an input parameter is invalid.
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
1000	General warning.
08S01	Failed to connect server for communication.
24000	Invalid cursor state.
40001	Serialization failure.
40003	The execution has not finished and the transaction state is unknown.
HY000	General error.
HY001	Memory allocation error.
HY008	Operation is canceled.
HY009	NULL pointer is incorrectly used.
HY010	Function sequence error.
HY013	Memory management error.
HY090	Invalid character string or buffer length.
HY100	Uniqueness option type out of range..
HY101	Accuracy option type out of range.
HYC00	Optional feature is not implemented.
HYT00	Limit time exceeded.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLStatistics` function.

3.1.74. SQLTablePrivileges

Supported by ISO 92 CLI/ODBC 1.0. This function returns information about related tables or an authority list for each table. The information is returned as a result set.

Details of the SQLTablePrivileges function are as follows.

Syntax

SQLRETURN SQLTablePrivileges (SQLHSTMT      StatementHandle,
                              SQLCHAR       *CatalogName,
                              SQLSMALLINT   NameLength1,
                              SQLCHAR       *SchemaName,
                              SQLSMALLINT   NameLength2,
                              SQLCHAR       *TableName,
                              SQLSMALLINT   NameLength3);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle.
CatalogName	Input	Catalog name.
NameLength1	Input	Catalog name length.
SchemaName	Input	Schema name.
NameLength2	Input	Schema name length.
TableName	Input	Table name.
NameLength3	Input	Table name length.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to an input parameter is invalid.
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
08S01	Failed to connect server for communication.
24000	Invalid cursor state.
40001	Serialization failure.
40003	The execution has not finished and the transaction state is unknown.
HY000	General error.
HY001	Memory allocation error.
HY008	Operation is canceled.
HY009	NULL pointer is incorrectly used.
HY010	Function sequence error.
HY013	Memory management error.
HY090	Invalid character string or buffer length.
HYC00	Optional feature is not implemented.
HYT00	Limit time exceeded.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLTablePrivileges` function.

3.1.75. SQLTables

Supported by Xopen CLI/ISO 92 CLI/ODBC 1.0. This function returns information about the list of table names, stored in the data dictionary, of a connected certain datasource. The information is returned as a result set and used like a result set generated from a SELECT statement.

Details of the SQLTables function are as follows.

Syntax

SQLRETURN SQLTables (SQLHSTMT      StatementHandle,
                     SQLCHAR       *CatalogName,
                     SQLSMALLINT   NameLength1,
                     SQLCHAR       *SchemaName,
                     SQLSMALLINT   NameLength2,
                     SQLCHAR       *TableName,
                     SQLSMALLINT   NameLength3,
                     SQLCHAR       *TableType,
                     SQLSMALLINT   NameLength4);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle.
CatalogName	Input	Catalog name.
NameLength1	Input	Catalog name length.
SchemaName	Input	Schema name.
NameLength2	Input	Schema name length.
TableName	Input	Table name.
NameLength3	Input	Table name length.
TableType	Input	Table's data type.
NameLength4	Input	Table's data type length.

Return Code

Return Code	Description
SQL_SUCCESS	Function is finished successfully.
SQL_SUCCESS_WITH_INFO	Function is successfully finished but there is a warning message.
SQL_INVALID_HANDLE	Invalid handle given to input parameter.
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
08S01	Failed to connect server for communication.
24000	Invalid cursor state.
40001	Serialization failure.
40003	The execution is not finished and the transaction state is unknown.
HY000	General error.
HY001	Memory allocation error.
HY008	Operation is canceled.
HY009	NULL pointer is incorrectly used.
HY010	Function sequence error.
HY013	Memory management error.
HY090	Invalid character string or buffer length.
HYC00	Optional feature is not implemented.
HYT00	Timeout exceeded.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLTables` function.

3.1.76. SQLTransact (Deprecated)

This function commits or rolls back all the changes made in the database. If a transaction is used, the application program should call the function before the database is disconnected.

If the function is called, the open cursor is closed and the unprocessed result set is deleted.

Related Function

SQLTransact is replaced by SQLEndTran in ODBC 3.x.

3.2. Tibero API

3.2.1. SQLAllocEnv2 (Deprecated)

Like the SQLAllocEnv function, this function allocates and initializes the memory related to the environment handle. The function can configure whether an application program, which uses tbCLI, uses multi threads.

Multi threads configuration differs depending on the operating system.

OS	Description
UNIX line	UNIX line is set not to use multi threads by default. In order to use multi threads, you must set the last parameter UseMultiThread to 'TRUE'.
Windows line	Multi threads can be used regardless of the UseMultiThread value, therefore it is recommended the `SQLAllocEnv2` function or the `SQLAllocHandle2` functions are not used.

This function should be used when allocating an environment handle firstly to configure whether to allow the use of multi threads.

Related Function

SQLAllocEnv2 is replaced by SQLAllocHandle2.

3.2.2. SQLAllocHandle2

This function allocates environment, connection, and statement handles, and configures whether to allow a program using tbCLI to use multi threads.

The methods of configuring multi threads, by operating systems, are the same with that of the SQLAllocHandle function.

Details of the SQLAllocHandle2 function are as follows.

Syntax

SQLRETURN SQLAllocHandle (SQLSMALLINT    HandleType,
                          SQLHANDLE      InputHandle,
                          SQLHANDLE      *OutputHandle,
                          SQLSMALLINT    UseMultiThread);

Parameter

Parameter	Purpose	Description
HandleType	Input	Handle type to be allocated. Has one value among the types below. SQL_HANDLE_ENV SQL_HANDLE_DBC SQL_HANDLE_STMT
InputHandle	Input	Input handle. Has a different value depending on the Handle type. SQL_HANDLE_ENV: SQL_NULL_HANDLE SQL_HANDLE_DBC: Environment handle SQL_HANDLE_STMT: Connection handle
OutputHandle	Output	Pointer of the handle to be allocated. When allocating a different handle instead of the environment handle, if SQL_ERROR is returned, this option allocates an OutputHandle parameter as SQL_NULL_HDBC or SQL_NULL_HSTMT.
UseMultiThread	Input	Decides whether to use multi threads. When tbCLI is used in a multi-threads environment, set this value to SQL_TRUE.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to an input parameter is invalid.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
08003	Database connection does not exist.
HY000	General error.
HY001	Memory allocation error.
HY009	NULL pointer is incorrectly used.
HY010	Function sequence error.
HY013	Memory management error.
HY014	The number of handles exceeds the limited range.
HY092	Invalid property and option identifier.
HYC00	Optional feature is not implemented.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLAllocHandle2` handle.

Related Functions

SQLAllocHandle2 replaces SQLAllocConnect, SQLAllocEnv2, and SQLAllocstmt.

3.2.3. SQLGetWarningMsg

This function searches the warning message that was issued for a SQL statement.

Details of the SQLGetWarningMsg function are as follows.

Syntax

SQLRETURN SQLGetWarningMsg (SQLHSTMT      StatementHandle,
                            SQLCHAR       *OutputString,
                            SQLINTEGER    *BufLength);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle
OutputString	Output	Buffer to contain the warning message to be returned.
BufLength	Input	Length of the buffer to contain the warning message to be returned.

Return Code

Return Code Description
SQL_SUCCESS Function finished successfully.
SQL_ERROR Critical error occurred.

3.2.4. SQLGetWarningMsgLength

This function searches the length of the warning message that was issued for a specific SQL statement.

Details of the SQLGetWarningMsgLength function are as follows.

Syntax

SQLRETURN SQLGetWarningMsgLength (SQLHSTMT      StatementHandle,
                                  SQLINTEGER    *Length);

Parameter

Parameter Purpose Description
StatementHandle Input Statement handle
Length Output Length of the message to be returned.
Return Code

Return Code드 Description
SQL_SUCCESS Function finished successfully.
SQL_ERROR Critical error occurred.

3.2.5. SQLLobClose

This function closes the operation target LOB. If the target LOB is not closed before the transaction is completed, an error occurs. An error also occurs when trying to close an unopened LOB.

If an LOB related function is called without calling open and close, every function internally executes open or close.

Details of the SQLLobClose function are as follows.

Syntax

SQLRETURN SQLLobClose (SQLHSTMT      StatementHandle,
                       SQLINTEGER    Locator,
                       SQLINTEGER    *Indicator);

Parameter

Parameter Purpose Description
StatementHandle Input Statement handle.
Locator Input LOB locator.
Indicator Input NULL indicator pointer.
Return Code

Return Code Description
SQL_SUCCESS Function finished successfully.
SQL_INVALID_HANDLE The handle given to an input parameter is invalid.
SQL_ERROR Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
HY000	General error.
HY001	Memory allocation error.
HY010	Function sequence error.
HY013	Memory management error.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLLobClose` function.

3.2.6. SQLLobFreeLoc

This function frees the resources used by the operation target LOB locator.

Details of the SQLLobFreeLoc function are as follows.

Syntax

SQLRETURN SQLLobFreeLoc (SQLHSTMT      StatementHandle,
                         SQLINTEGER    Locator);

Parameter

Parameter Purpose Description
StatementHandle Input Statement handle.
Locator Output LOB locator
Return Code

Return Code Description
SQL_SUCCESS Function finished successfully.
SQL_ERROR Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
HY000	General error.
HY001	Memory allocation error.
HY010	Function sequence error.
HY013	Memory management error.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLLobFreeLoc` function.

3.2.7. SQLLobGetData (Deprecated)

Retrieves LOB object data from a specified place. The retrieved data varies depending on BLOB and CLOB.

Details of the SQLLobGetData function are as follows.

Syntax

SQLRETURN SQLLobGetData (SQLHSTMT       StatementHandle,
                         SQLINTEGER     SourceLocator,
                         SQLBIGINT      Offset,
                         SQLINTEGER     *ByteLength,
                         SQLINTEGER     *CharLength,
                         SQLSMALLINT    TargetCType,
                         SQLPOINTER     Data,
                         SQLINTEGER     BufferLength,
                         SQLINTEGER     *Indicator);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle.
SourceLocator	Input	LOB locator.
Offset	Input	Starting offset of the LOB data to be retrieved. CLOB, NCLOB: The starting character position. BLOB: The starting byte position.
ByteLength	Input/Output	BLOB type data length to be requested or returned.
CharLength	Input/Output	CLOB type data length to be requested or returned.
TargetCType	Input	C type of the data to be returned
Data	Input	Data pointer to be returned.
BufferLength	Input	Data buffer length to be returned.
Indicator	Output	Number of bytes written to data.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_NO_DATA	Function has completed, but related data cannot be found. (Ex: No row is updated by the given SQL statement.)
SQL_INVALID_HANDLE	The handle given to an input parameter is invalid.
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
01004	Character string is truncated from the right.
01S07	Part of information of numeric type or date type is truncated.
07006	Violation of limited data type property.
07009	Invalid descriptor index.
08S01	Failed to connect server for communication.
22002	Indicator variable is required but not offered.
22003	The numeric value is out of range.
22007	Invalid DATETIME type format.
22012	Divided by 0.
22015	Overflow occurred to the INTERVAL field.
22018	Invalid character value for cast configuration.
24000	Invalid cursor state.
HY000	General error.
HY001	Memory allocation error.
HY003	Invalid application buffer type.
HY008	Operation is canceled.
HY009	NULL pointer is incorrectly used.
HY010	Function sequence error.
HY013	Memory management error.
HY090	Invalid character string or buffer length.
HY109	Invalid cursor position.
HYC00	Optional feature is not implemented.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLLobGetData` function.

Related Function

SQLLobGetData is replaced by SQLLobGetData2.

3.2.8. SQLLobGetData2

Retrieves LOB object data from a specified location. The retrieved data varies depending on BLOB and CLOB.

The following describes the SQLLobGetData2 function details.

Syntax

SQLRETURN SQLLobGetData2 (SQLHSTMT       StatementHandle,
                          SQLINTEGER     Locator,
                          SQLBIGINT      Offset,
                          SQLINTEGER     *ReadLength,
                          SQLSMALLINT    TargetCType,
                          SQLPOINTER     DataPtr,
                          SQLINTEGER     BufferLength,
                          SQLINTEGER     *Indicator);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle.
Locator	Input	LOB locator
Offset	Input	Starting offset of the LOB data to be retrieved. CLOB, NCLOB: The starting character position. BLOB: The starting byte position.
ReadLength	Input/Output	Input CLOB, NCLOB: The starting character position. BLOB: Length of the data to be retrieved (in bytes). Output CLOB, NCLOB: Length of the data retrieved. BLOB: Length of the data retrieved (in bytes). If set to 0, 'BufferLength' number of bytes are filled.
TargetCType	Input	C type of the data to be returned
DataPtr	Input	Data pointer to be returned.
BufferLength	Input	Data buffer length to be returned.
Indicator	Output	Number of bytes written to data.

Return Code

Return Code	Description
SQL_SUCCESS	Function completed successfully.
SQL_SUCCESS_WITH_INFO	Function completed successfully, but a warning message exists.
SQL_NO_DATA	Function completed, but related data cannot be found. (Ex: No row is updated by the given SQL statement.)
SQL_INVALID_HANDLE	Handle given to an input parameter is invalid.
SQL_STILL_EXECUTING	Previously executed SQL statement is still executing.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
01004	Character string is truncated from the right.
01S07	Part of information of numeric type or date type is truncated.
07006	Violation of limited data type property.
07009	Invalid descriptor index.
08S01	Failed to connect server for communication.
22002	Indicator variable is required but not offered.
22003	The numeric value is out of range.
22007	Invalid DATETIME type format.
22012	Divided by 0.
22015	Overflow occurred to the INTERVAL field.
22018	Invalid character value for cast configuration.
24000	Invalid cursor state.
HY000	General error.
HY001	Memory allocation error.
HY003	Invalid application buffer type.
HY008	Operation is canceled.
HY009	NULL pointer is incorrectly used.
HY010	Function sequence error.
HY013	Memory management error.
HY090	Invalid character string or buffer length.
HY109	Invalid cursor position.
HYC00	Optional feature is not implemented.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLLobGetData` function.

3.2.9. SQLLobGetLength

This function searches the length of specified LOB data. The function can be used for both BLOB and CLOB type data.

Details of the SQLLobGetLength function are as follows.

Syntax

SQLRETURN SQLLobGetLength (SQLHSTMT       StatementHandle,
                           SQLINTEGER     Locator,
                           SQLBIGINT      *StringLength,
                           SQLINTEGER     *Indicator);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle.
Locator	Input	LOB locator
StringLength	Output	Length of LOB data to be returned. CLOB/NCLOB: Character length BLOB: Byte length
Indicator	Input	NULL indicator pointer.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to an input parameter is invalid.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
07006	Violation of a limited data type property.
08S01	Failed to connect server for communication.
HY000	General error.
HY001	Memory allocation error.
HY008	Operation is canceled.
HY009	NULL pointer is incorrectly used.
HY010	Function sequence error.
HY013	Memory management error.
HY019	Data that is neither character nor binary was sent by being divided.
HY020	Tried to connect NULL value.
HY090	Invalid character string or buffer length.
HYC00	Optional feature is not implemented.
0F001	No value on a LOB token.

3.2.10. SQLLobOpen

This function opens the operation target LOB data. The function must always be declared first, whenever a LOB operation is executed. If each LOB related function is called without calling Open and Close, every function internally executes open and close. If the same LOB instance is opened twice within a transaction, an error occurs. An error also occurs when attempting to reopen the same LOB instance by using a different locator.

Details of the SQLLobOpen function are as follows.

Syntax

SQLRETURN SQLLobOpen (SQLHSTMT       StatementHandle,
                      SQLINTEGER     Locator,
                      SQLSMALLINT    Mode,
                      SQLINTEGER     *Indicator);

Parameter

Parameter Purpose Description
StatementHandle Input Statement handle.
SourceLocator Input LOB locator.
Mode Input Position value of the data to be returned.
Indicator Input NULL indicator pointer.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to an input parameter is invalid.
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
24000	Invalid cursor state.
HY000	General error.
HY001	Memory allocation error.
HY010	Function sequence error.
HY013	Memory management error.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLLobOpen` function.

3.2.11. SQLLobPutData

This function writes data to a specified position within a LOB.

Details of the SQLLobPutData function are as follows.

Syntax

SQLRETURN SQLLobPutData (SQLHSTMT       StatementHandle,
                         SQLINTEGER     *DestLocator,
                         SQLBIGINT      DestOffset,
                         SQLSMALLINT    SourceCType,
                         SQLPOINTER     Source,
                         SQLINTEGER     *ByteLength,
                         SQLINTEGER     *CharLength,
                         SQLINTEGER     *Indicator);

Parameter

Parameter	Purpose	Description
StatementHandle	Input	Statement handle.
DestLocator	Input	LOB locator.
DestOffset	Input	Position to write in LOB data.
SourceCType	Input	C type of the data to write.
Source	Input	Pointer of the data to write.
ByteLength	Output	Length of the written BLOB type data.
CharLength	Output	Length of the written CLOB type data.
Indicator	Input	NULL indicator pointer.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to an input parameter is invalid.
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
24000	Invalid cursor state.
HY000	General error.
HY001	Memory allocation error.
HY010	Function sequence error.
HY013	Memory management error.
HYT01	Database connection time limit exceeded.
IM001	Driver does not support the `SQLLobPutData` function.

3.2.12. SQLLobTruncate

This function truncates LOB data.

Details of the SQLLobTruncate function are as follows.

Syntax

SQLRETURN SQLLobTruncate (SQLHSTMT      StatementHandle,
                          SQLINTEGER    *Locator,
                          SQLBIGINT     NewLength,
                          SQLINTEGER    *Indicator);

Parameter

Parameter Purpose Description
StatementHandle Input Statement handle.
Locator Input LOB locator.
NewLength Input New LOB data length after being truncated.
Indicator Input NULL indicator pointer.

Return Code

Return Code	Description
SQL_SUCCESS	Function finished successfully.
SQL_SUCCESS_WITH_INFO	Function finished successfully, but there is a warning message.
SQL_INVALID_HANDLE	The handle given to an input parameter is invalid.
SQL_STILL_EXECUTING	Previously executed SQL statement has not finished.
SQL_ERROR	Critical error occurred.

SQLSTATE

SQLSTATE	Description
01000	General warning.
01004	Character string is truncated from the right.
07006	Violation of limited data type property.
07S01	Default parameter is incorrectly used.
08S01	Failed to connect to server for communication.
HY000	General error.
HY001	Memory allocation error.
HY008	Operation is canceled.
HY009	NULL pointer is incorrectly used.
HY010	Function sequence error.
HY013	Memory management error.
HY019	Data that is neither character nor binary was sent by being divided.
HY090	Invalid character string or buffer length.
HYT01	Database connection time limit exceeded.

Parameter	Purpose	Description
Context	Input	Context
ErrorCode	Input	Error code
ErrorMessage	Input	Error Message

Return Code	Description
SQL_SUCCESS	Function has finished successfully
SQL_INVALID_HANDLE	The handle given to input parameter is invalid
SQL_ERROR	Critical error has occurred

Prev		Next
Chapter 2. Data Types	Home	Chapter 4. tbCLI Error Messages