You are on page 1of 132



Guide to Connecting to SQLBase

GUPTA, SQLBase, SQLRouter, Team Developer, and SQLTalk are trademarks of Gupta Technologies, LLC registered in the United States and/or other countries. SQLWindows is a registered trademark of Microsoft Corporation, and is used under license to Gupta Technologies, LLC. Centura and Centura Software are registered trademarks of Centura Software Corporation, and are used under license to Gupta Technologies, LLC. 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, LLC. 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. Netscape FastTrack and Navigator are trademarks of Netscape Communications Corporation. All other product or service names mentioned herein are trademarks or registered trademarks of their respective owners.

Copyright © 2005 by Gupta Technologies LLC. All rights reserved. 20-6245-0001 April 2005

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
Audience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10 Notation conventions . . . . . . . . . . . . . . . . . . . . . 1-10 Other helpful resources . . . . . . . . . . . . . . . . . . . 1-11 Send comments to.... . . . . . . . . . . . . . . . . . . . . . 1-11

1 Introduction to SQLBase Connectivity. 1-1
Gupta client and server technology. . . . . . . . . . . . . . . 1-1 SQL.INI and the Connectivity Administrator . . . . . . . . 1-2 Running Connectivity Administrator . . . . . . . . . . . 1-2 SQL.INI server-side example . . . . . . . . . . . . . . . . 1-9 SQL.INI client-side example . . . . . . . . . . . . . . . . 1-11 SQLBase native connectivity . . . . . . . . . . . . . . . . . . 1-11 General features of SQLBase . . . . . . . . . . . . . . . . . . 1-12 DML and DDL . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12 Making a connection. . . . . . . . . . . . . . . . . . . . . . 1-12 Bind variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12 Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12 Isolation levels . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13 Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14 Long character and long binary data handling . . 1-15 Stored procedures and triggers . . . . . . . . . . . . . 1-15


. . 2-5 Deprecated functions . . . . . . . . 3-3 4 Introducing SQLBase OLE DB Data Provider4-4 . . . . . . . . . . . . . . . . . . . . . . . 3-2 Linux connections . . . . . . . . . . . . . . . . . 2-12 How do I read and write long character and long binary data? 2-12 How do I run stored procedures? . . . . . . . . . . . . 3-1 Connection string keywords . . . . . . . . . 2-1 How does it work?. . . . 2-8 Configuring Data Sources in Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3 PHP example . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9 How-to information for ODBC . 2-12 How do I set isolation levels? . . . . . . . . . 2-6 Configuring Data Sources in Windows . . . . . . . . . . . . 2-3 System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 About the SQLBase ODBC driver for Linux . . . . . . . . . . . . . . . . . . . . . . .2 ODBC Driver Introduction . . . . . . . . . 2-7 Data Source Properties dialog . . . . . . . . . . . 2-9 Driver manager configuration files . 2-11 How do SQLBase datatypes map to ODBC datatypes?2-11 How do I start a transaction? . . . . . . . . . . . . . 2-2 About the SQLBase ODBC driver for Windows . . . . . . . 3-1 Connection strings . . . . 2-3 System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14 3 Making an ODBC Connection . . . . . . . . . . . . 2-2 ODBC overview. . . . . . . . . . . . . . . . . . . . 2-3 Supported Features . . . . 3-1 Logon dialog . . . . . . . . . . . . . . . . . . . . . 2-4 Supported ODBC Functions . . . . . . . . . . . . . . 2-4 Number of Connections and Statements Supported2-4 Isolation and Lock Levels Supported . . . . . . 2-9 Changing configuration information . . . . . . . . . . . . . . . . . . . . . . . . 2-4 ODBC Conformance Level . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 SQLBase OLE DB Data Provider name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6 ADO features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5 How do I use long character data and long binary data?4-5 ADO Overview . . . . . .1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9 SQLBase provider-specific dynamic properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4 Data source name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1 Supported COM objects . . . . . . . . . . . . . . . . . . . . 4-10 Sample applications . . . . . . . 5-2 Data Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10 Connecting to data through the Provider . . . . . . . . . 5-5 Command . . . . . . . . . . 4-6 Remote Data Service . . . . . . . . . 4-7 Programming with ADO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4 How do I set isolation levels? . . . . . 4-2 About SQLBase OLE DB Data Provider . . . . . . . . . . . . . . . . . . 4-4 How do SQLBase datatypes map to OLE DB datatypes?4-4 How do I start a transaction? . . 4-12 5 Supported OLE DB COM Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11 Coding Sample using ADO. . . . 4-9 Working with Data. . . . . . 4-11 Establishing a connection using ADO . . . . . . . . 4-4 How-to information for the OLE DB provider. . . . . . . . . . . . . . . 5-3 Session . . . . . . 4-2 Recommended reading . . . . . . . . . . . . . . . . 4-8 ADO Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8 Dynamic Properties Collections . . 4-2 OLE DB components . . . . . . . . . . . . . . . . . 4-4 Supported programming tools . . . . . . . . . . . . . 4-7 Threading . . 5-6 -5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5 SQLBaseConnection object . . . . . . . . . . . . . . 7-8 SQLBaseCommand properties. 7-2 How do SQLBase datatypes map to CLR datatypes?7-2 How do I start a transaction? . . . . . . . . . . . .NET Data Provider. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .NET implementation . 7-10 SQLBaseDataReader methods .. . . . . . . . . . . . . . . . . . . 7-9 SQLBaseCommand methods . . . . . . . 7-10 Get methods for long (BLOB) data . . . . . . . . . . 6-2 ADO mapping to Gupta interfaces . . . . . . . . . . .Rowset . . . . . . . 6-3 Error object mapping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4 Field object mapping . . . . . . 7-10 Get. . . . . . . . . . 7-9 SQLBaseDataReader object. . . . . 7-11 GetFieldType . . . . . . . . 7-1 SQLBase . . .. . 7-1 How-to information for the . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6 Recordset object mapping . 7-6 SQLBaseConnection methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . methods . . . . . . . . . . . . . 5-9 6 ADO Mapping to Gupta . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7 7 . . 7-11 -6 . . . . . . . . . . . . .NET requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6 SQLBaseConnection properties . . . . . . . . . . . . . . . . . . 7-6 SQLBaseCommand object . 7-11 GetDataTypeName. . . . . . . . . . . . . . . . . . 6-1 Isolation level mapping . . . . . . . . . . . . . 7-1 SQLBase . 5-8 Error . . . .NET data provider . . . . 6-3 Connection object mapping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2 Command object mapping . . . . . . 6-5 Parameter object mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3 How do I set isolation levels? . . . 7-3 How do I use long character data and long binary data?7-3 How do I run stored procedures? . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3 DDL Operations Support . . . . . . . . . . 8-1 JDK Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3 Multiple Connection Support. . . . . . . . . . . . . . . . . . . . . . 8-2 CLASSPATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12 GetValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3 Transaction Model . . . . . . . . . 7-12 NextResult . . . . . . . . . . . . . 7-15 Add . . . . . . . . . . . . . . . . . . . 8-3 Multi-threading Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12 GetOrdinal . . . . . . . . . . . . . . . 8-2 Getting Started . . . . . 7-16 SQLBaseException Properties . . . . . . . . . . 8-2 Tested Platforms. . . . . . . . . . . . . . . . . . . . 7-14 SQLBaseParameters object . . . . 8-3 SQLBase Support for JDBC . . . . . . . . . . . . . . . 8-1 Introduction . . . . . . . . . . . . . 7-16 8 Introduction to the JDBC driver . . . . . . . . . . . . 7-12 SQLBaseDataAdapter object . . . . . . . . . . . 7-13 SQLBaseDataAdapterProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2 Server Configuration. . . . . . . . . . 7-13 SQLBaseTransaction object . . . . . . . . . . . . . . . . . . 7-14 SQLBaseParameter object . . . . . . . . . . 8-3 DML Operations Support . 7-12 IsDbNull . . . . . . . . . . . . . . . 8-4 -7 . . . . . . . . . . . . .GetName . . . . . . . . . . . . . . . . . . . . . . . 7-15 SQLBaseException object . . . . . . . . . . . . . . . . . . 8-2 Installation . . . . . . . . . . . . . . 7-14 SQLBaseTransaction Properties . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14 SQLBaseTransaction methods. . . . . . . . . . 8-3 SQL Operations Support . . . 7-16 SQLBase classes and transaction state . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . 8-6 URL formats . . . .How-to information for the JDBC driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Index-1 -8 . . Glossary-1 Index . . . . . . . . . . 8-6 SQLBase Supported Data Types:. . . . . . . . . . . . 8-11 Named Cursor Support . . . . . . . . . . . . . 8-5 How do I use long character data and long binary data?8-5 How do I run stored procedures? . . . . . . . . . . . . . . . . . . . . . . . 8-13 Restrictions . . . . . . . 8-5 How do I set isolation levels? . . . . . . . . . . . . . . . . . . . . . . . . . 8-11 Stored procedure example . . . . . . . . . . . . . . . . . . . 8-13 Error Message Support . . . . . . . 8-11 Stored procedure support . . . . . . . . . 8-13 Application and Applet Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8 For READING Operations using ResultSet: . . 8-9 Bind variable support . . 8-6 Data types and conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4 How do SQLBase datatypes map to JDBC datatypes?8-4 How do I start a transaction? . . . 8-8 Datatypes example . . . . . . . . . . . 8-14 Glossary . . 8-6 URL keywords: . . . . . . . . . . . . . . .

The documentation format. The organization of this manual. This preface provides the following information: • • • • • Who should read this manual. Java. such as Microsoft Visual Basic.Guide to Connecting to SQLBase Preface This manual provides reference information about using database drivers and data providers to access SQLBase from programming tools. and Delphi. C++. Guide to Connecting to SQLBase -9 . Related publications. The notation conventions used in this manual.

Keyboard keys that you press. it is important to understand the typographical conventions we use in this manual: Formatting Convention You User bold type Courier 9 SQL. Things that you select. relational databases in general. and field names. C++. and Delphi.Preface Audience This manual is intended for Application Developers building client applications that access Gupta SQLBase using frontend products such as Visual Basic.EXE Precaution Vital information Supplemental information Alt+1 Warning: Important: Note: A plus sign between key names means to press and hold down the first key while you press the second key Type of Information A developer who reads this manual The end-user of applications that you write Menu items.INI MAPDLL. Development language code example Program names and file names -10 Guide to Connecting to SQLBase . and SQL. Notation conventions Before you start using this manual. This manual assumes you have a working knowledge of SQLBase. push buttons.

If you have any comments or suggestions regarding this manul. products. The technical services section of our Web site is a valuable resource for customers with technical support issues. Gupta Technologies LLC’s world wide Web site contains information about Gupta Technologies LLC’s partners. with comments or suggestions to: techpubs@guptaworldwide. access to Gupta’s online newsgroups. class schedules. Send comments to. including technical support case status. please send them to: Technical Publications Department Gupta Technologies 975 Island Drive Redwood Shores. or print any chapter. and addresses a variety of topics and services. This document collection lets you perform full-text indexed searches across the entire document suite. including course descriptions.. support. Open the collection by selecting the Gupta Books Online icon from the Start menu or by double-clicking on the launcher icon in the program group. white papers. navigate the table of contents using the expandable/collapsible browser. and users. product bulletins.. links to shareware tools. The Gupta document suite is available online. World Wide Web. commonly asked questions. CA 94065 or send email. sales. The URL is http://www. Our Web site also includes information on training.Other helpful resources Gupta Books Online. and certified training Guide to Connecting to SQLBase -11 . and downloadable product updates.


Gupta publishes SQLBase.Connecting to SQLBase Chapter 1 Introduction to SQLBase Connectivity Gupta client and server technology Connectivity has two faces at Gupta Technologies. even those that do not use Gupta client tools. written with any programming tool. and testing. Client computers. Since you are likely to use Gupta’s tools for these purposes. • Connecting to SQLBase 1-1 .INI file on their machines. the book you are reading now will discuss how to connect any client application. to Gupta SQLBase. for two reasons: • You need client tools for DBA tasks like configuration. for purposes of specifying basic server. still need at least a rudimentary client-side SQL. a set of tools for creating powerful client applications that connect to SQLBase and to many other data sources as well. In contrast. And we also publish Team Developer. Connecting Gupta Objects to Databases. backup. database and protocol information. you will still need to have some knowledge of client connectivity. The details of client connectivity for applications written with Team Developer to any data source are documented in another Gupta book. the relational database server discussed in this book. But the database administrator still needs to be concerned with client connectivity.

uncontrolled manual changes can accidentally introduce problems.INI can be modified with a text editor such as Notepad. The Connectivity tab works on client-side settings to add or remove. Even in cases where SQL. the main window can show two tabs. we discuss only basic SQL. Experienced users may wish to change SQL.INI. The remaining chapters in this book will discuss how to configure SQLBase drivers and data providers. also new in version 8.INI until new servers or new databases are added to the installation. you can: • • 1-2 Set up the options for a SQLBase server Enable and disable communication protocols Connecting to SQLBase .INI is created during the install process and is tailored to your answers to the install questions. enable or disable routers and protocols.INI before they are accessible to client applications.INI file is functional immediately and. and that is the name we use to refer to the configuration file in Gupta documentation. it is still indirectly involved since individual databases must be registered in SQL. SQL. Running Connectivity Administrator Connectivity Administrator is one of the options in the Gupta program group. Depending on what you have installed. In some cases such configuration involves changes to SQL.5. it is found in the same directory as the SQLBase executables. In this book. Although SQL. When configuring connectivity for a SQLBase server. Gupta recommends that when possible you use the Connectivity Administrator instead to make changes. By default. this file was always named SQL.INI.INI is not directly involved.INI concepts. In versions of SQLBase prior to 8. Choose the Server tab to add or remove databases and enable or disable protocols. and choices for its location were limited. although the default name is still SQL. for many users.Chapter 1 Introduction to SQLBase Connectivity SQL. such as the OLE DB data provider.INI settings to achieve specific performance and communication goals. such as being unable to use a specific protocol against SQLBase or being unable to access a particular database. it is unnecessary to ever change SQL. This default SQL. The Database Administrator’s Guide contains much more detailed information about every concept that is briefly discussed in this chapter.5.INI. For new SQLBase installations. In version 8.INI and the Connectivity Administrator Both Gupta’s client tools and their server tools use a configuration file to store connectivity information.5 the file name and location are now under your control. The ability to have any name and location for the configuration file is a feature that supports multiple concurent SQLBase installations on a single computer.

