SQLBase Connecting. Guide to Connecting to SQLBase Connecting To Sqlbase Page 1

Transcription

1 SQLBase Connecting Guide to Connecting to SQLBase Connecting To Sqlbase Page 1

2 Trademarks Gupta, the Gupta logo, Gupta Powered, the Gupta Powered logo, Centura, Centura Ranger, the Centura logo, Centura Web Developer, Fast Facts, Object Nationalizer, Quest, Quest/Web, QuickObjects, SQL/API, SQLBase, SQLConsole, SQLGateway, SQLHost, SQLNetwork, SQLRouter, SQLTalk, and Team Object Manager are trademarks of Gupta Technologies and may be registered in the United States of America and/or other countries. SQLWindows is a registered trademark and TeamWindows, ReportWindows and EditWindows are trademarks exclusively used and licensed by Gupta Technologies. Team Object Manager, Web Developer, QuickObjects, Object Nationalizer, Report Builder, Connectivity Administrator, Development Kit, Component Development Kit, SQLBase Resource Manager, and SQLConsole are names of products from Gupta Technologies. Adobe is a trademark of Adobe Systems, Incorporated. IBM, OS/2, NetBIOS, and AIX are registered trademarks of International Business Machines Corporation. Linux is a trademark of Linus Torvalds. Red Hat is a trademark of Red Hat, Incorporated. Novell and Netware are trademarks of Novell, Inc. SUSE is a trademark of SUSE LINUX AG. Java, JavaScript, and Solaris are trademarks of Sun Microsystems, Incorporated. Microsoft, Outlook, PowerPoint, Visual C++, Visual Studio, Internet Explorer, Internet Information Server, DOS, Win 32, Windows, ActiveX, MSDN, SQL Server, and Visual Basic are either registered trademarks or trademarks of Microsoft Corporation in the United States of America and/or other countries. This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. ( All other product or service names mentioned herein are trademarks or registered trademarks of their respective owners. Copyright Copyright 2012 by Gupta Technologies. All rights reserved. Connecting To Sqlbase Page 2

3 Table of Contents SQLBase Connecting... 1 Trademarks... 2 Copyright... 2 Table of Contents... 3 Chapter 1 Introduction to SQLBase Connectivity... 7 Gupta client and server technology... 7 SQL.INI and the Connectivity Administrator... 7 SQLBase native connectivity General features of SQLBase Chapter 2 ODBC Driver Introduction How does it work? ODBC overview About the SQLBase ODBC driver for Windows About the SQLBase ODBC driver for Linux Supported Features Configuring Data Sources in Windows Configuring Data Sources in Linux How-to information for ODBC Chapter 3 Making an ODBC Connection Connection strings bit vs. 64-bit Windows Logon dialog Connecting To Sqlbase Page 3

4 Linux connections Chapter 4 Introducing SQLBase OLE DB Data Provider Overview About SQLBase OLE DB Data Provider How-to information for the OLE DB provider ADO Overview Connecting to data through the Provider Establishing a connection using ADO Chapter 5 Supported OLE DB COM Objects Supported COM objects Data Source Session Command Rowset Error Chapter 6 ADO Mapping to SQLBase Isolation level mapping ADO mapping to Gupta interfaces Command object mapping Connection object mapping Error object mapping Field object mapping Parameter object mapping Recordset object mapping Chapter 7.NET Data Provider Connecting To Sqlbase Page 4

5 Using the New Fully Managed.NET Data Provider The New.NET Data Provider Connectivity SQLBase.NET requirements SQLBase.NET implementation How-to information for the.net data provider SQLBaseConnection object SQLBaseCommand object SQLBaseDataReader object SQLBaseDataAdapter object SQLBaseTransaction object SQLBaseParameter object SQLBaseParameterCollection object SQLBaseException object SQLBase classes and transaction state Chapter 8 Introduction to the JDBC driver Introduction JDK Versions Installation Getting Started SQLBase Support for JDBC How-to information for the JDBC driver URL formats Data types and conversions SQLBase Supported Data Types: Bind variable support Connecting To Sqlbase Page 5

6 Stored procedure support Named Cursor Support Error Message Support Application and Applet Development Chapter 9 Encrypting database connections using Secure Sockets Layer (SSL) Secure Sockets Layer (SSL) Configuring SSL encryption Glossary Connecting To Sqlbase Page 6

7 Chapter 1 Introduction to SQLBase Connectivity Gupta client and server technology Connectivity has two faces at Gupta Technologies. Gupta publishes SQLBase, the relational database server discussed in this book. And we also publish Team Developer, a set of tools for creating powerful client applications that connect to SQLBase and to many other data sources as well. The details of client connectivity for applications written with Team Developer to any data source are documented in another Gupta book, Connecting Gupta Objects to Databases. In contrast, the book you are reading now will discuss how to connect any client application, written with any programming tool, to Gupta SQLBase. But the database administrator still needs to be concerned with client connectivity, for two reasons: You need client tools for DBA tasks like configuration, backup, and testing. Since you are likely to use Gupta s tools for these purposes, you will still need to have some knowledge of client connectivity. Client computers, even those that do not use Gupta client tools, still need at least a rudimentary client-side SQL.INI file on their machines, for purposes of specifying basic server, database and protocol information. SQL.INI and the Connectivity Administrator Both Gupta s client tools and their server tools use a configuration file to store connectivity information. In versions of SQLBase prior to 8.5, this file was always named SQL.INI, and choices for its location were limited. In version 8.5 the file name and location are now under your control, although the default name is still SQL.INI, and that is the name we use to refer to the configuration file in Gupta documentation. The ability to have any name and location for the configuration file is a feature that supports multiple concurrent SQLBase installations on a single computer, also new in version 8.5. For new SQLBase installations, SQL.INI is created during the install process and is tailored to your answers to the install questions. By default, it is found in the same directory as the SQLBase executables. This default SQL.INI file is functional immediately and, for many users, it is unnecessary to ever change SQL.INI until new servers or new databases are added to the installation. Experienced users may wish to change SQL.INI settings to achieve specific performance and communication goals. Connecting To Sqlbase Page 7

8 The remaining chapters in this book will discuss how to configure SQLBase drivers and data providers. In some cases such configuration involves changes to SQL.INI. Even in cases where SQL.INI is not directly involved, such as the OLE DB data provider, it is still indirectly involved since individual databases must be registered in SQL.INI before they are accessible to client applications. Although SQL.INI can be modified with a text editor such as Notepad, uncontrolled manual changes can accidentally introduce problems, such as being unable to use a specific protocol against SQLBase or being unable to access a particular database. Gupta recommends that when possible you use the Connectivity Administrator instead to make changes. In this book, we discuss only basic SQL.INI concepts. The Database Administrator s Guide contains much more detailed information about every concept that is briefly discussed in this chapter. Running Connectivity Administrator Connectivity Administrator is one of the options in the Gupta program group. Depending on what you have installed, the main window can show two tabs. The Connectivity tab works on client-side settings to add or remove, enable or disable routers and protocols. Choose the Server tab to add or remove databases and enable or disable protocols. When configuring connectivity for a SQLBase server, you can: Set up the options for a SQLBase server Enable and disable communication protocols Modify the listening protocols of a database name Add or remove a server name from a listening protocol Add or remove a database name View a list of database names Change the settings of an installed server When configuring connectivity for a SQLBase client, you can: Edit the name, encryption level, and runtime directory of the client itself. Enable and disable listening protocols. Edit the properties of some listening protocols (TCP/IP and local connection) Associate new server names with a specific listening protocol, or remove server names from a listening protocol. Limit access to specific databases on a server, or access all databases. Change properties of a server/protocol combination, such as the TCP/IP listen port. Enable, disable, and configure data sources other than SQLBase. (That topic is related to Gupta Team Developer and is outside the scope of this book; see Connecting Gupta Objects to Databases.) Connecting To Sqlbase Page 8

9 The illustration below shows how the Client tab allows you to change the name and location of the configuration file you wish to edit, by directly typing the name or by clicking the Browse pushbutton. Connecting To Sqlbase Page 9

10 On both tabs, you left-click to select an item, double-click to change properties, or right-click to display a menu of connectivity functions. Connecting To Sqlbase Page 10

11 If you double-click on the server node ( server1 above), or right-click on it and choose Properties, you can work with the Server Configuration dialog box, which has three tabs: The Basic tab controls the server name. The name you use in SQL.INI files on client computers must match the name found here. Connecting To Sqlbase Page 11

12 The Optional tab allows you to configure other commonly-changed and critical settings. Connecting To Sqlbase Page 12

13 The Advanced tab allows you to change any server keyword, presuming that you know the value that should be associated with the keyword. Detailed information about values and keywords is available in Chapter 3 of the Database Administrator s Guide. You can also configure database settings, by double-clicking on a database node or by right-clicking it and then choosing Properties. Database setting changes are limited to the database name and activating/deactivating listening protocols. Note that in the example above, three of the listening protocol checkboxes are disabled. That is because those protocols have been disabled at the server level, so they cannot be manipulated at the database level. You can add a new database to the server by right-clicking the Databases node, then choosing Add database. SQL.INI server-side example Shown below is a portion of a typical SQL.INI file containing basic information about a SQLBase server and its databases. Some of the lines in the file are annotated to explain their purpose. [dbntsrv] dbntsrv is the abbreviation for the SQLBase unlimited-user version section. Your version might be different. For example, the 10-user version uses the abbreviation dbnt10sv. servername=server1,sqlmpipe,sqlws32 The default name for a SQLBase server is server1. Following the server name are the names of the listening protocols that apply to the entire server. (As we will see later, individual databases need not implement all of these protocols.) sqlmpipe represents the MTS (COM+) listener, and sqlws32 is the TCP/IP listener. These keywords are not case-sensitive. dbname=island,sqlmpipe,sqlws32 Connecting To Sqlbase Page 13

14 ISLAND is the demonstration/tutorial database installed with SQLBase. By default, it is assigned the same listening protocols as the server itself. Each database in a server must have a dbname line within the server section of SQL.INI. cache=2000 sortcache=2000 readonly=0 oracleouterjoin=0 logfileprealloc=0 partitions=0 optimizerlevel=2 locktimeout=275 dbdir=c:\program Files\Gupta Databases are physical files, each in its own subdirectory with the same name as the database itself. By default, these subdirectories are presumed to be located under the SQLBase program directory, but you can change the path to point elsewhere. dbname=sqlcon,sqlws32 Database SQLCON is used for the SQLConsole DBA utility. Note that in this example it implements only the TCP/IP listening protocol, not the MTS protocol. dbname=purple,sqlmpipe,sqlws32 Database PURPLE was added using Connectivity Administrator. Note that it implements both of the listening protocols used by the server itself. [dbntsrv.dll] comdll=sqlmpipe comdll=sqlws32 Section dbntsrv.dll determines which listening protocols will be loaded when the SQLBase server starts. [dbntsrv.ws32] listenport=2155 Each listening protocol has a separate section in SQL.INI with optional extra information. The TCP/IP listener has a default port, You can override this, but if you do, you must insure that any SQL.INI files on client machines are altered to match the new port number. Note: The default port for the MTS (COM+) listening protocol, SQLMPIPE, is This is not subject to overriding in SQL.INI - the port number is a runtime parameter that you supply to the SQLBase Resource Manager, SQLBrm.exe. For more information, see the SQLBase release notes. You can override this, but if you do, you must insure that any SQL.INI files on client machines are altered to match the new port number. Connecting To Sqlbase Page 14

15 SQL.INI client-side example This is a good spot to illustrate how SQL.INI files on client machines must match the SQL.INI on the server. Here are a few selected sections from SQL.INI on a client machine. [win32client.dll] comdll=sqlws32 The [winclient32.dll] section shows the communication libraries that the client loads when it first tries to connect to a database. sqlws32, as with the server, indicates the TCP/IP listening protocol. This client is going to take part in MTS transactions, so you might expect to see a comdll=sqlmpipe line in this section as we did when discussing the server. However, sqlmpipe is only used on the server. Clients use TCP/ IP for both ordinary database communications and MTS transactions, so only the sqlws32 line is required in this case. [win32client.ws32] serverpath=server1,devsrvr,2156/* The [win32client.ws32] section provides more detail about the TCP/IP listening protocol. In the serverpath line, we see the name of the server ( server1 ), which must match the name used in the SQL.INI file on the server machine. Then we see the name of the computer that hosts the SQLBase server ( devsrvr ). Then we see the listening port (2156). In this example, the SQLBase server is running the SQLMPIPE protocol for MTS (COM+) compatibility. Therefore the client SQL.INI points to the SQLMPIPE port, 2156, rather than the default TCP/IP port of If you change this port number to 2155, the client will still be able to communicate with the SQLBase server using TCP/IP, but will be unable to participate in MTS transactions. In any case, the port numbers used by the client SQL.INI file must match those used in the server SQL.INI file. Finally, the /* following the port number means that all databases on server1 are visible to the client. If you specified only one database name, such as 2156/ISLAND, then only that database would be visible to the client. The serverpath line is the only way that the client can determine how to reach the server, so its presence is critical. There can be multiple serverpath lines in this section, each pointing to different servers or different databases. SQLBase native connectivity This book discusses industry-standard drivers and database providers for SQLBase. In addition, SQLBase has native connectivity that can be used easily by Gupta client tools, and can be called from other client tools through an API. For more information about this native protocol, read the SQL Application Programming Interface book. General features of SQLBase SQLBase has a feature set that is largely consistent regardless of which driver or data provider is being used to communicate with it. However, there are slight differences in the feature set available to some drivers and data providers. Those differences will be noted individually in the chapters that describe the Connecting To Sqlbase Page 15

16 drivers and data providers. In this chapter, the general features of SQLBase are described. If you are interested in the most detailed information, refer to the SQL Language Reference book: DML and DDL SQLBase supports all commonly used Data Manipulation Language commands and Data Definition Language commands. For a summarized list of commands, see the SQL Command Reference chapter in the SQL Language Reference. Making a connection In the SQLBase native API, you can make implicit connections, meaning that multiple database cursors might be assigned to a single database connection. With implicit connections, changing the isolation level of a connection forces a COMMIT. Also, doing a COMMIT on one cursor will usually cause a COMMIT to occur for all other cursors sharing that connection, unless your application takes specific steps to prevent this. For more detailed information, see the chapter Using the SQL/API in the SQL Application Programming Interface Guide. However, all SQLBase drivers and data providers use explicit connections. This means that transactions performed against one connection will have no effect upon the transaction status of other connections. Bind variables SQLBase supports bind variables. A bind variable is a colon followed by a number or a string, in a position in a query where one would otherwise use literal data. The number or string corresponds to a variable in the client application running the query. Datatypes Here are the native datatypes supported by SQLBase: Type Name Type Length CHAR (or String 1 to 900 bytes VARCHAR) LONG (or LONG VARCHAR or CLOB) String Up to 2 gigabytes LONG NVARCHAR (or NCLOB) UTF-16 String Up to 2 gigabytes LONG VARBINARY (or BLOB) Data of any type Up to 4 gigabytes NCHAR (or NVARCHAR) String of national characters (U i d ) Up to 450 characters Connecting To Sqlbase Page 16

17 NUMBER Number Up to 22 digits DECIMAL (or DEC) Number Up to 15 digits, including scale digits INTEGER (or INT) Number Up to 10 digits of precision, range to SMALLINT Number Up to 5 digits of precision, range to DOUBLE PRECISION Number Double-precision floating point numbers, up to 22 digits. FLOAT Number Up to 22 digits of precision, including scale digits REAL Number Single-precision floating point numbers, up to 21 digits DATETIME (or TIMESTAMP) DATE Date/time Date/time Number representing both a date value and time value. Like DATETIME, but only the date portion of the value is returned TIME Date/time Like DATETIME, but only the time portion of the value is returned Detailed descriptions of these datatypes are available in the SQL Elements chapter of the SQL.Language Reference. There are significant differences between these datatypes and the sets of datatypes used in drivers and providers. The individual chapters following this one will detail the differences. Isolation levels Isolation levels are used to strike a balance between concurrency (allowing many users to share data) and consistency (insuring that data has not changed between the time it is read and the time it is altered.) There are differences in how isolation levels are mapped between SQLBase and the various drivers and providers - please read the relevant chapters. Cursor Stability (CS) The isolation level where a page acquires a shared lock on it only while it is being read (while the cursor is on it). A shared lock is dropped as the cursor leaves the page, but an exclusive lock (the type of lock used for an update) is retained until the transaction completes. This isolation level provides higher concurrency than Read Repeatability, but consistency is lower. Release Locks (RL) With the Cursor Stability isolation level, when a reader moves off a database page, the shared lock is dropped. However, if a row from the page is still in the message buffer, the page is still locked. In contrast, the Release Lock (RL) isolation level increases concurrency. By the time control returns to the application, all shared locks have been released. Connecting To Sqlbase Page 17

18 Read Only (RO) The isolation level where pages are not locked, and no user has to wait. This gives the user a snapshot view of the database at the instant that the transaction began. Data cannot be updated while in the read-only isolation level. Read Committed (RC) The isolation level where pages are not locked if data is only being read, and no user has to wait. When data is written, the behavior is similar to release locks isolation level. Read committed isolation level reads committed data, data that is committed before the transaction read committed timestamp. The timestamp is moved forward at various times to capture more recent committed data. R1 (RC1) The timestamp is changed when a transaction has no active commands and a new command starts. Starting a new cursor has no effect. R2 (RC2) The timestamp is changed when a new command starts in a transaction (multiple cursor scenario). Starting a new cursor moves the timestamp. R3 (RC3) The timestamp is changed when a new row is fetched or any other API call on a transaction is invoked. Read Repeatability (RR) The isolation level where if data is read again during a transaction, it is guaranteed that those rows would not have changed. Rows referenced by the program cannot be changed by other programs until the program reaches a commit point. Subsequent queries return a consistent set of results (as though changes to the data were suspended until all the queries finished). Other users will not be able to update any pages that have been read by the transaction. All shared locks and all exclusive locks are retained on a page until the transaction completes. Read repeatability provides maximum protection from other active application programs. This ensures a high level of consistency, but lowers concurrency. RR is the SQLBase default isolation level. Transactions SQLBase provides commands COMMIT and ROLLBACK to control transactions. In addition, the SAVEPOINT command can be used within scripts and procedures to create intermediate rollback points within a transaction. Distributed transactions In addition to a transaction that is handled on a single database server, SQLBase also provides the ability to do transactions that involve multiple database servers performing various parts of the transaction. For more information about this, read the Distributed Transactions chapter in the Database Administrator Guide. COM+ transactions in Windows SQLBase for Windows includes SQLBase Resource Manager, a component that makes it possible to coordinate database transactions inside a larger COM+ transaction. For more information, read the Communication chapter of the Database Administrator Guide. Long character and long binary data handling The LONG VARCHAR and LONG NVARCHAR datatypes accept character data. In Gupta Team Developer, or in applications that use the SQLBase native API, there are some extra steps required to make use of this datatype. However, all of the SQLBase drivers and data providers hide this complexity, so you can treat a LONG VARCHAR column just like any other datatype in your SQL commands. Connecting To Sqlbase Page 18

19 The LONG VARBINARY datatype accepts any type of data, and is usually used for binary data such as images. In Gupta Team Developer, or in applications that use the SQLBase native API, there are some extra steps required to make use of this datatype. Stored procedures and triggers SQLBase supports stored procedures. The procedural language is SAL (SQLWindows Application Language), which is the same language used in the SQLWindows tool that is part of Centura Team Developer. This language is also used in triggers. Parameters are allowed with stored procedures. Parameters can be either input-only or input-output. There is no output-only parameter type. For detailed information and examples of stored procedures and triggers, read the chapter Procedures and Triggers in the SQL Language Reference. Connecting To Sqlbase Page 19

20 Chapter 2 ODBC Driver Introduction This chapter describes SQLBase s support for the Microsoft Open DataBase Connectivity (ODBC) standard. The ODBC standard is an application programming interface (API) specification written by Microsoft. It is an effort to standardize the way in which front-end products access database servers from different vendors. Connecting To Sqlbase Page 20

21 How does it work? Each relational database vendor has its own proprietary API. If you want your client application to access a database server, you must code to the database vendor s API. Alternatively, you can use a router or gateway product to translate from one vendor s API to another vendor s API. Gupta s SQLRouter products provide such a service. They sit between a Gupta SQLWindows or Report Builder client application and a non-sqlbase database server and translate Gupta API calls into non-sqlbase API calls. Gupta has SQLRouter products that support DB2, DB2/400, Oracle, SQL Server, Sybase, and more. The ODBC standard takes another approach. It calls for all client applications to write to the ODBC standard API and for all database vendors to provide support for it. It then relies on third-party access tools or database drivers (such as the Gupta SQLBase ODBC driver) that conform to the ODBC specification to translate the ODBC standard API calls generated by the client application into the database vendor s proprietary API calls. ODBC overview The ODBC architecture specifies four components: The application. The application requests a connection with a data source. It calls ODBC functions to submit SQL statements and retrieve results. The Driver Manager. On Windows, the Driver Manager is a dynamic-link library (DLL) that is provided by Microsoft and is included with the Gupta SQLBase ODBC driver. Its primary purpose is to load drivers on behalf of an application. On Linux, a driver manager is a binary component provided by a third party such as iodbc or unixodbc. You must alter the configuration files for these binary components to link them with the SQLBase ODBC driver. The driver. To access SQLBase, you use the Gupta SQLBase ODBC driver, which is packaged with SQLBase. The driver processes ODBC function calls, submits SQL requests to a specific data source, and returns results to the application. If necessary, the driver modifies an application s request so that the request conforms to syntax supported by the associated DBMS. The data source. This consists of the data you want to access and its associated DBMS (in this case, SQLBase), operating system, and network platform (if any). Connecting To Sqlbase Page 21

22 For more detailed information on ODBC architecture and implementation, read the Microsoft s Programmer s Reference manual that accompanies the ODBC Software Developer s Kit (SDK). About the SQLBase ODBC driver for Windows The SQLBase ODBC driver supports the Gupta SQLBase database system in the following operating systems: Windows 98, ME, NT, 2000, Server 2003, and XP. The driver file name is sqlbaseodbc.dll. Driver and data source configuration are done through sqlbaseodbcsetup.dll. The information in this chapter is also available in an online help file that is accessible during ODBC data source configuration. System requirements The Gupta SQLBase ODBC driver (SQLBaseODBC.dll) requires: SQLBase version or higher. One of the supported operating systems: Microsoft Windows 95, 98, ME, NT, 2000 and XP. The Microsoft 3.5 Driver Manager. This is included with the Gupta SQLBase ODBC driver. To communicate with the server, the SQLBase driver requires SQLWNTM.DLL, SQLBAPW.DLL, and a communication DLL (for example, SQLWS32.DLL for TCP/ IP). The directory containing these files must be on your path. Client applications written with a Gupta programming tool, such as SQLWindows, cannot use ODBC to connect to SQLBase. For such applications, use the native SQLBase routers instead. About the SQLBase ODBC driver for Linux The SQLBase ODBC driver supports the Gupta SQLBase database system in the following operating systems: Red Hat 9.0, Red Hat Advanced Server 3.0, SUSE 9.0, SUSE Enterprise Server 8.0, SUSE Desktop 1.0. The driver file name is libsqlbaseodbc.so. Driver and data source configuration are done through text editing of configuration files. Connecting To Sqlbase Page 22

23 System requirements The Gupta SQLBase ODBC driver (libsqlbaseodbc.so) requires: SQLBase version or higher. One of the supported operating systems: Red Hat 9.0, Red Hat Advanced Server 3.0, SUSE 9.0, SUSE Enterprise Server 8.0, SUSE Desktop 1.0. A driver manager. The Gupta SQLBase ODBC driver has been tested with the iodbc and the unixodbc driver managers. These are available from third parties. Note: See release notes for exact versions of operating systems and ODBC driver managers Client applications written with Gupta Team Developer cannot use ODBC to connect to SQLBase. For such applications, use the native SQLBase routers instead. Supported Features The driver is very similar in its Windows and Linux implementations. Here are the few differences in Linux: The iodbc and unixodbc driver managers do not support Microsoft Distributed Transactions. The SQLBase Linux ODBC Driver supports only non-gui data source configuration. ODBC Conformance Level The API functions supported are listed in Supported ODBC Functions. The driver conforms to ODBC Core and Level 1 completely. In addition, many Level 2 functions and some Level 3 functions are supported. When queried for API conformance, the driver responds that it is Level 2 compliant. The driver supports the SQL Minimum Grammar as well as ODBC Escape Sequences for date, time and timestamp values, outer join and scalar functions. The driver also supports backward and random fetching in SQLExtendedFetch and SQLFetchScroll. Number of Connections and Statements Supported The SQLBase database system supports multiple connections and multiple statements per connection. Isolation and Lock Levels Supported SQLBase supports the following standard ODBC isolation levels: SQL_TXN_REPEATABLE_READ (maps to SQLBase level RR), Connecting To Sqlbase Page 23

24 SQL_TXN_READ_COMMITTED (maps to SQLBase level RL)and SQL_TXN_READ_UNCOMMITTED (maps to SQLBase level RL). SQLBase supports page-level locking. Supported ODBC Functions Gupta s SQLBase ODBC Driver supports the following functions: SQLAllocHandle SQLBindCol SQLBindParameter SQLBrowseConnect * SQLCancel SQLCloseCursor SQLColAttribute SQLColumnPrivileges SQLColumns SQLConnect SQLCopyDesc SQLDescribeCol SQLDescribeParam * SQLDisconnect SQLDriverConnect SQLEndTran SQLExecDirect SQLExecute SQLFetch SQLFetchScroll SQLFreeStmt SQLForeignKeys SQLFreeHandle SQLGetConnectAttr SQLGetCursorName SQLGetData SQLGetDescField SQLGetDescRec SQLGetDiagField SQLGetDiagRec SQLGetEnvAttr SQLGetInfo SQLGetStmtAttr SQLGetTypeInfo SQLMoreResults * SQLNativeSql SQLNumParams SQLNumResultCols SQLParamData Connecting To Sqlbase Page 24

25 SQLPrepare SQLPrimaryKeys SQLProcedureColumns ** SQLProcedures SQLPutData SQLRowCount SQLSetConnectAttr SQLSetCursorName SQLSetDescField SQLSetDescRec SQLSetEnvAttr SQLSetPos SQLSetStmtAttr SQLSpecialColumns SQLStatistics SQLTablePrivileges SQLTables * Exported by the driver but currently not fully implemented. Will return standard ODBC error to indicate that it is not implemented. ** Search patterns in SqlProcedureColumns are limited to the % symbol as the last character of the pattern. Any other wildcard characters will return a not-supported error. Deprecated functions Below is an alphabetic list of deprecated ODBC API functions. Note that these functions can still be used by an ODBC application, but they are implemented by the ODBC Driver Manager and not by the driver. The driver manager maps these deprecated functions into other functions that are actually implemented by the driver. Deprecated function SQLAllocConnect SQLAllocEnv SQLAllocStmt SQLBindParam SQLError SQLExtendedFetch SQLFreeConnect Mapped to SQLAllocHandle SQLAllocHandle SQLAllocHandle SQLBindParameter SQLGetDiagRec SQLFetchScroll SQLFreeHandle Connecting To Sqlbase Page 25

26 Deprecated function SQLFreeEnv SQLGetConnectOption SQLGetStmtOption SQLParamOptions SQLSetConnectOption SQLSetParam SQLSetScrollOptions SQLSetStmtOption SQLTransact Mapped to SQLFreeHandle SQLGetConnectAttr SQLGetStmtAttr SQLSetStmtAttr SQLSetConnectAttr SQLBindParameter SQLSetStmtAttr SQLSetStmtAttr SQLEndTran Configuring Data Sources in Windows To configure a SQLBase data source, do the following: 1. Start the ODBC Administrator to display a list of data sources. 2. If you are configuring an existing data source, select the data source name and click Configure to display the SQLBase Data Source Properties dialog box. If you are configuring a new data source, click Add to display a list of installed drivers. Select SQLBase and click Finish to display the SQLBase Data Source Properties dialog box. 3. Specify a data source name, a database name and optionally, a description. 4. Click Test Connect to attempt to connect to the data source using the connection properties specified in the Driver Setup dialog box. You may need to supply the name of the database server in the Test Connect dialog box. 5. If desired, configure optional data source settings in the Advanced section of the dialog. 6. Click OK or Cancel. If you click OK, the values you have specified become the defaults when you connect to the data source. You can change these defaults by using this procedure to reconfigure your data source. You can override these defaults by connecting to the data source using a connection string with alternate values. 7. You can also visit the Connection Pooling tab of the ODBC Administrator window to setup up connection pooling for your data source. Connection pooling offers Connecting To Sqlbase Page 26

27 performance advantages, and is particularly helpful when your data source is participating in a distributed transaction. Data Source Properties dialog Use the ODBC SQLBase Data Source Configuration dialog box to create new SQLBase data sources or configure existing data sources.. Data Source Name: A string that identifies this SQLBase data source configuration in the system information. Examples include Accounting or SQLBase-Serv1. Description: An optional long description of a data source name. For example, My Accounting Database or SQLBase on Server number 1." Database Name: The name of the database to which you want to connect by default. Isolation Level: The method of locking to use for this connection. Choices are Release Locks, Read Repeatability, Read Only, or Cursor Stability. For detailed information about how these levels work, read the SQLBase Language Reference manual, specifically the SET ISOLATION command. Input Message Size: The number of bytes in the input message buffer. The default is determined by SQLBase. Increasing this value retrieves more records across the network in a single fetch. Lock Timeout: The number of seconds SQLBase should wait for a lock to be freed before raising an error. Values can be -1 (wait forever) to 1800; the default is 300. Config Filename (INI): The name (and, optionally, path) of the configuration file that contains information about SQLBase servers and databases. This name can be left blank; if so, the configuration file is searched for using the algorithm described in chapter 3 of the SQLBase Database Administrator s Guide. Connecting To Sqlbase Page 27

28 Configuring Data Sources in Linux Driver manager configuration files Popular ODBC driver managers for Linux, such as iodbc and unixodbc, use configuration files to get data source information. These files are named odbc.ini and odbcinst.ini. They are most commonly found in the /etc directory. Driver managers can also search for configuration files. For example, iodbc searches for odbc.ini as follows: 1. $ODBCINI - Environment variable, if set. 2. ~/.odbc.ini - Located in home-directory ($HOME), if it exists for user DSN 3. /etc/odbc.ini - A system-wide default Changing configuration information Configuration changes are done by using a text editor on the configuration files. In the case of unixodbc it is possible to use a utility, odbcinst, to make changes to the configuration files. However, you would still use a text editor to enter the lines that are shown in the examples below into a template file, then use odbcinst to actually copy those lines from the template file into the configuration files. For more detail about using odbcinst instead of editing the configuration files manually, see Nick Gorham s explanation of odbcinst. Shown below is an example data source, Gupta1, as it would be configured for different driver managers. unixodbc To learn how unixodbc searches for its configuration files, see the unixodbc web site. Entries in the odbcinst.ini file: Connecting To Sqlbase Page 28

29 [Gupta SQLBase] Driver = /opt/gupta/sqlbase90/libsqlbaseodbc.so Setup = /opt/gupta/sqlbase90/libsqlbaseodbcsetup.so Here are the corresponding entries in the odbc.ini file: [Gupta1] Driver=/opt/Gupta/SQLBase90/libsqlbaseodbc.so Description=Gupta SQLBase DSN DSN=Gupta1 Servername=server1 LoginID=SYSADM Username=SYSADM Password=SYSADM Database=island ini=/opt/gupta/sqlbase90/sql.ini InputMessageSize=2000 IsoLevel=Release Locks LockTimeOut=300 iodbc The configuration entries for iodbc are similar, but not identical, to unixodbc. Here is the odbcinst.ini file: ; /etc/odbcinst.ini file begin ; ; odbcinst.ini ; [ODBC Drivers] Gupta SQLBase = Installed [Gupta SQLBase] Driver = /opt/gupta/sqlbase90/libsqlbaseodbc.so Setup = /opt/gupta/sqlbase90/libsqlbaseodbcsetup.so And here is the odbc.ini file: ; /etc/odbc.ini file begin ; ; odbc.ini ; [ODBC Data Sources] Gupta1=Gupta SQLBase ODBC Driver [Gupta1] Description=Gupta SQLBase DSN Driver=/opt/Gupta/SQLBase90/libsqlbaseodbc.so DSN=Gupta1 Servername=server1 LoginID=SYSADM Username=SYSADM Password=SYSADM Database=island ini=/opt/gupta/sqlbase90/sql.ini InputMessageSize=2000 IsoLevel=Release Locks LockTimeOut=300 [Default] Driver = /opt/gupta/sqlbase90/libsqlbaseodbc.so ; /etc/odbc.ini file end Connecting To Sqlbase Page 29

30 How-to information for ODBC How do SQLBase datatypes map to ODBC datatypes? The SQLBase data types are mapped to the standard ODBC data types as follows: SQLBase CHAR DATE DECIMAL DOUBLE PRECISION INTEGER LONG VARBINARY (BLOB) LONG VARCHAR (CLOB) NCHAR NUMBER NVARCHAR REAL SMALLINT TIME TIMESTAMP VARCHAR ODBC SQL_VARCHAR SQL_TYPE_DATE SQL_DECIMAL SQL_DOUBLE SQL_INTEGER SQL_LONGBINARY SQL_LONGVARCHAR SQL_WCHAR SQL_DOUBLE SQL_WCHAR SQL_REAL SQL_SMALLINT SQL_TYPE_TIME SQL_TYPE_TIMESTAMP SQL_VARCHAR How do I start a transaction? By turning off autocommit, your application begins an implicit transaction. SQLSetConnectAttr(hdbc, SQL_AUTOCOMMIT, SQL_AUTOCOMMIT_OFF); You can end the transaction with either a rollback or commit flag. SQLEndTran(henv, hdbc, SQL_COMMIT); Distributed transactions benefit from connection pooling. For more information about configuring connection pooling, see Configuring Data Sources in Windows on page 2-7. For information about changing connection pooling from within an application, search the Microsoft KnowledgeBase using connection pooling to find information on code samples. How do I set isolation levels? Connecting To Sqlbase Page 30

31 To set isolation level, use the connection property SQL_TXN_ISOLATION. Set it to one of the supported levels, as listed in Isolation and Lock Levels Supported on page 2-4 How do I read and write long character and long binary data? ODBC functions SqlGetData and SqlPutData are the primary methods of handling the ODBC datatype SQL_LONGVARCHAR., which can contain either long character or long binary information. In this fragment of C code, a large text string is first written to the database, then read back from the database. rc = SQLExecDirect(hstmt, "DROP TABLE TBLOB", SQL_NTS); rc = SQLTransact(henv, hdbc, SQL_COMMIT); rc = SQLExecDirect(hstmt,"CREATE TABLE TBLOB (I INTEGER NOT NULL, B LONG )", SQL_NTS); assert(rc == SQL_SUCCESS); rc = SQLTransact(henv, hdbc, SQL_COMMIT); assert(rc == SQL_SUCCESS); cbvalue = 0; rc = SQLPrepare(hstmt, "INSERT INTO TBLOB VALUES (?,?)", SQL_NTS); assert(rc == SQL_SUCCESS); rc = SQLSetParam(hstmt, 1, SQL_C_LONG, SQL_INTEGER, 0, 0, &l, NULL); assert(rc == SQL_SUCCESS); rc = SQLSetParam(hstmt, 2, SQL_C_CHAR, SQL_LONGVARCHAR, blob_size, 0, NULL, &cbvalue); assert(rc == SQL_SUCCESS); cbvalue = SQL_DATA_AT_EXEC; l = 2; blobbuf = malloc(blobbuf_size); memset(blobbuf, 'A', blobbuf_size); rc = SQLExecute(hstmt); assert(rc == SQL_NEED_DATA); rc = SQLParamData(hstmt, &token); if (rc == SQL_NEED_DATA) { for (j = 0; j < blob_size; ) { SDWORD s; s = (SDWORD)blobbuf_size; if (s + j > blob_size) { s -= (s + j) - blob_size; assert(s + j!= blob_size); } rc = SQLPutData(hstmt, blobbuf, s); assert(rc==sql_success); j += (ULONG)s; } rc = SQLParamData(hstmt, &token); assert(rc == SQL_SUCCESS); } Connecting To Sqlbase Page 31

32 else { error_line( LINE ); } rc = SQLTransact(henv, hdbc, SQL_COMMIT); assert(rc == SQL_SUCCESS); rc = SQLFreeStmt(hstmt, SQL_RESET_PARAMS); assert(rc == SQL_SUCCESS); memset(blobbuf, ~0, 100); rc = SQLPrepare(hstmt, "SELECT I, B FROM TBLOB WHERE I = 2", SQL_NTS); assert(rc == SQL_SUCCESS); rc = SQLExecute(hstmt); assert(rc == SQL_SUCCESS); rc = SQLFetch(hstmt); assert(rc == SQL_SUCCESS); rc = SQLGetData(hstmt, 1, SQL_C_LONG, &l, 0L, &cbvalue); assert(rc == SQL_SUCCESS); blob_read = 0L; do { rc = SQLGetData(hstmt, 2, SQL_C_BINARY, blobbuf, blobbuf_size, &cbvalue); assert(cbvalue > 0); blob_read += (cbvalue < blobbuf_size? cbvalue : blobbuf_size); } while (rc == SQL_SUCCESS_WITH_INFO); assert(rc == SQL_SUCCESS); assert(blob_read == blob_size); rc = SQLFreeStmt(hstmt, SQL_CLOSE); assert(rc == SQL_SUCCESS); free(blobbuf); How do I run stored procedures? A stored procedure without parameters can be run like a regular SQL query, as in this C example: sql= "{call maketables}"; rc = SQLExecDirect(hstmt,sql,SQL_NTS); CHECK(rc,hstmt); A stored procedure that uses parameters requires the use of binds, as in this example of procedure test that was created with a string parameter named quote : /* Prepare the procedure invocation statement */ SQLPrepare(hstmt, "{call test(?)}", SQL_NTS); /* Populate record 1 of IPD */ SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, 30, 0, szquote, 0, &cbvalue); Connecting To Sqlbase Page 32

