advertisement
ALTIBASE Application Development
ODBC Users’ Manual
release 5.3.3
ALTIBASE Application Development ODBC User’s Manual
Release 5.3.3
Copyright ? 2001~2009 Altibase Corporation. All rights reserved.
This manual contains proprietary information of Altibase Corporation; it is provided under a license agreement containing restrictions on use and disclosure and is also protected by copyright patent and other intellectual property law. Reverse engineering of the software is prohibited.
Altibase Corporation
10F, Daerung PostTower II, 182-13,
Guro-dong Guro-gu Seoul, 152-847, Korea
Telephone: +82-2-2082-1000 Fax: 82-2-2082-1099
E-mail: [email protected] www: http://www.altibase.com
Sample of Using Metadata...............................................................................................................................................................210
Example of Procedure test Program.............................................................................................................................................217
SQLColumns, SQLGetTypeInfo, SQLPrimaryKeys, SQLProcedureColumns, SQLProcedures, SQLStatistics,
SQLCHAR, SQLSCHAR .........................................................................................................................................................243
SQL_BIT, SQL_VARBIT .........................................................................................................................................................243
SQL_NIBBLE ............................................................................................................................................................................247
Limitation on ALTER SESSION statements ..................................................................................................................257
Preface
i Preface
About This Manual
About This Manual
This manual describes how to use the ODBC.
Target Users
•
•
•
•
•
•
This manual has been prepared for the following Altibase users.
Database Manager
Performance Manager
Database User
•
• Application Program Developer
Technical Assistance Team
•
Before reading this manual, understanding of following background knowledge is recommended.
Basic knowledge required for computers, operation systems, and operating system utilities
Experience in using the relational database or understanding of the database concept
Computer programming experience
Experience in managing the database server, the operation system, or the network
Software Environment
This manual has been prepared assuming Altibase 5.3.1 will be used as the database server.
Organization
•
This manual has been organized as follows:
Chapter 1. ODBC Introduction
•
This chapter shows you how to use ODBC, ODBC programming procedure, ODBC functions.
Chapter 2. ODBC Functions
•
This chapter shows you the specifications of ODBC functions.
Chapter 3. LOB Interface
•
This chapter shows functions and data types that can be used for handling LOB data.
Appendix A. Sample Codes
•
This appendix shows the entire sample codes used this documents.
Appendix B. Data Types
ODBC Users’ Manual ii
About This Manual
•
This appendix explains the Altibase SQL data types, C data types, and conversion between data types.
Appendix C. ODBC Error codes
This appendix explains the Altibase ODBC Drive Error reference as defined in X/Open and SQL
Access Group SQL CAE specification.
• Appendix D. ODBC Conformance Levels
This appendix describes the conformance level of Altibase ODBC Driver.
Convention
•
This chapter describes the rules of this manual. With understanding of this rule, it is easy to retrieve information in this manual and other manuals.
•
Rules are as follows:
Syntax diagram
Sample code rule
Syntax Diagram
This manual describes the command syntax by using the diagram composed of the following elements:
Elements semantics
The command starts. The syntax element which is not a complete command starts with an arrow.
Reserved word
The command continues to the next line. The syntax element which is not a complete command terminates with this symbol.
The command continues from the previous line. The syntax element which is a complete command starts with this symbol.
The command terminates.
;
Mandatory
SELECT iii Preface
About This Manual
Elements semantics
Optional
NOT
Mandatory field with optional items Only one field must be provided.
ADD
DROP
Optional field with optional item
ASC
DESC
Optional Multiple fields are allowed. The comma must be in front of every repetition.
ASC
DESC
,
Sample Code Rule
The code example explains SQL, stored procedure, iSQL, or other command line syntax.
The following table describes the printing rules used in the code example.
[ ]
{ }
Rules semantics
Display the optional fields.
Display the mandatory fields. Indicates to make sure to select at least one.
Example
VARCHAR [(size)] [[FIXED |]
VARIABLE]
{ ENABLE | DISABLE | COMPILE }
ODBC Users’ Manual iv
About This Manual
|
...
Rules
Other symbols.
Itelicized words
Lower case words
Upper case words semantics Example
Argument indicating optional or mandatory fields
Repetition of the previous argument-
Omit the example codes.
Symbols other than the above.
Indicates variable or value that must be provided by user.
Program elements provided by the user such as table names, column names, file names, etc.
Elements provided by the system or keyword appeared in the syntax
]
{ ENABLE | DISABLE | COMPILE
}[ ENABLE | DISABLE | COMPILE
SQL> SELECT ename FROM employee;
ENAME
------------------------
SWNO
HJNO
HSCHOI
...
20 rows selected.
EXEC :p1 := 1; acc NUMBER(11,2);
SELECT * FROM TABLE_name;
CONNECT userID/password;
SELECT ename FROM employee;
DESC SYSTEM_.SYS_INDICES_;
Related Resource
•
•
•
•
•
•
•
•
•
For more detailed information, see the following document list.
Altibase Installation Manual
Altibase Administrator’s Manual
Altibase Replication User’s Manual
Altibase Precompiler User’s Manual
Altibase ODBC User’s Manual
Altibase Application Program Interface User’s Manual
Altibase iSQL User’s Manual
Altibase Utilities User’s Manual
Altibase Error Message Reference
Online Manual
Korean and English versions of on-line manuals (PDF or HTML) are available from Altibase Download v Preface
About This Manual
Center ( http://atc.altibase.com/ ).
Altibase Welcomes Your Opinions!
•
•
•
Please send us your comments and suggestions regarding this manual. Your comments and suggestions are important, and they may be used to improve future versions of the manual. When you send your feedback, please make sure to include the following information:
The name and version of the manual in use
Your comments or suggestions regarding the manual
Your name, address, and phone number
Please send your e-mail to the following address: [email protected]
This address is intended to report any errors or omissions discovered in the manual. When you need an immediate assistance regarding technical issues, please contact Altibase Customer Support Center.
We always appreciate your comments and suggestions.
ODBC Users’ Manual vi
1
ODBC Introduction
The ODBC is a callable SQL programming interface. The callable SQL interface is used to access the database and execute a dynamic SQL statement through calling the function.
1 ODBC Introduction
Open Database Connectivity
Open Database Connectivity
The ODBC is a standard open application program interface to access the database. It makes possible for applications to access data from a variety of database management systems (DBMSs). It provides calling level interfaces to access database servers and to execute SQL statements. That application will be independent of DBMS. This Guide is for the Altibase ODBC Driver’s users.
Backgrounds of the ODBC
The ODBC was first created by SQL Access Group (SAG) and introduced in September 1992. Now various versions for UNIX, OS/2, Microsoft Windows and Macintosh are available also.
The ODBC is based on the callable standard SQL interface(CLIs). The ODBC enables the programs to use the SQL request to access the database although those programs do not know the independent interface of the database. The ODBC receives the SQL request and converts each request in a format comprehensible for the database system.
ODBC versus Embedded C/C++ Programming
The ODBC interface is designed for use C/C++ Languages. Then what’s the difference between programs using ODBA and C/C++ precompiler.An application that uses C/C++ Precompiler interface requires a precompiler to convert an SQL statement into a code. The ODBC application uses the standard function that executes an SQL statement while it does not need pre-compiling.
The advantage is that it can use other database products that provide the standard functions. In other words, the ODBC supports independent development of an application for each database product.
Groups of ODBC Functions
•
•
•
•
The API of the ODBC consists of functions that define environment for running applications, managing connections, and processing SQL statements and transactions. Depending on the features of each function, these are groupped by followings:
Managing Environments and Connections
SQL Processing
Setting and Retrieving Driver Attributes
Meta data processing
Managing Environments and Connections
The APIs that allocate resources necessary for the connection to the database server and provide connection-related features. Releases the memory space after disconnected from datasources.
ODBC Users’ Manual 2
Open Database Connectivity
SQL Processing
The APIs that allocate resources and prepare commands for the processing, executing and retreiving results of SQL statements.
Setting and Retrieving Driver Attributes
The APIs that set the environment for the processing of the SQL, connection status, and statement attributes.
Metadata Processing
The APIs that provide features to define tables and columns and to retrieve database metadata.
3 ODBC Introduction
Using the ODBC
Using the ODBC
This chapter explains how to develop user application programs using the Altibase ODBC driver
Basic Usages
•
•
•
The ODBC application program generally consists of following three parts:
Initializing Handles
Transaction Processing
Release Handles
Besides the above, The diagnosis messages is made through the all parts of an application.
Initializing Handles
This is a part to allocate and initialize the environment and connection handles.
Transition from one phase to the next phase is made through transmission of proper handles to send information about the execution results from the previous phase. Handle types provided by
ODBC Users’ Manual 4
Using the ODBC the ODBC are as follows:
Environment Handles
Tthe environment handles obtain general environment about an application environment. The environment handles must be allocated before the connection handle. In one application, multiple environment handles can be allocated.
Connection Handles
The connection handles obtain connection-related information that the ODBC manages. They Includesconnection and transaction status, and diagnosis information. An application allocates the connection handle for each connection and attempts to connect to a database server.
Statement handles
The statement handles obtain the information of SQL statements. The statement handleare related to the connection handles. They allocate the statement handle to execute SQL statements. Maximum 1024 statements can be allocated to one connection.
Processing of Transactions
The following figure is a general procedure of calling functions to processing a transaction.
5 ODBC Introduction
Using the ODBC
Release Handle
This step is for releasing the handles and meory allocated by an application, and finishing an application.
Managing Diagnosis Messages
Diagnosis is to handle the warning or error status occurred in an application. There are 2 Levels of disgnosis messages in the ODBC.
Application Return Values
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_NO_DATA_FOUND
SQL_ERROR
SQL_INVALID_HANDLE
Description
Successful completion of the function
Successful execution with warning and other information
The function is successful, but there is no related data.
Failure of the function
The function failed due to invalid input handles.
The diagnosis messages are returned except the case of SQL_SUCCESS, SQL_NO_DATA_FOUND,
SQL_INVALID_HANDLE. To check the diagnosis message, call SQLGetDiagRec(), SQLGetDiagField()
Diagnosis Messages
The diagnosis message is a five-bytes alphanumeric character string. The heading two characters refer to the class, and the next three character refer to the sub class.
The Altibase ODBC diagnosis messages follow the standard of X/Open SQL CAE specifications.
Restriction
ALTIBASE client library doesn't use signal processor.
Therefore, if access to network terminates due to external factors, application can be shut down compulsorily by receiving signal of SIGPIPE.
You may process it in user application to avoid forced shutdown.
And you can't call functions of ALTIBASE client library to process it because program can be stopped.
However, you can after processing it.
ODBC Users’ Manual 6
Using ODBC
Using ODBC
This chapter describes how to use ODBC in Unix and Windows.
Using UNIX ODBC versus Using Windows ODBC
All APIs are used in the same way but different strings(supported by SQLDriverConnect) are used to connect to a database server depending on kinds of API.
Unix
DSN=host_ip;PORT_NO=20300;UID=SYS;PWD=MANAGER;CONN-
TYPE=1;NLS_USE=US7ASCII
The name of shared library is libodbcinst.so (the extension of HP is sl.) by default in Unix-ODBC or iODBC where Altibase ODBC library is installed. However, if wanting to set its name manually, you can specify it with UNIX_ODBC_INST_LIB_NAME.
ex) You should change setting of environment variable in iODBC.
Unix-ODBC
Extra setting is not a requisite for running Unix ODBC Manager.
iODBC
You should specify the following setting of evironment variable to make an iODBC manager provide an ODBC driver for ALTIBASE.
export UNIX_ODBC_INST_LIB_NAME=libiodbcinst.so
You can specify the following setting of evironment variable under the necessity.
export LD_PRELOAD=/lib/libdemangle.so
•
•
•
•
•
•
•
In addition, if iODBC manager fails to provide an ODBC driver for AIX, you should specify additional setting after checking the following
You should extract iodbcinst.so. from iodbcinst.a after searching for a path where iODBC library is installed.
$> ar -x libiodbcinst.a
You should change so.2 into so as file extension.
$> mv libiodbcinst.so.2 libiodbcinst.so
iODBC shared library search path should be specified by setting the value of the environment variable LIBPATH.
ex) Shared library path is /usr/local/lib : export LIBPATH=/usr/local/lib:$LIBPATH
7 ODBC Introduction
Using ODBC
Windows
After installing ODBC Driver, you should specify data source name registered in Setting -> Administrative Tools -> Data Source as DSN=datasource_name.
ODBC Users’ Manual 8
Basic Programming Steps
Basic Programming Steps
9 ODBC Introduction
Basic Programming Steps
Step 1: Connecting to a Database
The first step is to connect to the database. The following functions are necessary for this step:
STEP 1: CONNECT
SQLAllocHandle()
SQLSetEnvAttr()
SQLAllocHandle()
SQLDriverConnect()
SQLSetConnectAttr()
The first operation to access a database is to allocate the environment handle using SQLAllocHandle
().
An application sets the environmental attribute by calling SQLSetEnvAttr () .
Then, an application allocates the connection handle by using SQLAllocHandle () and calls SQLDriverConnect () to connect to a database.
After connecting successfully, an application can set the connection attributes by using SQLSetConnectAttr ().
Step 2: Initializing an application Status
The second phase is usually to initialize an application as described in the figure below. However each application can have different operations.
STEP 2: INITIALIZE
SQLAllocStmt()
SQLSetStmtAttr()
An application allocates the statement handle by using SQLAllocStmt (). Most applications sets the status of application attributes by using SQLSetStmtAttr ().
Step 3: Executing an SQL statements
The third phase is to build and execute the SQLSTATEments as shown below. The processing types in the phase can be different. An application creates or executes an SQL statement based on an SQL statement requested by users.
STEP 3: EXECUTE
Catalog function or
SQLBindParameter()
...
SQLExecDirect()
The SQLExecDirect() function called to execute an SQL statement. In case to execute multiple times for the performance, preparation and execution will be made by SQLPrepare () and SQLExecute respectively.
If an SQL statement includes the arguments, an application will call SQLBindParameter () and bind each argument with an application variable. Before the argument is bound, SQLPrepare () must be executed. After binding is made, SQLExecute () can be executed.
An application can delay execution of an SQL statement and may call the function that returns the
ODBC Users’ Manual 10
Basic Programming Steps database metadata instead.We called those functions as catalog functions
The action of an application depends on the execution type of an SQL statements.
SQL Statement Types
SELECT or catalog function
UPDATE, DELETE, or INSERT
Other SQL Statements
Actions
Phase 4a : Get the results.
Phase 4b : Get the number of affected rows.
Phase 3 : Build and execute an SQL statement. or
Phase 5 Commit the transaction.
Step 4a: Fetch the Results
This phase is the step to fetch the results.
STEP 4a: FETCH RESULTS
SQLNumResultCols()
SQLDescribeCol()
SQLBindCol()
SQLFetch()
SQLGetData()
If a statements executed in the Step 3 is SELECT or catalog function, an application calls SQLNumResultCols () to find the number of the columns in the result set. This step is not needed if an application already knows the number of columns in the result set.
Then, an application brings the name of the result set, the data type, and the precision to SQLDescribeCol (). In the same way, if an application already knows this information, this step will not be necessary. Then, an application sends this information to SQLBindCol () that binds an application variables and the columns of the result set.
Then, an application calls SQLFetch () to fetch the first row of data and stores the data in the variables bound to SQLBindCol (). In case there is only one recored in the row, use the SQLGetData () to get the data. To fetch multiple rows of data, an application keeps calling SQLFetch () and SQLGet-
Data ().
An application returns to Step 3 to execute other statements in the same transaction or goes to step
5 to commit or rollback the transaction.
Step 4b: Fetch the Affected Row Count
If a statements executed in Step 3 is UPDATE, INSERT, or DELETE, an application will bring the number of affected rows using SQLRowCount ().
An application goes back to Step 3 to execute other statements in the same transaction, or Step 5 to commit or rollback the transaction.
11 ODBC Introduction
Basic Programming Steps
Step 5: Commit/Rollback a Transaction
In Step 5, an application commits the transaction or calls SQLEndTran () for rollback. An application performs this phase only when the transaction commit mode is in non-auto-commit mode. If the transaction commit mode is auto-commit, the transaction will be automatically reflected immediately when an SQL statements are successfully executed.
To execute an SQL statement in the new transaction, an application shoult to return to Step 3. An application goes to Step 6 to disconnect from the database.
Step 6: Disconnect from the Altibase Database
STEP 6 : DISCONNECT
SQLFreeHandle()
SQLDisconnect()
SQLFreeConnect()
SQLFreeEnv()
In the final step, an application disconnects from the database. An application calls SQLFreeHandle () and release the handles and resources.
Then, an application disconnects from the database by using SQLDisconnect (), and returns the connection handle by using SQLFreeConnect ().
Lastly, an application returns the environment handle by using SQLFreeEnv () and ends the program.
ODBC Users’ Manual 12
Summary of ODBC Functions
Summary of ODBC Functions
Task
Managing environments and connections
Function Name
SQLAllocConnect
SQLAllocEnv
SQLAllocStmt
SQLAllocHandle
SQLCloseCursor
SQLConnect
SQLDisconnect
SQLDriverConnect
SQLEndTran
SQLFreeConnect
SQLFreeEnv
SQLFreeFailover
SQLFreeHandle
SQLFreeStmt
SQLTransact
Purpose
Obtains an environment, connection, statement, or descriptor handle.
Allocates an environment, connection, statement, or descriptor handle.
Obtains statement handles and Allocates memory.
Initializes of resources, environments, and statement handles and allocates memory
This closes cursor and discards pending resuts.
Connects to a target database
Closes the connection. Releases an environment, connection, statement, or descriptor handle.
Connects to a specific driver by connection string or requests that the Driver Manager and driver display connection dialog boxes for the user.
Commits or rolls back a transaction.
Closes the connection handle, and releases the memory.
Closes the environment handle, and releases the memory.
Frees the failover handle assigned to SQLAlloc-
Failover
Releases the memory allocated to the connection, the handle, and the command.
Closes the statement handle, and releases the allocated memory.
Commits or releases all changes related to the database.
13 ODBC Introduction
Summary of ODBC Functions cessing
Task
SQL ProReque sting
Function Name
SQLBindParameter
SQLExecDirect
SQLExecute
SQLNativeSql
SQLParamData
SQLPrepare
SQLPutData
Retriev ing
SQLBindCol
SQLColAttribute
SQLDescribeCol
SQLDescribeParam
SQLERROR
SQLFetch
SQLFetchScroll
SQLGetConnectAttr
SQLGetData
SQLGetStmtAttr
SQLGetTypeInfo
SQLNumParams
SQLNumResultCols
SQLRowCount
SQLMoreResults
ODBC Users’ Manual 14
Purpose
Binds the parameter to an SQL statement.
Directly executes an SQL statement.
Executes a prepared SQL statement
This efficiently tests the syntax of SQL statements and converts it to that ODBC driver supprots.
This is used to supply data at statement execution time.
Prepares an SQL statement for later execution
This is used to supply data at statement execution time.
Defines the buffer and the data type to receive the columns of the result set.
Defines the attributes about the columns of the result set.
Checks the metadata about one column in the result set.
Checks information related to the parameter marker (?) in the result set.
Checks diagnosis messages related to the recently called ODBC function.
Returns multiple result rows.
The result set the cursor to the desired direction of progress, and get a column to bind
Returns the properties setting of connection
Returns the data of a specified column in the result set
Returns the attributes related to the current statement handle
Returns the information about the data type supported by the database.
Returns the number of parameters in an SQL statement.
Returns the number of columns in the result set.
Returns the number of rows affected by an insert, update, or delete request.
Returns whether there is more result
Summary of ODBC Functions
Task
Setting and retrieving driver attributes
Function Name
SQLGetEnvAttr
SQLGetFunctions
SQLSetConnectAttr
SQLSetEnvAttr
SQLSetStmtAttr
SQLColumns Metadata Processing(catalog functions)
SQLForeignKeys
SQLGetDescField
SQLGetDescRec
SQLGetDiagField
SQLGetDiagRec
SQLPrimaryKeys
SQLProcedureColumns
SQLProcedures
SQLSetDescField
SQLSpecialColumns
SQLStatistics
SQLTablePrivileges
SQLTables
Purpose
This returns the current setting of an environment attribute.
This returns information about whether a driver supports a specific ODBC function.
Sets the connection attributes.
Sets the environment attributes
Sets the statement attributes.
Returns the list of column names in specified tables.
Returns a list of column names that make up foreign keys, if they exist for a specified table.
This returns a single field of a descriptor record.
This returns values of mutiple fields of a descriptor record.
Diagnose the result after the function is used
This returns several commonly used fields of a diagnostic record after using the function.
Returns the list of column names that make up the primary key for a table.
Returns the list of input and output parameters, as well as the columns that make up the result set for the specified procedures.
Returns the list of procedure names stored in a specific database.
This sets the descriptor field.
Returns information about the optimal set of columns that uniquely identifies a row in a specified table, or the columns that are automatically updated when any value in the row is updated by a transaction.
Returns statistics about a single table and the list of indexes associated with the table.
Returns a list of tables and the privileges associated with each table.
Returns the list of table names stored in a specific database.
15 ODBC Introduction
Summary of ODBC Functions
ODBC Users’ Manual 16
2
ODBC Functions
•
•
•
•
•
•
•
•
This chapter describes the specifications of ODBC functions.
For each ODBC functions, the following information are described.
Name of the function and purpose of use
Function prototype for C/C++ Users
Arguments list of the function
Return Values
Usages of function and notes
Diagnosis message that can be displayed when an error occurrs in function
Related Function list
Example source codes
17 ODBC Functions
SQLAllocConnect
SQLAllocConnect
SQLAllocConnect allocates an environment, connection, statement, or descriptor handle. This function allocates the related resources in the environment identified by the connection handles and the input environment handles.
SQLAllocConnect () can be replaced by SQLAllocHandle ().
Syntax
SQLRETURN SQLAllocConnect (
SQLHENV env,
SQLHDBC *dbc );
Arguments
Data Type
SQLHENV
SQLHDBC * env dbc
Argument In/Out
Input
Output
Description
Environment Handle
Connection Handle Pointer
Return Values
SQL_SUCCESS
SQL_INVALID_HANDLE
SQL_ERROR
Description
The ODBC uses the output connection handle to refer to all information related to the connection such as connection status, transaction status, and error information.
If the pointer (dbc) indicating the connection handle refers to the valid connection handle allocated by SQLAllocConnect (), the calling result will change the original value. If it is application programming error, it is not detected by ODBC.
* Call SQLAllocEnv() before calling this function.
ODBC Users’ Manual 18
SQLAllocConnect
Diagnosis
SQLSTATE
HY000
HY001
HY009
Description
General error
Memory allocation error
Invalid Arguments used
(null pointer).
Comments
Channel initialization error
Failed to allocate the memory for the explicit handle.
dbc is a NULL pointer.
Related Functions
SQLAllocEnv
SQLConnect
SQLDisconnect
SQLFreeConnect
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_ex1.cpp.
/* Memory allocation for the environment */ if (SQLAllocEnv(&env) != SQL_SUCCESS)
{
printf("SQLAllocEnv error!!\n");
return SQL_ERROR;
}
/* Memory allocation for the connection */ if (SQLAllocConnect(env, &dbc) != SQL_SUCCESS)
{
printf("SQLAllocConnect error!!\n");
return SQL_ERROR;
}
19 ODBC Functions
SQLAllocEnv
SQLAllocEnv
SQLAllocEnv allocates the resources related to the environment handles.
SQLAllocEnv () can be replaced by SQLAllocHandle ().
Syntax
SQLRETURN SQLAllocEnv (
SQLHENV *env );
Arguments
Data Type
SQLHENV * env
Argument In/Out
Output
Description
Environment handle pointer
Return Values
SQL_SUCCESS
SQL_ERROR
Description
One application can use various environment variables.
To use resources of the ODBC, the program that called SQLAllocEnv () must not terminate or get out of the stack. Otherwise, an application may lose the statement handles and other allocated resources.
Before calling SQLAllocConnect () or other ODBC functions, an application must call this function.
Then, the env value will be sent to all functions that require the environment handles as input values.
Related Functions
SQLAllocConnect
SQLAllocStmt
SQLFreeEnv
ODBC Users’ Manual 20
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_ex1.cpp.
/* Memory allocation for the environment */ if (SQLAllocEnv(&env) != SQL_SUCCESS)
{
printf("SQLAllocEnv error!!\n");
return SQL_ERROR;
}
SQLAllocEnv
21 ODBC Functions
SQLAllocHandle
SQLAllocHandle
SQLAllocHandle allocates and initializes the memory for the environment, connection, and statement handles.
Syntax
SQLRETURN SQLAllocHandle (
SQLSMALLINT HandleType,
SQLHANDLE InputHandle,
SQLHANDLE *OutputHandlePtr );
Arguments
Data Type
SQLSMALLINT
SQLHANDLE
SQLHANDLE *
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Arguments
HandleType
In/Out
Input
InputHandle
OutputHandlePtr
Input
Output
Description
One of the following handle type is allocated:
SQL_HANDLE_ENV,
SQL_HANDLE_DBC,
SQL_HANDLE_STMT
If the input HandleType is
SQL_HANDLE_ENV, InputHandle will be SQL_Null_Handle.
Or if the input HandleTyp is
SQL_HANDLE_DBC, it will be the environment handle. In case of SQL_HANDLE_STMT, it will be the connection handle.
The pointer of the allocated handle
ODBC Users’ Manual 22
SQLAllocHandle
Description
SQLAllocHandle () allocates the environment, connection and statement handles to be described in the next paragraph.
This function will replace SQLAllocEnv (), SQLAllocConnect () and SQLAllocStmt () functions. To request the environment handle, an application calls SQLAllocHandle () of which HandleTyp is
SQL_HANDLE_ENV and input handle is SQL_Null_Handle. To request the connection handle, an application must call SQLAllocHandle () of which HandleTyp is SQL_HANDLE_DBC and the input handle must be a valid environment handle. To request the statement handle, an application must call SQLAllocHandle () of which HandleTyp is SQL_HANDLE_STMT and the input handle must be a valid connection handle.
One application can allocate multiple environment, connection, and statement handles at one time.
However, several environment, connection or statement handle cannot be used at the same time on another thread of one process.
Allocation of the Environment Handles
The environment handle provides global information about the validity or activation of the connection handle.
To request an environment handle, an application must call SQLAllocHandle () of which HandleTyp is
SQL_HANDLE_ENV and input handle is SQL_Null_Handle. The ODBC allocates the memory needed for environment information and returns the handle related to the *OutputHandle. An application sends the *OutputHandle value to the subsequent callings that require the environment handles.
Allocation of the Connection Handles
The connection handle provides information about the validity of the statement handle or activation of the transaction.
To request the connection handle, an application calls SQLAllocHandle () of which HandleTyp is
SQL_HANDLE_DBC. InputHandle argument calls SQLAllocHandle () and is set as the returned environment handle. The ODBC allocates the memory necessary for the connection and returns the handle values related to the *OutputHandle. An application sends the *OutputHandle to the subsequent callings that require the connection handle.
Allocation of the Statement handles
The statement handle provides command information such as error messages about processing an
SQL statement and status state.
To request the statement handle, an application connects to the database and calls SQLAllocHandle
() before sending an SQL statement. For this calling, the HandleTyp must be set as
SQL_HANDLE_STM and the InputHandle argument must be set as a connection handle to be returned by calling SQLAllocHandle (). The ODBC allocates the memory necessary for the command, connects the statement handle, and returns the handle related to *OutputHandle. An application sends *OutputHandle value to the subsequent callings that require the statement handle.
23 ODBC Functions
SQLAllocHandle
Diagnosis
SQLSTATE
HY000
HY001
HY009
Description
General error
Memory allocation error
Invalid arguments used
(null pointer).
Comments
Failed to allocate the memory for the explicit handle.
OutputHandlePtr is a NULL pointer.
Related Functions
SQLExecDirect
SQLExecute
SQLFreeHandle
SQLPrepare
SQLSetConnectAttr
SQLSetEnvAttr
SQLSetStmtAttr
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_meta1.cpp
/* Memory allocation for the environment */ if (SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HENV, &env) != SQL_SUCCESS)
{
printf("SQLAllocEnv error!!\n");
return SQL_ERROR;
}
/* Memory allocation for the connection */ if (SQLAllocHandle(SQL_HANDLE_DBC, env, &dbc) != SQL_SUCCESS)
{
printf("SQLAllocConnect error!!\n");
return SQL_ERROR;
}
ODBC Users’ Manual 24
SQLAllocStmt
SQLAllocStmt
SQLAllocStmt allocates and initializes the memory for the SQL statements. Up to 1024statements are allocated to one connection.
SQLAllocStmt () can be replaced by SQLAllocHandle ().
Syntax
SQLRETURN SQLAllocStmt (
SQLHDBC dbc,
SQLHSTMT *stmt );
Arguments
Data Type
SQLHDBC
SQLHSTMT *
Arguments dbc stmt
In/Out
Input
Output
Description
Connection Handle
Pointer of statement handle
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
In case SQL_ERROR is returned, stmt arguments will be set as SQL_NULL_STMT. An application must set stmt arguments as SQL_NULL_STMT and calls SQLERROR ().
Description
The ODBC relates the descriptors, results and status data with the processed SQL statements by using each statement handle. Each SQL statement must have a statement handle, but other commands can use the handles again.
When this function is called, the database connection used by the databasec must be referred to.
If the input pointer indicates the valid statement handle allocated by the previous calling of SQLAllocStmt (), the original value will be changed according to the result of this calling.
As an application programming error, it is not detected by ODBC.
25 ODBC Functions
SQLAllocStmt
* Call SQLAllocEnv() before calling this function. This function must be called before other functions that have SQLPrepare (), SQLExecute (), SQLExecDirect () or statement handle as an input Arguments.
Diagnosis
SQLSTATE
HY000
HY001
HY009
HY010
Description Comments
General error
Memory allocation error
The number of stmt (1024) exceeds
Failed to allocate the memory for the stmt.
Invalid Arguments used (null pointer).
stmt is a NULL pointer.
Continuous function error (not connected or disconnected status) dbc is not connected or disconnected.
Related Functions
SQLConnect
SQLFreeStmt
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_ex1.cpp
/* Memory allocation for a statement */ if (SQL_ERROR == SQLAllocStmt(dbc, &stmt))
{
printf("SQLAllocStmt error!!\n");
return SQL_ERROR;
}
ODBC Users’ Manual 26
SQLBindCol
SQLBindCol
SQLBindCol binds an application variables to the columns of the result sets for all data types.
Syntax
SQLRETURN SQLBindCol (
SQLHSTMT stmt,
SQLSMALLINT col,
SQLSMALLINT cType,
SQLPOINTER value,
SQLINTEGER max,
SQLINTEGER *valueLength );
Arguments
Data Type
SQLHSTMT
SQLSMALLINT
SQLSMALLINT
SQLPOINTER
Argument stmt col
In/Out
Input
Input cType value
Input/Output(Suspended)
Output
Description
Statement handle
Column position in the result set to bind. Starts with 1.
C data type identifier of the *Value buffer. About the OODBC data types See the appendix of this document.
Pointer of the buffer to store the data. SQLFetch () returns the data to this buffer.If the value is a NULL pointer, the ODBC will unbind the data buffer for the result set columns. An application unbinds all columns by calling SQLFreeStmt () using SQL_UNBind option. However, if the ValueLength argument is valid even though the value argument is a NULL pointer, an application still have buffer for binding. of the length.
27 ODBC Functions
SQLBindCol
Data Type
SQLINTEGER
SQLINTEGER *
Argument max
In/Out
Input valueLength Input/Output(Suspended)
Description
Maximum size of the buffer (in bytes). When returning the character data to the *Value, the *Value argument must include space for the NULL-terminatior. Otherwise, the ODBC cuts out the data. In case a fixed length data (integer, date structure, etc) are returned, the ODBC will ignore max. Therefore, a sufficient buffer size must be allocated. Otherwise, the ODBC passes through the end of the buffer and saves the garbage data.
Is a pointer for the data length or
NULL. SQLFetch () function be able to return the length of data or
SQL_NULL_DATA
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
The pointer value and ValueLength are suspended output variables for this function. Thememory address indicated by this pointer will not be updated until SQLFetch () is called. The position referred to by this pointer must be valid till SQLFetch () is called.
SQLBindCol () binds application variables to the columns of the result set for all data types. When
SQLFetch () is called, the data will be sent from the databaseMS to an application.
An application calls SQLBindCol () once for each column. When SQLFetch () is called, the data of each bound column is stored in the address allocated by the value or the ValueLength pointer.
An application can inquire the attributes such as the data type or length of the column by calling
SQLDescribeCol () or SQLColAttribute (). This information can be used to indicate the proper data type or to convert the data into another data type.
The columns are identified in a series of numbers from the left to the right. The number of columns in the result set can be decided by setting SQL_DESC_Count in SQLNumResultCols () or fieldIdentifier argument and by calling SQLColAttribute ().
An application may not bind any column. The data in unbound column can be searched by SQLGet-
ODBC Users’ Manual 28
SQLBindCol
Data () after SQLFetch () is called. In usuall case SQLBindCol () is more efficient than SQLGetData ().
* To get the data from the buffer identified by this function, SQLBindCol () must be called before
SQLFetch ().
Diagnosis
SQLSTATE
07009
HY000
HY001
HY003
Description Comments
Invalid column number.
col Arguments exceeds the maximum number of columns in the result set.
General error
Memory allocation error Failed to allocate the memory for the explicit handle.
An application buffer type is not valid.
cType argument is not valid.
Related Functions
SQLDescribeCol
SQLFetch
SQLFreeStmt
SQLGetData
SQLNumResultCols
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_ex2.cpp
sprintf(query,"SELECT id,name,age FROM DEMO_EX2 WHERE id=?"); if (SQLPrepare(stmt,query, SQL_NTS) != SQL_SUCCESS)
{
execute_err(dbc, stmt, query);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLBindParameter(stmt, 1, SQL_PARAM_INOUT,
SQL_C_CHAR, SQL_CHAR,
8, 0,
id_in, sizeof(id_in), NULL) != SQL_SUCCESS)
{
execute_err(dbc, stmt, query);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
29 ODBC Functions
SQLBindCol
/* Set the variable to bring the result of Select. */ if (SQLBindCol(stmt, 1, SQL_C_CHAR,
id, sizeof(id), NULL) != SQL_SUCCESS)
{
printf("SQLBindCol error!!!\n");
execute_err(dbc, stmt, query);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLBindCol(stmt, 2, SQL_C_CHAR,
name, sizeof(name), NULL) != SQL_SUCCESS)
{
printf("SQLBindCol error!!!\n");
execute_err(dbc, stmt, query);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLBindCol(stmt, 3, SQL_C_SLONG,
&age, 0, NULL) != SQL_SUCCESS)
{
printf("SQLBindCol error!!!\n");
execute_err(dbc, stmt, query);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
To display the result while the result is available */ printf("id\tName\tAge\tbirth\t\sex\tetc\n"); printf("====================================================================
=\n"); for ( i=1; i<=3; i++ )
{
sprintf(id_in, "%d0000000", i);
if ( SQLExecute(stmt) != SQL_SUCCESS )
{
execute_err(dbc, stmt, "SQLExecute : ");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
if ( (rc = SQLFetch(stmt)) != SQL_NO_DATA && rc == SQL_SUCCESS )
{ printf("%-10s%-20s%-5d%4d/%02d/%02d %02d:%02d:%02d\t%-2d\t",
id, name, age, birth.year, birth.month, birth.day,
birth.hour, birth.minute, birth.second, sex);
if (etc_ind == SQL_NULL_DATA)
{
printf("NULL\n");
}
else
{
printf("%.3f\n", etc);
}
}
else
{
execute_err(dbc, stmt, query);
break;
}
}
ODBC Users’ Manual 30
SQLCloseCursor
SQLCloseCursor
This closes cursor and discards the suspended results.
Syntax
SQLRETURN SQLCloseCurosr (
SQLHSTMT stmt);
Arguments
Data Type
SQLHSTMT
Argument stmt In
In/Out Description
Command Handle
Return Value
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
This closes cursor and discars the suspended results. This option has same functionality as using
SQL_CLOSE option in SQLFreeStmt(). However, 240000 errors occur if cursor is not open in SQLClose-
Corsor().
Diagnostics
SQLSTATE
HY000
HY001
Description
General Error
Memory Allocation Error
24000 The state of cursor is incorrect.
31
Comments
This denotes to fail to allocate memory for handle.
No cursor is open in command handle.
ODBC Functions
SQLCloseCursor
Related Function
SQLFreeHandle
ODBC Users’ Manual 32
SQLBindParameter
SQLBindParameter
SQLBindParameter binds the parameter marker of an SQL statement with an application variables.
The data is transmitted from an application to the database when SQLExecute () is called.
Syntax
SQLRETURN SQLBindParameter (
SQLHSTMT stmt,
SQLSMALLINT par,
SQLSMALLINT pType,
SQLSMALLINT cType,
SQLSMALLINT sqlType,
SQLINTEGER columnSize,
SQLSMALLINT scale,
SQLPOINTER value,
SQLINTEGER valueMax,
SQLINTEGER *valueLength );
Arguments
Data Type
SQLHSTMT
SQLSMALLINT
SQLSMALLINT
Argument stmt par pType
In/Out
Input
Input
Input
SQLSMALLINT
SQLSMALLINT cType sqlType
Input
Input
Description
Statement handle
Parameter order. Starting with 1.
Parameter type.All parameters in an SQL statement are input variables
(SQL_PARAM_INOUT), When executing a stored procedure, arguments can be are input, output, or input/output type variables. (SQL_PARAM_INOUT,
SQL_PARAM_OUTPUT,
SQL_PARAM_INOUT_OUTPUT)
C data type of parameterSQL_C_CHARSQL_C_SBIGINT, etcSee :Appendix of this document
Data type SQL_CHAR of the parameterSQL_VARCHAR, etcSee :Appendix of this document
33 ODBC Functions
SQLBindParameter
Data Type
SQLINTEGER
SQLSMALLINT
SQLPOINTER
SQLINTEGER
SQLINTEGER *
Argument columnSize scale value valueMax valueLength
In/Out Description
Input
Input
Input (Suspended)
An argument that indicates the precision of a parameter marker. Based on SQL type, it can be used as follows:*
SQL_CHAR, SQL_VARCHAR: Indicates the max allowed length of a parameter marker. (If columnSize is 0, the default columnSize is used. For SQL_CHAR and
SQL_VARCHAR, their columnSize is
32,000.)* SQL_DECIMAL, SQL_NUMERIC:
Indicates the decimal significant digits of a parameter marker. (If columnSize is 0, the default columnSize is used. For both
SQL_DECIMAL and SQL_NUMERIC, the columnSize is 38, which is the max number of decimal significant digits.)*
SQL_BINARY, SQL_BYTES, SQL_NIBBLE,
SQL_VARBIT: Indicates the max allowed length of a parameter marker.(If column-
Size is 0, the default columnSize is used.
The columnSize for each type is as follows:For SQL_BINARY, SQL_BYTE and
SQL_VARBIT, their columnSize is 32000.
For SQL_NIBBLE, its columnSize is 254.)*
For other types, the user-defined column-
Size argument is ignored and the following fixed value is used.SQL_SMALLINT
5SQL_INTEGER 10SQL_BIGINT
19SQL_REAL 7SQL_FLOAT
38SQL_DOUBLE 15SQL_TYPE_DATE
30SQL_TYPE_TIME
30SQL_TYPE_TIMESTAMP
30SQL_INTERVAL 10SQL_GEOMETRY
3200
The Scale of *value.
The pointer of the actual data about the parameter when SQLExecute () or SQLExecDirect () is called.
Input/Output Maximum length of the *Value buffer for the character or binary C data
Input(Suspended)
Pointer of the input/output data length when SQLExecute () or SQLExecDirect () is called
Return Values
SQL_SUCCESS
ODBC Users’ Manual 34
SQLBindParameter
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
Binding Arrays
The array binding method reduces the network round-trip count and improves the speed by sending the parameter using array types.
The following figure briefly shows how works array binding. Larger amount of data can be sent in a shorter time due to reduced network paging count.
There are two array binding types:
Column-wise Parameter Binding
When using column-wise binding, an application binds one or two, or in some cases three, arrays to each column for which data is to be returned. To use a column-wise binding, do the following:
Set SQL_ATTR_PARAM_BIND_TYPE in Arguments Attribute of an application function SQLSetStmtAttr()
Set SQL_PARAM_BIND_BY_COLUMN in param.
For each column to be bound, the applicatoin performs the following procedures.
35 ODBC Functions
SQLBindParameter
1.
Allocate the parameter buffer array.
2.
Allocate the indicator buffer array.
3.
Call SQLBindParameter () with arguments.
cType is C data type of the single element in the parameter buffer array.
sqlType is the SQL data type of the parameter.
Value is the address of the parameter buffer array.
valueMax is the size of the single element in the parameter buffer array.
valueLength is the address of the length/indicator array.
The following figure shows how the column-wise binding operates for each column.
4. Example
#define DESC_LEN 51
#define ARRAY_SIZE 10
SQLCHAR * Statement = "INSERT INTO Parts (PartID, Description, Price) "
"VALUES (?, ?, ?)";
SQLUINTEGER
SQLCHAR
PartIDArray[ARRAY_SIZE];
DescArray[ARRAY_SIZE][DESC_LEN];
SQLREAL
SQLINTEGER
PriceArray[ARRAY_SIZE];
PartIDIndArray[ARRAY_SIZE], DescLenOrIndArray[ARRAY_SIZE],
PriceIndArray[ARRAY_SIZE];
SQLUSMALLINT i, ParamStatusArray[ARRAY_SIZE];
SQLUINTEGER ParamsProcessed;
ODBC Users’ Manual 36
SQLBindParameter
// Set the SQL_ATTR_PARAM_BIND_TYPE statement attribute to use
// column-wise binding.
SQLSetStmtAttr(hstmt, SQL_ATTR_PARAM_BIND_TYPE,
SQL_PARAMETER_BIND_BY_COLUMN, 0);
// Specify the number of elements in each parameter array.
SQLSetStmtAttr(hstmt, SQL_ATTR_PARAMSET_SIZE, ARRAY_SIZE, 0);
// Specify an array in which to return the status of each set of
// parameters.
SQLSetStmtAttr(hstmt, SQL_ATTR_PARAM_STATUS_PTR, ParamStatusArray, 0);
// Specify an SQLUINTEGER value in which to return the number of sets of
// parameters processed.
SQLSetStmtAttr(hstmt, SQL_ATTR_PARAMS_PROCESSED_PTR, &ParamsProcessed, 0);
// Bind the parameters in column-wise fashion.
SQLBindParameter(hstmt, 1, SQL_PARAM_INOUT, SQL_C_ULONG, SQL_INTEGER, 5, 0,
PartIDArray, 0, PartIDIndArray);
SQLBindParameter(hstmt, 2, SQL_PARAM_INOUT, SQL_C_CHAR, SQL_CHAR, DESC_LEN -
1, 0,
DescArray, DESC_LEN, DescLenOrIndArray);
SQLBindParameter(hstmt, 3, SQL_PARAM_INOUT, SQL_C_FLOAT, SQL_REAL, 7, 0,
PriceArray, 0, PriceIndArray);
Row-wise Binding
When using row-wise binding, an application defines a structure containing one or two, or in some cases three, elements for each column for which data is to be returned.An application performs the next procedures to use the row-wise binding.
Define the array to include the single set of the parameters (including parameters and the length/ indicator buffers).
Set SQL_ATTR_PARAM_BIND_TYPE in argument attributes of function SQLSetStmtAttr (), and set the size of the array including program variables in the argument parameter, and binds the address of each element to the first element of the array.
Call SQLBindParameter () with following arguments.
cType is the component type of the parameter buffer.
sqlType is the SQL data type of the parameter.
Value is the address of the parameter buffer component in the first array element.
valueMax is the size of the parameter buffer component.
valueLength is the address of the length/indicator to be bound.
The following figure shows how row-wise binding operates.
37 ODBC Functions
SQLBindParameter
Example
#define DESC_LEN 51
#define ARRAY_SIZE 10 typedef tagPartStruct {
SQLREAL Price;
SQLUINTEGER PartID;
SQLCHAR Desc[DESC_LEN];
SQLINTEGER
SQLINTEGER
SQLINTEGER
} PartStruct;
PriceInd;
PartIDInd;
DescLenOrInd;
PartStruct PartArray[ARRAY_SIZE];
SQLCHAR * Statement = "INSERT INTO Parts (PartID, Description,
Price) "
"VALUES (?, ?, ?)";
SQLUSMALLINT i, ParamStatusArray[ARRAY_SIZE];
SQLUINTEGER ParamsProcessed;
// Set the SQL_ATTR_PARAM_BIND_TYPE statement attribute to use
// column-wise binding.
SQLSetStmtAttr(hstmt, SQL_ATTR_PARAM_BIND_TYPE, sizeof(PartStruct), 0);
// Specify the number of elements in each parameter array.
SQLSetStmtAttr(hstmt, SQL_ATTR_PARAMSET_SIZE, ARRAY_SIZE, 0);
// Specify an array in which to return the status of each set of
// parameters.
SQLSetStmtAttr(hstmt, SQL_ATTR_PARAM_STATUS_PTR, ParamStatusArray, 0);
// Specify an SQLUINTEGER value in which to return the number of sets of
// parameters processed.
SQLSetStmtAttr(hstmt, SQL_ATTR_PARAMS_PROCESSED_PTR, &ParamsProcessed, 0);
// Bind the parameters in row-wise fashion.
SQLBindParameter(hstmt, 1, SQL_PARAM_INOUT, SQL_C_ULONG, SQL_INTEGER, 5, 0,
ODBC Users’ Manual 38
SQLBindParameter
&PartArray[0].PartID, 0, &PartArray[0].PartIDInd);
SQLBindParameter(hstmt, 2, SQL_PARAM_INOUT, SQL_C_CHAR, SQL_CHAR, DESC_LEN -
1, 0,
PartArray[0].Desc, DESC_LEN, &PartArray[0].DescLenOrInd);
SQLBindParameter(hstmt, 3, SQL_PARAM_INOUT, SQL_C_FLOAT, SQL_REAL, 7, 0,
&PartArray[0].Price, 0, &PartArray[0].PriceInd);
Constraints
For SQL_BINARY, SQL_BYTES, SQL_NIBBLE and SQL_VARBIT types, the buffer size and column size must be specified.
For SQL_CHAR and SQL_VARCHAR types, the default precision is the max size that a column can have. For SQL_NUMERIC and SQL_NUMBER types, the precision is 38.
Diagnosis
SQLSTATE
07006
07009
HY000
HY001
HY003
HY009
HY090
HY105
Description Comments
Violation of the limited data type attributes
Invalid number
General error
Memory allocation error
A cType data type cannot be converted into a sqlType data type.
Indicated par value is smaller than 1.
An application buffer type is not valid.
A cType value is invalided C data type.
Invalid pointer used (null pointer) valueLength is a NULL pointer and pType is not SQL_PARAM_OUTPUT.
Invalid buffer length
Failed to allocate the memory for the explicit handle.
Wf73 Invalid parameter type valueMax value is smaller than 0 or higher than 64K pType is invalided value (in, out, inout)
Related Functions
SQLExecDirect
SQLExecute
SQLFreeStmt
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_ex2.cpp
39 ODBC Functions
SQLBindParameter sprintf(query,"INSERT INTO DEMO_EX2 VALUES( ?, ?, ?, ?, ?, ? )");
/* Prepare for a statement and bind the variable. */ if (SQLPrepare(stmt, query, SQL_NTS) != SQL_SUCCESS)
{
execute_err(dbc, stmt, query);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLBindParameter(stmt,1, /* the sequence of host variables indicated by
?, starting with 1 */
SQL_PARAM_INOUT, /* Indicates in, out, and inout. */
SQL_C_CHAR, /* c type of the variable to bind */
SQL_CHAR, /* Data type of the corresponding column in the database char (8)*/
8, /* precision of the column type upon creation of the table */
0, /* Scale of the column type upon creation of the table */
id, /* Pointer of the buffer to be bound */
sizeof (id), /* Size of the buffer to be bound */
&id_ind /* indicator */
) != SQL_SUCCESS)
{
execute_err(dbc, stmt, query);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLBindParameter(stmt, 2, SQL_PARAM_INOUT,
SQL_C_CHAR, SQL_VARCHAR,
20, /* varchar(20) */
0,
name, sizeof(name), &name_ind) != SQL_SUCCESS)
{
execute_err(dbc, stmt, query);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLBindParameter(stmt, 3, SQL_PARAM_INOUT,
SQL_C_SLONG, SQL_INTEGER,
0, 0, &age,
0,/* Not used when the buffer to be bound is the fixed size type. */
NULL) != SQL_SUCCESS)
{
execute_err(dbc, stmt, query);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLBindParameter(stmt, 4, SQL_PARAM_INOUT,
SQL_C_TYPE_TIMESTAMP, SQL_DATE,
0, 0, &birth, 0, NULL) != SQL_SUCCESS)
{
execute_err(dbc, stmt, query);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLBindParameter(stmt, 5, SQL_PARAM_INOUT,
SQL_C_SSHORT, SQL_SMALLINT,
0, 0, &sex, 0, NULL) != SQL_SUCCESS)
{
execute_err(dbc, stmt, query);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLBindParameter(stmt, 6, SQL_PARAM_INOUT,
SQL_C_DOUBLE, SQL_NUMERIC,
10, 3, &etc, 0, &etc_ind) != SQL_SUCCESS)
ODBC Users’ Manual 40
SQLBindParameter
{
execute_err(dbc, stmt, query);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
/* Execute the prepared statement. */ sprintf(id, "10000000"); sprintf(name, "name1"); age = 28;
birth.year=1980;birth.month=10;birth.day=10;
birth.hour=8;birth.minute=50;birth.second=10; sex = 1; etc = 10.2; id_ind = SQL_NTS; /* id => NULL terminated string */ name_ind = 5; /* name => length=5 */
/* etc is the fixed size type. Therefore, it will be ignored unless the indicator is SQL_NULL_DATA. */ if (SQLExecute(stmt) != SQL_SUCCESS)
{
execute_err(dbc, stmt, query);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
41 ODBC Functions
SQLColAttribute
SQLColAttribute
SQLColAttribute brings the attributes for the column of the result set, and judges the count of columns.
SQLColAttributeW() as a Unicode string supports same execution as SQLColAttribute().
Syntax
64 bit Windows
SQLRETURN SQLColAttribute (
SQLHSTMT stmt,
SQLSMALLINT columnNumber,
SQLSMALLINT fieldIdentifier,
SQLCHAR *charAttributePtr,
SQLSMALLINT bufferLength,
SQLSMALLINT *stringLengthPtr,
SQLLEN *numericAttributePtr );
Other Platforms
SQLRETURN SQLColAttribute (
SQLHSTMT stmt,
SQLSMALLINT columnNumber,
SQLSMALLINT fieldIdentifier,
SQLCHAR *charAttributePtr,
SQLSMALLINT bufferLength,
SQLSMALLINT *stringLengthPtr,
SQLPOINTER *numericAttributePtr );
Arguments
Data Type
SQLHSTMT
SQLSMALLINT
Argument stmt columnNumber
In/Out
Input
Input
Description
Statement handle
The column position in the result set.
Starts with 1.
ODBC Users’ Manual 42
Data Type
SQLSMALLINT
Argument In/Out fieldIdentifier Input
SQLCHAR *
SQLSMALLINT
SQLSMALLINT *
SQLINTEGER * charAttributePtr bufferLength stringLength-
Ptr numericAttributePtr
Output
Input
Output
Output
SQLColAttribute
Description
Information identifier to know:SQL_DESC_CASE_SENSITIVE,
SQL_DESC_CATALOG_NAME,SQL_DESC_
COUNT,SQL_DESC_DISPLAY_SIZE,SQL_D
ESC_LABEL,SQL_DESC_LENGTH,SQL_DES
C_NAME,SQL_DESC_NULLABLE,SQL_DES
C_PRECISION, SQL_DESC_SCALE,
SQL_DESC_SCHEMA_NAME,SQL_DESC_T
ABLE_NAME,SQL_DESC_TYPE,SQL_DESC
_TYPE_NAME,SQL_DESC_UNSIGNED
Buffer pointer to store data to be returned when fieldIdentifier in column-
Number is the character string. If field value is an integer, it is not used.
The character number of *charAttributePtrIf *charAttributePtr is an integer, this field is ignored.
Pointer to a buffer in whih to return the total number of bytes (excluding the nulltermination byte) available to return in
*charAttributePtr.
Pointer of the integer buffer to which the value of fieldIdentifier field in column-
Number row is returned.
Return Values
SQL_SUCCESS
SQL_INVALID_HANDLE
SQL_ERROR
Description
Instead of returning a specified arguments set such as SQLDescribeCol (),using SQLColAttribute () the attributes for a specified column can be defined. In case the required information is a string type, it will be returned to charAttributePtr. In case the required information is numeric type, it will be returned to numericAttributePtr.
The column is identified by its position (from left to the right, starting with 1).
Call SQLNumResultCols () before calling SQLColAttribute () to check whether the result set exists.
SQLDescribeCol () must be called before SQLBindCol () in case an application does not know about column attributes such as data types, length, etc.
43 ODBC Functions
SQLColAttribute
fieldIdentifier Descriptor Types
The following table shows the descriptor types returned by SQLColAttribute ().
Descriptor
SQL_DESC_CASE_SENSITIVE
SQL_DESC_CATALOG_NAME
SQL_DESC_COUNT
SQL_DESC_DISPLAY_SIZE
SQL_DESC_LABLE
SQL_DESC_LENGTH
SQL_DESC_NAME
SQL_DESC_NULLABLE
SQL_DESC_PRECISION
SQL_DESC_SCALE
SQL_DESC_SCHEMA_NAME
SQL_DESC_TABLE_NAME
SQL_DESC_TYPE
SQL_DESC_TYPE_NAME
SQL_DESC_UNSIGNED
Data Type
SQLINTEGER
SQLCHAR *
SQLINTEGER
SQLINTEGER
SQLCHAR *
SQLINTEGER
SQLCHAR *
SQLINTEGER
SQLINTEGER
SQLINTEGER
SQLCHAR *
SQLCHAR *
SQLINTEGER
SQLCHAR *
SQLINTEGER
Description
Discrimination of upper and lower characters
Catalog of the table including columns
The column number of the result set is returned.
The maximum number of characters to display the column data
Column label or title
Data bytes related to the column
Name of the column
Whether or not to NULL
Yes – SQL_NULLABLE
No – SQL_NO_NULLS
Precision of the column
Decimal point attributes of the column
Schema of the table including the columns
Table Name
SQL data type
Database type name
Inspection of column items
Diagnosis
SQLSTATE
07009
Description
Invalid column number
HY000 General error
Comments columnNumber is 0 or higher than the number of columns in the result set.
ODBC Users’ Manual 44
SQLColAttribute
Related Functions
SQLBindCol
SQLDescribeCol
SQLFetch
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_meta8.cpp
sprintf(query,"SELECT * FROM DEMO_META8"); if (SQLExecDirect(stmt,query, SQL_NTS) != SQL_SUCCESS)
{
execute_err(dbc, stmt, query);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
SQLNumResultCols(stmt, &columnCount);
for ( i=0; i<columnCount; i++ )
{
SQLColAttribute(stmt, i+1,
SQL_DESC_NAME,
columnName, sizeof(columnName), &columnNameLength,
NULL);
SQLColAttribute(stmt, i+1,
SQL_DESC_TYPE,
NULL, 0, NULL,
&dataType);
SQLColAttribute(stmt, i+1,
SQL_DESC_PRECISION,
NULL, 0, NULL,
&columnPrecision);
SQLColAttribute(stmt, i+1,
SQL_DESC_SCALE,
NULL, 0, NULL,
&scale);
SQLColAttribute(stmt, i+1,
SQL_DESC_NULLABLE,
NULL, 0, NULL,
&nullable);
}
45 ODBC Functions
SQLColumns
SQLColumns
SQLColumns retrieves column information of a specified tableas an result set format.
SQLColumnsW() as a Unicode string supports same execution as SQLColumns().
Syntax
SQLRETURN SQLColumns (
SQLHSTMT stmt,
SQLCHAR *cName,
SQLSMALLINT cNameLength,
SQLCHAR *sName,
SQLSMALLINT sNameLength,
SQLCHAR *tName,
SQLSMALLINT tNameLength,
SQLCHAR *colName,
SQLSMALLINT colNameLength );
Arguments
Data Type
SQLHSTMT
SQLCHAR*
SQLSMALLINT
SQLCHAR *
SQLSMALLINT
SQLCHAR *
SQLSMALLINT
SQLCHAR *
SQLSMALLINT
Argument In/Out stmt cName
Input
Input cNameLength Input sName Input sNameLength Input tName Input tNameLength Input colName Input colName-
Length
Input
Description
Statement handle
Catalog Name
The character number of *cName
Name of the schema to retrieve
The character number of *sName
Table name to retrieve
The character number of *tName
Column to retrieve
The character number of *colName
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
ODBC Users’ Manual 46
SQLColumns
SQL_ERROR
Description
This function is usually used before execution of the command to get column information in the database catalog. SQLColumns () can be used to retrieve all data types returned by SQLTables (). On the contrary, SQLColAttribute () and SQLDescribeCol () functions describe columns of the result set and SQLNumResultCols() returns the number of columns in the result set.
SQLColumns () returns the results in the standard result set format sorted by TABLE_CAT,
TABLE_SCHEM, TABLE_NAME, and ORDINAL_POSITION.
Some of columns returned by SQLStatistics () are not returned by SQLColumns (). For example, SQL-
Columns () does not return index columns created by expressions such as “Salary + Benefits” or
“DEPT = 0012” and the filter.
Columns Returned by SQLColumns ()
The following table lists the columns of the result sets.
Name
TABLE_CAT
TABLE_SCHEM
TABLE_NAME 3
COLUMN_NAME 4
1
2
No.
DATA_TYPE
TYPE_NAME
5
6
COLUMN_SIZE 7
BUFFER_LENGTH 8
DECIMAL_DIGITS 9
Data Type
VARCHAR
VARCHAR
Description
Always return NULL
Schema name; NULL in case not suitable for the database
Table Name VARCHAR
(NOT NULL)
VARCHAR
(NOT NULL)
Column Name.As for the unnamed string, the ODBC driver returns the empty character string.
SQL data type SMALLINT
(NOT NULL)
VARCHAR
(NOT NULL)
INTEGER
INTEGER
SMALLINT
Character string representing the name of the data type corresponding to
DATA_TYPE.
String Size. NULL will be returned when the string size is not proper.
The maximum buffer length to store the data
NULL will be returned when the data type cannot apply the decimal points of the string and the decimal points.
47 ODBC Functions
SQLColumns
Name
NUM_PREC_RAD
IX
10
No.
NULLABLE 11
REMARKS
COLUMN_DEF
12
13
SQL_DATA_TYPE 14
SQL_DATETIME_
SUB
CHAR_OCTET_LE
NGTH
15
16
ORDINAL_POSITI
ON
IS_NULLABLE
17
18
Data Type Description
SMALLINT
SMALLINT
(NOT NULL)
In case of the numeric data type, it is 10:
For COLUMN_SIZE and DECIMAL_DIGIT, decimal digits allowable in this string is given. For example, DECIMAL(12,5) string can return NUM_PREC_RADIX 10,
COLUMN_SIZE 12, and DECIMAL_DIGITS
5.
SQL_NO_NULLS when the column is not allowed NULL or SQL_NULLABLE when
NULL is allowed.
Description of the column
Default value of the column
SQL data type
VARCHAR
VARCHAR
SMALLINT
(NOT NULL)
SMALLINT
INTEGER
INTEGER (NOT
NULL)
VARCHAR
Subtype code for the data type. NULL is returned for other data types.
Maximum digits of the character of binary data-type string. For other data types, NULL will be returned.
Column order of the table. The first column number is 1 in the table.
NO : When the column does not include
NULL:YES : When the column includes
NULL:
Diagnosis
SQLSTATE
08S01
Description
Communication channel error
HY000 General error
Related Functions
SQLBindCol
SQLFetch
ODBC Users’ Manual 48
Comments
Communication channel error before the function processing is completed between the ODBC and the database.
SQLColumns
SQLStatistics
SQLTables
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_meta2.cpp
if (SQLColumns(stmt,NULL, 0,
NULL, 0,
"DEMO_META2", SQL_NTS,
NULL, 0) != SQL_SUCCESS)
{
execute_err(dbc, stmt, "SQLColumns");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
SQLBindCol(stmt, 1, SQL_C_CHAR, szCatalog, STR_LEN,&cbCatalog);
SQLBindCol(stmt, 2, SQL_C_CHAR, szSchema, STR_LEN, &cbSchema);
SQLBindCol(stmt, 3, SQL_C_CHAR, szTableName, STR_LEN,&cbTableName);
SQLBindCol(stmt, 4, SQL_C_CHAR, szColumnName, STR_LEN, &cbColumnName);
SQLBindCol(stmt, 5, SQL_C_SSHORT, &DataType, 0, &cbDataType);
SQLBindCol(stmt, 6, SQL_C_CHAR, szTypeName, STR_LEN, &cbTypeName);
SQLBindCol(stmt, 7, SQL_C_SLONG, &ColumnSize, 0, &cbColumnSize);
SQLBindCol(stmt, 8, SQL_C_SLONG, &BufferLength, 0, &cbBufferLength);
SQLBindCol(stmt, 9, SQL_C_SSHORT, &DecimalDigits, 0, &cbDecimalDigits);
SQLBindCol(stmt, 10, SQL_C_SSHORT, &NumPrecRadix, 0, &cbNumPrecRadix);
SQLBindCol(stmt, 11, SQL_C_SSHORT, &Nullable, 0, &cbNullable);
SQLBindCol(stmt, 17, SQL_C_SLONG, &OrdinalPosition, 0, &cbOrdinalPosition);
SQLBindCol(stmt, 18, SQL_C_CHAR, szIsNullable, STR_LEN, &cbIsNullable); while ( (rc = SQLFetch(stmt)) != SQL_NO_DATA)
{
if ( rc == SQL_ERROR )
{
execute_err(dbc, stmt, "SQLColumns:SQLFetch");
break;
}
printf(...);
}
49 ODBC Functions
SQLConnect
SQLConnect
SQLConnect connects the ODBC with the database. The connection handle refers to all data related to the database connection including connection status, transaction status, and error data.
SQLConnectW() as a Unicode string supports same execution as SQLConnect().
Syntax
SQLRETURN SQLConnect (
SQLHDBC dbc,
SQLCHAR *db,
SQLSMALLINT dbLength,
SQLCHAR *usr,
SQLSMALLINT usrLength,
SQLCHAR *pwd,
SQLSMALLINT pwdLength );
Arguments
Data Type
SQLHDBC
SQLCHAR *
SQLSMALLINT
SQLCHAR *
SQLSMALLINT
SQLCHAR *
SQLSMALLINT
Argument dbc
Db dbLength usr usrLength pwd
In/Out
Input
Input
Input
Input
Input
Input pwdLength Input
Description
Connection Handle
Host IP
The character number of * db
User Identifier
The character number of * usr
Authentication character string(password)
The character number of * pwd
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
ODBC Users’ Manual 50
SQLConnect
Description
The input length Arguments (dbLength, usrLength, pwdLength) can be set to actual length of the related data. SQL_NTS to indicate that the related data terminated with NULL, or a length value that does not include a NULL termination character can be set.
* SQLAllocConnect () must be called before this function.
This function must be called before SQLAllocStmt ().
Informations such as IP address, user name, and password can be set by SQLSetConnectAttr () as an argument string.
You set the parameters excepting dbc on null or zero in the distributed transaction(Reference the
SQLSetConnectAttr).
Diagnosis
SQLSTATE
08001
Description
Cannot be connected to the server.
08002
08S01
The connection name is already in use.
Communication channel error
HY000
HY001
General error
Memory allocation error
Comments
ODBC cannot establish connection with the database.
The corresponding dbc is already connected to the database.
Communication channel error before the function processing is completed between the ODBC and the database.
The character set does not exist.
Cannot allocate the requested memory for the ODBC to execute the function and complete execution.
Related Functions
SQLAllocHandle
SQLDisconnect
SQLDriverConnect
SQLSetConnectAttr
51 ODBC Functions
SQLDescribeCol
SQLDescribeCol
SQLDescribeCol returns the name of the column, data type, decimal value, and NULLability of columns from the result set.
SQLDescribeColW() as a Unicode string supports same execution as SQLDescribeCol().
Syntax
SQLRETURNSQLDescribeCol (
SQLHSTMT stmt,
SQLSMALLINT col,
SQLCHAR *name,
SQLSMALLINT nameMax,
SQLSMALLINT *nameLength,
SQLSMALLINT *type,
SQLINTEGER *precision,
SQLSMALLINT *scale,
SQLSMALLINT *nullable );
Arguments
Data Type
SQLHSTMT
SQLSMALLINT
Argument stmt col
In/Out
Input
Input
SQLCHAR*
SQLSMALLINT
SQLSMALLINT * name nameMax nameLength
Output
Input
Output
SQLSMALLINT * type
SQLINTEGER * precision
Output
Output
SQLSMALLINT * scale Output
Description
Statement handle
Order of the parameter marker. Starts with 1
Pointer of the column name
The character number of the * Name
The length of the *name (excluding
NULL-termination byte)
Pointer of the SQL data type in the column
Pointer of column size in databaseThe
ODBC returns 0 ,when pointer column size cannot be decided
Pointer of the number of decimal values in databaseIf the number of decimal values in the database cannot be decided or is not proper, the ODBC will return 0.
ODBC Users’ Manual 52
Data Type
SQLSMALLINT *
Argument
- NULLable
In/Out
Output
SQLDescribeCol
Description
The pointer of the value that indicates whether the column allows
NULL.SQL_NO_NULLS: The column does not allow NULL data.SQL_NULLABLE: The column allows NULL data.
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
An application usually calls SQLPrepare (), and calls SQLDescribeCol () before SQLExecute (). An application can call also SQLDescribeCol () after calling SQLExecDirect ().
SQLDescribeCol () searches names, types, and lengths of the columns created by SELECT statements.
If the column is an expression, *name will be also an expression.
Diagnosis
SQLSTATE
01004
07009
Description
String data, right-truncated.
Invalid descriptor index
Comments
If the buffer *name is not long enough to return the entire column name, the length of the full column name will be returned as *nameLength.
The col value is 0. The identified col value is higher than the number of columns in the result set.
HY000
HY090
General error
Invalid string or buffer length The identified nameMax is smaller than 0.
If SQLDescribeCol () is called after SQLPrepare () and before SQLExecute (), all SQLSTATE that can be returned by SQLPrepare () or SQLExecute () can be returned.
53 ODBC Functions
SQLDescribeCol
Related Functions
SQLBindCol
SQLColAttribute
SQLFetch
SQLNumResultCols
SQLPrepare
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_meta2.cpp
sprintf(query,"SELECT * FROM DEMO_EX1"); if (SQLExecDirect(stmt,query, SQL_NTS) != SQL_SUCCESS)
{
execute_err(dbc, stmt, query);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
SQLNumResultCols(stmt, &columnCount); for ( i=0; i<columnCount; i++ )
{
SQLDescribeCol(stmt, i+1, columnName, sizeof(columnName),
&columnNameLength, &dataType,
&columnSize, &scale, &nullable);
}
ODBC Users’ Manual 54
SQLDescribeParam
SQLDescribeParam
SQLDescibe returns the SQL data types of the columns related to the parameter marker (?) of the dynamic SQL statements, size, data types, expressions of the corresponding parameter markers, number of decimal values, and the NULLability.
Syntax
SQLRETURNSQLDescribeParam (
SQLHSTMT stmt,
SQLSMALLINT iparam,
SQLSMALLINT *type,
SQLINTEGER *size,
SQLSMALLINT *decimaldigit,
SQLSMALLINT *nullable );,
Arguments
Data Type
SQLHSTMT
SQLSMALLINT
Argument stmt iparam
SQLSMALLINT *
SQLINTEGER * type size
In/Out
Input
Input
Output
Output
SQLSMALLINT *
SQLSMALLINT * decimaldigit
- NULLable
Output
Output
Description
Statement handle
Order of the parameter marker, starting with 1
SQL data type pointer of the parameter
SQL data type pointer of the parameter.Column size or expression pointer of the corresponding parameter
Number of decimal values of the column, expression pointer of the corresponding parameter
Pointer of the value that shows whether
NULL is allowed for the parameter or not.
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
55 ODBC Functions
SQLDescribeParam
Description
Parameter iparam is identified by the number. It is numbered from the left to the right starting with
1.
* SQLPrepare () must be called before this function.
Before SQLBindParameter (), SQLDescribeParam () must be called.
* Types, sizes, decimal digits, and NULLable of the parameter have the following limitations:
type: SQL_VACHAR
size: 4000
decimaldigit: 0
nullable: SQL_NULLABLE_UNKNOWN , The ODBC Drive cannot decide whether the parameter allows
NULL data.
Diagnosis
SQLSTATE
07009
Description
Invalid column number
HY010 Error in function-calling order
Comments
iparam is out of the entire argument range.
Called before SQLPrepare () / SQLExecDirect ().
Related Functions
SQLExecDirect
SQLNumParams
SQLPrepare
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_info2.cpp
SQLPrepare(hstmt, Statement, SQL_NTS);
// Check to see if there are any parameters. If so, process them.
SQLNumParams(hstmt, &NumParams); if (NumParams) {
// Allocate memory for three arrays. The first holds pointers to buffers in w hich
// each parameter value will be stored in character form. The second con-
ODBC Users’ Manual 56
SQLDescribeParam tains
the
// length of each buffer. The third contains the length/indicator value for each
// parameter.
PtrArray = (SQLPOINTER *) malloc(NumParams * sizeof(SQLPOINTER));
BufferLenArray = (SQLINTEGER *) malloc(NumParams * sizeof(SQLINTEGER));
LenOrIndArray = (SQLINTEGER *) malloc(NumParams * sizeof(SQLINTEGER));
for (i = 0; i < NumParams; i++) {
// Describe the parameter.
SQLDescribeParam(hstmt, i + 1, &DataType, &ParamSize, &DecimalDigits,
&Nullable);
// Call a helper function to allocate a buffer in which to store the parameter
// value in character form. The function determines the size of the buffer fr om
// the SQL data type and parameter size returned by SQLDescribeParam and returns
// a pointer to the buffer and the length of the buffer.
PtrArray[i] = (char*)malloc(ParamSize);
BufferLenArray[i] = SQL_NTS;
// Bind the memory to the parameter. Assume that we only have input parameters.
SQLBindParameter(hstmt, i + 1, SQL_PARAM_INOUT, SQL_C_CHAR, DataType, Param-
Size,
DecimalDigits, PtrArray[i], BufferLenArray[i],
&LenOrIndArray[i]);
// Prompt the user for the value of the parameter and store it in the memory
// allocated earlier. For simplicity, this function does not check the value
// against the information returned by SQLDescribeParam. Instead, the driver does
// this when a statement is executed.
strcpy((char*)PtrArray[i], "AAAAAAA");
BufferLenArray[i] = 7;
}
}
57 ODBC Functions
SQLDisconnect
SQLDisconnect
SQLDisconnect colses a connection and releases the handles for the connection.
Syntax
SQLRETURN SQLDisconnect (
SQLHDBC dbc );
Arguments
Data Type
SQLHDBC
Argument dbc
In/Out
Input
Description
Connection Handle
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
If an application calls SQLDisconnect () before releasing the statement handles related to the connection, the connection with the database will be closed.
When SQL_SUCCESS_WITH_INFO is returned, it means that database is successfully disconnected but additional errors or specified implementation program data exist. The cases are as follows:
An error occurred after disconnection. When connection is not established due to other problems such as communication failure
An application can use the databasec to request another SQLConnect () after successfully calling
SQLDisconnect ().
* To connect another database after calling this function, call SQLConnect () or SQLDriverConnect ().
ODBC Users’ Manual 58
Diagnosis
SQLSTATE
HY000 General error
Description
Related Functions
SQLAllocHandle
SQLConnect
SQLDriverConnect
SQLEndTran
SQLFreeConnect
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_ex1.cpp
SQLDisconnect( dbc );
Comments
SQLDisconnect
59 ODBC Functions
SQLDriverConnect
SQLDriverConnect
SQLDriverConnect () is alternative to SQLConnect (). This function supports the connection string that requires more information than three arguments (DSN, user ID, and password) of SQLConnect ().
SQLDriverConnect () provides connection attributes as follows: host IP or host nameone or more user IDsone or more passwordsconnection methodport numberNLS_USETIMEOUT setting
SQLDriverConnectW() as a Unicode string supports same execution as SQLDriverConnect().
Syntax
SQLRETURN SQLDriverConnect (
SQLHDBC dbc,
SQLPOINTER windowHandle,
SQLCHAR *InConnectionString,
SQLSMALLINT length1,
SQLCHAR *OutConnectionString,
SQLSMALLINT bufferLength,
SQLSMALLINT *strLength2Ptr,
SQLSMALLINT DriverCompletion );
Arguments
Data Type
SQLHDBC
SQLPOINTER
SQLCHAR*
Argument
Dbc windowHandle
InConnectionString
SQLSMALLINT length1
SQLCHAR *
SQLSMALLINT
SQLSMALLINT *
SQLSMALLINT
OutConnectionString bufferLength strLength2Ptr
DriverCompletion
In/Out
Input
Input
Input
Input
Output
Input
Output
Input
Description
Connection Handle
Not used.
A complete connection string, a partial connection string, or an empty character string.For more information see the following description section
The character number of * InConnectionString
Not used.
Not used.
Not used.
Not used.
ODBC Users’ Manual 60
SQLDriverConnect
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_NO_DATA_FOUND
SQL_INVALID_HANDLE
SQL_ERROR
Description
•
•
•
•
•
•
•
This connection string is used to transmit one or more values needed for completion of the connection. The contents of the connection string and DriverCompletion determine the connection method.
•
Each keyword has following attributes.
DSN
Database name, Host IP or host name
UID
User Id
PWD
Password .If there is no password for the user id, no data will be defined.
CONNTYPE
Connection methods (1 : TCP/IP, 2 : UNIX DOMAIN, 3 : IPC)
PRIVILEGE sys account could be granted sysdba privilege for remote access.
Access with (sysdba) sysdba privilege is available through TCP/IP and UNIX DOMAIN, but remote access is only through TCP/IP.
PORT_NO
Connection port number
NLS_USE
NLS language. such as US7ASCII for English, KO16KSC5601 for Korean
NLS_NCHAR_LITERAL_REPLACE
This checks to use NCHAR with analyzing SQL statements. (0: doesn't analyze SQL statments, 1: analyzes SQL statements.
61 ODBC Functions
SQLDriverConnect
•
•
•
•
This causes worse performance.)
TIMEOUT
Time waiting for server connection attemption. The default value is 3 seconds.
CONNECTION_TIMEOUT
Set timeout value to prevent blocking that may occur in select() or poll() in an unstable network
DATE_FORMAT
Date Format. The default date format is YYYY/MM/DD HH:MI:SS.
ALTERNATESERVER
Specifys the IP addresses and the connection port numbers of the alternative servers to use the connection failover feature. For example, the format is
(192.168.1.2:20300,192.168.1.3:20300).
IpcFilePath •
•
•
Client can't connect to server through IPC in Unix because they have different socket paths if having different ALTIBASE_HOMEs each other. You can communicate with Unix domain by using ALTIBASE_HOME/trc/cm-ipc, and then you can get information of shared memory.
APP_INFO
This sets information of program you connect to, and you can check this with the following statement.select CLIENT_APP_INFO from v$session;
AUTOCOMMIT
This denotes to set AUTOCOMMIT mode (ON or OFF).
• LONGDATACOMPAT
This enables BLOB and CLOB to be types for ODBC when you connect to ODBC with data whose type is BLOB or CLOB (YES or No).
InConnectionString :
DSN=192.168.1.11;UID=SYS;PWD=MANAGER;CONNTYPE=1;NLS_USE=KO16KSC5601;PORT_NO=20
202;TIMEOUT=5;CONNECTION_TIMEOUT=10;DATE_FORMAT=DD-MON-YYYY;IPCFILEPATH="…/cmipc”
Restriction
•
• You can access to database remotely with sysdba privilege, but can't start up database.
When you try to contact local server with sysdba privilege through TCP/IP in the state of no remote access specified in REMOTE_SYSDBA_ENABLE and no loop back (127.0.0.1), local server can regard this trial as remote access and then can't allow it.
shell> isql -u sys -p manager -s 192.168.3.91 -port 11515 –sysdba
ODBC Users’ Manual 62
•
SQLDriverConnect
ISQL_CONNECTION = TCP, SERVER = 192.168.3.91, PORT_NO = 11515
[ERR-410C8 : remote access as SYSDBA not allowed]
If the values of PORT_NO and NLS_USE aren't specified in connection string, you should set same value of environment variable below as the value specified in property file. However, if you want to set national-character figurative constant instead of environment variable, you should specify ALTIBASE_NLS_NCHAR_LITERAL_REPLACE as 1. This causes parsing additionally.
export ALTIBASE_PORT_NO=20300 export ALTIBASE_NLS_USE=US7ASCII export ALTIBASE_NLS_NCHAR_LITERAL_REPLACE=0
Diagnosis
SQLSTATE
08001
Description
Unable to establish connection.
08002 The connection name is in use.
08S01 Communication channel error
HY000
HY001
General error
Memory allocation error
Comments
The client is unable to connect to a server.
The connection handle dbc is already connected to the database and still open.
The communication channel between the driver and the database to which the driver was attempting to connect failed before the function completed processing
An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined.
Cannot allocate the requested memory for the ODBC to execute the function and complete execution.
Related Functions
SQLAllocHandle
SQLConnect
SQLDisconnect
SQLFreeHandle
SQLSetConnectAttr
63 ODBC Functions
SQLDriverConnect
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_ex1.cpp
sprintf(connStr,
"DSN=127.0.0.1;UID=%s;PWD=%s;CONNTYPE=%d;NLS_USE=%s",
/* ;PORT_NO=20300", */
USERNAME, PASSWD, 2, NLS);
/* Establish a connection. */ if (SQLDriverConnect( dbc, NULL, connStr, SQL_NTS,
NULL, 0, NULL,
SQL_DRIVER_NOPROMPT ) != SQL_SUCCESS)
{
execute_err(dbc, SQL_NULL_HSTMT, "SQLDriverConnect");
return SQL_ERROR;
}
ODBC Users’ Manual 64
SQLEndTran
SQLEndTran
SQLEndTran requests a commit or rollback operation for all active operations on all statements associated with a connection. SQLEndTran can also request that a commit or rollback operation be performed for all connections associated with an environment..
Syntax
SQLRETURN SQLEndTran (
SQLSMALLINT handleType,
SQLHENV handle,
SQLSMALLINT type );
Arguments
Data Type
SQLSMALLINT
Argument handleType
In/Out
Input
SQLHENV
SQLSMALLINT handle type
Input
Input
Description
Handle type identifier. It should be either
SQL_HANDLE_ENV or
SQL_HANDLE_DBC.
The handle.
One of the following two values:SQL_COMMITSQL_ROLLBACK
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
If the handleType is SQL_HANDLE_ENV and the handle is effective environment handle, the ODBC will call SQLEndTran () for each connection handle related to the environment. The handle argument to call the ODBC must be the environment handle of the ODBC. In this case, the ODBC may commit the transaction or attempt to rollback depending on the type in the connected status.
If the type is SQL_COMMIT, SQLEndTran () will send commit command to the session related to the connection. If the type is SQL_ROLLBACK, SQLEndTran () will give rollback request to the connection-related session.
65 ODBC Functions
SQLEndTran
In case of the manual commit mode, by calling SQLSetConnectAttr () that can set
SQL_ATTR_AutoCommit statement attribute as SQL_AutoCommit_OFF, the new transaction will internally start when an SQL statement to be included in the transaction is executed.
Diagnosis
Comments SQLSTATE
HY000 General error
Description
Related Functions
SQLFreeHandle
SQLFreeStmt
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_tran1.cpp
SQLEndTran(SQL_HANDLE_DBC, dbc, SQL_COMMIT);
ODBC Users’ Manual 66
SQLError
SQLError
SQLError returns error or status information.
SQLErrorW() as a Unicode string supports same execution as SQLError().
Syntax
SQLRETURN SQLError(
SQLHENV env,
SQLHDBC dbc,
SQLHSTMT stmt,
SQLCHAR *state,
SQLINTEGER *err,
SQLCHAR *msg,
SQLSMALLINT msgMax,
SQLSMALLINT *msgLength );
Arguments
Data Type
SQLHENV
SQLHDBC
SQLHSTMT
SQLCHAR *
SQLINTEGER *
SQLCHAR *
SQLSMALLINT
SQLSMALLINT *
Argument env dbc stmt state err msg msgMax msgLength
In/Out
Input
Input
Input
Output
Output
Output
Input
Output
Description
Environment Handle
Connection Handle
Statement handle
Pointer of SQLSTATE
Pointer of unique Altibase error code
Pointer of the diagnosis message
The character number of the * msg buffer
Pointer of the total length of return buffer. Excludes NULL termination character.
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
67 ODBC Functions
SQLError
Description
SQLSTATE is the same as defined by X/OPEN SQL CAE and X/OPEN SQLCLI snapshot.
SQLERROR() gets diagnosis information as followings:
To gain environment-related diagnosis information, send a valid environment handle. Set dbc and stmt as SQL_NULL_DBC and SQL_NULL_STMT.
To acquire connection-related diagnosis information, send the valid database connection handle and set stmt as SQL_NULL_STMT. Arguments env will be ignored.
To acquire diagnosis information related to a command, send the valid statement handle. env and dbc Arguments will be ignored.
If diagnosis information created by one ODBC function is not catched before functions other than
SQLERROR () are called by the same handle, information related to calling of the previous functions will be lost. Always true regardless whether there is diagnosis information created by the second calling of the ODBC function.
To prevent the error message from being cut, the buffer length will be declared as
SQL_MAX_MESSAGE_LENGTH + 1. The message text cannot be longer than this.
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_ex1.cpp
SQLINTEGER errNo;
SQLSMALLINT msgLength;
SQLCHAR errMsg[MSG_LEN]; if (SQLERROR ( SQL_NULL_HENV, aCon, aStmt,
NULL, &errNo,
errMsg, MSG_LEN, &msgLength ) == SQL_SUCCESS)
{
printf(" Error : # %ld, %s\n", errNo, errMsg);
}
ODBC Users’ Manual 68
SQLExecDirect
SQLExecDirect
If an SQL statement includes parameters, the given SQL statement will be directly executed using the current value of the parameter marker. When Using SQLExecDirect(), the SQL statement can be executed only once and is the fastest method to submit for an one-time execution.
SQLExecDirectW() as a Unicode string supports same execution as SQLExecDirect().
Syntax
SQLRETURN SQLExecDirect (
SQLHSTMT stmt,
SQLCHAR *sql,
SQLINTEGER sqlLength );
Arguments
Data Type
SQLHSTMT
SQLCHAR *
SQLINTEGER
Argument stmt sql sqlLength
In/Out
Input
Input
Input
Description
Statement handle
SQL statement to be executed
The character number of *sql length
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_NO_DATA_FOUND
SQL_INVALID_HANDLE
SQL_ERROR
Description
The parameter marker can be included in an SQL statement string. Tthe parameter marker specified by "?" and designates the place of the parameters to be replaced as an application variable when
SQLExecDirect() is called. SQLBindParameter () binds an application variable with the parameter marker, and displays whether data must be converted during data transmission. All parameters must be bound before SQLExecDirect () is called.
To select the row in the result set received from the server when an SQL statement is SELECT, the buffer must be bound by SQLBindCol () after SQLExecDirect () is successfully returned and SQLFetch
69 ODBC Functions
SQLExecDirect
() must be called to refer to the bound buffer.
If SQLExecDirect () executes an UPDATE or DELETE statement that does not affect any row, calling
SQLExecDirect () will return SQL_NO_DATA. Use SQLRowCount() to check the number of affecting records.
Diagnosis
SQLSTATE
08003
08S01
HY000
HY001
HY009
Description Comments
Invalid connection handle used
Communication failure Communication channel error
General error
Memory allocation error Failed to allocate the memory for the explicit handle.
Invalid Arguments used (null pointer).
*sql is a NULL pointer
Related Functions
SQLBindCol
SQLEndTran
SQLExecute
SQLFetch
SQLGetData
SQLPrepare
SQLStmtAttr
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_ex1.cpp
sprintf(query,"SELECT * FROM DEMO_EX1"); if (SQLExecDirect(stmt,query, SQL_NTS) != SQL_SUCCESS)
{
execute_err(dbc, stmt, query);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
ODBC Users’ Manual 70
SQLExecute
SQLExecute
SQLExecute submits a prepared statement, using the current values of the parameter marker variables if any parameter markers exist in the statement.
Syntax
SQLRETURN SQLExecute (
SQLHSTMT stmt );
Arguments
Data Type
SQLHSTMT
Argument stmt
In/Out
Input
Description
Statement handle
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_NO_DATA_FOUND
SQL_INVALID_HANDLE
SQL_ERROR
Description
The parameter marker can be included in a SQL statement string. The parameter marker specified by
‘?’ and designates the place of the parameters to be replaced as an application variable when SQLExecute () is called. SQLBindParameter () must bind each parameter marker with a corresponding application variable, and displays whether the data must be converted for transmission. All parameters must be bound before SQLExecute () is called.
SQLExecute() executes a statement prepared by SQLPrepare(). After the application processes or discards the results from a call to SQLExecute, the application can call SQLExecute() again with new parameter values
The command executed by SQLExecDirect () cannot be execute again by SQLExecute (). SQLPrepare
() must be called first.
In case SQLExecute () executes an UPDATE and DELETE statement that does not affect any row in the database, calling SQLExecute () will return SQL_NO_DATA. Use SQLRowCount() to check the number of record.
71 ODBC Functions
SQLExecute
If SQL_ATTR_PARAMSET_SIZE statement attribute is higher than 1 and the SQL statement has at least one parameter marker, SQLExecute () will execute an SQL statement once for a series of the parameters in the array indicated by the *Value argument upon calling of SQLBindParameter ().
Diagnosis
SQLSTATE
07006
Description
Restricted data type attribute violation
08003
08S01 Communication channel error
Comments
The column data within the result set must not be converted to the data type expressed in cType of SQLBind-
Col().
When stmt is not connected or the connection is released
The communication link between the driver and the database to which the driver was connected failed before the function completed processing.
HY000
HY090
General error
Invalid string or buffer length If SQLBindParameter () and the related parameters are NULL pointers, the parameter length is not 0 or
SQL_NULL_DATA. If the parameter designated with SQLBindParameter () is not the NULL pointer, C data type will be SQL_C_BINARY or
SQL_C_CHAR and the parameter length will be smaller than 0.
SQLExecute () can return all SQLSTATE data that are returned by SQLPrepare ().
Related Functions
SQLBindCol
SQLEndTran
SQLExecDirect
SQLFetch
SQLFreeStmt
SQLGetData
ODBC Users’ Manual 72
SQLPrepare
SQLSetStmtAttr
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_ex2.cpp
See the examples of SQLBindParameter ().
SQLExecute
73 ODBC Functions
SQLFetch
SQLFetch
SQLFetch() fetches the next rowset of data from the result set and returns data for all bound columns.
The user can separately get columns by directly receiving the data for the variables specified in SQL-
BindCol () using or by calling SQLGetData () to fetch. In case SQLFetch () is called while conversion is set upon binding of the column, the data will be converted.
Syntax
SQLRETURN SQLFetch (
SQLHSTMT stmt);
Arguments
Data Type
SQLHSTMT
Argument stmt
In/Out
Input
Description
Statement handle
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
SQL_NO_DATA_FOUND
Description
SQLFetch() can be called only when the recently executed command in stmt is a SELECT statement.
SQLBindCol () and the number of binding variables of the application must not exceed the number of columns in the result set. Otherwise, SQLFetch () will fail.
Positioning the Cursor
When the result set is created, the cursor is positioned before the start of the result set. SQLFetch () returns the next row set in the result set. The SQL_ATTR_ROW_ARRAY_SIZE statement attribute specifies the number of rows in the rowset. For example, if the number of rows is 5 when the result set has total 100 rows, the result row set of initial SQLFetch () is from 1 to 5. Also, if the result set is
ODBC Users’ Manual 74
SQLFetch from the 52nd row to 56th row of the current row set, 57th rows to 61st rows will be returned by
SQLFetch (). SQL_SUCCESS will be returned, and the number of released rows will be 5. The following table shows the row set and returns the code that was returned by SQLFetch ().
Current row set Returned code New row set
Post-start
1 to 5
52 to 56
91 to 95
93 to 97
96 to 100
99 to 100
After end
SQL_SUCCESS
SQL_SUCCESS
SQL_SUCCESS
SQL_SUCCESS
SQL_SUCCESS
SQL_NO_DATA
SQL_NO_DATA
SQL_NO_DATA
1 to 5
6 to 10
57 to 61
96 to 100
98 to 100
None
None
None
After SQLFetch () is returned, the current row will become the first row of the row set.
0
0
3
0
5
5
5
5
Number of the fetched rows
Returning the Data in Bound Columns.
As SQLFetch() returns each row, it places the data for each bound column in the buffer bound to that column. If no columns are bound, SQLFetch does not return any data but does move the block cursor forward.
For each bound column, SQLFetch () does the following:
When the data is NULL, set SQL_NULL_DATA in the length/indicator buffer and go to the next column. If the data for the column is not NULL, SQLFetch proceeds to step 2
Converts the data of the type specified in the type argument of SQLBindCol ().
If the data is converted into the flexible length data type, SQLFetch () will inspect whether the data length (including NULL-terminatior when converted into SQL_C_CHAR) exceeds the data buffer length. If the character data length exceeds the data buffer length, SQLFetch () will cut the NULL-terminatior according to the data buffer length. In this way, finish the data composed of NULL characters. If the binary data length exceeds the data buffer length, SQLFetch () will cut the data according to the data buffer. The length of the data buffer is specified in SQLBindCol () length.
Positions the converted data in the data buffer.
Positions the data length in the length/indicator buffer. If the indicator pointer and the length pointer are set as the same buffer, the length will be recorded for the valid data and
SQL_NULL_DATA will be recorded for the NULL data. If there is no bound length/indicator buffer,
SQLFetch () will not return the length.
The contents of the bound data buffer and the length/indicator buffer are not defined unless
75 ODBC Functions
SQLFetch
SQLFetch () returns SQL_SUCCESS or SQL_SUCCESS_WITH_NOINFO. When the result of SQLFetch () is SQL_ERROR, it is invalid value.
Row Status Array
The row status array is used to return the status of each row in the rowset. The address of this array is specified with the SQL_ATTR_ROW_STATUS_PTR statement attribute. The array is allocated by the application and must have as many elements as are specified by the SQL_ATTR_ROW_ARRAY_SIZE statement attribute. If the value of SQL_ATTR_ROW_STATUS_PTR is a NULL pointer, SQLFetch () will not return the row status.
Rows Fetched Buffer
The rows fetched buffer is used to return the number of rows fetched, including those rows for which no data was returned because an error occurred while they were being fetched. In other words, it is the number of rows for which the value in the row status array is not SQL_ROW_NOROW.
The address of this buffer is specified with the SQL_ATTR_ROWS_FETCHED_PTR statement attribute.
The buffer is allocated by the application. This buffer is allocated by an application and set by
SQLFetch (). If SQL_ATTR_ROWS_FETCHED_PTR statement attribute is a NULL pointer, SQLFetch () will not return the number of the fetched rows.
If SQLFetch () does not return SQL_SUCCESS or SQL_SUCCESS_WITH_INFO except SQL_NO_DATA, the contents of the row fetched buffer will not be determined. In this case, the row fetched buffer will be set to 0.
Error Handling
Errors and warnings can apply to individual rows or to the entire function.
Errors and warnings for the entire function
If a random warning is applied to the entire function, SQLFetch () will return
SQL_SUCCESS_WITH_INFO and proper SQLSTATE. The warning status records applied to the function must be returned before the status records are applied to each row.
Diagnosis
SQLSTATE
01004
Description
String data, right truncated
Comments
String or binary data returned for a column resulted in the truncation of nonblank character or non-NULL binary data. If it was a string value, it was right-truncated.
ODBC Users’ Manual 76
SQLFetch
SQLSTATE
07006
Description
Restricted data type attribute violation
08S01 Communication channel error
Comments
The column data within the result set must not be converted to the data type expressed in cType of SQLBind-
Col().
Communication channel failure before the function processing is completed between the ODBC and the database
HY000 General error
Related Functions
SQLBindCol
SQLDescribeCol
SQLExecDirect
SQLExecute
SQLFreeStmt
SQLGetData
SQLNumResultCols
SQLPrepare
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_ex2.cpp
See example of SQLBindCol()
77 ODBC Functions
SQLFetchScroll
SQLFetchScroll
SQLFetchScroll() fetches the specified rowset of data from the result set and returns data for all bound columns. Rowsets can be specified at an absolute or relative position.
Syntax
SQLRETURN SQLFetchScroll(SQLHSTMT stmt,
SQLSMALLINT fOrient,
SQLINTEGER fOffset)
Arguments
Data Type
SQLHSTMT
SQLSMALLINT
Argument stmt fOrient
In/Out
Input
Input
SQLINTEGER fOffset Input
Description
Statement handle
Type of fetch, This argument determines scroll direction.SQL_FETCH_NEXTSQL_FETCH_PRIO
RSQL_FETCH_FIRSTSQL_FETCH_LASTSQL
_FETCH_ABSOLUTESQL_FETCH_RELATIV
E
Number rows to fetch
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
SQL_NO_DATA_FOUND
Description
SQLFetchScroll() fetches the specified rowset of data from the result set and returns data for all bound columns. Rowsets can be specified at an absolute or relative position.
You can set the cursor direction like followings;
SQL_FETCH_NEXT
ODBC Users’ Manual 78
SQLFetchScroll
Return the next rowset. This is equivalent to calling SQLFetch(). SQLFetchScroll() ignores the value of
FetchOffset.
SQL_FETCH_PRIOR
Return the prior rowset. SQLFetchScroll() ignores the value of FetchOffset.
SQL_FETCH_RELATIVE
Return the rowset FetchOffset from the start of the current rowset.
SQL_FETCH_ABSOLUTE
Return the rowset starting at row FetchOffset.
SQL_FETCH_FIRST
Return the first rowset in the result set. SQLFetchScroll() ignores the value of FetchOffset.
SQL_FETCH_LAST
Return the last complete rowset in the result set. SQLFetchScroll() ignores the value of FetchOffset.
Diagnosis
SQLSTATE
01004
Description
String data, right truncated
08S01 Communication channel error
Comments
String or binary data returned for a column resulted in the truncation of nonblank character or non-NULL binary data. If it was a string value, it was right-truncated.
Communication channel failure before the function processing is completed between the ODBC and the database
HY000 General error
Related Functions
SQLFetch
Example
SQLFetchScroll(stmt , SQL_FETCH_RELATIVE, 10);
79 ODBC Functions
SQLForeignKeys
SQLForeignKeys
•
SQLForeignkeys () can return the following:
A list of foreign keys of a specified table (columns of a specified table referring to the primary keys of other tables)
• A list of foreign keys of other tables referring to the primary keys of a specified table
SQLForeignKeysW() as a Unicode string supports same execution as SQLForeignKeys().
Syntax
SQLRETURN SQLForeignKeys (
SQLHSTMTstmt,
SQLCHAR *pkcName,
SQLSMALLINT pkcNaneLength,
SQLCHAR *pksName,
SQLSMALLINT pksNameLength,
SQLCHAR *pktName,
SQLSMALLINT pktNameLength,
SQLCHAR *fkcName,
SQLINTEGER fkcNaneLength,
SQLCHAR *fksName,
SQLSMALLINT fksNameLength,
SQLCHAR *fktName,
SQLSMALLINT fktNameLength);
Arguments
Data Type
SQLHSTMT
SQLCHAR*
SQLSMALLINT
SQLCHAR *
SQLSMALLINT
SQLCHAR *
SQLSMALLINT
SQLCHAR *
Argument stmt pkcName pkcName-
Length pksName pksName-
Length pktName pktName-
Length fkcName
In/Out
Input
Input
Input
Input
Input
Input
Input
Input
Description
Statement handle
Primary key table catalog name
The character number of pkcName
Primary key table schema name
The character number of pksName
Primary key table
The character number of pktName
Foreign key table catalog name
ODBC Users’ Manual 80
Data Type
SQLSMALLINT
SQLCHAR *
SQLSMALLINT
SQLCHAR *
SQLSMALLINT
Argument fkcName-
Length fksName fksName-
Length fktName fktName-
Length
In/Out
Input
Input
Input
Input
Input
SQLForeignKeys
Description
The character number of fkcName
Foreign key table schema name
The character number of fksName
Foreign key table name
The character number of fktName
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
If *pktName contains a table name, SQLForeignKeys ()returns a result set containing the primary key of the specified table and all of the foreign keys that refer to it. The list of foreign keys in other tables does not include foreign keys that point to unique constraints in the specified table.
If *fktName has a table name, SQLForeignKeys () will returns a result set containing all of the foreign keys in the specified table that point to primary keys in others tables, and the primary keys in the other tables to which they refer. The list of foreign keys in the specified table does not contain foreign keys that refer to unique constraints in other tables.
If both *pktName and *fktName have table names, SQLForeignKeys will return the foreign keys of the table specified by *fktName. For *fktName, refer to the primary keys of the table specified in *pkt-
Name.
SQLForeignKeys () returns the result in the standard result set form sorted by FKTABLE_CAT,
FKTABLE_SCHEM, FKTABLE_Name, and KEY_SEQ in case the foreign keys related to the primary keys are requested. If the primary keys related to the foreign keys are requested, the result in the standard result set sorted by PKTABLE_CAT, PKTABLE_SCHEM, PKTABLE_Name, and KEY_SEQ will be returned.
The following table lists the strings of the result sets.
81 ODBC Functions
SQLForeignKeys
Columns Returned by SQLForeignKeys ()
String Name
PKTABLE_CAT
PKTABLE_SCHEM
PKTABLE_NAME
PKCOLUMN_NAME
FKTABLE_CAT
FKTABLE_SCHEM
FKTABLE_NAME
FKCOLUMN_NAME
KEY_SEQ
UPDATE_RULE
1
2
String
No.
Data Type
VARCHAR
VARCHAR
3
Description
Always NULL Return
Foreign key table schema name; NULL if not applicable to the database.
Primary key table name
4
5
6
7
8
9
10
VARCHAR
(NOT NULL)
VARCHAR
(NOT NULL)
VARCHAR
VARCHAR
VARCHAR
(NOT NULL)
VARCHAR
(NOT NULL)
SMALL-
INT(NOT
NULL)
SMALLINT
Primary key column name.As for the unnamed string, ODBC makes the empty character string return.
Always NULL Return
Primary key table schema name; NULL if not applicable to the database
Foreign key table name
Foreign key column name.As for the unnamed string, ODBC makes the empty character string return.
Column number sequence (starting with 1)
DELETE_RULE
FK_NAME
PK_NAME
DEFERRABILITY
11
12
13
14
SMALLINT
VARCHAR
VARCHAR
SMALLINT
Application of SQL_NO_ACTION to the foreign key upon UPDATE operation
Application of SQL_NO_ACTION to the foreign key upon DELETE operation
Foreign key name. NULL not proper for the database
Primary key name. NULL not proper for the database
SQL_INITIALLY_IMMEDIATE
ODBC Users’ Manual 82
SQLForeignKeys
Diagnosis
SQLSTATE
08S01
HY009
HY090
Description Comments
Communication channel error Communication channel failure before the function processing between the ODBC and the database is completed
Invalid Arguments used (null pointer).
Argument pktName and fktName are
NULL pointer.
Invalid string or buffer length The value of one of the name length arguments was less than 0 but not equal to SQL_NTS.
Related Functions
SQLBindCol
SQLFetch
SQLPrimaryKeys
SQLStatistics
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_meta9.cpp
if (SQLForeignKeys(stmt,
NULL, 0,
"SYS", SQL_NTS,
"ORDERS", SQL_NTS,
NULL, 0,
NULL, 0,
NULL, 0) != SQL_SUCCESS)
{
execute_err(dbc, stmt, "SQLForeignKeys");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
SQLBindCol(stmt, 2, SQL_C_CHAR, szPKSchema, NAME_LEN, &cbPKSchema);
SQLBindCol(stmt, 3, SQL_C_CHAR, szPKTableName, NAME_LEN,&cbPKTableName);
SQLBindCol(stmt, 4, SQL_C_CHAR, szPKColumnName, NAME_LEN, &cbPKColumnName);
SQLBindCol(stmt, 6, SQL_C_CHAR, szFKSchema, NAME_LEN, &cbFKSchema);
SQLBindCol(stmt, 7, SQL_C_CHAR, szFKTableName, NAME_LEN,&cbFKTableName);
SQLBindCol(stmt, 8, SQL_C_CHAR, szFKColumnName, NAME_LEN, &cbFKColumnName);
SQLBindCol(stmt, 9, SQL_C_SSHORT, &KeySeq, 0, &cbKeySeq);
83 ODBC Functions
SQLFreeConnect
SQLFreeConnect
SQLFreeConnect() frees resources associated with a specific connection.
SQLFreeConnect () has been replaced by SQLFreeHandle ().
Syntax
SQLRETURN SQLFreeConnect (
SQLHDBC dbc );
Arguments
Data Type
SQLHDBC
Argument dbc
In/Out
Input
Description
Connection Handle Pointer
Return Values
SQL_SUCCESS
SQL_INVALID_HANDLE
SQL_ERROR
Description
When this function is called in the connected status, SQL_ERROR will be returned but the connection handle is still valid.
Related Functions
SQLDisconnect
SQLFreeEnv
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_ex1.cpp .> if ( conn_flag == 1 )
{
SQLDisconnect( dbc );
}
ODBC Users’ Manual 84
if ( dbc != NULL )
{
SQLFreeConnect( dbc );
} if ( env != NULL )
{
SQLFreeEnv( env );
}
SQLFreeConnect
85 ODBC Functions
SQLFreeEnv
SQLFreeEnv
SQLFreeEnv frees resources associated with a specific environment. SQLFreeEnv () has been replaced by SQLFreeHandle ().
Syntax
SQLRETURN SQLFreeEnv (
SQLHENV env );
Arguments
Data Type
SQLHENV
Argument env
In/Out
Input
Description
Environment Handle
Return Values
SQL_SUCCESS
SQL_INVALID_HANDLE
SQL_ERROR
Description
In case this function is called in a valid connection handle, SQL_ERROR will be returned but the environment handle is still valid.
* SQLFreeConnect () must be called before this function.
Related Functions
SQLFreeConnect
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_ex1.cpp >
SQLFreeConnect()>
See example of SQLFreeConnect()
ODBC Users’ Manual 86
SQLFreeHandle
SQLFreeHandle
SQLFreeHandle frees resources associated with a specific environment, connection, statement, or descriptor handle
Syntax
SQLRETURN SQLFreeHandle (
SQLSMALLINT handleType,
SQLHANDLE handle );
Arguments
Data Type
SQLSMALLINT
Argument handleType
In/Out
Input
SQLHANDLE handle Input
Description
Handle type to be freed:
SQL_HANDLE_ENV
SQL_HANDLE_DBC
SQL_HANDLE_STMT
If the handleType is not the one of these values, SQLFreeHandle() free
SQL_INVALID_HANDLE.
Handle to be freed
Return Values
SQL_SUCCESS
SQL_INVALID_HANDLE
SQL_ERROR
If SQLFreeHandle () returns SQL_ERROR, the handle is valid.
Description
SQLFreeHandle () can replace with SQLFreeEnv (), SQLFreeConnect (), and SQLFreeStmt () function.
Once the handle is released, an application cannot use the released handle.
Freeing an Environment Handle
Before handleType calls SQLFreeHandle (), SQL_HANDLE_ENV, an application must call SQLFreeHandle () of which handleType is SQL_HANDLE_DBC for all connections allocated in the corresponding
87 ODBC Functions
SQLFreeHandle environment. Otherwise, calling SQLFreeHandle () will return SQL_ERROR and the corresponding environment and the random activated connection remains still vaild.
Freeing a Connection Handle
If an error is detected on this handle before handleType calls SQLFreeHandle (), SQL_HANDLE_DBC, an application must call SQLDisconnect () for the connection. Otherwise, calling of SQLFreeHandle () will return SQL_ERROR and connection will be still vaild.
Freeing a Statement Hanle
Calling SQLFreeHandle () of which handleType is SQL_HANDLE_STMT will release all resources allocated by calling SQLAllocHandle of which handleType is SQL_HANDLE_STMT. Calling SQLFreeHandle () to release the command with the result suspended by an application will delete the suspended results.
Diagnosis
SQLSTATE
HY000
HY001
Description
General error
Memory allocation error
Comments
Related Functions
SQLAllocHandle
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_meta1.cpp .> if ( dbc != NULL )
{
SQLFreeHandle( SQL_HANDLE_DBC, dbc );
} if ( env != NULL )
{
SQLFreeHandle( SQL_HANDLE_ENV, env );
}
Failed to allocate the memory for the explicit handle.
ODBC Users’ Manual 88
SQLFreeStmt
SQLFreeStmt
SQLFreeStmt stops processing associated with a specific statement, closes any open cursors associated with the statement, discards pending results, or, optionally, frees all resources associated with the statement handle..
Syntax
SQLRETURN SQLFreeStmt (
SQLHSTMT stmt,
SQLSMALLINT fOption );
Arguments
Data Type
SQLHSTMT
SQLSMALLINT
Argument stmt fOption
In/Out
Input
Input
Description
Statement handle
Handle Control Method
SQL_CLOSE,
SQL_DROP,
SQL_UNBIND,
SQL_RESET_PARAMS
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
Calls SQLFreeStmt () with the one of following options:
SQL_CLOSE: Closes the cursor related to stmt, and discards all pending results. An application can open this cursor again by executing SELECT statement again using the same or different variables.
However, if no cursor is open, this option will not effect for the application.
SQL_DROP: The resources related to the input statement handle will be released, and the handle will be freed. In case there is an open cursor, the cursor will be closed and all pending results will be deleted.
89 ODBC Functions
SQLFreeStmt
SQL_UNBIND: Releases all column buffers bound by SQLBindCol for the given StatementHandle.
SQL_RESET_PARAMS: Releases all parameter buffers set by SQLBindParameter (). The relation between an application variable or file reference and an SQL statement parameter marker of the statement handle will be released.
Diagnosis
Comments SQLSTATE
HY000 General error
Description
Related Functions
SQLAllocHandle
SQLFreeHandle
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_ex1.cpp
SQLFreeStmt(stmt, SQL_DROP);
ODBC Users’ Manual 90
SQLGetConnectAttr
SQLGetConnectAttr
SQLGetConnectAttr gets the current setting of connection.
SQLGetConnectAttrW() as a Unicode string supports same execution as SQLGetConnectAttr().
Syntax
SQLRETURN SQLGetConnectAttr (
SQLHDBC dbc,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER *StringLengthPtr );
Arguments
Data Type
SQLHDBC
SQLINTEGER
SQLPOINTER
SQLINTEGER
Argument dbc
Attribute
ValuePtr
In/Out
Input
Input
Output
BufferLength Input
SQLINTEGER StringLength-
Ptr
Output
Description
Connection Handle
Attribute to retrieve
Memory pointer to bring the value corresponding to the attribute
If *ValuePtr is the pointer of character string, this has the byte length of string or the value of SQL_NTS.If *ValuePtr is the pointer of binary buffer, its value is the binary length of data.If *ValuePtr is the pointer with fixed-length data type like integer, its value is ignored.
This returns bytes (excluding the null-termination characater) available to return in *ValuePtr.
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
91 ODBC Functions
SQLGetConnectAttr
Description
In case the attribute returns the string, ValuePtr will be a pointer indicating the string buffer.
The maximum length of the returned string including the NULL-terminatior will be the BufferLength bytes.
Depending on the attribute, an application must establish connections before calling SQLGetConnectAttr ().
List of Connection Attributes
Attribute
SQL_ATTR_AUTOCOMMIT
SQL_ATTR_CONNECTION_TIMEOUT
SQL_ATTR_PORT
SQL_ATTR_TXN_ISOLATION
SQL_ATTR_LOGIN_TIMEOUT
SQL_ATTR_CONNECTION_DEAD
Contents
32-bit value to set reflection for the connection.SQL_AUTOCOMMIT_ON: Each SQL statement is automatically committed. SQL_AUTOCOMMIT_OFF:
Not automatically committed.
Set timeout value to prevent blocking that may occur in select() or poll() in an unstable network
Server port number (32-bit Integer)
32-bit value that sets the transaction isolation level for the current connection referred to by dbc.
SQLINTEGER value corresponding to the waiting time
(in seconds) for logging in before the data is returned to an application. The default depends on the driver. If
ValuePtr is 0, timeout will be disabled and connection attempt will be permanently awaited.
SQL_CD_TRUE Disconnected status SQL_CD_FALSE:
Connected status
Diagnosis
SQLSTATE
08S01
HYC00
Description
Communication channel error
Optional feature not implemented.
Comments
Communication channel failure before the function processing is completed between the ODBC driver and the database
Not supported by the driver specified in the argument Attribute.
ODBC Users’ Manual 92
SQLGetConnectAttr
Related Functions
SQLSetConnectAttr
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_dead.cpp
rc = SQLGetConnectAttr( dbc, SQL_ATTR_CONNECTION_DEAD, &isDead, 0, NULL );
… if ( rc == SQL_SUCCESS )
{
if ( isDead == SQL_CD_TRUE )
{
printf("The Connection has been lost.\n");
}
else
{
printf("The Connection is active.\n");
}
}
93 ODBC Functions
SQLGetData
SQLGetData
SQLGetData retrieves data for a specified column in the result set. It can be called multiple times to retrieve variable-length data in parts
SQLGetData () will be called for each column, and SQLFetch () will be called to retrieve one or more rows:
Syntax
SQLRETURN SQLGetData (
SQLHSTMT stmt,
SQLSMALLINT col,
SQLSMALLINT cType,
SQLPOINTERV alue,
SQLINTEGERV alueMax,
SQLINTEGER *pcbValue );
Arguments
Data Type
SQLHSTMT
SQLSMALLINT
SQLSMALLINT
SQLPOINTER
SQLINTEGER
Argument stmt col cType
In/Out
Input
Input
Input
Value
ValueMax
Output
Input
Description
Statement handle
Column sequence. Starting with 1
The type identifier of C data type in the *
Value buffer
Pointer of the buffer to return the data
Length of *Value buffer, in bytesWhen returning the character data to the
*Value, the *Value argument must include a NULL-terminatior. Otherwise, the ODBC cuts out the data. In case of a fixed length data such as integer, date structure, etc, are returned, the ODBC will ignore ValueMax. Therefore, a sufficient buffer size must be allocated. Otherwise, the ODBC passes through the end of the buffer and saves the data.If ValueMaxis smaller than 0, SQLGetData () will return
SQLSTATE HY090.If the Value is not set as a NULL pointer, ValueMax will be ignored by the ODBC.
ODBC Users’ Manual 94
Data Type
SQLINTEGER *
Argument pcbValue
In/Out
Output
SQLGetData
Description
Pointer of buffer that will return the length or indicator variableIf this variable is a NULL pointer, no length or indicator will be returned. When the fetched data is
NULL, this variable will return the error
(SQL_SUCCESS_WITH_INFO). SQLGetData
() will return the following to the length/ indicator buffer:SQL_NULL_DATA
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_NO_DATA_FOUND
SQL_ERROR
SQL_INVALID_HANDLE
Description
SQLGetData () returns the data of a specified column. SQLGetData () can be called only after one or more rows are fetched by SQLFetch (). Although there are some exceptions, the user can bind a several columns in the row and call SQLGetData () for the other columns.
Using SQLGetData ()
This function returns only the data of unbound columnsWhen SQLGetData () is called, the col value must be higher than or the equal to previously called column. In other words, the data must be searched in ascending order.
Retrieving Data with SQLGetData ()
To return the data to a specified column, SQLGetData () must execute the following series of procedures.
Returns SQL_NO_DATA if it has already returned all of the data for the column.
If the data is NULL, SQL_NULL_DATA will be set in *pcbValue.
If the data for the corresponding column is not NULL, SQLGetData () will proceed to the next phase.
If the data is converted into flexible data types such as character type or binary type, SQLGetData () will check whether the data length exceeds ValueMax. If the length of the data including NULL-terminatior exceeds ValueMax, SQLGetData () will cut the data to ValueMax length with the NULL-terminatior length deducted. In this way, finish the data composed of NULL characters. If the binary
95 ODBC Functions
SQLGetData data length exceeds the data buffer length, SQLGetData () will cut the data according to the Value-
Max.
If the data buffer is small and does not include the NULL-terminatior, SQLGetData () will return
SQL_SUCCESS_WITH_INFO.
SQLGetData () does not cut the data converted into the fixed-length data type. SQLGetData () always assumes that the *Value length is the size of the data type.
Places the converted (or cut) data in *Value.
Places the data length in *pcbValue. If *pcbValue is a NULL pointer, SQLGetData () will not return the length.
If the data is cut during conversion although there is no loss of significant information (for example,
1.234 is converted into 1) or if valueMax is too small (for example, character string "abcde" i placed in the 4-byte buffer), SQLGetData () will return SQLSTATE 01004 (with the data cut) and
SQL_SUCCESS_WITH_INFO.
If SQLGetData () does not return SQL_SUCCESS or SQL_SUCCESS_WITH_INFO, contents of the bound data buffer and the length/indicator buffer will not be defined.
Diagnosis
SQLSTATE
01004
Description
String data, right truncated
07009 Invalid descriptor index
HY000
HY010
General error
Continuous function error
HY090 Invalid string or buffer length
Related Functions
SQLBindCol
ODBC Users’ Manual 96
Comments
When the size of the value to be returned is higher than the size of the given buffer
The col value is 0. The col value is higher than the column value in the result set. An application has already called SLQGetData () for the current row. The number of columns in the current calling is smaller than the number of columns in the previous calling.
The given stmt cannot execute this function. This function can be called after the result set creation phase.
valueMax is smaller than 0.
SQLExecDirect
SQLExecute
SQLFetch
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_info1.cpp
See example of SQLGetTypeInfo()
SQLGetData
97 ODBC Functions
SQLGetDescField
SQLGetDescField
This retrieves an attribute of descriptor. Unicode SQLGetDescFieldW() supports same execution as SQLGetDescField().
Syntax
SQLRETURN SQLGetDescField (
SQLHDESC desc,
SQLSMALLINT recNumber,
SQLSMALLINT fieldIdentifier,
SQLPOINTER ValuePtr,
SQLINTEGER *bufferLength,
SQLINTEGER *stringLengthPtr);
Arguments
Data Type
SQLHDESC
SQLSMALLINT
SQLSMALLINT
SQLPOINTER
SQLINTEGER *
SQLINTEGER *
Argument desc recNumber fieldIdentifier In
In
In
In/Out
ValuePtr Out bufferLength In stringLength-
Ptr
Out
Description
Descriptor Handle
This starts from 1 of column number.
This specifies the attribute of column to retrieve.
Buffer pointer where attributes are saved
ValuePtr Size
Size speciified in ValuePtr
Return Value
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_NO_DATA
SQL_INVALID_HANDLE
SQL_ERROR
ODBC Users’ Manual 98
SQLGetDescField
Description
This retrieves one column information with descriptor handle.
Diagnostics
SQLSTATE
HY000
HY001
Description
General Error
Memory Allocation Error
HY010
01004
07009
Function Sequence Error
Cutted Resource
Invalid Descriptor Index
Related Function
SQLGetDescRec
SQLSetDescField
SQLSetDescRec
Comments
No error occurs explicitly.
This denotes to fail to allocate memory for handle.
The size of ValuePtr buffer is lesser than the size of returned data.
The value of recNumber is incorrect.
99 ODBC Functions
SQLGetDescRec
SQLGetDescRec
This retrieves multiple number of descriptor attributes. Unicode SQLGetDescRecW() supports same execution as SQLGetDescRec().
Syntax
SQLRETURN SQLGetDescRec (
SQLHDESC desc,
SQLSMALLINT recNumber,
SQLCHAR *name,
SQLSMALLINT bufferLength,
SQLSMALLINT *stringLength,
SQLSMALLINT *type,
SQLSMALLINT *subType,
SQLLEN *lengthPtr,
SQLSMALLINT *precision,
SQLSMALLINT *scale,
SQLSMALLINT *nullable);
Arguments
Data Type
SQLHDESC
SQLSMALLINT
SQLCHAR *
SQLSMALLINT
SQLSMALLINT *
SQLSMALLINT *
SQLSMALLINT *
SQLLEN *
SQLSMALLINT *
SQLSMALLINT *
SQLSMALLINT *
Argument desc recNumber
In
In name Out bufferLength In stringLength type subType lengthPtr
Out
Out
Out
Out precision scale nullable
Out
Out
Out
In/Out Description
Descriptor Handle
This starts from 1 of column number.
Pointer recieving column name
Size of name buffer
Size specified in name
Pointer recieving column type
Pointer recieving subtype of column
Pointer recieving column length
Pointer recieving column precision
Pointer recieving column scale
Pointer recieving whether to specify null in column
Return Value
SQL_SUCCESS
ODBC Users’ Manual 100
SQLGetDescRec
SQL_SUCCESS_WITH_INFO
SQL_NO_DATA
SQL_INVALID_HANDLE
SQL_ERROR
Description
You can retrieve several information of column with descriptor handle.
Diagnostics
SQLSTATE
HY000
HY001
Description
General Error
Memory Allocation Error
HY010
01004
07009
Function Sequence Error
Cutted Resource
Invalid Descriptor Index
Related Function
SQLBindCol
SQLBindParameter
SQLGetDescFiled
Comments
No error occurs explicitly.
This denotes to fail to allocate memory for handle.
The size of name buffer is lesser than that of retunred data.
The value of recNumber is incorrect.
101 ODBC Functions
SQLGetDiagField
SQLGetDiagField
SQLGetDiagField is Used to diagnose the result after an ODBC function is used.
SQLGetDiagFieldW() as a Unicode string supports same execution as SQLGetDiagField().
Syntax
SQLRETURN SQLGetDiagField(
SQLSMALLINT HandleType,
SQLHANDLE Handle,
SQLSMALLINT RecNumber,
SQLSMALLINT DiagIdentifier,
SQLPOINTER DiagInfoPtr,
SQLSMALLINT BufferLength,
SQLSMALLINT *StringLengthPtr)
Arguments
Data Type
SQLSMALLINT
Argument
HandleType
In/Out
Input
SQLHANDLE
SQLSMALLINT
SQLPOINTER
SQLINTEGER
Handle Input
DiagIdentifier Input
DiagInfoPtr
BufferLength
Output
Input
Description
A handle type to be assigned. It can be any of the followings:
SQL_HANDLE_ENV
SQL_HANDLE_DBC
SQL_HANDLE_STMT
If input HandleType is SQL_HANDLE_ENV,
InputHandle should be
SQL_NULL_HANDLE. If
SQL_HANDLE_DBC, it should be an environment handle. If SQL_HANDLE_STMT, it should be a connection handle.
A type to be diagnosed. For now,
SQL_DIAG_NUMBER is only supported.
A pointer to the buffer to which diagnostic information is returned.
If *DiagInfoPtr is the pointer of character string, this has the byte length of string or the value of SQL_NTS.If *DiagInfoPtr is the pointer of binary buffer, this has the binary length of data.If *DiagInfoPtr is the pointer with fixed-length data type, its value is ignored.
ODBC Users’ Manual 102
Data Type
SQLINTEGER*
Argument
StringLength-
Ptr
In/Out
Output
SQLGetDiagField
Description
This returns bytes (excluding the null-termination character) available to return in
*ValuePtr.
Result Value
An error message for each handle type.
Description
This function is used to diagnose the execution result for an error. It is used in the following case:
In ODBC functions, when SQL_ERROR or SQL_SUCCESS_WITH_INFO is returned, error and warning information is gathered. This function is used to determine the gathered information.
Any ODBC function can call this function for diagnosis after its execution. This function shows the most recently stored diagnosis information.
Currently, it works for the following handle types:
SQL_HANDLE_ENV
SQL_HANDLE_DBC
SQL_HANDLE_STMT
For an input Argument, if HandleType is SQL_HANDLE_ENV, InputHandle should be
SQL_NULL_HANDLE, or if SQL_HANDLE_DBC, it should be an environment handle, or if
SQL_HANDLE_STMT, it should be a connection handle. That is, a value should be set properly for each input handle.
Related Function
SQLError
103 ODBC Functions
SQLGetDiagRec
SQLGetDiagRec
You can use this when retrieving serveral attributes of diagnostic message after using ODBC function. Unicode SQLGetDiagRecW() supports same execution as SQLGetDiagRec().
Syntax
SQLRETURN SQLGetDiagRec (
SQLSMALLINT handleType,
SQLHANDLE handle,
SQLSMALLINT recNumber,
SQLCHAR *sqlstatus,
SQLINTEGER *nativeError,
SQLCHAR *messageText,
SQLSMALLINT bufferLength,
SQLSMALLINT *stringLength);
Argument
Data Type
SQLSMALLINT
SQLHANDLE
SQLSMALLINT
SQLCHAR *
SQLINTEGER *
SQLCHAR *
SQLSMALLINT
SQLSMALLINT
Argument handleType handle recNumber sqlstatus nativeError messageText
Out
Out bufferLength In stringLength Out
In
In
In
Out
In/Out Description
Handle Type
Handle
This starts from 1 of diagnostic message.
SQLSTATE
Unique Error Number
Buffer pointer recieving message
Size of message text
Size specified in message text
Return Value
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
ODBC Users’ Manual 104
Description
This retrieves several attributes of diagnostic message.
Related Function
SQLGetDiagField
SQLGetDiagRec
105 ODBC Functions
SQLGetEnvAttr
SQLGetEnvAttr
This retrieves attribute value of environment handle.
Syntax
SQLRETURN SQLGetEnvAttr (
SQLHENV env,
SQLINTEGER attribute,
SQLPOINTER value,
SQLINTEGER bufferLength,
SQLINTEGER *stringLength);
Argument
Data Type
SQLHENV
SQLINTEGER
SQLPOINTER
SQLINTEGER
SQLINTEGER *
Argument env attribute
In
In
In/Out value Out bufferLength In stringLength Out
Description
Environment Handle
This inserts attribute of envionment handle.
Buffer pointer where attributes are saved
Size of Attribute Value
Size specified in the value of attribute
Return Value
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_NO_DATA
SQL_INVALID_HANDLE
SQL_ERROR
Description
This retrieves attribute value of environment handle.
ODBC Users’ Manual 106
SQLGetEnvAttr
Diagnosis
SQLSTATE
HY000
HY001
Description
General Error
Memory Allocation Error
HY092
01004
HYC00
Invalid Attribute or Option
Cutted Resource
Unsupported Attribute Use
Related Function
SQLSetEnvAttr
Comments
No error occurs explicitly.
This denotes to fail to allocate memory for handle.
The value specified in attribute is not valid one supported by this driver.
The size of value buffer is lesser than the size of returned data.
The value specified in attribute is unsupported in driver.
107 ODBC Functions
SQLGetFunctions
SQLGetFunctions
This retrieves function list supported by ODBC driver.
Syntax
SQLRETURN SQLGetFunctions (
SQLHDBC dbc,
SQLUSMALLINT functionId,
SQLUSMALLINT *supported);
Argument
Data Type Argument
SQLHDBC
SQLUSMALLINT dbc functionId
SQLUSMALLINT * supported
In
In
Out
In/Out Description
Connection Handle
Function ID
Array pointer recieving the supported function list
Return Value
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
This retrieves function list supported by ODBC driver. One list can be retrieved at a time or all lists can be retrieved with SQL_API_ALL_FUNCTIONS and SQL_API_ODBC3_ALL_FUNCTIONS.You should pinpoint the location suited for ID value of function in argumnet Supported. If this function is supported, SQL_TRUE is returned. Otherwise, SQL_FALSE is returned.If using
SQL_API_ALL_FUNCTIONS, you shoould apply pointer of array whose size is 100 to Supported pointer and pinpoint the location suited for the value of function ID. If using
SQL_API_ODBC3_ALL_FUNCTIONS, you should apply pointer of array whose size is the value of
SQL_API_ODBC3_ALL_FUNCTIONS_SIZE to Supported pointer and you can check supported functions by using SQL_FUNC_EXISTS.
ODBC Users’ Manual 108
SQLGetFunctions
Diagnostics
SQLSTATE
HY000
HY001
Description
General Error
Memory Allocation Error
HY010 Function Sequence Error
Related Function
SQLGetInfo
Comments
No error occurs explicitly.
This denotes to fail to allocate memory for handle.
109 ODBC Functions
SQLGetInfo
SQLGetInfo
This indicates to return general information of DBMS accessed to application.
SQLGetInfoW() as a Unicode string supports same execution as SQLGetInfo().
Syntax
SQLRETURN SQLGetInfo(
SQLHANDLE ConnectionHandle,
SQLUSMALLINT InfoType,
SQLPOINTER InfoValuePtr,
SQLSMALLINT BufferLength,
SQLSMALLINT *StringLengthPtr );
Arguments
Data Type
SQLHANDLE
SQLUSMALLINT
SQLPOINTER
Arguments
Connection-
Handle
InfoType
InfoValuePtr
In
In
In/Out
SQLSMALLINT
SQLSMALLINT *
BufferLength In
StringLength-
Ptr
Out
Description
Database Connection Handle
Data Type which you want to search to data types of buffer pointer which makes data returned16 bit integer value32 bit integer value32 bit binary value32 bit maskNull Determination
Character String
The byte size of buffer which InfoValuePtr indicates
The byte length of result values which
InfoValuePtr indicates
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE
ODBC Users’ Manual 110
SQLGetInfo
Description
SQLGetInfo() is used to get general information of DBMS. You can get relevant information of each type according to InfoType with this function, and Altibase follows the standard of ODBC.
Diagnosis
SQLSTATE
01004
Description
String data, right truncated
08003
08S01
HY000
HY090
HY096
Comments
The size of returned values is bigger than that of the given buffer.
Communication channel error(Data
Sending/Recieving Failure)
Communication channel error before the function processing is completed between the ODBC and the database.
General Error
Invalid Arguments used
Out of InfoType Range
One value among name length arguments must be under 0 or not be equal to SQL_NTS.
The values specified in InfoType are invalid in the version which ODBC provides.
111 ODBC Functions
SQLGetPlan
SQLGetPlan
This is nonstandard function returning execution information.
Syntax
SQLRETURN SQLGetPlan (
SQLHSTMT stmt,
SQLCHAR **aPlan);
Arguments
Data Type
SQLHSTMT
SQLCHAR**
Argument stmt aPlan
In
Out
In/Out Description
Input Statement Handle
Pointer to store output execution information
Returned Values
SQL_SUCCESS
SQL_ERROR
Description
SQLGetPlan is nonstandard function, but you can use it when retrieving information of execution plan. At this time, you shouldn't modify information returned by aPlan.
Related Function
SQLSetConnectAttr
Example
< See : $ALTIBASE_HOME/sample/SQLCLI/demo_plan.cpp > if( SQLSetConnectAttr( dbc, ALTIBASE_EXPLAIN_PLAN,
(SQLPOINTER) 1, 0) != SQL_SUCCESS)
.
.
.
if ( SQLGetPlan(stmt, (SQLCHAR**)&plan) != SQL_SUCCESS )
ODBC Users’ Manual 112
SQLGetStmtAttr
SQLGetStmtAttr
SQLGetStmtAttr retrieves the attributes related to the current statement handle .
SQLGetStmtAttrW() as a Unicode string supports same execution as SQLGetStmtAttr().
Syntax
SQLRETURN SQLGetStmtAttr (
SQLHSTMT stmt,
SQLINTEGER Attribute,
SQLPOINTER param,
SQLINTEGER StringLength
SQLINTEGER *StringLengthPtr );
Arguments
Data Type
SQLHSTMT
SQLINTEGER
Argument stmt
Attribute
In/Out
Input
Input
SQLPOINTER
SQLINTEGER
SQLINTEGER * param
StringLength
StringLength-
Ptr
Output
Input
Output
Description
Statement handle
Attribute to set, Supported attributes
SQL_ATTR_MAX_ROWS,
SQL_ATTR_ROW_ARRAY_SIZE,
SQL_ATTR_ROW_BIND_TYPE,
SQL_ATTR_ROW_STATUS_PTR
ALTIBASE_STMT_ATTR_ATOMIC_ARRAY
Pointer of the value related to the attributeDepending on the Attribute, the param will be a 32-bit integer, the pointer of the Null-terminator, the binary pointer, or the value defined in the ODBC.If Attribute is the unique value of the ODBC, param is the integral number with a sign.
If the Attribute has been defined in the
ODBC and if the param indicates the character string or binary buffer, this argument must be the length of *param.
If the Attribute is defined in the ODBC and param is an integer, this Arguments will be ignored.
Returns the length (excluding the NULLterminatior) of the value returned to ValuePtr.
113 ODBC Functions
SQLGetStmtAttr
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE
Description
SQLGetStmtAttr () returns the attribute related to the statement handle. For the statement attribute or more information, see SQLSetStmtAttr ().
Diagnosis
SQLSTATE
HY090
HY092
Description
Invalid string or buffer length
Invalid attribute or option
HYC00 Option not implemented
Comments
StringLength is smaller than 0.
The value specified in the attribute argument is not supported by this driver.
The value specified in the attribute argument of ODBC is valid but not supported by this driver.
Related Functions
SQLGetConnectAttr
SQLSetConnectAttr
SQLSetStmtAttr
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_plan.cpp
SQLGetStmtAttr(stmt, SQL_ATTR_EXPLAIN_PLAN, plan, sizeof(plan), &plan_ind)
ODBC Users’ Manual 114
SQLGetTypeInfo
SQLGetTypeInfo
SQLGetTypeInfo returns information related to the data types that the database supports. The driver returns the information in the form of an SQL result set. The data type is used in the DDL statement.
Syntax
SQLRETURN SQLGetTypeInfo (
SQLHSTMT stmt,
SQLSMALLINT type );
Arguments
Data Type
SQLHSTMT
SQLSMALLINT
Argument stmt type
In/Out
Input
Input
Description
Statement handle
SQL data type
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
SQLGetTypeInfo () converts data type information that Altibase provides into the standard result set type. The current result set is sorted by TYPE_NAME in ascending orders to be returned.
Diagnosis
SQLSTATE
08S01
Description Comments
Communication channel error Communication channel failure before the function processing between the ODBC and the database is completed
115 ODBC Functions
SQLGetTypeInfo
SQLSTATE
HY000
HY001
Description
General error
Memory allocation error
Comments
Cannot allocate the requested memory for the ODBC to execute the function and complete execution.
Related Functions
SQLBindCol
SQLColAttribute
SQLFetch
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_info1.cpp
if (SQLGetTypeInfo(stmt, SQL_ALL_TYPES) != SQL_SUCCESS)
{
execute_err(dbc, stmt, "SQLGetTypeInfo");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} while ( (rc = SQLFetch(stmt)) != SQL_NO_DATA)
{
if ( rc == SQL_ERROR )
{
execute_err(dbc, stmt, "SQLGetTypeInfo:SQLFetch");
break;
}
SQLGetData(stmt, 1, SQL_C_CHAR, szTypeName, STR_LEN, &cbTypeName);
SQLGetData(stmt, 2, SQL_C_SSHORT, &DataType, 0, &cbDataType);
SQLGetData(stmt, 3, SQL_C_SLONG, &ColumnSize, 0, &cbColumnSize);
SQLGetData(stmt, 9, SQL_C_SSHORT, &Searchable, 0, NULL);
SQLGetData(stmt, 14, SQL_C_SSHORT, &MinScale, 0, &cbMinScale);
SQLGetData(stmt, 15, SQL_C_SSHORT, &MaxScale, 0, &cbMaxScale);
SQLGetData(stmt, 16, SQL_C_SSHORT, &SQLDataType, 0, &cbSQLDataType);
SQLGetData(stmt, 18, SQL_C_SLONG, &NumPrecRadix, 0, &cbNumPrecRadix);
printf("%-20s%10d%10d%10d\t",
szTypeName, DataType, ColumnSize, SQLDataType);
if ( Searchable == SQL_PRED_NONE )
{
printf("SQL_PRED_NONE\n");
}
else if ( Searchable == SQL_PRED_CHAR )
{
printf("SQL_PRED_CHAR\n");
}
else if ( Searchable == SQL_PRED_BASIC )
{
printf("SQL_PRED_BASIC\n");
}
ODBC Users’ Manual 116
else if ( Searchable == SQL_SEARCHABLE )
{
printf("SQL_SEARCHABLE\n");
}
}
SQLGetTypeInfo
117 ODBC Functions
SQLMoreResult
SQLMoreResult
SQLMoreResult returns whether there is more result.
Syntax
SQLRETURN SQLMoreResults (
SQLHSTMT stmt);
Arguments
Data Type
SQLHSTMT
Argument stmt
In/Out
Input
Description
Instruction Handle
Result Values
SQL_SUCCESS
SQL_NO_DATA_FOUND
Description
When a statement is fetched to obtain its result, the corresponding cursor is located at the first record of the result set. Depending on an application, when its result set is used, a further check is performed to see if there is more result left. If there are more result values left, SQL_SUCCESS is returned, and if not, SQL_NO_DATA_FOUND is returned.
If the result set is fetched, the cursor is located at the first result set. Depending on an application, when its result set is used, a further check is performed to see if there is more result left. If there are more result values left, SQL_SUCCESS is returned, and if not, SQL_NO_DATA_FOUND is returned.
Related Function
SQLFetch
ODBC Users’ Manual 118
SQLNativeSql
SQLNativeSql
This coverts SQL statements to statements supported by ODBC driver. Unicode SQLNativeSqlW() supports same execution as SQLNativeSql().
Syntax
SQLRETURN SQLNativeSql (
SQLHDBC dbc,
SQLCHAR *InstatementText,
SQLINTEGER textLength,
SQLCHAR *OutStstementText,
SQLINTEGER bufferLength,
SQLINTEGER textLength);
Argument
Data Type
SQLHDBC
SQLCHAR *
SQLINTEGER
SQLCHAR *
SQLINTEGER
SQLINTEGER
Argument dbc
Instatement-
Text textLength
In
In
OutStstementText
In
Out bufferLength In textLength Out
In/Out Description
Connection Handle
SQL Statements to Convert
Length of InstatementText
Buffer Pointer recieving the converted
SQL statements
Size of OutStstementText
Size specified in OutStstementText
Return Value
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
This converts SQL statements to statements supported by ODBC driver.
119 ODBC Functions
SQLNativeSql
Diagnosis
SQLSTATE
HY000
HY001
Description
General Error
Memory Allocation Error
01004 Cutted Source
Comments
No error occurs explicitly.
This denotes to fail to allocate memory for handle.
Buffer size of OutStstementText is lesser than the size of returned data.
Example
SQLNativeSql(dbc,
(SQLCHAR*)"INSERT INTO T1 VALUES( {d '1981-09-27'} )",
SQL_NTS,
outText,
100,
&outTextLen);
INSERT INTO T1 VALUES( TO_DATE('1981-09-27', 'YYYY-MM-DD')) is saved in outText.
ODBC Users’ Manual 120
SQLNumParams
SQLNumParams
SQLNumParams returns the number of parameters in an SQL statement.
Syntax
SQLRETURN SQLNumParams (
SQLHSTMT stmt,
SQLSMALLINT *parameterCounterPtr );
Arguments
Data Type
SQLHSTMT
SQLSMALLINT *
Argument stmt parameter-
CountPtr
In/Out
Input
Output
Description
Statement handle
Pointer of the number of the parameters
Return Values
SQL_SUCCESS
Description
This function can be called only after SQLPrepare () is called.
If the stmt does not include parameters, SQLNumParams () will set 0 in *parameterCountPtr.
Diagnosis
Comments SQLSTATE
HY000 General error
Description
Related Functions
SQLBindParameter
SQLDescribeParam
121 ODBC Functions
SQLNumParams
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_info2.cpp
SQLPrepare(hstmt, Statement, SQL_NTS);
// Check to see if there are any parameters. If so, process them.
SQLNumParams(hstmt, &NumParams); if (NumParams) {
// Allocate memory for three arrays. The first holds pointers to buffers in which
// each parameter value will be stored in character form. The second contains
the
// length of each buffer. The third contains the length/indicator value for each
// parameter.
PtrArray = (SQLPOINTER *) malloc(NumParams * sizeof(SQLPOINTER));
BufferLenArray = (SQLINTEGER *) malloc(NumParams * sizeof(SQLINTEGER));
LenOrIndArray = (SQLINTEGER *) malloc(NumParams * sizeof(SQLINTEGER));
for (i = 0; i < NumParams; i++) {
// Describe the parameter.
SQLDescribeParam(hstmt, i + 1, &DataType, &ParamSize, &DecimalDigits,
&Nullable);
// Call a helper function to allocate a buffer in which to store the parameter
// value in character form. The function determines the size of the buffer from
// the SQL data type and parameter size returned by SQLDescribeParam and returns
// a pointer to the buffer and the length of the buffer.
PtrArray[i] = (char*)malloc(ParamSize);
BufferLenArray[i] = SQL_NTS;
// Bind the memory to the parameter. Assume that we only have input parameters.
SQLBindParameter(hstmt, i + 1, SQL_PARAM_INOUT, SQL_C_CHAR, DataType, Param-
Size,
DecimalDigits, PtrArray[i], BufferLenArray[i],
&LenOrIndArray[i]);
// Prompt the user for the value of the parameter and store it in the memory
// allocated earlier. For simplicity, this function does not check the value
// against the information returned by SQLDescribeParam. Instead, the driver does
// this when a statement is executed.
strcpy((char*)PtrArray[i], "AAAAAAA");
BufferLenArray[i] = 7;
}
}
ODBC Users’ Manual 122
SQLNumResultCols
SQLNumResultCols
SQLNumResultCols returns the number of columns in a result set.
Syntax
SQLRETURN SQLNumResultCols (
SQLHSTMT stmt,
SQLSMALLINT *col );
Arguments
Data Type
SQLHSTMT
SQLSMALLINT *
Argument stmt col
In/Out
Input
Output
Description
Statement handle
Pointer to save the number of columns in a result set.
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
If the commands related to stmt do not return columns, SQLNumResultCols () will set 0 in *col.
This function can be called only after SQLPrepare () or SQLExecDirect () is called. After this function is called, SQLDescribeCol (), SQLColAttribute (), SQLBindCol () or SQLGetData () can be called.
When the command is in ready, executed, or defined status, SQLNumResultCols () can be successfully called.
123 ODBC Functions
SQLNumResultCols
Diagnosis
SQLSTATE
08S01
Description
Communication channel error
Comments
Communication channel failure before the function processing is completed between the ODBC and the database
HY000 General error
If SQLNumResultCols () is called after SQLPrepare () and before SQLExecute (), no SQLSTATE returned by these two functions can be returned.
Related Functions
SQLBindCol
SQLColAttribute
SQLDescribeCol
SQLExecDirect
SQLExecute
SQLFetch
SQLGetData
SQLPrepare
SQLSetStmtAttr
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_ex1.cpp
sprintf(query,"SELECT * FROM DEMO_EX1"); if (SQLExecDirect(stmt,query, SQL_NTS) != SQL_SUCCESS)
{
execute_err(dbc, stmt, query);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
SQLNumResultCols(stmt, &columnCount);
ODBC Users’ Manual 124
SQLParamData
SQLParamData
You can use this when inserting data while running command.
Syntax
SQLRETURN SQLParamData (
SQLHSTMT stmt,
SQLPOINTER *value);
Argument
Data Type
SQLHSTMT
SQLPOINTER *
Argument stmt value
In
Out
In/Out Description
Command Handle
Pointer to save address specified in SQL-
BindParameter
Return Value
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_NEED_DATA
SQL_NO_DATA
SQL_INVALID_HANDLE
SQL_ERROR
Description
You can use this with SQLPutData when inserting data while running command.
Diagnosis
SQLSTATE
HY000 General Error
Description
125
Comments
No error occurs explicitly
ODBC Functions
SQLParamData
SQLSTATE
HY001
Description
Memory Allocation Error
HY010 Continuous Function Error
Related Function
SQLBindParameter
SQLExecDirect
SQLExecute
SQLPutData
Comments
This denotes to fail to allocate memory for handle.
ODBC Users’ Manual 126
SQLPrepare
SQLPrepare
This prepares an SQL string for execution. SQLPrepareW() as a Unicode string supports same execution as SQLPrepare().
Syntax
SQLRETURN SQLPrepare (
SQLHSTMT stmt,
SQLCHAR *sql,
SQLSMALLINT sqlLength );
Arguments
Data Type
SQLHSTMT
SQLCHAR *
SQLSMALLINT
Argument stmt sql sqlLength
In/Out
Input
Input
Input
Description
Statement handle
SQL text string column
The character number of *sql length
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
An application calls SQLPrepare () to send an SQL statement to the database. The application may include more than one parameter markers (?) in the SQL statement. To include the parameter marker, an application inserts the parameter marker in the SQL character string at a proper position.
Once the statement is ready, an application calls the function. To refer to the statement, use the statement handle. The statements related to the statement handle can be executed again when an application calls SQLFreeStmt () using SQL_DROP option to release the statement or when the statement handle is used again to call SQLPrepare (), SQLExecDirect (), or catalog function such like SQL-
Columns (), SQLTables (). Once an application prepares the statement, an application an request information about the result set format. Calling SQLDescribeCol () after SQLPrepare () may not be as effective as calling it after SQLExecute () or SQLExecDirect ().
The ODBC data type will be inspected when the command is executed (in case not all parameters
127 ODBC Functions
SQLPrepare are bound.) For maximum inter-operation, an application must unbound all parameters applied to the previous SQL statement before the same command prepares a new SQL statement. This prevents errors that occur due to pervious parameters applied to new information.
Diagnosis
SQLSTATE
08003
08S01
HY000
HY001
HY009
Description
Communication channel error
Comments
When stmt is not connected or the connection is released
Communication channel failure before the function processing is completed between the ODBC and the database
General error
Memory allocation error
Use an invalid pointer (null pointer)
Cannot allocate the requested memory for the ODBC to execute the function and complete execution.
sql is a NULL pointer
Related Functions
SQLAllocHandle
SQLBindCol
SQLBindParameter
SQLEndTran
SQLExecDirect
SQLExecute
SQLRowCount
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_ex2.cpp
sprintf(query,"INSERT INTO DEMO_EX2 VALUES( ?, ?, ?, ?, ?, ? )");
/* Prepare for a statement and bind the variable. */ if (SQLPrepare(stmt, query, SQL_NTS) != SQL_SUCCESS)
{
execute_err(dbc, stmt, query);
SQLFreeStmt(stmt, SQL_DROP);
ODBC Users’ Manual 128
return SQL_ERROR;
}
SQLPrepare
129 ODBC Functions
SQLPrimaryKeys
SQLPrimaryKeys
SQLPrimaryKeys returns the column names that make up the primary key for a table. The driver returns the information as a result set. This function does not support returning primary keys from multiple tables in a single call.
SQLPrimarykeysW() as a Unicode string supports same execution as SQLPrimarykey().
Syntax
SQLRETURN SQLPrimaryKeys (
SQLHSTMT stmt,
SQLCHAR *cName,
SQLSMALLINT cNameLength,
SQLCHAR *sName,
SQLSMALLINT sNameLength,
SQLCHAR *tName,
SQLSMALLINT tNameLength );
Arguments
Data Type
SQLHSTMT
SQLCHAR *
SQLSMALLINT
SQLCHAR *
SQLSMALLINT
SQLCHAR *
Argument In/Out stmt cName
Input
Input cNameLength Input sName Input sNameLength Input tName Input
SQLSMALLINT tNameLength Input
Description
Statement handle
Catalog Name
The character number of *cName
Schema Name
Length of character string of *sName
The table name. Cannot be a NULL pointer. tName cannot contain a string search pattern.
Length of character *tName
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
ODBC Users’ Manual 130
SQLPrimaryKeys
Description
SQLPrimaryKeys () returns the results in the format of standard result set which is sorted in order byTABLE_CAT, TABLE_SCHEM, TABLE_NAME, and KEY_SEQ.
The search type cannot be used to define the schema-defining arguments or the table name.
In many cases, calling of SQLPrimaryKeys () is mapped on the search that is complex and cost a lot.
Therefore, the stored result set must be used instead of repeating the calling.
Columns Returned by SQLPrimaryKeys ()
The following table lists the columns of the result set.
3
4
1
2
5
No.
Name Data Type
TABLE_CAT
TABLE_SCHEM
VARCHAR
VARCHAR
TABLE_NAME VARCHAR (NOT NULL)
COLUMN_NAME VARCHAR (NOT NULL)
KEY_SEQ SMALLINT (NOT NULL)
6 PK_NAME VARCHAR
Description
Null will be always returned.
Primary key table schema name
Primary key table name
First primary key column name
Column orders of the first primary key starting with 1
First primary key name
Diagnosis
SQLSTATE
08S01
HY000
HY009
Description Comments
Communication channel error Communication channel failure before the function processing is completed between the ODBC and the database
General error
Invalid Arguments used (null pointer).
tNameTransfer NULL pointer
Related Functions
SQLBindCol
SQLFetch
131 ODBC Functions
SQLPrimaryKeys
SQLStatistics
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_meta3.cpp
if (SQLPrimaryKeys(stmt,
NULL, 0,
NULL, 0,
(char*)"DEMO_META3", SQL_NTS) != SQL_SUCCESS)
{
execute_err(dbc, stmt, "SQLPrimaryKeys");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
SQLBindCol(stmt, 1, SQL_C_CHAR, szCatalog, STR_LEN,&cbCatalog);
SQLBindCol(stmt, 2, SQL_C_CHAR, szSchema, STR_LEN, &cbSchema);
SQLBindCol(stmt, 3, SQL_C_CHAR, szTableName, STR_LEN,&cbTableName);
SQLBindCol(stmt, 4, SQL_C_CHAR, szColumnName, STR_LEN, &cbColumnName);
SQLBindCol(stmt, 5, SQL_C_SSHORT, &KeySeq, 0, &cbKeySeq);
SQLBindCol(stmt, 6, SQL_C_CHAR, szPkName, STR_LEN, &cbPkName); while ( (rc = SQLFetch(stmt)) != SQL_NO_DATA)
{
if ( rc == SQL_ERROR )
{
execute_err(dbc, stmt, "SQLPrimaryKeys:SQLFetch");
break;
}
printf("%-20s%-20s%-3d%-20s\n", szTableName,
szColumnName, KeySeq, szPkName);
}
ODBC Users’ Manual 132
SQLProcedureColumns
SQLProcedureColumns
SQLProcedureColumns returns the list of input and output parameters, as well as the columns that make up the result set for the specified procedures. The driver returns the information as a result set on the specified statement.
SQLProcedureColumnsW() as a Unicode string supports same execution as
SQLProcedureColumns().
Syntax
SQLRETURN SQLProcedureColumns (
SQLHSTMT stmt,
SQLCHAR *cName,
SQLSMALLINT cNameLength,
SQLCHAR *sName,
SQLSMALLINT sNameLength,
SQLCHAR *pName,
SQLSMALLINT pNameLength,
SQLCHAR *colName,
SQLSMALLINT colNameLength );
Arguments
Data Type
SQLHSTMT
SQLCHAR *
SQLSMALLINT
SQLCHAR *
SQLSMALLINT
SQLCHAR *
Argument In/Out stmt cName
Input
Input cNameLength Input sName Input sNameLength Input pName Input
SQLSMALLINT
SQLCHAR *
SQLSMALLINT pNameLength Input colName colName-
Length
Input
Input
Description
Statement handle
Procedure Catalog Name
The character number of *cName
Procedure Schema Name
Length of character string of *sName
Procedure name. Cannot be a NULL pointer. pName must not include the character string search pattern.
Character string of *pName
Column Name
Character string of *colName
Return Values
SQL_SUCCESS
133 ODBC Functions
SQLProcedureColumns
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
This function is used before a statement is executed to retrieve the procedure parameters and the columns that form the result sets returned by the procedure.
SQLProcedureColumns () returns the results in the standard result set sorted in order by
PROCEDURE_CAT, PROCEDURE_SCHEM, PROCEDURE_NAME, and COLUMN_TYPE. The column names will be returned for each procedure in the following order: Name of returned value, each parameter names to call the procedures (or calling order), and column names of the result set returned by the procedure (or column order.)
An application must bind the unique columns which contains the ODBC driver information to the last data of the result set.
Columns Returned by SQLProcedureColumns ()
Name
PROCEDURE_CAT
PROCEDURE _SCHEM
PROCEDURE _NAME
COLUMN_NAME
COLUMN_TYPE
DATA_TYPE
TYPE_NAME
1
2
No.
Data Type
VARCHAR
VARCHAR
3
Description
Returns NULL always
Procedure schema name; NULL if not applicable to the database
Procedure name
4
VARCHAR
(NOT NULL)
VARCHAR
(NOT NULL)
5
6
SMALLINT
(NOT NULL)
Procedure column name. The driver returns an empty string for a procedure column that does not have a name.
Defines the procedure column as a parameter or a result set column:.SQL_PARAM_INOUT: The procedure column is the input parameter.SQL_PARAM_INOUT_OUTPUT: The procedure column is the input/output parameters.SQL_PARAM_OUTPUT: The procedure column is the output parameter.
SQL data type
7
SMALLINT
(NOT NULL)
VARCHAR
(NOT NULL)
Name of the data type corresponding to the database
ODBC Users’ Manual 134
SQLProcedureColumns
Name
COLUMN_SIZE
BUFFER_LENGTH
DECIMAL_DIGITS
NUM_PREC_RADIX
NULLABLE
REMARKS
COLUMN_DEF
SQL_DATA_TYPE
SQL_DATETIME_SUB
CHAR_OCTET_LENGTH
ORDINAL_POSITION
IS_NULLABLE
8
No.
9
10
11
12
13
14
15
16
17
18
19
Data Type Description
INTEGER
INTEGER
SMALLINT
SMALLINT
SMALLINT
(NOT NULL)
VARCHAR
VARCHAR
Column Size. NULL will be returned when the column size is not proper.
The maximum byte storing the data
The NULL will return the data type that cannot apply the decimal points of the string and the decimal points.
In case of the numeric data type 10: For
COLUMN_SIZE and DECIMAL_DIGIT, decimal digits allowable in this string is be given. For example, DECIMAL(12,5) string can return NUM_PREC_RADIX 10,
COLUMN_SIZE 12, and DECIMAL_DIGITS
5.
SQL_NO_NullS when the procedure column does not allow NULL value, or
SQL_Nullable when NULL is allowed.
Description of the procedure column
The default value of the column. If NULL was specified as the default value, this column is the word NULL, not enclosed in quotation marks. If the default value cannot be represented without truncation, this column contains TRUNCATED, with no enclosing single quotation marks. If no default value was specified, this column is NULL.The value of COLUMN_DEF can be used in generating a new column definition, except when it contains the value TRUNCATED
SQL data type SMALLINT
(NOT NULL)
SMALLINT
INTEGER
INTEGER (NOT
NULL)
VARCHAR
The subtype code for datetime and interval data types. For other data types, this column returns a NULL.
Maximum digits of the character string or binary data-type string.
Location of the order of the parameters in the procedure definition (starting with 1)
NO : When the string does not contain the NULL:YES : When the string contain the NULL:
135 ODBC Functions
SQLProcedureColumns
Diagnosis
SQLSTATE
HY000
HY009
Description Comments
General error
Invalid Arguments used (null pointer).
CName is a NULL pointer
Related Functions
SQLBindCol
SQLFetch
SQLProcedures
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_meta6.cpp
if (SQLProcedureColumns(stmt,
NULL, 0,
NULL, 0,
"DEMO_META6_PROC", SQL_NTS,
NULL, 0) != SQL_SUCCESS)
{
execute_err(dbc, stmt, "SQLProcedureColumns");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
SQLBindCol(stmt, 1, SQL_C_CHAR, szCatalog, STR_LEN,&cbCatalog);
SQLBindCol(stmt, 2, SQL_C_CHAR, szSchema, STR_LEN, &cbSchema);
SQLBindCol(stmt, 3, SQL_C_CHAR, szProcName, STR_LEN,&cbProcName);
SQLBindCol(stmt, 4, SQL_C_CHAR, szColumnName, STR_LEN, &cbColumnName);
SQLBindCol(stmt, 5, SQL_C_SSHORT, &ColumnType, 0, &cbColumnType);
SQLBindCol(stmt, 7, SQL_C_CHAR, szTypeName, STR_LEN, &cbTypeName);
SQLBindCol(stmt, 8, SQL_C_SLONG, &ColumnSize, 0, &cbColumnSize);
SQLBindCol(stmt, 10, SQL_C_SSHORT, &DecimalDigits, 0, &cbDecimalDigits);
SQLBindCol(stmt, 11, SQL_C_SSHORT, &NumPrecRadix, 0, &cbNumPrecRadix);
SQLBindCol(stmt, 18, SQL_C_SLONG, &OrdinalPosition, 0, &cbOrdinalPosition);
ODBC Users’ Manual 136
SQLProcedures
SQLProcedures
SQLProcedures returns the list of procedure names stored in a specific database. Procedure is a generic term used to describe an executable object, or a named entity that can be invoked using input and output parameters..
SQLProceduresW() as a Unicode string supports same execution as SQLProcedures().
Syntax
SQLRETURN SQLProcedures (
SQLHSTMT stmt,
SQLCHAR *cName,
SQLSMALLINT cNameLength,
SQLCHAR *sName ,
SQLSMALLINT sNameLength,
SQLCHAR *pName,
SQLSMALLINT pNameLength );
Arguments
Data Type
SQLHSTMT
SQLCHAR *
SQLSMALLINT
SQLCHAR *
SQLSMALLINT
SQLCHAR *
Argument In/Out stmt cName
Input
Input cNameLength Input sName Input sNameLength Input pName Input
SQLSMALLINT pNameLength Input
Description
Statement handle
Procedure Catalog Name
The character number of *cName
Procedure Schema Name
Length of character string of *sName
Procedure name. Cannot be a NULL pointer. pName must not contain the string search-patterns..
Character string of *pName
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
137 ODBC Functions
SQLProcedures
Description
SQLProcedures () displays the list of all procedures in the required range. A user may have or have not a privilege to use and execute these procedures.
SQLProcedures () returns the results in the format of the standard result set format sorted in order by
PROCEDURE_CAT, PROCEDURE_SCHEM, and PROCEDURE_NAME.
Note SQLProcedures () may not return all procedures. An application can use the valid procedures whether the procedure is returned by SQLProcedures () or not.
The Column Returned by SQLProcedures ()
Name
PROCEDURE_CAT
PROCEDURE _SCHEM
PROCEDURE _NAME
NUM_INOUT_PARAMS
NUM_OUTPUT_PARAMS
NUM_RESULT_SETS
REMARKS
PROCEDURE_TYPE
1
No.
Data Type
VARCHAR
2
3
VARCHAR
Description
Procedure catalog identifier; NULL if not applicable to the database..
Procedure schema identifier; NULL if not applicable to the database
Procedure identifier
4
5
6
7
8
VARCHAR
(NOT NULL)
N/A
N/A
N/A
VARCHAR
SMALLINT
Reserved for future use. An application must not apply any returned data to this result string.
Reserved for future use. An application must not apply any returned data to this result string.
Reserved for future use. An application must not apply any returned data to this string.
Procedure description
Definition of the procedure typeSQL_PT_UNKNOWN: It cannot be determined whether the procedure returns a value..SQL_PT_PROCEDURE:
The returned object is a procedure; that is, it does not have a return value..SQL_PT_FUNCTION: The returned object is a function; that is, it has a return value.
ODBC Users’ Manual 138
SQLProcedures
Diagnosis
SQLSTATE
08S01
HY000
HY009
Description Comments
Communication channel error Communication channel failure before the function processing is completed between the ODBC and the database
General error
Invalid Arguments used (null pointer).
CName is a NULL pointer sNme, pName are NULL pointer
Related Functions
SQLBindCol
SQLFetch
SQLProcedureColumns
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_meta5.cpp
if (SQLProcedures(stmt,
NULL, 0,
NULL, 0,
NULL, 0) != SQL_SUCCESS)
{
execute_err(dbc, stmt, "SQLProcedures");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
139 ODBC Functions
SQLPutData
SQLPutData
You can use this when inserting data while running command.
Syntax
SQLRETURN SQLPutData (
SQLHSTMT stmt,
SQLPOINTER data,
SQLLEN strLength);
Argument
Data Type
SQLHSTMT
SQLPOINTER
SQLLEN
Argument stmt data strLength
In
In
In
In/Out Description
Command Handle
Pointer of Data Buffer
Data Size
Return Value
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
You can use this with SQLParamData when inserting data while running command.
Diagnosis
SQLSTATE
HY000
HY001
Description
General Error
Memory Allocation Error
ODBC Users’ Manual 140
Comments
No error occurs explicitly.
This denotes to fail to allocate memory for handle.
SQLSTATE
HY010
Description
Continuous Function Error
Related Function
SQLBindParameter
SQLExecDirect
SQLExecute
SQLParamData
Comments
SQLPutData
141 ODBC Functions
SQLRowCount
SQLRowCount
SQLRowCount returns the number of rows affected by an UPDATE, DELETE,or INSERT statement.
Syntax
SQLRETURN SQLRowCount (
SQLHSTMT stmt,
SQLINTEGER *row );
Arguments
Data Type
SQLHSTMT
SQLINTEGER *
Argument stmt row
In/Out
Input
Output
Description
Statement handle
Pointer to save the number of row
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
If the most recent statement referred to by the input statement handle is not UPDATE,DELETE, or
INSERT statement or if it is not successfully executed, this function returns *row as -1.
However, if no row was affected after UPDATE, DELETE, or INSERT statement or if SELECT statement is submitted,it returns *row as 0.
The rows in the tables affected by the SQL statement such as cascading delete operationare not included.
Before this function is called, SQLExecute () or SQLExecDirect () must be called.
ODBC Users’ Manual 142
Diagnosis
SQLSTATE
HY000 General error
Description
Related Functions
SQLExecDirect
SQLExecute
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_exa5.cpp
if (SQLExecute(stmt) != SQL_SUCCESS)
{
execute_err(dbc, stmt, query);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
SQLRowCount(stmt, &row_count);
Comments
SQLRowCount
143 ODBC Functions
SQLSetConnectAttr
SQLSetConnectAttr
SQLSetConnectAttr() sets attributes that govern aspects of connections.
SQLSetConnectAttrW() as a Unicode string supports same execution as SQLSetConnectAttr().
Syntax
SQLRETURN SQLSetConnectAttr (
SQLHDBC dbc,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER StringLength );
Arguments
Data Type
SQLHDBC
SQLINTEGER
SQLPOINTER
Argument dbc
Attribute
ValuePtr
In/Out
Input
Input
Input
SQLINTEGER StringLength Input
Description
Connection Handle
Attribute to set
Pointer of value contaied attribute.Depending on the Attribute value, the ValuePtr will be either a 32-bit unsigned integer or a pointer indicating the Null-terminator string.
SQL_ATTR_AUTOCOMMIT
SQL_ATTR_CONNECTION_TIMEOUT
SQL_ATTR_PORT
SQL_ATTR_TXN_ISOLATION
ALTIBASE_APP_INFO
ALTIBASE_DATE_FORMAT
When ValuePtr is the character string,
StringLengt is the length of the character string or SQL_NTS. If ValuePtr is 32-bit integer, this argument is ignored.
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
ODBC Users’ Manual 144
SQLSetConnectAttr
Description
An application can call SQLSetConnectAttr () at any point whether the connection is allocated or released. All connections successfully set by an application and statement attribute are stored until
SQLFreeHandle () is called in the current connection.
Connection Attribute
Attribute
SQL_ATTR_AUTOCOMMIT
SQL_ATTR_CONNECTION_TIMEOUT
SQL_ATTR_PORT
SQL_ATTR_TXN_ISOLATION
ALTIBASE_APP_INFO
ALTIBASE_DATE_FORMAT
Contents
32-bit value to set the commit mode.
SQL_AUTOCOMMIT_ON: Each SQL statement is automatically committed
SQL_AUTOCOMMIT_OFF: Not automatically committed.
Set timeout value to prevent blocking that may occur in select() or poll() in an unstable network
Server port setting (32-bit Integer)
32-bit value that sets the transaction isolation level for the current connection referred to by dbc.
Specify an identifier for an ODBC client to obtain more detailed information on the user's session.
Sets the date format. Supports YYYY/MM/DD HH:MI:SS as the default.
Diagnosis
SQLSTATE
08S01
Description
Communication channel error
Comments
Communication channel failure before the function processing is completed between the ODBC and the database
HY000 General error
In case of the statement attribute, SQLSetConnectAttr () can return any SQL state returned by SQL-
SetStmtAttr ().
Related Functions
SQLAllocHandle
145 ODBC Functions
SQLSetConnectAttr
Example
< See: $ALTIBASE_HOME/sample/SQLCLI/demo_tran1.cpp > if (SQLSetConnectAttr(dbc, SQL_ATTR_AUTOCOMMIT,
(void*)SQL_AUTOCOMMIT_OFF, 0) != SQL_SUCCESS)
{
execute_err(dbc, SQL_NULL_HSTMT, "Autocommit OFF");
return SQL_ERROR;
}
ODBC Users’ Manual 146
SQLSetDescField
SQLSetDescField
This specifies an attribute of descriptor. Unicode SQLSetDescFieldW() supports same execution as
SQLSetDescField().
Syntax
SQLRETURN SQLSetDescField (
SQLHDESC desc,
SQLSMALLINT recNumber,
SQLSMALLINT fieldIdentifier,
SQLPOINTER value,
SQLINTEGER bufferLength);
Argument
Data Type
SQLHDESC
SQLSMALLINT
SQLSMALLINT
SQLPOINTER
SQLINTEGER
Argument desc renNumber fieldIdentifier In
In
In
In/Out value In bufferLength In
Description
Descriptor Handle
This starts from 1 of column number.
This specifies the attribute of column to retrieve.
Buffer pointer specifying attributes
Value size
Return Value
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
This specifies an attribute of descriptor.
147 ODBC Functions
SQLSetDescField
Diagnosis
SQLSTATE
HY000
HY001
Description
General Error
Memory Allocation Error
HY010
07009
Order Error of Calling Function
Invalid Descriptor Index
Related Function
SQLBindCol
SQLBindParameter
SQLGetDescField
SQLGetDescRec
Comments
No error occurs explicitly.
This denotes to fail to allocate memory for handle.
The value of recNumber is incorrect.
ODBC Users’ Manual 148
SQLSetEnvAttr
SQLSetEnvAttr
SQLSetEnvAttr() sets the environment attribute for the current environment.
Syntax
SQLRETURN SQLSetEnvAttr (
SQLHENV env,
SQLINTEGER Attribute,
SQLPOINTER Value,
SQLINTEGER StringLength );
Arguments
Data Type
SQLHENV
SQLINTEGER
SQLPOINTER
Argument env
Attribute
Value
In/Out
Input
Input
Input
SQLINTEGER StringLength Input
Description
Environment Handle
Environment attribute to set.
Pointer of the value related to the Attribute. Depending on the Attribute, the
Value will be either a 32-bit unsigned integer or a pointer indicating the Nullterminator string.
In case the attribute is the character, it is the length of *Value.
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
An application can call SQLSetEnvAttr () only when no connection handle is allocated in the current environment. All environment attribute successfully set in an application are stored till SQLFreeHandle () is called in the current environment.
149 ODBC Functions
SQLSetEnvAttr
Environment Attributes
Attribute
SQL_ATTR_ODBC_VERSION
Diagnosis
SQLSTATE
HY000 General error
Description
Related Functions
SQLAllocHandle
Contents
(Applied only in Win32.)
SQL_OV_ODBC3 or
SQL_OV_ODBC2
Comments
ODBC Users’ Manual 150
SQLSetStmtAttr
SQLSetStmtAttr
SQLSetStmtAttr() sets the attribute related to the statement handle.
SQLSetStmtAttrW() as a Unicode string supports same execution as SQLSetStmtAttr().
Syntax
SQLRETURN SQLSetStmtAttr (
SQLHSTMT stmt,
SQLINTEGER Attribute,
SQLPOINTER param,
SQLINTEGER StringLength );
Arguments
Data Type
SQLHENV
Argument stmt
In/Out
Input
Description
Statement handle
151 ODBC Functions
SQLSetStmtAttr
Data Type
SQLINTEGER
SQLPOINTER
Argument
Attribute
In/Out
Input param Input
Description
Attribute to set, Supported attribute value:
SQL_ATTR_CONCURRENCY,
SQL_ATTR_CURSOR_SCROLLABLE,
SQL_ATTR_CURSOR_SENSITIVITY,
SQL_ATTR_CURSOR_TYPE,
SQL_ATTR_PARAM_BIND_TYPE,
SQL_ATTR_PARAM_STATUS_PTR,
SQL_ATTR_PARAMS_PROCESSED_PTR,
SQL_ATTR_PARAMS_ROW_COUNTS_PTR,
SQL_ATTR_PARAMS_SET_ROW_COUNTS,
SQL_ATTR_PARAMSET_SIZE,
SQL_ATTR_ROW_ARRAY_SIZE,
SQL_ATTR_ROW_BIND_TYPE,
SQL_ATTR_ROW_STATUS_PTR,
SQL_ATTR_ROWS_FETCHED_PTR
ALTIBASE_STMT_ATTR_ATOMIC_ARRAY
Attribute value which is not currently being supported:
SQL_ATTR_APP_PARAM_DESC,
SQL_ATTR_APP_ROW_DESC,
SQL_ATTR_ASYNC_ENABLE,
SQL_ATTR_ENABLE_AUTO_IPD,
SQL_ATTR_FETCH_BOOKMARK_PTR,
SQL_ATTR_IMP_PARAM_DESC,
SQL_ATTR_IMP_ROW_DESC,
SQL_ATTR_KEYSET_SIZE,
SQL_ATTR_MAX_LENGTH,
SQL_ATTR_METADATA_ID,
SQL_ATTR_NOSCAN,
SQL_ATTR_PARAM_BIND_OFFSET_PTR,
SQL_ATTR_PARAM_OPERATION_PTR,
SQL_ATTR_QUERY_TIMEOUT,
SQL_ATTR_RETRIEVE_DATA,
SQL_ATTR_ROW_BIND_OFFSET_PTR,
SQL_ATTR_ROW_NUMBER,
SQL_ATTR_ROW_OPERATION_PTR,
SQL_ATTR_SIMULATE_CURSOR,
SQL_ATTR_USE_BOOKMARKS
Pointer of the value related to the Attribute
Depending on the pointer, Attribute, the param will be a 32-bit integer, the pointer of the Null-terminator, the character string’s pointer, the binary pointer, or the value defined in the ODBC.
If Attribute is the unique value of the ODBC, param is the integer number with a sign.
ODBC Users’ Manual 152
Data Type
SQLINTEGER
SQLSetStmtAttr
Argument In/Out
StringLength Input
Description
If Attribute has been defined in the ODBC and param indicates the character string or binary buffer, this argument must be the byte length of *param.
If Attribute has been defined in the ODBC and param is an integer, this argument is ignored.
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
The command option for stmt is valid until the option is changed by calling of SQLSetStmtAttr () or till stmt is removed by calling of SQLFreeHandle (). Handle release method: Calling SQL_CLOSE,
SQL_UNBIND, or SQL_RESET_PARAMS with SQLFreeStmt () does not reset the statement attribute.
To use a column-wise binding, set SQL_ATTR_PARAM_BIND_TYPE in Arguments Attribute of an application function SQLSetStmtAttr() and set SQL_PARAM_BIND_BY_COLUMN in param.
ARRAY_SIZE changes only PARAM_SIZE at every execution moment. PARAM_STATUS_PTR is the vaule to return if each column will be executed, and specifies SQLSMALLINT array. If succeeds,
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO will be returned, and if fails, then SQL_PARAM_UNUSED will be returned respectively.
For Macro values: SQL_PARAM_SUCCESS is 0SQL_PARAM_ERROR is 5,
SQL_PARAM_SUCCESS_WITH_INFO is 6SQL_PARAM_UNUSED is 7.
SQLSetStmtAttr(stmt, SQL_ATTR_PARAM_BIND_TYPE,
SQL_PARAM_BIND_BY_COLUMN);SQLSetStmtAttr(stmt, SQL_ATTR_PARAMSET_SIZE,
ARRAY_SIZE, 0);SQLSetStmtAttr(stmt, SQL_ATTR_PARAM_STATUS_PTR, ParamStatusArray, 0);
Designates the pointer of the variables to store the number of columns processed by
PARAMS_PROCESSED_PTR. The pointer type of SQLINTEGER. Then, execute SQLBindParameter () like before.
SQLSetStmtAttr(stmt, SQL_ATTR_PARAMS_PROCESSED_PTR, &ParamsProcessed,
0);then, Executing SQLBindParameter().
When using the row-wise binding, define the size of the structure in PARAM_Bind_Type, unlike in the column-wise binding.
SQLSetStmtAttr(stmt, SQL_ATTR_PARAM_BIND_TYPE, sizeof(struct…));SQLSetStmtAttr(stmt, SQL_ATTR_PARAMSET_SIZE, ARRAY_SIZE, 0);SQLSetStmtAttr(stmt,
153 ODBC Functions
SQLSetStmtAttr
SQL_ATTR_PARAM_STATUS_PTR, ParamStatusArray, 0);SQLSetStmtAttr(stmt,
SQL_ATTR_PARAMS_PROCESSED_PTR, &ParamsProcessed, 0); then, Execute SQLBindParameter().
Statement Attributes
Attribute
SQL_ATTR_CONCURRENCY
SQL_ATTR_CURSOR_SCROLLABLE
SQL_ATTR_CURSOR_SENSITIVITY
SQL_ATTR_CURSOR_TYPE
SQL_ATTR_PARAM_BIND_TYPE
SQL_ATTR_PARAM_STATUS_PTR
ODBC Users’ Manual
Contents
SQLUINTEGER value specifying the temporary processing of the cursor:
SQL_CONCUR_READ_ONLY: The cursor supports readonly. Updating is not allowed.
32-bit integer to designate whether the open cursor can be scrolled for this statement handle. (Supports only SQL_FETCH_NEXT.)
Not used
SQLUINTEGER indicating the cursor type.
SQL_CURSOR_FORWARD_ONLY: The cursor only proceeds forward.
SQL_CURSOR_STATIC: The data located in the result set are static.
Setting value which is necessary for array binding
To retrieve the data by the column-wise binding,
SQL_PARAM_BIND_BY_COLUMN (default) is set in this field.
To retrieve the data by the row-wise binding, the length of the structure or the length of the buffer to which the dynamic parameter will be bound will be set. This length must include the bound parameter space.
(Necessary for array binding)
This field is requested only when PARAMSET_SIZE is higher than 1.
Status values are as follows:
SQL_PARAM_SUCCESS: An SQL statement has been successfully executed. The macro value is 0.
SQL_PARAM_SUCCESS_WITH_INFO: An SQL statement has been successfully executed.: however, the warning data can be viewed from the diagnosis data structure.
The macro value is 5.
SQL_PARAM_ERROR: Error occurs during the execution of parameters. additional error information can be viewed on the diagnosis data structure. The macro value is 6.
SQL_PARAM_UNUSED: This parameter set is not used partly because an error has occurred preventing the previous parameter from further proceeding. The macro value is 7.
154
SQLSetStmtAttr
Attribute Contents
SQL_ATTR_PARAMS_PROCESSED_PTR (Necessary for array binding)
Indicates the buffer that return the number of parameters including the errors.
In case of the NULL pointer, no data will be returned.
If SQL_SUCCESS or SQL_SUCCESS_WITH_INFO is not returned upon calling of SQLExecDirect () or SQLExecute (), the contents of the buffer will not be defined.
SQL_ATTR_PARAMS_ROW_COUNTS_
PTR
(Necessary for array binding)
Sets the buffer that returns the following values as the result of SQLExecute to array binding.
SQL_SUCCESS: When an SQL statement was successfully executed for all array elements
SQL_ERROR When even one array element fails to execute SQL statement
SQL_NO_DATA: When no array element was changed
(inputted or deleted)
SQL_ATTR_PARAMS_SET_ROW_COU
NTS
SQL_ATTR_PARAMSET_SIZE
SQL_ATTR_ROW_ARRAY_SIZE
SQL_ATTR_ROW_BIND_TYPE
(Necessary for array binding)
SQL_ROW_COUNTS_ON: Returns the number of records changed by each array element. In other words, if there are changed records, the number of records will be returned. If there is no record changed, 0 will be returned. In case an error occurs, SQL_USHRT_MAX
(65534) will be returned.
SQL_ROW_COUNTS_OFF: Existing behaviors of attribute
SQL_ATTR_PARAM_STATUS_PTR will be maintained.
(Necessary for array binding)
SQLUINTEGER value that indicates the number of values for each parameter.
(Necessary setting value at the time of the array fetch in the SELECT statement)
SQLUINTEGER that indicates the number of rows returned by calling each SQLFetch ().
(Necessary setting value at the time of the array fetch in the SELECT statement)
SQLUINTEGER that sets the direction of the binding to be used upon calling of SQLFetch (). The column-wise binding is searched by setting
SQL_BIND_BY_COLUMN. The row-wise binding searches the data by setting the length of the structure or the length of the buffer to which the results columns will be bound.
In case the length is specified, the space for the columns to be bound must be included.
155 ODBC Functions
SQLSetStmtAttr
Attribute
SQL_ATTR_ROW_STATUS_PTR
SQL_ATTR_ROWS_FETCHED_PTR
ALTIBASE_STMT_ATTR_ATOMIC_ARR
AY
Contents
(Necessary setting value at the time of the array fetch in the SELECT statement)
The size of the array is same as the number of rows of the row set.
In this attribute, the NULL pointer can be set. In this case, the ODBC does not return the column status value.
(Necessary setting value at the time of the array fetch in the SELECT statement)
SQLUINTEGER* value indicating the buffer that returns the number of fetched rows after SQLFetch () is called
This is Altibase only attribute indicating to execute
Atomic Array Insert. Array Insert can execute the entire statements respectively, whereas Atomic Array Insert can execute several statements at one execution and this results in them executed as a single statement in other words. You may specify
ALTIBASE_STMT_ATTR_ATOMIC_ARRAY in Attribute and SQL_TRUE/SQL_FALSE in the param argument.
If you choose SQL_TRUE, you can execute Atomic Array
Insert.
However, you must specify Array Size in order that
Atomic Array Insert has better performance than the existing Array Insert does.(SQL_ATTR_PARAMSET_SIZE)
And you can save result values with using the following attributes.
SQL_ATTR_PARAM_STATUS_PRT : Real result values are saved only in the first row and the rest is successfully processed.
SQL_ATTR_PARAMS_PROCESSED_PTR : Real result values are saved only in the first row and the rest of them are ignored.
Diagnosis
SQLSTATE
HY000 General error
Description Comments
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_ex4.cpp
SQLSetStmtAttr(stmt, SQL_ATTR_PARAM_BIND_TYPE, (void*)sizeof(demo_ex4_data),
0);
ODBC Users’ Manual 156
SQLSetStmtAttr
SQLSetStmtAttr(stmt, SQL_ATTR_PARAMSET_SIZE, (void*)10, 0);
SQLSetStmtAttr(stmt, SQL_ATTR_PARAMS_PROCESSED_PTR,(void*) &processed_ptr,
0);
SQLSetStmtAttr(stmt, SQL_ATTR_PARAM_STATUS_PTR, (void*)status, 0);
You may use Automic Array Insert.
SQLSetStmtAttr(stmt, SQL_ATTR_PARAMSET_SIZE, (SQLPOINTER) array_size, 0); //
Specify Array Size.
SQLSetStmtAttr(stmt, ALTIBASE_STMT_ATTR_ATOMIC_ARRAY, (SQLPOINTER) SQL_TRUE,
0); // Specify Atomic attribute.
157 ODBC Functions
SQLSpecialColumns
SQLSpecialColumns
•
SQLSpecialColumns retrieves the following information about columns within a specified table:
The optimal set of columns that uniquely identifies a row in the table.
• Columns that are automatically updated when any value in the row is updated by a transaction.
SQLSpecialColumnsW() as a Unicode string supports same execution as SQLSpecialColumns().
Syntax
SQLRETURN SQLSpecialColumns (
SQLHSTMT stmt,
SQLSMALLINT fColType,
SQLCHAR *szTableQual,
SQLSMALLINT cbTableQual,
SQLCHAR *szTableOwner,
SQLSMALLINT cbTableOwner,
SQLCHAR *szTableName,
SQLSMALLINT cbTableName,
SQLSMALLINT fScope,
SQLSMALLINT fNullable );
Arguments
Data Type
SQLHSTMT
SQLSMALLINT
Argument stmt fColType
In/Out
Input
Input
SQLCHAR *
SQLSMALLINT
SQLCHAR *
SQLSMALLINT
SQLCHAR *
SQLSMALLINT
SQLSMALLINT szTableQual cbTableQual szTableName cbTableName fScope
Input
Input szTableOwner Input cbTable-
Owner
Input
Input
Input
Input
Description
Statement handle
Type of the column to be returned
SQL_BEST_ROWID: Returns the optimal column that uniquely identify the rows in the table by searching column value(s).
Null will be always returned.
The character number of * szTableQual
Schema Name
The character number of *szTableOwner’
The table name. Cannot be a NULL pointer.
The character number of *szTableNam
Not used
ODBC Users’ Manual 158
Data Type
SQLSMALLINT
Argument fNullable
In/Out
Input
SQLSpecialColumns
Description
Not used (Does not allow NULL data because the corresponding columns are returned to the primary keys.)
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
When fColType is SQL_BEST_ROWID, SQLSpecialColumns () returns column(s) that uniquely identify each row in the table. These columns can be used in select-list or Where clause.
SQLSpecialColumns () is used to return these columns because SQLColumns () does not return the columns that are automatically updated when columns or rows are updated by the transaction.
If there are no columns that uniquely identifies each row in the table, SQLSpecialColumns () will return the row set without rows. To subsequently call SQLFetch () on the command syntax, return
SQL_NO_DATA.
When the fact that the database does not support fColType, fScope, and fNullable arguments is stated, SQLSpecialColumns () will return the empty result set.
Columns Returned by SQLSpecialColumns ()
Name
SCOPE 1
COLUMN_NAME 2
No.
DATA_TYPE
TYPE_NAME
COLUMN_SIZE
3
4
5
Data Type
SMALLINT
VARCHAR
(NOT NULL)
SMALLINT
(NOT NULL)
VARCHAR
(NOT NULL)
INTEGER
Description
SQL_SCOPE_SESSION value is fixed to 2.
Column Name.As for the unnamed string, ODBC returns the empty character string.
SQL data type
Character string representing the name of the data type corresponding to DATA_TYPE.
Column Size. NULL will be returned when the string size is not proper.
159 ODBC Functions
SQLSpecialColumns
Name
BUFFER_LENGTH 6
DECIMAL_DIGITS 7
No.
Data Type
INTEGER
SMALLINT
PSEUDO_COLUM
N
8 SMALLINT
Description
The maximum byte storing the data
The NULL will return the data type that cannot apply the decimal points of the column and the decimal points.
Maximum digits of the character of binary datatype string. For other data types, NULL will be returned.
Diagnosis
SQLSTATE
08S01
HY009
Description
Communication line failure
Use an invalid pointer (null pointer)
Comments
Communication channel failure before the function processing is completed between the ODBC and the database szTableName is a NULL pointer.
Related Functions
SQLBindCol
SQLColumns
SQLFetch
SQLPrimaryKeys
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_meta7.cpp .> if (SQLSpecialColumns(stmt, 0,
NULL, 0,
NULL, 0,
"DEMO_META7", SQL_NTS,
NULL, 0) != SQL_SUCCESS)
{
execute_err(dbc, stmt, "SQLColumns");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
SQLBindCol(stmt, 2, SQL_C_CHAR, szColumnName, STR_LEN, &cbColumnName);
SQLBindCol(stmt, 3, SQL_C_SSHORT, &DataType, 0, &cbDataType);
SQLBindCol(stmt, 4, SQL_C_CHAR, szTypeName, STR_LEN, &cbTypeName);
ODBC Users’ Manual 160
SQLSpecialColumns
SQLBindCol(stmt, 5, SQL_C_SLONG, &ColumnSize, 0, &cbColumnSize);
SQLBindCol(stmt, 6, SQL_C_SLONG, &BufferLength, 0, &cbBufferLength);
SQLBindCol(stmt, 7, SQL_C_SSHORT, &DecimalDigits, 0, &cbDecimalDigits);
161 ODBC Functions
SQLStatistics
SQLStatistics
SQLStatistics retrieves a list of statistics about a single table and the indexes associated with the table. The driver returns the information as a result set
SQLStatisticsW() as a Unicode string supports same execution as SQLStatistics().
Syntax
SQLRETURN SQLStatistics (
SQLHSTMT stmt,
SQLCHAR *cName,
SQLSMALLINT cNameLength,
SQLCHAR *sName,
SQLSMALLINT sNameLength,
SQLCHAR *tName,
SQLSMALLINT tNameLength,
SQLSMALLINT unique,
SQLSMALLINT reserved );
Arguments
Data Type
SQLHSTMT
SQLCHAR *
SQLSMALLINT
SQLCHAR *
SQLSMALLINT
SQLCHAR *
SQLSMALLINT
SQLSMALLINT
Argument In/Out stmt cName
Input
Input cNameLength Input sName Input sNameLength Input tName Input tNameLength Input unique Input
SQLSMALLINT reserved Input
Description
Statement handle
Catalog Name
The character number of *cName
Schema Name
Length of character string of *sName
The table name. Cannot be a NULL pointer.
Length of character string of *tName index type:
SQL_INDEX_UNIQUE or
SQL_INDEX_ALL
For future use
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
ODBC Users’ Manual 162
SQLStatistics
SQL_INVALID_HANDLE
SQL_ERROR
Description returns information about a single table as a standard result set, ordered by NON_UNIQUE, TYPE,
INDEX_QUALIFIER, INDEX_NAME, and ORDINAL_POSITION. The result set combines the statistical information of the table and the data for index.
Column returned by SQLStatistics ()
Column Name
TABLE_CAT
TABLE_SCHEM
TABLE_NAME
NON_UNIQUE
INDEX_QUALIFIER
INDEX_NAME
TYPE
ORDINAL_POSITION
1
2
No.
Data Type
VARCHAR
VARCHAR
3
4
5
6
7
8
VARCHAR
(NOT NULL)
SMALLINT
VARCHAR
VARCHAR
SMALLINT
(NOT NULL)
SMALLINT
Description
Null will be always returned.
Schema name of the table to which the statistic or index applies.
Table name of the table to which the statistic or index applies.
Indicates whether the index prohibits duplicate values:
SQL_TRUE if the index values can be nonunique.
SQL_FALSE if the index values must be unique.
NULL is returned if TYPE is SQL_TABLE_STAT.
An empty character string is returned.
Index name; NULL data will be returned when the TYPE is SQL_TABLE_STAT.
TYPE of the returned data
SQL_TABLE_STAT: Indicates whether the statistical data for the table are displayed
SQL_INDEX_BTREE: Indicates B-Tree index.
SQL_INDEX_HASHED: Indicates the hashed index.
SQL_INDEX_OTHER : Indicates other index types. (T-Tree)
Position of the columns in order in the index.
(Starting with 1) NULL data will be returned when the TYPE is SQL_TABLE_STAT
163 ODBC Functions
SQLStatistics
Column Name
COLUMN_NAME
ASC_OR_DESC
CARDINALITY
PAGES
FILTER_CONDITION
9
No.
Data Type
VARCHAR
10
11
12
13
CHAR(1)
INTEGER
INTEGER
VARCHAR
Description
Column name .
If the column is expression (e.g. SALARY +
BENEFITS), the expression will be returned. If the expression cannot be determined, the empty character string will be returned.
Null data will be returned when the TYPE is
SQL_TABLE_STAT.
Column sorting order. A: In ascending orders,
D In descending orders, If the database does not support the sorting orders and the TYPE is SQL_TABLE_STAT, NULL data will be returned.
Table or index order. When the TYPE is
SQL_TABLE_STAT, the row number will be returned. If the TYPE is not SQL_TABLE_STAT, the unique number of the index will be returned. If the database does not support the TYPE, NULL data will be returned.
Page number used to store data in the index or table. If the TYPE is SQL_TABLE_STAT, this column will include the number of pages used to define the table.
If the TYPE is not SQL_TABLE_STAT, this column contains the number of pages used to store the index.
If the database does not support the TYPE,
NULL data returns.
In case of the filtered index, this column will have the filtering conditions. 30000; filter" conditions cannot be decided, this column is an empty character string.
Null In case the filter has not been faltered.
When it is not possible to decide whether the index has been filtered or the TYPE is
SQL_TABLE_STAT.
Diagnosis
SQLSTATE
08S01
Description
Communication channel error
Comments
Communication channel failure before the function processing is completed between the ODBC and the database
ODBC Users’ Manual 164
SQLStatistics
SQLSTATE
HY000
HY009
Description
General error
Use an invalid pointer (null pointer)
Comments tName is a NULL pointer cName is a NULL pointer sName is a NULL pointer
Related Functions
SQLBindCol
SQLFetch
SQLPrimaryKeys
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_meta4.cpp .> if (SQLStatistics(stmt,NULL, 0,
NULL, 0,
"DEMO_META4", SQL_NTS,
SQL_INDEX_ALL, 0) != SQL_SUCCESS)
{
execute_err(dbc, stmt, "SQLStatistics");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
SQLBindCol(stmt, 2, SQL_C_CHAR, szSchema, STR_LEN, &cbSchema);
SQLBindCol(stmt, 3, SQL_C_CHAR, szTableName, STR_LEN,&cbTableName);
SQLBindCol(stmt, 4, SQL_C_SSHORT, &NonUnique, 0, &cbNonUnique);
SQLBindCol(stmt, 6, SQL_C_CHAR, szIndexName, STR_LEN, &cbIndexName);
SQLBindCol(stmt, 8, SQL_C_SSHORT, &OrdinalPosition, 0, &cbOrdinalPosition);
SQLBindCol(stmt, 9, SQL_C_CHAR, szColumnName, STR_LEN, &cbColumnName);
SQLBindCol(stmt, 10, SQL_C_CHAR, szAscDesc, 2, &cbAscDesc);
165 ODBC Functions
SQLTablePrivileges
SQLTablePrivileges
SQLTablePrivileges returns a list of tables and the privileges associated with each table. The driver returns the information as a result set on the specified statement..
SQLTablePrivilegesW() as a Unicode string supports same execution as SQLTablePrivileges().
Syntax
SQLRETURN SQLTablePrivileges(
SQLHSTMT stmt,
SQLCHAR *cName,
SQLSMALLINT cNaneLength,
SQLCHAR *sName,
SQLSMALLINT sNameLength,
SQLCHAR *tName,
SQLSMALLINT tNameLength);
Arguments
Data Type
SQLHSTMT
SQLCHAR*
SQLSMALLINT
SQLCHAR *
SQLSMALLINT
SQLCHAR *
SQLSMALLINT
Argument In/Out stmt cName
Input
Input cNameLength Input sName Input sNameLength Input tName Input tNameLength Input
Description
Statement handle
Catalog Name
The character number of *cName
Name of the schema to retrieve
Length of character string of *sName
Table name to retrieve
Length of character string of *tName
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
ODBC Users’ Manual 166
SQLTablePrivileges
Description
SQLTablePrivileges () returns the data in the standard result set format sorted by TABLE_CAT,
TABLE_SCHEM, TABLE_NAME, PRIVILEGE, and GRANTEE.
Columns Returned by SQLTablePrivileges ()
Column Name
TABLE_CAT
TABLE_SCHEM
1
2
No.
TABLE_NAME
GRANTOR
GRANTEE
PRIVILEGE
IS_GRANTABLE
3
4
5
6
7
Data Type
VARCHAR
VARCHAR
VARCHAR (NOT
NULL)
VARCHAR
VARCHAR(NOT
NULL)
VARCHAR(NOT
NULL)
VARCHAR
Description
Always NULL Return
Schema name; NULL if not applicable to the database.
Table name
Name of the user who granted the privilege;
NULL if not applicable to the database.
Name of the user to whom the privilege was granted.
Table privilege. One of the following privileges:
Alter The grantee can change the definition of the table.
Delete The grantee can dele the rows in the table.
Index The grantee can perform index operations (such as create or alter) for the table.
INSERT: The grantee can insert new rows to the table.
REFERENCES: The grantee can refer to the columns of the table with the limited conditions.
SELECT: The grantee can search one or multiple columns in the table.
UPDATE: The grantee can modify one or more data for the table.
Indicates whether the grantee can give privilege to other users. Yes. No. Or NULL if unknown or not applicable to the database.
167 ODBC Functions
SQLTablePrivileges
Diagnosis
SQLSTATE
08S01
HY009
HY090
Description Comments
Communication channel error Communication channel failure before the function processing is completed between the ODBC and the database
Invalid Arguments used (null pointer).
Argument cName is a NULL pointer.
Invalid character string or buffer length
One of the name length Arguments is smaller than 0 or is not equal to
SQL_NTS.
Related Functions
SQLBindCol
SQLCancel
SQLColumns
SQLFetch
SQLPrimaryKeys
SQLStatistics
SQLTables
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_meta10.cpp
if (SQLTablePrivileges(stmt,
NULL, 0,
"SYS", SQL_NTS,
"DEMO_META10", SQL_NTS) != SQL_SUCCESS)
{
execute_err(dbc, stmt, "SQLTablePrivileges");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
SQLBindCol(stmt, 2, SQL_C_CHAR, szSchema, NAME_LEN, &cbSchema);
SQLBindCol(stmt, 3, SQL_C_CHAR, szTableName, NAME_LEN,&cbTableName);
SQLBindCol(stmt, 4, SQL_C_CHAR, szGrantor, NAME_LEN, &cbGrantor);
SQLBindCol(stmt, 5, SQL_C_CHAR, szGrantee, NAME_LEN, &cbGrantee);
SQLBindCol(stmt, 6, SQL_C_CHAR, szPrivilege, NAME_LEN,&cbPrivilege);
SQLBindCol(stmt, 7, SQL_C_CHAR, szGrantable, 5, &cbGrantable);
ODBC Users’ Manual 168
SQLTables
SQLTables
SQLTables returns the list of table, catalog, or schema names, and table types, stored in a specific data source. The driver returns the information as a result set.
SQLTablesW() as a Unicode string supports same execution as SQLTables().
Syntax
SQLRETURN SQLTables (
SQLHSTMT stmt,
SQLCHAR *cName,
SQLSMALLINT cNameLength,
SQLCHAR *sName,
SQLSMALLINT sNameLength,
SQLCHAR *tName,
SQLSMALLINT tNameLength,
SQLCHAR *tableType,
SQLSMALLINT tableTypeLength);
Arguments
Data Type
SQLHSTMT
SQLCHAR *
SQLSMALLINT
SQLCHAR *
SQLSMALLINT
SQLCHAR *
SQLSMALLINT
SQLCHAR *
SQLSMALLINT
Argument In/Out stmt cName
Input
Input cNameLength Input sName Input sNameLength Input tName Input tNameLength Input tableType Input tableType-
Length
Input
Description
Statement handle for the searched result
Catalog Name
The character number of *cName
Schema Name
Length of character string of *sName
Table Name
Length of character string of *tName
Table type list to compare
Length of character string of *tableType
Return Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
169 ODBC Functions
SQLTables
SQL_ERROR
Description
SQLTables () displays all table information within the required range. Some users may or may not have the SELECT privilege to any of these tables.
The application must be able to handle a situation where the user selects a table for which SELECT privileges are not granted.
The following special syntaxes are defined for cName, sName, tName, and tableType of SQLTables () to support the catalogs, schema, and the list of table types:
If sName is SQL_ALL_SCHEMAS and cName and tName are empty character strings, the result set will include the schema list valid for the database. (All columns expect that TABLE_SCHEM columns will include NULL data.)
If tableType is SQL_ALL_TABLE_TYPES and cName, sName, and tName are empty character strings, the result set will include the list of table types valid for the database. (All columns except
TABLE_TYPE column will include the NULL data.)
An application must specify the tableType in capital letters.
SQLTables () returns the data in the standard result set format sorted by TABLE_TYPE, TABLE_CAT,
TABLE_SCHEM, and TABLE_NAME.
Columns Returned by SQLTables ()
Name
TABLE_CAT
TABLE_SCHEM
TABLE_NAME
TABLE_TYPE
REMARKS
4
5
No.
1
2
Data Type
VARCHAR
VARCHAR
3
Description
Null will be always returned.
Schema name including TABLE_Name; NULL if not applicable to the database
Table Name VARCHAR
(NOT NULL)
VARCHAR
VARCHAR
Table type name (Only ‘Table’ exists in Altibase.)
For future use.
ODBC Users’ Manual 170
SQLTables
Diagnosis
SQLSTATE
08S01
Description
Communication channel error
Comments
Communication channel failure before the function processing is completed between the ODBC and the database
HY000 General error
Related Functions
SQLBindCol
SQLColumns
SQLFetch
SQLStatistics
Example
See: $$ALTIBASE_HOME/sample/SQLCLI/demo_meta1.cpp
if (SQLTables(stmt,
NULL, 0,
NULL, 0,
NULL, 0,
NULL, 0) != SQL_SUCCESS)
{
execute_err(dbc, stmt, "SQLTables");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
if (SQLBindCol(stmt, 2, SQL_C_CHAR,
schem, sizeof(schem), &schem_ind) != SQL_SUCCESS)
{
execute_err(dbc, stmt, "SQLBindCol");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
if (SQLBindCol(stmt, 3, SQL_C_CHAR,
name, sizeof(name), &name_ind) != SQL_SUCCESS)
{
execute_err(dbc, stmt, "SQLBindCol");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
if (SQLBindCol(stmt, 4, SQL_C_CHAR,
type, sizeof(type), &type_ind) != SQL_SUCCESS)
171 ODBC Functions
SQLTables
{
execute_err(dbc, stmt, "SQLBindCol");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} while ( (rc = SQLFetch(stmt)) != SQL_NO_DATA)
{
if ( rc == SQL_ERROR )
{
execute_err(dbc, stmt, "SQLFetch");
break;
}
printf("%-40s%-40s%s\n", schem, name, type);
}
ODBC Users’ Manual 172
SQLTransact
SQLTransact
SQLTransact requests a commit or rollback operation for all active operations on all statements associated with a connection.
Normally terminates or cancels all changed in the database made after the connection or before calling of SQLTransact ().
If the transaction is in use in the connection status, an application must call SQLTransact () before disconnecting the database.
SQLTransact () has been replaced by SQLEndTran ().
Syntax
SQLRETURN SQLTransact (
SQLHENV env,
SQLHDBC dbc,
SQLSMALLINT type );
Arguments
Data Type
SQLHENV
SQLHDBC
SQLSMALLINT
Argument
Env
Dbc type
In/Out
Input
Input
Input
Description
Environment Handle
Connection Handle
One of the following two values.SQL_COMMIT, SQL_ROLLBACK
Return Values
SQL_SUCCESS
SQL_INVALID_HANDLE
SQL_ERROR
Description
Completing the transaction with SQL_COMMIT or SQL_ROLLBACK will have the following effects:
Even after SQLTransact () is called, the statement handle remains valid.
The bound parameter and the column binding remain alive longer than the transaction.
173 ODBC Functions
SQLTransact
Discarding incompleted result sets..
Calling SQLTransact () when there is not transaction is currently used will return SQL_SUCCESS without any affecting the database server.
SQLTransact() may fail while Commit or Rollback is executed due to loss of connection. In this case, an application cannot judge whether commit or rollback was made.In this case the database administrator handles it manually.
Example
See: $ALTIBASE_HOME/sample/SQLCLI/demo_tran1.cpp
SQLTransact(SQL_NULL_HENV, dbc, SQL_COMMIT);
ODBC Users’ Manual 174
3
LOB Interface
This chapter describes functions and data types that can be used for handling LOB data.
175 LOB Interface
LOB Data Types
LOB Data Types
The following table shows SQL data type identifiers that support LOB:
SQL
TypeIdentifier
SQL_BLOB
SQL_CLOB
Data Type
BLOB
CLOB
Description
BLOB is a binary data type with a variable length.
CLOB is a character data type with a variable length.
The following table shows C data type identifiers that support LOB. It lists C data type of ODBC for each identifier and their definition.
C Type Identifier
SQL_C_BLOB_LOCATOR
SQL_C_CLOB_LOCATOR
ODBC C Type
SQLUBIGINT
SQLUBIGINT
C Type Definition unsigned _int64 unsigned _int64
The name of a 64-bit integer type may vary depending on platform. The _int64 shown in the above table is the name of a 64-bit integer that is used in several platforms including Windows.
Use SQL_C_CHAR for CLOB data and SQL_C_BINARY for BLOB data to bind user variables.
To obtain a LOB locator, bind SQL_C_CLOB_LOCATOR or SQL_C_BLOB_LOCATOR appropriately based on the LOB column type. A LOB locator in this context, – a LOB location input scheme – is a handle that is used during LOB data operation like a file pointer in an operating system.
The LOB location input scheme for Read can be obtained after SELECT LOB column name FROM table where… and select are executed. The LOB location input scheme for Write can be obtained after SELECT LOB column name FROM table where… FOR UPDATE are executed.
Since a LOB location input scheme refers to LOB data at a certain point in relation to MVCC, it has the same life cycle with the transaction that has created itself. Therefore, to perform LOB operation with a LOB location input scheme, a connection should be always established in Non-Autocommit Mode.
Care must be taken as there is no LOB type of a user variable such as SQL_C_BLOB or SQL_C_CLOB.
ODBC Users’ Manual 176
Function Overview
Function Overview
The functions that are available for manipulating LOB data are as follows:
1.
SQLBindFileToCol() (Non-standard)
Full Retrieve
2.
SQLBindFileToParam() (Non-standard)
Full Insert, Full Update
3.
SQLGetLobLength() (Non-standard)
Get the length of LOB data.
4.
SQLGetLob() (Non-standard)
Partial Retrieve
5.
SQLPutLob() (Non-standard)
Partial Insert, Partial Update, Partial Delete
6.
SQLFreeLob() (Non-standard)
Release the LOB locator being used.
7.
SQLGetData(), SQLPutData() (Standard)
Full Retrieve/Update
8.
Other ODBC standard functions
Among the above functions, the functions #1 through #6 are special functions that are provided by
Altibase for LOB manipulation, and they are not ODBC standard functions.
ODBC standard functions such as #7 and #8 can be used to access LOB data whether the database column type is LOB or not. However, when only a standard function is used, the functions for partial update and partial retrieve are not available.
If a user wants to do programming with ODBC Driver Manager, he should add the following entry to the odbc.ini file:
LongDataCompat = yes
If the above entry is added, the types such as SQL_BLOB and SQL_CLOB are converted to
SQL_LONGVARBINARY and SQL_LONGVARCHAR types respectively before they are passed to the user. Therefore, if ODBC Driver Manager is used, transparent manipulation of LOB data can be ensured.
177 LOB Interface
SQLBindFileToCol
SQLBindFileToCol
SQLBindFileToCol binds a file or files to the columns in the result set for BLOB or CLOB data type.
Syntax
SQLRETURN SQLBindFileToCol(
SQLHSTMT stmt,
SQLSMALLINT col,
SQLCHAR *fileName,
SQLINTEGER *fileNameLength,
SQLUINTEGER *fileOptions,
SQLINTEGER fileNameBufferSize,
SQLLEN *valueLength);
Arguments
Data Type
SQLHSTMT
SQLSMALLINT
SQLCHAR *
SQLINTEGER *
Argument
Stmt
Col filename fileName-
Length
In/Out
Input
Input
Input(Pending)
Input(Pending)
Description
An instruction handle for the found results.
Begins from #1 in the order of columns in the result set to bind.
A pointer to the buffer that holds a filename or an array of filenames. It cannot be NULL.Upon SQLFetch(), there should be a filename stored in this buffer, and
SQLFetch() returns data to the file(s).Either of an absolute path (recommended) and a relative path is allowed.
A pointer to the buffer that holds a filename length or an array of filename lengths.Upon SQLFetch(), there should be a filename length stored in this buffer.If this argument is NULL, a filename is regarded as a null-terminated string. That is, it has the same effect as if SQL_NTS were stored in the memory pointed by this argument.The max. length of a filename is 255 characters.
ODBC Users’ Manual 178
SQLBindFileToCol
Data Type
SQLINTEGER *
SQLINTEGER *
SQLLEN *
Argument fileOptions Input(Pending)
In/Out Description
A pointer to the buffer that holds a file option or an array of file options. Upon
SQLFetch(), there should a file option stored in this buffer. The following options are available:
SQL_FILE_CREATE creates one if there is no file, and returns SQL_ERROR if there is a file.
SQL_FILE_OVERWRITE creates one if there is no file, and overwrites it if there is a file.
SQL_FILE_APPEND creates one if there is no file, and appends to it if there is a file.Only one of the above options can be selected and there is no default option.
This argument cannot be NULL.
Sets the length of the fileName buffer.
fileNameBufferSize valueLength
Input
Output(Pending)
A pointer to the buffer that holds an indicator variable or an array of indicator variables. It cannot be NULL. It is used to return the length of the data stored in a file or to indicate that LOB is NULL.
SQLFetch() can return the following values to the buffer pointed by this pointer:
1. Data length,
2. SQL_NULL_DATA.
Result Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
SQLBindFileToCol() binds LOB data in the result set to a file, and SQLBindCol() binds it to an application variable (memory buffer).
If SQLFetch() is called after SQLBindFileToCol() is called, LOB data from DBMS is stored in a file, and the length (byte) of the data stored in the file is stored in the buffer pointed by the valueLength pointer. If LOB is NULL, SQL_NULL_DATA is stored in the buffer pointed by the valueLength pointer.
The values of fileName, fileNameLength and fileOptions arguments are referred to upon SQLFetch(),
179 LOB Interface
SQLBindFileToCol and any error in these arguments is also reported during fetching.
To transfer more than one LOB to a file at once upon fetching, all of the fileName, fileNameLength, fileOptions and valueLength arguments should be arrays.
Diagnosis
SQLSTATE
08S01
Description
A communication line fault (Data transmission failure)
HY000 A general error
Note
A communication line fails before function processing is complete between ODBC and DB.
Related Functions
SQLBindCol
SQLBindFileToParam
SQLDescribeCol
SQLFetch
Examples
It is assumed that a table has been created with the following DDL.
CREATE TABLE T1 (i1 INTEGER PRIMARY KEY, i2 BLOB);
Write one LOB to a file.
SQLCHAR fileName[16];
SQLINTEGER fileNameLength = 15;
SQLUINTEGER fileOptions = SQL_FILE_CREATE;
SQLINTEGER valueLength;
.
strcpy(query, "SELECT i2 FROM T1 WHERE i1=1"); if (SQLPrepare(stmt, query, SQL_NTS) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLPrepare : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
/* Specify a file to put the result values of Select. */ strcpy(fileName, "Terminator2.avi"); if (SQLBindFileToCol(stmt, 1, fileName, &fileNameLength, &fileOptions, 16,
&valueLength) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLBindFileToCol : “);
ODBC Users’ Manual 180
SQLBindFileToCol
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLExecute(stmt) != SQL_SUCCESS)
{
execute_err(dbc, stmt, "SQLExecute : ");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLFetch(stmt) == SQL_SUCCESS)
{
printf("SQLFetch success!!!\n");
} else
{
execute_err(dbc, stmt, “SQLFetch : “);
}
Write three LOB’s to a file.
SQLCHAR fileName[3][10];
SQLINTEGER fileNameLength[3];
SQLUINTEGER fileOptions[3];
SQLINTEGER valueLength[3];
.
.
.
if (SQLSetStmtAttr(stmt, SQL_ATTR_ROW_ARRAY_SIZE, (SQLPOINTER) 3, 0) !=
SQL_SUCCESS)
{
execute_err(dbc, stmt, "SQLSetStmtAttr : ");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLSetStmtAttr(stmt, SQL_ATTR_ROW_BIND_TYPE, SQL_BIND_BY_COLUMN, 0) !=
SQL_SUCCESS)
{
execute_err(dbc, stmt, "SQLSetStmtAttr : ");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} strcpy(query, "SELECT i2 FROM T1 WHERE i1 >= 1 AND i1 <= 3"); if (SQLExecDirect(stmt, query, SQL_NTS) != SQL_SUCCESS)
{
execute_err(dbc, stmt, "SQLExecDirect : ");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
/* Specify a file to put the result values of Select. */ strcpy(fileName[0], "Cube.avi"); strcpy(fileName[1], "Movie.avi"); strcpy(fileName[2], "Term.avi"); for (i = 0; i < 3; i++)
{
fileNameLength[i] = strlen(fileName[i]);
fileOptions[i] = SQL_FILE_CREATE;
}
181 LOB Interface
SQLBindFileToCol if (SQLBindFileToCol(stmt, 1, (SQLCHAR *) fileName, fileNameLength, fileOptions, 10, valueLength) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLBindFileToCol : “);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLFetch(stmt) == SQL_SUCCESS)
{
printf("SQLFetch success!!!\n");
} else
{
execute_err(dbc, stmt, “SQLFetch : “);
}
Write n LOB’s to a file.
SQLCHAR fileName[11];
SQLINTEGER fileNameLength = 10;
SQLUINTEGER fileOptions = SQL_FILE_OVERWRITE;
SQLINTEGER valueLength;
.
strcpy(query, "SELECT i2 FROM T1"); if (SQLExecDirect(stmt, query, SQL_NTS) != SQL_SUCCESS)
{
execute_err(dbc, stmt, "SQLExecDirect : ");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLBindFileToCol(stmt, 1, fileName, &fileNameLength, &fileOptions, 11,
&valueLength) != SQL_SUCCESS)
{
execute_err(dbc, stmt, "SQLBindFileToCol : “);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} for (i = 0; ; i++)
{
sprintf(fileName, "Term%02d.avi", i + 1);
rc = SQLFetch(stmt);
if (rc == SQL_SUCCESS)
{
printf("SQLFetch of file[%02] success!!!\n", i + 1);
}
else if (rc == SQL_NO_DATA)
{
break;
}
else
{
execute_err(dbc, stmt, "SQLFetch : ");
break;
}
}
ODBC Users’ Manual 182
SQLBindFileToParam
SQLBindFileToParam
SQLBindFileToParam binds the parameter market ‘?’ used for LOB data type to a file or files. When
SQLExecute() or SQLExecDirect() is called, data is transferred from the file(s) to the database management system.
Syntax
SQLRETURN SQLBindFileToParam(
SQLHSTMT stmt,
SQLSMALLINT par,
SQLSMALLINT sqlType,
SQLCHAR *fileName,
SQLINTEGER *fileNameLength,
SQLUINTEGER *fileOptions,
SQLINTEGER maxFileNameLength,
SQLLEN *ind);
Arguments
Data Type
SQLHSTMT
SQLSMALLINT
SQLSMALLINT
SQLCHAR *
Argument stmt
Par sqlType fileName
In/Out
Input
Input
Input
Input(Pending)
Description
A handle for the found results.
The order of parameters, which begins at
1.
The SQL data type of a parameter.The following options are available:
SQL_BLOB
SQL_CLOB
A pointer to the buffer that holds a filename or an array of filenames.
Upon SQLExecute() or SQLExecDirect(), there should be a filename stored in this buffer.
Either of an absolute path (recommended) and a relative path is allowed.
This argument cannot be NULL.
183 LOB Interface
SQLBindFileToParam
Data Type
SQLINTEGER *
SQLINTEGER *
SQLINTEGER *
SQLLEN *
Argument fileName-
Length fileOptions
In/Out
Input(Pending)
Input(Pending) fileNameBufferSize
Ind
Input
Input(Pending)
Description
A pointer to the buffer that holds a filename length or an array of filename lengths.Upon SQLExecute() or SQLExec-
Direct(), there should be a filename length stored in this buffer.If this argument is NULL, a filename is regarded as a null-terminated string. That is, it has the same effect as if SQL_NTS were stored in the memory pointed by this argument.The max. length of a filename is 255 characters.
A pointer to the buffer that holds a file option or an array of file options. Upon
SQLExecute() or SQLExecDirect(), there should a file option stored in this buffer.The following option is available:
SQL_FILE_READ.
The length of the filename buffer.
A pointer to the buffer that holds an indicator variable or an array of indicator variables. It cannot be NULL.It is used to determine if LOB is NULL.The following values can be set for the buffer pointed by this pointer:
0,
SQL_NULL_DATA.
Result Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
SQLBindFileToParam() binds a LOB parameter marker to a file. SQLBindParameter() can be used to bind a parameter marker to an application variable (memory buffer). For SQLBindFileToParam() and
SQLBindParameter(), only the binding by the most recently called bind function is valid.
Because the values of fileName, fileNameLength, fileOptions and ind arguments are referred to upon SQLExecute() or SQLExecDirect(), they should be set before SQLExecute() or SQLExecDirect() is called. When SQLExecute() or SQLExecDirect() is called, data is transferred from the file being bound
ODBC Users’ Manual 184
SQLBindFileToParam to DBMS.
If LOB is NULL, the buffer pointed by the ind pointer should be set to SQL_NULL_DATA, and then
SQLExecute() or SQLExecDirect() should be called. If LOB is not NULL, the buffer pointed by the ind pointer should be set to 0. The ind argument cannot be a NULL pointer.
To bind an array of files to a parameter marker, all of the fileName, fileNameLength, fileOptions and ind arguments should be arrays.
Diagnosis
SQLSTATE
08S01
Description
A communication link fault (Data transmission failure)
HY000 A general error
Note
A communication link failed before function processing is complete between ODBC and DB.
Related Functions
SQLBindCol
SQLBindFileToCol
SQLExecute
SQLExecDirect
SQLDescribeParam
Examples
It is assumed that a table has been created with the following DDL.
CREATE TABLE T1 (i1 INTEGER PRIMARY KEY, i2 BLOB);
Input one LOB to a table.
SQLCHAR fileName[16];
SQLINTEGER fileNameLength = 15;
SQLUINTEGER fileOptions = SQL_FILE_READ;
SQLINTEGER ind = 0;
.
strcpy(query, "INSERT INTO T1 VALUES (1, ?)");
/* Prepare a statement and bind a file. */ if (SQLPrepare(stmt, query, SQL_NTS) != SQL_SUCCESS)
{
185 LOB Interface
SQLBindFileToParam
execute_err(dbc, stmt, “SQLPrepare : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} strcpy(fileName, "Terminator2.avi"); if (SQLBindFileToParam(stmt, 1, SQL_BLOB, fileName, &fileNameLength, &fileOptions, 16, &ind) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLBindFileToParam : “);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLExecute(stmt) != SQL_SUCCESS)
{
execute_err(dbc, stmt, "SQLExecute : ");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
Input three LOB’s to a table.
SQLINTEGER i1[3];
SQLCHAR fileName[3][10];
SQLINTEGER fileNameLength[3];
SQLUINTEGER fileOptions[3];
SQLINTEGER ind[3];
.
if (SQLSetStmtAttr(stmt, SQL_ATTR_PARAMSET_SIZE, (SQLPOINTER) 3, 0) !=
SQL_SUCCESS)
{
execute_err(dbc, stmt, "SQLSetStmtAttr : ");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLSetStmtAttr(stmt, SQL_ATTR_PARAM_BIND_TYPE,
SQL_PARAMETER_BIND_BY_COLUMN, 0) != SQL_SUCCESS)
{
execute_err(dbc, stmt, "SQLSetStmtAttr : ");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} strcpy(query, "INSERT INTO T1 VALUES (?, ?)");
/* Prepare a statement and bind a file. */ if (SQLPrepare(stmt, query, SQL_NTS) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLPrepare : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLBindParameter(stmt, 1, SQL_PARAM_INPUT, SQL_C_INTEGER, SQL_INTEGER, 0,
0, (SQLPOINTER) i1, 0, NULL) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLBindParameter : “);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
ODBC Users’ Manual 186
SQLBindFileToParam if (SQLBindFileToParam(stmt, 2, SQL_BLOB, (SQLCHAR *) fileName, fileName-
Length, fileOptions, 10, ind) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLBindFileToParam : “);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
/* Specify a file to insert data. */ strcpy(fileName[0], "Cube.avi"); strcpy(fileName[1], "Movie.avi"); strcpy(fileName[2], "Term.avi"); for (i = 0; i < 3; i++)
{
i1[i] = i + 1;
fileNameLength[i] = strlen(fileName[i]);
fileOptions[i] = SQL_FILE_READ;
ind[i] = 0;
} if (SQLExecute(stmt) != SQL_SUCCESS)
{
execute_err(dbc, stmt, "SQLExecute : ");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
Update one LOB in a table.
SQLCHAR fileName[16];
SQLINTEGER fileNameLength = 15;
SQLUINTEGER fileOptions = SQL_FILE_READ;
SQLINTEGER ind = 0;
.
strcpy(query, "UPDATE T1 SET i2=? WHERE i1=1");
/* Prepare a statement and bind a file. if (SQLPrepare(stmt, query, SQL_NTS) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLPrepare : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} strcpy(fileName, "Terminator2_fix.avi"); if (SQLBindFileToParam(stmt, 1, SQL_BLOB, fileName, &fileNameLength, &fileOptions, 16, &ind) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLBindFileToParam : “);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLExecute(stmt) != SQL_SUCCESS)
{
execute_err(dbc, stmt, "SQLExecute : ");
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
187 LOB Interface
SQLGetLobLength
SQLGetLobLength
SQLGetLobLength gets the length of the LOB pointed by the LOB locator obtained during the current transaction.
Syntax
SQLRETURN SQLGetLobLength(
SQLHSTMT stmt,
SQLUBIGINT locator,
SQLSMALLINT locatorCType,
SQLLEN * valueLength);
Arguments
Data Type
SQLHSTMT
SQLUBIGINT
SQLSMALLINT
Argument In/Out
Stmt locator
Input
Input locatorCType Input
SQLLEN * valueLength Output
Description
A handle for the found results.
A LOB locator.
The C data type of A LOB locator. It can have the following values:
SQL_C_BLOB_LOCATOR
SQL_C_CLOB_LOCATOR
Used to store the LOB length or to indicate that LOB is NULL. The buffer pointed by the pointer returns the following values:
Data length
SQL_NULL_DATA
Result Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
A function that is used to get the length of the LOB pointed by a LOB locator.
ODBC Users’ Manual 188
SQLGetLobLength
A LOB locator has the value that directly points LOB in a database (not offset in LOB). A LOB locator can be obtained in two ways:
It can be obtained from the LOB column in the result set of the SELECT SQL statement with SQLBind-
Col() or SQLGetData() function.
In this case, the application buffer type bound by the user should be SQL_C_CLOB_LOCATOR or
SQL_C_BLOB_LOCATOR.
It can be obtained from the output parameter of SQLBindParameter().
In this case, the application buffer type bound by the user should be SQL_C_CLOB_LOCATOR or
SQL_C_BLOB_LOCATOR.
If a LOB locator has not been obtained during the current transaction, it cannot be used as an argument for this function. This is because a LOB locator becomes invalid if a transaction is terminated. If an invalid LOB locator is used as an argument, this function will return SQL_ERROR, and the buffer pointed by the valueLength argument will not be changed.
The length of LOB is returned via the valueLength argument. However, If a LOB locator points NULL
LOB, SQL_NULL_DATA is returned to the buffer pointed by the valueLength argument. If a LOB locator points NULL LOB, this function will not return an error.
Diagnosis
SQLSTATE
08S01
Description
A communication link fault (Data transmission failure)
HY000 A general error
Related Functions
SQLBindCol
SQLBindParameter
SQLFetch
SQLExecute
SQLGetLob
SQLPutLob
Note
A communication link failed before function processing is complete between ODBC and DB.
189 LOB Interface
SQLGetLobLength
Example
It is assumed that a table has been created with the following DDL.
CREATE TABLE T1 (i1 INTEGER PRIMARY KEY, i2 BLOB);
Get the length of LOB data.
DQLINTEGER valueLength;
SQLUBIGINT lobLoc;
.
.
.
strcpy(query, "SELECT i2 FROM T1 WHERE i1=1"); if (SQLExecDirect(stmt, query, SQL_NTS) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLExecDirect : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLBindCol(stmt, 1, SQL_C_BLOB_LOCATOR, &lobLoc, 0, NULL) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLBindCol : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLFetch(stmt) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLFetch : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLGetLobLength(stmt, lobLoc, SQL_C_BLOB_LOCATOR, &valueLength) !=
SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLGetLobLength : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} printf("SQLGetLobLength success!!!\n"); if (SQLFreeLob(stmt, lobLoc) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLFreeLob : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
ODBC Users’ Manual 190
SQLGetLob
SQLGetLob
SQLGetLob gets a part of data in the LOB pointed by the LOB locator obtained during the current transaction to an application data buffer.
Syntax
SQLRETURN SQLGetLob(
SQLHSTMT stmt,
SQLSMALLINT locatorCType,
SQLUBIGINT sourceLocator,
SQLLEN fromPosition,
SQLLEN forLength,
SQLSMALLINT targetCType,
SQLPOINTER value,
SQLLEN bufferSize,
SQLLEN * valueLength);
Arguments
Data Type
SQLHSTMT
SQLSMALLINT
Argument In/Out
Stmt Input locatorCType Input
SQLUBIGINT
SQLLEN
SQLLEN
SQLSMALLINT
SQLPOINTER
SQLLEN sourceLocator Input fromPosition forLength targetCType
Value bufferSize
Input
Input
Input
Output
Input
Description
A handle for the found results.
The C data type identifier of a LOB locator.
It can have the following values:
SQL_C_BLOB_LOCATOR
SQL_C_CLOB_LOCATOR
A source LOB locator.
The start point of data to transfer from
LOB (byte). It begins at 1.
The length of data to transfer from LOB
(byte).
The C data type identifier of the value buffer. It can have the following values:
SQL_C_BINARY
SQL_C_CHAR
If the user reads BLOB data into the
SQL_C_CHAR buffer, BINARY is converted to CHAR, and the result value is stored in an application buffer.
A pointer to the buffer that holds data.
The size of the value buffer (byte).
191 LOB Interface
SQLGetLob
Data Type
SQLLEN *
Argument valueLength
In/Out
Output
Description
A pointer to the buffer to which the length of data stored in the value buffer is returned. This argument cannot be NULL.
Result Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
Gets a part of data in the LOB pointed by the source locator to an application data buffer. It is used to get LOB data in parts. The total length of LOB can be obtained by calling SQLGetLobLength().
If a source locator is not the LOB locator obtained during the current transaction, it cannot be used as an argument for this function. This is because a LOB locator becomes invalid if a transaction is terminated. If a source LOB locator is not valid, the SQLGetLob() function will return SQL_ERROR, and the buffer pointed by the value and valueLength arguments will not be changed.
If a source locator points NULL LOB, the SQLGetLob() function works in the same way as when a LOB locator points LOB with length 0.
If the size of data that will be returned by calling SQLGetLob() exceeds the size of bufferSize, the SQL-
GetLob() will return SQL_SUCCESS_WITH_INFO (SQLSTATE=01004), and the data will be truncated to fit the buffer size before it is returned to the buffer.
Diagnosis
SQLSTATE
08S01
Description
A communication link fault (Data transmission failure)
HY000 A general error
Related Functions
SQLGetLobLength
ODBC Users’ Manual 192
Remark
A communication link failed before function processing is complete between ODBC and DB.
SQLGetLob
SQLPutLob
Example
It is assumed that a table has been created with the following DDL.
CREATE TABLE T1 (i1 INTEGER PRIMARY KEY, i2 CLOB);
Get LOB data to an application buffer by using the SQLGetLob() function.
SQLCHAR buf[1024];
SQLINTEGER valueLength, accumLength, forLength, procLength;
SQLUBIGINT lobLoc;
.
.
strcpy(query, "SELECT i2 FROM T1 WHERE i1=1"); if (SQLExecDirect(stmt, query, SQL_NTS) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLExecDirect : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLBindCol(stmt, 1, SQL_C_CLOB_LOCATOR, &lobLoc, 0, NULL) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLBindCol : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLFetch(stmt) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLFetch : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLGetLobLength(stmt, lobLoc, SQL_C_CLOB_LOCATOR, &valueLength) !=
SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLGetLobLength : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} for (accumLength = 0; accumLength < valueLength; accumLength += procLength)
{
if (valueLength - accumLength > 256)
{
forLength = 256;
}
else
{
forLength = valueLength - accumLength;
}
if (SQLGetLob(stmt, SQL_C_CLOB_LOCATOR, lobLoc, accumLength, forLength,
SQL_C_CHAR, buf, 256, &procLength) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLGetLob : ”);
SQLFreeStmt(stmt, SQL_DROP);
193 LOB Interface
SQLGetLob
return SQL_ERROR;
}
printf("%s", buf);
} if (SQLFreeLob(stmt, lobLoc) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLFreeLob : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
ODBC Users’ Manual 194
SQLPutLob
SQLPutLob
SQLPutLob insert, update or delete data in an application data buffer to the current LOB pointed by a LOB locator. Each operation is handled as a special case of the update operation. Inserting is to update LOB data with length 0 with new data. Deleting is to update the LOB data for length n with 0.
Syntax
SQLRETURN SQLPutLob(
SQLHSTMT stmt,
SQLSMALLINT locatorCType,
SQLUBIGINT targetLocator,
SQLLEN fromPosition,
SQLLEN forLength,
SQLSMALLINT sourceCType,
SQLPOINTER value,
SQLLEN valueLength);
Arguments
Data Type
SQLHSTMT
SQLSMALLINT
Argument In/Out stmt Input locatorCType Input
SQLUBIGINT
SQLLEN
SQLLEN
SQLSMALLINT
SQLPOINTER
SQLLEN targetLocator Input fromPosition forLength sourceCType value valueLength
Input
Input
Input
Input
Input
Description
A handle for the found results.
The C data type of a target LOB locator.
SQL_C_BLOB_LOCATOR
SQL_C_CLOB_LOCATOR
A target LOB locator.
The start point to update data in LOB
(byte). It begins at 1.
The length of a segment in LOB to be updated (byte).
The C data type identifier of the value buffer.
SQL_C_BINARY (for BLOB),
SQL_C_CHAR (for CLOB)
A pointer to the buffer that holds data.
The length of a buffer that holds data
(byte).
It should be set with 0 or a larger value. It cannot be set with SQL_NULL_DATA.
If the value is 0, the data for forLength from fromPosition in a target LOB is deleted (0 does not mean SQL_NTS.)
195 LOB Interface
SQLPutLob
Result Values
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR
Description
Inserts or updates data stored in an application data buffer to the LOB pointed by a target LOB locator. It can also delete a part or all of the data in the LOB pointed a target LOB locator.
It replaces the data for forLength from fromPosition with the data for valueLength in the value buffer. If forLength > valueLength, the length of target LOB decreases, and if forLength < valueLength, the length increases.
If forLength = 0 and valueLength > 0, it inserts data in the value buffer to the fromPosition position of target LOB. When this happens, the data after the fromPosition position in the original target LOB is shifted backward for valueLength. If forLength > 0 and valueLength = 0, it deletes the data for for-
Length from the fromPosition position of target LOB. When this happens, the data after the fromPosition + forLength position in the original target LOB is shifted forward for forLength.
If a target locator is not the LOB locator opened during the current transaction, it cannot be used as an argument for this function. This is because the LOB locator becomes invalid if a transaction is terminated. If a target LOB locator is not valid, the SQLPutLob() function will return SQL_ERROR.
If a target locator points NULL LOB, the SQLPutLob() function works in the same way as when a LOB locator points LOB with length 0.
The fromPosition argument should not exceed target LOB at the time of calling. If it is larger than target LOB, the SQLPutLob() function will return SQL_ERROR.
Diagnosis
SQLSTATE
08S01
Description
A communication link fault (Data transmission failure)
HY000 A general error
Related Functions
SQLGetLobLength
ODBC Users’ Manual 196
Note
A communication link failed before function processing is complete between ODBC and DB.
SQLPutLob
SQLGetLob
Examples
It is assumed that a table has been created with the following DDL.
CREATE TABLE T1 (i1 INTEGER PRIMARY KEY, i2 CLOB);
After inserting a record with the CLOB column value being ‘Ver.Beta’, replace ‘Beta’ with ‘Gamma’.
SQLCHAR buf[5];
SQLUBIGINT lobLoc;
.
strcpy(query, "INSERT INTO T1 VALUES (1, 'Ver.Beta')"); if (SQLExecDirect(stmt, query, SQL_NTS) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLExecDirect : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
.
strcpy(query, "SELECT i2 FROM T1 WHERE i1=1 FOR UPDATE"); if (SQLExecDirect(stmt, query, SQL_NTS) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLExecDirect : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLBindCol(stmt, 1, SQL_C_CLOB_LOCATOR, &lobLoc, 0, NULL) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLBindCol : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLFetch(stmt) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLFetch : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} memcpy(buf, "Gamma", 5); if (SQLPutLob(stmt, SQL_C_CLOB_LOCATOR, lobLoc, 4, 4, SQL_C_CHAR, buf, 5) !=
SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLPutLob : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLFreeLob(stmt, lobLoc) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLFreeLob : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
197 LOB Interface
SQLPutLob
After inserting a record with the CLOB column value being ‘ss’, insert ‘mile’ between two s’s.
SQLCHAR buf[4];
SQLUBIGINT lobLoc;
.
strcpy(query, "INSERT INTO T1 VALUES (2, 'ss')"); if (SQLExecDirect(stmt, query, SQL_NTS) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLExecDirect : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
.
strcpy(query, "SELECT i2 FROM T1 WHERE i1=1 FOR UPDATE"); if (SQLExecDirect(stmt, query, SQL_NTS) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLExecDirect : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLBindCol(stmt, 1, SQL_C_CLOB_LOCATOR, &lobLoc, 0, NULL) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLBindCol : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLFetch(stmt) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLFetch : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} memcpy(buf, "mile", 4); if (SQLPutLob(stmt, SQL_C_CLOB_LOCATOR, lobLoc, 1, 0, SQL_C_CHAR, buf, 4) !=
SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLPutLob : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
/* Delete ‘mil’ from 'smiles’. */ if (SQLPutLob(stmt, SQL_C_CLOB_LOCATOR, lobLoc, 1, 3, SQL_C_CHAR, NULL, 0) !=
SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLPutLob : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
/* Append ‘4’ to ‘ses’. */ memcpy(buf, "4", 1); if (SQLPutLob(stmt, SQL_C_CLOB_LOCATOR, lobLoc, 3, 0, SQL_C_CHAR, buf, 1) !=
SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLPutLob : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLFreeLob(stmt, lobLoc) != SQL_SUCCESS)
ODBC Users’ Manual 198
SQLPutLob
{
execute_err(dbc, stmt, “SQLFreeLob : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
Insert a record with the CLOB column value being ‘Ver.0.9a’.
SQLCHAR buf[8];
SQLINTEGER lobInd;
SQLUBIGINT lobLoc;
.
.
.
strcpy(query, "INSERT INTO T1 VALUES (5, ?)"); if (SQLPrepare(stmt, query, SQL_NTS) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLPrepare : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLBindParameter(stmt, 1, SQL_PARAM_OUTPUT, SQL_C_CLOB_LOCATOR,
SQL_CLOB_LOCATOR, 0, 0, &lobLoc, 0, &lobInd) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLBindParameter : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLExecute(stmt) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLExecute : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} memcpy(buf, "Ver.0.9a", 8); if (SQLPutLob(stmt, SQL_C_CLOB_LOCATOR, lobLoc, 0, 0, SQL_C_CHAR, buf, 7) !=
SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLPutLob : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
/* In ‘Ver.0.9a’, replace ‘0.9’ with ‘1’. */ memcpy(buf, "1", 1); if (SQLPutLob(stmt, SQL_C_CLOB_LOCATOR, lobLoc, 4, 3, SQL_C_CHAR, buf, 1) !=
SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLPutLob : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLFreeLob(stmt, lobLoc) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLFreeLob : ”);
SQLFreeStmt(stmt, SQL_DROP);
199 LOB Interface
SQLPutLob
return SQL_ERROR;
}
Change the CLOB of multiple records to ‘Retail’ at once.
SQLCHAR buf[6];
SQLINTEGER lobInd;
SQLUBIGINT lobLoc;
.
.
.
strcpy(query, "UPDATE T1 SET i2=? WHERE i1>=1 AND i1<=100"); if (SQLPrepare(stmt, query, SQL_NTS) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLPrepare : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
/* If an UPDATE query is executed after a LOB locator parameter is being outbound, LOB columns to be updated will be truncated to null automatically. */ if (SQLBindParameter(stmt, 1, SQL_PARAM_OUTPUT, SQL_C_CLOB_LOCATOR,
SQL_CLOB_LOCATOR, 0, 0, &lobLoc, 0, &lobInd) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLBindParameter : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLExecute(stmt) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLExecute : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} memcpy(buf, “Retail”, 6); if (SQLPutLob(stmt, SQL_C_CLOB_LOCATOR, lobLoc, 0, 0, SQL_C_CHAR, buf, 6) !=
SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLPutLob : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
} if (SQLFreeLob(stmt, lobLoc) != SQL_SUCCESS)
{
execute_err(dbc, stmt, “SQLFreeLob : ”);
SQLFreeStmt(stmt, SQL_DROP);
return SQL_ERROR;
}
ODBC Users’ Manual 200
SQLFreeLob
SQLFreeLob
SQLFreeLob releases resources that are related to a LOB locator opened during the current transaction.
Syntax
SQLRETURN SQLFreeLob (
SQLHSTMT stmt,
SQLUBIGINT locator);
Arguments
Data Type
SQLHSTMT
SQLUBIGINT
Argument stmt locator
In/Out
Input
Input
Description
A handle for the found results.
A LOB locator.
Result Values
SQL_SUCCESS
SQL_INVALID_HANDLE
SQL_ERROR
Description
Reports that operation of LOB pointed by a LOB locator is complete. This will release the LOB locator assigned by a server and other related resources in the server.
This function does not commit or rollback changes to LOB pointed by a LOB locator.
If a transaction is terminated with SQLEndTran(), a LOB locator is automatically released and this function does have to be called.
201 LOB Interface
SQLFreeLob
Diagnosis
SQLSTATE
08S01
Description
A communication link fault (Data transmission failure)
HY000 A general error
Note
A communication link failed before function processing is complete between ODBC and DB.
Related Functions
SQLGetLobLength
SQLGetLob
SQLPutLob
Example
Please see the examples of SQLGetLobLength(), SQLGetLob() and SQLPutLob().
ODBC Users’ Manual 202
Programing Considerations
Appendix A. Sample Codes
The appendix contains the entire sample codes which used this document
Programing Considerations
The following describes notes on programming the client using the ODBC and frequent errors:
Multithreading
On multi-threaded operating systems, multiple environment handle (SQLHENV) can be allocated by one application. In case of a multi-threaded application, one environment handle and one connection handle must be allocated to each thread. In the multi-threaded program, the same connection handle can be used by multiple threads at the same time.
When develop multi-threaded applications, ideAllocErrorSpace () function that allocates space for each thread to store the database-related errors must be called during creation of the thread.
Statement Handles
The statement handles (SQLHSTMT) can be allocated by one connection handle (SQLHDBC.) up to
1024
Binding Parameters
Note on using the last argument, valueLength (indicator), upon calling SQLBindCol () and SQLBind-
Parameter ().
In case the value fetched by the output argument in SQLBindCol () is NULL, SQL_NULL_DATA will be returned to the indicator argument.
The valueLength of SQLBindParameter () is used to indicate the length of the buffer when the data type of the argument bound to the input buffer is the variable type. (When the parameter inout type is SQL_PARAM_INOUT)
For example,
Indicator value is SQL_NTS: A string in which the buffer ends with NULL ( '' )
SQL_NULL_DATA Binding the NULL value
If inout type is SQL_PARAM_OUTPUT in SQLBindParameter (), the indicator functions same as SQL-
BindCol () indicator in SELECT statement.
203 Sample Codes
Sample of Simple Basic Program
Transaction Commit Mode
In case the program is terminated without being committed in the autocommit off session, all execution statement not committed will be all rolled back. However, if the program is terminated after
SQLDisconnect () is called, the program will be committed.
Using SQLFreeStmt() function
If the second argument is SQL_DROP in SQLFreeStmt (), the status of the handle will be changed into the previous status before the handle was allocated. however, when SQL_CLOSE argument is used, the handle status after SQLAllocStmt () is executed will be selected and can be used for other queries. In case the command executes SQLPrepare (), the status will be changed into the preparation status after SQLFreeStmt () is called by SQL_CLOSE.
In case SELECT statement is executed by SQLPrepare (). Execution result of SELECT statement upon changing from SQLExecute () to SQLFetch (). When SQLExecute () is called again by binding other hosts variables without fetching untill the last record of the result set, "invalid cursor state" may occur. To prevent this, the user must call SQLFreeStmt ( .. , SQL_CLOSE ) and SQLExecute ().However, if SQLFetch () was executed until the last record in the execution result of SELECT statement, SQL-
FreeStmt () of SQL_CLOSE does not need to be called for normal operation.
Sample of Simple Basic Program
/***********************************************
** File name = basic.cpp
** Record insertion example of EMPLOYEE table
**
** Used ODBC function:
** SQLAllocEnv()
** SQLAllocConnect()
** SQLAllocStmt()
** SQLBindCol()
** SQLBindParameter()
** SQLDisconnect()
** SQLDriverConnect()
** SQLExecDirect()
** SQLExecute()
** SQLERROR()
** SQLFreeConnect()
** SQLFreeEnv()
** SQLFetch()
** SQLFreeStmt()
** SQLPrepare()
** SQLEndTran()
** SQLTransact()
** SQLSetConnectAttr()
************************************************/
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <sqlcli.h>
#define SQL_LEN 1024
#define MSG_LEN 1024
ODBC User’s Manual 204
Sample of Simple Basic Program
#define MAXCOLS 100 int db_error(SQLHENV henv, SQLHDBC hdbc, SQLHSTMT hstmt); int main()
{
SQLHENV henv;
SQLHDBC hdbc;
SQLHSTMT hstmt1,
hstmt2;
SQLCHAR server[20],
uid[10],
pwd[10],
port[10],
constr[100],
query[SQL_LEN],
id[9],
name[31],
dept[11],
age[4],
dept_no[5],
temp[31],
*tmp;
SQLINTEGER len;
SQLINTEGER bindp_len;
SQLSMALLINT colnum;
SQLRETURN rc;
/* Get environment handle */ rc = SQLAllocEnv(&henv); if ( rc == SQL_ERROR )
{
db_error(henv, hdbc, SQL_NULL_HSTMT);
}
/* Get connection handle */ rc = SQLAllocConnect(henv, &hdbc); if ( rc == SQL_ERROR )
{
db_error(henv, hdbc, SQL_NULL_HSTMT);
}
/* Get server name, port num., uid, pwd by user. */ printf("Enter Server Name & Port num.
(server:port) : "); gets(temp); tmp = strtok(temp,":"); if( tmp == NULL )
{
printf("You must specify Server name\n");
SQLFreeConnect(hdbc);
SQLFreeEnv(henv);
exit(0);
} strcpy(server, tmp); tmp = strtok(NULL,":"); if( tmp == NULL )
{
printf("You don't specify Port Number with Server name\n");
printf("Port num : ");
gets(port);
205 Sample Codes
Sample of Simple Basic Program
} else strcpy(port, tmp); printf("Enter User Name : "); gets(uid); printf("Enter Password Name : "); gets(pwd);
/* Make connection String for SQLDriverConnect */ sprintf(constr, "DSN=%s;UID=%s;PWD=%s;CONNTYPE=1;PORT_NO=%s", server, uid, pwd, port);
/* Connect to Altibase */ rc = SQLDriverConnect(hdbc, NULL, constr, SQL_NTS, NULL, 0, NULL,
SQL_DRIVER_COMPLETE); if ( rc == SQL_ERROR )
{
db_error(henv, hdbc, SQL_NULL_HSTMT);
printf("Connect Error!!
Program terminated\n");
SQLFreeConnect(hdbc);
SQLFreeEnv(henv);
exit(0);
}
/* Now Processing SQL Query */ rc = SQLAllocStmt(hdbc, &hstmt1); if ( rc == SQL_ERROR )
{
db_error(henv, hdbc, SQL_NULL_HSTMT);
printf("SQLAllocStmt Error!!\n");
rc = SQLDisconnect(hdbc);
if ( rc == SQL_ERROR )
{
printf("disconnect error\n");
}
SQLFreeConnect(hdbc);
SQLFreeEnv(henv);
exit(0);
} rc = SQLAllocStmt(hdbc, &hstmt2); if ( rc == SQL_ERROR )
{
db_error(henv, hdbc, SQL_NULL_HSTMT);
printf("SQLAllocStmt Error!!\n");
if ( rc == SQL_ERROR )
{
printf("disconnect error\n");
}
SQLFreeConnect(hdbc);
SQLFreeEnv(henv);
exit(0);
}
/* AUTO_COMMIT MODE False */
SQLSetConnectAttr(hdbc, SQL_ATTR_AUTOCOMMIT, (void*)SQL_AUTOCOMMIT_OFF, 0); sprintf(query, "CREATE TABLE EMPLOYEE
( ID VARCHAR(8) primary key,
NAME VARCHAR(30) not NULL,
AGE NUMERIC(3),
DEPT VARCHAR(10),
DEPT_NO NUMERIC(4) )");
ODBC User’s Manual 206
Sample of Simple Basic Program rc = SQLExecDirect(hstmt1,query, SQL_NTS); if ( rc == SQL_ERROR )
{
printf("Error : %s\n",query);
db_error(henv, hdbc, hstmt1);
}
SQLFreeStmt(hstmt1, SQL_CLOSE); sprintf(query,"INSERT INTO EMPLOYEE
VALUES( ?, ?, ?, ?, ? )"); rc = SQLPrepare(hstmt1, query, SQL_NTS); if ( rc == SQL_ERROR )
{
db_error(henv, hdbc, hstmt1);
} rc = SQLBindParameter(hstmt1, 1, SQL_PARAM_INOUT, SQL_C_CHAR, SQL_VARCHAR, 8,
0, id, 0, &bindp_len); if ( rc == SQL_ERROR )
{
db_error(henv, hdbc, hstmt1);
} rc = SQLBindParameter(hstmt1, 2, SQL_PARAM_INOUT, SQL_C_CHAR, SQL_VARCHAR,
30, 0, name, 0,
&bindp_len); if ( rc == SQL_ERROR )
{
db_error(henv, hdbc, hstmt1);
} rc = SQLBindParameter(hstmt1, 3, SQL_PARAM_INOUT, SQL_C_CHAR, SQL_NUMERIC, 3,
0, age, 0, &bindp_len); if ( rc == SQL_ERROR )
{
db_error(henv, hdbc, hstmt1);
} rc = SQLBindParameter(hstmt1, 4, SQL_PARAM_INOUT, SQL_C_CHAR, SQL_VARCHAR,
10, 0, dept, 0, &bindp_len); if ( rc == SQL_ERROR )
{
db_error(henv, hdbc, hstmt1);
} rc = SQLBindParameter(hstmt1, 5, SQL_PARAM_INOUT, SQL_C_CHAR, SQL_NUMERIC, 4,
0, dept_no, 0, &bindp_len); if ( rc == SQL_ERROR )
{
db_error(henv, hdbc, hstmt1);
} sprintf(query,"SELECT * FROM EMPLOYEE
WHERE NAME = ?"); rc = SQLPrepare(hstmt2, query, SQL_NTS); if ( rc == SQL_ERROR )
{
db_error(henv, hdbc, hstmt2);
} rc = SQLBindParameter(hstmt2, 1, SQL_PARAM_INOUT, SQL_C_CHAR, SQL_VARCHAR,
30, 0, name, 0, &bindp_len); if ( rc == SQL_ERROR )
{
db_error(henv, hdbc, hstmt2);
207 Sample Codes
Sample of Simple Basic Program
} bindp_len = SQL_NTS; while (1)
{
printf("Insert Id, Name, Age, Dept, Dept_no for EMPLOYEE Table.\n");
printf("or Type 'q' to Quit.\n");
printf("Id : ");
fflush(stdin);
gets(id);
if ( id[0] == 'q' ) break;
printf("Name : ");
gets(name);
printf("Age : ");
gets(age);
printf("Dept : ");
gets(dept);
printf("Dept_no : ");
gets(dept_no);
if ( !id[0] || !name[0] || !age[0] ||!dept[0] || !dept_no[0] )
{
printf("Missing values\n");
continue;
}
rc = SQLExecute(hstmt1);
if ( rc == SQL_ERROR )
{
printf("Insert Failed!!\n");
db_error(henv, hdbc, hstmt1);
}
else
{
/*rc = SQLTransact(henv,hdbc,SQL_COMMIT);*/
rc = SQLEndTran(SQL_HANDLE_ENV, hdbc, SQL_COMMIT);
if(rc == SQL_ERROR)
{
db_error(henv, hdbc, hstmt1);
}
else
{
printf("\n COMMIT Success. \n");
}
}
rc = SQLExecute(hstmt2);
if ( rc == SQL_ERROR )
{
db_error(henv, hdbc, hstmt2);
}
else
{
printf("Inserted row was :\n");
if (SQL_ERROR == SQLBindCol(hstmt2, 1, SQL_C_CHAR, id, sizeof(id), &len))
{
printf("SQLBindCol error!!!\n");
db_error(henv, hdbc, hstmt2);
ODBC User’s Manual 208
Sample of Simple Basic Program
}
if (SQL_ERROR == SQLBindCol(hstmt2, 2, SQL_C_CHAR, name, sizeof(name),
&len))
{
printf("SQLBindCol error!!!\n");
db_error(henv, hdbc, hstmt2);
}
if (SQL_ERROR == SQLBindCol(hstmt2, 3,
SQL_C_CHAR, age, sizeof(age), &len))
{
printf("SQLBindCol error!!!\n");
db_error(henv, hdbc, hstmt2);
}
if (SQL_ERROR == SQLBindCol(hstmt2, 4,
SQL_C_CHAR, dept, sizeof(dept), &len))
{
printf("SQLBindCol error!!!\n");
db_error(henv, hdbc, hstmt2);
}
if (SQL_ERROR == SQLBindCol(hstmt2, 5,
SQL_C_CHAR, dept_no, sizeof(dept_no), &len))
{
printf("SQLBindCol error!!!\n");
db_error(henv, hdbc, hstmt2);
}
while (SQLFetch(hstmt2) == SQL_SUCCESS)
{
printf("ID: %s , Name: %s , Age: %s ,
Dept: %s , dept_no: %s\n\n\n",
id, name, age, dept, dept_no);
}
}
}
SQLFreeStmt(hstmt1, SQL_CLOSE);
SQLFreeStmt(hstmt2, SQL_CLOSE);
sprintf(query, "SELECT * FROM EMPLOYEE");
rc = SQLExecDirect(hstmt1,query, SQL_NTS);
if ( rc == SQL_ERROR )
{
db_error(henv, hdbc, hstmt1);
}
else
{
printf("%8s%30s%5s%10s%8s\n", "Id",
"Name", "Age", "Dept", "Dept_no");
int i;
for ( i = 0; i < 65; i++ ) printf("-");
printf("\n");
if (SQL_ERROR == SQLBindCol(hstmt1, 1,
SQL_C_CHAR, id, sizeof(id), &len))
{
printf("SQLBindCol error!!!\n");
db_error(henv, hdbc, hstmt2);
}
if (SQL_ERROR == SQLBindCol(hstmt1, 2,
SQL_C_CHAR, name, sizeof(name), &len))
{
printf("SQLBindCol error!!!\n");
db_error(henv, hdbc, hstmt1);
}
209 Sample Codes
Sample of Using Metadata
if (SQL_ERROR == SQLBindCol(hstmt1, 3,
SQL_C_CHAR, age, sizeof(age), &len))
{
printf("SQLBindCol error!!!\n");
db_error(henv, hdbc, hstmt1);
}
if (SQL_ERROR == SQLBindCol(hstmt1, 4,
SQL_C_CHAR, dept, sizeof(dept), &len))
{
printf("SQLBindCol error!!!\n");
db_error(henv, hdbc, hstmt1);
}
if (SQL_ERROR == SQLBindCol(hstmt1, 5,
SQL_C_CHAR, dept_no, sizeof(dept_no), &len))
{
printf("SQLBindCol error!!!\n");
db_error(henv, hdbc, hstmt1);
}
while (SQLFetch(hstmt1) == SQL_SUCCESS)
{
printf("%8s%30s%5s%10s%8s\n", id, name,
age, dept, dept_no);
}
printf("\n");
}
SQLFreeStmt(hstmt1, SQL_CLOSE);
/* Disconnect & free all handle */ rc = SQLDisconnect(hdbc); if ( rc == SQL_ERROR )
{
printf("disconnect error\n");
}
SQLFreeConnect(hdbc);
SQLFreeEnv(henv);
} int db_error(SQLHENV henv, SQLHDBC hdbc, SQLHSTMT hstmt)
{
SQLINTEGER errNo;
SQLSMALLINT msgLength;
SQLCHAR errMsg[MSG_LEN];
if (SQL_SUCCESS == SQLERROR ( henv, hdbc, hstmt, NULL, &errNo, errMsg,
MSG_LEN, &msgLength ))
{
printf(" ERR_-%ld : %s\n", errNo, errMsg);
}
return SQL_ERROR;
}
Sample of Using Metadata
/***********************************************
** File name = meta.cpp
** Meta data search program example
**
** Used ODBC function:
** SQLAllocEnv()
ODBC User’s Manual 210
** SQLAllocConnect()
** SQLAllocStmt()
** SQLBindCol()
** SQLColumns()
** SQLDriverConnect()
** SQLDisconnect()
** SQLERROR()
** SQLFreeEnv()
** SQLFetch()
** SQLFreeStmt()
** SQLFreeConnect()
** SQLPrimaryKeys()
** SQLStatistics()
** SQLTables()
************************************************/
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <sqlcli.h>
#define SQL_LEN 1024
#define MSG_LEN 1024
#define TBL_NAME_LEN 50
#define COL_LEN 4001 int db_error(SQLHENV henv, SQLHDBC hdbc,
SQLHSTMT hstmt); int db_tables(SQLHENV henv, SQLHDBC hdbc,
SQLHSTMT hstmt); int db_primary(SQLHENV henv, SQLHDBC hdbc,
SQLHSTMT hstmt); int db_fields(SQLHENV henv, SQLHDBC hdbc,
SQLHSTMT hstmt); int db_indices(SQLHENV henv, SQLHDBC hdbc,
SQLHSTMT hstmt);
SQLHSTMT hstmt1; int main()
{
SQLHENV henv;
SQLHDBC hdbc;
SQLHSTMT hstmt;
SQLCHAR server[20],
uid[10],
pwd[10],
port[5],
constr[100],
temp[30],
*tmp;
SQLRETURN rc; char job[10];
/* Get environment handle */ rc = SQLAllocEnv(&henv); if ( rc == SQL_ERROR )
{
db_error(henv, hdbc, SQL_NULL_HSTMT);
}
/* Get connection handle */ rc = SQLAllocConnect(henv, &hdbc); if ( rc == SQL_ERROR )
{
db_error(henv, hdbc, SQL_NULL_HSTMT);
211
Sample of Using Metadata
Sample Codes
Sample of Using Metadata
}
/* Get server name, port num., uid, pwd by user. */ printf("Enter Server Name & Port num.
(server:port) : "); gets(temp); tmp = strtok(temp,":"); if( tmp == NULL )
{
printf("You must specify Server name\n");
SQLFreeConnect(hdbc);
SQLFreeEnv(henv);
exit(0);
} strcpy(server, tmp); tmp = strtok(NULL,":"); if( tmp == NULL )
{
printf("You don't specify Port Number with
Server name\n");
printf("Port num : ");
gets(port);
} else strcpy(port, tmp); printf("Enter User Name : "); gets(uid); printf("Enter Password Name : "); gets(pwd);
/* Make connection String for SQLDriverConnect */ sprintf(constr, "DSN=%s;UID=%s;PWD=%s;CONN-
TYPE=1;NLS_USE=US7ASCII;PORT_NO=%s", server, uid, pwd, port);
/* Connect to Altibase */ rc = SQLDriverConnect(hdbc, NULL, constr,
SQL_NTS, NULL, 0, NULL, SQL_DRIVER_NOPROMPT); if ( rc == SQL_ERROR )
{
db_error(henv, hdbc, SQL_NULL_HSTMT);
}
/* Now Using Metadata */
/* Get Statment handle */ rc = SQLAllocStmt(hdbc, &hstmt); if ( rc == SQL_ERROR )
{
db_error(henv, hdbc, SQL_NULL_HSTMT);
printf("SQLAllocStmt Error!!\n");
rc = SQLDisconnect(hdbc);
if ( rc == SQL_ERROR )
{
printf("disconnect error\n");
}
SQLFreeConnect(hdbc);
SQLFreeEnv(henv);
exit(0);
}
ODBC User’s Manual 212
Sample of Using Metadata while (1)
{
printf("Select Job
(t:tables|f:fields|p:primary key|i:indices|q:exit) : ");
gets( job[0] );
fflush(stdin);
switch ( job )
{
case 'p' : db_primary(henv, hdbc, hstmt); break;
case 't' : db_tables(henv, hdbc, hstmt); break;
case 'i' : db_indices(henv, hdbc, hstmt); break;
case 'f' : db_fields(henv, hdbc, hstmt); break;
case 'q' : goto end;break;
default : printf("You Select Wrong job!\n");
}
}
/* Do Something */ end:
rc = SQLFreeStmt(hstmt,SQL_DROP);
if ( rc == SQL_ERROR )
{
printf("SQLFreeStmt Error!!\n");
}
/* Disconnect & free all handle */
rc = SQLDisconnect(hdbc);
if ( rc == SQL_ERROR )
{
printf("disconnect error\n");
}
SQLFreeConnect(hdbc);
SQLFreeEnv(henv);
} int db_error(SQLHENV henv, SQLHDBC hdbc, SQLHSTMT hstmt)
{
SQLINTEGER errNo;
SQLSMALLINT msgLength;
SQLCHAR errMsg[MSG_LEN];
if (SQL_SUCCESS == SQLERROR ( henv, hdbc, hstmt, NULL, &errNo, errMsg,
MSG_LEN, &msgLength ))
{
printf(" rCM_-%ld : %s\n", errNo, errMsg);
}
return SQL_ERROR;
} int db_tables(SQLHENV henv, SQLHDBC hdbc,
SQLHSTMT hstmt)
{
SQLCHAR TABLE_name[TBL_NAME_LEN], type_name[TBL_NAME_LEN];
SQLINTEGER len;
if (SQL_ERROR == SQLTables( hstmt, NULL, 0,
NULL, 0, NULL, 0, NULL, 0))
{
printf("Error SQLTables!!! \n");
db_error(henv, hdbc, hstmt);
return SQL_ERROR;
}
if (SQL_ERROR == SQLBindCol(hstmt, 3,
SQL_C_CHAR, TABLE_name, TBL_NAME_LEN, &len))
{
213 Sample Codes
Sample of Using Metadata
printf("SQLBindCol error!!! ==> 3; \n");
db_error(henv, hdbc, hstmt);
return SQL_ERROR;
}
if (SQL_ERROR == SQLBindCol(hstmt, 4, SQL_C_CHAR, type_name,
TBL_NAME_LEN, &len))
{
printf("SQLBindCol error!!! ==> 4");
db_error(henv, hdbc, hstmt);
return SQL_ERROR;
}
printf("%25s\t%15s\n", "[TABLE_name]","[type_name]");
while (SQLFetch(hstmt) == SQL_SUCCESS)
{
printf("%25s\t%15s\n", TABLE_name,type_name);
}
return SQL_SUCCESS;
} int db_primary(SQLHENV henv, SQLHDBC hdbc, SQLHSTMT hstmt)
{
SQLCHAR table[TBL_NAME_LEN], column_name[COL_LEN],
type_name[TBL_NAME_LEN];
SQLINTEGER order, len;
printf("Type Table Name : ");
gets(table);
if (SQL_ERROR == SQLPrimaryKeys( hstmt, NULL,
0, NULL, 0, table, SQL_NTS))
{
printf("error SQLPrimaryKeys!!! \n");
db_error(henv, hdbc, hstmt1);
return SQL_ERROR;
}
if (SQL_ERROR == SQLBindCol(hstmt, 4,
SQL_C_CHAR, column_name, COL_LEN, &len))
{
printf("SQLBindCol error!!! ==> 4");
db_error(henv, hdbc, hstmt);
return SQL_ERROR;
}
if (SQL_ERROR == SQLBindCol(hstmt, 5,
SQL_C_SLONG, &order, 0, &len))
{
printf("SQLBindCol error!!! ==> 5");
db_error(henv, hdbc, hstmt);
return SQL_ERROR;
}
if (SQL_ERROR == SQLBindCol(hstmt, 6, SQL_C_CHAR, type_name,
TBL_NAME_LEN, &len))
{
printf("SQLBindCol error!!! ==> 6");
db_error(henv, hdbc, hstmt);
return SQL_ERROR;
} printf("*** Table [%s] ***\n",table); while (SQLFetch(hstmt) == SQL_SUCCESS)
{
printf("-- Column Name : %s\n", column_name);
printf(" Type : %s\n", type_name);
printf(" Order : %ld\n", order);
}
ODBC User’s Manual 214
Sample of Using Metadata return SQL_SUCCESS;
} int db_fields(SQLHENV henv, SQLHDBC hdbc, SQLHSTMT hstmt)
{
SQLCHAR table[TBL_NAME_LEN],
column_name[COL_LEN],
type_name[TBL_NAME_LEN],
default_val[TBL_NAME_LEN],
is_nullable[5];
SQLINTEGER column_size, order, len;
SQLSMALLINT scale, precision; printf("Type Table Name : "); gets(table); if (SQL_ERROR == SQLColumns( hstmt, NULL, 0,
NULL, 0, table, SQL_NTS, NULL, 0))
{
printf("SQLExecute SQLExecDirect!!! \n");
db_error(henv, hdbc, hstmt);
return SQL_ERROR;
} if (SQL_ERROR == SQLBindCol(hstmt, 4,
SQL_C_CHAR, column_name, COL_LEN, &len))
{
printf("SQLBindCol error!!! ==> 4");
db_error(henv, hdbc, hstmt);
return SQL_ERROR;
} if (SQL_ERROR == SQLBindCol(hstmt, 6,
SQL_C_CHAR, type_name, TBL_NAME_LEN, &len))
{
printf("SQLBindCol error!!! ==> 6");
db_error(henv, hdbc, hstmt);
return SQL_ERROR;
} if (SQL_ERROR == SQLBindCol(hstmt, 7,
SQL_C_SLONG, &column_size, 0, &len))
{
printf("SQLBindCol error!!! ==> 7");
db_error(henv, hdbc, hstmt);
return SQL_ERROR;
} if (SQL_ERROR == SQLBindCol(hstmt, 8, SQL_C_SSHORT, &precision, 0, &len))
{
printf("SQLBindCol error!!! ==> 10");
db_error(henv, hdbc, hstmt);
return SQL_ERROR;
} if (SQL_ERROR == SQLBindCol(hstmt, 9,
SQL_C_SSHORT, &scale, 0, &len))
{
printf("SQLBindCol error!!! ==> 9");
db_error(henv, hdbc, hstmt);
return SQL_ERROR;
} if (SQL_ERROR == SQLBindCol(hstmt, 13,
SQL_C_CHAR, default_val, TBL_NAME_LEN, &len))
{
printf("SQLBindCol error!!! ==> 13");
db_error(henv, hdbc, hstmt);
215 Sample Codes
Sample of Using Metadata
return SQL_ERROR;
} if (SQL_ERROR == SQLBindCol(hstmt, 17,
SQL_C_SLONG, &order, 0, &len))
{
printf("SQLBindCol error!!! ==> 8");
db_error(henv, hdbc, hstmt);
return SQL_ERROR;
} if (SQL_ERROR == SQLBindCol(hstmt, 18,
SQL_C_CHAR, is_nullable, 5, &len))
{
printf("SQLBindCol error!!! ==> 13");
db_error(henv, hdbc, hstmt);
return SQL_ERROR;
} printf("*** Table [%s] ***\n",table); while (SQLFetch(hstmt) == SQL_SUCCESS)
{
printf("-- Column Name : %s\n",
column_name);
printf(" Type : %s\n", type_name);
printf(" Size : %ld\n", column_size);
printf(" Scale : %d\n", scale);
printf(" Precision : %d\n", precision);
printf(" Default Value : %s\n", default_val);
printf(" Order : %ld\n", order);
printf(" NULLable : %s\n", is_nullable);
} return SQL_SUCCESS;
} int db_indices(SQLHENV henv, SQLHDBC hdbc,SQLHSTMT hstmt)
{
SQLCHAR table[TBL_NAME_LEN], column_name[COL_LEN],
index_name[TBL_NAME_LEN];
SQLINTEGER len;
SQLSMALLINT nonunique, indextype, indexno;
printf("Type Table Name : ");
gets(table);
if (SQL_ERROR == SQLStatistics( hstmt, NULL,
0, NULL, 0, table, SQL_NTS,
SQL_INDEX_ALL, 0)) //SQL_INDEX_UNIQUE*/
{
printf("SQLExecute SQLExecDirect!!! \n");
db_error(henv, hdbc, hstmt);
return SQL_ERROR;
}
if (SQL_ERROR == SQLBindCol(hstmt, 4, SQL_C_SSHORT, &nonunique, 0, &len))
{
printf("SQLBindCol error!!! ==> 4");
db_error(henv, hdbc, hstmt);
return SQL_ERROR;
}
if (SQL_ERROR == SQLBindCol(hstmt, 6, SQL_C_CHAR, index_name, TBL_NAME_LEN,
&len))
{
printf("SQLBindCol error!!! ==> 6");
db_error(henv, hdbc, hstmt);
return SQL_ERROR;
} if (SQL_ERROR == SQLBindCol(hstmt, 7, SQL_C_SSHORT, &indextype, 0, &len))
ODBC User’s Manual 216
Example of Procedure test Program
{
printf("SQLBindCol error!!! ==> 7");
db_error(henv, hdbc, hstmt);
return SQL_ERROR;
} if (SQL_ERROR == SQLBindCol(hstmt, 8, SQL_C_SSHORT, &indexno, 0, &len))
{
printf("SQLBindCol error!!! ==> 8");
db_error(henv, hdbc, hstmt);
return SQL_ERROR;
} if (SQL_ERROR == SQLBindCol(hstmt, 9, SQL_C_CHAR, column_name, COL_LEN,
&len))
{
printf("SQLBindCol error!!! ==> 9");
db_error(henv, hdbc, hstmt);
return SQL_ERROR;
} printf("*** Table [%s] ***\n",table); while (SQLFetch(hstmt) == SQL_SUCCESS)
{
printf("-- Column Name : %s\n",
column_name);
printf(" Index Name : %s\n", index_name);
printf(" Index Type : %d\n", indextype);
printf(" Index Num : %d\n", indexno);
printf(" Is Unique : %s\n", nonunique?
"NO":"YES");
}
return SQL_SUCCESS;
}
Example of Procedure test Program
/***********************************************
** File name = proctest.cpp
** Example of procedure test program
**
** Used ODBC function:
** SQLAllocEnv()
** SQLAllocConnect()
** SQLAllocStmt()
** SQLDriverConnect()
** SQLExecDirect()
** SQLExecute()
** SQLPrepare()
** SQLBindParameter()
** SQLDisconnect()
** SQLERROR()
** SQLFreeEnv()
** SQLFreeStmt()
** SQLFreeConnect()
************************************************/
#include <idl.h>
#include <sqlcli.h>
#include <time.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <iduPropertyMgr.h>
217 Sample Codes
Example of Procedure test Program
#define ADDR_LEN 50
#define PHONE_LEN 13
#define MSG_LEN 1024
#define JOB_LEN 14
#define YMD_LEN 15
#define ZIP_LEN 7
#define REC_CNT 100000
#define NUM_LEN 22 int main()
{
SQLCHAR errMsg[MSG_LEN];
SQLCHAR sql[1000];
SQLHENV env;
SQLHDBC con;
SQLHSTMT stmt;
SInt i;
SInt i1;
SInt i2;
SInt i3;
SInt i1_len;
SInt i2_len;
SInt i3_len; if (SQL_ERROR == SQLAllocEnv(&env))
{
printf("AllocEnv error!!\n");
exit(1);
} else
{
printf("success AllocEnv\n");
} if (SQL_ERROR == SQLAllocConnect(env, &con))
{
printf("AllocEnv error!!\n");
SQLFreeEnv(env);
exit(1);
} else
{
printf("success AllocConnect\n");
} char connStr[1024]; sprintf(connStr, "DSN=127.0.0.1;UID=SYS;PWD=MANAGER;CONNTYPE=2"); if (SQL_ERROR == SQLDriverConnect( con, NULL,
connStr, SQL_NTS, NULL, 0, NULL,
SQL_DRIVER_NOPROMPT ))
{
printf("connection error\n");
SInt errNo;
SShort msgLength;
if (SQL_SUCCESS == SQLERROR ( env, con,
SQL_NULL_HSTMT, NULL, &errNo,
errMsg, MSG_LEN, &msgLength ))
{
printf(" ERR_-%d : %s\n", errNo, errMsg);
}
SQLFreeEnv(env);
exit(1);
}
ODBC User’s Manual 218
Example of Procedure test Program if (SQLAllocStmt(con, &stmt) == SQL_ERROR)
{
printf("SQLAllocStmt error....\n");
exit(1);
} strcpy(sql, "drop procedure proc1"); if (SQLExecDirect(stmt,sql,SQL_NTS) == SQL_ERROR)
{
printf("ERROR: drop procedure error \n");
} else
{
printf("SUCCESS: drop procedure\n");
} strcpy(sql, "create procedure proc1
( p1 in integer, p2 in out integer, p3 out integer )
as
begin
p3 := p1 + p2;
p2 := p1 * 2;
end"); if (SQLExecDirect(stmt,sql,SQL_NTS) == SQL_ERROR)
{
printf("ERROR: create procedure error \n");
} else
{
printf("SUCCESS: create procedure\n");
} strcpy(sql, "execute proc1(?,?,?)"); if ( SQLPrepare(stmt,sql,SQL_NTS) == SQL_ERROR )
{
printf("ERROR: prepare stmt\n");
} else
{
printf("SUCCESS: prepare stmt\n");
}
/* Bind Parameters */ if ( SQLBindParameter( stmt, 1,
SQL_PARAM_INOUT,
SQL_C_SLONG,
SQL_INTEGER, 0, 0, &i1, 0,
&i1_len) == SQL_ERROR )
{
printf("ERROR: Bind Parameter\n");
} else
{
// printf("SUCCESS: Bind Parameter\n");
} if ( SQLBindParameter( stmt, 2,
SQL_PARAM_INOUT_OUTPUT,
SQL_C_SLONG,
SQL_INTEGER, 0, 0, &i2, 4,
&i2_len) == SQL_ERROR )
{
printf("ERROR: 2 Bind Parameter\n");
} else
{
219 Sample Codes
Example of Procedure test Program
// printf("SUCCESS: 2 Bind Parameter\n");
} if ( SQLBindParameter( stmt, 3,
SQL_PARAM_OUTPUT,
SQL_C_SLONG,
SQL_INTEGER, 0, 0, &i3, 4,
&i3_len) == SQL_ERROR )
{
printf("ERROR: 3 Bind Parameter\n");
} else
{
// printf("SUCCESS: 3 Bind Parameter\n");
} for ( i = 0; i < 10; i++ )
{
i1 = i;
i2 = i + 1;
printf("[BEFORE] I1 : %d, I2 : %d, I3 : %d\n", i1, i2, i3 );
if (SQL_ERROR == SQLExecute(stmt))
{
printf("ERROR: Execute Procedure\n");
}
else
{
// printf("SUCCESS: Execute Procedure\n");
}
printf("[AFTER] I1 : %d(%d), I2 : %d(%d),
I3 : %d(%d)\n", i1, i1_len, i2, i2_len, i3, i3_len );
} // for if (SQLFreeStmt( stmt, SQL_DROP ) == SQL_ERROR )
{
printf("sql free stmt error\n");
} if (SQL_ERROR == SQLDisconnect(con))
{
printf("disconnect error\n");
} if (SQL_ERROR == SQLFreeConnect(con))
{
printf("SQLFreeConnect error!!\n");
} if (SQL_ERROR == SQLFreeEnv(env))
{
printf("SQLFreeConnect error!!\n");
}
return 0;
}
ODBC User’s Manual 220
Appendix B. Data Types
SQL Data Types
This appendix describes the data types of Altibase SQL data types, C data types, and the data conversion
SQL Data Types
To find which data types the Altibase ODBC supports, call SQLGetTypeInfo ().
The following table shows the list of the Altibase SQL data types and the standard SQL type identifier.
SQL type identifier
SQL_CHAR
SQL_VARCHAR
SQL_WCHAR
SQL_WVARCHAR
SQL_DECIMAL
SQL_NUMERIC
SQL_SMALLINT
SQL_INTEGER
SQL_BIGINT
SQL_REAL
SQL_FLOAT
SQL_DOUBLE
SQL_BINARY
ALTIBASE data types
CHAR(n)
VARCHAR(n)
NCHAR(n)
NVARCHAR(n)
DECIMAL(p, s)
NUMERIC(p, s)
SMALLINT
INTEGER
BIGINT
REAL
FLOAT(p)
DOUBLE
BLOB(n)
SQL_TYPE_DATE DATE
Comments
Character string of fixed string length n.
Variable-length character string with a maximum string length n.
Unicode character data type with fixed length(n)N means the number of characters.
Unicode character data type with variable length: If declared as fixed, SQL_WVARCHAR has a fixed length. If declared as variable, SQL_WVARCHAR has a variable length.N means the number of characters.
See: NUMERIC(p, s)
Signed, exact, numeric value with a precision p and scale s (1<=p<=38, -84<=s<=126)
2-byte integer data type(-2^15+1 ~ 2^15-1)
4-byte integer data type(-2^31+1 ~ 2^31-1)
8-byte integer data type(-2^63+1 ~2^63-1)
The same data type as Float of C
Fixed decimal numeric type data from -1E+120 to
1E+120 (1<=p<=38)
The same data type with DOUBLE of C
Binary data type size of n
Year, month, and day fields, conforming to the rules of the Gregorian calendar.
221 Data Types
C Data Types
SQL type identifier
SQL_TYPE_TIME
SQL_TYPE_TIMES
TAMP
SQL_INTERVAL
SQL_BYTES
SQL_NIBBLE
SQL_GEOMETRY
ALTIBASE data types
DATE
DATE
-
BYTE(n)
NIBBLE(n)
GEOMETRY
Comments
Hour, minute, and second fields, with valid values for hours of 00 to 23, valid values for minutes of 00 to 59, and valid values for seconds of 00 to 61.
Year, month, day, hour, minute, and second fields, with valid values as defined for the DATE and TIME data types.
The result type of the DATE – DATE
Binary data type with the fixed length as long as the specified size (1 byte<=n<=32000 bytes)
Binary data type with the fixed length as long as the changeable size (n) (1 byte<=n<=255 bytes)
See: Altibase Spatial Temporary SQL document
C Data Types
C data types refer to the data type of C buffer used to store the data in an application.
C data type is specified with the type argument in SQLBindCol () and SQLGetData (), and in SQLBind-
Parameter () with cType.
The following table is the list of valid type identifiers for C data type. Also, the table lists the definitions of C data type of the ODBC and the data types corresponding to each identifier.
C Type Identifier
SQL_C_CHAR
SQL_C_BIT
SQL_C_WCHAR
SQL_C_STINYINT
SQL_C_UTINYINT
SQL_C_SBIGINT
SQL_C_UBIGINT
SQL_C_SSHORT
SQL_C_USHORT
SQL_C_SLONG
SQL_C_ULONG
ODBC User’s Manual
ODBC C typedef
SQLCHAR *
SQLCHAR
SQLWCHAR *
SQLSCHAR
SQLCHAR
SQLBIGINT
SQLUBIGINT
SQLSMALLINT
SQLUSMALLINT
SQLINTEGER
SQLUINTEGER
222
C type unsigned char * unsigned char short * signed char unsigned char
_int64 unsigned _int64 short int unsigned short int int unsigned int
C Type Identifier
SQL_C_FLOAT
SQL_C_DOUBLE
SQL_C_BINARY
ODBC C typedef
SQLREAL
SQLDOUBLE
SQLCHAR *
C type float double unsigned char *
C Data Types
C Type Identifier
SQL_C_TYPE_DATE
SQL_C_TYPE_TIME
ODBC C typedef
SQL_DATE_STRUCT
SQL_C_TYPE_TIMESTAMP SQL_TIMESTAMP_STRUCT
SQL_C_BYTES
SQL_C_NIBBLE
SQL_TIME_STRUCT
SQLCHAR *
SQL_NIBBLE_STRUCT
C type struct tagDATE_STRUCT {
SQLSMALLINT year;
SQLSMALLINT month;
SQLSMALLINT day;
} DATE_STRUCT struct tagTIME_STRUCT {
SQLSMALLINT hour;
SQLSMALLINT minute;
SQLSMALLINT second;
} TIME_STRUCT struct tagTIMESTAMP_STRUCT {
SQLSMALLINT year;
SQLSMALLINT month;
SQLSMALLINT day;S
QLSMALLINT hour;
SQLSMALLINT minute;
SQLSMALLINT second;
SQLINTEGER fraction;
} TIMESTAMP_STRUCT; unsigned char * struct tagNIBBLE_STRUCT {
SQLCHAR length;
SQLCHAR value[1];
} NIBBLE_STRUCT
223 Data Types
Converting SQL Data into C Data Types
Converting SQL Data into C Data Types
Converting Data from SQL to C Data types
SQL_CHAR
SQL_VARCHAR
SQL_DECIMAL
SQL_NUMERIC
# ○ ○ ○
# ○ ○ ○
○
○
# ○ ○ ○ ○ ○ ○ ○ ○ ○ # ○ ○
# ○ ○ ○ ○ ○ ○ ○ ○ ○ # ○ ○
SQL_SMALLINT(signed) ○ ○ ○ ○ ○ ○ # ○ ○ ○ ○ ○ ○
SQL_INTEGER(signed) ○ ○ ○ ○ ○ ○ ○ ○ # ○ ○ ○ ○
SQL_BIGINT(signed)
SQL_REAL
○ ○ ○ ○ # ○ ○ ○ ○ ○ ○ ○ ○
○ ○ ○ ○ ○ ○ ○ ○ ○ ○ # ○ ○
SQL_FLOAT
SQL_DOUBLE
SQL_BINARY
SQL_TYPE_DATE
SQL_TYPE_TIME
# ○ ○ ○ ○ ○ ○ ○ ○ ○ # ○ ○
○ ○ ○ ○ ○ ○ ○ ○ ○ ○ ○ # ○
# ○
○
○
SQL_TYPE_TIMESTAMP ○
SQL_INTERVAL
SQL_BYTES
SQL_NIBBLE
○
○
○
○ #
○
○
○
#
○
○
○ ○ ○ #
○ # ○
#
SQL_GEOMETRY #
#
# : Default conversion
○ : Supported conversion
ODBC User’s Manual 224
Converting C Data into SQL Data types
Converting C Data into SQL Data types
Converting Data from C to SQL Data types
SQL_C_CHAR
SQL_C_BIT
SQL_C_STINYINT
SQL_C_UTINYINT
SQL_C_SBIGINT
SQL_C_UBIGINT
SQL_C_SSHORT
SQL_C_USHORT
SQL_C_SLONG
SQL_C_ULONG
SQL_C_FLOAT
SQL_C_DOUBLE
SQL_C_BINARY
SQL_C_TYPE_DATE
SQL_C_TYPE_TIME
SQL_C_TYPE_TIMESTAMP
SQL_C_BYTES
SQL_C_NIBBLE
# : Default conversion
○ : Supported conversion
# # # # ○ ○ ○ ○ ○ ○ ○ ○
○ ○ ○ ○ ○ ○ ○ ○ ○ ○
○ ○ ○ ○ ○ ○ ○ ○ ○ ○
○ ○ ○ ○ ○ ○ ○ ○ ○ ○
○ ○ ○ ○ ○ ○ # ○ ○ ○
○ ○ ○ ○ ○ ○ ○ ○ ○ ○
○ ○ ○ ○ # ○ ○ ○ ○ ○
○ ○ ○ ○ ○ ○ ○ ○ ○ ○
○ ○ ○ ○ ○ # ○ ○ ○ ○
○ ○ ○ ○ ○ ○ ○ ○ ○ ○
○ ○ ○ ○ ○ ○ ○ # ○ ○
○ ○ ○ ○ ○ ○ ○ ○ # #
○ ○ #
○ ○
○
○
○
○ #
#
225 Data Types
Converting C Data into SQL Data types
ODBC User’s Manual 226
ODBC Error Codes
Appendix C. ODBC Error
Codes
SQLERROR returns SQLSTATE as defined in X/Open and SQL Access Group SQL CAE specification
(1992). SQLSTATE is a five-digit character string. This Chapter contains the Altibase ODBC Drive Error refrence.
ODBC Error Codes
SQLSTATE
01004
07006
07009
Error
String data, right-truncated
Restricted data type attribute violation
Invalid descriptor index
Can be returned from
SQLDescribeCol
SQLFetch
SQLGetData
SQLBindParameter
SQLExecute
SQLFetch
SQLBindCol
SQLBindParameter
SQLColAttribute
SQLDescribeCol
SQLDescribeParam
SQLGetData
* For SQLSTATE 08001, 08002, 08003, and 08S01, see the next table.
227 ODBC Error Codes
ODBC Error Codes
SQLSTATE
HY000
HY001
HY003
Error Can be returned from
General error
Memory allocation error (Cannot allocate the requested memory for the
ODBC to execute and complete the function.)
An application buffer type is not valid.
(cType Argument value is not a valid C data type.)
SQLAllocStmt
SQLAllocConnect
SQLBindCol
SQLBindParameter
SQLColAttribute
SQLColumns
SQLConnect
SQLDescribeCol
SQLDisconnect
SQLDriverConnect
SQLEndTran
SQLExecDirect
SQLExecute
SQLFetch
SQLFreeHandle
SQLFreeStmt
SQLGetData
SQLNumParams
SQLNumResultCols
SQLPrepare
SQLPrimaryKeys
SQLProcedureColumns
SQLProcedures
SQLRowCount
SQLSetAttribute
SQLSetConnectAttr
SQLSetEnvAttrS
QLStatistics
SQLTables
SQLAllocConnect
SQLAllocStmt
SQLBindCol
SQLBindParameter
SQLConnect
SQLDriverConnect
SQLExecDirect
SQLGetTypeInfo
SQLPrepare
SQLBindCol
SQLBindParameter
ODBC User’s Manual 228
ODBC Error Codes
SQLSTATE
HY009
HY010
HY090
HY092
HY105
HYC00
Error
Used an invalid pointer (null pointer)
Function sequence error
Invalid character string or buffer
Invalid attribute or option
Invalid parameter type
Used an attribute not supported.
Can be returned from
SQLAllocConnect
SQLAllocStmt
SQLBindParameter
SQLExecDirect
SQLForeignKeys
SQLPrimaryKeys
SQLProcedureColumns
SQLProcedures
SQLSpecialColumns
SQLStatistics
SQLTablePrivileges
SQLAllocStmt
SQLDescribeParam
SQLGetData
SQLBindParameter
SQLDescribeCol
SQLExecute
SQLForeignKeys
SQLGetData
SQLGetStmtAttr
SQLTablePrivileges
SQLGetStmtAttr
SQLBindParameter
SQLGetConnectAttr
SQLGetStmtAttr
Database Connection-related Error Codes
SQLSTATE
HY000
Code
0x51001
0x5003b
HY001
08001
0x5104A
0x50032
Error
The character set does not exist.
Can be returned from
SQLConnect
SQLDriverConnect
SQLExecute The communication buffer is insufficient. (It exceeded the length of the communication buffer.)
Memory allocation error (Cannot allocate the memory requested for the
SQLCLI to execute the function and complete execution)
The ODBC cannot set the connection to a database.
SQLConnect
SQLDriverConnect
SQLConnect
SQLDriverConnect
229 ODBC Error Codes
Statement State Transition-related Errors
Network-related Error Codes
SQLSTATE
08002
Code
0x51035
08003 0x51036
08S01 0x51043
Error
The corresponding dbc is already connected to the database.
Connection does not exist.
Communication channel error
(Communication channel failure before the function is processed between the SQLCLI and the database.)
Can be returned from
SQLConnect
SQLDriverConnect
SQLExecDirect
SQLExecute
SQLPrepare
SQLColumns
SQLConnect
SQLDriverConnect
SQLExecDirect
SQLExecute
SQLFetch
SQLForeignKeys
SQLGetConnectAttr
SQLPrepare
SQLPrimaryKeys
SQLProcedureColumns
SQLProcedures
SQLSetConnectAttr
SQLSpecialColumns-
SQLStatistics
SQLTablePrivileges
SQLTables
Statement State Transition-related Errors
The following table shows how each status is converted when the ODBC function that uses the corresponding handle type (environment, connection, or statement) is called in the statement status.
Summited statements have the following status:
State
Unallocated statement. (The connection state must be connected connection.)
Allocated statement.
Prepared statement. (A (possibly empty) result set will be created.)
Cursor positioned with SQLFetch.
Description
S0
S1
S2
S6
The entry values in the conversion table are as follows:
ODBC User’s Manual 230
Statement State Transition-related Errors
When the status is not converted after the function is executed
Sn : When the command status is converted into a specified status
(IH) : Invalid Handle
(HY010) : Function sequence error
(24000) : Invalid Cursor State
Note
S : Success. In this case, the function returns one of the following values: SQL_SUCCESS_WITH_INFO or SQL_SUCCESS.
E : Error. In this case, the function returns SQL_ERROR:
R : Results. There is result set when Result command is executed. (There is possibility that the result set is empty set.)
NR : No Results. No result set when the command is executed.
NF : No Data Found. The function returns SQL_NO_DATA.
RD : Receive Done
P : Prepared. A statement was prepared.
NP : Not Prepared. A statement was not prepared.
The following example shows how to view a statement state transition table for SQLPrepare function:
(IH)
S0Unallocated S1Allocated
S => S1
S2Prepared
S => S2
E => S1
S6Infetch
(24000)
If SQLPrepare function is called when the handle type is SQL_HANDLE_STMT and the command status is S0, the ODBC administrator will return SQL_INVALID_Handle (IH). If SQLPrepare function is called and successfully executed when the handle type is SQL_HANDLE_STMT and the status is S1,
S1 status will be kept. If SQLPrepare function is called and successfully executed when the handle type is SQL_HANDLE_STMT and the status is converted to S2, the status of the command will be converted into S2. Otherwise, the command status will remain as S1 as it was. If the function is called while the handle type is SQL_HANDLE_STMT and the status is S6, the ODBC administrator always returns SQL_ERROR and SQLSTATE 24000 (Invalid Cursor State).
231 ODBC Error Codes
Statement State Transition-related Errors
SQLAllocHandle
--
S1*
S0Unallocated
--
S1Allocated
* When HandleType is SQL_HANDLE_STMT
SQLBindCol
--
S2Prepared
--
S6Infetch
(IH)
S0Unallocated
--
S1Allocated
SQLBindParameter
--
S2Prepared
--
S6Infetch
(IH)
S0Unallocated
--
S1Allocated
--
S2Prepared S6Infetch
--
SQLColumns, SQLGetTypeInfo, SQLPrimaryKeys, SQLProcedureColumns, SQLProcedures, SQLStatistics, SQLTables
(IH)
S0Unallocated S1Allocated
S => S6
S2Prepared
E => S1
S => S6
S6Infetch
(24000)
ODBC User’s Manual 232
Statement State Transition-related Errors
SQLConnect
S0Unallocated
(Error)
S1Allocated
(Error)
SQLDisconnect
S2Prepared
(Error) (Error)
S6Infetch
S0Unallocated S1Allocated
* => S0
S2Prepared
* => S0
S6Infetch
* => S0 --
When the *function SQLDisconnect is called, all commands related to the connection handle will be terminated. This function converts the connection status into allocated connection status.; Before the command status becomes S0, the connection status will become C4 (connected connection).
See SQLDriverConnect: SQLConnect
SQLExecDirect
(IH)
S0Unallocated S1Allocated
S, NR => --
S, R => S6
S2Prepared
S, NR => S1
S, R => S6
E => S1
S6Infetch
(24000)
233 ODBC Error Codes
Statement State Transition-related Errors
SQLExecute
(IH)
S0Unallocated S1Allocated
(HY010)
S2Prepared
S, NR => --
S, R => S6
E => --
SQLFetch
S6Infetch
(24000)
(IH)
S0Unallocated S1Allocated
(HY010)
S2Prepared
(HY010)
S6Infetch
S => --
RD || NF || E =>
(if NP => S1, if P => S2)
SQLFreeHandle
--
(IH)
S0Unallocated S1Allocated
(HY010)
S0
S2Prepared
(HY010)
S0
S6Infetch
(HY010)
S0
(1) When the handle type of the first row is SQL_HANDLE_ENV or SQL_HANDLE_DBC:
(2) When the handle type of the second row is SQL_HANDLE_STMT:
SQLFreeStmt
(IH)
S0Unallocated
--
S1Allocated
--
S2Prepared S6Infetch
NP = > S1
P => S2
ODBC User’s Manual 234
Statement State Transition-related Errors
S6Infetch
(IH)
S0Unallocated
S0
S1Allocated
(1) When fOption of the first row is SQL_CLOSE:
(2) When fOption of the second row is SQL_DROP:
S0
S2Prepared
SQLGetData
S0
(IH)
S0Unallocated S1Allocated
(HY010)
SQLGetTypeInfo: See SQLColumns.
S2Prepared
(HY010)
S6Infetch
S || NF => --
SQLNumResultCols
(IH)
S0Unallocated S1Allocated
(HY010)
SQLPrepare
S2Prepared
S => -S => --
S6Infetch
(IH)
S0Unallocated S1Allocated
S => --
S2Prepared
S => --
E => S1
SQLPrimaryKeys: See SQLColumns.
S6Infetch
(24000)
235 ODBC Error Codes
Statement State Transition-related Errors
SQLProcedureColumns: See SQLColumns.
SQLProcedures: See SQLColumns.
SQLSetConnectAttr
--*
S0Unallocated S1Allocated S2Prepared S6Infetch
(24000) ---
When the *set attribute is the connection attribute: When the set attribute has the statement attribute, SQLSetStmtAttr will be referred to.
SQLSetEnvAttr
S0Unallocated
(Error)
S1Allocated
(Error)
SQLSetStmtAttr
S2Prepared
(Error) (Error)
S6Infetch
(IH)
S0Unallocated
--
S1Allocated
(1) When Attribute argument is neither
SQL_ATTR_CONCURRENCY,
SQL_ATTR_CURSOR_TYPE,
SQL_ATTR_SIMULATE_CURSOR,
SQL_ATTR_USE_BOOKMARKS,
SQL_ATTR_CURSOR_SCROLLABLE, nor
SQL_ATTR_CURSOR_SENSITIVITY
ODBC User’s Manual 236
S2Prepared
(1) => --
(2) => (Error)
S6Infetch
(1) => --
(2) => (24000)
State Transition Tables
(2) When Attribute argument is either
SQL_ATTR_CONCURRENCY,
SQL_ATTR_CURSOR_TYPE,
SQL_ATTR_SIMULATE_CURSOR,
SQL_ATTR_USE_BOOKMARKS,
SQL_ATTR_CURSOR_SCROLLABLE, or
SQL_ATTR_CURSOR_SENSITIVITY
SQLStatistics: See SQLColumns.
SQLTables: See SQLColumns.
State Transition Tables
The followings summarize the major functions that affect the state transition:
Request
Current
State
S0
UNALLOCATED
Prepare (IH)
S1
ALLOCATED
S => S1
ExecDirect (IH)
Execute (IH)
S,NR => S1
S,R => S6
(HY010)
Fetch (IH) (HY010)
S2
PREPARED
S => S2
E => S1
S,NR => S1
S,R => S6
E => S1
S,NR => S2
S,R => S6
E => S2
(HY010)
FreeStmt(CLOS
E)
(IH) S1
237
S2
S6
INFETCH
(24000)
(24000)
(24000)
S => S6
RD || NF || E =>
(if NP => S1, if P => S2 )
NP => S1
P => S2
ODBC Error Codes
State Transition Tables
Request
Current
State
S0
UNALLOCATED
FreeStmt(DRO
P)
(IH)
S1
ALLOCATED
S0
S2
PREPARED
S0
S6
INFETCH
S0
Cf )
- (IH) : Invalid Handle (HY010) : Function Sequence Error
- (24000) : Invalid Cursor State
- S : Success E : Error except Network Error
- R : Results NR : No Results NF : No data Found RD: Receive Done
- P : Prepared NP : Not Prepared
ODBC User’s Manual 238
Interface Conformance Levels
Appendix D. ODBC Conformance Levels
This appendix describes the conformance level of Altibase ODBC Driver.
Interface Conformance Levels
The purpose of classifying the conformance levels is to have the information about the features that the ODBC driver supports. There are total three conformance levels. To meet the specific conformance level, all the corresponding requirements for such level should be met.
The following table shows the conformance level in compliance with ODBC 3.x, which is different from ODBC 2.x conformance level. Conformance level 1 in compliance with ODBC2.x can be considered as the core conformance.
Altibase ODBC is implemented in compliance with ODBC 2.x so that it can be considered as the core in the following table. However, it may not support functions of ODBC 3.0 specification.
Function Conformance Level
Function Name
SQLAllocHandle
SQLBindCol
SQLBindParameter
SQLBrowseConnect
SQLBulkOperations
SQLCancel
SQLCloseCursor
SQLColAttribute
SQLColumnPrivileges
SQLColumns
SQLConnect
Level
Core
Core
Core
Level1
Level1
Core
Core
Core
Level2
Core
Core
O
O
O
O
X
X
X
O
X
O
O
Support status
X
X
O
X
To be supported
Remarks
Privileges about the column are not supported by
Altibase.
239 ODBC Conformance Levels
Interface Conformance Levels
Function Name
SQLGetDescField
SQLGetDescRec
SQLGetDiagField
SQLGetDiagRec
SQLGetEnvAttr
SQLGetFunctions
SQLGetStmtAttr
SQLGetTypeInfo
SQLMoreResults
SQLNativeSql
SQLNumParams
SQLNumResultCols
SQLParamData
SQLPrepare
QLCopyDesc
SQLDescribeCol
SQLDescribeParam
SQLDisconnect
SQLDriverConnect
SQLEndTran
SQLExecDirect
SQLExecute
SQLFetch
SQLFetchScroll
SQLForeignKeys
SQLFreeHandle
SQLFreeStmt
SQLGetConnectAttr
SQLGetCursorName
SQLGetData
Level
Level1
Core
Core
Core
Core
Core
Core
Core
Core
Core
Core
Core
Core
Core
Core
Core
Core
Core
Core
Core
Level2
Core
Core
Core
Core
Core
Core
Core
Level2
Core
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
O
X
O
Support status
To be supported
O
Remarks
Not fully supported.
ODBC 3.0
ODBC 3.0
ODBC 3.0
ODBC 3.0
ODBC User’s Manual 240
Interface Conformance Levels
Function Name Level
SQLPrimaryKeys Level1
SQLProcedureColumns Level1
SQLProcedures
SQLPutData
Level1
Core
SQLRowCount
SQLSetConnectAttr
SQLSetCursorName
SQLSetDescField
Core
Core
Core
Core
SQLSetDescRec
SQLSetEnvAttr
SQLSetPos
SQLSetStmtAttr
SQLSpecialColumns
SQLStatistics
SQLTablePrivileges
SQLTables
Core
Core
Level1
Core
Core
Core
Level2
Core
O
O
O
O
X
O
O
O
O
O
O
O
O
O
O
O
Support status
O
To be supported
ODBC 3.0
ODBC 3.0
Remarks
241 ODBC Conformance Levels
Interface Conformance Levels
ODBC User’s Manual 242
Data Type
Appendix E. Upgrade
This appendix describes the requirements to make ODBC applications for Altibase 4 available for
Altibase 5 as follows.
The level of CLI interface has been improved since the upgrade to Altibase 5. Especially it has high compatibility with user applications and general purpose applications to follow the standard of X/
Open CLI or ODBC specification to the highest degree.
•
•
This appendix explains data types newly added or defined, and other changes.
Data Types
Other Changes
Data Type
This section describes data types newly added to Altibase5.
You can resolve the problems derived from compiling the existing applications to firmly keep the standard compared to previous version.
SQLCHAR, SQLSCHAR
The previous CLI applications have used SQLCHAR and char together. However, standard-oriented
SQLCHAR is defined newly as follows.
typedef unsigned char SQLCHAR; typedef signed char SQLSCHAR;
Therefore, errors occur when you compile the existing applications with the following statements.
char *query = “....”;
SQLPrepare(stmt, query, SQL_NTS);
You have only to modify type casting as follows to solve this problem.
char *query = “....”;
SQLPrepare(stmt, (SQLCHAR *)query, SQL_NTS);
SQL_BIT, SQL_VARBIT
Subsequent releases, starting with version 5, support BIT type as standard SQL92 and VARBIT type for your convenience. Refer to SQL User’s Manual for details about them.
243 Upgrade
Data Type
BIT to C type
The following indicates conversion table related to BIT.
C type id
SQL_C_CHAR
SQL_C_STINYINT
SQL_C_UTINYINT
SQL_C_SBIGINT
SQL_C_UBIGINT
SQL_C_SSHORT
SQL_C_USHORT
SQL_C_SLONG
SQL_C_ULONG
SQL_C_FLOAT
SQL_C_DOUBLE
SQL_C_NUMERIC
SQL_C_BIT
SQL_C_BINARY
None
None
Test
BufferLength > 1
BufferLength <= 1
None(The values of
BufferLength have the fixed type like this, and they are ignored in case of coversion.)
*TargetValuePtr *StrLen_or_IndPtr SQLSTATE
Data (‘0’ or ‘1’)
Undefined
Data (0 or 1)
1
Undefined
Size of C type n/a
22003 n/a
Data (0 or 1)
Data (See below for formats)
1
Data length to be written in the memory the user binds n/a n/a
VARBIT to C type
The following indicates conversion table related to VARBIT.
C type id
SQL_C_CHAR
SQL_C_BIT
SQL_C_BINARY
Test
BufferLength > 1
BufferLength <= 1
None
*TargetValuePtr *StrLen_or_IndPtr SQLSTATE
Data
Undefined
Data (0 or 1)
Data (Its format is same as that of BIT)
Precision of varbit
Undefined
1
Data length to be written in the memory the user binds n/a
22003 n/a n/a
C type to BIT/VARBIT
No type is converted to BIT currently.
ODBC User’s Manual 244
Data Type
Binary Format
0 7 8 15
Precision
16 23 24 31 where n= (Precision+7)/8 + 3
Precision : Length of BIT data
Data : BIT Data
32 39 ...
Data ....
8n 8n+7
Data Type Conversion Example
BIT/VARBIT SQL_C_BINARY
Data themselves are sent from server to user when you bind and fetch BIT to SQL_C_BINARY. Data formats sotred in user buffer are as mentioned above.
You can access to the server conveniently if specifying struct bit_t as the following examples and using it.
CREATE TABLE T1(I1 BIT(17), I2 VARBIT(37));
INSERT INTO T1 VALUES(BIT'11111011010011011',
VARBIT'0010010010101110001010100010010011011');
INSERT INTO T1 VALUES(BIT'110011011',
VARBIT'001110001010100010010011011');
---------------------void dump(unsigned char *Buffer, SQLINTEGER Length)
{ for (SQLINTEGER i = 0; i < Length; i++)
{ printf(“%02X “, *(Buffer + i));
}
} typedef struct bit_t
{
SQLUINTEGER mPrecision; unsigned char mData[1];
} bit_t; bit_t *Bit; bit_t *Varbit;
SQLLEN Length;
SQLRETURN rc;
Bit = (bit_t *)malloc(BUFFER_SIZE);
Varbit = (bit_t *)malloc(BUFFER_SIZE);
SQLBindCol( stmt, 1,
SQL_C_BINARY,
(SQLPOINTER)Bit,
BUFFER_SIZE,
&LengthBit);
SQLBindCol( stmt, 2,
SQL_C_BINARY,
245 Upgrade
Data Type
(SQLPOINTER)Varbit,
BUFFER_SIZE,
&LengthVarbit); do
{ memset(Buffer, 0, BUFFER_SIZE); rc = SQLFetch(stmt); printf(“-----\n”); printf(“>> Bit\n”); printf(“Length : %d\n”, LengthBit); printf(“Precision : %d\n”, Bit->mPrecision); dump(Bit->mData, LengthBit – sizeof(SQLUINTEGER)); printf(“>> Varbit\n”); printf(“Length : %d\n”, LengthVarbit); printf(“Precision : %d\n”, Varbit->mPrecision); dump(Varbit->mData, LengthVarbit – sizeof(SQLUINTEGER));
} while (rc != SQL_NO_DATA);
When you execute the program above, the results are as follows.
------
>> Bit
Length : 7
Precision : 17
FB 4D 80 (1111 1011 0100 1101 1)
>> Varbit
Length : 9
Precision : 37
24 AE 2A 24 D8 (0010 0100 1010 1110 0010 1010 0010 0100 1101 1)
------
>> Bit
Length : 7
Precision : 17 -> Precision indicates 17 because “0” bit is appended.
CD 80 00 (1100 1101 1000 0000)
>> Varbit
Length : 8
Precision : 27 -> Precision indicates 27 because VARBIT doesn’t perform padding.
38 A8 93 60 (0011 1000 1010 1000 1001 0011 011)
If BUFFER_SIZE is less than required, SQLFetch() returns SQL_SUCCESS_WITH_INFO, and wirtes its data in the memory bound as BUFFER_SIZE.
BIT/VARBIT to SQL_C_BIT
SQL_C_BIT of ODBC requires special care because it is the unsigned 8bit integer whose value is 0 or
1. In other words, bound variables don’t have 0x64 but 0x01 even though BIT ‘011001’ is stored on the table of server when you bind them with SQL_C_BIT and fetch them.
BIT to SQL_C_CHAR
If you bind BIT column with SQL_C_CHAR when fetching it, the result always has 0 or 1 following
ODBC type conversion rules.
CREATE TABLE T1 (I1 BIT(12));
INSERT INTO T1 VALUES(BIT’110011000010’);
INSERT INTO T1 VALUES(BIT’010011000010’);
SQLCHAR sData[128];
ODBC User’s Manual 246
Data Type
SQLLEN sLength; sQuery = (SQLCHAR *)”SELECT I1 FROM T1”;
SQLBindCol(stmt, 1, SQL_C_CHAR, sData, sizeof(sData), sLength);
SQLExecDirect(stmt, sQuery, SQL_NTS); while (SQLFetch(stmt) != SQL_NO_DATA)
{ printf(“bit value = %s, ”, sData); printf(“sLength = %d\n”, sLength);
}
If you execute program above, the following is displayed on the screen.
1, sLength = 1
0, sLength = 1
VARBIT to SQL_C_CHAR
All data in the column are fetched when you fetch VARBIT columns because conversion tool is made itself without VARBIT types in ODBC standard.
CREATE TABLE T1 (I1 VARBIT(12));
INSERT INTO T1 VALUES(VARBIT’110011000010’);
INSERT INTO T1 VALUES(VARBIT’01011010’);
SQLCHAR sData[128];
SQLLEN sLength; sQuery = (SQLCHAR *)”SELECT I1 FROM T1”;
SQLBindCol(stmt, 1, SQL_C_CHAR, sData, sizeof(sData), &sLength);
SQLExecDirect(stmt, sQuery, SQL_NTS); while (SQLFetch(stmt) != SQL_NO_DATA)
{ printf(“bit value = %s, ”, sData); printf(“sLength = %d\n”, sLength);
}
If you execute program above, the following is displayed on the screen.
110011000010, sLength = 12
01011010, sLength = 8
SQL_NIBBLE
SQL_C_NIBBLE supported in Altibase4 isn’t available to Altibase5. However, you can fetch data with
SQL_C_BINARY.
NIBBLE to C type
Conversion is available only to SQL_C_CHAR and SQL_C_BINARY.
247 Upgrade
Data Type
C type id
SQL_C_CHAR
SQL_C_BINARY
Test
BufferLength > 1
*TargetValuePtr
Data (‘0’ or ‘1’)
BufferLength <= 1 Undefined
None Data (See below for formats)
*StrLen_or_IndPtr
Data length to be written in the memory the user binds
(Except null and termination character)
Undefined
Data length to be written in the memory the user binds
SQLSTATE n/a
22003 n/a
NIBBLE is fetched in binary format in the same way as BIT, but binary format of NIBBLE is different from that of BIT because its precision field has 1 byte integer.
Binary Format
0 7 8 15
Precision
Where n = (Precision+1)/2
Precision : Length of NIBBLE data
Data : Nibble Data
...
Data ....
8n 8n+7
Data Type Conversion Example
NIBBLE to SQL_C_BINARY
Data themselves are sent from server to user when you bind and fetch NIBBLE to SQL_C_BINARY.
Data types stored in user buffer are as metioned above.
You can access to the server conveniently if specifying nibble_t as the results are as follows.
CREATE TABLE T1(I1 NIBBLE, I2 NIBBLE(10), I3 NIBBLE(21) NOT NULL);
INSERT INTO T1 VALUES(NIBBLE'A', NIBBLE'0123456789', NIB-
BLE'0123456789ABCDEF00121');
INSERT INTO T1 VALUES(NIBBLE'B', NIBBLE'789', NIBBLE'ABCD1234');
------------------void dump(unsigned char *Buffer, int Length)
{ for (int i = 0; i < Length; i++) printf(“%02X “, *(Buffer + i));
} typedef struct nibble_t
{
ODBC User’s Manual 248
Data Type unsigned char mPrecision; unsigned char mData[1];
} nibble_t; nibble_t *Buffer;
SQLLEN Length;
SQLRETURN rc;
Buffer = (nibble_t *)malloc(BUFFER_SIZE);
SQLBindCol(stmt, 2, SQL_C_BINARY, (SQLPOINTER)Buffer, BUFFER_SIZE, &Length); do
{ memset(Buffer, 0, BUFFER_SIZE); rc = SQLFetch(stmt); printf(“----\n”); printf(“Length : %d\n”, Length); printf(“Precision : %d\n”, Buffer->mPrecision); dump(Buffer->mData, Length – sizeof(SQLUINTEGER));
} while (rc != SQL_NO_DATA);
When you execute the program above, the results are as follows.
Length : 6
Precision : 10
01 23 45 67 89
----
Length : 3
Precision : 3
78 90
NIBBLE to SQL_C_CHAR
Examples and results are omitted cause of no unusual events in this case.
SQL_BYTE
This is bound to SQL_C_BINARY instead of SQL_C_BYTE in Altibase4 and then is executed in the same way as this is in Altibase4.
BYTE to C types
Conversion to other types is not available except SQL_C_CHAR and SQL_C_BINARY. However, original data requires special care that its 1 byte is expressed as ASCII 2 characters when you convert binary data to SQL_C_CHAR.
C type id
SQL_C_CHAR
Test
(Byte length of data)
* 2 < BufferLength
(Byte length of data)
* 2 >= BufferLength
*TargetValuePtr
Data
Truncated data
*StrLen_or_IndPt r
Length of data in bytes
Length of data in bytes
SQLSTATE n/a
01004
249 Upgrade
Data Type
C type id
SQL_C_BINARY
Test
Byte length of data
<= BufferLength
Byte length of data >
BufferLength
*TargetValuePtr
Data
Truncated data
*StrLen_or_IndPt r
Length of data in bytes
Length of data in bytes
SQLSTATE n/a
01004
Each byte of binary data is always converted to a pair of hex characters when Altibase ODBC CLI converts them to SQL_C_CHAR. Therefore, if buffer size of bound SQL_C_CHAR indicates the even, NULL termination character is printed not in the last byte of it but in ahead of that.
Source binary data(hex characters
AA BB 11 12
Size of bound buffer(byt es)
8
9
Contents of the buffer bound as SQL_C_CHAR hex : 41 41 42 42 31 31 00 ??
string : “AABB11” hex : 41 41 42 42 31 31 31 32 00 string : “AABB1112”
*StrLen_or_IndPt r
SQLSTATE
8
8
01004 n/a
Binary Format
Byte type doesn’t have special format like NIBBLE or BIT, but is the conjunction of binary data.
Data Type Conversion Example
BYTE to SQL_C_CHAR
CREATE TABLE T1(I1 BYTE(30));
INSERT INTO T1 VALUES(BYTE’56789ABC’);
-------------------
SQLLEN Length;
SQLRETURN rc;
// execution query : SELECT * FROM T1;
Buffer = (nibble_t *)malloc(BUFFER_SIZE);
SQLBindCol(stmt, 1, SQL_C_CHAR, (SQLPOINTER)Buffer, BUFFER_SIZE, &Length); do
{ memset(Buffer, 0, BUFFER_SIZE); rc = SQLFetch(stmt); printf(“Length : %d\n”, Length); printf(“Data : %s\n”, Length);
} while (rc != SQL_NO_DATA);
When you execute the program above, the results are as follows.
ODBC User’s Manual 250
Data Type
Execution Query 1 : BUFFER_SIZE >= 9
Length : 8
Data : 56789ABC
Execution Query 2 : BUFFER_SIZE == 8
Length : 8
Data : 56789A 8 This is bound in byte buffer, and then only 6 characters are expressed.
Execution Query 3 : BUFFER_SIZE == 7
Length : 8
Data : 56789A same as BUFFER_SIZE == 8
Execution Query 4 : BUFFER_SIZE == 6
Length : 8
Data : 5678
SQLFetch() retunrs SQL_SUCCESS_WITH_INFO for execution results except 1. SQLSTATE indicates
01004.
BYTE to SQL_C_BINARY
No unusual events for binding to binary in this case.
DATE : SQL_TYPE_TIMESTAMP
SQL_TYPE_TIMESTAMP is retuned when Altibase5 inserts data as SQL Type into DATE column with using SQLDescribeCol() or SQLColAttribute(). SQL_TYPE_TIMESTAMP is similar to Altibase DATE type of ODBC standard, and consists of year, month, day, hour and second.
However, if you call SQLColAttribute() or SQLDescribeCol(), SQL_DATE is returned as SQL type because DATE type in Altibase4 consists of basic elements such as day and hour, and much data such as special characters separating basic elements.
Therefore, when you use ODBC of Altibase 5, SQL_TYPE_DATE, SQL_TYPE_TIME and
SQL_TYPE_TIMESTAMP as constant numbers for ODBC 3.0 are recommended.
LOB
Data Type
In Altibase 4, length of LOB type is limited to page size. However, it consists of BLOB and CLOB supporting maximum 2GB.
Altibase 4 DDL
CREATE TABLE T1 (I1 BLOB(3));
Altibase 5 DDL
CREATE TABLE T1 (I1 BLOB); ---> This precision in brackets disappears.
251 Upgrade
Data Type
LOB Function Use
CLI application supports private functions to use LOB.Refer to LOB Interface of ODBC User’s Manual for details about special functions for LOB.
You can use functions available to general binary and character type except functions for LOB. You can store and search LOB data with standard ODBC in ODBC application cause of these features.
You can’t update and retrieve data partially in ODBC application, whereas you can in CLI application with SQLGetLob and SQLPutLob.
CREATE TABLE T1 (I1 BLOB, I2 CLOB); // CONNECTION 의 AUTOCOMMIT This makes off mode.
SQLCHAR sBlobData[128];
SQLCHAR sClobData[128];
SQLLEN sBlobLength;
SQLLEN sClobLength;
SQLCHAR *sQuery = (SQLCHAR *)”INSERT INTO T1 VALUES(?, ?)”;
SQLPrepare(stmt, sQuery, SQL_NTS);
SQLBindParameter(stmt, 1, SQL_C_BINARY, SQL_BLOB,0, 0, sBlobData,
sizeof(sBlobData), &sBlobLength);
SQLBindParameter(stmt, 2, SQL_C_CHAR, SQL_CLOB,0, 0, sClobData, sizeof
(sClobData), &sClobLength); sBlobLength = create_blob_data(sBlobData); sprintf((char *)sClobData, “this is clob data”); sClobLength = SQL_NTS;
SQLExecute(stmt);
Using LOB in ODBC application
If you want to fetch LOB column in ODBC application and store data in LOB column, call SQLDescribeCol, SQLColAttribute or SQLDescribeParam.
If you execute these functions in LOB column, they are returned as data types of SQL_BLOB and
SQL_CLOB. However, ODBC application doesn’t recognize data types such as SQL_BLOB or
SQL_CLOB.
Therefore, you may return them as data type which ODBC application recognizes.You can solve this problem by setting LongDataCompat = on in odbc.ini. If you call SQLColAttribute() in LOB column for this option, ODBC returns SQL_LONGVINARYto SQL_BLOB and SQL_LONGVARCHAR to
SQL_CLOB relatively.
LOB Use Examples in PHP Program
The following is the examples using LOB in PHP application. You may check 2 properties as follows in php.ini before executing programs.
odbc.defaultlrl = 4096 (This value must be specified as greater than 1) odbc.defaultbinmode = 0 (You must specify this as 0 for using LOB because this can be executed without allocating additional memory.)
~/.odbc.ini is as follows.
[Altibase]
ODBC User’s Manual 252
Data Type
Driver = AltibaseODBCDriver
Description = Altibase DSN
ServerType = Altibase
UserName = SYS
Password = MANAGER
Server = 127.0.0.1
Port = 20073
LongDataCompat = on
NLS_USE = US7ASCII php program
<?
/*
* =================================================
* Connection Trial
* =================================================
*/
$Connection = @odbc_connect("Altibase", "SYS", "MANAGER"); if (!$Connection)
{ echo "ConnectFail!!!\n"; exit;
}
/*
* =================================================
* Table Creation
* =================================================
*/
@odbc_exec($Connection, "DROP TABLE T2 "); if (!@odbc_exec($Connection,
"CREATE TABLE T2 (I1 INTEGER, B2 BLOB, C3 CLOB) TABLESPACE SYS_TBS_DATA"))
{ echo "create test table Fail!!!\n"; exit;
}
/*
* =================================================
* autocommit off for using LOB
* =================================================
*/ odbc_autocommit($Connection, FALSE);
/*
* =================================================
* Data Insertion
* =================================================
*/
$query = "INSERT INTO T2 VALUES (?, ?, ?)";
$Result1 = @odbc_prepare($Connection, $query); if (!$Result1)
{
$msg = odbc_errormsg($Connection); echo "prepare insert: $msg\n"; exit;
} for ($i = 0; $i < 10; $i++)
{
253 Upgrade
Data Type
/*
* ----------------------
* Reading in File
* ----------------------
*/
$fileno2 = $i + 1;
$filename2 = "a$fileno2.txt"; print("filename = $filename2\n");
$fp = fopen($filename2, "r");
$blob = fread($fp, 1000000); fclose($fp);
$fileno3 = 10 - $i;
$filename3 = "a$fileno3.txt"; print("filename = $filename3\n");
$fp = fopen($filename3, "r");
$clob = fread($fp, 1000000); fclose($fp);
/*
* ----------------------
* INSERT
* ----------------------
*/
$Result2 = @odbc_execute($Result1, array($i, $blob, $clob)); print("inserting $i ,$filename2 and $filename3 into T2 ......... "); if (!$Result2)
{ print("FAIL\n");
$msg = odbc_errormsg($Connection); echo "execute insert: $msg \n"; exit;
} print("OK\n");
}
/*
* =================================================
* COMMIT
* =================================================
*/ odbc_commit($Connection);
/*
* =================================================
* Check inserted data
* =================================================
*/ print "\n\n"; print "==========================================\n"; print "Selecting from table\n"; print "==========================================\n";
$query = "select * from t2";
$Result1 = @odbc_exec($Connection, $query); if (!$Result1)
{
$msg = odbc_errormsg($Connection);
ODBC User’s Manual 254
echo "ERROR select: $msg\n"; exit;
}
$rownumber = 0; while (odbc_fetch_row($Result1))
{
$data1 = odbc_result($Result1, 1);
$data2 = odbc_result($Result1, 2);
$data3 = odbc_result($Result1, 3);
$len2 = strlen($data2);
$len3 = strlen($data3); print "\n==========================================\n"; print "Row $rownumber....\n";
$rownumber++; print "data1 = ".$data1."\n"; print "-------\n"; print "data2 = \n";
// print $data2; // Output is omitted because this is binary data.
print "\n"; print "dataLen2 = [$len2]\n"; print "-------\n"; print "data3 = \n"; print $data3; print "\n"; print "dataLen3 = [$len3]\n";
} odbc_commit($Connection);
@odbc_close($Connection);
?>
Other Changes
Other Changes
This section describes changes except data types.
SQLCloseCursor
You can call functions in the following order because there isn’t ODBC state machine in Altibase4 CLI library.
SQLHSTMT stmt;
SQLAllocHandle(SQL_HANDLE_STMT, dbc, &stmt);
SQLPrepare(stmt, (SQLCHAR *)”SELECT I1 FROM T1”, SQL_NTS);
SQLExecute(stmt);
SQLFetch(stmt);
SQLExecute(stmt);
However, if you execute codes above with ODBC-CLI in Altibase5, function sequence error occurs in
SQLExecute(stmt). Because stmt performing SQLExecute() first indicates to generate result set.
Therefore, ODBC cursor becomes open and state of stmt indicates S5. (Refer to MSDN ODBC specification.). However, error occurs in this state cause of no performing SQLExecute().
If you want to perform SQLExecute() again, call SQLCloseCursor() clearly as follows and then make stmt have S1 or S3 state.
255 Upgrade
Other Changes
SQLExecute(stmt);
SQLFetch(stmt);
SQLCloseCursor(stmt);
SQLExecute(stmt);
SQLBindParameter - ColumnSize Argument
ColumnSize of SQLBindParameter() as the 6th parameter in Altibase 5 is different from that of previous one.
If you insert 0 into this argument for previous version, no problem.
However, if you insert maximum length of data transmitted to server in Altibase 5, its performance has problem because it checks their information whenever executed.
SQLBindParameter – StrLen_or_IndPtr Argument
CLI library in Altibase 4 references data only if they, which StrLen_or_IndPtr argument indicates, have variable length.
However, Altibase 5 references the values in the memory StrLen_or_IndPtr argument indicates whenever performing SQLExecute() or SQLExecDirect() because Altibase 5 can implement SQLPut-
Data() and SQLParamData().
Therefore, you need special care in perfectly initializing memory the pointer indicates if sending
StrLen_or_Ind as the last argument of SQLBindParameter() to not Null pointer but valid pointer variables.
If SQL_DATA_AT_EXEC is -2 as constant number or SQL_LEN_DATA_AT_EXEC() is less than -100 without initializing memory completely, CLI library judges user intends to send the argument with
SQLPutData(). And CLI library returns SQL_NEED_DATA when you call SQLExecute().
If SQLExecDirect() returns the unintended value(SQL_NEED_DATA) cause of no initialized value above, this influences on functions called next. So you need special care that function sequence errors in all functions called next cause to return SQL_ERROR.
SQLPutData(), SQLParamData()
ODBC-CLI in Altibase 5 supports SQLPutData() and SQLParamData() provided not in previous version. Refer to MSDN for details about each function.
The following is the example program with using functions and StrLen_or_IndPtr mentioned above.
Table Schema :
CREATE TABLE T2_CHAR (I1 INTEGER, I2 CHAR(50)); void putdata_test(void)
{
SQLRETURN sRetCode;
SQLHANDLE sStmt;
SQLINTEGER i1;
SQLLEN i1ind;
ODBC User’s Manual 256
Other Changes
SQLCHAR *i2[10] =
{
(unsigned char *)"0000000000000.",
(unsigned char *)"1111111111111. test has been done.",
(unsigned char *)"2222222222222. Abra ca dabra",
(unsigned char *)"3333333333333. Short accounts make long friends.",
(unsigned char *)"4444444444444. Whar the hell are you doing man!",
(unsigned char *)"5555555555555. Oops! I missed this row. What an idiot!",
(unsigned char *)"6666666666666. SQLPutData test is well under way.",
(unsigned char *)"7777777777777. The length of this line is well over 50
characters.",
(unsigned char *)"8888888888888. Hehehe",
(unsigned char *)"9999999999999. Can you see this?",
};
SQLLEN i2ind;
SQLINTEGER i;
SQLINTEGER sMarker = 0; i1ind = SQL_DATA_AT_EXEC; i2ind = SQL_DATA_AT_EXEC; sRetCode = SQLAllocHandle(SQL_HANDLE_STMT, gHdbc, &sStmt); check_error(SQL_HANDLE_DBC, gHdbc, "STMT handle allocation", sRetCode); sRetCode = SQLBindParameter(sStmt, 1, SQL_PARAM_INPUT,
SQL_C_SLONG, SQL_INTEGER,
0, 0, (SQLPOINTER *)1, 0, &i1ind); sRetCode = SQLBindParameter(sStmt, 2, SQL_PARAM_INPUT,
SQL_C_CHAR, SQL_CHAR,
60, 0, (SQLPOINTER *)2, 0, &i2ind); sRetCode = SQLPrepare(sStmt,
(SQLCHAR *)"insert into t2_char values (?, ?)", SQL_NTS); for(i = 0; i < 10; i++)
{ i1 = i + 1000; printf("\n"); printf(">>>>>>>> row %d : inserting %d, \"%s\"\n", i, i1, i2[i]); sRetCode = SQLExecute(sStmt); if(sRetCode == SQL_NEED_DATA)
{ sRetCode = SQLParamData(sStmt, (void **)&sMarker); while(sRetCode == SQL_NEED_DATA)
{ printf("SQLParamData gave : %d\n", sMarker); if(sMarker == 1)
{ sRetCode = SQLPutData(sStmt, &i1, 0);
} else if(sMarker == 2)
{ int unitsize = 20; int size; int pos; int len;
257 Upgrade
Other Changes len = strlen((char *)(i2[i])); for(pos = 0; pos < len;)
{ size = len - pos; if(unitsize < size)
{ size = unitsize;
} sRetCode = SQLPutData(sStmt, i2[i] + pos, size);| pos += size;
}
} else
{ printf("bbbbbbbbbbbbbbbbbbbbbbbbbbbbb!!! unknown marker value\n"); exit(1);
} sRetCode = SQLParamData(sStmt, (void **)&sMarker);
}
}
} sRetCode = SQLFreeHandle(SQL_HANDLE_STMT, sStmt); check_error(SQL_HANDLE_DBC, gHdbc, "STMT free", sRetCode);
}
Limitation on ALTER SESSION statements
Altibase 4 specifies AUTOCOMMIT MODE and DEFAULT_DATE_FORMAT as session properties as follows.
SQLExecDirect(stmt,
“ALTER SESSION SET AUTOCOMMIT=FALSE”,
SQL_NTS);
SQLExecDirect(stmt,
“ALTER SESSION SET DEFAULT_DATE_FORMAT='YYYY/MM/DD'",
SQL_NTS);
2 session properties above must have information on ODBC-CLI because they definitely affect conversion of ODBC-CLI and operation of functions related to transactions.
However, ODBC-CLI can’t know property changes if transmitting SQL syntaxes to server directly with using SQLExecDirect().
ODBC-CLI can get information from server to know the values of property, but this causes to have worse performance.
In Altibase 5 the property is modified with SQLSetConnectAttr() to solve this problem. Altibase 5 always makes the property in ODBC-CLI same as that in server.
Altibase executes as follows when using ODBC-CLI.
SQL_ATTR_AUTOCOMMIT,
(SQLPOINTER)SQL_AUTOCOMMIT_OFF,
0);
SQLSetConnectAttr(conn,
ALTIBASE_DATE_FORMAT,
ODBC User’s Manual 258
Other Changes
(SQLPOINTER)"YYYY/MM/DD",
SQL_NTS);
SQLRowCount(), SQLMoreResults() functions
•
•
•
There are 2 results of ODBC.
Number of affected rows
• Result set
ODBC-CLI considers multiple results in Altibase 5. In other words, you can get them by one execution. Therefore, returned results of SQLRoewCount() are different from those of Altibase 4 when you use array binding.
SQLRowCount() : gets affected row count in “current” result.
SQLMoreResults() : moves to “next” result and returns SQL_NO_DATA if current result is last.
Example
CREATE TABLE T1 (I1 INTEGER);
INSERT INTO T1 VALUES(1);
INSERT INTO T1 VALUES(2); ........ repeat 1000 times
2
3
.
.
SELECT * FROM T1;
T1
-----
1
.
1000
-----
SQLINTEGER p1[3];
SQLINTEGER p2[3];
SQLLEN rowcount = 0L;
SQLLEN totalRowcount = 0L; p1[0] = 10; p2[0] = 20; p1[1] = 100; p2[1] = 200; p1[2] = 11; p2[2] = 14;
SQLSetStmtAttr(stmt, SQL_ATTR_PARAMSET_SIZE, 3); // <--- array binding
SQLBindParameter(stmt, 1, p1 ..);
SQLBindParameter(stmt, 2, p2 ..);
SQLExecDirect(stmt,
(SQLCHAR *)"DELETE FROM T1 WHERE I1>? AND I1<?”,
SQL_NTS); do {
SQLRowCount(stmt, &rowcount); printf("%d\n", rowcount); totalRowcount += rowcount; rc = SQLMoreResults(stmt);
} while (rc != SQL_NO_DATA);
259 Upgrade
Other Changes printf(“totalRowcount = %d\n”, totalRowCount);
Execution Results
9 => This is affected row count of DELETE FROM T1 WHERE I1>10 AND I1<20
199 => This is affected row count of DELETE FROM T1 WHERE I1>100 AND I1<200
0 => This is affected row count of DELETE FROM T1 WHERE I1>11 AND I1<14
(No record exists because it is deleted by the first execution.)
208 => This is the total of affected row counts
Each execution result of syntax the argument indicates is created, and then sent to ODBC-CLI. When multiple results are created like this, each data can move for next result with SQLMoreResults() and have its result with SQLRowCount().
If you sum up 3results above in Altibase4, SQLRowCount() returns 208.
If you want same results in Altibase 5 as in Altibase 4, you may execute SQLMoreResults() repeatedly until it returns SQL_NO_DATA, and then add this result to result of SQLRowCount().
Unlimited Array Execute, Array Fetch
Altibase doesn’t have restrictions on Array Execute and Array Fetch as buffer size.
Therefore, you can bind array in the allocated memory and can use CM_BUFF_SIZE no more.
Unavailable Properties
Batch Processing Mode
You can’t use batch keyword of connection string and SQL_ATTR_BATCH.
SQL_ATTR_MAX_ROWS
This indicates to specify the number of prefetched row for better performance in Altibase4. However, this property is similar to LIMIT of SELECT statement following ODBC. This option isn’t available for ODBC-CLI of Altibase.
Therefore, if you specify property above as SQLSetStmtAttr(), this asks your attention because error occurs like ‘Optional feature not implemented’.
ODBC User’s Manual 260
Index
B
Basic Programming Steps
Binding Parameters
C
C Data Types
Converting C Data into SQL Data types
Converting SQL Data into C Data Types
D
Data Type
E
Example of Procedure test Program 217
F
Function Conformance Level
Function Overview
L
Limitation on ALTER SESSION statements 257
LOB
LOB Data Types
M
Managing Diagnosis Messages
O
ODBC Error Codes
Open Database Connectivity
P
Programing Considerations
S
Sample of Simple Basic Program
Sample of Using Metadata 210
SQL Data Types
SQLAllocConnect
SQLAllocEnv
SQLAllocHandle
SQLAllocStmt
SQL_ATTR_MAX_ROWS
SQLBindCol
SQLBindFileToCol
SQLBindFileToParam
SQLBindParameter
SQL_BIT 243
261
SQL_BYTE
SQLCloseCursor
SQLColAttribute
SQLColumns
SQLConnect
SQLDescribeCol
SQLDescribeParam
SQLDisconnect
SQLDriverConnect
SQLEndTran
SQLError
SQLExecDirect
SQLExecute
SQLFetch
SQLFetchScroll
SQLForeignKeys
SQLFreeConnect
SQLFreeEnv
SQLFreeHandle
SQLFreeLob
SQLFreeStmt
SQLGetConnectAttr
SQLGetData
SQLGetDescField
SQLGetDescRec
SQLGetDiagField
SQLGetDiagRec
SQLGetEnvAttr
SQLGetFunctions
SQLGetInfo
SQLGetLob
SQLGetLobLength
SQLGetPlan
SQLGetStmtAttr
SQLGetTypeInfo
SQLMoreResult
SQLMoreResults()
SQLNativeSql
SQL_NIBBLE 247
SQLNumParams
SQLNumResultCols
SQLParamData
SQLParamData()
SQLPrepare
SQLPrimaryKeys
SQLProcedureColumns
SQLProcedures
SQLPutData
SQLPutData()
SQLPutLob
SQLRowCount
SQLRowCount()
SQLSetConnectAttr
SQLSetDescField
SQLSetEnvAttr
SQLSetStmtAttr
SQLStatistics
SQLTablePrivileges
SQLTables
SQLTransact
SQL_TYPE_TIMESTAMP
SQL_VARBIT 243
State Transition Tables
Statement State Transition-related Errors
StrLen_or_IndPtr
U
Using SQLFreeStmt() function
Using the ODBC
Using Windows ODBC versus Using UNIX ODBC
262
advertisement
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project