• Download: http://ftp.cubrid.org/CUBRID_Drivers/ODBC_Driver/

Changed and Enhanced Features:

• APIS-184 - ODBC] how to do auto_commit off in C#

Fixed bugs:

• APIS-152 - ODBC] Error when executing a query in Korean
• APIS-155 - Run time error when selecting in CUBRID ODBC Driver
• APIS-156 - user reported> ODBC driver has a Fetch error
• APIS-443 - Fetch error in using openrowset() call in sql server
• APIS-445 - sql server core dump if openrowset() call on numeric field from ODBC driver
• APIS-536 - ODBC] The returned value of OdbcConnection.Database is incorrect
• APIS-538 - ODBC] A problem of the returned value of OdbcConnection.DataSource property
• APIS-539 - ODBC] OdbcDataReader.GetDataTypeName doesn't work
• APIS-540 - ODBC] OdbcDataReader GetInt16, GetInt32 doesn't returns expected exception when read an overbound integer

CUBRID ODBC Driver 9.1.0 Release Note

Functionality added or changed:

The following ODBC APIs are newly supported by CUBRID ODBC:

• SQLPrimaryKeys
• SQLForeignKeys
• SQLProcedures
• SQLProcedureColumns
• SQLTablePrivileges

All four functions are catalog functions, which can get schema information of database you connect to. CUBRID schema information is stored in system catalog table, so you can also get this information from system catalog virtual table using SQL statement.

Database schema information is important for data modeling tools like CA ERwin Data Modeler, which enables you to visualize complex data structures. It uses schema information, for example, tables of database, columns and attributes of table, the primary and foreign keys of table, and relationships between tables and so on, to get the structure of the database.

1. SQLPrimaryKeys returns the column names that make up the primary key for a table.
2. SQLForeignKeys can return:
   1. A list of foreign keys in the specified table (columns in the specified table that refer to primary keys in other tables).
   2. A list of foreign keys in other tables that refer to the primary key in the specified table.
3. SQLProcedures returns returns the list of function/procedure names stored in a specific data source.
   1. Stored functions/procedures are blocks of code that have a flow of commands for data manipulation and are easy to manipulate and administer. CUBRID supports to develop stored functions and procedures in Java. Java stored functions/procedures are executed on the JVM (Java Virtual Machine) hosted by CUBRID.
4. SQLProcedureColumns returns the list of input and output parameters for the specified procedures, but not including the return columns.
5. SQLTablePrivileges returns a list of tables and the privileges associated with each table, which represents authorization information of the classes for which the current user has authorization in the database.

Fixed bugs:

• SQLFetchScroll: When parameter FetchOrientation is SQL_FETCH_LAST, SQLFetchScroll should return the last complete rowset in the result set. But it will return the first, not the last.
  • SQLFetchScroll is used to 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 or by bookmark.
• SQLSetPos: Application will crash when calling SQLSetPos.
  • SQLSetPos sets the cursor position in a rowset and allows an application to refresh, update or delete data in the result set.
• SQLSetPos: The default value of statement attribute SQL_ATTR_ROW_ARRAY_SIZE is 1, which is the number of rows returned by each call to SQLFetch or SQLFetchScroll. If we set this attribute to value that is more than 1, SQLSetPos can't work correctly.
• SQLStatistics and SQLSpecialColumns: The results of the two catalog functions are not valid.
  
  SQLStatistics retrieves a list of statistics about a single table and the indexes associated with the table. SQLSpecialColumns retrieves the following information about columns within a specified table:
  • When IdentifierType is SQL_BEST_ROWID, it will return information of columns that uniquely identifies a row in the table;
  • When IdentifierType is SQL_ROWVER, it will return information of columns that are automatically updated when any value in the row is updated by a transaction.
    
    No data type in CUBRID will auto-update, so it only can return the columns which compose the unique keys.

CUBRID OLEDB Driver 9.1.0.p1 Release Note (2013-05-06)

• Download: http://ftp.cubrid.org/CUBRID_Drivers/OLEDB_Driver

Fixed bugs:

• APIS-390 - Requesting schema_info unnecessarily
• APIS-398 - OLEDB] The previous Connection String doesn't work when connecting to a remote CUBRID 
• APIS-406 - OLEDB] provider 64bit doesn't work well - CLONE from CUBRIDSUS
• APIS-407 - OLEDB] Supporting Charset setting in OLEDB Provider
• APIS-457 - OLEDB] Some warnings in Test Connection, if using 64bit provider
• APIS-490 - When using CursorLocation = adUseClient, it is crashed!
• APIS-531 - OLEDB] OleDbCommand.ExecuteReader(CommandBehavior) problem
• APIS-534 - OLEDB] return value of OleDbDataAdapter.Fill(DataTable) is not right
• APIS-535 - OLEDB]if use Reader.GetBoolean to get a bit data, it will throw an exception
• APIS-541 - OLEDB] rollback of OleDbTransaction is not work

CUBRID OLEDB Driver 9.1.0 Release Note

Updates summary since beta release
=================================================

• 2 new schema rowsets added (Catalog and SQL language)
• New test cases added (localization, data types handling, extended connect)
• Changed the login internal procedure to use the connect_with_url CCI function; additional parameters included (login & query timeout, auto-commit)
• 64-bit driver library available for download
• Various updates in the source code; more code cleanup
• Additional resources made available (new tutorial and short video)
• Some improvements in LOB handling
• New Installer version

General development notes
=================================================

• The 8.4.1 provider code is based on the legacy CUBRID 3.1 OLE DB provider code
• Various enhancements and support for latest CUBRID releases has been implemented
• We have focused on supporting OLE DB Consumer templates (http://msdn.microsoft.com/en-us/library/8k76sd16%28v=vs.80%29.aspx). Direct OLE DB interfaces should work as well, but the technology is deprecated. 
• A full suite of open source test cases is now part of the driver code base release
• Regarding .NET support (via System.Data.OleDb namespace), we are encouraging the use of the fully managed CUBRID ADO.NET driver instead (http://www.cubrid.org/wiki_apis/entry/cubrid-ado-net-driver).
• The code is released under the BSD license (http://www.cubrid.org/bsd_license).

Release components

==============================================

• The driver source code (http://svn.cubrid.org/cubridapis/oledb/branches/RB-8.4.1/Source/)
• The driver OLE DB Data Provider compiled library x32/x64 release (CUBRIDProvider.dll)
• Win32 Driver Installer (with a short video)
• Release notes
• Test cases suite : 60+ OLE DB Consumer test cases (see the attachments for a test suite run output)
• 3 Tutorials

Known limitations
=================================================

• There is limited support for queries not based on tables structures, in terms of columns automatic definitions
• There is no full support yet for BLOB/BLOB Dynamic Accessors
• Update() support is restricted to Auto-Commit mode = Off, which must be explicitly stated via session transaction.
• Not all schema are implemented as defined here: http://msdn.microsoft.com/en-us/library/a6fhbff0%28v=vs.71%29.aspx.
• More test coverage is required for testing non-standard data types
• We are supporting mainly C++ OLE DB templates; there is limited or no support for other driver usages (direct interfaces
• Very limited support for some special data types: SET, MUTISET and SEQUENCE

What's next/To-Do
=================================================

• Re-Generate and publish the Doxygen driver documentation
• Continue to improve support for BLOB/CLOB
• Make available in write-mode additional connection properties: loging & query timeouts
• Add more test cases coverage, in particular for CUBRID specific data types and for .NET OleDb access.
• Remove the data provider distribution from the CUBRID standard installer
• Continue SVN cleanup and update Trunk

9.1.0.p1

Fixed bugs:

• [APIS-390] - 수행하지 않는(필요없는) schema_info 요청
• [APIS-398] - OLEDB] Driver를 사용하여 원격지의 CUBRID 연결 시 기존 Connection String이 적용되지 않음
• [APIS-406] - OLEDB] provider 64비트가 정상동작하지 않음 - CLONE from CUBRIDSUS
• [APIS-407] - OLEDB] OLEDB 프로바이더에 charset 지정 가능하도록 수정
• [APIS-457] - OLEDB] Some warnings in Test Connection, if using 64bit provider
• [APIS-490] - When using CursorLocation = adUseClient, it is crashed!
• [APIS-531] - OLEDB] OleDbCommand.ExecuteReader(CommandBehavior) problem
• [APIS-534] - OLEDB] return value of OleDbDataAdapter.Fill(DataTable) is not right
• [APIS-535] - OLEDB]if use Reader.GetBoolean to get a bit data, it will throw an exception
• [APIS-541] - OLEDB] rollback of OleDbTransaction is not work