33 /* Get IPD handle and set the NAMED and UNNAMED fields for record # 1 */ SQLGetStmtAttr(hstmt, SQL_ATTR_IMP_PARAM_DESC, &hipd, 0, 0); SQLSetDescField(hIpd, 1, SQL_DESC_NAME, "quote", SQL_NTS); /* Assuming that szquote has been appropriately initialized, execute the statement */ SQLExecute(hstmt); Connecting To Sqlbase Page 33

34 Chapter 3 Making an ODBC Connection Connection strings If your application requires a connection string to connect to a data source, you must specify the data source name that tells the driver which section of the odbc.ini file to use for the default connection information. Optionally, you may specify attribute or value pairs in the connection string to override the default values stored in the odbc.ini file. You can specify either long or short attribute names in the connection string. Gupta recommends that you use long names. The connection string has the following format: DSN=data source name[;attribute=value[;attribute=value]...] An example of a connection string for SQLBase is: DSN=SQLBase Island;SERVER=SERVER1;DATABASE=PAYROLL; UID=JOHN;PWD=XYZZY Connection string keywords Driver: Used in DSN-less connections, and is required to tell the Driver Manager which ODBC driver the rest of the connection string pertains to. Connecting To Sqlbase Page 34

35 DataSourceName (DSN): A string that identifies a single connection to a SQLBase database system, for example, Accounting. Database (DB): The name of the database system to which you want to connect. ServerName (SRVR): The name of the server that hosts the database to which you want to connect. LogonID (UID): The default Logon ID used to connect to your SQLBase system. A Logon ID is required only if security is enabled on your database system. If so, contact your system administrator to get your Logon ID. This value is case-sensitive. Password (PWD): Case-sensitive password. IsoLevel (IL): A string that specifies how SQLBase will handle locking for this connection. Possible values are RL (Release Locks), RR (Read Repeatability), RO (Read-Only), and CS (Cursor Stability). For detailed information about how these levels work, read the SQLBase Language Reference manual, specifically the SET ISOLATION command. InputMessageSize (IMS): Controls the number of bytes of the input message buffer. Increasing this value retrieves more records across the network in a single fetch. LockTimeOut (LTO): Number of seconds SQLBase waits for a lock to be freed before raising an error. Values can be -1 to A value of -1 is infinite wait. Default is 300. NoRecovery (NR): This keyword is accepted for backwards compatibility, but has no effect on the SQLBase server. 32-bit vs. 64-bit Windows When setting up a 32bit ODBC connection on 32bit Windows OS, or a 64bit connection on a 64bit OS, simply run odbcad32, pick the appropriate ODBC driver, and create a new user dsn. When setting up a 32bit ODBC connection on a 64bit Windows OS, you will need to run odbcad32 from the command line as follows: cd c:\windows\syswow64 odbcad32 Pick the 32bit ODBC driver and create a new user dsn. Logon dialog Your application might supply enough information in the connection string to make the connection without prompting you. If not, when the SQLBase ODBC Driver Connecting To Sqlbase Page 35