disable. and configure data sources other than SQLBase. you can: • • • • • • • Edit the name. encryption level. such as the TCP/IP listen port.INI and the Connectivity Administrator • • • • • 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. Enable and disable listening protocols. Enable. or remove server names from a listening protocol. Edit the properties of some listening protocols (TCP/IP and local connection) Associate new server names with a specific listening protocol.SQL.) Connecting to SQLBase 1-3 . and runtime directory of the client itself. or access all databases. see Connecting Gupta Objects to Databases. Limit access to specific databases on a server. Change properties of a server/protocol combination. (That topic is related to Gupta Team Developer and is outside the scope of this book.

by directly typing the name or by clicking the Browse pushbutton.Chapter 1 Introduction to SQLBase Connectivity The illustration below shows how the Client tab allows you to change the name and location of the configuration file you wish to edit.. 1-4 Connecting to SQLBase .

Connecting to SQLBase 1-5 . double-click to change properties. you left-click to select an item. or right-click to display a menu of connectivity functions.INI and the Connectivity Administrator On both tabs.SQL.

The name you use in SQL. you can work with the Server Configuration dialog box.Chapter 1 Introduction to SQLBase Connectivity If you double-click on the server node (“server1” above). which has three tabs: The Basic tab controls the server name.INI files on client computers must match the name found here. 1-6 Connecting to SQLBase . or right-click on it and choose Properties.

Connecting to SQLBase 1-7 .INI and the Connectivity Administrator The Optional tab allows you to configure other commonly-changed and critical settings.SQL.

presuming that you know the value that should be associated with the keyword. 1-8 Connecting to SQLBase .Chapter 1 Introduction to SQLBase Connectivity The Advanced tab allows you to change any server keyword. Detailed information about values and keywords is available in Chapter 3 of the Database Administrator’s Guide.

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

it is assigned the same listening protocols as the server itself.Chapter 1 Introduction to SQLBase Connectivity “ISLAND” is the demonstration/tutorial database installed with SQLBase. Note that it implements both of the listening protocols used by the server itself. Each database in a server must have a “dbname” line within the server section of SQL. You can override this. By default. SQLMPIPE.dll] comdll=sqlmpipe comdll=sqlws32 Section “dbntsrv. you must insure that any SQL. but if you do.INI with optional extra information. 1-10 Connecting to SQLBase . but you can change the path to point elsewhere.INI files on client machines are altered to match the new port number.sqlmpipe. Note that in this example it implements only the TCP/IP listenting protocol. SQLBrm. 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.INI files on client machines are altered to match the new port number. dbname=PURPLE.the port number is a runtime parameter that you supply to the SQLBase Resource Manager. 2155.sqlws32 Database “PURPLE” was added using Connectivity Administrator. each in its own subdirectory with the same name as the database itself.ws32] listenport=2155 Each listening protocol has a separate section in SQL. For more information. but if you do.INI. This is not subject to overriding in SQL. The TCP/IP listener has a default port.dll” determines which listening protocols will be loaded when the SQLBase server starts.INI . By default. dbname=SQLCON. [dbntsrv. not the MTS protocol. these subdirectories are presumed to be located under the SQLBase program directory. [dbntsrv.sqlws32 Database “SQLCON” is used for the SQLConsole DBA utility. is 2156. You can override this. see the SQLBase release notes.exe. Note: The default port for the MTS (COM+) listening protocol. you must insure that any SQL.

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

meaning that multiple database cursors might be assigned to a single database connection. see the SQL Command Reference chapter in the SQL Language Reference. unless your application takes specific steps to prevent this.. The number or string corresponds to a variable in the client application running the query. Also. doing a COMMIT on one cursor will usually cause a COMMIT to occur for all other cursors sharing that connection. you can make "implicit" connections. Datatypes Here are the native datatypes supported by SQLBase: Type Length 1 to 254 bytes CHAR (or VARCHAR) String 1-12 Connecting to SQLBase . Bind variables SQLBase supports bind variables. In this chapter. For a summarized list of commands. refer to the SQL Language Reference book: DML and DDL SQLBase supports all commonly used Data Manipulation Language commands and Data Definition Language commands.Chapter 1 Introduction to SQLBase Connectivity 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. there are slight differences in the feature set available to some drivers and data providers. However. changing the isolation level of a connection forces a COMMIT. the general features of SQLBase are described. For more detailed information. Those differences will be noted individually in the chapters that describe the drivers and data providers. However. If you are interested in the most detailed information. see the chapter Using the SQL/API in the SQL Application Programming Interface Guide. 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. Making a connection In the SQLBase native API. This means that transactions performed against one connection will have no effect upon the transaction status of other connections. With implicit connections. all SQLBase drivers and data providers use "explicit" connections.

up to 22 digits. but only the date portion of the value is returned Like DATETIME. 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 Connecting to SQLBase 1-13 . range -2147483648 to +2147483647 Up to 5 digits of precision. including scale digits Up to 10 digits of precision. Up to 22 digits of precision. There are significant differences between these datatypes and the sets of datatypes used in drivers and providers. Like DATETIME. range -32768 to 32767 Double-precision floating point numbers. The individual chapters following this one will detail the differences. but only the time portion of the value is returned SMALLINT DOUBLE PRECISION FLOAT REAL DATETIME (or TIMESTAMP) DATE Number Number Number Number Date/time Date/time TIME Date/time Detailed descriptions of these datatypes are available in the SQL Elements chapter of the SQL.Language Reference.General features of SQLBase Type Length 255 bytes to 2 gigabytes LONG (or LONG VARCHAR) NUMBER DECIMAL (or DEC) INTEGER (or INT) String (can be used for binary data too) Number Number Number Up to 22 digits Up to 15 digits. including scale digits Single-precision floating point numbers. up to 21 digits Number representing both a date value and time value.

the shared lock is dropped. read the Distiibuted Transactions chapter in the Database Administrator Guide. All shared locks and all exclusive locks are retained on a page until the transaction completes. By the time control returns to the application.) There are differences in how isolation levels are mapped between SQLBase and the various drivers and providers . when a reader moves off a database page. Other users will not be able to update any pages that have been read by the transaction. However. Rows referenced by the program cannot be changed by other programs until the program reaches a commit point. Read Only (RO)—The isolation level where pages are not locked. the SAVEPOINT command can be used within scripts and procedures to create intermediate rollback points within a transaction. RR is the SQLBase default isolation level. A shared lock is dropped as the cursor leaves the page. SQLBase also provides the ability to do transactions that involve multiple database servers performing various parts of the transaction. and no user has to wait. if a row from the page is still in the message buffer. Transactions SQLBase provides commands COMMIT and ROLLBACK to control transactions. but lowers concurrency. This isolation level provides higher concurrency than Read Repeatability. Subsequent queries return a consistent set of results (as though changes to the data were suspended until all the queries finished). This gives the user a snapshot view of the database at the instant that the transaction began. the page is still locked. 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). Read repeatability provides maximum protection from other active application programs. For more information about this. the Release Lock (RL) isolation level increases concurrency. all shared locks have been released. but an exclusive lock (the type of lock used for an update) is retained until the transaction completes. Distributed transactions In addition to a transaction that is handled on a single database server. it is guaranteed that those rows would not have changed. Data cannot be updated while in the read-only isolation level.Chapter 1 Introduction to SQLBase Connectivity time it is read and the time it is altered. In contrast.please read the relevant chapters. In addition. 1-14 Connecting to SQLBase . This ensures a high level of consistency. but consistency is lower. Release Locks (RL)—With the Cursor Stability isolation level. Read Repeatability (RR)—The isolation level where if data is read again during a transaction.

For detailed information and examples of stored procedures and triggers. However. read the chapter Procedures and Triggers in the SQL Language Reference.General features of SQLBase COM+ transactions in Windows SQLBase for Windows includes SQLBase Resource Manager. so you can treate a LONG VARCHAR column just like any other datatype in your SQL commands. There is no output-only parameter type. In Gupta Team Developer. This language is also used in triggers. a component that makes it possible to coordinate database transactions inside a larger COM+ transaction. or in applications that use the SQBase native API. For more information. read the Communication chapter of the Database Administrator Guide. Stored procedures and triggers SQLBase supports stored procedures. all of the SQLBase drivers and data providers hide this complexity. which is the same language used in the SQLWindows tool that is part of Gupta Team Developer. Parameters can be either input-only or input-output. The procedural language is SAL (SQLWindows Application Language). Parameters are allowed with stored procedures. Connecting to SQLBase 1-15 . Long character and long binary data handling The LONG (or LONG VARCHAR) datatype accepts both character and binary data. there are some extra steps required to make use of this datatype.

Chapter 1 Introduction to SQLBase Connectivity 1-16 Connecting to SQLBase .

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

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

DLL.DLL. One of the supported operating systems: Microsoft Windows 98.0. For such applications.0.0. use the native SQLBase routers instead. To communicate with the server. the SQLBase driver requires SQLWNTM. SQLBAPW. SUSE 9.0. and a communication DLL (for example. or Server 2003. Client applications written with a Gupta programming tool. About the SQLBase ODBC driver for Windows The SQLBase ODBC driver supports the Gupta SQLBase database system in the following operating systems: Windows 98.0. NT. SUSE Enterprise Server 8. SUSE Desktop requires: Connecting to SQLBase 2-3 . System requirements The Gupta SQLBase ODBC driver (SQLBaseODBC. This is included with the Gupta SQLBase ODBC driver. The driver file name is libsqlbaseodbc. ME. XP. SQLWS32. and XP. The information in this chapter is also available in an online help file that is accessible during ODBC data source configuration. Red Hat Advanced Server 3. The directory containing these files must be on your path. cannot use ODBC to connect to SQLBase.dll.5 Driver Manager.dll) requires: • • • SQLBase version 9.0 or higher. 2000 .dll. 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. The driver file name is sqlbaseodbc. Server 2003. Driver and data source configuration are done through sqlbaseodbcsetup. The Microsoft 3. NT. System requirements The Gupta SQLBase ODBC driver ( for TCP/ IP). such as SQLWindows. ME. Driver and data source configuration are done through text editing of configuration files.About the SQLBase ODBC driver for Windows 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). 2000.

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

Supported Features SQL_TXN_READ_COMMITTED (maps to SQLBase level RL)and SQL_TXN_READ_UNCOMMITTED (maps to SQLBase level RL). 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 2-5 . SQLBase supports page-level locking.

but they are implemented by the ODBC Driver Manager and not by the driver. Deprecated function SQLAllocConnect SQLAllocEnv SQLAllocStmt SQLBindParam SQLError SQLExtendedFetch SQLFreeConnect Mapped to SQLAllocHandle SQLAllocHandle SQLAllocHandle SQLBindParameter SQLGetDiagRec SQLFetchScroll SQLFreeHandle 2-6 Connecting to SQLBase . Deprecated functions Below is an alphabetic list of deprecated ODBC API functions. Note that these functions can still be used by an ODBC application. ** 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. The driver manager maps these deprecated functions into other functions that are actually implemented by the driver. Will return standard ODBC error to indicate that it is not implemented.Chapter 2 ODBC Driver Introduction 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.

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

Data Source Name: A string that identifies this SQLBase data source configuration in the system information. Choices are Release Locks. read the SQLBase Language Reference manual. For example. or Cursor Stability. Read Only.Chapter 2 ODBC Driver Introduction offers performance advantages. 2-8 Connecting to SQLBase . . For detailed information about how these levels work. Data Source Properties dialog Use the ODBC SQLBase Data Source Configuration dialog box to create new SQLBase data sources or configure existing data sources." Database Name: The name of the database to which you want to connect by default." Description: An optional long description of a data source name. Examples include "Accounting" or "SQLBase-Serv1. specifically the SET ISOLATION command. Read Repeatability. and is particularly helpful when your data source is participating in a distributed transaction. "My Accounting Database" or "SQLBase on Server number 1. Isolation Level: The method of locking to use for this connection.