.NET Framework is a software framework for Microsoft Windows operating systems. It includes a large library, and it supports several programming languages which allows language interoperability (each language can utilize code written in other languages). The .NET library is available to all the programming languages that .NET supports. A data provider in the .NET Framework serves as a bridge between an application and a data source; a data provider is used to retrieve data from a data source and to reconcile changes to that data back to the data source.

OLEDB driver source code is distributed under the terms of BSD open source license.

CUBRID ODBC driver supports ODBC version 3.52, ODBC core, and some of Level 1 and Level 2 APIs. Since it has been developed based on ODBC Spec 3.x, backward compatibility is not completely ensured for programs written using ODBC Spec 2.x.

ODBC driver source code is distributed under the terms of BSD open source license.

Download

Download a new installation package file which name is "CUBRID_OLEDB_Provider-<version>-win32-x64.zip".

It will install both CUBRIDProvider32.dll and CUBRIDPRovider64.dll at once. You can find a CUBRID OLEDB Provider installer at:

http://ftp.cubrid.org/CUBRID_Drivers/OLEDB_Driver/ or

http://www.cubrid.org/?mid=downloads&item=oledb_driver

Driver Installation

Run a CUBRID OLEDB Provider Installer (exe) and click the Next / Install Button.

In your installation directory, you can see the following DLL files and uninstall. exe.

DB Connection

Data Link Properties Dialog Box

To access this dialog box in Visual Studio .NET, select Connect to Database from the Tools menu or click the Connect to Database icon in Server Explorer.
You also can open this dialog box by double-clicking a universal data link (.udl) file in Windows Explorer, and in a variety of other ways, including programmatically.

1）you must install Visual Studio first, click “Connect to Database”

2) Choose <other>,and .Net Famework Data Provider for OLE DB, Then click continue button

3) Choose CUBRID OLE DB Provider, then click Data links button

4) Fill in the information, and click Test Connection button, if driver connect database successful, success dialog will pop up.
More information can found in msdn: http://msdn.microsoft.com/en-us/library/79t8s5dk(v=vs.71).aspx

5) A simple method of open dialog
First, create a text file, and modify extension to *.udl: 1.txt -> 1.udl

Second, double click 1.udl, dialog will pop up.

 6)  Setting method of character set

Connection String:

"Provider=CUBRIDProvider;Data Source=demodb;Location=10.34.64.104;User ID=dba;Password=;Port=30000;Fetch Size=100;Charset=utf-8;"

Configuration

The following tutorials will help you when developing your application thru CUBRID OLEDB Provider. 

• CUBRID OLEDB Overview
• OLEDB Connection String
• Configuring Connection String
• OLEDB Consumer Templates Coding

Requirements

To install the PHP Driver using PECL, you need to have CUBRID Database installed in your system since PHP Driver is dependent on CUBRID CCI API.

Installation

Type the following command to install the latest version of CUBRID PHP Driver.

If you need older version of the driver, you can indicate its exact version like:

During the installation you will be prompted to enter "CUBRID base install dir [!autodetect] :". Just to make sure your installation goes smoothly, enter the full path to the directory where you have installed CUBRID. Ex: if CUBRID was installed at /home/cubridtest/CUBRID, then enter /home/cubridtest/CUBRID.

a) If you have Centos 6.0 and above or Fedora 15 and above, then do not edit the php.ini as stated in step b and instead create a file named cubrid.ini in which you add only the line extension=cubrid.so. This file has to be placed in the /etc/php.d folder.

b) Edit the php.ini (default location: /etc/php5/apache2/php.ini or /etc/php.ini) and add the following two lines at the end of the file.

To apply the changes, restart your Web Server.

What If I don't have PECL installed?

If you do not have PECL installed, follow these instructions to get it installed in your system.

Ubuntu Instructions

In order to install CUBRID-PHP API on Ubuntu, you will need PHP Development Tools (phpize) and pear packager.

• Type the following command to install phpize: 
  
  sudo apt-get install php5-dev
• Type the following command to install pear package: 
  sudo apt-get install php-pear

Then follow the above instructions to install CUBRID PHP Driver.

Fedora/CentOS Instructions

In order to install CUBRID-PHP API on Fedora/CentOS, you will need PHP PEAR and phpize packages.

• Install phpize. Remember that php-dev should be either PHP 5.2.x compatible or PHP 5.3.x since CUBRID-PHP Extension is developed for these PHP versions. If your Linux distribution installs earlier version, you need to update it. 
  yum install php-devel
• Download PEAR package: 
  wget http://pear.php.net/go-pear.phar
• Run PEAR package with PHP: 
  php go-pear.phar

What's Next?

If you are not familiar with the CUBRID Node.js driver yet, check out our CUBRID Node.js Tutorials. Same goes for the CUBRID SHARD basic concepts – see CUBRID SHARD.

Setting up the CUBRID SHARD environment

The first thing we need to do is set up the CUBRID SHARD and the shard databases architecture. For simplicity we will use two shard DB nodes. 

So let’s get right to it. First, in each shard DB node we will create a database and a user account, and start the database:

To do this, we will use the CUBRID command line tool “csql”. In each shard DB node, type the following commands:

Next, we have to change the shard configurations. In the node that we choose to be the shard server we have to edit three shard configuration files located in the \CUBRID\conf directory:

The first file, shard.conf, contains the shard broker parameters. The only thing to do here is to make sure that the following parameters are set:

In the second file - shard_connection.txt, we will configure the network addresses of the shard DB nodes. In our setup, one node is on the same machine as the shard server, and the other one is located somewhere else in the local area network. 

Make sure that you set the correct IP address for the second shard DB node.

The last file that we need to configure is shard_key.txt. This file configures the shard DB mapping configuration, for the shard key hash value, as follows:

This configuration means that an INSERT statement will execute on shard 0 when the shard key hash result created by default hash function is between 0 and 127, and will execute on shard 1 when the shard key hash result created by the default hash function is between 128 and 255.

We are now ready to start the CUBRID SHARD service:

We have one more step to complete before we can use Node.js with CUBRID SHARD – prepare our test data. 

Using the CUBRID Node.js 2.0 driver with CUBRID SHARD

The code examples we will show in this guide use the CUBRID Node.js 2.0 driver to perform the followings operations:

Inserting data:

Let’s see how to insert data into the shard DB nodes:

The output is:

As you can see, there are a few differences in the above code when compared to connecting and inserting in a “normal” CUBRID database setup. The most important one is the connection port. By default, the CUBRID SHARD broker port is 45011, but you can change it in the shard.conf file.

Another key difference is in the INSERT statement that we execute. Here we have to specify the shard_key column using a shard SQL hint. It will tell the shard broker which shard DB to choose according to the setup we made in the shard_key.txt file.

Tip: For more information about shard SQL hints see Selecting a Shard DB through the Shard SQL Hint.

So, let’s see what CUBRID SHARD did when it executed these statements, by checking the shard broker log file located in \CUBRID\log\broker\proxy_log:

Querying the CUBRID SHARD DB nodes

In the next section we will learn how to retrieve the data from our shard DB nodes. The only thing that is different here is that CUBRID SHARD uses the (old) 8.4.x TCP protocol for query execution, so before we can run a query we have to tell Node.js driver to use this protocol by calling the setEnforceOldQueryProtocol() method. Now we can execute our queries, again using the shard SQL hints:

Here we used the /*+ shard_id(0) */ SQL hint to specify which shard DB we are targeting. As expected, we have retrieved the data from the first shard DB node:

To get the data from the other shard DB the only thing we have to change is the parameter of the SQL hint to 1: /*+ shard_id(1) */ and we will get the desired results:

What if we want to get data from an invalid shard id, for example if we run “select * from student /*+ shard_id(2) */”? The shard broker will obviously return an error. So let’s look at the log file after we ran this query:

References and links

We hope you enjoyed using the CUBRID Node.js 2.0 driver in a sharding environment!

Please let us know your feedback and suggestions, so we can improve! And do not forget, tryout the CUBRID Node.js 2.0 driver!

• [Installing CUBRID PDO Driver using PECL] (Linux)
• [Downloading and Installing Precompiled CUBRID PHP/PDO Driver (Windows)]
• Create a CUBRID Database VM with Vagrant and Chef Cookbook under 5 minutes (Linux)
• [Build CUBRID PDO Driver on Mac OS X through PECL using CCI Driver] (Mac OS X)

Requirements

To install the PDO Driver using PECL, you need to have CUBRID Database installed in your system since PDO Driver is dependent on CUBRID CCI API.

Installation

Type the following command to install the latest version of CUBRID PDO Driver.

If you need older version of the driver, you can indicate its exact version like:

During the installation you will be prompted to enter "CUBRID base install dir [!autodetect] :". Just to make sure your installation goes smoothly, enter the full path to the directory where you have installed CUBRID. Ex: if CUBRID was installed at /home/cubridtest/CUBRID, then enter /home/cubridtest/CUBRID.

a) If you have Centos 6.0 and above, Fedora 15 and above, or Ubuntu 13.04 and above, create a file named pdo_cubrid.ini in /etc/php5/conf.d/ or /etc/php.d (check where in your system other .ini files are located).

b) Otherwise, edit the php.ini (default location: /etc/php5/apache2/php.ini or /etc/php.ini).

Then in the above .ini file add the following line:

To apply the changes, restart your Web Server.

What If I don't have PECL installed?

• Install PECL packager

What's Next?

Download CCI driver

CUBRID PDO driver has a dynamic dependency on CCI driver. You can download either 64 or 32 bit version of CUBRID CCI diver depending on your Mac OS architecture. Once you download it, you need to copy the contents of the /lib directory to /usr/lib and the contents of /include directory to /usr/include. The following example illustrates how to extract a 64-bit version and copy its contents.

Install PDO driver using PECL

Type the following command to install the latest version of CUBRID PDO Driver from PECL repository.

If you need older version of the driver, you can indicate its exact version like:

During the installation you will be prompted to enter "CUBRID base install dir [!autodetect]:". Enter that same directory where we have extracted CUBRID CCI driver files.

Configure php.ini

Now find the php.ini file and add the following line which instructs your Web server or FastCGI Process Manager to load CUBRID PDO extension with the next restart.

Done! Now restart your Web server to load CUBRID extension.

Test CUBRID PHP API

Create a simple test.php file with the following contents:

In your browser visit http://localhost/test.php. Search for "pdo_cubrid". You should see entries like Version, CCI Version, and CUBRID Version.

If you have any questions, please ask them at our Q&A site. If any issues with installation, post on our forum.

Requirements