36 needs additional information from you to make a connection, it displays a dialog box. Fill out the values in the dialog box as shown below: Note: The logon dialog is available only in the Windows ODBC driver, not in the Linux ODBC driver. In the Linux ODBC driver, if the connection string contains insufficient information to make a connection, the database server will return an error. 1. Optionally, type the name of the server containing the SQLBase database tables you want to access or select the name from the Server Name drop-down list box, which displays the server names you specified in the Setup dialog box. Type Local to access a local SQLBase database. 2. Type the name of the database you want to access. If you specified a server name, you can select the name from the Database Name drop-down list box. 3. If required, type your user name. 4. If required, type your password. Click OK to complete the logon and to update the values in the system information. Linux connections Since there is no logon dialog for Linux operating systems, your Linux ODBC configuration files must be complete and accurate before you attempt to log on. The data source that you wish to connect to must be present in these files (particularly odbc.ini.). Several lines are necessary for each data source. See the sample Gupta1 data source, as it is configured in unixodbc on page 2-9 or iodbc on page Connecting To Sqlbase Page 36

37 PHP example An example of how a PHP script might connect to the Gupta1 data source from chapter 2 is shown below. The following script effects a connection to a database (`Gupta1' is the default DSN), and either executes a query or lists tables present in that database. Save this code to a file php-odbc-sample.php. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" " <html> <head> <title> Gupta test of ODBC access through PHP hosting</title> <link type="text/css" rel="stylesheet" media="all" href="../../tutorial.css" /> </head> <body> <h1>testing ODBC connectivity from PHP hosted within Gupta</h1> <hr /> <?php # set global variables based on the form thing - see `register global # variables' and PHP security updates $query=$_post['query']; $uid=$_post['uid']; $passwd=$_post['passwd']; $listtables=$_post['listtables']; $DSN=$_POST['DSN']; $exec=$_post['exec'];?> <p>enter the parameters for your query here:</p> <form action="php-odbc-sample.php" method="post"> <div> <span class="caption">dsn</span> <input type="text" name="dsn" value="<?php print ($DSN<>"")?$DSN:"Gupta1"?>" /> <span class="caption">userid</span> <input type="text" name="uid" value="<?php print ($uid<>"")?$uid:"sysadm"?>" /> Connecting To Sqlbase Page 37

38 <span class="caption">password</span> <input type="password" name="passwd" value="<?php print ($passwd<>"")?$passwd:"sysadm"?>" /> </div> <div> <span class="caption">query</span> <input type="text" name="query" value="<?php print ($query<>"")?$query:"select * from budget"?>" /> </div> <div> <input type="submit" name="exec" value="execute query" /> or <input type="submit" name="listtables" value="list Tables" /> </div> </form> <hr /> <?php if($query<>"" && $DSN<>"" && $exec!=null) { print "<h2>results:</h2> "; print "<p>connecting... "; $handle=odbc_connect ("$DSN", "$uid", "$passwd"); } if(!$handle) { print "<p>uh-oh! Failure to connect to DSN [$DSN]: <br />"; odbc_errormsg(); } else { print "done</p> "; $resultset=odbc_exec ($handle, "$query"); odbc_result_all($resultset, "border=2"); odbc_close($handle); } if($listtables!=null) { print "<h2>list of tables</h2>"; print "<p>connecting... "; $handle=odbc_connect ("$DSN", "$uid", "$passwd"); print "done</p>"; Connecting To Sqlbase Page 38

39 }?> if(!$handle) { print "<p>uh-oh! Failure to connect to DSN [$DSN]: <br />"; odbc_errormsg(); } else { $resultset=odbc_tables($handle); odbc_result_all($resultset, "border=2"); odbc_close($handle); } </body> </html> Connecting To Sqlbase Page 39

40 Chapter 4 Introducing SQLBase OLE DB Data Provider This chapter contains an overview of SQLBase OLE DB Data Provider functionality and software requirements. It also discusses ActiveX Data Objects (ADO) and how the SQLBase OLE DB Data Provider works with the ADO standard. Connecting To Sqlbase Page 40

41 Overview OLE DB is an application programming interface, written by Microsoft. Part of Microsoft s Universal Data Access strategy, it aims to facilitate access to information across data sources. The goal is to reliably offer high-performance data access that supports industry standards. The Universal Data Access strategy addresses the technical obstacles organizations face when trying to disseminate information across client/server networks and the World Wide Web. This task becomes more of a challenge given multiple platforms, legacy systems, and numerous programming languages and development tools. Based on open industry specifications, Universal Data Access allows developers to extend the capabilities of existing technologies. OLE DB fits into this strategy by giving developers the ability to write applications that have uniform access to data regardless of the data source and development tool. Using OLE DB, it is possible for different pieces of an application to be written in different languages due to OLE DB s COM structure. OLE DB components The two main components of OLE DB are a data provider and a data consumer. An OLE DB data provider responds to OLE DB calls resulting in data being returned in a usable tabular format. A data consumer is an application or COM component that uses the OLE DB API to access a data source. Since OLE DB comprises a set of Component Object Model (COM) interfaces, it results in a high level of interoperability among programming tools. The COM interfaces support the full DBMS functionality of the data source. The COM specification allows you to use a variety of programming tools, such as Visual Basic and Delphi, to develop application components that can function within a single application. Recommended reading To make the best use of OLE DB, we recommend that you read Microsoft OLE DB 2.0 Programming Reference and Data Access SDK. About SQLBase OLE DB Data Provider Built upon OLE DB technology, SQLBase OLE DB Data Provider lets programmers access SQLBase functionality from a variety of supported visual programming tools. Historically, developers have had to call SQL/API functions or use the ODBC API to access a database. SQLBase OLE DB Data Provider exposes SQLBase Server properties more completely than the ODBC driver does, allowing developers to directly interface with the database and server using a variety of programming tools. SQLBase OLE DB Data Provider is a set of COM objects that expose the SQLBase functionality needed by developers to build applications. In addition to standard OLE DB conformance, the Provider interfaces enable access to DBMS functionality not normally provided by OLE DB, including backup, create database, and shutdown server. A DLL, SQLBase OLE DB Data Provider runs in the address-space of the client program and is written over the SQL/API. Using OLE DB interfaces, the Provider lets you define DBMS components, including row containers, query processors, and transaction coordinators. Connecting To Sqlbase Page 41

42 Another level of simplification: ADO. The Provider also provides high level access to your data through ActiveX Data Objects (ADO). The following figure shows the role of SQLBase OLE DB Data Provider in the application development process. SQLBase OLE DB Data Provider name When you configure a programming tool to use the Provider, you may need to enter a provider name. For SQLBase OLE DB Data Provider, the name is: SQLBaseOLEDB Connecting To Sqlbase Page 42

43 The provider string is initialized for the open call that establishes a connection to SQLBase through the OLE DB provider. The name of the SQLBase OLE DB provider is hard-coded as a constant. The user ID, password, location and data source (tablename) are read from objects in your code. Here is a sample: ' set up connection string and open connection to data source Dim sconnect As String sconnect = "Provider=SQLBASEOLEDB" _& ";Data Source=ISLAND" _ & ";User ID=SYSADM" _ & ";Password=sysadm" For a more complete example of connecting to SQLBase using ADO, read Chapter 5, Establishing a connection using ADO. Data source name Some programming tools may prompt you for a data source name. For SQLBase OLE DB, the data source name is the name of the SQLBase database itself (for example, ISLAND). Supported programming tools SQLBase OLE DB Data Provider is designed to work with the following programming tools: Gupta Team Developer (SQLWindows), all the languages of Microsoft s Visual Studio, Delphi, Crystal Reports, PowerBuilder, and many others. In general, SQLBase OLE DB Data Provider works with any development environment that supports OLE DB data access. 32-bit vs. 64-bit Windows When setting up a 32bit OLEDB connection on a 32-bit Windows operating system, or a 64bit connection on a 64bit operating system, do the following: Right click on the UDL file and click on properties. This should open the file with the "OLE DB Core Services" program. Choose the OLEDB provider and configure your connection. When setting up a 32bit OLEDB connection on a 64-bit Windows operating system, enter these commands in the command prompt: cd c:\windows\syswow64 rundll32.exe "C:\Program Files (x86)\common Files\System\Ole DB\oledb32.dll",OpenDSLFile <path to udl file>\test32.udl How-to information for the OLE DB provider How do SQLBase datatypes map to OLE DB datatypes? Connecting To Sqlbase Page 43

44 SQLBase CHAR DATE DECIMAL DOUBLE PRECISION INTEGER LONG VARBINARY (BLOB) LONG VARCHAR (CLOB) NCHAR NUMBER NVARCHAR SMALLINT TIME TIMESTAMP VARCHAR OLE DB DBTYPE_STR DBTYPE_DBDATE DBTYPE_NUMERIC DBTYPE_R8 DBTYPE_I4 DBTYPE_BYTES DBTYPE_BYTES DBTYPE_WSTR DBTYPE_R8 DBTPTYPE_WSTR DBTYPE_I2 DBTYPE_DBTIME DBTYPE_DBTIMESTAMP DBTYPE_STR How do I start a transaction? Through the ITransactionLocal::StartTransaction and ITransactionJoin::JoinTransaction methods of the Session object, your application can initiate local transactions and/or join in distributed transactions. SQLBase support for these interfaces is identical to the support described in the Microsoft Developer Network documentation. In MSDN, search for those method or interface names to get more detail on the overall transaction process. How do I set isolation levels? The first parameter of the ITransactionLocal::StartTransaction method is isolation level. Use one of the supported levels shown in Isolation level mapping on page 6-1. While not all OLE DB isolation levels are supported by the default SQLBase settings, isolation level behavior can be overridden to use any allowed SQLBase isolation level to correspond to the specified OLE DB isolation level. Any values set can be used during the lifetime of the connection to set transaction isolation levels as well. To set an isolation level when initiating a new connection using a connection string, use the following syntax (example given in C#): System.Data.OleDb.OleDbConnection conn = new System.Data.OleDb.OleDbConnection( "PROVIDER=SQLBASEOLEDB.1; Data Source=island;User ID=sysadm; + Password=sysadm;Extended Properties=\"ini=C:\\Program Files\Gupta\\SQLBase116\\ + sql.ini;isolation=rc;readcommitted=r3\""); Connecting To Sqlbase Page 44

45 The isolation keyword can be set to one of the following values: RR RL CS RC R1 R2 R3 The allowed keys for the OLEDB Isolation Level Mappings are: Chaos ReadCommitted ReadUncommitted RepeatableRead Serializable Unspecified How do I use long character data and long binary data? These are edited code fragments from sample project Tut5, in Visual Basic version 6. They illustrate how to fetch long data into an image. Populate a Recordset from a query that includes a SQLBase LONG VARCHAR datatype: strsql = "SELECT EMPLOYEE_ID, LAST_NAME, FIRST_NAME, , CURRENT_SALARY, PHOTO1 FROM EMPLOYEE" Dim myrs As ADODB.Recordset Dim icount As Integer myado.setcursortype (adopenkeyset) myado.setlocktype (adlockoptimistic) myado.doselect (strsql) Set myrs = myado.getrs If Not myrs.bof And Not myrs.eof Then myrs.movefirst End If Get the value of a Recordset column and convert it to a byte array, then a file, then load the image with the file. Dim chunk() As Byte chunk() = StrConv(myRS("PHOTO1").Value, vbfromunicode) Set strstream = New ADODB.Stream strstream.type = adtypebinary strstream.open strstream.write chunk strstream.savetofile "C:\Temp.gif", adsavecreateoverwrite Image1.Picture = LoadPicture("C:\Temp.gif") Connecting To Sqlbase Page 45

46 Writing long binary information to the database can be accomplished by changing the value of a Recordset column. In this case the binary information was first written to a file. Set strstream = New ADODB.Stream strstream.type = adtypebinary strstream.open strstream. LoadFromFile sfilename strstream.position = 0 strstream.type = adtypetext strstream.charset = "ISO " myrs.fields("photo1").value = strstream.readtext myrs.save When working with long character data, you can choose to move it to a Byte array. You can also simply fetch it into the Text value of a TextBox or RichTextBox control, or into a string variable. ADO Overview Microsoft ActiveX Data Objects (ADO) enables you to write an application to access and manipulate data in a database server through an OLE DB provider, such as the SQLBase provider. ADO's primary benefits are data source independence, high speed, ease of use, low memory overhead, and a small disk footprint. Since ADO is independent of the data source, you do not have to know all the intricacies of the database to take advantage of the provider. For more general information about OLE DB providers, see the documentation for the Microsoft OLE DB SDK or visit the Microsoft OLE DB Web page. The SQLBase OLE DB Data Provider is a standard provider you can use with ADO as you would other standard providers. To make the best use of ADO, we recommend you access the samples in: and access further information on ADO in: ADO features ADO provides a number of features for building client/server and Web-based applications. Using the SQLBase provider with ADO, you can take advantage of: Independently-created objects. Unlike Data Access Objects (DAO) or Remote Data Objects (RDO), you no longer have to navigate through a hierarchy to create objects because most ADO objects can be independently created. This allows you to create and track only the objects you need, and also results in fewer ADO objects and thus a smaller working set. Batch updating. If you are using client-side cursors, you can do batch updating. This helps improve performance by locally caching changes to data, then writing them all to the server in a single update. Connecting To Sqlbase Page 46

47 Support for stored procedures with input (not output) parameters. Different cursor types, including support of backend specific cursors. With the SQLBase provider, when the user asks for the ability to fetch backward or scroll backward, the provider asks the server to enable its cursors. Remote Data Service ADO's Remote Data Service (RDS) allows data remoting, by which you can move data from a server to a client application or Web page, manipulate the data on the client, and return updates to the server in a single round trip. Previously released as Advanced Data Connector, RDS has been combined with the ADO programming model to simplify client-side data remoting. For more information, see the Remote Data Service documentation. As part of the Microsoft Data Access Components, ADO and RDS are automatically installed and registered by a host product, such as Microsoft Internet Information Server. The host product setup program may require that you specifically request the Microsoft Data Access Components in order to have ADO and RDS installed. Programming with ADO ADO is a dual-interface COM type library. The file name is msado15.dll. The program ID (ProgID) is ADODB. In two- and three-tier database applications, ADO code that is to execute on the client uses the ProgID ADOR instead. To use ADO with Microsoft Visual Basic or Microsoft Office, you also need to establish a reference to the ADO type library. From the Project menu, select References, check the box for Microsoft ActiveX Data Objects 1.5 Library, and then click OK. ADO objects, methods, and properties will then be accessible through the VBA Object Browser and the IDE Editor. To use ADO with Microsoft Visual J++, you also need to create a set of class files using the Java Type Library Wizard. From the Tools menu, select the Java Type Library Wizard, check the box for Microsoft ActiveX Data Objects 1.5 Library, and then click OK. The wizard will then create the necessary Java class files for ADO. For some programming languages, you also need to reference (using the #include statement) one or more additional files in your source code, as shown here: C++ VBScript JScript adoint.h adoid.h adovbs.inc adojavas.inc Threading With SQLBase OLE DB Data Provider, use ADO as apartment-model threaded. ADO Objects Connecting To Sqlbase Page 47

48 Although you create ADO objects outside the scope of a hierarchy, the objects exist within hierarchical relationships, as shown in the ADO Object Model. There are seven objects in the ADO object model: Command Maintains information about a command, such as a query string, parameter definitions, and so on. You can execute a command string on a Connection object or a query string as part of opening a Recordset object, without defining a Command object. The Command object is useful where you want to define query parameters, or execute a stored procedure that returns output parameters. Connection Maintains connection information with the data provider. Error Contains extended error information about an error condition raised by the provider. Because a single statement can generate two or more errors, the Errors collection can contain more than one Error object at a time, all of which result from the same incident. Field Contains information about a single column of data within a Recordset. The Recordset object features a Fields collection to contain all of its Field objects. Parameter A single parameter for a parameterized Command. The Command object features a Parameters collection to contain all of its Parameter objects. Property A provider-defined characteristic of an ADO object. Recordset A set of records returned from a query, and a cursor into those records. You can open a Recordset (that is, execute a query) without explicitly opening a Connection object. However, if you do first create a Connection object, you can open multiple Recordset objects on the same connection. Cursor In ADO, this is the equivalent of a recordset. Each of these objects features a set of properties and methods with which you can manipulate the object and its contents. Dynamic Properties Collections The Connection, Command, and Recordset objects each support a Properties collection. The properties collection contains any dynamic (or provider-specific ) properties exposed through ADO by the SQLBase provider. You use the collection and the Item method to reference the property by its name or by its ordinal position in the collection, as shown: Command.Properties.Item(0) Command.Properties.Item("Name") Because the Item method is a default method on an ADO collection, you can omit it: Command.Properties(0) Command.Properties("Name") Connecting To Sqlbase Page 48

49 Further, the Properties collection itself is the default collection for the Connection, Command, and Recordset objects, so you can omit it as well: Command(0) Command("Name") All of these syntax forms are identical. Which one you choose depends on your coding style preference. Working with Data In ADO, the Recordset object is the main interface to data. While the other objects are useful for managing connections, collecting error information, persisting queries, and so on, most of your code's interaction with ADO will involve one or more Recordset objects. This Microsoft Visual Basic Scripting code generates a Recordset from a SQLBase data source: set rstmain = CreateObject("ADODB.Recordset") rstmain.open "SELECT * FROM company", _ "provider=sqlbaseoledb;data source=island", _ adopenkeyset, adlockbatchoptimistic The first line creates the ADO Recordset object. The second line opens the recordset with a query. The third line specifies the SQLBase provider and the data source. This generates a forward-only, read-only Recordset object. With a few modifications, you can obtain a more functional Recordset: set rstmain = CreateObject("ADODB.Recordset") rstmain.open "SELECT * FROM company", _ "provider=sqlbaseoledb;data source=island", adopenkeyset, _ adlockbatchoptimistic This creates a fully scrollable and batch-updatable Recordset. In order to reference ADO constants by name (instead of by value) when coding in a scripting language, as shown in these code examples, you must include the appropriate header file. For Microsoft Visual Basic Scripting code, include the file adovbs.inc in your code. For Microsoft JScript, include the file adojavas.inc in your code. You should always refer to constants by name rather than by value because the values may change from one version to the next. However, because each provider is unique, how your application interacts with ADO will vary slightly between different providers. The differences you need to be aware of when using SQLBase OLE DB Data Provider are: Connection parameters in the ConnectionString property. Command object usage. Recordset behavior. Connecting To Sqlbase Page 49

50 Note: For the Recordset object, Gupta recommends that you use server-side cursors (aduseserver). If client cursors are used, then at the end of your application s unit of work, all the changes should be committed using the UpdateBatch() method. UpdateBatch() throws up following warning message which can be ignored: Run-time error ' (80040e38)': Row cannot be located for updating. Some values may have been changed since it was last read SQLBase provider-specific dynamic properties The Properties collections of the Connection, Command, and Recordset objects include dynamic properties specific to the SQLBase provider. These properties provide information about functionality beyond the built-in properties ADO supports. After establishing the connection and creating these objects, use the Refresh method on the object's Properties collection to obtain the SQLBase provider-specific properties. Sample applications The SQLBase provider comes with a number of sample applications. These samples have been developed to show some of the ways ADO can be used with Visual BASIC to communicate with the SQLBase database product. simplefetch Lets you connect to SQLBase and navigate, forward and backwards, through the COMPANY table - part of the ISLAND sample database for SQLBase. The code for this application is discussed in detail later in this chapter. schema Lets you query the ADO schema types that the SQLBase OLE DB Data Provider supports. DBExplore Lets you query SQLBase using SQL statements to return Recordsets from the SQLBase database. DBExplore.exe pulls out a Long Binary set of information, processes it, and writes it out to a file. Long text fields and Long Binaries are treated the same by the provider. SqlBaseNativeCmdSample Demonstrates the SQLBase Native commands (load, unload, store, erase and retrieve). You must have installed Microsoft Visual Basic 6.0, the Microsoft Data Access components and the SQLBase OLE DB Data Provider in order to use these samples. Connecting to data through the Provider Whether or not you use ADO or direct OLE DB, you acquire database information using these steps: 1. Initialize the provider. Connecting To Sqlbase Page 50

51 2. Establish a connection. 3. Open a recordset object. 4. Navigate through the database. 5. Process the recordset. 6. Disconnect. Establishing a connection using ADO ADO is an OLE DB consumer; it consumes OLE DB interfaces and data from the provider. To establish a connection to SQLBase through ADO, the sample we present in the next section follows these steps: 1. Create the various ADO objects. For example, a connection object, a recordset object, and an error object. 2. Define a routine to output the Errors collection. 3. Define a routine to safety handle null fields. 4. Define a routine to fetch the values of the various fields from the database table. Our sample assigns the field data to text boxes on the Visual BASIC form. 5. Define the code for the Connect button. The name of the SQLBase OLE DB provider is SQLBaseOLEDB. This is hard- coded as a constant. The user, password, and data source (tablename) are read from TextBox objects. 6. Provide code for a button for closing the connection to SQLBase. 7. Provide code for a button that moves to the first record in the returned Recordset. 8. Provide code for a button that moves to the next record in the RecordSet. 9. Provide code for a button that moves to the previous record in the RecordSet. 10. Provide code for button that moves to the last record in the RecordSet. Coding Sample using ADO The following code sample illustrates how to use SQLBase OLE DB Data Provider. For more information, refer to the samples that ship with the product. The code fragments show how to establish a connection, open a recordset object, and navigate through a SQLBase table using ADO in Visual BASIC. They are based on the simplefetch sample supplied with the Connecting To Sqlbase Page 51

52 OLE DB Provider. Portions of the code that don't specifically illustrate the concepts used have been excluded from this text for brevity. 1. Create the various ADO objects Dim cncompany As New ADODB.Connection Dim rscompany As New ADODB.Recordset Dim ercompany As ADODB.Errors 2. Define two routines to output the Errors collection. OutputErrorMessages() is called whenever an error condition is signalled from the provider. This routine outputs the elements of the Errors collection, one at a time, by calling OutputMessage(). OutputMessage adds the messages to a ListBox on the form, and keeps the latest message in view at all times. Private Sub OutputErrorMessages() ' loop through errors returned from provider, ' output to Messages Listbox Dim ErrLoop As Error Set ercompany = cncompany.errors For Each ErrLoop In ercompany OutputMessage ("Error: " _ & Str(ErrLoop.NativeError) & " " _ & ErrLoop.SQLState _ & ErrLoop.Description) Next ErrLoop End Sub Private Sub OutputMessage(sMessage As String) lbmessages.additem smessage) lbmessages.topindex = _bmessages.listcount - 1 End Sub 3. Define a routine to check for null fields. TextBox objects can be bound to your recordset object, to cause them to update and handle NULL values automatically. Because this sample obtains the values directly, IsNull is called on each value to prevent errors from Visual BASIC when returning NULL values. Private Function GetField(sFieldName As String) As String If Not IsNull(rsCompany.Fields(sFieldName)) Then GetField = rscompany.fields(sfieldname) Else GetField = "" End If End Function Connecting To Sqlbase Page 52

53 4. Define a routine to fetch the values of the various fields from the database table, assigning them to TextBox objects on the form. A check for BOF or EOF prevents errors when attempting to display values outside the table. GetField() is used to prevent issues with NULL values returned from the provider. Private Sub UpdateFieldsDisplay() If Not rscompany.bof And Not rscompany.eof Then ' fill fields of form from DB table CompanyID = GetField("Company_ID") CompanyName = GetField("Company_Name") Address = GetField("Address") City = GetField("City") State = GetField("State") End If End Sub 5. Define the code for the Connect button. This is where the connection to the database is established, and the recordset object is connected to the COMPANY table. Private Sub pbconnect_click() Establish error trapping, and clear the Errors collection to set up for the open attempt. On Error GoTo FindErr cncompany.errors.clear ' clear errors list The provider string is initialized for the open call that establishes a connection to S QLBase through the OLE DB provider. The name of the SQLBase OLE DB provider is hardcoded as a constant. The user, password, and data source (tablename) are read from TextBox objects on the form. Dim sconnect As String ' holds ADO connect string ' set up connection string and open connection to data ' source sconnect = "Provider=SQLBaseOLEDB" _ & ";Data Source=" & ebdatasourcename.text _ & ";User ID=" & ebuserid.text _ & ";Password=" & ebpassword.text Note that instead of providing an explicit connection string as shown above, you could place the name of a UDL file (must have extension.udl) into the string. The Open function will then read that file and use the contents as the connection string. So the second way of initializing sconnect is as follows: sconnect = "c:\\my Documents\\my_config.udl" Connecting To Sqlbase Page 53

54 Then do the actual connection... cncompany.open sconnect Connect the RecordSet object to the COMPANY table. The adopendynamic parameter is used to allow backward navigation through the table in this sample. ' open recordset on COMPANY table rscompany.open "COMPANY", cncompany, _ adopendynamic,, adcmdtable Move the RecordSet object to the first record in the table, and call the routine to display the field values on the form. ' move to first record, update display of fields rscompany.movefirst Call UpdateFieldsDisplay Exit Sub Provide an error routine that reports any problems with the connection to SQLBase or the COMPANY table. Sub FindErr ' error occurred -- loop through error list ' and add messages to listbox Call OutputErrorMessages ' clear errors queue, restore arrow cursor, ' exit subroutine cncompany.errors.clear Exit Sub End Sub 6. Provide code for a button for closing the connection to SQLBase. Private Sub pbdisconnect_click() cncompany.close End Sub 7. Provide code for a button that moves to the first record. We must call UpdateFieldsDisplay() to update the fields on each movement of the RecordSet object. Private Sub pbfirst_click() ' move to first record, update fields ' display rscompany.movefirst Call UpdateFieldsDisplay End Sub Connecting To Sqlbase Page 54

55 8. Provide code for a button that moves to the next record in the RecordSet. Special checks are made to stop at the end of the table. Private Sub pbnext_click() ' if we're not past last record, move to next record If Not rscompany.eof Then rscompany.movenext ' if we're NOW past the last record ' put cursor back on last record If rscompany.eof Then rscompany.movelast Else Call UpdateFieldDisplay End if End Sub 9. Provide code for button that moves to the previous record in the RecordSet. Checks are made to stop at the beginning of the table. Private Sub pbprev_click() ' if we're not before the first 'record, move to previous record If Not rscompany.bof Then rscompany.moveprevious ' if we're NOW before the first record... If rscompany.bof Then ' put cursor back on first record rscompany.movefirst Else Call UpdateFieldsDisplay End If End Sub 10. Provide code for button that moves to the last record in the RecordSet. Private Sub pblast_click() ' move to last record, update fields display rscompany.movelast Call UpdateFieldsDisplay End Sub Connecting To Sqlbase Page 55

56 Chapter 5 Supported OLE DB COM Objects This chapter describes the OLE DB COM objects supported by SQLBase OLE DB Data Provider. In this chapter, the tables describe interfaces of objects the Provider supports, and whether our support is standard or specific. Connecting To Sqlbase Page 56

57 Supported COM objects SQLBase OLE DB Data Provider uses OLE DB COM objects and their supported interfaces to provide access to SQLBase functionality. SQLBase OLE DB Data Provider uses the following COM cotypes: Data Source (TDataSource) objects contain the machinery to connect to a data source, such as a file or a DBMS. These objects function as factory for sessions. Session (TSession) objects create a context for transactions and can be implicitly or explicitly transacted. A single data source object can create multiple sessions. Sessions are a factory for transactions, commands, and rowsets. Command (TCommand) objects create a text command, such as an SQL statement, that can query or update a data source. If the text command specifies a row set, such as an SQL Select statement, it creates a row set. A single session can create multiple commands. Rowset (TRowset) objects expose data from a data source in a tabular format. Row sets can be created from a session or a command. An index object is a special case of a row set object. Error (TError) objects are created when errors occur when accessing a data provider. They include status, return codes, and an optional custom error object. SQLBase OLE DB Data Provider utilizes the custom error object. For a list and detailed description of the supported interfaces for the COM objects above, read Microsoft OLE DB documentation or visit the Microsoft Web site. Data Source SQLBase OLE DB Data Provider uses the following Data Source (TDataSource) object interfaces: Mandatory IDBCreateSession IDBInitialize IDBProperties IPersist Optional IDBInfo ISupportErrorInfo Data Source properties In addition to the properties inherited from its underlying classes, TDataSource has some specific properties of interest: DBPROP_INIT_PROVIDERSTRING Connecting To Sqlbase Page 57

58 This property can be used to supply up to three pieces of configuration information prior to making a connection to the database server. The parameter value, a string, must be formatted as follows: INI=<ConfigFileName>;ims=<value>;oms=<value> The configuration file name should include a fully qualified path. ims, input message buffer size, and oms, output message buffer size, can have a minimum value of 1 and a maximum value of (Default values are 2000 and 1000.) None of the three pieces of the string are required; any of them can be omitted. If there are two or more pieces in the string, the elements must be separated by semicolons. Data Source descriptions The following table briefly describes the data source interfaces and the level of support they receive. Interface Name Description Support IDBCreateSession IDBInitialize IDBProperties IPersist IDBInfo ISupportErrorInfo Calls on a data source object to obtain a Standard. new session. Initialize and uninitialize data source objects. Sets and gets properties values for the data source object. Returns the class identifier of an object. Standard. Standard, except enumerators are not supported. Standard, except enumerators are not supported. Returns a list of provider- specific Optional interface is keywords, or information about literals. supported. Shows whether an interface can return automated error messages. SQLBase OLE DB COM objects that implement this interface also return error objects. Connecting To Sqlbase Page 58

59 Session SQLBase OLE DB Data Provider uses the following Session (TSession) object interfaces: Mandatory IGetDataSource IOpenRowset ISessionProperties Optional IDBCreateCommand IDBSchemaRowset ISupportErrorInfo ITableDefinition IIndexDefinition ITransactionLocal ITransactionObject ITransactionJoin Session descriptions The following table briefly describes the session interfaces and the level of support they receive. Interface Name Description Support IGetDataSource IOpenRowset IGetDataSource returns an interface pointer to the data source object. IOpenRowset opens and returns a rowset that includes all rows from a single base table or index. Standard. Standard. ISessionProperties IDBCreateCommand ISessionProperties returns information about the properties a session supports and the current settings of those properties. It is a mandatory interface on sessions. Consumers call IDBCreateCommand::CreateComm on a session to obtain a new command. Standard. Standard. IDBSchemaRowset ISupportErrorInfo ITableDefinition IIndexDefinition IDBSchemaRowset provides advanced schema Standard. information. ISupportErrorInfo interface shows whether an interface Standard. can return automated error messages. The ITableDefinition interface exposes simple methods Standard. to create, drop, and alter data source tables. The IIndexDefinition interface exposes simple methods Standard. to create, drop, and alter data source indexes. Connecting To Sqlbase Page 59

60 ITransactionLocal ITransactionObject ITransactionJoin ITransactionLocal is used to start, commit, and abort session transactions. It is optional. ITransactionObject obtains the transaction object associated with a particular transaction level. ITransactionJoin allows your session to enlist in a distributed transaction, Standard. Standard. Standard Command SQLBase OLE DB Data Provider uses the following Command (TCommand) object interfaces: Mandatory IAccessor IColumnsInfo ICommand ICommandProperties ICommandText IConvertType Optional IColumnsRowset ICommandPrepare ICommandWithParameters ISupportErrorInfo Command Class Interface descriptions The following table briefly describes the command class interfaces and the level of support they receive. Interface Name Description Support IAccessor IColumsInfo ICommand ICommandProperties ICommandText The IAccessor describes how consumer buffer data is Standard. stored. IColumnsInfo exposes column information for a rowset or See Note. prepare command. Also, it provides limited information for an array. ICommand executes commands. This interface is Standard. mandatory on commands. ICommandProperties specifies properties from the Rowset Standard. property group to the command. When ICommandText is specified through Standard. SetCommandText, it replaces the existing command text. IConvertType IConvertType provides command or rowset conversion type Standard. information. This interface is mandatory on commands, rowsets, and index rowsets. Connecting To Sqlbase Page 60

61 IColumnsRowSet ICommandPrepare This interface supplies complete infomation about columns in a rowset. This optional interface encapsulates command optimization, a separation of compile time and run time. Standard. See Note. ICommandWithParameters This interface encapsulates parameters. ISupportErrorInfo Standard. ISupportErrorInfo interface shows whether an interface can Standard. return automated error messages. Note: Because the SQLBase OLE DB provider exposes ICommandPrepare, there are important stipulations to using the IColumnsInfo interface. Please see the OLE DB Programmer s Reference for further information. Rowset SQLBase OLE DB Data Provider uses the following Rowset (TRowset) object interfaces: Mandatory IAccessor IColumnsInfo IConvertType IRowset IRowsetInfo Optional IRowsetErrorInfo ISupportErrorInfo IRowsetChange Rowset Interface descriptions The following table briefly describes the rowset interfaces and the level of support they receive. Interface Name Description Support IAccessor The IAccessor describes how consumer buffer data is stored. Standard. IColumnsInfo IColumnsInfo exposes column information about rowset or prepared commands. It provides a limited set of array information. IConvertType IConvertType provides command or rowset conversion type information. This interface is mandatory for commands, rowsets, and index rowsets. See Note. Standard. IRowset IRowsetInfo IRowset is the base rowset interface. It provides methods for fetching rows sequentially, getting the data from those rows, and managing rows. IRowset Standard. requires IAccessor and IRowsetInfo. IRowsetInfo provides information about a rowset. IRowsetInfo also provides methods for retrieving objects associated with the rowset. All rowsets must Standard. implement IRowsetInfo. Connecting To Sqlbase Page 61

62 Interface Name Description Support IRowsetErrorInfo IRowsetErrorInfo indicates whether a specific interface can return Automation error objects. Standard. ISupportErrorInfo IRowsetChange ISupportErrorInfo interface shows whether an interface can return automated error messages. IRowsetChange has methods for updating the columns of existing rows, deleting existing rows, and adding new rows. SQLBase OLE DB COM objects that implement this interface also return error objects Provider cannot update rowsets derived from multiple tables. Does not support updating, deleting or inserting rows for Schema Rowset. Note: Because the SQLBase OLE DB provider exposes ICommandPrepare, there are important stipulations to using the IColumnsInfo interface. Please see the OLE DB Programmer s Reference for further information. Error SQLBase OLE DB Data Provider uses the following Error set (TError) object interfaces: Mandatory IErrorInfo IErrorRecords Optional None. Connecting To Sqlbase Page 62

63 Error Interface descriptions The following table briefly describes the error interfaces and the level of support they receive. Interface Name Description Support IErrorInfo IErrorRecords ISQLErrorInfo IErrorInfo returns error & return code information. It returns the error message, component name, and GUID of the interface where the error occurred, and the name and Help file topic that applies to the error. OLE DB error objects expose IErrorInfo at two levels. IErrorRecords is defined by OLE DB. It is used to add and retrieve records for an OLE DB error object. Information is passed to and from OLE DB error objects in an ERRORINFO structure. ISQLErrorInfo returns the SQLSTATE & native error code. Standard. Standard. Standard. Connecting To Sqlbase Page 63

64 Chapter 6 ADO Mapping to SQLBase This chapter provides isolation lever mapping to SQLBase. This chapter also provides tables that list, for each ADO object: The ADO method, property, or collection. The OLE DB method called. Whether or not it is supported by the SQLBase OLE DB Data Provider. Connecting To Sqlbase Page 64

65 Isolation level mapping This table compares ADO isolation levels to SQLBase. ADO Default adxactunspecified adxactbrowse adxactchaos adxactcursorstability adxactisolated adxactreadcommitted adxactreaduncommitted adxactrepeatableread adxactserializable SQLBase RL (release lock) Set to default (CS) RL (release lock) error RL (release lock) error RL (release lock) RL (release lock) RR (repeatable read) error ADO mapping to Gupta interfaces There is a table following for each of these objects: Command Connection Error Field Parameter Recordset The tables use this nomenclature for ADO methods, properties, and collections: Method() Property Collection[] Connecting To Sqlbase Page 65

66 Command object mapping ADO Method, Property, OLE DB Method(s) called or Collection Execute() ICommand::Execute.ActiveConnection.CommandText ICommandText::SetCommandText.CommandTimeout.CommandType.Prepared Parameters[] Properties[] ICommandProperties::SetCommandProperties (DBPROP_COMMANDTIMEOUT) ICommandPrepare::Prepare ICommandPrepare::Unprepare ICommandWithParameters::GetParameterInfo or DBSCHEMA_PROCEDURE_PARAMETERS ICommandWithParameters::SetParameterInfo IDBProperties::GetPropertyInfo ICommandProperties::GetProperties ICommandProperties::SetProperties Support? Connection object mapping ADO Method, Property, or Collection OLE DB Method(s) called Support? BeginTrans() ITransactionLocal::StartTransaction Close() CommitTrans() ITransactionLocal::Commit Execute() Open() ICommand::Execute or IOpenRowset::OpenRowset IDBInitialize::Initialize IDBCreateSession::CreateSession RollBack() ITransactionLocal::Abort OpenSchema() IDBSchemaRowset::GetRowset.Attributes ITransactionLocal::Abort.CommandTimeout ICommandProperties::SetCommandProperties (DBPROP_COMMANDTIMEOUT) Connecting To Sqlbase Page 66

67 .ConnectionTimeout.DefaultDatabase IDBProperties::SetProperties (DBPROP_INIT_TIMEOUT) IDBProperties::GetProperties (DBPROP_CURRENTCATALOG) IDBProperties::SetProperties (DBPROP_CURRENTCATALOG).IsolationLevel ITransactionLocal::StartTransaction.Mode IDBProperties::GetProperties (DBPROP_INIT_MODE) IDBProperties::SetProperties (DBPROP_INIT_MODE).Provider ISourcesRowset::GetSourcesRowset.Version Errors[] IErrorRecords Properties[] IDBProperties::GetPropertyInfo IDBProperties::GetProperties IDBProperties::SetProperties Error object mapping ADO Method, Property, or Collection OLE DB Method(s) called Support?.Description IErrorRecords::GetErrorInfo.HelpContent IErrorRecords::GetErrorInfo.HelpFile IErrorRecords::GetErrorInfo.NativeError.Number IErrorRecords::GetCustomErrorObject ISQLError::GetSQLInfo.Source IErrorRecords::GetErrorInfo.SQLState IErrorRecords::GetCustomErrorObject ISQLError::GetSQLInfo Connecting To Sqlbase Page 67

68 Field object mapping ADO Method, Property, or Collection OLE DB Method(s) called Support? AppendChunk() ISequentialStream::Write GetChunk() ISequentialStream::Read.ActualSize IAccessor::CreateAccessor IRowset::GetData.Attributes IColumnInfo::GetColumnInfo.DefinedSize IColumnInfo::GetColumnInfo.Name IColumnInfo::GetColumnInfo.NumericScale IColumnInfo::GetColumnInfo.OriginalValue IRowsetUpdate::GetOriginalData No.Precision IColumnInfo::GetColumnInfo.Type IColumnInfo:GetColumnInfo.UnderlyingValue.Value Properties[] IRowsetRefresh::GetLastVisibleData or IRowsetRefresh::GetVisibleData IAccessor::CreateAccessor IRowset::GetData IRowset::SetData IColumnsRowset::GetAvailableColumns IColumnsRowset::GetColumnsRowset No No Y Parameter object mapping ADO Method, OLE DB Method(s) called Property, or Collection AppendChunk() Support?.Attributes.Direction ICommandWithParameters::GetParameterInfo or DBSCHEMA_PROCEDURE_PARAMETERS ICommandWithParameters::SetParameterInfo ICommandWithParameters::GetParameterInfo or DBSCHEMA_PROCEDURE_PARAMETERS ICommandWithParameters::SetParameterInfo (No) (No) Connecting To Sqlbase Page 68

69 .Name.NumericScale.Precision.Size.Type.Value Properties[] ICommandWithParameters::GetParameterInfo or DBSCHEMA_PROCEDURE_PARAMETERS ICommandWithParameters::GetParameterInfo or DBSCHEMA_PROCEDURE_PARAMETER ICommandWithParameters::SetParameterInfo ICommandWithParameters::GetParameterInfo or DBSCHEMA_PROCEDURE_PARAMETERS ICommandWithParameters::SetParameterInfo ICommandWithParameters::GetParameterInfo or DBSCHEMA_PROCEDURE_PARAMETERS ICommandWithParameters::SetParameterInfo ICommandWithParameters::GetParameterInfo or DBSCHEMA_PROCEDURE_PARAMETERS ICommandWithParameters::SetParameterInfo IAccessor::CreateAccessor ICommand::Execute (No) (No) (No) (No) (No) Recordset object mapping ADO Method, OLE DB Method(s) called Property, or Collection Support? AddNew() IRowsetChange::InsertRow CancelBatch() IRowsetUpdate::Undo No CancelUpdate() Clone() IRowsetLocate No Close() IAccessor::ReleaseAccessor IRowset::ReleaseRows Delete() IRowsetChange::DeleteRows GetRows() IAccessor::CreateAccessor IRowsetLocate::GetRowsAt IRowset::GetNextRows IRowset::GetData No Move() MoveFirst() IRowsetLocate::GetRowsAt or IRowset::GetNextRows IRowsetLocate::GetRowsAt or IRowset::RestartPosition MoveLast() IRowsetLocate::GetRowsAt No Connecting To Sqlbase Page 69 No No

70 MoveNext() MovePrevious() IRowsetLocate::GetRowsAt or IRowset::GetNextRows IRowsetLocate::GetRowsAt or IRowset::GetNextRows NextRecordset() IMultipleResults::GetResult No Open() Requery() IOpenRowset::OpenRowset or ICommand::Execute IOpenRowset::OpenRowset or ICommand::Execute Resync() IRowsetRefresh::RefreshVisibleData No Supports() IRowsetInfo::GetProperties Update() IRowsetChange::SetData and/or UpdateBatch() IR tu d t U d t IRowsetUpdate::Update N No.AbsolutePage.AbsolutePosition.ActiveConnection.BOF.Bookmark.CacheSize IRowsetScroll::GetApproximatePosition IRowsetScroll::GetRowsAtRatio or IRowsetLocate::GetRowsAt IRowsetScroll::GetApproximatePosition IRowsetScroll::GetRowsAtRatio or IRowsetLocate::GetRowsAt IDBInitialize::Initialize IDBCreateSession::CreateSession IAccessor::CreateAccessor IRowsetLocate::GetRowsAt IRowsetLocate::GetRowsAt or IRowset::GetNextRows.CursorType ICommandProperties::SetProperties.EditMode IRowsetUpdate::GetRowsStatus No.EOF.Filter IRowsetUpdate::GetPendingRows IRowsetLocate::GetRowsByBookmark or IRowsetView::CreateView IRowsetView::OpenViewChapter IViewFilter::SetFilter.LockType ICommandProperties::SetProperties.MaxRecords IOpenRowset::OpenRowset (DBPROP_MAXROWS) or ICommandProperties::SetCommandProperties.PageCount ( IRowsetScroll::GetApproximatePosition ) No.PageSize (PageCount, AbsolutePage properties) No No No No No No No No No No No No No No No No Connecting To Sqlbase Page 70

71 .RecordCount IRowsetScroll::GetApproximatePosition No.Source.Status IRowsetUpdate::GetRowStatus No Fields[] IColumnInfo::GetColumnInfo Properties[] IRowsetInfo::GetPropertyInfo IRowsetInfo::GetProperties IRowsetInfo::SetProperties Connecting To Sqlbase Page 71

72 Chapter 7.NET Data Provider Using the New Fully Managed.NET Data Provider As of SQLBase 11.7, the new all-c# NET data provider supports a number of new connectivity features, such as connecting to a database without sql.ini, as well as support for many new 11.7-only features. We sometimes refer to this driver as the fully managed driver because it does not rely on the C API as does our earlier.net Data Provider. In addition to being fully written in managed code, the.net Data Provider offers the convenience of being able to ship as a single file, making deployment much easier. In order to keep both drivers available and ease the transition to the new driver, we currently are making both drivers available. Code compiled against the old driver can be used without modification in most cases. It is recommended that you consider moving to the new provider, since it is currently the focus of our development effort, and the provider based on the C API is considered deprecated. Moving to the new driver is relatively simple, and involves making the changes in the following table: Connecting To Sqlbase Page 72

73 Environment / Code All Visual Studio Projects Connection Strings using Data Source VB.NET Projects New Managed Driver Replace Unify.SQLBase.Data.dll with Gupta.SQLBase.Data.dll in your project references (for example, by right-clicking on your project in the Solution Explorer, then Add Reference. In the new driver, we have brought Data Source in line with other.net drivers, to mean the server or hostname,.e.g, localhost. To specify your database, use Initial Catalog, e.g. Data Source=localhost;Initial Catalog=island Replace: Imports Unify.SQLBase.Data With: Imports Gupta.SQLBase.Data Generally a project-wide search and replace Unify Gupta will be all you need. Earlier Driver Continue to use Unify.SQLBase.Data.dll, adding the new file to your project to have Visual Studio update the reference. No code changes needed. No code change needed. C# Projects Replace: using Unify.SQLBase.Data; With: using Gupta.SQLBase.Data; No code change needed. Generally a project-wide search and replace Unify Gupta will be all you need. The New.NET Data Provider Connectivity This chapter discusses the new connectivity features in the unmanaged driver features and provides a variety of different sample connection strings, and a table that shows the available keywords. We discuss both "legacy style" connections that rely on sql.ini and new connection strings that can be used without sql.ini. Connecting without sql.ini The new.net data provider can connect directly to SQLBase without using SQL.INI. Here are some examples that show how this is done. Connecting To Sqlbase Page 73

74 Connection Scenario Create connection to the server with the name Server1 on the local machine, connecting to ISLAND on the default port Create a custom connection, overriding several of the defaults Create an APIPE connection to ISLAND (local machine only) Connection String Example Data Source=LOCALHOST; InitialCatalog=ISLAND;ServerName=Server1 Data Source= ;InitialCatalog=demo; User=myuser;Password=secret;ServerName=serv123;Port=1959; Data Source=localhost;InitialCatalog=island; Transport=apipe;ServerName=Server1 SSL (Secure Sockets Layer) For the.net provider, secure socket layer connection settings must be specified in the connection string. Note however that the default "negotiate" setting allows you to configure this on the server and have clients attempt to connect this way. For more information about SSL connections, see chapter 9 of this document. Named Pipe Connections For the.net driver, connections via the new named pipe interface are specified in the connection string. Ini file settings are ignored. Connection Scenario Connect via named pipes (Windows only) Connection String Example Data Source=LOCALHOST;InitialCatalog=ISLAND; ServerName=Server1;User=SYSADM; Password=SYSADM;Transport=npipe Connection String Keywords The following keywords can be used in the connection string. Keywords are case insensitive. Values are case insensitive except in contexts where the value is case sensitive, such as passwords. The default value will be used if the value is not available. Keyword / Synonyms Data Source datasource ds Meaning / Value Examples Default The hostname or IP address of the machine on which SQLBase is running devserver.guptatechnologies.com localhost LOCALHOST Connecting To Sqlbase Page 74

75 Initial Catalog initialcatalog database db The SQLBase database to which you want to connect island DEMO ISLAND User userid uid User ID Password pwd The database user SYSADM SYSADM The password (value is case sensitive) SYSADM M1ck3yM0us3 SYSADM Server Server Name Servername ClientName Client Name AutoCommit Auto Commit Port The sqlbase server (as specified by the ServerName line in the [dbntsrv] section) Optional name to identify the client Automatically commit after each query For socket / SSL connections, the windows socket port to connect to Server1 GreatApp 2.1 Transport The transport layer to use. TCP APipe NPipe SSL UseSSL Use SSL IsolationLevel Isolation Level Use Secure Sockets Layer. Note that this is only available on socket connections to 11.7 or later servers. Isolation level to use, RL, RR, etc. N/A true false false Always - Fail if can't connect via SSL Never - Do not try to connect via SSL Negotiate - Try SSL, but connect without if not available RL RR etc. client hostname TCP Never IMS Input message size generally, when using SSL OMS Output message size Ini Location of ini file C:\sqlbase\sql.ini Connects without ini if sufficient information specified, otherwise tries to find ini using default search rules. RL Connecting To Sqlbase Page 75

76 Timeout Timeout Connection timeout for socket connections, in seconds 15 SQLBase.NET requirements You must have the.net Framework already installed on your machine before the SQLBase.NET Data Provider will install correctly. Gupta recommends that you install the most recent service pack for the.net Framework first. The SQLBase installation program offers you the option of installing the.net Data Provider. You must choose this option to use the provider. The actual component name is Gupta.SQLBase.Data.dll (for the new, fully managed data provider) and Unify.SQLBase.Data.dll (for the earlier.net data provider that was based on the C API). It is registered as a.net component during installation Any programming language that uses the provider will need to reference that component and its related namespace. For example, in Visual Basic.NET, you must choose menu item Project, Add Reference, locate the "Gupta SQLBase.NET Data Provider" item in the list on the ".NET" tab of the dialog, select it, and click OK. To reference the namespace, you must add a declaration to your code. In Visual Basic.NET, for example, you might do this with a line above your main code module: VB: Imports Gupta.SQLBase.data C#: using Gupta.SQLBase.Data; for the new, fully managed driver. For the older driver based on the C API, use: VB: Imports Unify.SQLBase.data C#: using Unify.SQLBase.Data; SQLBase.NET implementation The current version of SQLBase provides objects that implement eight of the.net interfaces. The vast majority of their functionality is identical to that described in the.net Framework documentation for the class library. In this chapter, we will only document a property or method when there is something distinct about the way it is implemented in SQLBase. SQLBaseConnection: implements the IDbConnection interface, establishes a connection to a specific data source. Connecting To Sqlbase Page 76

77 SQLBaseCommand: implements the IDbCommand interface, executes a command against a data source, exposes parameters and can execute within the scope of a Transaction. SQLBaseDataReader: implements the IDataReader interface and reads a scrollable, read-only stream of data from a data source. SQLBaseDataAdapter: implements the IDataAdapter interface; populates a DataSet and resolves updates with the data source. SQLBaseTransaction: implements the IDbTransaction interface and represents a transaction to be performed at a data source. SQLBaseParameter: implements the IDataParameter interface, represents a parameter which can be passed to a SQL command. SQLBaseParameters: implements the IDataParameters interface, which is a simple collection of SQLBaseParameter objects. In addition to these eight objects, SQLBase provides SQLBaseException, a public interface/object which is used for throwing exceptions to a client in case of a SQLBase error during a client method call. These objects are inherited from standard classes in the Microsoft.NET Framework. This chapter does not document the methods and properties that are inherited from those standard classes; it focuses only on the methods and properties that are specific to Gupta s implementation of the framework. Connecting To Sqlbase Page 77

78 How-to information for the.net data provider How do SQLBase datatypes map to CLR datatypes? SQLBase Type Binary Char Char>254 Date Decimal Double Float Graphic Integer Longbinary Longvar Long Varbinary (Blob) Long Varchar (Clob) Longvargraphic Number Nchar Nvarchar Smallint Time Timestamp Varchar Varchar>254 Vargraphic Varbinary CLR Type byte[] String char[] DateTime Decimal Double Single byte[] Int32 byte[] byte[] byte[] Char[] byte[] Decimal String String Int16 DateTime DateTime String char[] byte[] byte[] Connecting To Sqlbase Page 78

79 How do I start a transaction? See BeginTransaction on page 7-7, in the description of methods of the Connection object. How do I set isolation levels? Isolation level is specified as one of the parameters of BeginTransaction on page 7-7. Note that only some.net isolation levels are supported by SQLBase. The.NET isolation level behavior (eg. System.Data.IsolationLevel.ReadCommitted) can be overridden to use any allowed SQLBase isolation level to correspond to the specified.net isolation level. Any values set can be used during the lifetime of the connection to set transaction isolation levels as well (using the System.Data.IsolationLevel values). To set an isolation level when initiating a new connection using a connection string, use the following syntax (example given in C#): SQLBaseConnection conn = new SQLBaseConnection("ds = island; isolation=rc; ReadCommitted=R3"); Isolation sets the default isolation level (RC in this case) ReadCommitted sets the.net System.Data.IsolationLevel.ReadCommitted equal to, in this case, the SQLBase R3 mode. The allowed values for isolation are: RR RL CS RC R1 R2 R3 The allowed keys for the.net Isolation Level mappings are: Chaos ReadCommitted ReadUncommitted RepeatableRead Serializable Snapshot Unspecified How do I use long character data and long binary data? In this example from the Tut5 application in samples\tutorials\vb.net, a dataset is created that includes a LONG VARCHAR column, and the data from that column is subsequently placed in a byte array that will be used to construct an image. ' Setup the SQLBase connection string conn = New SQLBaseConnection("data source=island; uid = sysadm; _ pwd= sysadm; ini=d:\gupta\sqlbase 8.5\sql.ini ") Connecting To Sqlbase Page 79

80 ' Open a connection to SQLBase conn.open() ' Setup the Adapter's select command adapter.selectcommand() = New SQLBaseCommand("SELECT EMPLOYEE_ID, _ LAST_NAME, FIRST_NAME, , " & _ "CURRENT_SALARY, PHOTO1 FROM EMPLOYEE", conn) ' Create a new DataSet ds = New DataSet() ' Fill the DataSet with the Adapter adapter.fill(ds, "EMPLOYEE") ' Close the database connection conn.close() 'Create the array to store the picture Dim arrpicture() As Byte = CType(ds.Tables(0).Rows(i)("PHOTO1"), _ Byte()) In this example from the Tut5 application in samples\tutorials\vb.net, an image is used to update the EMPLOYEES.PHOTO column in the ISLAND database. Variable FileByteArray was previously initialized with the bytes of the image. ' Setup the SQLBase connection string ' & open a connection to SQLBase conn = New SQLBaseConnection("data source=island; uid = _ sysadm; pwd= sysadm; ini=d:\gupta\sqlbase 8.5\sql.ini ") conn.open() 'Setup the Update SQL & Declare a Command Object UpdCmd = New SQLBaseCommand("UPDATE EMPLOYEE SET PHOTO1=:lsPhoto _ WHERE EMPLOYEE_ID=:sEmployeeID", conn) 'Add the parameters UpdCmd.Parameters.Add("lsPhoto", DbType.Binary, o.length).value = _ FileByteArray UpdCmd.Parameters.Add("sEmployeeID", DbType.String, _ "EMPLOYEE_ID").Value = txtemployeeid.text ' Execute the command If UpdCmd.ExecuteNonQuery() Then MessageBox.Show("Image Updated", "Message") SavePictureToDB = True End If 'Close the database connection conn.close() Connecting To Sqlbase Page 80

81 How do I run stored procedures? The Visual Basic.NET code example below calls stored procedure COMPANY_SP2, which is part of the sample database ISLAND. The procedure accepts a single input parameter of type string (sname), containing a company name, and returns several string values, containing information from a row in the COMPANY table that matches the company name. ' Setup the SQLBase connection string. Be sure the ' "ini" argument points to the correct file. conn = New SQLBaseConnection("data source=island; uid = sysadm; _ pwd= sysadm; ini=c:\program files\gupta\sqlbase90\sql.ini") ' Open a connection to SQLBase conn.open() 'build a command that invokes stored procedure COMPANY_SP2 cmd = New SQLBaseCommand("COMPANY_SP2", conn) cmd.commandtype = _ CommandType.StoredProcedure 'COMPANY_SP2 requires one input parameter. It has ' four output parameters, but those don't need to be defined here. Dim sparam As SQLBaseParameter sparam = New SQLBaseParameter("sName", DbType.String) cmd.parameters.add(sparam) 'the actual reading of data could be done with a SQLBaseDataAdapter 'and a dataset, but in this case we use the SQLBaseDataReader. Dim Reader As SQLBaseDataReader 'initialize the value of the input parameter cmd.parameters("sname").value = TextName.Text call the stored procedure Reader = cmd.executereader() ' Insert code to read through the datareader. If Reader.Read() Then TextAddress.Text = Reader.GetString(0) TextCity.Text = Reader.GetString(1) TextState.Text = Reader.GetString(2) TextZip.Text = Reader.GetString(3) End If ' Close the database connection conn.close() Connecting To Sqlbase Page 81

82 SQLBaseConnection object For information about the methods, properties and events inherited from IDbConnection see the.net Framework documentation. SQLBaseConnection properties ConnectionString This property supplies basic information about the data source. It can contain multiple keyword=value parameters separated by semicolons, as described below: datasource data source ds database db=data source name string; userid user id uid=user id string; password pwd=password string; poolsize pool size=integer; connection lifetime=integer; ims=integer; oms=integer; isolation=string (2 chars); ReadCommitted=string (2 chars) All keywords except the first one are optional. Keywords are not case-sensitive. In cases where more than one keyword has the same meaning, the keywords are shown separated by pipe symbols in the diagram above. ims (input message buffer) and oms (output message buffer) are described in detail in the Configuration Files chapter of the Database Administrator s Guide. SQLBaseConnection methods BeginTransaction Syntax IDbTransaction BeginTransaction ( IsolationLevel) Description Start a new transaction. Parameters IsolationLevel string. SQLBase supports the following values in the IsolationLevel parameter: Chaos ReadUncommitted (SQLBase Release Lock) ReadCommitted (SQLBase Cursor Stability) RepeatableRead (SQLBase Repeatable Read) Serializable Snapshot Unspecified (SQLBase Repeatable Read). Use of other unsupported isolation level values will cause a SQLBase exception with Connecting To Sqlbase Page 82

83 "Unsupported isolation level : xxx." message. Related methods Commit and Rollback are also supported by the SQLBaseConnection object. ChangeDatabase Syntax void ChangeDatabase (string dbname ) Description This method is not supported by SQLBase. Calling this method will throw a NotSupportedException exception to the caller. Close Syntax void Close() Description This method logically closes your database connection. The connection may be cached rather than physically closed; for details on this, read Connection pooling in the Open method on page 7-9. CreateCommand Syntax IDbCommand CreateCommand( ) Description Initialize a new SQLBaseCommand object. GetSQLBaseSchemaTable Syntax DataTable GetSQLBaseSchemaTable (schemaguid, restrictions) Description Return a DataTable object containing schema information for the currently connected database. SQLBase supports the following types of schema information: SQLBaseSchemaGuid.Tables SQLBaseSchemaGuid.Columns SQLBaseSchemaGuid.Tables_Info SQLBaseSchemaGuid.Provider_Type SQLBaseSchemaGuid.Catalogs SQLBaseSchemaGuid.Foreign_Keys SQLBaseSchemaGuid.Primary_Keys SQLBaseSchemaGuid.Indexes SQLBaseSchemaGuid.Procedures SQLBaseSchemaGuid.Views SQLBaseSchemaGuid.Column_Privileges SQLBaseSchemaGuid.Table_Privileges Connecting To Sqlbase Page 83

84 Parameters schemaguid restrictions instance of class SQLBaseSchemaGuid String Open Syntax void Open( connection_string ) Description Opens a database connection. When you call this method, SQLBase will attempt to reuse an existing open database connection from the connection pool. If this is not possible, it will create a new database connection. Parameters connection_string string. See the detailed descriptoin of this parameter in property ConnectionString, above. Connection pooling in the Open method SQLBase provides two of the keywords in the connection string parameter of the Connect method to assist with connection pooling. poolsize indicates how many SQLBase connections should be kept open, whether they are in immediate use or not. The default value is 5. connection lifetime indicates how long each connection should be maintained, in seconds. The default value is 60. These defaults are stored in the Windows registry under key HKEY_LOCAL_MACHINE\Software\Gupta\SQLBase\DotNetDataProvider. Each connection pool is specific to the application that calls the Connect method. When the number of active connections is still below or at the poolsize limit, connections that have been closed by the application remain cached (physically open and available for new connection requests) until their lifetime is reached, at which time they are physically disconnected. Each call to Connect resets the current values for poolsize and connection lifetime. Gupta recommends that you avoid issuing Connect calls in which the new value for poolsize is smaller than the one currently being used by the application. SQLBaseCommand object For information about the methods, properties and events inherited from IDbCommand, see the.net Framework documentation. The SQLBaseCommand object is often initialized from the CreateCommand method of the SQLBaseConnection class. To release that class underlying database cursor, it is important to call the Dispose method of SQLBaseCommand when your processing is finished. Otherwise the command object is released either when the connection is released or the garbage collector releases the object, and both of these will be quite late in most circumstances. In addition, relying upon the garbage collector may mean incomplete release of all resources connected to the command object, raising the possibility of eventually running out of resources in an application with heavy use of SQLBaseCommand objects. Connecting To Sqlbase Page 84

85 SQLBaseCommand properties CommandText You should set the value of the CommandText property of the object before any other methods are called. For a Text Command type (see CommandType property), the CommandText property should contain a valid SQL statement. For a Stored Procedure type, the CommandText property should contain a procedure name. For a Table Direct type, the CommandText property should contain a table name. CommandType SQLBase supports three types of command objects: TextCommand, StoredProcedure, and TableDirect. The default type of each command object, upon creation, is Text Command. You are responsible for changing this type, if necessary, by altering the CommandType property of the object. SQLBaseCommand methods Cancel Syntax void Cancel ( ) Description Attempts to cancel the execution of a command. This method is not supported in SQLBase, and will throw a NotSupportedException when called. GetSQLBaseParameter Syntax void GetSQLBaseParameter ( parametertype, value, length ) Description Retrieves the value of an interal SQLBase parameter. SetSQLBaseParameter and GetSQLBaseParameter are not part of the IDbCommand interface. They manipulate the many SQLBase internal parameters. Detailed documentation for these parameters is available in the SQLBase SQL Application Programming Interface Reference, under the function sqlset. Parameters parametertype string. One of the many parameter names defined in the SQLBase API reference value length string, pass by reference. Contains the value returned by SQLBase. integer, pass by reference. Buffer length of value SetSQLBaseParameter Syntax void SetSQLBaseParameter ( parametertype, value, length ) Description Attempts to set a SQLBase parameter value Connecting To Sqlbase Page 85

86 SetSQLBaseParameter and GetSQLBaseParameter are not part of the IDbCommand interface. They manipulate the many SQLBase internal parameters. Detailed documentation for these parameters is available in the SQLBase SQL Application Programming Interface Reference, under the function sqlset. Note: This method should be used only by advanced SQLBase developers. Calling this method while in the middle of a transaction can potentially cause unpredictable results in the transaction or the database. parametertype string. One of the many parameter names defined in the SQLBase API reference value string. The value to set SQLBaseDataReader object For information about the methods, properties and events inherited from IDataReader, see the.net Framework documentation. This object provides the capability of reading a scrolling result set obtained by executing a command against a data source. SQLBase supports only a single result set. Datatypes are mapped to CLRcompatible types as described in How do SQLBase datatypes map to CLR datatypes? on page 7-3. To make use of scrolling result sets, property SQLBaseCommand.ResultSetMode must be set to TRUE. The SQLBaseDataReader object implements interface IEnumerable, with a single method, GetEnumerator, which returns an IEnumerator object. That object has methods MoveNext and Reset, and get/set property RowPos (current row of result set), which allow you to move to a specific row in the result set. SQLBaseDataReader methods Get... methods Syntax Int16 GetInt16 (index) Int32 GetInt32 (index) Int64 GetInt64 (index) Single GetFloat (index) byte GetByte (index) char GetChar (index) Double GetDouble (index) Decimal GetDecimal (index) Guid GetGuid (index) DateTime GetDateTime (index) TimeSpan GetTime (index) Boolean GetBoolean (index) String GetString (index) Object GetValue (index) Description Each of these methods retrieves a single value from a column in the dataset. The specific method chosen is dependent on the datatype of the column. If parameter index is not valid, exception IndexOutOfRange is thrown. Connecting To Sqlbase Page 86

87 Parameters index int. The position of the column in the result set. Get methods for long (BLOB) data Syntax Description long GetBytes (index, offset, buffer, readbytes) long GetChars (index, offset, buffer, readbytes) Reads bytes or characters from a column with a long datatype. If index is not found, throws exception IndexOutOfRange. Returns the number of bytes actually read, or, if buffer is null, the length of the column. Parameters index Long. Relative position of the column in the row. offset based. long. Offset within the long data column at which reading is to begin. Zero- Connecting To Sqlbase Page 87

88 buffer byte[] or char[], depending on method. Buffer to hold the results of the read. readbytes long. Number of bytes to read into buffer. GetDataTypeName Syntax string GetDataTypeName (index) Description Get the SQLBase (not CLR) datatype for the specified column. If index is not found, throws exception IndexOutOfRange. Parameters index int. Position of column in the result set. GetFieldType Syntax Type GetFieldType (index) Description Return the.net system type for the specified column. If index is not found, throws exception IndexOutOfRange. Parameters index int. Position of column in the result set. GetName Syntax string GetName (index) Description Get the column (field) name for the specified column. If index is not found, throws exception IndexOutOfRange. Parameters index int. Position of column in the result set. Connecting To Sqlbase Page 88

89 GetOrdinal Syntax Int16 GetOrdinal (column) Description Returns the ordinal (position in the row, beginning with one) of the column named in parameter column. If the column name is not found, throws exception IndexOutOfRange. Parameters column int. The position of the column in the result set. GetValues Syntax int GetValues (objectarray) Description Retrieves multiple values into an array of objects, rather than retrieving a single value as the other Get... methods do. It returns the actual number of valus that were retrieved: Parameters objectarray Object. An array of type Object that will receive values for each column in the result set. If there are fewer elements in the array than there are columns in the result set, then the method will fill only those elements, then stop. IsDbNull Syntax bool IsDbNull (index) Description Checks the specified column for a null value, and returns TRUE if found, or FALSE if not found. If index is not found, throws exception IndexOutOfRange. Parameters index offset of column NextResult Syntax bool NextResult ( ) Description Moves to the next result set. SQLBase supports only a single result set, so calls to this method always return FALSE. Connecting To Sqlbase Page 89

90 SQLBaseDataAdapter object This class does not inheirt from SqlDataAdapter, since that class contains logic that is specific to Microsoft SQL Server. However, its function is quite similar; a data adapter has a database connection and a group of commands that are designed to move data from the database into a data set object. This class inherits from the more general DbDataAdapter class. For information about the methods, properties and events inherited from DbDataAdapter, see the.net Framework documentation. The methods of this class are all inherited from the standard DbDataAdapter class, which can be found in the Microsoft.NET Framework documentation. To complete the functionality of this class, SQLBase must implement four properties that are found in the DbDataAdapterInterface. Each of these properties has Get and Set methods. SQLBaseDataAdapterProperties DeleteCommand Contains the text of a SQL query used to delete records. InsertCommand Contains the text of a SQL query used to insert new records. SelectCommand Contains the text of a SQL query used to select records. When a.net client calls the dataadapter.fill ( ) method it will execute the command which is contained in the SelectCommand property. The command object will return a IDataReader interface to the data adapter after executing the command, and the data adapter will use that interface to get data from the data source and fill the System.DataSet object. After that client can manipulate the data in in the DataSet object through DataSet methods. UpdateCommand Contains the text of a SQL query used to update records. When a.net client calls the dataadapter.update ( ) method it will execute the three commands contained in the UpdateCommand, InsertCommand and DeleteCommand properties, and update the data source through these commands with the changes in the DataSet. SQLBaseTransaction object For information about the methods, properties and events inherited from IDbTransaction, see the.net Framework documentation. Connecting To Sqlbase Page 90

91 SQLBaseTransaction Properties Connection Datatype: SQLBaseConnection. The Connection object which should be passed to this object in the constructor. IsolationLevel Datatype: IsolationLevel. Get only. The IsolationLevel enumeration which should be passed to this object in the constructor from the connection s BeginTransaction ( ) method. SQLBaseTransaction methods Commit Syntax void Commit ( ) Description Commit the database transaction. The current transaction is complete. The client should call BeginTransaction method from the Connection object to start a transaction again. Rollback Syntax void Rollback ( ) Description Roll back a transaction from a pending state. SQLBaseParameter object For information about the methods, properties and events inherited from IDbTransaction, see the.net Framework documentation. This object has four properties and no methods. You must set its properties to appropriate values before supplying this object to the SQLBaseCommand object before execution. Properties DbType: DbType Get/Set. The CLR datatype of the parameter. String: ParameterName Get/Set. The name that the command object uses to refer to the parameter. String: SourceColumn Get/Set. Links this parameter to a column in a DataSet object. Connecting To Sqlbase Page 91

92 Object: Value Get/Set. The actual value assigned to this parameter. SQLBaseParameterCollection object This object is basically a collection of SQLBaseParameter objects. The Add method is overloaded in five ways. Add Syntax (Overload 1) SQLBaseParameter Add (value) Description Adds a parameter Parameters value object. Syntax (Overload 2) SQLBaseParameter Add (value) Description Adds a parameter Parameters value SQLBaseParameter Syntax (Overload 3) SQLBaseParameter Add (parametername, type) Description Adds a parameter Parameters parametername dbtype string. Datatype of the parameter. Syntax (Overload 4) SQLBaseParameter Add (parametername, dbtype) Description Adds a parameter Connecting To Sqlbase Page 92

93 Connecting To Sqlbase Page 93

94 Parameters parametername value string. Name of the parameter. object. Value of the parameter. Syntax (Overload 5) SQLBaseParameter Add(parameterName, dbtype, column) Description Adds a parameter Parameters parametername type column string. Name of the parameter. DbType. Datatype of the parameter. string. Data set column associated with the parameter. SQLBaseException object This object handles all errors returned by SQLBase. SQLBaseException Properties int: ErrorCode Get only. The SQLBase numeric code of the error. int: ErrorPosition Get only. The offset in the command text where the error was detected. String: ErrorMessage Get only. The description of the error. SQLBase classes and transaction state It is possible in the.net framework to write code that could disrupt the state of a SQLBase transaction. To prevent this disruption, the SQLBaseCommand class will throw an exception if you try to change its Transaction property to anything other than the result of the last call to SQLBaseConnection.BeginTransaction: Failed to set transaction for the command. The transaction is not compatible with the connection. The exception guards against situations like the example below: Open a SQLBaseConnection object named conn Create a SQLBaseCommand object against conn named cmd Connecting To Sqlbase Page 94

95 Create a SQLBaseTransaction object named txn by calling the conn.begintransaction method. (Now this database connection is logically inside a transaction.) The commands belonging to the connection, including cmd, will acquire txn in their Transaction property. Set the cmd.transaction property to null. (This would mean that the command no longer participates in the txn transaction.) Execute the command. Commit but how? The Commit method is part of the SQLBaseTransaction class, and we have set cmd.transaction to null, so we have no object to use for calling that method. Because you changed the SQLBaseCommand.Transaction property, the SQLBase connection is now in an inconsistent state, running a pending SQLBase engine transaction that can t or won t be committed because the necessary.net transaction is no longer associated with that connection. The.NET interface definitions imply that you can have a command object whose Transaction property points to a transaction created under some other database connection, not the connection used when the command was initialized. Despite this theoretical possibility, Gupta recommends that you think of the connection, transaction and command objects as a set that reference each other. This is a more accurate reflection of how the SQLBase engine works internally a commit on a SQLBase connection commits all the cursors that are active against that connection. So, from the.net viewpoint, a call to cmd.transaction.commit will commit not just cmd, but all other commands that belong to the same connection. Note that this concept also applies if your application is running some commands under a transaction and other commands without a transaction. In this situation, the commands belonging to the transaction need a separate connection of their own. To summarize this issue in two brief rules: 1. Whatever its current value, you must not change the SQLBaseCommand.Transaction property to a different value. If you attempt to do this, an exception will be thrown. 2. If you wish to have multiple transactions active simultaneously in your application, make sure that you have a separate SQLBaseConnection object associated with each transaction, and make sure that the SQLBaseCommand objects relevant to that transaction also belong to the same connection. A transaction and a connection have a one-to-one relationship that must not be altered. Connecting To Sqlbase Page 95

96 Chapter 8 Introduction to the JDBC driver This chapter describes specific issues relating to the Gupta SQLBase JDBC (Java Database Connectivity) Driver. For general information on JDBC Drivers, we recommend you visit java.sunt.com or read one of the many published books on JDBC Drivers. The example source code shown in this chapter is derived from the files available in the Samples subdirectory of the SQLBase program directory (presuming that you asked to install samples during installation.) Introduction The SQLBase JDBC driver supports applications written using JDBC and higher. It is a Type 4 Driver according to the definition published by Javasoft, meaning that it is a native-protocol driver which converts JDBC calls into the network TCP/IP protocol used by the database server, requiring no additional middle layer components of either the client or the server. The SQLBase JDBC Driver is therefore both thin and portable. Using this driver, developers can create Java applets that connect to remote SQLBase databases resident on Web Servers, or create Java applications that connect to SQLBase databases on either local or remote machines, using SQLBase's existing TCP/IP protocol support. JDK Versions There are multiple versions of the Java Development Kit (JDK). This driver is compatible with JDK 1.1.x and higher. Modern Web browsers such as Netscape Communicator version 4 and higher, and Microsoft Internet Explorer version 4 and higher, support JDK 1.1.x, including JDBC functionality. Installation Tested Platforms This driver has been tested on Windows 98, ME, NT, 2000, Server 2003, and XP, and (for Linux) on Red Hat 9.0, Red Hat Advanced Server 3.0, SUSE 9.0, SUSE Enterprise Server 8.0, SUSE Desktop 1.0. Connecting To Sqlbase Page 96

97 Getting Started Windows You can request JDBC support during the initial install of SQLBase The default directory for SQLBase itself is c:\program files\gupta\sqlbase90. Presuming you also install the JDBC driver to this directory, then after installation, the following files and directories will be found. c:\program files\gupta\sqlbase90\java\sqlbasejdbc.jar - Contains the JDBC class files. c:\program files\gupta\sqlbase90\samples - Contains a set of sample JDBC application programs as tutorials. Linux JDBC support is an option at the time of installation in Linux. If you use the default installation directory, the following file will be installed: /opt/gupta/sqlbase90/java/sqlbasejdbc.jar - JDBC class files CLASSPATH To allow the Java Virtual Machine to load the SQLBase JDBC Driver locally or at the host-of-origin, the standard Java system environment variable CLASSPATH must be modified to include the root directory containing the JDBC classes. For example, if you chose the SQLBase default directory as your installation directory, you would set the variable as follows on Windows: SET CLASSPATH=%CLASSPATH%;C:\program files\gupta\java\sqlbasejdbc.jar And on Linux, if you chose the default installation directory, CLASSPATH would be altered like this: export CLASSPATH=$CLASSPATH:/opt/Gupta/SQLBase90/java/SQLBaseJDBC.jar Server Configuration The server should be configured to listen on TCP/IP protocols. For more information regarding the use of TCP/IP, please refer to the SQLBase Database Administrator's Guide chapter on communications. SQLBase Support for JDBC SQL Operations Support The SQLBase JDBC Driver is designed to access relational database over the Internet or an Intranet. It currently supports common DDL and DML operations. DDL Operations Support All DDL operations, such as creating tables, dropping tables, and creating indices are supported. Operations which require a server connection, such as loading and unloading, backup, and restore are not supported in this release of the JDBC Driver since such connections are not supported by JDBC. Connecting To Sqlbase Page 97

98 DML Operations Support Most DML operations such as insertions, deletions, updates, selects (including data binding), long varchars, and stored procedures are supported. The "ADJUSTING" clause of the INSERT keyword is not supported. Multiple Connection Support The SQLBase JDBC Driver supports the multiple connection model of SQLBase 7.0 and higher. An application can establish multiple connections ("cursor handles") to a SQLBase Server, and transactions committed for one connection are completely independent of transactions committed for another connection. Multi-threading Support The JDBC Driver is implemented to be thread safe. An application can use multiple threads to perform operations on various tables while the user continues to interact with the application. It is NOT recommended that JDBC objects (i.e. Statement, ResultSet etc.) are shared between threads because an object's internal state can be corrupted by interleaved threads. Each thread should operate privately on JDBC objects. Transaction Model The transaction model is uniform between the SQLBase ODBC Driver and the JDBC Driver. Isolation Level TRANSACTION_NONE Description AutoCommit plus RL (release locks) isolation TRANSACTION_READ_COMMITTED CS (cursor stability) TRANSACTION_SERIALIZABLE Not Supported (Creates an Exception) TRANSACTION_READ_UNCOMMITTED Not Supported (Creates an Exception) TRANSACTION_REPEATABLE_READ RR For SQLBase specific applications or applets that require a strict SQLBase transaction model, the SQLBase JDBC Driver provides an extended TRANSACTION MODE as indicated below: Isolation Level TRANSACTION_SQLBASE_RL TRANSACTION_SQLBASE_RR TRANSACTION_SQLBASE_CS TRANSACTION_SQLBASE_RO TRANSACTION_SQLBASE_RC Description RL (release locks) isolation RR (read repeatability) isolation CS (cursor stability) isolation RO (read only) isolation RC (read committed) isolation Connecting To Sqlbase Page 98

99 TRANSACTION_SQLBASE_RC1 RC1 (read committed-1) isolation * TRANSACTION_SQLBASE_RC2 RC2 (read committed-2) isolation * TRANSACTION_SQLBASE_RC3 RC3 (read committed-3) isolation * * These isolation levels were added in version 11.6, and differ as follows: RC1 - Timestamp changes when a transaction has no active commands and a new command starts. Starting a new cursor has no effect. RC2 - Timestamp changes when a new command starts in a transaction (multiple cursor scenario). Starting a new cursor moves the timestamp. RC3 - Timestamp changes when a new row is fetched or any other API call on a transaction is invoked. The default TRANSACTION isolation for the JDBC Driver is TRANSACTION_REPEATABLE_READ. How-to information for the JDBC driver How do SQLBase datatypes map to JDBC datatypes? See SQLBase Supported Data Types: on page 8-8 How do I start a transaction? A code fragment illustrating a simple transaction is shown below. Changing the setting of AuoCommit implicitly starts a new transaction. Connection con1 = DriverManager.getConnection(url, "SYSADM", "SYSADM"); con1.setautocommit(false); Statement stmt1 = con1.createstatement(); try { stmt1.executeupdate("drop TABLE TESTAC1"); } catch (SQLException se) { // Do nothing if table does not exist } stmt1.executeupdate("create TABLE TESTAC1 (C1 INT, C2 CHAR(10))"); con1.commit(); stmt1.close(); Connecting To Sqlbase Page 99

100 How do I set isolation levels? Use method settransactionisolation, as shown below. Connection con1 = DriverManager.getConnection(url, "SYSADM", "SYSADM"); con1.settransactionisolation(connection.transaction_none); The supported isolatoin levels are shown in Transaction Model on page 8-4. To set an isolation level using a connection string, use the isolation keyword, and set it to one of the following values: RR RL CS RC R1 R2 R3 How do I use long character data and long binary data? In this code fragment from sample program longs.java, included with SQLBase, you can see methods getasciistream and setasciistream are used to bind long data to specific symbol positions in a SQL query statement. In this example, the number 1 used as the first parameter in the method refers to the second column or second bind variable (in a zero-based list). stmt.executeupdate("create table test(c1 int, c2 long varchar)"); con1.commit(); System.out.println("inserting long data"); //Inserting Long Data java.io.file file = new java.io.file("longs.txt"); long filelength = file.length(); java.io.inputstream fin = new java.io.fileinputstream(file); java.sql.preparedstatement pstmt = con1.preparestatement ("INSERT INTO test VALUES (1,?)"); stmt.setasciistream(1, fin,(int)filelength); pstmt.executeupdate(); //Fetching Long Data byte [] buff = new byte[4096]; ResultSet rs = stmt.executequery("select c1 = 1 "); while (rs.next ()) { fin = rs.getasciistream(1); } How do I run stored procedures? See Stored procedure support on page 8-11 c2 FROM test WHERE URL formats Examples of use of the standard formats are illustrated below: Connecting To Sqlbase Page 100

101 jdbc:sqlbase://localhost[:2157]/island [;ims=;oms=] jdbc:sqlbase://server1[:2157]/island [;ims=;oms=] jdbc:sqlbase:// xxx.xx:2156/island [;ims=;oms=] URL keywords: jdbc:sqlbase: is the JavaSoft registered URL keyword for SQLBase localhost is used to refer to the host name of the local machine server1 is the host name of the machine server1 The default port used by SQLBase to receive incoming TCP/IP requests is It needs to be specified only when a different port number is being used by the SQLBase server, in which case it follows the host name or IP address, separated by a colon. island is the database where this URL is intended to connect xxx.xx is an IP address. ims (optional) is input message buffer size. Use a value from 1 to If no value or an invalid value is specified, the default of ims=2000 will be used. oms (optional) is output message buffer size. Use a value from 1 to If no value or an invalid value is specified, the default of oms=1000 will be used. Data types and conversions SQLBase data types do not map completely to Java data types. The following conversion table is provided to show the mapping between SQLBase storage types and the Java data types: Explanation of keys: Key C Description Conversion is done - a conversion warning is issued for accuracy check D Date crash is done E Throw exception - this conversion is not allowed W Field width and data width mismatch - a truncation warning is issued for loss of digits * No warning - a valid get/set is performed Connecting To Sqlbase Page 101

102 SQLBase Supported Data Types: SQL Data Type CHAR, DATE DATETIME DECIMAL DOUBLE FLOAT INTEGER LONG VARBINARY (BLOB) LONG VARCHAR (CLOB) NCHAR NUMBER NVARCHAR REAL TIME VARCHAR JDBC Data Type CHAR DATE DT NUM NUM NUM NUM LONGVARBINARY LONG CHAR NUM VARCHAR NUM TIME VARCHAR For READING Operations using ResultSet: CHAR NUM DATE LONG DT TIME ResultSet Methods W W W W W W getstring from CHAR,VARCHAR C * E E E E getbigdecimal from NUMERIC C C E E E E getbool from BIT C W E E E E getbyte from TINYINT C W E E E E getshort from SMALLINT C W E E E E getint from INTEGER Connecting To Sqlbase Page 102

103 CHAR NUM DATE LONG DT TIME ResultSet Methods C W E E E E getlong from BIGINT C W E E E E getfloat from REAL C W E E E E getdouble from DOUBLE * C C * C C getbytes[] ** C C * E C C getdate from DATE C C C E C * gettime from TIME C C C E * C gettimestamp from TIMESTAMP * C C * C C getstream from LONGVARCHAR ** same as getstream from VARBINARY or LONGVARBINARY Datatypes example This example shows the use of various methods (setstring, setshort, etc.) in preparing bind variable datatypes. Similar methods (getstring, getshort, etc.) are used when retrieving individual values from result sets. public class InsertDataTypes { private static String url = "jdbc:sqlbase://localhost:2155/ ISLAND"; private static void executeupdate(statement stmt, String sql ) { try { stmt.executeupdate(sql); } catch (Exception ex) { System.out.println("'" + sql + "' failed with: " + ex); } } public static void main (String args[]) { try { Class.forName("jdbc.gupta.sqlbase.SqlbaseDriver"); if ( args.length > 0 && args[0].length() > 0) { url = args[0]; Connecting To Sqlbase Page 103

104 } // ENDIF Get Connection URL Connection con1 = DriverManager.getConnection(url, "SYSADM", "SYSADM"); Statement stmt = con1.createstatement(); try { executeupdate(stmt, "drop table foosh"); } catch (Exception e) { System.out.println("e = " + e.getmessage()); } String squery = "Create table foosh (C1 char(10)," + "C2 varchar(10), C3 dec(8,2), C4 integer," + "C5 smallint, C6 float," + " C7 datetime, C8 time, C9 date)"; executeupdate(stmt, squery); con1.commit(); System.out.println("Will insert 9 columns to the row"); PreparedStatement pstmt = con1.preparestatement( "Insert into foosh values(?,?,?,?,?,?,?,?,?)"); java.sql.datex = java.sql.date.valueof(" "); java.sql.timestamp = java.sql.timestamp.valueof(" :59:59.0"); Time z = Time.valueOf("23:30:15"); short a = 8; pstmt.setstring(1,"sushi"); pstmt.setstring(2,"wushi"); pstmt.setdouble (3, ); pstmt.setint (4,31); pstmt.setshort (5,a); pstmt.setfloat (6,18.0f); pstmt.settimestamp(7,y); pstmt.settime(8,z); pstmt.setdate(9,x); int n = pstmt.executeupdate(); Statement stmt1 = con1.createstatement(); ResultSet rs = stmt1.executequery( "select C1,C2,C3,C4, C5, C6, C7,C8,C9 from foosh"); while (rs.next()) { String s1 = rs.getstring(1); String s2 = rs.getstring(2); double d = rs.getdouble("c3"); int i = rs.getint(4); Connecting To Sqlbase Page 104

105 float f = rs.getfloat(6); java.sql.timestamp d1 = rs.gettimestamp(7); java.sql.time d2 = rs.gettime(8); java.sql.date d3 = rs.getdate(9); System.out.println("C1 = " + i); System.out.println("C2 = " System.out.println("C3 = " System.out.println("C4 = " System.out.println("C5 = " System.out.println("C6 = " System.out.println("C7 = " System.out.println("C8 = " } con1.commit(); con1.close(); + s1); + d); + i); + f); + d1); + d2); + d3); } } } } catch (Exception ex) { System.out.println("Exception in main: " + ex); } Bind variable support The SQLBase JDBC Driver supports the bind variable escape character '?' in a SQL statement. The driver attempts to parse the '?' from the input SQL statement. The parser skips over '?' characters that are used within single quoted expression constants or double quoted identifier to avoid disruption of the syntax of the SQL statement. The example source code above, for datatypes, also illustrates the use of bind variables within SQL queries. Stored procedure support The SQLBase JDBC Driver supports the CallableStatement { call?,... } syntax. However, since SQLBase Stored Procedures do not support any OUT parameters, a SQLException will be thrown when the CallableStatement.registerOutParameter(...) method is called. This restriction also invalidates the [? =] portion of the { [? =] call?,... } syntax. SQLBase stored procedures return the result via a ResultSet. After executing the Connecting To Sqlbase Page 105

106 CallableStatement, a getresult() method can be called to retrieve result data. ResultSetMetaData is also helpful in determining the column types, column lengths and other information about the result data. To provide input parameters, the CallableStatement.setXXX() methods can be called to pass Java data types from the caller to the stored procedure as bind data. Stored procedure example This program does an insert on execution of a procedure. To prepare for this test you need to do some work on the database. First, you need to make sure there is a table named FOO (C1 int,c2 char(10)) in database ISLAND. Second, you need to store the following procedure... STORE JAVA_PROC_1 PROCEDURE: JAVA_PROC_1 PARAMETERS Number: x ACTIONS On Procedure Execute Call SqlImmediate('insert into foo values(:x, \'Gupta\')') When you are done, you can drop FOO and ERASE JAVA_PROC_1..now, the example program. import java.io.*; import java.util.*; import java.sql.*; public class Proc { private static String url = "jdbc:sqlbase://localhost:2155/ ISLAND"; public static void main (String args[]) { try { Class.forName("jdbc.gupta.sqlbase.SqlbaseDriver"); if (args.length > 0 &&args[0].length() > 0) { url = args[0]; } // ENDIF Get Connection URL Connection con = DriverManager.getConnection(url, "SYSADM", "SYSADM"); CallableStatement cstmt = con.preparecall("{call Java_Proc_1}"); cstmt.setint(1,45); cstmt.executeupdate(); Connecting To Sqlbase Page 106

107 } } con.commit(); // Is it there? Statement s = con.createstatement(); ResultSet r = s.executequery("select C1,C2 FROM FOO"); while (r.next()) { int i = r.getint(1); String str = r.getstring(2); System.out.println("C1: " + i + " C2: " + str); } cstmt.close(); s.close(); con.close(); } catch (Exception ex) { System.out.println("\nException in main: " + ex + "\n"); System.out.println("Unable to access or execute procedure Java_Proc_1"); } Named Cursor Support Cursor naming is supported by the SQLBase JDBC Driver. Cursor names are generally used in conjunction with the WHERE CURRENT OF clause of an UPDATE or DELETE statement. After the cursor name is set for a Statement or PreparedStatement object (using method setcursorname) the executequery() can be called to prepare a SELECT statement. Connection con1 = DriverManager.getConnection(url, "SYSADM", "SYSADM"); con1.settransactionisolation(statement stmt2 = con1.crea Connection.TRANSACTION_REPEATABLE_READ);... Statement stmt2 = con1.createstatement(); stmt2.setcursorname("c2"); Statement stmt1 = con1.createstatement(); ResultSet rs = stmt2.executequery("select C1,C2 FROM FOO FOR UPDATE OF C1"); The cursor name can then be used by other Statement or PreparedStatement objects with the WHERE CURRENT OF clause in SQL statements. while (rs.next()) { int k = rs.getint(1); String s = rs.getstring(2); if (k == 2) Connecting To Sqlbase Page 107

108 executeupdate(stmt1, "UPDATE FOO SET C1 = 200 WHERE CURRENT OF C2"); Error Message Support This release provides a simplified version of error message text from error.sql. However, in order to keep the memory consumption down and the SQLBase JDBC thin, error tokens, reason and remedy are not supported. Application and Applet Development Java Virtual Machine reserves the java.xxx.xxx package for its own libraries. Generally, any library that is not part of the JVM cannot use the java.xxx.xxx package. The java.xxx.xxx package is critical to applets. Loading a library from unrecognized java.xxx will result in "class not found" exception being thrown by the SecurityManager. To avoid this problem, the SQLBase JDBC Driver is normally packaged under the jdbc.gupta.sqlbase.* package. If you encounter problems during execution of the sample Java programs, you should examine CLASSPATH to ensure that it contains a path to the location of the SQLBase JDBC Driver classes. To allow the SQLBase error text to be displayed by the JDK 1.1.x line of the SQLBase JDBC Driver, the error.html file must be copied to the WWW root directory or the <HOME> directory of the system where the SQLBase JDBC Driver is installed, in this case the host-of-origin. Restrictions All of the documented JDBC API is included in this release. Certain functionality of the API is neither completely supported, directly relevant nor necessarily supportable by SQLBase. Where this occurs, SQLException will be thrown with the "...not supported..." message. Network Check Network check (netcheck) is not implemented in the SQLBase JDBC Driver. If network check is set in the SQL.INI file for the SQLBase server, the JDBC driver may not be able to communicate with the server. SQLWarning Support In general, SQLBase does not support warnings. However, the warning processing using SQLWarning is implemented in the SQLBase JDBC Driver for trapping potential problems generated during data conversion. Encrypted Databases Applications using the JDBC Driver cannot connect to encrypted SQLBase databases. NLS and DBCS Databases The JDBC Driver supports non-us databases. Please refer to the file CountrySetting.java file in the samples directory for more information on how to connect to non-us databases. DBCS databases are also supported in this release. Connecting To Sqlbase Page 108

109 Chapter 9 Encrypting database connections using Secure Sockets Layer (SSL) This chapter describes the client-side configuration to permit TCP/IP based connections to enable encryption via Secure Sockets Layer (SSL). Secure Sockets Layer (SSL) Secure Sockets Layer (or SSL) is a standards-based method of securing network connections. SQLBase 11.7 adds the capability to use SSL to encrypt communications across TCP/IP network connections. The encryption makes it very difficult to snoop the database messages transmitted between the server and client. All SQLBase 11.7 or higher clients (C API,.NET, ODBC, OLEDB, JDBC) can make SSL connections. Configuring SSL encryption For an encrypted SSL connection to be established, the following is required: The connection must be done over TCP/IP (either IPV4 or IPV6). Both the client and server must be version 11.7 or higher. The server must be configured for SSL. The server configuration is documented in the SQLBase Database Administrator s Guide, chapters 4 and 8. SQLBase 11.7 and higher clients (other than the.net Data Provider) will by default request an SSL connection from the server. If the server is configured for SSL an encrypted connection will be established, otherwise a plaintext connection is made. The.NET Data Provider will not use SSL unless it is specifically configured to do so. The SSL client configuration parameter. The behavior of the client is configurable via the SSL configuration parameter. The SSL configuration parameter can take the following values: ssl=negotiate ssl=always The client will request an SSL connection from the server and fall back to a plaintext connection if SSL is unavailable. This is the default setting for the ssl configuration parameter on all clients except for the.net data provider. The client requires an SSL connection. If SSL is unavailable, the client will reject the Connecting To Sqlbase Page 109

110 connection attempt. ssl=never The client does not attempt to establish an SSL connection. The server will reject the connection if it is configured to only allow SSL connections. This is the default setting for the.net data provider. The SSL client configuration parameter interacts with the server s SSL configuration settings as described in the following table: Server Settings SSL not configured or pre-11.7 server SSL configured, sslonly=0 SSL configured, sslonly=1 ssl=negotiate Non-SSL (plaintext) connection established SSL connection (encrypted) established SSL connection (encrypted) established Client Settings ssl=always Connection rejected by client SSL connection (encrypted) established SSL connection (encrypted) established ssl=never, or pre-11.7 client. Non-SSL (plaintext) connection established Non-SSL (plaintext) connection established Connection rejected by server Setting the SSL configuration parameter The SSL configuration parameter can be set either in the client connection string (C API,.NET data provider, OLEDB, ODBC), at the end of the JDBC connection URL or in the SERVERPATH configuration setting in the client s SQL.INI. In the case of the ODBC driver, it can also be set in the Additional options field of the Gupta SQLBase Data Source Properties dialog in the ODBC Administrator. For example: SQL.INI serverpath=server1,localhost,2155/*;ssl=always ODBC DSN=Island;SERVER=SERVER1;DATABASE=PAYROLL;UID=JOHN;PWD=XYZZY;SSL=never OLEDB Provider=SQLBASEOLEDB;Data Source=ISLAND;User ID=SYSADM;Password=sysadm;SSL=negotiate Connecting To Sqlbase Page 110

111 .NET Data Source=localhost;Initial Catalog=ISLAND;ServerName=Server1; User=SYSADM;Password=SYSADM;SSL=always JDBC jdbc:sqlbase://localhost:2155/island;ssl=always Connecting To Sqlbase Page 111

112 Glossary A Abort To return the values changed by a transaction to their original state. Accessor A collection of information that describes how data is stored in the consumer's buffer. The provider uses this information to determine how to transfer data to and from this buffer. See also reference accessor. Accessor handle A handle that identifies an accessor. Auto-commit mode A transaction commit mode in which all actions taken in a transaction are committed immediately after they are performed. B Binary large object (BLOB) Any binary or character data over a certain number of bytes, such as 255. Typically much longer. Such data is generally sent to and retrieved from the data source in parts. Also known as long data. Binding As a verb, the act of associating a column in a rowset or a parameter in a text command with a consumer variable. As a noun, the association or the DBBINDING structure that describes the association. Bookmark A value that identifies a row in a rowset. Bookmarks are saved by the consumer and used later in the life of the rowset to retrieve a particular row. BSTR A pointer to a null-terminated character string in which the string length is stored with the string. B-tree A tree structure for storing database indexes. Buffer A piece of memory used to pass information, usually data, between the consumer and provider. C Catalog A database object that contains one or more schemas. Change To update, delete, or insert a row of data. Class ID A globally unique identifier (GUID) associated with an OLE class object. If a class object will be used to create more than one instance of an object, the associated server application should register its CLSID in the system registry so that clients can locate and load the executable code associated with the object(s). Every OLE server or container that allows linking to its embedded objects must register a CLSID for each supported object definition. Client/server A database access strategy in which one or more clients access data through a server. The clients generally implement the user interface while the server controls database access. Column The container for a single item of information in a row. Also known as field. Connecting To Sqlbase Page 112

113 Column ID A structure used to identify a column, primarily in a command where there are no stable ordinals or column names. COM object An object that conforms to the OLE Component Object Model (COM). A COM object is an instance of an object definition, which specifies the object's data and one or more implementations of interfaces on the object. Clients interact with a COM object only through its interfaces. See also Component Object Model and interface. Command An OLE DB object that encapsulates a command. Command text The text command associated with a command object. Although it is not required to be, this is usually an SQL statement. Commit To make the changes in a transaction permanent. Component An object that encapsulates both data and code, and provides a well- specified set of publicly available services. Component Object Model (COM) The OLE object-oriented programming model that defines how objects interact within a single process or between processes. In COM, clients have access to an object through interfaces implemented on the object. See also interface. Concurrency The ability of more than one transaction to access the same data at the same time. Consumer Software that calls OLE DB methods and interfaces. Container A file containing linked or embedded objects. Convert To change data from one type to another, such as from an integer to a string. Coordinated transaction A transaction composed of multiple, subordinate transactions. All of the subordinate transactions must succeed for the coordinated transaction to succeed. Also known as a distributed transaction. CoType A way to define a group of COM objects, such as rowsets or commands, that have similar characteristics. All COM objects that belong to a particular CoType must expose the mandatory interfaces in that CoType. In addition, they can expose the optional interfaces in the CoType and any interfaces not in the CoType. D Data The data for a parameter in a text command or a column in a row. Data Definition Language (DDL) Those text commands that define, as opposed to manipulate, data. For example, the SQL statements CREATE TABLE, CREATE INDEX, GRANT, and REVOKE. Data Manipulation Language (DML) Those text commands that manipulate, as opposed to define, data. For example, the SQL statements INSERT, UPDATE, DELETE, and SELECT. Data part Data has three parts: the data value, the length of the data value, and the status of the data value. Data provider A provider that directly exposes data, as opposed to a service component. Data source The data the user wants to access, such as the data in a database, file, or array. This is distinct from a data source object. Connecting To Sqlbase Page 113

114 Data source object An OLE DB object that connects to a data source. This is distinct from the data source. Data type The type of a piece of data. See also type indicator. Database A discrete collection of data in a DBMS. Also a DBMS. Database Management System (DBMS) A layer of software between the physical database and the user. The DBMS manages all access to the database. An OLE DB provider can be built directly on top of a DBMS or as a layer between the DBMS and the consumer. Deferred column A column for which the data is not instantiated in the rowset until the consumer actually attempts to access that data. Delayed update mode An update mode in which changes made through IRowsetChange are cached in the rowset and transmitted to the data source only when IRowsetUpdate::Update is called. See also immediate update mode. Delete To remove an existing row of data from the data source. Distributed transaction See coordinated transaction. Dynamic error An error message that cannot be predicted because it is not provider specific.dynamic error ID An identifier that is used by a lookup service and is associated with an error object. E Empty string A zero-length string. See also null pointer and NULL value. Endogenous change A change to data originating from a process other than your own. Enumerator An OLE DB object that searches for data sources and other enumerators. See also root enumerator. Error A condition in which a fatal error occurred. Also used to refer to any error, regardless of whether it is fatal. Error code A class of return code, of the type HRESULT, that begins with E_ or DB_E_ and indicates that the method failed completely and was unable to do any useful work. Error lookup service A method used by a provider to handle and interpret OLE DB error objects. Error object An object that contains detailed information about an error. See also OLE Automation error object and OLE DB error object. Event An action taken by a provider, such as changing a column value or deleting a row, of which the provider notifies the consumer. Execution plan A plan generated by a query engine to execute a command. Equivalent to executable code compiled from a third-generation language such as C. F Fetch To retrieve one or more rows from the data source and instantiate them in a rowset. Field See column. Connecting To Sqlbase Page 114

115 Fixed-length data type A data type that is always stored in the same number of bytes, such as a two-byte integer. See also variable-length data type. Foreign key A column or columns in a table that match the primary key in another table. G Getting data Transferring data from the provider to the consumer, as in getting column or output parameter data. Globally Unique Identifier (GUID) A 16-byte value that uniquely identifies something, usually the software that implements one or more COM objects or an interface on one of those objects. Also known as a UUID (Universally Unique Identifier). H Handle A value that uniquely identifies something such as a row or an accessor. Handles are meaningful only to the software that creates and uses them, but are passed by other software to identify things. HRESULT An opaque result handle defined to be zero for a successful return from a function and nonzero if error or status information is returned. I Interface Identifier (IID) A globally unique identifier (GUID) associated with an interface. Some functions take IIDs as parameters to allow the caller to specify which interface pointer should be returned. Immediate update mode An update mode in which changes made through IRowsetChange are immediately transmitted to the data source. See also delayed update mode. Index rowset A rowset built over an index. Each row in an index rowset contains a bookmark that points to a row in a rowset built over the corresponding table. Initialize To change the state of an enumerator or data source object so it can be used to access data. For example, initializing a data source object might require the provider to open a data file or connect to a database. Input parameter A parameter in a text command for which the consumer supplies a value to the provider. Input/output parameter A parameter in a text command for which the consumer supplies a value to the provider and the provider returns a value to the consumer. Insert To add a new row of data to the data source. Instantiate To create an instance of a COM object. Interface A group of semantically related functions that provide access to a COM object. Each OLE interface defines a contract that allows objects to interact according to the Component Object Model (COM). Although OLE provides many interface implementations, most interfaces can also be implemented by developers designing OLE applications. See also Component Object Model and COM object. Connecting To Sqlbase Page 115

116 IPersist* object An OLE object that supports IPersistStream, IPersistStreamInit, or IPersistStorage. Isolation level See transaction isolation level. J JDBCA set of Java classes which standardizes access to any vendor s database from Java applications or applets. Join An operation in a relational database that links the rows in two or more tables by matching values in specified columns. K Key A column or columns whose values identify a row. See also primary key and foreign key. Key value bookmark A bookmark that uses a unique key to identify a row. See also numeric bookmark. L Length The length of a data value. See also data part, value, and status. Listener A consumer that has requested that a provider send it notifications of various events. Long data See BLOB. M Manual-commit mode A transaction commit mode in which transactions must be explicitly committed or aborted by calling ITransaction::Commit or ITransaction::Abort. Maximum precision The maximum number of base 10 digits that can be stored in a particular data type. See also precision. Metadata Data that describes a parameter in a text command or a column in a rowset. For example, the data type, length, and updatability of a column. Method A function in an interface. Moniker A name for a specific object instance. Multiple results object An OLE DB object created by executing a command and through which multiple results (rowsets or row counts) can be retrieved. N Next fetch position The position of the next row that will be fetched by a call to IRowset::GetNextRows. Notification A call from a provider to a consumer, in which the provider notifies the consumer that a particular event is occurring. Notification sink An actual object that implements the notification interface. Null pointer A pointer with a value of zero. It is an error to dereference a null pointer. See also empty string and NULL value. Connecting To Sqlbase Page 116

117 NULL value Having no explicitly assigned value. In particular, a NULL value is different from a zero or a blank. See also empty string and null pointer. Numeric bookmark A bookmark that uses a unique number to identify a row. See also key value bookmark. O Object In OLE, a programming structure encapsulating both data and functionality that are defined and allocated as a single unit and for which the only public access is through the programming structure's interfaces. A COM object must support, at a minimum, the IUnknown interface, which maintains the object's existence while it is being used and provides access to the object's other interfaces. See also Component Object Model and interface. ODBC Microsoft s earliest standard for OLE Microsoft's object-based technology for sharing information and services across process and machine boundaries. OLE Automation error object An error object that conforms to the standards specified for such objects by OLE Automation. See also OLE DB error object. OLE DB A set of interfaces that expose data from a variety of data sources using COM. OLE DB error object An error object used by OLE DB objects to return an error. OLE DB error objects are an extension of Automation error objects. OLE DB object A COM object defined by OLE DB. The COM objects defined by OLE DB are enumerators, data source objects, sessions, commands, rowsets, multiple results objects, OLE DB error objects, transaction objects, and transaction options objects. OLE DB Software Development Kit (SDK) A collection of redistributable software, header files, tools, sample code, and documentation to be used by developers of OLE DB consumers and providers. OLE object In OLE DB, a COM object that is stored in a column. In OLE, a COM object. Optimistic concurrency A strategy to increase concurrency in which rows are not locked. Instead, before they are updated or deleted, a rowset checks to see if they have been changed since they were last read. If so, the update or delete fails. See also pessimistic concurrency. Ordinary bookmark A bookmark whose value is defined by the provider. See also standard bookmark. Output parameter A parameter in a text command for which the provider returns a value to the consumer. P Parallel processing A method of processing that can run only on a computer that contains two or more processors running simultaneously. Parameter A variable in a text command. A parameter can be an input, input/output, or output parameter. Connecting To Sqlbase Page 117

118 Pending change A change that has been cached in a rowset and not yet transmitted to the data source. See also delayed update mode and immediate update mode. Persist To save the current state of a COM object, such as to a file. Currently, only data source objects can be persisted. Pessimistic concurrency A strategy for implementing serializability in which rows are locked so that other transactions cannot change them. See also optimistic concurrency. Phase A step in a sequence of notifications caused by a single event. The sequence of notifications is similar to the phases in a two-phase commit protocol. Precision The number of base 10 digits in a number. See also maximum precision. Prepare To compile a command. An execution plan is created by preparing a command. Preserved rowset A rowset in which all previously defined functionality is retained after a commit or abort. Primary key A column or columns that uniquely identifies a row in a table. Procedure A group of one or more precompiled commands (generally SQL statements) that are stored as a named object in a database. Property Attributes of an OLE DB object. For example, the maximum number of rows in a rowset that can be active at one time. Property group The set of all properties that apply to a particular OLE DB object. Property set A property is identified by a GUID and an integer (the property ID). A property set is the set of all properties that share the same GUID. Provider Software that implements OLE DB methods and interfaces. Q Query A text command. Sometimes used to mean a text command that creates a rowset. R Reason The specific event that occurred, such as changing a row value or deleting a row. Record See row. Reference counting Keeping a count of each interface pointer held on an object to ensure that the object is not destroyed before all references to it are released. In OLE DB, rows and accessors are also reference counted. Reference accessor An accessor that enables a consumer to get rowset data directly from the provider's buffer. Support for reference accessors is optional. Release To decrease the reference count on a row, accessor, or COM object. When the reference count reaches zero, the provider generally releases the resources used by the row, accessor, or COM object. Result A row count or rowset created by executing a command. See also multiple results object. Connecting To Sqlbase Page 118

119 Resynchronize To update the data in a rowset with the data in the data source that is visible to the current transaction according to its isolation level. Return code The value returned by an OLE DB method. Root enumerator An enumerator shipped in the OLE DB SDK that enumerates the data sources and enumerators listed in the registry. See also enumerator. Row A set of related columns that describe a specific entity. Also known as a record. Row handle A handle used to identify a row. Rowset An OLE DB object that contains a set of rows, each of which has columns of data. S Scale The number of digits in a number that are to the right of the decimal point. Schema A database object that contains one or more tables, often created by a single user. Schema rowset A predefined rowset that provides information about the structure of a database. Self bookmark A bookmark, stored in column 0 of a row, that is used to return to that row. Serializability Whether two transactions executing simultaneously produce a result that is the same as the serial (or sequential) execution of those transactions. Serializable transactions are required to maintain database integrity. Service component A provider that does not directly expose data, but instead provides a service, such as query processing. Used in conjunction with data providers. Session An OLE DB object that serves as the context for a transaction. Setting data Transferring data from the consumer to the provider, as in setting column or input parameter data. SQL Structured Query Language. A language used by relational databases to query, update, and manage data. Text commands often use SQL. Standard bookmark A bookmark whose value is defined by OLE DB. See also ordinary bookmark. Static error An error (text) that is stored by a specific provider lookup service, and most commomly tied to a single data store. Status The status of a data value. See also data part, value, and length. Storage interface An interface used to access data in a storage object: ISequentialStream, IStream, IStorage, or ILockBytes. Storage object A COM object that implements a storage interface. Storage objects are used to access BLOB data and OLE objects stored in a column. Success A condition in which no errors occurred. Success code A class of return code, of the type HRESULT, that begins with S_ or DB_S_ and indicates success of the method. Connecting To Sqlbase Page 119

120 T Table A collection of rows in the data source. Text command A text string, usually an SQL statement, that defines a command. Transaction An atomic unit of work. The work in a transaction must be completed as a whole; if any part of the transaction fails, the entire transaction fails. Transaction isolation The act of isolating one transaction from the effects of all other transactions. Transaction isolation level A measure of how well a transaction is isolated. Transaction object An OLE DB object used to support transactions. Transaction options object An OLE DB object used to define various options for a transaction. Transfer To move data between the consumer's and provider's buffers. The provider, not the consumer, transfers data. See also getting data and setting data. Transmit To send changes made through IRowsetChange to the data source. See also delayed update mode and immediate update mode. Transmitted change A change that has been sent to the data source. See also pending change. Truncate To discard one or more bytes of variable-length data or non-significant digits of numeric data. Truncation results in a warning condition when getting data and an error condition when setting data. Type indicator An integer value passed to or returned from an OLE DB method to indicate the data type of a consumer variable, a parameter, or a column. U Uninitialize To change the state of an enumerator or data source object so it cannot be used to access data. For example, uninitializing a data source object might require the provider to close a data file or disconnect from a database. Unprepare To discard the current execution plan. Update To change an existing row of data in the data source. Also, to transmit pending changes to the data source. User The end user, which is a generally a person, as opposed to the consumer, which is a piece of software. V Value A data value. See also data part, length, and status. Variable-length data type A data type for which the length of the data can vary, such as a string. See also fixed-length data type. Visibility Whether data values can be detected by a rowset. Refers both to the visibility of data in a data source and data cached in a rowset. W Connecting To Sqlbase Page 120

121 Warning A condition in which a nonfatal error occurred. Warning code A class of return code, of the type HRESULT, that begins with S_ or DB_S_ and indicates success of the method but with a warning. Z Connecting To Sqlbase Page 121

122 Zombie A state in which the only valid consumer action on a COM object is generally to release that object Connecting To Sqlbase Page 122

123 Connecting To Sqlbase Page 123