In the case of unixODBC it is possible to use a utlility. Shown below is an example data source.odbc. path) of the configuration file that contains information about SQLBase servers and databases. you would still use a text editor to enter the lines that are shown in the examples below into a template file. the default is 300. see Nick Gorham’s explanation of odbcinst.A system-wide default Changing configuration information Configuration changes are done by using a text editor on the configuration files. These files are named odbc.Located in home-directory ($HOME). Lock Timeout: The number of seconds SQLBase should wait for a lock to be freed before raising an error. the configuration file is searched for using the algorithm described in chapter 3 of the SQLBase Database Administrator’s Guide. However.ini as follows: 1. This name can be left blank. ~/. use configuration files to get data source information.ini . Values can be -1 (wait forever) to 1800. For more detail about using odbcinst instead of editing the configuration files manually. see the unixODBC web site.Environment variable. to make changes to the configuration files. Entries in the odbcinst. Increasing this value retrieves more records across the network in a single fetch. 3. iODBC searches for odbc. Config Filename (INI): The name (and. unixODBC To learn how unixODBC searches for its configuration files.ini. For example. if it exists – for user DSN /etc/odbc. such as iODBC and unixODBC. if set. Driver managers can also search for configuration files. odbcinst. They are most commonly found in the /etc directory. $ODBCINI . then use odbcinst to actually copy those lines from the template file into the configuration files. if so. The default is determined by SQLBase.ini and odbcinst. "Gupta1". Configuring Data Sources in Linux Driver manager configuration files Popular ODBC driver managers for Linux.Configuring Data Sources in Linux Input Message Size: The number of bytes in the input message buffer. as it would be configured for different driver managers.ini file: Connecting to SQLBase 2-9 . 2.ini . optionally.

so And here is the odbc.ini InputMessageSize=2000 IsoLevel=Release Locks LockTimeOut=300 iODBC The configuration entries for iODBC are Description=Gupta SQLBase DSN DSN=gupta1 Servername=server1 LoginID=SYSADM Username=SYSADM Password=SYSADM Database=island ini=/opt/Gupta/SQLBase90/ Setup = /opt/Gupta/SQLBase90/libsqlbaseodbcsetup. .-----.ini file: .ini file: [gupta1] Driver=/opt/Gupta/SQLBase90/libsqlbaseodbc.ini file begin ----.ini . . odbc. [ODBC Data Sources] Gupta1=Gupta SQLBase ODBC Driver [Gupta1] Description=Gupta SQLBase DSN Driver=/opt/Gupta/SQLBase90/libsqlbaseodbc.Chapter 2 ODBC Driver Introduction [Gupta SQLBase] Driver = /opt/Gupta/SQLBase90/libsqlbaseodbc.ini file begin ----.ini . Here is the odbcinst./etc/odbcinst.-----. odbcinst. but not identical.ini file: .so DSN=gupta1 2-10 Connecting to SQLBase . to Setup = /opt/Gupta/SQLBase90/ Here are the corresponding entries in the odbc./etc/odbc. [ODBC Drivers] Gupta SQLBase = Installed [Gupta SQLBase] Driver = /opt/Gupta/SQLBase90/libsqlbaseodbc.

/etc/odbc.How-to information for ODBC 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/ .-----.ini file end ----- 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 Varchar Number Real Smallint Time Timestamp Varchar SQL_VARCHAR SQL_TYPE_DATE SQL_DECIMAL SQL_DOUBLE SQL_INTEGER SQL_LONGVARCHAR SQL_DOUBLE SQL_REAL SQL_SMALLINT SQL_TYPE_TIME SQL_TYPE_TIMESTAMP SQL_VARCHAR ODBC Connecting to SQLBase 2-11 .

"CREATE TABLE TBLOB (I INTEGER NOT NULL . &l. rc = SQLTransact(henv. your application begins an implicit transaction. For information about changing connection pooling from within an application. SQL_NTS). SQL_AUTOCOMMIT. use the connection property SQL_TXN_ISOLATION. How do I set isolation levels? To set isolation level. 2-12 Connecting to SQLBase . rc = SQLTransact(henv. see Configuring Data Sources in Windows on page 2-7.. For more information about configuring connection pooling. SQL_C_LONG. "INSERT INTO TBLOB VALUES (?. assert(rc == SQL_SUCCESS). B LONG )". then read back from the database. You can end the transaction with either a rollback or commit flag. which can contain either long character or long binary information. assert(rc == SQL_SUCCESS). SQL_COMMIT). hdbc. Set it to one of the supported levels. rc = SQLPrepare(hstmt. NULL).Chapter 2 ODBC Driver Introduction How do I start a transaction? By turning off autocommit. "DROP TABLE TBLOB". SQL_AUTOCOMMIT_OFF). rc = SQLExecDirect(hstmt. hdbc. In this fragment of C code. assert(rc == SQL_SUCCESS). SQLEndTran(henv. SQLSetConnectAttr(hdbc. SQL_INTEGER. hdbc. SQL_NTS). Distributed transactions benefit from connection pooling. 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. assert(rc == SQL_SUCCESS). search the Microsoft KnowledgeBase using connection pooling to find information on code samples. a large text string is first written to the database. SQL_NTS). rc = SQLExecDirect(hstmt. 1. cbValue = 0. 0. rc = SQLSetParam(hstmt. ?)". 0. SQL_COMMIT). SQL_COMMIT).

} else { error_line(__LINE__). blobbuf. hdbc. j += (ULONG)s. j < blob_size. s = (SDWORD)blobbuf_size. ~0. assert(rc==SQL_SUCCESS). assert(rc == SQL_SUCCESS). memset(blobbuf. l = 2. memset(blobbuf. rc = SQLGetData(hstmt. assert(s + j != blob_size). blobbuf_size). 'A'. 100). &cbValue). &token). } rc = SQLParamData(hstmt. blobbuf = malloc(blobbuf_size). B FROM TBLOB WHERE I = 2". rc = SQLFreeStmt(hstmt. SQL_COMMIT). NULL. &cbValue).How-to information for ODBC rc = SQLSetParam(hstmt. assert(rc == SQL_SUCCESS). SQL_NTS). 0. SQL_C_LONG. &token). if (rc == SQL_NEED_DATA) { for (j = 0. assert(rc == SQL_SUCCESS). Connecting to SQLBase 2-13 . rc = SQLParamData(hstmt. assert(rc == SQL_NEED_DATA). blob_size.blob_size. SQL_C_CHAR. } rc = SQLPutData(hstmt. assert(rc == SQL_SUCCESS). if (s + j > blob_size) { s -= (s + j) . assert(rc == SQL_SUCCESS). } rc = SQLTransact(henv. 0L. s). 2. rc = SQLPrepare(hstmt. ) { SDWORD s. assert(rc == SQL_SUCCESS). rc = SQLFetch(hstmt). cbValue = SQL_DATA_AT_EXEC. SQL_RESET_PARAMS). "SELECT I. rc = SQLExecute(hstmt). rc = SQLExecute(hstmt). &l. SQL_LONGVARCHAR. assert(rc == SQL_SUCCESS). 1.

as in this C example: sql= "{call maketables}". &hIpd. SQL_NTS). 30. &cbValue). SQL_DESC_NAME. do { rc = SQLGetData(hstmt. rc = SQLExecDirect(hstmt.SQL_NTS). 0. "quote". } while (rc == SQL_SUCCESS_WITH_INFO). assert(rc == SQL_SUCCESS). szQuote. SQL_CHAR. assert(cbValue > 0). CHECK(rc. 0. blobbuf_size. free(blobbuf). SQL_C_CHAR. } How do I run stored procedures? A stored procedure without parameters can be run like a regular SQL query. /* Populate record 1 of IPD */ SQLBindParameter(hstmt. 2. SQLSetDescField(hIpd. 2-14 Connecting to SQLBase .sql. blobbuf. as in this example of procedure "test" that was created with a string parameter named "quote": /* Prepare the procedure invocation statement */ SQLPrepare(hstmt. assert(rc == SQL_SUCCESS).Chapter 2 ODBC Driver Introduction assert(rc == SQL_SUCCESS). rc = SQLFreeStmt(hstmt. SQL_ATTR_IMP_PARAM_DESC. A stored procedure that uses parameters requires the use of binds. "{call test(?)}". &cbValue). assert(blob_read == blob_size). blob_read += (cbValue < blobbuf_size ? cbValue : blobbuf_size). SQL_CLOSE).hstmt). SQL_NTS). execute the statement */ SQLExecute(hstmt). SQL_PARAM_INPUT. /* Assuming that szQuote has been appropriately initialized. 1. blob_read = 0L. SQL_C_BINARY. 0. /* Get IPD handle and set the NAMED and UNNAMED fields for record # 1 */ SQLGetStmtAttr(hstmt. 1. 0).

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

and CS (Cursor Stability). it displays a dialog box. NoRecovery (NR): This keyword is accepted for backwards compatibility. If not. IsoLevel (IL): A string that specifies how SQLBase will handle locking for this connection. For detailed information about how these levels work. Possible values are RL (Release Locks). for example. This value is case-sensitive. the database server will return an error. LogonID (UID): The default Logon ID used to connect to your SQLBase system. but has no effect on the SQLBase server. A value of -1 is infinite wait. ServerName (SRVR): The name of the server that hosts the database to which you want to connect. specifically the SET ISOLATION command. contact your system administrator to get your Logon ID. In the Linux ODBC driver. read the SQLBase Language Reference manual. not in the Linux ODBC driver. Fill out the values in the dialog box as shown below: Note: The logon dialog is available only in the Windows ODBC driver. if the connection string contains insufficient information to make a connection. Logon dialog Your application might supply enough information in the connection string to make the connection without prompting you. 3-2 Connecting to SQLBase . Values can be -1 to 1800. Increasing this value retrieves more records across the network in a single fetch. RR (Read Repeatability). RO (Read-Only). Database (DB): The name of the database system to which you want to connect. Default is 300. A Logon ID is required only if security is enabled on your database system. when the SQLBase ODBC Driver needs additional information from you to make a connection. "Accounting". InputMessageSize (IMS): Controls the number of bytes of the input message buffer.Chapter 3 Making an ODBC Connection DataSourceName (DSN): A string that identifies a single connection to a SQLBase database system. Password (PWD): Case-sensitive password. If so. LockTimeOut (LTO): Number of seconds SQLBase waits for a lock to be freed before raising an error.

If required. your Linux ODBC configuration files must be complete and accurate before you attempt to log on. and either executes a query or lists tables present in that database. Type the name of the database you want to access. Several lines are necessary for each data source.). type your password. as it is configured in unixODBC on page 2-9 or iODBC on page 2-10. The following script effects a connection to a database (`Gupta1' is the default DSN). Click OK to complete the logon and to update the values in the system information.dtd"> Connecting to SQLBase 3-3 .w3. If required. 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. PHP example An example of how a PHP script might connect to the ’Gupta1’ data source from chapter 2 is shown below. you can select the name from the Database Name drop-down list box. Save this code to a file php-odbc-sample. type your user Optionally.Linux connections 1.php. 2. The data source that you wish to connect to must be present in these files (particularly odbc.ini. Type Local to access a local SQLBase database.0 Strict//EN" "http:/ /www. which displays the server names you specified in the Setup dialog box. Linux connections Since there is no logon dialog for Linux operating systems. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1. See the sample "Gupta1" data source. 3. If you specified a server name. 4.

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" ?>" /> <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" 3-4 Connecting to SQLBase . $uid=$_POST['uid']./.. $passwd=$_POST['passwd']. $DSN=$_POST['DSN'].see `register global # variables' and PHP security updates $query=$_POST['query']..Chapter 3 Making an ODBC Connection <html> <head> <title> Gupta test of ODBC access through PHP hosting</title> <link type="text/css" rel="STYLESHEET" media="ALL" href=". ?> <p>Enter the parameters for your query here:</p> <form action="php-odbc-sample. $exec=$_POST['exec']. $listtables=$_POST['listtables'].css" /> </head> <body> <h1>Testing ODBC connectivity from PHP hosted within Gupta</h1> <hr /> <?php # set global variables based on the form thing ./tutorial.

"border=2"). odbc_close($handle). } else { print "done</p> ". ". $handle=odbc_connect ("$DSN". } } if($listtables!=NULL) { print "<h2>List of tables</h2>". } else { $resultset=odbc_tables($handle). if(!$handle) { print "<p>Uh-oh! Failure to connect to DSN [$DSN]: <br />". print "done</p> ". odbc_errormsg(). odbc_result_all($resultset.. "$uid". "$passwd"). odbc_close($handle). ". "$query"). "border=2").Linux connections ?>" /> </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> ". odbc_result_all($resultset. if(!$handle) { print "<p>Uh-oh! Failure to connect to DSN [$DSN]: <br />". $handle=odbc_connect ("$DSN". print "<p>Connecting. print "<p>Connecting.. "$uid". $resultset=odbc_exec ($handle. Connecting to SQLBase 3-5 . odbc_errormsg().. "$passwd")..

Chapter 3 Making an ODBC Connection } } ?> </body> </html> 3-6 Connecting to SQLBase .

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

Since OLE DB comprises a set of Component Object Model (COM) interfaces. Using OLE DB. 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. Part of Microsoft’s Universal Data Access strategy. This task becomes more of a challenge given multiple platforms. Based on open industry specifications. allowing developers to directly interface with the database and server using a variety of 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. About SQLBase OLE DB Data Provider Built upon OLE DB technology. it aims to facilitate access to information across data sources.Chapter 4 Introducing SQLBase OLE DB Data Provider Overview OLE DB is an application programming interface. we recommend that you read Microsoft OLE DB 2. it results in a high level of interoperability among programming tools. legacy systems. such as Visual Basic and Delphi. An OLE DB data provider responds to OLE DB calls resulting in data being returned in a usable tabular format. 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. The goal is to reliably offer high-performance data access that supports industry standards.0 Programming Reference and Data Access SDK. it is possible for different pieces of an application to be written in different languages due to OLE DB’s COM structure. SQLBase OLE DB Data Provider lets programmers access SQLBase functionality from a variety of supported visual programming tools. SQLBase OLE DB Data Provider is a set of COM objects that expose the SQLBase functionality needed by developers to build applications. written by Microsoft. SQLBase OLE DB Data Provider exposes SQLBase Server properties more completely than the ODBC driver does. A data consumer is an application or COM component that uses the OLE DB API to access a data source. OLE DB components The two main components of OLE DB are a data provider and a data consumer. Recommended reading To make the best use of OLE DB. to develop application components that can function within a single application. and numerous programming languages and development tools. In addition to standard OLE 4-2 Connecting to SQLBase . developers have had to call SQL/API functions or use the ODBC API to access a database. Historically.

the Provider lets you define DBMS components. The Provider also provides high level access to your data through ActiveX Data Objects (ADO). Using OLE DB interfaces. create database. including backup. SQLBase OLE DB Data Provider runs in the address-space of the client program and is written over the SQL/API. Another level of simplification: ADO. and shutdown server. the Provider interfaces enable access to DBMS functionality not normally provided by OLE DB. Application ADO SQLBase OLE DB Data Provider Other Data Providers SQL/API ODBC Other databases SQLBase databases Other data sources Connecting to SQLBase 4-3 . including row containers. and transaction coordinators. query processors.About SQLBase OLE DB Data Provider DB conformance. The following figure shows the role of SQLBase OLE DB Data Provider in the application development process. A DLL.

In general.Password=sysadm" For a more complete example of connecting to SQLBase using ADO. 4-4 Connecting to SQLBase . Supported programming tools SQLBase OLE DB Data Provider is designed to work with the following programming tools: Gupta Team Developer (SQLWindows). The name of the SQLBase OLE DB provider is hard-coded as a constant. you may need to enter a provider name. your application can initiate local transactions and/or join in distributed transactions. the data source name is the name of the SQLBase database itself (for example. Data source name Some programming tools may prompt you for a data source name. For SQLBase OLE DB.User ID=SYSADM" _ & ". How-to information for the OLE DB provider How do SQLBase datatypes map to OLE DB datatypes? How do I start a transaction? Through the ITransactionLocal::StartTransaction and ITransactionJoin::JoinTransaction methods of the Session object. the name is: SQLBaseOLEDB The provider string is initialized for the open call that establishes a connection to SQLBase through the OLE DB provider. all the languages of Microsoft’s Visual Studio. read Chapter 5.Data Source=ISLAND" _ & ". Crystal Reports. password. For SQLBase OLE DB Data Provider. PowerBuilder. SQLBase OLE DB Data Provider works with any development environment that supports OLE DB data access. ISLAND). location and data source (tablename) are read from objects in your code. and many others. Delphi. Here is a sample: Dim sConnect As String ' holds ADO connect string ' set up connection string and open connection to data source sConnect = "Provider=SQLBASEOLEDB" _ & ". The user ID. Establishing a connection using ADO.Chapter 4 Introducing SQLBase OLE DB Data Provider SQLBase OLE DB Data Provider name When you configure a programming tool to use the Provider.

EMAIL. then a file. vbFromUnicode) Set strStream = New ADODB. Dim chunk() As Byte chunk() = StrConv(myRS("PHOTO1"). FIRST_NAME.doSelect (strSQL) Set myRS = myADO.setCursorType (adOpenKeyset) myADO. LAST_NAME.Picture = LoadPicture("C:\Temp.setLockType (adLockOptimistic) myADO. Use one of the supported levels shown in Isolation level mapping on page 6-2. CURRENT_SALARY.getRS If Not myRS.gif". How do I set isolation levels? The first parameter of the ITransactionLocal::StartTransaction method is isolation level. In MSDN.Open strStream. They illustrate how to fetch long data into an image.Type = adTypeBinary strStream. Populate a Recordset from a query that includes a SQLBase LONG VARCHAR datatype: strSQL = "SELECT EMPLOYEE_ID. in Visual Basic version 6. adSaveCreateOverWrite Image1. How do I use long character data and long binary data? These are edited code frargments from sample project Tut5.gif") Connecting to SQLBase 4-5 .MoveFirst End If Get the value of a Recordset column and convert it to a byte array.BOF And Not myRS.Value.Stream strStream. PHOTO1 FROM EMPLOYEE" Dim myRS As ADODB.Write chunk strStream. then load the image with the file. search for those method or interface names to get more detail on the overall transaction process. Note that not all OLE DB isolation levels are supported by SQLBase.EOF Then myRS.SaveToFile "C:\Temp.How-to information for the OLE DB provider SQLBase support for these interfaces is identical to the support described in the Microsoft Developer Network documentation.Recordset Dim iCount As Integer myADO.

com/data and access further information on ADO in: www. you can take advantage of: 4-6 Connecting to SQLBase . such as the SQLBase provider.Position = 0 strStream.Chapter 4 Introducing SQLBase OLE DB Data Provider Writing long binary information to the database can be accomplished by changing the value of a Recordset column. ADO's primary benefits are data source independence.Fields("PHOTO1"). Since ADO is independent of the data source.Charset = "ISO-8859-1" myRS.Value = strStream.LoadFromFile sFileName strStream. To make the best use of ADO. For more general information about OLE DB providers.Type = adTypeBinary strStream. you do not have to know all the intricacies of the database to take advantage of the provider.Open strStream. or into a string variable.Type = adTypeText strStream. In this case the binary information was first written to a file.Stream strStream. The SQLBase OLE DB Data Provider is a standard provider you can use with ADO as you would other standard providers. Using the SQLBase provider with ADO. you can choose to move it to a Byte array. high When working with long character data.ReadText myRS. we recommend you access the samples in: www. 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. low memory overhead. see the documentation for the Microsoft OLE DB SDK or visit the Microsoft OLE DB Web ADO features ADO provides a number of features for building client/server and Web-based applications. Set strStream = New ADODB. You can also simply fetch it into the Text value of a TextBox or RichTextBox control. and a small disk footprint. ease of

Programming with ADO ADO is a dual-interface COM type library. see the Remote Data Service documentation. As part of the Microsoft Data Access Components. then writing them all to the server in a single update. Connecting to SQLBase 4-7 . RDS has been combined with the ADO programming model to simplify client-side data remoting. when the user asks for the ability to fetch backward or scroll backward. The host product setup program may require that you specifically request the Microsoft Data Access Components in order to have ADO and RDS installed. If you are using client-side cursors.5 Library. select the Java Type Library Wizard. This helps improve performance by locally caching changes to data. check the box for "Microsoft ActiveX Data Objects 1. and also results in fewer ADO objects and thus a smaller working set. To use ADO with Microsoft Visual J++. This allows you to create and track only the objects you need. the provider asks the server to enable its cursors. by which you can move data from a server to a client application or Web page. you can do batch updating. check the box for "Microsoft ActiveX Data Objects 1. Batch updating. and return updates to the server in a single round trip.dll. including support of backend–specific cursors. To use ADO with Microsoft Visual Basic or Microsoft Office. Different cursor types." In two. Previously released as Advanced Data Connector. and properties will then be accessible through the VBA Object Browser and the IDE Editor. The file name is msado15. Unlike Data Access Objects (DAO) or Remote Data Objects (RDO). ADO objects." and then click OK. manipulate the data on the client. select References. The wizard will then create the necessary Java class files for ADO. such as Microsoft Internet Information Server. you also need to create a set of class files using the Java Type Library Wizard. • • • Remote Data Service ADO's Remote Data Service (RDS) allows data remoting. From the Tools menu. you no longer have to navigate through a hierarchy to create objects because most ADO objects can be independently created." and then click OK. The program ID (ProgID) is "ADODB. methods.and three-tier database applications.5 Library. Support for stored procedures with input (not output) parameters. ADO and RDS are automatically installed and registered by a host product. With the SQLBase provider. From the Project menu.ADO Overview • Independently-created objects. you also need to establish a reference to the ADO type library. For more information. ADO code that is to execute on the client uses the ProgID "ADOR" instead.

all of which result from the same incident. this is the equivalent of a recordset. as shown here: C++ adoint. However. use ADO as apartment-model threaded.Chapter 4 Introducing SQLBase OLE DB Data Provider For some programming JScript adojavas.h VBScript adovbs. without defining a Command object. the Errors collection can contain more than one Error object at a time. Cursor —In ADO. you can open multiple Recordset objects on the same connection. 4-8 Connecting to SQLBase . and a cursor into those records. Property — A provider-defined characteristic of an ADO object. parameter definitions. There are seven objects in the ADO object model: Command — Maintains information about a command. Each of these objects features a set of properties and methods with which you can manipulate the object and its contents. or execute a stored procedure that returns output parameters. the objects exist within hierarchical relationships. The Command object features a Parameters collection to contain all of its Parameter objects. if you do first create a Connection Threading With SQLBase OLE DB Data Provider. such as a query string. Because a single statement can generate two or more errors. Parameter — A single parameter for a parameterized Command. You can open a Recordset (that is. The Recordset object features a Fields collection to contain all of its Field objects.h adoid. you also need to reference (using the #include statement) one or more additional files in your source code. Connection — Maintains connection information with the data provider. ADO Objects Although you create ADO objects outside the scope of a hierarchy. Recordset — A set of records returned from a query. The Command object is useful where you want to define query parameters. Field — Contains information about a single column of data within a Recordset. as shown in the ADO Object Model. Error — Contains extended error information about an error condition raised by the provider. and so on. You can execute a command string on a Connection object or a query string as part of opening a Recordset object. execute a query) without explicitly opening a Connection object.

Item("Name") Because the Item method is a default method on an ADO collection.Properties. collecting error information. as shown: Command.ADO Overview Dynamic Properties Collections The Connection. This Microsoft Visual Basic Scripting code generates a Recordset from a SQLBase data source: set rstMain = CreateObject("ADODB. and so on. While the other objects are useful for managing connections. Working with Data In ADO. With a few modifications. This generates a forward-only.Open "SELECT * FROM company". The third line specifies the SQLBase provider and the data source.Item(0) Command. You use the collection and the Item method to reference the property by its name or by its ordinal position in the collection.Properties(0) Command. read-only Recordset object.Properties. and Recordset objects each support a Properties collection. the Recordset object is the main interface to data. so you can omit it as well: Command(0) Command("Name") All of these syntax forms are identical. the Properties collection itself is the default collection for the Connection. persisting queries.Recordset") rstMain.Properties("Name") Further.Open "SELECT * FROM company". most of your code's interaction with ADO will involve one or more Recordset objects. Command. _ Connecting to SQLBase 4-9 .Data source=ISLAND" The first line creates the ADO Recordset object. you can obtain a more functional Recordset: set rstMain = CreateObject("ADODB. The second line opens the recordset with a query. _ "provider=SQLBaseOLEDB. Which one you choose depends on your coding style preference.Recordset") rstMain. The properties collection contains any dynamic (or "provider-specific") properties exposed through ADO by the SQLBase provider. Command. you can omit it: Command. and Recordset objects.

as shown in these code examples. you must include the appropriate header file. how your application interacts with ADO will vary slightly between different providers. adLockBatchOptimistic This creates a fully scrollable and batch-updatable Recordset.Chapter 4 Introducing SQLBase OLE DB Data Provider "provider=SQLBASEOLEDB. then at the end of your application’s unit of work. use the Refresh method on the object's Properties collection to obtain the SQLBase provider-specific properties. After establishing the connection and creating these objects. Some values may have been changed since it was last read” SQLBase provider-specific dynamic properties The Properties collections of the Connection. The code for this application is discussed in detail later in this chapter. Note: For the Recordset object.Data source=ISLAND". include the file adojavas. because each provider is unique. • simplefetch Lets you connect to SQLBase and navigate. UpdateBatch() throws up following warning message which can be ignored: “Run-time error '-2147217864 (80040e38)': Row cannot be located for updating. You should always refer to constants by name rather than by value because the values may change from one version to the in your code. Command object usage. forward and in your code. For Microsoft Visual Basic Scripting code. 4-10 Connecting to SQLBase . 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. In order to reference ADO constants by name (instead of by value) when coding in a scripting language. If client cursors are used. and Recordset objects include dynamic properties specific to the SQLBase provider. include the file adovbs.part of the ISLAND sample database for SQLBase. Sample applications The SQLBase provider comes with a number of sample applications. For Microsoft JScript. Command. through the COMPANY table . Gupta recommends that you use server-side cursors (adUseServer). adOpenKeyset. all the changes should be committed using the UpdateBatch() method. The differences you need to be aware of when using SQLBase OLE DB Data Provider are: Connection parameters in the ConnectionString property. However. These properties provide information about functionality beyond the built-in properties ADO supports. Recordset behavior.

a connection object. a recordset object. Define a routine to fetch the values of the various fields from the database table.0. the sample we present in the next section follows these steps: 1. 3. processes it. Define a routine to safety handle null fields. You must have installed Microsoft Visual Basic 6. Connecting to data through the Provider Whether or not you use ADO or direct OLE DB. To establish a connection to SQLBase through ADO. Disconnect. • SqlBaseNativeCmdSample Demonstrates the SQLBase Native commands (load. and writes it out to a file.Connecting to data through the Provider • schema Lets you query the ADO schema types that the SQLBase OLE DB Data Provider supports. 5. it consumes OLE DB interfaces and data from the provider. • DBExplore Lets you query SQLBase using SQL statements to return Recordsets from the SQLBase database. Define a routine to output the Errors collection. Open a recordset object. DBExplore. 2. Establishing a connection using ADO ADO is an OLE DB consumer. 2. Connecting to SQLBase 4-11 . 6. 4. Create the various ADO objects. and an error object. Long text fields and Long Binaries are treated the same by the provider. store. erase and retrieve) . Process the recordset. Establish a connection. For example. you acquire database information using these steps: 1. 4. the Microsoft Data Access components and the SQLBase OLE DB Data Provider in order to use these samples. Navigate through the database.exe pulls out a Long Binary set of information. unload. Initialize the provider. 3.

by calling OutputMessage(). and data source (tablename) are read from TextBox objects. 6. Portions of the code that don't specifically illustrate the concepts used have been excluded from this text for brevity. output to Messages Listbox Dim ErrLoop As Error Set erCompany = cnCompany. 9. This is hardcoded as a constant. 10.Errors 2. The user. Provide code for button that moves to the last record in the RecordSet. They are based on the simplefetch sample supplied with the OLE DB Provider. Define two routines to output the Errors collection.Errors For Each ErrLoop In erCompany 4-12 Connecting to SQLBase . password. For more information. Provide code for a button that moves to the first record in the returned Recordset. and keeps the latest message in view at all times. and navigate through a SQLBase table using ADO in Visual BASIC. Provide code for a button that moves to the next record in the RecordSet. Provide code for a button that moves to the previous record in the RecordSet. 5. 1. The name of the SQLBase OLE DB provider is SQLBaseOLEDB. open a recordset object. 7.Recordset Dim erCompany As ADODB. The code fragments show how to establish a connection. 8. Coding Sample using ADO The following code sample illustrates how to use SQLBase OLE DB Data Provider. Define the code for the Connect button. Private Sub OutputErrorMessages() ‘ loop through errors returned from provider.Connection Dim rsCompany As New ADODB. This routine outputs the elements of the Errors collection. OutputMessage adds the messages to a ListBox on the form. one at a time. OutputErrorMessages() is called whenever an error condition is signalled from the provider.Chapter 4 Introducing SQLBase OLE DB Data Provider Our sample assigns the field data to text boxes on the Visual BASIC form. Create the various ADO objects Dim cnCompany As New ADODB. refer to the samples that ship with the product. Provide code for a button for closing the connection to SQLBase.

1 End Sub 3. assigning them to TextBox objects on the form.NativeError) & " " _ & ErrLoop.ListCount .SQLState _ & ErrLoop.TopIndex = lbMessages. TextBox objects can be bound to your recordset object.Establishing a connection using ADO OutputMessage ("Error: " _ & Str(ErrLoop. A check for BOF or EOF prevents errors when attempting to display values outside the table. Define a routine to check for null fields.Fields(sFieldName)) Then GetField = rsCompany. GetField() is used to prevent issues with NULL values returned from the provider. to cause them to update and handle NULL values automatically. Private Sub UpdateFieldsDisplay() If Not rsCompany.Fields(sFieldName) Else GetField = "" End If End Function 4.Description) Next ErrLoop End Sub Private Sub OutputMessage(sMessage As String) lbMessages. Define a routine to fetch the values of the various fields from the database table. IsNull is called on each value to prevent errors from Visual BASIC when returning NULL values.BOF And Not rsCompany.AddItem (sMessage) lbMessages. Because this sample obtains the values directly. Private Function GetField(sFieldName As String) As String If Not IsNull(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 Connecting to SQLBase 4-13 .

Chapter 4

Introducing SQLBase OLE DB Data Provider


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 SQLBase through the OLE DB provider. The name of the SQLBase OLE DB provider is hard-coded 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 can also 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"

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

4-14 Connecting to SQLBase

Establishing a connection using ADO

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.
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


Provide code for a button for closing the connection to SQLBase.

Private Sub pbDisconnect_Click() cnCompany.Close End Sub


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


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

Connecting to SQLBase


Chapter 4

Introducing SQLBase OLE DB Data Provider

If Not rsCompany.EOF Then rsCompany.MoveNext ' if we're NOW past the last record... If rsCompany.EOF Then ' put cursor back on last record rsCompany.MoveLast Else Call UpdateFieldsDisplay End If End Sub


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

4-16 Connecting to SQLBase

Connecting to SQLBase 5-1 . the tables describe interfaces of objects the Provider supports. and whether our support is standard or specific.Connecting to SQLBase 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.

Command (TCommand) objects create a text command.Chapter 5 Supported OLE DB COM Objects Supported COM objects SQLBase OLE DB Data Provider uses OLE DB COM objects and their supported interfaces to provide access to SQLBase functionality. These objects function as factory for sessions. 5-2 Connecting to SQLBase . A single data source object can create multiple sessions. Rowset (TRowset) objects expose data from a data source in a tabular format. Error (TError) objects are created when errors occur when accessing a data provider. and an optional custom error object. Row sets can be created from a session or a command. such as a file or a DBMS. An index object is a special case of a row set object. SQLBase OLE DB Data Provider utilizes the custom error object. SQLBase OLE DB Data Provider uses the following COM cotypes: • Data Source (TDataSource) objects contain the machinery to connect to a data source. Sessions are a factory for transactions. commands. read Microsoft OLE DB documentation or visit the Microsoft Web site. and rowsets. that can query or update a data source. such as an SQL statement. • • • • For a list and detailed description of the supported interfaces for the COM objects above. return codes. it creates a row set. such as an SQL Select statement. If the text command specifies a row set. They include status. A single session can create multiple commands. Session (TSession) objects create a context for transactions and can be implicitly or explicitly transacted.

can have a minimum value of 1 and a maximum value of 32000. (Default values are 2000 and 1000. and oms. Interface Name IDBCreateSession IDBInitialize Description Calls on a data source object to obtain a new session. ims. any of them can be omitted.Data Source Data Source SQLBase OLE DB Data Provider uses the following Data Source (TDataSource) object interfaces: Mandatory Optional IDBCreateSession IDBInitialize IDBProperties IPersist IDBInfo ISupportErrorInfo Data Source properties In addition to the properties inherited from its underlying classes. The parameter value. Standard. input message buffer size.oms=<value> The configuration file name should include a fully qualified path.ims=<value>. Initialize and uninitialize data source objects. If there are two or more pieces in the string. output message buffer size. except enumerators are not supported. must be formatted as follows: INI=<ConfigFileName>. Data Source descriptions The following table briefly describes the data source interfaces and the level of support they receive. Connecting to SQLBase 5-3 . the elements must be separated by semicolons. TDataSource has some specific properties of interest: DBPROP_INIT_PROVIDERSTRING This property can be used to supply up to three pieces of configuration information prior to making a connection to the database server. a string. Support Standard.) None of the three pieces of the string are required.

except enumerators are not supported. Optional interface is supported. Returns the class identifier of an object. Shows whether an interface can return automated error messages. SQLBase OLE DB COM objects that implement this interface also return error objects. Returns a list of providerspecific keywords. Support Standard. Standard.Chapter 5 Supported OLE DB COM Objects Interface Name IDBProperties Description Sets and gets properties values for the data source object. or information about literals. IPersist IDBInfo ISupportErrorInfo 5-4 Connecting to SQLBase .

Support Standard. Standard. It is a mandatory interface on sessions. IDBSchemaRowset provides advanced schema information. IDBCreateCommand Standard. IDBSchemaRowset Standard.Session 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. IOpenRowset opens and returns a rowset that includes all rows from a single base table or index. Consumers call IDBCreateCommand::CreateComm on a session to obtain a new command. Interface Name IGetDataSource IOpenRowset Description IGetDataSource returns an interface pointer to the data source object. ISessionProperties Standard. Connecting to SQLBase 5-5 . ISessionProperties returns information about the properties a session supports and the current settings of those properties.

Chapter 5 Supported OLE DB COM Objects Interface Name ISupportErrorInfo Description ISupportErrorInfo interface shows whether an interface can return automated error messages. commit. ITableDefinition Standard. ITransactionJoin Standard Command SQLBase OLE DB Data Provider uses the following Command (TCommand) object interfaces: Mandatory IAccessor IColumnsInfo ICommand ICommandProperties ICommandText IConvertType IColumnsRowset ICommandPrepare ICommandWithParameters ISupportErrorInfo Optional 5-6 Connecting to SQLBase . and alter data source indexes. ITransactionLocal Standard. drop. IIndexDefinition Standard. and alter data source tables. ITransactionObject Standard. and abort session transactions. drop. The ITableDefinition interface exposes simple methods to create. Support Standard. ITransactionLocal is used to start. It is optional ITransactionObject obtains the transaction object associated with a particular transaction level. The IIndexDefinition interface exposes simple methods to create. ITransactionJoin allows your session to enlist in a distributed transaction.

IConvertType Standard. Support Standard. This optional interface encapsulates command optimization. This interface supplies complete infomation about columns in a rowset. IColumnsInfo exposes column information for a rowset or prepare command. This interface is mandatory on commands. Interface Name IAccessor IColumsInfo Description The IAccessor describes how consumer buffer data is stored. IConvertType provides command or rowset conversion type information. Connecting to SQLBase 5-7 . ICommandWithParameters Standard. a separation of compile time and run time. IColumnsRowSet ICommandPrepare Standard. This interface encapsulates parameters. When ICommandText is specified through SetCommandText. Standard. and index rowsets. ISupportErrorInfo Note: Because the SQLBase OLE DB provider exposes ICommandPrepare.Command Command Class Interface descriptions The following table briefly describes the command class interfaces and the level of support they receive. it replaces the existing command text. See Note. Standard. ICommand executes commands. This interface is mandatory on commands. Please see the OLE DB Programmer’s Reference for further information. Standard. See Note. Also. ICommandProperties specifies properties from the Rowset property group to the command. ISupportErrorInfo interface shows whether an interface can return automated error messages. there are important stipulations to using the IColumnsInfo interface. it provides limited information for an array. rowsets. ICommand ICommandProperties ICommandText Standard.

IRowsetInfo provides information about a rowset. IRowsetInfo also provides methods for retrieving objects associated with the rowset. IRowsetInfo Standard. IConvertType provides command or rowset conversion type information. IRowset requires IAccessor and IRowsetInfo. All rowsets must implement IRowsetInfo. It provides a limited set of array information. It provides methods for fetching rows sequentially. and managing rows. This interface is mandatory for commands. Interface Name IAccessor IColumnsInfo Description The IAccessor describes how consumer buffer data is stored. and index rowsets. Support Standard. IConvertType Standard. IRowset is the base rowset interface. See Note.Chapter 5 Supported OLE DB COM Objects 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. IRowset Standard. getting the data from those rows. rowsets. 5-8 Connecting to SQLBase . IColumnsInfo exposes column information about rowset or prepared commands.

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

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

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

Chapter 6 ADO Mapping to Gupta Isolation level mapping This table compares ADO isolation levels to SQLBase. and collections: • • • Method() . ADO Default adXactUnspecified adXactBrowse adXactChaos adXactCursorStability adXactIsolated adXactReadCommitted adXactReadUncommitted adXactRepeatableRead adXactSerializable SQLBase CS (cursor stability) Set to default (CS) RL (release lock) error CS (cursor stability) error CS (cursor stability) 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.Property Collection[] 6-2 Connecting to SQLBase . properties.

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

Provider .HelpContent .Description .ConnectionTimeout .Chapter 6 ADO Mapping to Gupta ADO Method. or Collection .Mode . Property. or Collection OpenSchema() .DefaultDatabase OLE DB Method(s) called IDBSchemaRowset::GetRowset ITransactionLocal::Abort ICommandProperties::SetCommandProperties (DBPROP_COMMANDTIMEOUT) IDBProperties::SetProperties (DBPROP_INIT_TIMEOUT) IDBProperties::GetProperties (DBPROP_CURRENTCATALOG) IDBProperties::SetProperties (DBPROP_CURRENTCATALOG) ITransactionLocal::StartTransaction IDBProperties::GetProperties (DBPROP_INIT_MODE) IDBProperties::SetProperties (DBPROP_INIT_MODE) ISourcesRowset::GetSourcesRowset Support? Yes Yes Yes Yes Yes Yes Yes Yes Yes .NativeError OLE DB Method(s) called IErrorRecords::GetErrorInfo IErrorRecords::GetErrorInfo IErrorRecords::GetErrorInfo IErrorRecords::GetCustomErrorObject ISQLError::GetSQLInfo Support? Yes Yes Yes Yes Yes 6-4 Connecting to SQLBase . Property.HelpFile .Version Errors[] Properties[] Yes Yes IErrorRecords IDBProperties::GetPropertyInfo IDBProperties::GetProperties IDBProperties::SetProperties Yes Yes Yes Yes Error object mapping ADO Method.IsolationLevel .Attributes .CommandTimeout .

Source . Property.Value OLE DB Method(s) called ISequentialStream::Write ISequentialStream::Read IAccessor::CreateAccessor IRowset::GetData IColumnInfo::GetColumnInfo IColumnInfo::GetColumnInfo IColumnInfo::GetColumnInfo IColumnInfo::GetColumnInfo IRowsetUpdate::GetOriginalData IColumnInfo::GetColumnInfo IColumnInfo:GetColumnInfo IRowsetRefresh::GetLastVisibleData or IRowsetRefresh::GetVisibleData IAccessor::CreateAccessor IRowset::GetData IRowset::SetData IColumnsRowset::GetAvailableColumns IColumnsRowset::GetColumnsRowset Support? Yes Yes Yes Yes Yes Yes Yes Yes No Yes Yes No No Yes Yes Yes Yes Yes Properties[] Connecting to SQLBase 6-5 .SQLState OLE DB Method(s) called Support? Yes IErrorRecords::GetErrorInfo IErrorRecords::GetCustomErrorObject ISQLError::GetSQLInfo Yes Yes Yes Field object mapping ADO Method.Precision .Name .Number .Attributes .UnderlyingValue .Field object mapping ADO Method. Property. or Collection .DefinedSize .ActualSize .NumericScale .OriginalValue . or Collection AppendChunk() GetChunk() .Type .

Name .Type .NumericScale . Property.Size .Attributes ICommandWithParameters::GetParameterInfo or DBSCHEMA_PROCEDURE_PARAMETERS ICommandWithParameters::SetParameterInfo ICommandWithParameters::GetParameterInfo or DBSCHEMA_PROCEDURE_PARAMETERS ICommandWithParameters::SetParameterInfo 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 OLE DB Method(s) called Support? Yes Yes (No) Yes Yes (No) Yes Yes (No) Yes (No) Yes Yes (No) Yes Yes (No) Yes Yes (No) Yes Yes Yes Yes .Precision . or Collection AppendChunk() .Value Properties[] 6-6 Connecting to SQLBase .Chapter 6 ADO Mapping to Gupta Parameter object mapping ADO Method.Direction .

Property.Recordset object mapping Recordset object mapping ADO Method. or Collection AddNew() CancelBatch() CancelUpdate() Clone() Close() Delete() GetRows() IRowsetLocate IAccessor::ReleaseAccessor IRowset::ReleaseRows IRowsetChange::DeleteRows IAccessor::CreateAccessor IRowsetLocate::GetRowsAt IRowset::GetNextRows IRowset::GetData IRowsetLocate::GetRowsAt or IRowset::GetNextRows IRowsetLocate::GetRowsAt or IRowset::RestartPosition IRowsetLocate::GetRowsAt IRowsetLocate::GetRowsAt or IRowset::GetNextRows IRowsetLocate::GetRowsAt or IRowset::GetNextRows IMultipleResults::GetResult IOpenRowset::OpenRowset or ICommand::Execute IOpenRowset::OpenRowset or ICommand::Execute IRowsetRefresh::RefreshVisibleData IRowsetInfo::GetProperties OLE DB Method(s) called IRowsetChange::InsertRow IRowsetUpdate::Undo Support? Yes No Yes No Yes Yes Yes Yes No Yes Yes No Yes No Yes No No Yes No Yes No Yes Yes Yes Yes No Yes Move() MoveFirst() MoveLast() MoveNext() MovePrevious() NextRecordset() Open() Requery() Resync() Supports() Connecting to SQLBase 6-7 .

RecordCount 6-8 Connecting to SQLBase .MaxRecords .EditMode .ActiveConnection . or Collection Update() UpdateBatch() .LockType .PageCount . Property.BOF .AbsolutePage OLE DB Method(s) called IRowsetChange::SetData and/or IRowsetUpdate::Update IRowsetUpdate::Update IRowsetScroll::GetApproximatePosition IRowsetScroll::GetRowsAtRatio or IRowsetLocate::GetRowsAt IRowsetScroll::GetApproximatePosition IRowsetScroll::GetRowsAtRatio or IRowsetLocate::GetRowsAt IDBInitialize::Initialize IDBCreateSession::CreateSession Support? Yes No No No No No No No No Yes Yes Yes .CacheSize .PageSize .AbsolutePosition .Chapter 6 ADO Mapping to Gupta ADO Method.CursorType .Bookmark .EOF . AbsolutePage properties) IRowsetScroll::GetApproximatePosition No No No No No Yes Yes Yes No No No .Filter IAccessor::CreateAccessor IRowsetLocate::GetRowsAt IRowsetLocate::GetRowsAt or IRowset::GetNextRows ICommandProperties::SetProperties IRowsetUpdate::GetRowsStatus Yes No No Yes Yes No Yes IRowsetUpdate::GetPendingRows IRowsetLocate::GetRowsByBookmark or IRowsetView::CreateView IRowsetView::OpenViewChapter IViewFilter::SetFilter ICommandProperties::SetProperties IOpenRowset::OpenRowset (DBPROP_MAXROWS) or ICommandProperties::SetCommandProperties (DBPROP_MAXROWS) IRowsetScroll::GetApproximatePosition (PageCount.

Status Fields[] Properties[] OLE DB Method(s) called Support? Yes IRowsetUpdate::GetRowStatus IColumnInfo::GetColumnInfo IRowsetInfo::GetPropertyInfo IRowsetInfo::GetProperties IRowsetInfo::SetProperties No Yes Yes Yes Yes Connecting to SQLBase 6-9 . Property.Source . or Collection .Recordset object mapping ADO Method.

Chapter 6 ADO Mapping to Gupta 6-10 Connecting to SQLBase .

Connecting to SQLBase

Chapter 7

.NET Data Provider
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. 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:
Imports Gupta.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

Connecting to SQLBase


Chapter 7

.NET Data Provider

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. 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.

How-to information for the .NET data provider
How do SQLBase datatypes map to CLR datatypes?
SQLBase Type Integer Smallint Float Number Int32 Int16 Single Decimal CLR Type


Connecting to SQLBase

How-to information for the .NET data provider

SQLBase Type Double Decimal Date Time Timestamp Char Varchar Graphic Vargraphic Binary Varbinary Longvar Longvargraphic Longbinary Char>254 Varchar>254 Double

CLR Type

Decimal DateTime DateTime DateTime String String byte[] byte[] byte[] byte[] byte[] byte[] byte[] char[] char[]

How do I start a transaction?
See BeginTransaction on page 7-6, 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-6. Note that only some .NET isolation levels are supported by SQLBase.

How do I use long character data and long binary data?
In this example from the Tut5 application in samples\tutorials\, 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.
Connecting to SQLBase


PHOTO1 FROM EMPLOYEE". pwd= sysadm. "EMPLOYEE_ID").Tables(0).ini ") ' Open a connection to SQLBase conn.ini ") conn.Open() ' Setup the Adapter's select command adaptor. " & _ "CURRENT_SALARY. LAST_NAME. an image is used to update the EMPLOYEES.ExecuteNonQuery() Then 'Close the database connection conn. conn) 'Add the parameters UpdCmd.5\sql. pwd= sysadm. "EMPLOYEE") ' Close the database connection conn.Binary. ini=D:\Gupta\SQLBase 8. uid = sysadm. Byte()) In this example from the Tut5 application in samples\tutorials\vb. Variable FileByteArray was previously initialized with the bytes of the uid = sysadm. "Message") SavePictureToDB = True End If 7-4 Connecting to SQLBase .Open() 'Setup the Update SQL & Declare a Command Object UpdCmd = New SQLBaseCommand("UPDATE EMPLOYEE SET PHOTO1=:lsPhoto WHERE EMPLOYEE_ID=:sEmployeeID".Value = txtEmployeeID.Fill(ds.SelectCommand() = New SQLBaseCommand("SELECT EMPLOYEE_ID.Close() MessageBox. ini=D:\Gupta\SQLBase 8. FIRST_NAME.Text ' Execute the command If UpdCmd.PHOTO column in the ISLAND database.Chapter 7 .NET Data Provider ' Setup the SQLBase connection string conn = New SQLBaseConnection("data source=island. conn) ' Create a new DataSet ds = New DataSet() ' Fill the DataSet with the Adapter adaptor.Rows(i)("PHOTO1"). DbType.Add("sEmployeeID".Show("Image Updated".Parameters. o.Length). EMAIL. ' Setup the SQLBase connection string & open a connection to SQLBase conn = New SQLBaseConnection("data source=island.Close() 'Create the array to store the picture Dim arrPicture() As Byte = CType(ds.Add("lsPhoto".5\sql.Value = FileByteArray UpdCmd.Parameters. DbType.

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

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

Primary_Keys SQLBaseSchemaGuid. GetSQLBaseSchemaTable Syntax Description DataTable GetSQLBaseSchemaTable (schemaGuid.Foreign_Keys SQLBaseSchemaGuid.Procedures SQLBaseSchemaGuid. restrictions) Return a DataTable object containing schema information for the currently connected database. read Connection pooling in the Open method on page 7-8.Views SQLBaseSchemaGuid. The connection may be cached rather than physically closed.Table_Privileges Parameters schemaGuid instance of class SQLBaseSchemaGuid Connecting to SQLBase 7-7 . Close Syntax Description void Close() This method logically closes your database connection.Tables SQLBaseSchemaGuid.Indexes SQLBaseSchemaGuid.Tables_Info SQLBaseSchemaGuid.Provider_Type SQLBaseSchemaGuid. SQLBase supports the following types of schema information: SQLBaseSchemaGuid. Calling this method will throw a NotSupportedException exception to the caller.Columns SQLBaseSchemaGuid.SQLBaseConnection object ChangeDatabase Syntax Description void ChangeDatabase (string dbname ) This method is not supported by SQLBase. for details on this. CreateCommand Syntax Description IDbCommand CreateCommand( ) Initialize a new SQLBaseCommand object.Catalogs SQLBaseSchemaGuid.Column_Privileges SQLBaseSchemaGuid.

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

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

Datatypes are mapped to CLR-compatible types as described in How do SQLBase datatypes map to CLR datatypes? on page 7-2. The value to be assigned to the parameter. under the function sqlset. string. GetEnumerator. methods Syntax Int16 GetInt16 (index) Int32 GetInt32 (index) Int64 GetInt64 (index) Single GetFloat (index) byte GetByte (index) char GetChar (index) 7-10 Connecting to SQLBase . SQLBaseDataReader object For information about the methods. They manipulate the many SQLBase internal parameters.ResultSetMode must be set to TRUE. The SQLBaseDataReader object implements interface IEnumerable. Parameters parametertype value length string. Note: This method should be used only by advanced SQLBase developers. see the . SQLBaseDataReader methods Get.NET Data Provider SetSQLBaseParameter and GetSQLBaseParameter are not part of the IDbCommand interface. integer.NET Framework documentation. That object has methods MoveNext and Reset. which returns an IEnumerator object. properties and events inherited from IDataReader. with a single method. To make use of scrolling result sets.. Detailed documentation for these parameters is available in the SQLBase SQL Application Programming Interface Reference.Chapter 7 . which allow you to move to a specific row in the result set. property SQLBaseCommand.. One of the parameter names documented in the SQLBase API Reference. SQLBase supports only a single result set. This object provides the capability of reading a scrolling result set obtained by executing a command against a data source. and get/set property RowPos (current row of result set). The length in bytes of value. Calling this method while in the middle of a transaction can potentially cause unpredictable results in the transaction or the database.

The position of the column in the result set. index int. the length of the column. Relative position of the column in the row. Zero-based. or. index int. offset. throws exception IndexOutOfRange. buffer. byte[] or char[]. Offset within the long data column at which reading is to begin.NET system type for the specified column. index offset buffer readBytes Long. If index is not found. GetFieldType Syntax Description Type GetFieldType (index) Return the . exception IndexOutOfRange is thrown. Parameters Get methods for long (BLOB) data Syntax Description long GetBytes (index. If index is not found. Number of bytes to read into buffer. Buffer to hold the results of the read. If parameter index is not valid. If index is not found. The specific method chosen is dependent on the datatype of the column. Parameters GetDataTypeName Syntax Description Parameters string GetDataTypeName (index) Get the SQLBase (not CLR) datatype for the specified column.SQLBaseDataReader object 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. readBytes) long GetChars (index. offset. throws exception IndexOutOfRange. Returns the number of bytes actually read. buffer. throws exception IndexOutOfRange. Connecting to SQLBase 7-11 . long. if buffer is null. long. readBytes) Reads bytes or characters from a column with a long datatype. Position of column in the result set. depending on method.

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

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

NET Data Provider SQLBaseTransaction object For information about the methods.NET Framework documentation. properties and events inherited from IDbTransaction. The client should call BeginTransaction method from the Connection object to start a transaction again. This object has four properties and no methods. Get only. Rollback Syntax Description void Rollback ( ) Roll back a transaction from a pending state. see the . The CLR datatype of the parameter. IsolationLevel Datatype: IsolationLevel. SQLBaseParameter object For information about the methods. The Connection object which should be passed to this object in the constructor. You must set its properties to appropriate values before supplying this object to the SQLBaseCommand object before execution. SQLBaseTransaction methods Commit Syntax Description void Commit ( ) Commit the database transaction.Chapter 7 . The current transaction is complete.NET Framework documentation. Properties DbType: DbType Get/Set. The IsolationLevel enumeration which should be passed to this object in the constructor from the connection’s BeginTransaction ( ) method. properties and events inherited from IDbTransaction. see the . 7-14 Connecting to SQLBase . SQLBaseTransaction Properties Connection Datatype: SQLBaseConnection.

type) text parametername type string. Name of the parameter. String: SourceColumn Get/Set. The name that the command object uses to refer to the parameter. The actual value assigned to this parameter. Value of the parameter. Object: Value Get/Set. value) text parametername value string. Add Syntax Description Parameters SQLBaseParameter Add (value) Add value object. The Add method is overloaded in five ways. Links this parameter to a column in a DataSet object. object. SQLBaseParameters object This object is basically a collection of SQLBaseParameter objects. Datatype of the parameter. Syntax Description Parameters SQLBaseParameter Add (value) text value SQLBaseParameter Syntax Description Parameters SQLBaseParameter Add (parametername.SQLBaseParameters object String: ParameterName Get/Set. Name of the parameter DbType. Syntax Description Parameters SQLBaseParameter Add (parametername. Connecting to SQLBase 7-15 .

SQLBase classes and transaction state It is possible in the .BeginTransaction method. column) text parametername type column string.BeginTransaction: “Failed to set transaction for the command. dbType.” The exception guards against situations like the example below: • • • Open a SQLBaseConnection object named “conn” Create a SQLBaseCommand object against conn named “cmd” Create a SQLBaseTransaction object named “txn” by calling the conn. String: ErrorMessage Get only. The description of the error. 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. Name of the parameter. DbType. Data set column associated with the parameter. SQLBaseException Properties int: ErrorCode Get only. The offset in the command text where the error was detected. (Now this database connection is logically 7-16 Connecting to SQLBase .Chapter 7 . To prevent this disruption. The transaction is not compatible with the connection. SQLBaseException object This object handles all errors returned by SQLBase.NET Data Provider Syntax Description Parameters SQLBaseParameter Add(parameterName. int: ErrorPosition Get only. string. The SQLBase numeric code of the error. Datatype of the parameter.NET framework to write code that could disrupt the state of a SQLBase transaction.

SQLBase classes and transaction state

“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. 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


Chapter 7

.NET Data Provider

7-18 Connecting to SQLBase

Connecting to SQLBase

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 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.)

The SQLBase JDBC driver supports applications written using JDBC 1.3.1 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.

Connecting to SQLBase


the following file will be installed: /opt/Gupta/SQLBase90/java/SQLBaseJDBC.0.0.JDBC class files CLASSPATH To allow the Java Virtual Machine to load the SQLBase JDBC Driver locally or at the host-of-origin. Modern Web browsers such as Netscape Communicator version 4 and higher. the following files and directories will be found. Server 2003. and (for Linux) on Red Hat 9. SUSE 9. support JDK 1. Installation Tested Platforms This driver has been tested on Windows 98. Presuming you also install the JDBC driver to this directory. ME. if you chose the SQLBase default directory as your installation directory.1. the standard Java system environment variable CLASSPATH must be modified to include the root directory containing the JDBC classes.0. This driver is compatible with JDK 1. SUSE Desktop 1. Red Hat Advanced Server 3. then after installation.Contains the JDBC class files.0. Linux JDBC support is an option at the time of installation in Linux. 2000. you would set the variable as follows on Windows: 8-2 Connecting to SQLBase . For example.Contains a set of sample JDBC application programs as tutorials. and Microsoft Internet Explorer version 4 and higher.x and higher.1.jar .Chapter 8 Introduction to the JDBC driver JDK Versions There are multiple versions of the Java Development Kit (JDK).0. and XP. SUSE Enterprise Server 8. c:\program files\gupta\SQLBase90\Samples . If you use the default installation directory. 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.x. c:\program files\gupta\SQLBase90\Java\SQLBaseJDBC. NT.jar . including JDBC functionality.

and transactions committed for one connection are completely independent of transactions committed for another connection. such as loading and unloading. if you chose the default installation directory. backup. An application can establish multiple connections ("cursor handles") to a SQLBase Server.jar Server Configuration The server should be configured to listen on TCP/IP protocols. CLASSPATH would be altered like this: export CLASSPATH=$CLASSPATH:/opt/Gupta/SQLBase90/java/SQLBaseJDBC. deletions. Multiple Connection Support The SQLBase JDBC Driver supports the multiple connection model of SQLBase 7. please refer to the SQLBase Database Administrator's Guide chapter on communications. The "ADJUSTING" clause of the INSERT keyword is not supported. selects (including data binding). For more information regarding the use of TCP/IP.jar And on Linux. DDL Operations Support All DDL operations. updates. DML Operations Support Most DML operations such as insertions. dropping tables.SQLBase Support for JDBC SET CLASSPATH=%CLASSPATH%. Multi-threading Support The JDBC Driver is implemented to be thread safe. SQLBase Support for JDBC SQL Operations Support The SQLBase JDBC Driver is designed to access relational database over the Internet or an Intranet. and stored procedures are supported.0 and higher. Operations which require a server connection. An application can use multiple threads to perform operations on various tables while the user continues to interact with the application. and creating indices are supported. Connecting to SQLBase 8-3 . long varchars. such as creating tables. and restore are not supported in this release of the JDBC Driver since such connections are not supported by JDBC. It currently supports common DDL and DML operations.C:\program files\gupta\java\SQLBaseJDBC.

Chapter 8 Introduction to the JDBC driver It is NOT recommended that JDBC objects (i.) are shared between threads because an object's internal state can be corrupted by interleaved threads. ResultSet etc.e. Each thread should operate privately on JDBC objects. How-to information for the JDBC driver How do SQLBase datatypes map to JDBC datatypes? See SQLBase Supported Data Types: on page 8-8 8-4 Connecting to SQLBase . 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 Description RL (release locks) isolation RR (read repeatability) isolation CS (cursor stability) isolation RO (read only) isolation The default TRANSACTION isolation for the JDBC Driver is TRANSACTION_REPEATABLE_READ. Isolation Level TRANSACTION_NONE TRANSACTION_READ_COMMITTED TRANSACTION_SERIALIZABLE TRANSACTION_READ_UNCOMMITTED TRANSACTION_REPEATABLE_READ Description AutoCommit plus RL (release locks) isolation CS (cursor stability) Not Supported (Creates an Exception) Not Supported (Creates an Exception) RR For SQLBase specific applications or applets that require a strict SQLBase transaction model. Statement. Transaction Model The transaction model is uniform between the SQLBase ODBC Driver and the JDBC Driver.

length().executeUpdate("DROP TABLE TESTAC1"). //Inserting Long Data java.executeUpdate("CREATE TABLE TESTAC1 (C1 INT. How do I set isolation levels? Use method setTransactionIsolation. long fileLength = file. con1. con1. Connection con1 = DriverManager.?)").println("inserting long data").FileInputStream(file).getConnection(url. "SYSADM". catch (SQLException se) // Do nothing if table does not exist } information for the JDBC driver How do I start a transaction? A code fragment illustrating a simple transaction is shown below. you can see methods getAsciiStream and setAsciiStream are used to bind long data to specific symbol positions in a SQL query statement. Connection con1 = DriverManager.commit().io. con1.setAutoCommit(false).out. The supported isolatoin levels are shown in Transaction Model on page How do I use long character data and long binary data? In this code fragment from sample program longs.prepareStatement("INSERT INTO test VALUES (1.File("longs.executeUpdate("create table test(c1 int.TRANSACTION_NONE). java.getConnection(url. con1.sql. 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). System. included with SQLBase.File file = new java.InputStream fin = new java. Statement stmt1 = con1.commit(). Changing the setting of AuoCommit implicitly starts a new transaction. try {stmt1. In this example. "SYSADM").close(). "SYSADM").createStatement(). "SYSADM". java. Connecting to SQLBase 8-5 . c2 long varchar)").PreparedStatement pstmt = con1.txt"). as shown below. stmt. C2 CHAR(10))").

95.oms=] jdbc:sqlbase://server1[:2157]/island [. the default of ims=2000 will be used. Use a value from 1 to 32000. ims (optional) is input message buffer size. the default of oms=1000 will be used. The following conversion table is provided to show the mapping between SQLBase storage types and the Java data types: 8-6 Connecting to SQLBase .Chapter 8 Introduction to the JDBC driver stmt.ims=.setAsciiStream(1. while (rs. It needs to be specified only when a different port number is being used by the SQLBase server. ResultSet rs = stmt.oms=] jdbc:sqlbase://198. island is the database where this URL is intended to connect.(int)fileLength). fin. Use a value from 1 to pstmt.xx:2156/island [. oms (optional) is output message buffer size.getAsciiStream(1) in which case it follows the host name or IP address. How do I run stored procedures? See Stored procedure support on page 8-11 URL formats Examples of use of the standard formats are illustrated below: jdbc:sqlbase://localhost[:2157]/island [. separated by a colon.ims=.executeQuery("SELECT c2 FROM test WHERE c1 = 1 "). 198. If no value or an invalid value is specified. //Fetching Long Data byte [] buff = new byte[4096]. Data types and conversions SQLBase data types do not map completely to Java data types.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 ()) { fin = rs. If no value or an invalid value is specified.xx is an IP address.95.

a valid get/set is performed Connecting to SQLBase 8-7 .Data types and conversions Explanation of keys: Key C D E W * Description Conversion is done .a truncation warning is issued for loss of digits No warning .a conversion warning is issued for accuracy check Date crash is done Throw exception .this conversion is not allowed Field width and data width mismatch .

DECIMAL. REAL DATE LONGVARCHAR DATETIME TIME SQL Data Type For READING Operations using ResultSet: CHAR W C C C C C C C C * C C C * NUM W * C W W W W W W C C C C C DATE W E E E E E E E E C * C C C LONG W E E E E E E E E * E E E * W E E E E E E E E C C C * C DT TIME W E E E E E E E E C C * C C ResultSet Methods getString from CHAR. INTEGER.Chapter 8 Introduction to the JDBC driver SQLBase Supported Data Types: JDBC Data Type CHAR NUM DATE LONG DT TIME CHAR NUMBER. FLOAT.VARCHAR getBigDecimal from NUMERIC getBool from BIT getByte from TINYINT getShort from SMALLINT getInt from INTEGER getLong from BIGINT getFloat from REAL getDouble from DOUBLE getBytes[] ** getDate from DATE getTime from TIME getTimestamp from TIMESTAMP getStream from LONGVARCHAR ** same as getStream from VARBINARY or LONGVARBINARY 8-8 Connecting to SQLBase . DOUBLE.

out.?. C8 time.?.forName("jdbc.2).getMessage()). etc.SqlbaseDriver"). etc.?.length > 0 && args[0]. try { executeUpdate(stmt. } catch (Exception e) { System. C3 dec(8. con1.out. } } public static void main (String args[]) { try { Class.) in preparing bind variable datatypes.out. C4 integer. "SYSADM". public class InsertDataTypes { private static String url = "jdbc:sqlbase://localhost:2155/ ISLAND".length() > 0) { url = args[0].println("'" + sql + "' failed with: " + ex). Connecting to SQLBase 8-9 .createStatement()." + "C5 smallint. if ( args. C9 date)". } String sQuery = "Create table foosh (C1 char(10). } // ENDIF Get Connection URL Connection con1 = DriverManager. sQuery).println("e = " + e.getConnection( url.commit().) are used when retrieving individual values from result sets. String sql ) { try { stmt. Similar methods (getString. private static void executeUpdate(Statement stmt.?.?)"). }catch (Exception ex) { System." + " C7 datetime. "drop table foosh").println("Will insert 9 columns to the row"). C6 float. System.gupta." + "C2 varchar(10).?.?. getShort. setShort.SQLBase Supported Data Types: Datatypes example This example shows the use of various methods (setString. executeUpdate(stmt. "SYSADM").?. Statement stmt = con1.prepareStatement ( "Insert into foosh values(?. PreparedStatement pStmt = con1.sqlbase.executeUpdate(sql).

0").z).getTimestamp(7).println("Exception in main: " + ex). " + d2). } catch (Exception ex) { System.valueOf("1999-11-31"). C7.setShort (5.y).setString(2.a). java. = = = = = = = = " + i).println("C1 System. pStmt.valueOf("23:30:15").setDouble (3.getInt(4).Date.6789. java. pStmt. System. float f = rs.out.setInt (4. short a = 8.sql. pStmt. pStmt.executeUpdate()."+ "C2. pStmt.sql.out. java.close().C3. Statement stmt1 = con1.Timestampy = java.C8.println("C2 System.getString(2).println("C4 System.18. C6. String s2 = rs.println("C8 } con1.setFloat (6.Chapter 8 Introduction to the JDBC driver java.setString(1. pStmt. C5.getTime(8).println("C6 System.println("C5 System. while (rs.Datex = java.sql.sql.out. " + s1)."Wushi"). " + d1). int n = pStmt.createStatement().Timestamp. java.out. double d = rs.Timestamp d1 = rs.valueOf("1998-1130 12:59:59.C9 from foosh").setTime(8.sql.out. int i = rs. ResultSet rs = stmt1.out. con1.commit().0f).out.getDouble("c3").C4.out.setDate(9.println("C3 System.x). pStmt.Date d3 = rs.getDate(9). " + d). pStmt. " + d3).setTimestamp(7.getFloat(6).println("C7 System.98).out.Time d2 = rs. " + i).getString(1).sql. 8-10 Connecting to SQLBase ."Sushi").31) { String s1 = rs.executeQuery("select C1. Time z = Time. pStmt. " + f).

.... also illustrates the use of bind variables within SQL queries. a SQLException will be thrown when the CallableStatement. column lengths and other information about the result data. for datatypes. since SQLBase Stored Procedures do not support any OUT parameters. } syntax. the CallableStatement. However. } syntax. To prepare for this test you need to do some work on the database..setXXX() methods can be called to pass Java data types from the caller to the stored procedure as bind data.registerOutParameter(. The example source code above.) method is called. \'Gupta\')') Connecting to SQLBase 8-11 . First.C2 char(10)) in database ISLAND.. Stored procedure support The SQLBase JDBC Driver supports the CallableStatement { call ?. Stored procedure example This program does an insert on execution of a procedure. After executing the CallableStatement... Second. To provide input parameters. SQLBase stored procedures return the result via a ResultSet. ResultSetMetaData is also helpful in determining the column types. This restriction also invalidates the [? =] portion of the { [? =] call ?. you need to store the following procedure .. The driver attempts to parse the '?' from the input SQL statement. STORE JAVA_PROC_1 PROCEDURE: JAVA_PROC_1 PARAMETERS Number: x ACTIONS On Procedure Execute Call SqlImmediate('insert into foo values(:x.Bind variable support } } } Bind variable support The SQLBase JDBC Driver supports the bind variable escape character '?' in a SQL statement. a getResult() method can be called to retrieve result data. 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.. you need to make sure there is a table named FOO (C1 int.

ResultSet r = s.close().C2 FROM FOO").util. you can drop FOO and ERASE JAVA_PROC_1 . String str = r.executeQuery("SELECT C1. while (r.gupta. if ( args. CallableStatement cstmt = con. cstmt.SqlbaseDriver").length() > 0) { url = args[0]. } // ENDIF Get Connection URL Connection con = DriverManager.createStatement().getConnection(url.*. } cstmt.Chapter 8 Introduction to the JDBC driver When you are done. import java.setInt(1.sqlbase.close(). import java. s. con. "SYSADM").out. the example program.*.45).executeUpdate(). "SYSADM". System. public class Proc { private static String url ISLAND".forName(""{call Java_Proc_1}").getString(2).out.println("\nException in main: " + ex + "\n").commit(). import java.length > 0 && args[0].out. } } } 8-12 Connecting to SQLBase .println("C1: " + i + " C2: " + str).next()) { int i = r. // Is it there? Statement s = con. = "jdbc:sqlbase://localhost:2155/ public static void main (String args[]) { try { Class.println("Unable to access or execute procedure Java_Proc_1").close(). System. cstmt.*. } catch (Exception ex) { System.getInt(1).

.createStatement().setCursorName("C2"). while ( package is critical to applets.executeQuery("SELECT C1.sql. 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.createStatement().setTransactionIsolation(Statement stmt2 = con1. con1.getInt(1). any library that is not part of the JVM cannot use the java.TRANSACTION_REPEATABLE_READ).next()) { int k = rs. The cursor name can then be used by other Statement or PreparedStatement objects with the WHERE CURRENT OF clause in SQL statements. "SYSADM"). Statement stmt2 = con1.Named Cursor Support Named Cursor Support Cursor naming is supported by the SQLBase JDBC Driver. error will result in "class not found" exception being thrown by the SecurityManager. Connecting to SQLBase 8-13 . Application and Applet Development Java Virtual Machine reserves the java. Error Message Support This release provides a simplified version of error message text from error.sqlbase. String s = rs. if (k == 2) executeUpdate(stmt1. reason and remedy are not supported. "SYSADM". However.crea Connection. Loading a library from unrecognized java. in order to keep the memory consumption down and the SQLBase JDBC package. Generally. Connection con1 = DriverManager. The* package. ResultSet rs = stmt2.getConnection( package for its own libraries. Cursor names are generally used in conjunction with the WHERE CURRENT OF clause of an UPDATE or DELETE statement. To avoid this problem.C2 FROM FOO FOR UPDATE OF C1"). the SQLBase JDBC Driver is normally packaged under the jdbc. "UPDATE FOO SET C1 = 200 WHERE CURRENT OF C2"). Statement stmt1 = con1.gupta. stmt2.getString(2).xxx. .

However. SQLBase does not support file in the samples directory for more information on how to connect to non-US databases. 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. If network check is set in the SQL. Network Check Network check (netcheck) is not implemented in the SQLBase JDBC Driver." message. 8-14 Connecting to SQLBase .INI file for the SQLBase server. Encrypted Databases Applications using the JDBC Driver cannot connect to encrypted SQLBase databases.x line of the SQLBase JDBC Driver. in this case the host-of-origin. the warning processing using SQLWarning is implemented in the SQLBase JDBC Driver for trapping potential problems generated during data conversion. Where this occurs.html file must be copied to the WWW root directory or the <HOME> directory of the system where the SQLBase JDBC Driver is installed.. directly relevant nor necessarily supportable by SQLBase.not supported. DBCS databases are also supported in this release. SQLWarning Support In general..1. SQLException will be thrown with the ". Restrictions All of the documented JDBC API is included in this release.. Certain functionality of the API is neither completely supported.Chapter 8 Introduction to the JDBC driver If you encounter problems during execution of the sample Java programs. Please refer to the file CountrySetting. the JDBC driver may not be able to communicate with the server. the error.. NLS and DBCS Databases The JDBC Driver supports non-US databases.

BSTR A pointer to a null-terminated character string in which the string length is stored with the string. Buffer A piece of memory used to pass information. See also reference accessor. B Binary large object (BLOB) Any binary or character data over a certain number of bytes. Accessor A collection of information that describes how data is stored in the consumer's buffer. Also known as long data. B-tree A tree structure for storing database indexes. Typically much longer. usually data. Binding As a verb. Connecting to SQLBase -1 . Such data is generally sent to and retrieved from the data source in parts. Bookmark A value that identifies a row in a rowset. such as 255.Glossary Connecting to SQLBase A Abort To return the values changed by a transaction to their original state. Bookmarks are saved by the consumer and used later in the life of the rowset to retrieve a particular row. the act of associating a column in a rowset or a parameter in a text command with a consumer variable. Auto-commit mode A transaction commit mode in which all actions taken in a transaction are committed immediately after they are performed. As a noun. the association or the DBBINDING structure that describes the association. between the consumer and provider. The provider uses this information to determine how to transfer data to and from this buffer. Accessor handle A handle that identifies an accessor.

which specifies the object's data and one or more implementations of interfaces on the object. Command An OLE DB object that encapsulates a command. Concurrency The ability of more than one transaction to access the same data at the same time. The clients generally implement the user interface while the server controls database access. See also interface. Container A file containing linked or embedded objects. Consumer Software that calls OLE DB methods and interfaces. Commit To make the changes in a transaction permanent. primarily in a command where there are no stable ordinals or column names. clients have access to an object through interfaces implemented on the object. Every OLE server or container that allows linking to its embedded objects must register a CLSID for each supported object definition. and provides a wellspecified set of publicly available services. If a class object will be used to create more than one instance of an object. Clients interact with a COM object only through its interfaces. Class ID A globally unique identifier (GUID) associated with an OLE class object. delete. COM object An object that conforms to the OLE Component Object Model (COM). -2 Connecting to SQLBase . this is usually an SQL statement. Change To update. Although it is not required to be. Client/server A database access strategy in which one or more clients access data through a server. In COM. See also Component Object Model and interface. Convert To change data from one type to another. 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). Also known as field. or insert a row of data. A COM object is an instance of an object definition. Component Object Model (COM) The OLE object-oriented programming model that defines how objects interact within a single process or between processes. Component An object that encapsulates both data and code. Column The container for a single item of information in a row. such as from an integer to a string. Command text The text command associated with a command object. Column ID A structure used to identify a column.Glossary C Catalog A database object that contains one or more schemas.

or array. See also type indicator. CoType A way to define a group of COM objects. Data source object An OLE DB object that connects to a data source. the length of the data value. Database Management System (DBMS) A layer of software between the physical database and the user. All of the subordinate transactions must succeed for the coordinated transaction to succeed. CREATE INDEX. Database A discrete collection of data in a DBMS. as opposed to manipulate. All COM objects that belong to a particular CoType must expose the mandatory interfaces in that CoType. 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. Connecting to SQLBase -3 . DELETE. For example. subordinate transactions. See also immediate update mode. GRANT. Data type The type of a piece of data. Also known as a distributed transaction. For example. Deferred column A column for which the data is not instantiated in the rowset until the consumer actually attempts to access that data. Data source The data the user wants to access. and REVOKE. data. file. Data provider A provider that directly exposes data. In addition. This is distinct from a data source object. data. they can expose the optional interfaces in the CoType and any interfaces not in the CoType. such as the data in a database. An OLE DB provider can be built directly on top of a DBMS or as a layer between the DBMS and the consumer.Coordinated transaction A transaction composed of multiple. Also a DBMS. such as rowsets or commands. the SQL statements CREATE TABLE. This is distinct from the data source. The DBMS manages all access to the database. UPDATE. and SELECT. the SQL statements INSERT. that have similar characteristics. D Data The data for a parameter in a text command or a column in a row. Data Manipulation Language (DML) Those text commands that manipulate. as opposed to define. as opposed to a service component. and the status of the data value. Delete To remove an existing row of data from the data source. Data Definition Language (DDL) Those text commands that define. Data part Data has three parts: the data value.

regardless of whether it is fatal. that begins with E_ or DB_E_ and indicates that the method failed completely and was unable to do any useful work.Glossary Distributed transaction See coordinated transaction. Error object An object that contains detailed information about an error. 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. of the type HRESULT. See also variable-length data type. Fixed-length data type A data type that is always stored in the same number of bytes. such as changing a column value or deleting a row. Foreign key A column or columns in a table that match the primary key in another table. E Empty string A zero-length string. Also used to refer to any error. Field See column. Error code A class of return code. Dynamic error An error message that cannot be predicted because it is not provider specific. See also OLE Automation error object and OLE DB error object. See also root enumerator. Error A condition in which a fatal error occurred. See also null pointer and NULL value. Execution plan A plan generated by a query engine to execute a command.Dynamic error ID An identifier that is used by a lookup service and is associated with an error object. Enumerator An OLE DB object that searches for data sources and other enumerators. Endogenous change A change to data originating from a process other than your own. such as a two-byte integer. Error lookup service A method used by a provider to handle and interpret OLE DB error objects. of which the provider notifies the consumer. G -4 Connecting to SQLBase . Event An action taken by a provider.

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. Initialize To change the state of an enumerator or data source object so it can be used to access data.Getting data Transferring data from the provider to the consumer. Index rowset A rowset built over an index. as in getting column or output parameter data. -5 Connecting to SQLBase . but are passed by other software to identify things. initializing a data source object might require the provider to open a data file or connect to a database. Insert To add a new row of data to the data source. Immediate update mode An update mode in which changes made through IRowsetChange are immediately transmitted to the data source. See also delayed update mode. Input parameter A parameter in a text command for which the consumer supplies a value to the provider. Interface A group of semantically related functions that provide access to a COM object. Some functions take IIDs as parameters to allow the caller to specify which interface pointer should be returned. I Interface Identifier (IID) A globally unique identifier (GUID) associated with an interface. Each row in an index rowset contains a bookmark that points to a row in a rowset built over the corresponding table. 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. Each OLE interface defines a contract that allows objects to interact according to the Component Object Model (COM). H Handle A value that uniquely identifies something such as a row or an accessor. most interfaces can also be implemented by developers designing OLE applications. Also known as a UUID (Universally Unique Identifier). Instantiate To create an instance of a COM object. Although OLE provides many interface implementations. 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. Handles are meaningful only to the software that creates and uses them. See also Component Object Model and COM object. For example.

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

the IUnknown interface. See also OLE DB error object. a COM object. sample code. 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 NULL value is different from a zero or a blank. rowsets. OLE DB error objects are an extension of Automation error objects. OLE Automation error object An error object that conforms to the standards specified for such objects by OLE Automation. a COM object that is stored in a column. It is an error to dereference a null pointer. See also Component Object Model and interface. Numeric bookmark A bookmark that uses a unique number to identify a row. tools. Connecting to SQLBase -7 . In particular. in which the provider notifies the consumer that a particular event is occurring. Null pointer A pointer with a value of zero. OLE DB A set of interfaces that expose data from a variety of data sources using COM.Notification A call from a provider to a consumer. OLE object In OLE DB. commands. A COM object must support. header files. ODBC Microsoft’s earliest standard for OLE Microsoft's object-based technology for sharing information and services across process and machine boundaries. See also key value bookmark. transaction objects. Notification sink An actual object that implements the notification interface. which maintains the object's existence while it is being used and provides access to the object's other interfaces. OLE DB error objects. NULL value Having no explicitly assigned value. OLE DB Software Development Kit (SDK) A collection of redistributable software. at a minimum. sessions. In OLE. See also empty string and null pointer. data source objects. O Object In OLE. OLE DB object A COM object defined by OLE DB. and transaction options objects. See also empty string and NULL value. and documentation to be used by developers of OLE DB consumers and providers. The COM objects defined by OLE DB are enumerators. OLE DB error object An error object used by OLE DB objects to return an error. multiple results objects.

input/output. If so. Output parameter A parameter in a text command for which the provider returns a value to the consumer. Property group The set of all properties that apply to a particular OLE DB object. See also maximum precision. a rowset checks to see if they have been changed since they were last read. such as to a file. Persist To save the current state of a COM object. Pessimistic concurrency A strategy for implementing serializability in which rows are locked so that other transactions cannot change them. -8 Connecting to SQLBase . Precision The number of base 10 digits in a number. Instead. or output parameter. before they are updated or deleted. See also standard bookmark. Phase A step in a sequence of notifications caused by a single event. See also delayed update mode and immediate update mode. The sequence of notifications is similar to the phases in a two-phase commit protocol. An execution plan is created by preparing a command. Prepare To compile a command. See also optimistic concurrency. Pending change A change that has been cached in a rowset and not yet transmitted to the data source. Procedure A group of one or more precompiled commands (generally SQL statements) that are stored as a named object in a database. A property set is the set of all properties that share the same GUID.Glossary Optimistic concurrency A strategy to increase concurrency in which rows are not locked. Currently. Property set A property is identified by a GUID and an integer (the property ID). For example. the update or delete fails. Preserved rowset A rowset in which all previously defined functionality is retained after a commit or abort. Property Attributes of an OLE DB object. Primary key A column or columns that uniquely identifies a row in a table. only data source objects can be persisted. Ordinary bookmark A bookmark whose value is defined by the provider. Parameter A variable in a text command. A parameter can be an input. See also pessimistic concurrency. P Parallel processing A method of processing that can run only on a computer that contains two or more processors running simultaneously. the maximum number of rows in a rowset that can be active at one time.

Q Query A text command. such as changing a row value or deleting a row. S Scale The number of digits in a number that are to the right of the decimal point. 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. Schema rowset A predefined rowset that provides information about the structure of a database. R Reason The specific event that occurred. often created by a single user. See also multiple results object. or COM object.Provider Software that implements OLE DB methods and interfaces. rows and accessors are also reference counted. 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. Also known as a record. Support for reference accessors is optional. Rowset An OLE DB object that contains a set of rows. Result A row count or rowset created by executing a command. each of which has columns of data. Schema A database object that contains one or more tables. Release To decrease the reference count on a row. or COM object. When the reference count reaches zero. Reference accessor An accessor that enables a consumer to get rowset data directly from the provider's buffer. See also enumerator. Sometimes used to mean a text command that creates a rowset. Root enumerator An enumerator shipped in the OLE DB SDK that enumerates the data sources and enumerators listed in the registry. In OLE DB. Row handle A handle used to identify a row. accessor. Record See row. Return code The value returned by an OLE DB method. the provider generally releases the resources used by the row. accessor. Connecting to SQLBase -9 . Row A set of related columns that describe a specific entity.

and length. that begins with S_ or DB_S_ and indicates success of the method. See also data part. See also ordinary bookmark. Status The status of a data value. Transaction An atomic unit of work. and manage data. Text command A text string. that is used to return to that row. Success A condition in which no errors occurred. usually an SQL statement. Service component A provider that does not directly expose data. Text commands often use SQL. Transaction object An OLE DB object used to support transactions. IStream. value. that defines a command. stored in column 0 of a row. Setting data Transferring data from the consumer to the provider.Glossary Self bookmark A bookmark. Storage objects are used to access BLOB data and OLE objects stored in a column. Static error An error (text) that is stored by a specific provider lookup service. -10 Connecting to SQLBase . SQL Structured Query Language. Serializability Whether two transactions executing simultaneously produce a result that is the same as the serial (or sequential) execution of those transactions. Storage interface An interface used to access data in a storage object: ISequentialStream. and most commomly tied to a single data store. as in setting column or input parameter data. Success code A class of return code. update. Standard bookmark A bookmark whose value is defined by OLE DB. the entire transaction fails. such as query processing. IStorage. T Table A collection of rows in the data source. Storage object A COM object that implements a storage interface. Transaction isolation The act of isolating one transaction from the effects of all other transactions. but instead provides a service. Session An OLE DB object that serves as the context for a transaction. Used in conjunction with data providers. Serializable transactions are required to maintain database integrity. A language used by relational databases to query. The work in a transaction must be completed as a whole. or ILockBytes. Transaction isolation level A measure of how well a transaction is isolated. of the type HRESULT. if any part of the transaction fails.

uninitializing a data source object might require the provider to close a data file or disconnect from a database. For example. See also delayed update mode and immediate update mode. Transfer To move data between the consumer's and provider's buffers. such as a string. length. See also pending change. V Value A data value. Truncate To discard one or more bytes of variable-length data or non-significant digits of numeric data. Type indicator An integer value passed to or returned from an OLE DB method to indicate the data type of a consumer variable. Refers both to the visibility of data in a data source and data cached in a rowset. which is a generally a person. U Uninitialize To change the state of an enumerator or data source object so it cannot be used to access data. User The end user. See also fixed-length data type. that begins with S_ or DB_S_ and indicates success of the method but with a warning. transfers data. See also getting data and setting data. or a column. Warning code A class of return code.Transaction options object An OLE DB object used to define various options for a transaction. Also. as opposed to the consumer. Z Connecting to SQLBase -11 . Variable-length data type A data type for which the length of the data can vary. of the type HRESULT. Truncation results in a warning condition when getting data and an error condition when setting data. Visibility Whether data values can be detected by a rowset. The provider. Unprepare To discard the current execution plan. W Warning A condition in which a nonfatal error occurred. a parameter. See also data part. Transmitted change A change that has been sent to the data source. to transmit pending changes to the data source. Update To change an existing row of data in the data source. which is a piece of software. and status. Transmit To send changes made through IRowsetChange to the data source. not the consumer.

Glossary Zombie A state in which the only valid consumer action on a COM object is generally to release that object. -12 Connecting to SQLBase .

4-10 BOF 4-13 E EOF 4-13 error COM object 5-2 interfaces 5-9 routine 4-15 trapping 4-14 error object 4-8. 4-12 escape character 8-11 C++ 4-8 caching 4-7 CLASSPATH 8-2 closing 4-15 collections 4-9. 6-4 Errors collection 4-11.NET exceptions 7-16 transactions 7-16 ConnectionString property 7-6 Connectivity Administrator 1-2 Crystal Reports 4-4 cursor object 4-8 cursors 4-7 A ActiveX Data Objects 4-3 ADO 4-3. 4-10 IsNull 4-13 J Java 4-7 SQLBase OLE DB Data Provider User’s Guide -1 .exe 4-11 DBPROP_INIT_PROVIDERSTRING 5-3 DeleteCommand property 7-13 Delphi 4-4 disconnect 4-15 Dynamic Properties 4-9 B C batch updates 4-7. 4-6 coding sample 4-12 adoid.Index Symbols . 6-3 CommandText 7-9 CommandText property 7-9 CommandType property 7-9 Component Object Model 4-2 configuring the provider 4-4 connecting 4-10 using ADO 4-11 Connection 7-8 connection lifetime 7-6 connection object 4-8.h 4-8 adoint. 6-5 H header file 4-10 hierarchy 4-8 I IEnumerable 7-10 IEnumerator 7-10 InsertCommand property 7-13 iODBC 2-9 ISLAND sample database 4-9. 4-14 COM object 5-2 interfaces 5-3 DBExplore. 6-2 COM 4-2 cotypes 5-2 objects 5-1 COM+ 1-9 command COM object 5-2 interfaces 5-6 command object 4-8. 6-3 Connection pooling 7-8 connection pooling 2-7 connection string 7-8 F fetch 4-13 field object 4-8.h 4-8 4-8 Advanced Data Connector 4-7 apartment-model 4-8 applet 8-13 application developers 1-10 D Data Access Objects 4-7 data consumer 4-2 data provider 4-2 data source 4-8. 4-10 adovbs.

4-14 PHP 3-3 poolsize 7-6 PowerBuilder 4-4 previous record 4-16 program ID 4-7 properties 4-8.ini 2-9 Open DataBase Connectivity see ODBC -2 SQLBase OLE DB Data Provider User’s Guide . 4-10 L last record 4-16 libraries ADO 4-7 Linux 2-9 Long Binary 4-11 Long text fields 4-11 parameter object 4-8.ini 2-9 odbcinst 2-9 odbcinst. 4-9 provider string 4-14 P R reading 4-2 Recordset object 4-9 recordset object 4-8.Index Java Development Kit 8-2 Java Type Library Wizard 4-7 Java Virtual Machine 8-13 JDBC 8-1 bind variables 8-11 data types 8-6 isolation levels 8-4 JScript 4-8. 6-6 password 4-4. 6-2 Properties collections 4-10 property object 4-8 provider name 4-4. 6-2 Microsoft Visual J++ 4-7 MTS 1-9 N named cursor 8-13 navigation 4-14 NULL values 4-13 S sample applications 4-10 schema 4-11 Scripting code 4-10 scrollable 4-10 scrolling result sets 7-10 SelectCommand property 7-13 session COM object 5-2 interfaces 5-5 simplefetch 4-10.INI 1-2 SQL/API functions 4-2 SQLBaseCommand Cancel 7-9 GetSQLBaseParameter 7-9 SetSQLBaseParameter 7-9 SQLBaseCommand object 7-8 SQLBaseConnection 7-6 BeginTransaction 7-6 ChangeDatabase 7-7 Close 7-7 CreateCommand 7-7 O objects ADO 4-8 ODB data types 2-7 ODBC 2-1 see Chapter 10 Conformance 2-4 connection string 3-1 data source properties 2-8 driver 2-2 driver manager 2-2 isolation 2-4 overview 2-2 supported functions 2-5 ODBC API 4-2 odbc. 4-12 SQL. 6-7 Remote Data Objects 4-7 Remote Data Service 4-7 RowPos 7-10 rowset COM object 5-2 interfaces 5-8 M methods 4-8.

GetSQLBaseSchemaTable 7-7 Open 7-8 SQLBaseDataAdapter object 7-13 SQLBaseDataReader Get methods 7-10 Get methods for long (BLOB) data 7-11 GetDataTypeName 7-11 GetFieldType 7-11 GetName 7-12 GetOrdinal 7-12 GetValues 7-12 IsDbNull 7-12 NextResult 7-12 SQLBaseDataReader object 7-10 SQLBaseParameter object 7-14 SQLBaseParameters Add 7-15 SQLBaseParameters object 7-15 SQLBaseSchemaGuid 7-7 SQLBaseTransaction Commit 7-14 Rollback 7-14 SQLBaseTransaction object 7-14 stored procedure 8-11 stored procedures 4-7 Supported ODBC Functions 2-5 T TCP/IP 1-9 TextBox objects 4-13 Threading 4-8 Transaction Model 8-4 transaction state 7-16 U Universal Data Access 4-2 unixODBC 2-9 update 4-15 UpdateCommand property 7-13 V VBScript 4-8 Visual Basic 4-4 W Web sites 4-6 SQLBase OLE DB Data Provider User’s Guide -3 .

Index -4 SQLBase OLE DB Data Provider User’s Guide .