• Windows Vista/7
• CUBRID 8.4.1 (The CUBRID version must match the Driver version)
• Visual Studio 2010 Express Edition (http://www.microsoft.com/visualstudio/en-us/products/2010-editions/express)
• .NET framework 3.5 or above (http://www.microsoft.com/download/en/details.aspx?id=21)

CUBRID OLE DB Data Provider

Before you start to developing applications with CUBRID, you will need the provider library (CUBRIDProvider.dll). Make sure to download the appropiate DLL according to your CUBRID installation. You can check the CUBRID version by using the command "cubrid --version". You have several options:

Use official installer

Use the official CUBRID OLED DB Data Provider Installer. You can follow this 1 minute video tutorial to see how to install CUBRIDProvider using the installer.

Download the compiled libraries

• 32 bit OLEDB Data Provider
• 64 bit OLEDB Data Provider

If you choose to install it manually (by just downloading the CUBRIDProvider.dll), you need to properly register the driver before you can use it, through one of the following registration methods:

1. Download the CUBRIDProvider.tlb file from here, and make sure it is located in the same folder with the CUBRIDProvider.dll, and run the following command in that folder:

2. Download the CUBRIDProvider.reg file from here, update it by specifying your own path location of the CUBRIDProvider.dll (the CUBRIDProvider.reg file you downloaded will contain by default the following location: C:\CUBRID\oledb\CUBRIDProvider.dll) and then run the following command:

Compile from source code

Checkout the code from the SVN repository:http://svn.cubrid.org/cubridapis/oledb/branches/RB-8.4.1/Source/.

For compiling the source code and the example in this tutorial, use Microsoft Visual Studio Express edition – you can download it from: http://www.microsoft.com/express/Downloads/#2010-Visual-CPP. Please make sure you download the appropriate version – 32 or 64-bit.

Compile or modify the installer

If you wish to make certain changes to our OLEDB Data Provider Installer, refer to [Compiling the CUBRID OLE DB installer].

9.1.0.0001

Updates summary since beta release
=================================================

• 2 new schema rowsets added (Catalog and SQL language)
• New test cases added (localization, data types handling, extended connect)
• Changed the login internal procedure to use the connect_with_url CCI function; additional parameters included (login & query timeout, auto-commit)
• 64-bit driver library available for download
• Various updates in the source code; more code cleanup
• Additional resources made available (new tutorial and short video)
• Some improvements in LOB handling
• New Installer version

General development notes
=================================================

• The 8.4.1 provider code is based on the legacy CUBRID 3.1 OLE DB provider code
• Various enhancements and support for latest CUBRID releases has been implemented
• We have focused on supporting OLE DB Consumer templates (http://msdn.microsoft.com/en-us/library/8k76sd16%28v=vs.80%29.aspx). Direct OLE DB interfaces should work as well, but the technology is deprecated. 
• A full suite of open source test cases is now part of the driver code base release
• Regarding .NET support (via System.Data.OleDb namespace), we are encouraging the use of the fully managed CUBRID ADO.NET driver instead (http://www.cubrid.org/wiki_apis/entry/cubrid-ado-net-driver).
• The code is released under the BSD license (http://www.cubrid.org/bsd_license).

Release components
==============================================

• The driver source code (http://svn.cubrid.org/cubridapis/oledb/branches/RB-8.4.1/Source/)
• The driver OLE DB Data Provider compiled library x32/x64 release (CUBRIDProvider.dll)
• Win32 Driver Installer (with a short video)
• Release notes
• Test cases suite : 60+ OLE DB Consumer test cases (see the attachments for a test suite run output)
• 3 Tutorials

Known limitations
=================================================

• There is limited support for queries not based on tables structures, in terms of columns automatic definitions
• There is no full support yet for BLOB/BLOB Dynamic Accessors
• Update() support is restricted to Auto-Commit mode = Off, which must be explicitly stated via session transaction.
• Not all schema are implemented as defined here: http://msdn.microsoft.com/en-us/library/a6fhbff0%28v=vs.71%29.aspx.
• More test coverage is required for testing non-standard data types
• We are supporting mainly C++ OLE DB templates; there is limited or no support for other driver usages (direct interfaces
• Very limited support for some special data types: SET, MUTISET and SEQUENCE

What's next/To-Do
=================================================

• Re-Generate and publish the Doxygen driver documentation
• Continue to improve support for BLOB/CLOB
• Make available in write-mode additional connection properties: loging & query timeouts
• Add more test cases coverage, in particular for CUBRID specific data types and for .NET OleDb access.
• Remove the data provider distribution from the CUBRID standard installer
• Continue SVN cleanup and update Trunk

Download

Driver Installation

Configuration

OPEN DATA SOURCES ON WINDOWS 64-BIT

Create new data source

• DSN: Give a desired name to this data source (eg. your database name).
• Description: Enter the description for this data source.
• DB Name: Enter the target database name.
• DB User: Database user name.
• Password: Database user password.
• Server Address: Database host address (localhost). You can also enter the remote server's IP address.
• Server Port: CUBRID Broker's port number. The default port is 33000.
  You can check this in your command line terminal. Type cubrid service status. In the output you will seebroker1 in the first column and the port number in the third. You will notice that the broker uses the default port number 33000. If set otherwise, enter that port number into this field.
  
  Another way to find the Broker port number is in the Broker's configuration file located at%CUBRID%confcubrid_broker.conf. See the BROKER_PORT value.
• FETCH_SIZE: Set the number of record to fetch from the database. 100 should be reasonable.

Connecting to a database directly without DSN

Before establishing a connection

Notice: This Tutorial is only available for cubrid-odbc-8.4.0 or older versions. CUBRID ODBC installation used to have a problem on 64 bit OS so we have offered a new installation package available for both 32bit and 64 bit OS since 2013-05. If your CUBRID DB Engine is running on 64 bit OS, please choose a new installation package by following : http://www.cubrid.org/wiki_apis/entry/cubrid-odbc-driver-installation-instructions

If you still wish to separately download the ODBC driver, perhaps, for remote connection when CUBRID is not installed on your machine, you can download it from http://www.cubrid.org/?mid=downloads&item=odbc_driver&os=windows or from http://ftp.cubrid.org/CUBRID_Drivers/ODBC_Driver/.

Configuration

Open Data Sources on Windows 32-bit

On you PC, first open the Control Panel => Administrative Tools. You should see a list of tools available on your Windows OS as shown below.

Double click on the Data Sources (ODBC) to open it.

OPEN DATA SOURCES ON WINDOWS 64-BIT

If you are using 64-bit Windows, you should not launch Data Sources (ODBC) as shown above as it will start 64-bit version of Data Sources (ODBC) program. Since CUBRID ODBC driver is available only in 32-bit version, we need to start 32-bit version of Data Sources (ODBC) which is located in c:\Windows\System32\odbcad32.exe. Make sure you start this one.

Create new data source

Once you started the 32-bit version of Data Sources (ODBC), navigate to the Drivers tab and make sure the CUBRID Driver is available as shown below, which will mean that it has been successfully installed on your system.

Then navigate back to the User DSN tab and click on the Add button.

In the pop-up window choose the CUBRID Driver and click the Finish button.

Fill out the fields with the necessary data as shown in the image below.

• DSN: Give a desired name to this data source (eg. your database name).
• Description: Enter the description for this data source.
• DB Name: Enter the target database name.
• DB User: Database user name.
• Password: Database user password.
• Server Address: Database host address (localhost). You can also enter the remote server's IP address.
• Server Port: CUBRID Broker's port number. The default port is 33000.
  You can check this in your command line terminal. Type cubrid service status. In the output you will see broker1 in the first column and the port number in the third. You will notice that the broker uses the default port number 33000. If set otherwise, enter that port number into this field.

  

  Another way to find the Broker port number is in the Broker's configuration file located at %CUBRID%confcubrid_broker.conf. See the BROKER_PORT value.
• FETCH_SIZE: Set the number of record to fetch from the database. 100 should be reasonable.

Once filled out, click OK button. You will see CUBRID among the User Data Sources as shown below.

Connecting to a database directly without DSN

It is also possible to connect to the CUBRID database directly in the application source code indicating the connecting string. In this case, use the following connection string.

Before establishing a connection

Make sure that your database is started before you try to connect or link to a CUBRID database. Otherwise, you will receive an ODBC call failed error.

This is all you need to do in order to connect to a CUBRID database using the ODBC driver.

• Driver Build: ODBC 9.1, OLEDB 9.1
• Server Build: CUBRID 9.1 (9.1.0.0212) (64bit release build for linux_gnu)
• Test Platform: Windows7 32bit, Windows XP 32bit, Windows2003 64bit
• .Net Framework: 3.5

2.     Test Results

3.     Bug status

4.     Function Testing

5.     Issues

  1) Some CUBRID Date Type Name are not consistent with OLEDB Date Type Name. It may be ambiguous to users. We think it should be optimized. Please refer http://jira.cubrid.org/browse/APIS-30

  2) The CUBRID OLEDB Interface manual should describe the data type mapping between CUBRID and OLEDB, like the ODBC manual           http://www.cubrid.org/manual/91/en/api/odbc.html. It will help    user to develop with OLEDB interface more easily

  3) Some properties value of db connection should be consistent with MSDN. It will help users use CUBRID more clearly. Such   as http://jira.cubrid.org/browse/APIS-532 

9.1.0

Functionality added or changed:

The following ODBC APIs are newly supported by CUBRID ODBC:

• SQLPrimaryKeys
• SQLForeignKeys
• SQLProcedures
• SQLProcedureColumns
• SQLTablePrivileges

All four functions are catalog functions, which can get schema information of database you connect to. CUBRID schema information is stored in system catalog table, so you can also get this information from system catalog virtual table using SQL statement.

Database schema information is important for data modeling tools like CA ERwin Data Modeler, which enables you to visualize complex data structures. It uses schema information, for example, tables of database, columns and attributes of table, the primary and foreign keys of table, and relationships between tables and so on, to get the structure of the database.

1. SQLPrimaryKeys returns the column names that make up the primary key for a table.
2. SQLForeignKeys can return:
   1. A list of foreign keys in the specified table (columns in the specified table that refer to primary keys in other tables).
   2. A list of foreign keys in other tables that refer to the primary key in the specified table.
3. SQLProcedures returns returns the list of function/procedure names stored in a specific data source.
   1. Stored functions/procedures are blocks of code that have a flow of commands for data manipulation and are easy to manipulate and administer. CUBRID supports to develop stored functions and procedures in Java. Java stored functions/procedures are executed on the JVM (Java Virtual Machine) hosted by CUBRID.
4. SQLProcedureColumns returns the list of input and output parameters for the specified procedures, but not including the return columns.
5. SQLTablePrivileges returns a list of tables and the privileges associated with each table, which represents authorization information of the classes for which the current user has authorization in the database.

Fixed bugs:

• SQLFetchScroll: When parameter FetchOrientation is SQL_FETCH_LAST, SQLFetchScroll should return the last complete rowset in the result set. But it will return the first, not the last.
  • SQLFetchScroll is used to 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 or by bookmark.
• SQLSetPos: Application will crash when calling SQLSetPos.
  • SQLSetPos sets the cursor position in a rowset and allows an application to refresh, update or delete data in the result set.
• SQLSetPos: The default value of statement attribute SQL_ATTR_ROW_ARRAY_SIZE is 1, which is the number of rows returned by each call to SQLFetch or SQLFetchScroll. If we set this attribute to value that is more than 1, SQLSetPos can't work correctly.
• SQLStatistics and SQLSpecialColumns: The results of the two catalog functions are not valid.
  
  SQLStatistics retrieves a list of statistics about a single table and the indexes associated with the table. SQLSpecialColumns retrieves the following information about columns within a specified table:
  • When IdentifierType is SQL_BEST_ROWID, it will return information of columns that uniquely identifies a row in the table;
  • When IdentifierType is SQL_ROWVER, it will return information of columns that are automatically updated when any value in the row is updated by a transaction.
    
    No data type in CUBRID will auto-update, so it only can return the columns which compose the unique keys.

9.1.0.p1

Changed and Enhanced Features:

• [APIS-184] - [ODBC]how to do auto_commit off in C#

Fixed bugs:

• [APIS-152] - [ODBC] 한글 쿼리 실행 시 에러
• [APIS-155] - CUBRID ODBC Driver에서 SELECT 수행시 런타임 오류 발생
• [APIS-156] - user reported> ODBC driver has a Fetch error
• [APIS-443] - Fetch error in using openrowset() call in sql server
• [APIS-445] - sql server core dump if openrowset() call on numeric field from ODBC driver
• [APIS-536] - [ODBC] The returned value of OdbcConnection.Database is incorrect
• [APIS-538] - [ODBC] A problem of the returned value of OdbcConnection.DataSource property
• [APIS-539] - [ODBC] OdbcDataReader.GetDataTypeName doesn't work
• [APIS-540] - [ODBC] OdbcDataReader GetInt16, GetInt32 doesn't returns expected exception when read an overbound integer

1. Test Info

• Driver Build: ODBC 9.1
• Server Build: CUBRID 9.1 (9.1.0.0212) (64bit release build for linux_gnu)
• Test Platform: Windows7 32bit, Windows XP 32bit, Windows2003 64bit
• .Net Framework: 3.5

2.Test Results

3.Bug status

4. Function Testing

5.  Issues

None

In order to add CUBRID JDBC driver to your maven project, add the following dependency to your project's pom.xml file:

Remember to indicate the appropriate version number. The list of available versions can be found at http://maven.cubrid.org/cubrid/cubrid-jdbc/.

You should also add the repository information into your pom.xml file:

This concludes the maven tutorial. If you have any question, please post it on our Q&A Site or on our forum.

Introduction

The CUBRID OLE DB installer is open-source code, BSD licensed and built using NSIS.

NSIS (Nullsoft Scriptable Install System) is a professional open source system for creating Windows installers. It is designed to be as small and flexible as possible and is therefore very suitable for internet distribution.

We choosed NSIS because it is widely used in open source projects, it is script-based and allows us to create the logic to handle even the most complex installation tasks. 

Updating and compiling the installer

The source code for CUBRID OLEDB Installer is located in the CUBRID SVN repository:
http://svn.cubrid.org/cubridapis/oledb/branches/RB-xxx/installer/installer.nsi

If you want to compile the installer yourself, (and maybe change it,) we recommend the followings:

• Download the installer script source code - see the above specified location
• Update the script, if needed; we recommend using HM NIS Edit tool.
  
  "HM NIS Edit is the best Editor/IDE for Nullsoft Scriptable Install System (NSIS). Its useful for experts and beginners in the creation of Setup programs with the NSIS. Its Script Wizard will help you to create standard Setup programs with only few clicks, also its InstallOptions designer will help you to create your own custom pages with a friendly drag and drop interface."
• Compile the installer. (If you use HM NIS Edit it is just a matter of clicking a toolbar button.)

Notes:

By default, the installer script code is for creating the x32 installer. If you want to create the x64 installer,

please update the installer script first by commenting/uncommenting the appropiate lines of code (just search for "64" in the script).

Looking into the CUBRID documentation (http://www.cubrid.org/manual/841/en/Configuring%20Connection%20Strings), you will find out that in order touse the CUBRID OLE DB Provider, the connection string must be built using the following "pieces":

For example, to connect to the demodb database, using the public user, on a local CUBRID installation, the connection string will be:

Please note that in the next provider releases, you will be able to specify in the connection string additional information such as:

• Connection encoding
• Auto-commit mode

• 1 Overview
• 2 Getting Help
• 3 Preparing the Environment
  • 3.1 Preparing CUBRID
  • 3.2 Preparing Ruby
    • 3.2.1 On Windows
      • 3.2.1.1 Install Ruby
      • 3.2.1.2 Install Ruby Driver for CUBRID
    • 3.2.2 On Linux
      • 3.2.2.1 Install Ruby
      • 3.2.2.2 Install Ruby Driver for CUBRID
        • 3.2.2.2.1 Install Ruby Gem
        • 3.2.2.2.2 Manually Build the Library
        • 3.2.2.2.3 Example
• 4 Ruby API
  • 4.1 Connection Class
    • 4.1.1 Data Constants
    • 4.1.2 auto_commit=
    • 4.1.3 auto_commit?
    • 4.1.4 connect
    • 4.1.5 close
    • 4.1.6 commit
    • 4.1.7 rollback
    • 4.1.8 glo_new
    • 4.1.9 query
    • 4.1.10 prepare
    • 4.1.11 to_s
    • 4.1.12 server_version
  • 4.2 Statement Class
    • 4.2.1 Data Types
    • 4.2.2 affected_rows
    • 4.2.3 bind
    • 4.2.4 close
    • 4.2.5 column_info
    • 4.2.6 each
    • 4.2.7 each_hash
    • 4.2.8 execute
    • 4.2.9 fetch
    • 4.2.10 fetch_hash
    • 4.2.11 get_oid
  • 4.3 Oid Class
    • 4.3.1 [!](col_name)
    • 4.3.2 [!]=(col_name, obj)
    • 4.3.3 drop
    • 4.3.4 each
    • 4.3.5 lock
    • 4.3.6 refresh
    • 4.3.7 save
    • 4.3.8 table
    • 4.3.9 to_hash
    • 4.3.10 to_s
• 5 See also

Overview

This tutorial will explain all steps that you need to perform in order to connect to CUBRID Database and run SQL statements through Ruby programming language.

At any time if you feel lost somewhere, you can always visit the main page for Ruby Programming to start from the beginning.

Getting Help

If you have any troubles connecting to CUBRID through Ruby, post your questions to Ruby Forum at http://www.cubrid.org/forum.

Preparing the Environment

Preparing CUBRID

1. First thing you have to do is to make sure you have installed CUBRID Database according to all the steps explained in Install CUBRID. If you have not installed CUBRID yet, Download CUBRID and follow the Installation Instructions. In this tutorial I will be using the latest stable release CUBRID 9.1.0. On my machine it is installed in C:CUBRID. However, you do not have to worry much about it, as the CUBRID Installer automatically adds its location path to the Windows environment.
2. NOTE For Windows users: Make sure you have installed Java Development Kit (JDK) and Microsoft C++ 2008 Redistributable Package.

Preparing Ruby

On Windows

Install Ruby

You can download Ruby Installer from various places. I prefer to Download Ruby Installer from http://rubyinstaller.org. At this point you will see me using pure Ruby 1.8.7-p299. Currently Ruby 1.9.1 is not supported, as the Ruby Driver for CUBRID has been compiled in the 1.8.7 environment. But we have already started building for 1.9.1, so it will be available soon.

Install Ruby Driver for CUBRID

If you have installed the above mentioned Ruby 1.8.7-p299, you should already have RubyGem installed. RubyGem is required to install additional external packages such as CUBRID Database driver, ActiveRecord, and other similar extensions. In order to install the Ruby Driver for CUBRID, in the command line type gem install cubrid as shown below.

C:\Ruby> gem install cubrid

Successfully installed cubrid-0.65-x86-mingw32

1 gem installed

Installing ri documentation for cubrid-0.65-x86-mingw32...

Installing RDoc documentation for cubrid-0.65-x86-mingw32...

At this point you should see the message about the successful installation of cubrid-0.65-x86-mingw32 driver. The Ruby Driver provides the same functions as the original CUBRID CCI (C Interface) Library does. Below you will see sample tests which illustrate how to communicate with the CUBRID Database.

On Linux

Install Ruby

In order to install Ruby, we will use the generic Linux command. In this tutorial we will work under Ubuntu 10.4, and install Ruby 1.8.7. Type the following command to get Ruby and other necessary packages installed together.

sudo apt-get -y install ruby1.8-dev ruby1.8 ri1.8 rdoc1.8 irb1.8 libreadline-ruby1.8 libruby1.8 libopenssl-ruby rubygems1.8

sudo ln -s /usr/bin/ruby1.8 /usr/bin/ruby

sudo ln -s /usr/bin/rdoc1.8 /usr/bin/rdoc

sudo ln -s /usr/bin/irb1.8 /usr/bin/irb

sudo ln -s /usr/bin/ri1.8 /usr/bin/ri

The first line indicates which packages should be installed. Notice that I am installing Ruby 1.8 version. At this moment Ruby 1.9.1 is not supported. But we have already started building for 1.9.1, so it will be available soon. The rest four lines create symbol links so that you are able to run the commands link "ruby", "rdoc", "irb", and "ri". Actually, you will need only the first one.

Install Ruby Driver for CUBRID

On Linux there are two ways to get Ruby Driver for CUBRID installed.

1. Install Ruby Gem.
2. Manually compile the code and install the library.

Install Ruby Gem

• CUBRID gem has been successfully pushed to RubyGems.org. So, now on Linux users can get CUBRID connector through gem.
• Add the -E flag when installing the gem with sudo like "sudo -E gem install cubrid". The -E flag is necessary to make sure sudo does not reset the user path where CUBRID Database has been installed.

Manually Build the Library

• Download source code of Ruby Driver for CUBRID.
• Extract, then run the following command in the terminal, which means that you are running the Ruby code within extconf.rb file. It will create a Makefile.

ruby extconf.rb

• After the Makefile has been successfully created, type the following command to install the driver in your system.

make install

That's all! To see if everything has successfully been installed, print out the CUBRID Database version. Remember that in order to connect to a certain database, you have to first start that database. Otherwise, you will receive an error.

Example

Create a file called "testcubrid.rb" and paste the following Ruby code.

require 'rubygems'
require 'cubrid'
db = 'demodb'
con = Cubrid.connect(db)
if con
	puts "connection established"
	puts "CUBRID Database version is: #{con.server_version}"
	con.close()
else
	puts "Connection could not be established"
end

Then type the following commands in the terminal.

cubrid service start
cubrid server start demodb
ruby --rubygems testcubrid.rb

1. The first line will start CUBRID services.
2. The second line will start the database called "demodb".
3. The third line will run the Ruby code inside "testcurbid.rb" file.

You should see the following output.

connection established
CUBRID Database version is: 8.2.2.0261

Ruby API

Connection Class

Data Constants

Description

The following Data Types represent the Cubrid class data type constants declared in the Ruby API.

Syntax

Cubrid::DATE

auto_commit=

Description

This method is used to set the auto_commit mode of the current connection. If auto_commit is set to true, after every Statement.execute call the transaction will be immediately committed.

Syntax

auto_commit= true or false ? nil

Return value

• nil

auto_commit?

Description

This method is used to determine whether auto_commit mode of the current connection is set to true or false.

Syntax

auto_commit? ? true or false

Return value

• true: auto_commit is set to true
• false: auto_commit is set to false

connect

Description

This method is used to establish the connection with the database server by using the given information such as the database name, server address, port number, username and password. If the username and password are not set, public is used as default the default username and "" (empty password) is used as a password.

Example

@con = Cubrid.connect('db_name', 'host', port, 'db_user', 'db_password')
 
#OR
 
@con = Cubrid.connect('db_name')

• db_name : a string representing the database name
• host : a string representing the host name of the server (by default it is localhost)
• port : an integer representing the server port (by default it is 30000 - thirty thousand)
• db_user : a string representing the database user name (by default it is public)
• db_passwd : a string representing the database user password (by default it is "" - empty password)

Return Value

• @con: The connection has successfully been established!

• nil: Filed to establish the connection.

close

Description

This method is used to terminate the connection with the server. All pending Statements will also be closed.

Example

@con.close()

commit

Description

This method is used to commit the transactions being performed currently in the connection.

Example

@con.commit

Return value

• nil

rollback

Description

This method is used to rollback the last performed transactions. If the transaction is terminated, all Statement objects will also be closed.

Example

@con.rollback

Return value

• nil

glo_new

Description

This method is used to create a new GLO object. The glo_new method will return the OID of the newly created object. When glo_new is called CUBRID provides GLO which will store the binary data. Later GLO object can be directly accessed by OID.

Syntax

glo_new(classname <, filename>) ? OID 

Return value

• OID:

Example

The below example illustrates how to use glo_new method. When called, the data inside the file, whose filename has been passed as a parameter, will be stored in the database. If the filename is not indicated, the method will create an empty GLO object.

query

Description

This method directly executes the SQL statement, which has been passed as a parameter, without a need to perform the execute method.

Syntax

query(sql [!, option]) ? Statement
 
OR
 
query(sql [!, option]) { |row|
  ...
} ? nil 

Parameters

• sql : a string representing the SQL statement
• option: [!Optional] If Cubrid::INCLUDE_OID is passed as an option, the query method will behave like the prepare method.

Return value

• stmt: The request handler
• nil: The query has not been executed

Examples

A.

sql = "INSERT INTO table1 (id, name) VALUES (1, 'Ruby')"

stmt = @con.query(sql)

@con.commit

B.

con = Cubrid.connect('demodb')
stmt = con.query('SELECT * FROM db_user')
 
while row = stmt.fetch
   print row
end

stmt.close
stmt = con.query('SELECT * FROM db_user') { |row|
   print row
}

con.close

prepare

Description

This method is used to prepare an SQL statement.

Syntax

prepare(sql <, option>) ? Statement
 
#OR
 
prepare(sql <, option>) { |stmt|
  ...
} ? nil 

Parameters

• sql : a string representing the SQL statement
• option : [!Optional] If Cubrid::INCLUDE_OID is passed as an option, the returned results will include OID, which can be later retrieved by calling stmt.get_oid method.

Return Value

• stmt: The request handle

• nil: Filed to prepare the SQL statement.

Example

sql = "INSERT INTO table1 (id, name) VALUES (?, ?)"
stmt = @con.prepare(sql)
con = Cubrid.connect('demodb')
stmt = con.prepare('SELECT * FROM db_user')
stmt.execute

r = stmt.fetch

stmt.close
con.close
con.prepare('SELECT * FROM db_user') { |stmt|
   stmt.execute
   r = stmt.fetch
}

con.close

to_s

Description

This method is used to get the current connection information.

Example

# same as
# puts @con
connection_info = @con.to_s

Return values

• connection_info : a string representing the connection information.

server_version

Description

This method is used to get the version of the database server.

Example

version = @con.server_version

Return values

• version : a string representing the version of the database server.

Statement Class

Data Types

The table below shows the data type conversion between CUBRID native data types and Ruby representation.

affected_rows

Description

This method is used to get the number of rows which have been affected by the SQL statements (INSERT, DELETE, UPDATE).

Example

stmt = @con.query("UPDATE cities SET name = 'Paris' WHERE id = 4")
@con.commit
num = stmt.affected_rows

Return values

• num : an integer representing the number of rows affected by the last SQL statement.

bind

Description

This method is used to substitute the values instead of the variables indicated in the SQL queries as question marks (?) in the prepare method.

Syntax

bind(index, data [!, db_type, set_type]) ? nil 

Parameters

• index : an integer representing the order of the variable to be replaced - first, second, ...
• data : a value representing the data to be replaced for the variable at the order index.
• db_type : [!Optional] db_type is a type of the value to be bound. It can be omitted by default. If it is omitted, the type is automatically cast to an appropriate one.
• set_type : [!Optional]

Return value

• nil

Example

index = 1
value = "Ruby"

stmt.bind(index, value)
con = Cubrid.connect('demodb')
con.auto_commit = true
con.query('create table a (a int, b double, c string, d date)')
 
con.prepare('insert into a values (?, ?, ?, ?)') { |stmt|
   stmt.bind(1, 10)
   stmt.bind(2, 3.141592)
   stmt.bind(3, 'hello')
   stmt.bind(4, Time.local(2007, 12, 25, 10, 10, 10), Cubrid::DATE)
   stmt.execute
}

con.close

close

Description

This method is used to close the Statement.

Syntax

close() ? nil 

Return value

• nil

Example

stmt.close

column_info

Description

Returns the column information of the fetched rows. Because of the column information is represented as a hash, it is returned in the form of array.

Syntax

column_info() ? array 

Return value

• array: an array representing the hash of the key name, type_name, precision, scale, nullable, which refer to the column's name, the column's data type, precision, scale, null-ability, respectively.

Example

con = Cubrid.connect('demodb')
con.prepare('SELECT * FROM db_user') { |stmt|
   stmt.execute
   stmt.column_info.each { |col|
   print col[!'name']
   print col[!'type_name']
   print col[!'precision']
   print col[!'scale']
   print col[!'nullable']
   }
}

con.close

each

Description

Returns the fetched rows one by one in a cycle to the inside block. The row is represented as an array.

Syntax

each() { |row| block } ? nil 

Return value

• nil

Example

con = Cubrid.connect('demodb')
con.prepare('SELECT * FROM db_user') { |stmt|
   stmt.execute
   stmt.each { |r|
   print r[!0]
   }
}
con.close

each_hash

Description

Returns the fetched rows one by one in a cycle to the inside block similar to the each() method. The difference is that each_hash returns a row which is represented as a hash.

Syntax

each_hash() { |hash| block } ? nil

Return value

• nil

Example

con = Cubrid.connect('demodb')
con.prepare('SELECT * FROM db_user') { |stmt|
   stmt.execute
   stmt.each_hash { |r|
   print r[!'name']
   }
}
con.close

execute

Description

This method is used to execute a given SQL statement. It can receive zero or more parameters depending on whether the bind method has been used before or not. If the statement stmt has been already binded' to the values, the execute method does not need any parameter. If the statementstmt has not been binded' to any values yet, the execute method will instantly bind the receive parameters and execute the SQL statement. If auto_commit is set to true, the execute method will automatically commit the transaction.

Syntax

execute() ? int
execute(...) ? int

Parameters

• values : [!Optional] a value representing the data to be binded to each variable in the SQL statement.

Return value

• int: Returns 1, if successful; 0 in case of failure.

Example

con = Cubrid.connect('demodb')
con.prepare('insert into a values (?, ?, ?, ?)') { |stmt|
   stmt.execute (10, 3.141592, 'hello', Time.local(2007, 12, 25))
}
con.close
sql = "INSERT INTO table1 (id, name) VALUES (?, ?)"
stmt = @con.prepare(sql)
value1 = 1
value2 = "Ruby"
stmt.bind(1, value1)
stmt.bind(2, value2)
stmt.execute

OR

sql = "INSERT INTO table1 (id, name) VALUES (?, ?)"
stmt = @con.prepare(sql)
stmt.execute(value1, value2)

fetch

Description

Returns the row under the cursor as an array of column data. Once fetched the cursor is incremented by one, that is pointed to the next row. The row is represented as an array.

Syntax

fetch() ? array or nil 

Return value

• array : an array representing the row with columns.
• nil: if there is no row to be fetched, the method returns nil.

Below is a table which illustrates how

Example

con = Cubrid.connect('demodb')
con.prepare('SELECT * FROM db_user') { |stmt|
   stmt.execute
   r = stmt.fetch
   print r[!0]
}
con.close

fetch_hash

Description

Returns the row under the cursor as a hash of column data. Once fetched the cursor is incremented by one, that is pointed to the next row. The row is represented as an array.

Syntax

fetch_hash() ? hash or nil 

Return value

• hash : a hash representing the row with columns.
• nil: if there is no row to be fetched, the method returns nil.

Example

con = Cubrid.connect('demodb')
con.prepare('SELECT * FROM db_user') { |stmt|
   stmt.execute
   r = stmt.fetch_hash
   print r[!'name']
}
con.close

get_oid

Description

In case a statement has been prepared with Cubrid::INCLUDE_OID option, the get_oid method will return the Oid of the created GLO object.

Syntax

get_oid() ? Oid 

Return value

• Oid: the OID of the newly created GLO object.

Example

con = Cubrid.connect('demodb')
con.prepare('SELECT * FROM db_user', Cubrid::INCLUDE_OID) { |stmt|
   stmt.execute
   stmt.fetch
   oid = stmt.get_oid
   print oid.table
}
con.close

Oid Class

[!](col_name)

Description

Returns the column data of the OID.

Syntax

[!](col_name) ? obj 

Return value

• obj: the column data of the OID.

Example

con = Cubrid.connect('demodb')
stmt = con.prepare('SELECT * FROM db_user', Cubrid::INCLUDE_OID)
stmt.execute
stmt.fetch
oid = stmt.get_oid
print oid[!'name']
print oid.name
stmt.close
con.close

Another way to access the data in the column is to call the name as a method.

oid = stmt.get_oid
print oid.name

[!]=(col_name, obj)

Description

Stores the data to the OID column. In order to reflect the saved data in the database server save method should be called afterwards.

Syntax

[!]=(col_name, obj) ? nil 

Return value

• obj: the column data of the OID.

Example

con = Cubrid.connect('demodb')
stmt = con.prepare('SELECT * FROM db_user', Cubrid::INCLUDE_OID)
stmt.execute
stmt.fetch
oid = stmt.get_oid
oid[!'name'] = 'foo'
oid.save
stmt.close
con.close

It is also possible to store and save the data using the corresponding name and save methods for the column.

oid = stmt.get_oid
oid.name = 'foo'
oid.save

drop

Description

Removes the OID from the database server.

Syntax

drop() ? self

Return value

• self

each

Description

Passes the column name and its data to the following block.

Syntax

each() { |name, val|
  ...
} ? nil

Return value

• nil

Example

con = Cubrid.connect('demodb')
stmt = con.prepare('SELECT * FROM db_user', Cubrid::INCLUDE_OID)
stmt.execute
stmt.fetch
oid = stmt.get_oid
oid.each { |name, val|
   print name
   print val
}

lock

Description

Sets the Cubrid::READ_LOCK or Cubrid::WRITE_LOCK to the OID.

Syntax

lock(lockmode) ? self

Parameter

• lockmode : the mode of the lock. Can be either Cubrid::READ_LOCK or Cubrid::WRITE_LOCK.

Return value

• self

refresh

Description

Reads the OID data from the database server. The column data of the OID is not automatically synchronized with the database server. In case much time has been elapsed since the Oid object has been created, the refresh method has to be called to read the data from the database server.

Syntax

refresh() ? self

Return value

• self

Example

con = Cubrid.connect('demodb')
stmt = con.prepare('SELECT * FROM db_user', Cubrid::INCLUDE_OID)
stmt.execute
stmt.fetch
oid = stmt.get_oid
print oid[!'name']

#after some time
oid.refresh
print oid[!'name']
stmt.close
con.close

save

Description

Saves the data of OID to the database server.

Syntax

save() ? self

Return value

• self

table

Description

Returns the table name of the OID.

Syntax

table() ? string

Return value

• string : the table name of the OID

to_hash

Description

Returns the OID data in a hash.

Syntax

to_hash() ? Hash

Return value

• Hash : The OID data. The key will indicate on its name, and the value - its data.

to_s

Description

Returns the OID string.

Syntax

to_s() ? string

Return value

• string : the OID string.

See also

• Ruby Programming with CUBRID
• CUBRID API References

On Windows

We have pushed the CUBRID Connector to Gemcutter. Use the above command (gem install cubrid) in the command line to install the latest version of Ruby Driver for CUBRID on Windows.

On Linux

Linux users can also install the CUBRID Connector through gem. Remember to add -E flag when installing the gem with sudo like "sudo -E gem install cubrid". The -E flag is necessary to make sure sudo does not reset the user path where CUBRID Database has been installed.

What if I don't have Gem Installer?

On Windows

• Install Ruby 1.8.7. You can download it from RubyInstaller site at http://rubyinstaller.org/downloads/.
• Install DevKit. Most Ruby gems out there require the mingw compiler to build gems written in C. CUBRID gem has C codes as well, so DevKit is required to install the latest CUBRID gem. You can download the DevKit from the same RubyInstaller site at http://rubyinstaller.org/downloads/.
  • In the command line navigate to the location where you installed the DevKit and initialize DevKit by typing the following command. This will generate the config.yml file to be used later in this Step. Your installed Rubies will be listed there (only those installed by a RubyInstaller package are detected at present).
  ruby dk.rb init
  • If necessary, edit config.yml file to include installed Rubies not automagically discovered or remove Rubies you do not want to use the DevKit with. This step is not required if you have installed Ruby from http://rubyinstaller.org/downloads/.
  • Install DevKit by typing the following command in the command line. This step installs (or updates) an operating_system.rb file into the relevant directory needed to implement a RubyGems pre_install hook and a devkit.rb helper library file into <RUBY_INSTALL_DIR>lib ubysite_ruby.
  ruby dk.rb install
  • For more information on DevKit, refer to http://github.com/oneclick/rubyinstaller/wiki/Development-Kit.
  • Before trying to install cubrid, make sure that the "make" and "gcc" commands are available in your command line. If not, add C:\DevKit\bin\ and C:\DevKit\mingw\bin\ to your PATH environment variable (we assumed DevKit is in C:\DevKit).
• Install CUBRID gem by typing the following command.
gem install cubrid

On Linux

• Install Ruby 1.8.7 by typing the following command.
sudo apt-get -y install ruby1.8-dev ruby1.8 ri1.8 rdoc1.8 irb1.8 libreadline-ruby1.8 libruby1.8 libopenssl-ruby rubygems1.8
• You can see that ruby1.8-dev package has also been installed. It is necessary to compile the C code of the gem. If you do not have ruby1.8-dev package already in your system, install it by typing the following command.
sudo apt-get install ruby1.8-dev
• Create a symbolic link for ruby to be able to run ruby command from the terminal.
sudo ln -s /usr/bin/ruby1.8 /usr/bin/ruby
• Install CUBRID gem by typing the following command. Do not forget to add -E flag after sudo to include the path to CUBRID.
sudo -E gem install cubrid

Here is a test_cubrid.rb file to see if CUBRID driver is correctly installed. Run the following command to execute the code:

Note: If you don't want to use "-rubygems" attribute, then you must copy the cubrid.so file from C:\Ruby187\lib\ruby\gems\1.8\gems\cubrid-0.65\ext to C:\Ruby187\lib\ruby\site_ruby\1.8\i386-msvcrt (the paths may vary according to your ruby installation).

• Support for database parameters
• LOB objects handling support
• Extended database schema support

And others…

Database parameters

After connecting to a database, a user can specify some “global” session parameters that will control the behavior of SQL statements transactions’ isolation level execution, the auto-commit behavior and others.

The complete list of these CUBRID database parameters is defined in the Constants.js file:

For each parameter, the CUBRID communication protocol implements a dedicated support for GET and SET operations. Therefore, in order to manipulate them, also a dedicate functionality was needed in the Node.js driver and this is what we did in the 2.0 release.

Please note one exception - the MAX_STRING_LENGTH parameter cannot be set programmatically from code; it’s a broker parameter and the client can only query its current value.

We have provided support for:

• Getting a parameter value, using the getDatabaseParameter (…) method
• Setting a parameter value, using the setDatabaseParameter (…) method

Let’s see some examples. First, let set the value of the ISOLATION_LEVEL parameter:

And let’s see how we can retrieve the value of the LOCK_TIMEOUT parameter for the current session:

The output result is:

Note: The same value can be obtained also from CUBRID Manager Client:

If you need to change the default values for these parameters, it is highly recommended to do it immediately after connect (). One consequence is that you must use an explicit connect () statement in your application, and not the “implicit connect” driver feature (the “implicit connect” feature means that the driver can auto-connect when a query is first executed, without the need to issues an explicit connect() command).

LOB objects handling

In the previous driver version, the support for LOB (CLOB/BLOB) objects was limited to query only. Now, we have implemented the completed protocol required to update such data type columns. Please note that, as in the other CUBRID drivers, we have implemented dedicated driver query functions for handling LOB objects, as follows:

• lobNew(…)
• lobRead(…)
• lobWrite(…)

Let’s see a simple example of inserting a LOB value (the code below is an “extract” from an ActionQueue series of method calls):

And this is how we retrieve a LOB value:

(the str variable will contain the LOB data)

As you can see, it’s pretty simple to deal with LOB data types!

Database schema

If you remember, in the previous driver versions, we provided integrated support for querying two database schemas:

• TABLEs
• VIEWs

But CUBRID provides many more and some of the information cannot be obtained by querying the system objects – see, for example, the foreign keys.

Therefore, one of the things we did in this release was to improve the support for database schema, and so we add support for:

• ATTRIBUTEs (Table columns)
• CONSTRAINTs
• PRIMARY KEYs
• IMPORTED KEYs (Foreign keys)
• EXPORTED KEYs
• TABLE PRIVILEGEs

The method which must be used to retrieve a database schema is:

CUBRIDClient.getSchema(…)

Depending on schema, some method parameters might be mandatory!

For example, if you query the CONSTRAINTS schema, you need to provide the table name.

See the driver documentation for more details.

Let’s see an example for retrieving the list of foreign keys for a table (we will use the game table in the demodb database):

 The code is pretty simple:

And the output is: 

Please note that some of the database schemas can be obtained very easily by querying the appropriate system table – you don’t need the getSchema(…) method. For such schemas, we will not provide a dedicated functionality in the driver.

One simple example is the USERs schema, which can be obtained like this:

When running this script on the demodb database, we will get the list of users defined in the demodb:

Other features

Connection timeout

One of the requests we got for the 2.0 driver release was to implement a connection timeout feature. Simply said - wait for the connection to the database to complete within the specified number of seconds and eventually throw an error if the timeout occurs.

Obviously, the key thing here was to set the connection timeout at the Node.js socket connection layer level (and not on the consumer level):

Now let’s see this in action:

As you see, the timeout specified is 2.000, which is 2 sec.

After the 2 seconds, the script will timeout:

Extended events information

Another thing we have enhanced in the 2.0 release is the events information provided to the user.

This is actually one of the key things we are constantly looking into improving in our driver – the events model – because we believe it provides many advantages over the “classical” callbacks programming model.

For example, the query() events now returns also the source SQL statement:

For more details about the events model, please take a look at the driver documentation.

Objects array

Remember that in the version 1.0, when you we were retrieving the data returned by a query, we were accessing the data using an array notation:

Now, you can also do this - use an object notation:

Even if it looks easier to understand, we do not recommend using the object-type notation, unless you have good reasons. This is because of one reason – the syntax errors cannot be detected at development time, but only at runtime!

What we usually recommend instead is to use named-indexes in the array notation, for example:

Under the hood…

In this section, we will look at some internal driver implementation details.

The queue processor

In order to have an “automatic” queue processor, which takes care of executing the statements the users added to the queue, we needed a way to implement a routine which could (auto-)execute in a recursive manner, but without blocking the events queue. And this without using a “timer”, because this is not available in Node.js.

Note: Just to clarify, when we say that the “standard timer” feature is not available in Node.js, we are referring to the Windows timer functionality, where you don’t need to auto-call the recurrent function by yourself again and again, but you simply setup the timer function handler only once and the system takes care automatically of running it without any other actions required from the application.

Here is the logical structure of this routine we have developed:

Tip: As you can see there is an internal parameter - _QUERIES_QUEUE_CHECK_INTERVAL - which controls after which interval the routine restart itself. The default value is 1.000 msec. If for some reason, you need a “faster” queue, you can lower down the values of this parameter, for example:

<your_CUBRIDConnection_client_instance_name>._QUERIES_QUEUE_CHECK_INTERVAL = 500;

Some backward compatibility notes

Maybe you have asked if the “old” query(…) statement is still available…

The short answer is: Yes, it is still there in the driver and not only as an empty “shell”, but complete - nothing was changed in its implementation.

We made this choice for a couple of reasons:

• Not everybody will actually need the queries queue functionality
• Executing a query using the ”old” query(…) function is slighter faster and uses lesser resources. The reason is obvious – you will be bypassing entirely the queue processor.

Tip: Before you start coding, think about if you need the queue processor and make the best decision for your applications. Remember, there are 3 main ways to use the driver:

• Through the queries queue
• Through the ActionQueue (or any similar implementation,  see Async for example)
• Using simple “callback-chained“ queries

References and links

We hope you enjoyed this tutorial!

Please let us know your feedback and suggestions, so we can improve! And do not forget, tryout the CUBRID Node.js 2.0 driver!

ADO.NET driver source code is distributed under the terms of BSD open source license.