Copyright: © 1993, 1996
Citation: © 1993, 1996, Oracle Corporation. All rights reserved.


Contents

For Help on Help, Press [F1].

The following Help topics are available:

ORACLE ODBC DRIVER FOR RDB

New Features for Version 2.1

POST-INSTALLATION INFORMATION

Post-Installation Instructions

Configuring Data Sources

Files Created by the Installation

INTRODUCTION TO THE ORACLE ODBC DRIVER FOR RDB

What Is ODBC?

The Oracle ODBC Driver for Rdb As Part of Your System

Standards Conformance

Configuring the Data Source

Reducing Connection Time

Modifying the rdbodbc.ini or win.ini File

Client and Driver Logging

Enabling Oracle SQL/Services Client Logging

Enabling Oracle ODBC Driver for Rdb Logging

Reducing Lock Timeout

Enabling the "Fetch Ahead" Feature

Removing Control Characters from SQL Statements

Increasing the Network Buffer Size

Enabling the "Proxy Access" Feature

Common Problems

Using the Oracle ODBC Driver for Rdb for the First Time

Attaching to a Database

Error Messages

PROGRAMING CONSIDERATIONS

Format of the Connection String

Enabling Oracle SQL/Services Client Logging in a Program

Reducing Lock Timeout in a Program

Linking with odbc.lib

Using Oracle Rdb Lists

Using rowids or dbkeys

Obtaining Information About rowids or dbkeys

INSERT Statements that Return rowids or dbkeys

rowids or dbkeys in a WHERE Clause

Improving Concurrency and Performance

SQLColumns Function

Supported Functionality

API Conformance

SQL Grammar Extensions

Oracle ODBC Driver for Rdb Features

SQL Identifiers

Names and Version Numbers

Scalar Functions

Transaction Support

Mapping of SQL Data Types to ODBC Data Types

Mapping of ODBC Data Types to SQL Data Types

Transparent Access to Oracle Rdb Lists (Blobs)

ORACLE SQL/SERVICES ERRORS

-2000,SQLSRV_INVARG

-2001,SQLSRV_INVBUFSIZ

-2003,SQLSRV_NETERR

-2005,SQLSRV_INVASC

-2006,SQLSRV_INVSQLDA

-2007,SQLSRV_PRSERR

-2008,SQLSRV_INVSTMID

-2009,SQLSRV_INVCURNAM

-2011,SQLSRV_INTERR

-2012,SQLSRV_OPNLOGFIL

-2013,SQLSRV_NO_MEM

-2014,SQLSRV_INVSQLCA

-2015,SQLSRV_SQLDA_NOTALL

-2016,SQLSRV_MULTI_ACT

-2019,SQLSRV_INVEXEFLG

-2021,SQLSRV_INVASCSTR

-2025,SQLSRV_DUPCRSNAM

-2026,SQLSRV_INVCOLNUM

-2027,SQLSRV_INVDATTYP

-2028,SQLSRV_INCDATTYP

-2029,SQLSRV_USRDATALL

-2030,SQLSRV_ACTSTM

-2031,SQLSRV_APINOTSUP

-2032,SQLSRV_INV_CLS

-2033,SQLSRV_NO_PRCAVL

-2034,SQLSRV_GETACCINF

-2035,SQLSRV_EXEINTERR

-2036,SQLSRV_HOSTERR

-2037,SQLSRV_XPT_MISSING

-2042,SQLSRV_SRVNOTSUP

-2043,SQLSRV_INVSETLEN

-2044,SQLSRV_INVSQLLEN

-2045,SQLSRV_DLL_LOAD_ERR

-2046,SQLSRV_DLL_ADDR_ERR

-2048,SQLSRV_INVSELLST

-2049,SQLSRV_PWD_EXPIRED

-2050,SQLSRV_CONNTIMEOUT

-2051,SQLSRV_SVCNOTRUN

-2052,SQLSRV_SVC_SHUTDOWN

-2053,SQLSRV_TOOMANYCONNECTS

-2054,SQLSRV_SQLNET_BADINIT

-2055,SQLSRV_SQLNET_BADSERVICE

-2056,SQLSRV_SQLNET_BADCONNECT

-2057,SQLSRV_FTCMNYACT

-2058,SQLSRV_DATA_TOO_LONG

SAMPLE FILES

Include File for ODBC Options

File to Store Data As Lists Using List Cursors

File to Retrieve Lists Using Lists Cursors

COPYRIGHT AND TRADEMARK ACKNOWLEDGMENTS


ORACLE ODBC DRIVER FOR RDB

The Oracle ODBC Driver for Rdb allows ODBC MS Windows, Windows NT X86, and Windows NT Alpha applications read and write access to Oracle Rdb databases using TCP/IP, DECnet, SQL*Net, or IPX/SPX (for 16-bit applications only) transport. The Oracle ODBC Driver for Rdb uses the Oracle SQL/Services software to access the data. The following topics are described:

New features for Version 2.1 of the Oracle ODBC Driver for Rdb

Post-Installation Information

Introduction to the Oracle ODBC Driver for Rdb

Programming considerations

Oracle SQL/Services errors

Sample files

Copyright and trademark acknowledgements

Table of Contents view of this help file


New Features for V2.1
New Features for Version 2.1

New features for Oracle ODBC Driver for Rdb Version 2.1 software for the MS Windows, Windows 95, Windows NT X86, and Windows NT Alpha operating systems are described as follows:

A. Support for Oracle Rdb Hold Cursors

Support is added for Oracle Rdb Hold Cursors.

B. Support for Microsoft ODBC Version 2.10 Driver Manager and Utilities

The 16-bit Oracle ODBC Driver for Rdb kit contains the Microsoft ODBC Version 2.10 Driver Manager and utilities.

C. Support for Microsoft ODBC Version 2.5 Driver Manager and Utilities

The 32-bit Oracle ODBC Driver for Rdb kit contains the Microsoft ODBC Version 3.0 Driver Manager and utilities, but only supports the Microsoft ODBC Version 2.5 Driver Manager and Utilities.

D. Support for Oracle SQL*Net Transport

Support is added for Oracle SQL*Net transport.

E. Support for Proxy Access=2

To enable the "proxy access" feature but return an error message if the connection fails, change the proxy access value to 2 in the rdbodbc.ini or win.ini file.

F. Support for Windows 95

An Oracle ODBC Driver for Rdb for Windows 95 client is available for DECnet and TCP/IP transports.

G. Support for PATHWORKS 32 V7.0A (DECnet) on Windows 95 and Windows NT

The Oracle ODBC Driver for Rdb supports PATHWORKS 32 V7.0A (DECnet) on Windows 95 and Windows NT.


Installation Information
POST-INSTALLATION INFORMATION

The following post-installation information is described:

Post-installation instructions

Configuring the data sources

Files created by the installation


Post-Installation Instructions
Post-Installation Instructions for Conversion

If you are upgrading from the DEC ODBC Driver to the Oracle ODBC Driver for Rdb, the following cleanup operations can be performed:

For the Microsoft Windows V3.1 (16-Bit Driver)

Delete the following obsolete files:

odbcadm.exe

sqrdb.txt

sqrdbnet.txt

The installation prompts for this directory specification so it may be different on your system. The default is your_install_drive:\DECODBC (i.e. C:\DECODBC).

For the Microsoft Windows NT X86 Operating System (32-Bit Driver)

Remove the DEC ODBC Driver Group from the Program Manager using the following procedure:

1.	Close the DEC ODBC Driver window and return to the DEC ODBC Driver icon.

2.	Highlight the DEC ODBC Driver group.

3.	Pull down the File menu.

4.	Delete the DEC ODBC Driver group.

5.	A delete message dialog box appears.

6.	Click on Yes to delete the DEC ODBC Driver group.

Delete the following obsolete files:

odbcad32.exe

sqrdb.txt

sqrdbnet.txt

The installation prompts for this directory specification so it may be different on your system. The default is your_install_drive:\DECODBC (i.e. C:\DECODBC).

Remove the DEC ODBC Driver using the following procedure:

1.	Double click on the 32-bit ODBC Administrator.

2.	Click on Drivers.

3.	Delete the DEC ODBC Driver.

4.	A Microsoft ODBC Administrator message dialog box appears.

5.	Click on Yes to delete the DEC ODBC Driver.

For the Microsoft Windows NT Alpha Operating System (32-Bit Driver)

Remove the DEC ODBC Driver Group from the Program Manager using the following procedure:

1.	Close the DEC ODBC Driver window and return to the DEC ODBC Driver icon.

2.	Highlight the DEC ODBC Driver group.

3.	Pull down the File menu.

4.	Delete the DEC ODBC Driver group.

5.	A delete message dialog box appears.

6.	Click on Yes to delete the DEC ODBC Driver group.

Remove the DEC ODBC Driver using the following procedure:

1.	Double click on the 32-bit ODBC Administrator.

2.	Click on Drivers.

3.	Delete the DEC ODBC Driver.

4.	A Microsoft ODBC Administrator message dialog box appears.

5.	Click on Yes to delete the DEC ODBC Driver.

Post-Installation Instructions for V2.1

For the Microsoft Windows V3.1 (16-Bit Driver)

Delete the following obsolete file and its icon within the group:

sqrdbnet.txt

The installation prompts for this directory specification so it may be different on your system. The default is your_install_drive:\RDBODBC (i.e. C:\RDBODBC).

To delete the icon in the program group Oracle ODBC Driver for Rdb (the word "for" may be omitted), do the following:

1. Click on the icon name Oracle ODBC Driver Rdb Net Readme. (The word "Rdb" may be omitted.

2. Pull down the file menu.

3. Delete Oracle Driver Rdb Net Readme Icon.

4. A delete message dialog box appears.

5. Click on Yes to delete the Oracle Driver Rdb Net Readme Icon.

For the Microsoft Windows NT X86 Operating System (32-Bit Driver)

Delete the following obsolete file and its icon within the group (refer to the instructions described previously on how to delete the Oracle Driver Rdb Net Readme Icon):

sqrdbnet.txt

The installation prompts for this directory specification so it may be different on your system. The default is your_install_drive:\RDBODBC (i.e. C:\RDBODBC).

For the Microsoft Windows NT Alpha Operating System (32-Bit Driver)

Delete the following obsolete file and its icon within the group (refer to the instructions described previously on how to delete the Oracle Driver Rdb Net Readme Icon):

sqrdbnet.txt


Configuring Data Sources

After installing the Oracle ODBC Driver for Rdb, and before using it, you must configure the data source. For instructions, refer to the Configuring the Data Source topic.


Files Created by the Installation

16-bit Oracle ODBC Driver for Rdb Kit

The following files are installed by the 16-bit Oracle ODBC Driver for Rdb kit:

Oracle ODBC Driver for Rdb files:

File Name	Description
sqsapiw.dll	Oracle SQL/Services Dynamic Link Library (DLL) for Windows
sqrdbs.dll	Oracle ODBC Driver for Rdb setup Dynamic Link Library (DLL)
sqrdb.dll	Oracle ODBC Driver for Rdb Dynamic Link Library (DLL)
sqsapiw.ini	Oracle SQL/Services initialization file
sqrdb.txt	Oracle ODBC Driver for Rdb release notes
sqrdb.hlp	Oracle ODBC Driver for Rdb MS Windows and Windows 95 help file
odbctst.exe	Oracle ODBC Test Utility
Microsoft Driver Manager and ODBC Administrator files:

File Name	Description
odbcinst.dll	Microsoft ODBC Installer Dynamic Link Library (DLL)
odbc.dll	Microsoft ODBC Dynamic Link Library (DLL) (Driver Manager)
odbccurs.dll	Microsoft ODBC Cursor DLL
odbcadm.exe	Microsoft ODBC Administrator executable image
odbcinst.ini	Microsoft ODBC Installer INI file
odbc.ini	Microsoft ODBC Administrator INI file
odbcinst.hlp	Microsoft ODBC Installer help file
odbc32.dll	32-bit thunking Driver Manager
odbc16ut.dll	16-bit ODBC universal thunking DLL
odbccp32.dll	32-bit thunking installer DLL
cpn16ut.dll	16-bit installer universal thunking DLL
ctl3dv2.dll	16-bit three-dimensional window style library
Novell NetWare files:

File Name	Description
nwipxspx.dll	Novell Dynamic Link Library (DLL) from the NetWare C Interface SDK
nwnetapi.dll	Novell Dynamic Link Library (DLL) from the NetWare C Interface SDK
32-bit Oracle ODBC Driver for Rdb Kit

The following files are installed by the 32-bit Oracle ODBC Driver for Rdb kit:

Oracle ODBC Driver for Rdb files:

File Name	Description
sqsapi32.dll	Oracle SQL/Services Dynamic Link Library (DLL) for Windows NT
sqrdbs32.dll	Oracle ODBC Driver for Rdb setup Dynamic Link Library (DLL)
sqrdb32.dll	Oracle ODBC Driver for Rdb Dynamic Link Library (DLL)
sqsapi32.ini	Oracle SQL/Services initialization file
rdbodbc.ini	Oracle ODBC Driver for Rdb initialization file
sqrdb.txt	Oracle ODBC Driver for Rdb release notes
sqrdb.hlp	Oracle ODBC Driver for Rdb Windows 95, Windows NT X86, and Windows NT Alpha help file
odbctst.exe	Oracle ODBC Test Utility (not available for Windows NT Alpha)
Microsoft Driver Manager and ODBC Administrator files:

File Name	Description
odbccp32.dll	Microsoft ODBC Installer Dynamic Link Library (DLL)
odbc32.dll	Microsoft ODBC Dynamic Link Library (DLL) (Driver Manager)
odbccr32.dll	Microsoft ODBC Cursor DLL
odbcad32.exe	Microsoft ODBC Administrator executable image
odbcinst.dll	Microsoft ODBC Installer Dynamic Link Library (DLL)
odbc.dll	Microsoft ODBC Dynamic Link Library (DLL) (Driver Manager)
odbcinst.hlp	Microsoft ODBC Installer help file
odbc16gt.dll	16-bit ODBC generic thunking DLL
odbc32gt.dll	32-bit ODBC generic thunking DLL
ds16gt.dll	16-bit driver setup generic thunking DLL
ds32gt.dll	32-bit driver setup generic thunking DLL
ctl3d32.dll	32-bit three-dimensional windows style library


INTRODUCTION TO THE Oracle ODBC DRIVER FOR RDB

The Oracle ODBC Driver for Rdb allows ODBC MS Windows, Windows 95, Windows NT X86, and Windows NT Alpha applications read and write access to Oracle Rdb databases using TCP/IP, DECnet, SQL*Net (MS Windows applications only), or IPX/SPX (MS Windows applications only) transport. The Oracle ODBC driver for Rdb uses the Oracle SQL/Services software to access the data.

This topic provides an overview of the ODBC model and the Oracle ODBC Driver for Rdb, and provides information useful to application developers and application users.  Topics include:

What is ODBC?

The Oracle ODBC Driver for Rdb as part of your system

Standards conformance

Configuring the data source

Reducing connection time

Modifying the rdbodbc.ini or win.ini file

Common problems

Error messages


What Is ODBC?

Open Database Connectivity (ODBC) provides a standard interface that allows one application to access many different data sources. The application's source code does not have to be recompiled for each data source. A database driver links the application to a specific data source. A database driver is a dynamic-link library that an application can invoke on demand to gain access to a particular data source. Therefore, the application can access any data source for which a database driver exists.

The ODBC interface defines the following:

•	A library of ODBC function calls that allows an application to connect to a data source, execute SQL statements, and retrieve results

•	SQL syntax based on the X/Open and SQL Access Group (SAG) SQL CASE specification (1992)

•	A standard set of error codes

•	A standard way to connect to and log in to a data source

•	A standard representation for data types

This figure describes the components of the ODBC model.


The ODBC Model


ODBC Application

The ODBC application performs processing and calls ODBC functions to submit SQL statements and retrieve results. The application can access multiple data drivers, each of which accesses a different data source.


The Driver Manager
Driver Manager

The Driver Manager, which is provided by Microsoft, loads drivers on behalf of an application when the application calls the ODBC SQLConnect or ODBC SQLDriverConnect functions.


The ODBC Driver
ODBC Driver

An ODBC Driver is a dynamic-link library that applications can invoke on demand to access data. It processes ODBC function calls, submits SQL requests to a specific data source, and returns results to the application. If necessary, the driver modifies an application's request so that the request conforms to syntax supported by the associated data source. The Driver Manager and the driver appear to an application as one unit that processes ODBC function calls.


The Data Source
Data Source

The data source consists of the data that the user wants to access, and its associated operating system, database management system, and the network transport used to access the database management system.


Oracle Rdb

Oracle Rdb is a general purpose, multiuser, database management system based on the relational model. It supports a full set of utilities and an industry-standard SQL data definition and data manipulation language that lets you create, query, and maintain your Oracle Rdb databases.


The Oracle ODBC Driver for Rdb As Part of Your System

The Oracle ODBC Driver for Rdb for MS Windows, Windows NT X86, and Windows NT Alpha operating systems is Oracle's implementation of an ODBC driver. This figure shows the interaction of the Oracle ODBC driver for Rdb with other components.

The Oracle ODBC Driver for Rdb uses the Oracle SQL/Services client and server software to submit requests to and receive responses from the data source. DECnet, Transmission Control Protocol/Internet Protocol (TCP/IP), SQL*Net (MS Windows applications only), or Novell IPX/SPX (MS Windows applications only) communications protocol is used for communications between the Oracle SQL/Services client and Oracle SQL/Services server.

SQL statements are submitted through the dynamic SQL interface to the data source, which is an Oracle Rdb database.

The Oracle ODBC Driver for Rdb translates ODBC SQL syntax into syntax that can be used to access the data source. When the results are returned from the data source, the Oracle ODBC Driver for Rdb translates them back to ODBC SQL syntax.

For more information about the Oracle SQL/Services client and server software, refer to the Oracle SQL/Services documentation.


The Oracle ODBC Driver for Rdb

** MS Windows clients only


Standards Conformance

ODBC defines conformance levels for drivers in two areas: the ODBC application programming interface (API) and the ODBC SQL Grammar.

The Oracle ODBC Driver for Rdb supports Level 1 API functionality, which is an extended set of functionality that includes core functionality. The Core functions correspond to the functions in the X/Open and SQL Access Group Call Level Interface specification.

The Oracle ODBC Driver for Rdb supports Core SQL Grammar functionality, which corresponds to the X/Open and SQL Access Group SQL CAE specification (1992).

Core SQL Grammar includes the following:

•	Data definition language (DDL): ALTER TABLE, CREATE INDEX, CREATE TABLE, CREATE VIEW, DROP INDEX, DROP TABLE, DROP VIEW, GRANT, and REVOKE statements

•	Data manipulation language (DML): positioned DELETE, DELETE SEARCHED, INSERT, full SELECT, simple SELECT, positioned UPDATE, and UPDATE SEARCHED statements

•	Expressions: set functions (such as SUM and MIN), simple (such as A > B + C), and subquery

•	Data types: CHAR, DECIMAL, DOUBLE PRECISION, FLOAT, INTEGER, NUMERIC, REAL, SMALLINT, and VARCHAR

The Oracle ODBC Driver for Rdb also supports the following Extended SQL Grammar data types: BIGINT, DATE, LONGVARCHAR, and TINYINT.

NOTE: Do not use the REAL and TINYINT data types unless you are running Oracle Rdb V5.1 or a higher version of Oracle Rdb.

For more information on supported functions, refer to the Supported Functionality topic.


Configuring the Data Source

Before an application can communicate with the data source, you must provide configuration information. The configuration information informs the Oracle ODBC Driver for Rdb as to which information you want to access.

The data source consists of the data that you want to access, and its associated operating system, database management system, and network platform used to access the database management system. The data source for requests submitted by the Oracle ODBC Driver for Rdb is an Oracle Rdb database or DEC DB Integrator database running on the OpenVMS Alpha, OpenVMS VAX, or Digital UNIX operating system and accessed through DECnet, TCP/IP, SQL*Net, or IPX/SPX (OpenVMS Alpha or OpenVMS VAX only). The data source can also be any Rdb Dristributed Technology Suite (formerly DEC DB Integrator) family of gateway databases, globals, files, or data sets.

After you have installed the Oracle ODBC Driver for Rdb, use the Microsoft ODBC Administrator (which is installed when you install the Oracle ODBC Driver for Rdb) to perform the configuration. Follow these steps:

1.	Double click on the ODBC Administrator icon. A list of installed drivers is displayed.

2.	Click on the Add button in the Data Sources window and then click on the Oracle ODBC Driver for Rdb in the list of installed drivers.

3.	Click on OK. The Oracle ODBC Driver for Rdb Setup dialog box is displayed. You must enter the Data Source Name. You can provide the other information requested in the dialog box, or you can leave the fields blank and provide the information when you run the application.

•	The Data Source Name is the name used to identify the data source to ODBC.

•	The Description field allows you to add a comment about the data source.

•	The Transport is the network transport used to access the database. The transport that you selected as the default transport when you installed the Oracle ODBC Driver for Rdb is displayed. Click on the down arrow to display the names of other available network transports.

•	The Server is the OpenVMS Alpha or OpenVMS VAX node or Digital UNIX host name where the Oracle SQL/Services server that is used to access the data is running.

•	The Service (for the SQL*Net transport only) is either the SQL*Net Service Name or the SQL*Net Alias that is created by the Oracle Network Manager utility.  When you select the SQL*Net transport and specify the service name, the class name field is automatically filled in as "Not Applicable".

•	The Class (for all other supported transports except SQL*Net) is an Oracle SQL/Services class name or service that identifies the class of execute server processes or service name for the Oracle SQL/Services server. GENERIC is the default. Refer to the Oracle SQL/Services documentation for more information about class or service names.

•	The UserID is the OpenVMS Alpha, OpenVMS VAX, or Digital UNIX user name of the account on the server used to access the data.

•	The Attach statement is the SQL ATTACH statement used to access the database.

NOTE: If you are using preattached executors or execute server processes, as described in the Reducing Connection Time topic, do not specify an attach statement if the attach statement is already specified in the Oracle SQL/Services configuration file.

If you are using Oracle Rdb with multischema naming, you must use the ATTACH statement with the MULTISCHEMA IS OFF syntax:

ATTACH 'FILENAME DISK$1:[GERALDO.DB]SUPPLIES MULTISCHEMA IS OFF'

•	DBI Options -- Specify one or more of the following values if the version of Rdb Distributed Technology Suite (formerly DEC DB Integrator and DEC DB Integrator gateway) product can support the associated options. To specify more than one option, enter the sum of the values for the options.

Value	Description
0	None
1	Correlation names are not supported
2	The GROUP BY clause is not supported
4	Unions are supported
8	Outer joins are supported except for nested outer joins
16	Nested outer joins are supported
32	Scalar functions are supported
64	Subqueries are not supported
128	Expressions in the ORDER BY clause are supported
256	Transaction isolation levels are supported
512	Return the Read Only Column attribute for the INTERVAL data type
1024	Stored procedures are supported
2048	The NOT NULL constraint is not supported in the CREATE TABLE statement.
4096	Represent date-time data types as character data types.
•	Read Only -- Check this box to force read-only access.

•	Auxiliary Password -- Check this box if you want the ability to enter an auxiliary password during a connection attempt. This can be any of the Rdb Distributed Technology Suite (formerly DEC DB Integrator family) of gateway products password.

•	Translation Option is a numeric value that is passed to the translation library when it is called by the Oracle ODBC driver for Rdb:

•	Translation Library is where you can specify the name of a translation library that is to be called by the Oracle ODBC driver for Rdb.

•	Cursor Options -- specify one of the following values:

Value	Description
1	NOHOLD -- Do not hold cursors across transaction boundaries.
2	HOLD -- Hold cursors across transaction boundaries.
4.	After you have entered the data, click on OK or press Return.


Reducing Connection Time

When an ODBC application connects to an Oracle Rdb database, an OpenVMS Alpha or OpenVMS VAX process running the Oracle SQL/Services executors or execute server processes is created. This process then attaches to the Oracle Rdb database. This usually takes several seconds to occur.

You can reduce the time it takes to connect to the database by defining Oracle SQL/Services executors or a class of execute server processes that use executors or execute server processes that are already started. Optionally, the servers can also already be attached to the database.

Refer to the Oracle SQL/Services documentation for more information on executors or execute server process classes.


Modifying the rdbodbc.ini or win.ini File

You can modify the entries in the rdbodbc.ini (32-bit driver) or the win.ini (16-bit driver) file to:

Enable Oracle SQL/Services client logging or Oracle ODBC Driver for Rdb logging

Reduce the lock timeout period or limit the amount of time that Oracle Rdb will wait for locks to be resolved

Enable the "fetch ahead" feature to improve the speed for retrieving data from the host

Remove control characters for certain ODBC applications that issue SQL statements that contain control characters such as carriage returns

Increase the network buffer size from 1300 bytes to 5000 bytes if you predominately connect to V6.0 or higher Oracle Rdb servers

Enable the "proxy access" feature to avoid prompting for password information

How to change each entry in the rdbodbc.ini or win.ini file is described in more detail in each of these topics.


Client and Driver Logging

You can enable Oracle SQL/Services client logging and Oracle ODBC Driver for Rdb logging to identify problems with applications. When logging is enabled, log files are written to the application program's current working directory. Note that log files can be quite large and can slow down performance. Therefore, enable logging only when necessary, and disable it when it is no longer needed.

The Oracle ODBC Driver for Rdb installation procedure creates the following section in the Windows 95 and Windows NT rdbodbc.ini (32-bit driver) file or the MS Windows and Windows 95 win.ini (16-bit driver) file:

[Oracle ODBC Driver for Rdb]

Transport=1=decnet,2=tcp/ip,4=ipx/spx,5=sql*net

Client Logging=0

Driver Logging=0

LockTimeOut=0

A value of 0 for client logging and driver logging indicates that Oracle SQL/Services client logging and Oracle ODBC Driver for Rdb logging are turned off.

To enable logging, insert an appropriate value for client and/or driver logging. You can use the client logging and driver logging values to help debug problems encountered when running applications.

You can also enable client logging in a program, as shown in the Enabling Oracle SQL/Services Client Logging in a Program topic.


Enabling Oracle SQL/Services Client Logging

To enable client logging, insert a valid Oracle SQL/Services client logging value after the equal sign, as shown in the following example:

[Oracle ODBC Driver for Rdb]

Client Logging=3

Valid Oracle SQL/Services client logging values are shown in the Client Logging Values table. To enable more than one type of logging, add the logging values, as shown in the Client Logging Values table. For example, to enable association logging (a value of 1) and API routine logging (a value of 2), insert a value of 3 (1 + 2) after the equal sign.

The client log is written to the file client.log in the application program's current working directory. If there is more than one client log file, each file is uniquely named as clientxx.log, where xx is a number between 0 and 99.

Client Logging Values

Value	Argument	Description
0	SQLSRV_LOG_DISABLED	Disable logging
1	SQLSRV_LOG_ASSOCIATION	Enable association logging
2	SQLSRV_LOG_ROUTINE	Enable API routine logging
3	SQLSRV_LOG_ASSOCIATION	Enable association logging and API routine logging
	SQLSRV_LOG_ROUTINE
4	SQLSRV_LOG_PROTOCOL	Enable message protocol logging
5	SQLSRV_LOG_ASSOCIATION	Enable association logging and message protocol logging
	SQLSRV_LOG_PROTOCOL
6	SQLSRV_LOG_ROUTINE	Enable API routine logging and message protocol logging
	SQLSRV_LOG_PROTOCOL
7	SQLSRV_LOG_ASSOCIATION	Enable association logging, API routine logging, and message protocol logging
	SQLSRV_LOG_ROUTINE
	SQLSRV_LOG_PROTOCOL
For more information on client logging, refer to the Oracle SQL/Services documentation.


Enabling Oracle ODBC Driver for Rdb Logging

To enable Oracle ODBC Driver for Rdb logging, insert a valid Oracle ODBC Driver for Rdb logging value plus 1 after the equal sign, as shown in the following example:

[Oracle ODBC Driver for Rdb]

Driver Logging=7

Valid Oracle ODBC Driver for Rdb logging values are shown in the Driver Logging Values table. To enable more than one type of logging, add the logging values and then add 1, as shown in the Driver Logging Values table. For example, to log ODBC entry points (a value of 2) and main functions (a value of 4), insert a value of 7 (2 + 4 + 1) after the equal sign.

The driver log is written to the file odbcrdb.log in the application program's current working directory.

Driver Logging Values

Value	Value + 1	Description
0	-	Disable logging
2	3	Log ODBC entry points
4	5	Log main functions
6	7	Log ODBC entry points and main functions
8	9	Log ODBC utility functions
10	11	Log ODBC entry points and utility functions
12	13	Log ODBC main functions and utility functions
14	15	Log ODBC entry points, main functions, and utility functions
16	17	Log only SQL statements and errors
A value of 17 is usually the best Oracle ODBC Driver for Rdb logging value to start with initially for problem solving because it produces a small amount of output and only logs the SQL statements sent to the server and any errors that are returned from the server.  This logging value will generally record 90% of the errors that applications encounter.


Reducing Lock Timeout

Oracle Rdb will wait indefinitely for lock conflicts between transactions to be resolved. You can limit the amount of time that Oracle Rdb will wait for locks to be resolved by setting the Oracle ODBC Driver for Rdb's LockTimeOut entry in the Windows 95 and Windows NT rdbodbc.ini (32-bit driver) file or the MS Windows and Windows 95 win.ini (16-bit driver) file. The value you enter for the LockTimeOut parameter is the number of seconds after which Oracle Rdb will time out if it cannot obtain the requested locks. In the following example, Oracle Rdb will time out after 60 seconds:

[Oracle ODBC Driver for Rdb]

Transport=1=decnet,2=tcp/ip,4=ipx/spx,8=sql*net

Client Logging=0

Driver Logging=0

LockTimeOut=60


Enabling the "Fetch Ahead" Feature

To enable the "fetch ahead" feature, accept the entry FetchAhead=YES

The Oracle ODBC Driver for Rdb now implements a "fetch ahead" feature when retrieving data from the host. This improves the speed in which the data is retrieved. For applications that execute more than one SQL statement at a time over the same connection, the "fetch ahead" feature will need to be disabled. The driver will return the following error if the "fetch ahead" feature needs to be disabled:

Multiple SQL statements cannot be active when FetchAhead=YES

To disable the "fetch ahead" feature, change the value of the FetchAhead entry in the driver's section of the rdbodbc.ini or win.ini file from YES to NO.


Removing Control Characters from SQL Statements

To remove control characters, change the entry RemoveControlChars=NO

Certain ODBC applications issue SQL statements that contain control characters, such as carriage returns, which the SQL interface for Oracle Rdb does not allow.  If you are using such an application, change the value of the RemoveControlChars entry in the driver's section of the rdbodbc.ini or win.ini file from NO to YES.


Increasing the Network Buffer Size

To increase the network buffer size, change the entry NetworkBufferSize=1300

When accessing a V6.0 or higher Oracle SQL/Services server, the network buffer size can be up to 5000 bytes in size. If you predominantly connect to V6.0 servers, you should change the value of the NetworkBufferSize entry in the driver's section of the rdbodbc.ini or win.ini file from 1300 bytes to 5000 bytes.


Enabling the Proxy Access Feature
Enabling the "Proxy Access" Feature

To enable the "proxy access" feature to avoid prompting for password information, accept the entry Proxy Access=1, as shown in the following example:

[Oracle ODBC Driver for Rdb]

Proxy Access=1

The Oracle ODBC Driver for Rdb implements proxy access when using the SQLDriverConnect function call. This forces the Oracle ODBC Driver for Rdb to first connect to the Data Source without prompting for required information. If the connection fails, then the Oracle ODBC Driver for Rdb displays the dialog boxes to prompt the user for all connection information and data source information that are not defined in the odbc.ini file or registry. The main use of this feature is to override prompting for user passwords during the SQLDriverConnect operation. If proxy access is enabled, passwords are not required. For more information on setting up proxies refer to the Oracle SQL/Services documentation.

To enable the "proxy access" feature but return an error message if the connection fails rather than prompt the user for all connection information and data source information that are not defined in the odbc.ini file or registry, change the proxy access value to 2, as shown in the following example:

Proxy Access=2

To disable the proxy access feature, change the value of the proxy access entry in the Oracle ODBC driver for Rdb section of the rdbodbc.ini or win.ini file from 1 to 0.


Common Problems

Problems commonly encountered by users when running the Oracle ODBC Driver.for Rdb include:

Using the Oracle ODBC Driver for Rdb for the first time

Attaching to a database

Information about Oracle ODBC Driver for Rdb and other related error messages can be found under:

Error messages


Using the Oracle ODBC Driver for Rdb for the First Time
Using the ODBC Driver for the First Time

The following problems may occur when you use the Oracle ODBC Driver for Rdb for the first time and attempt to attach to a database or table:

•	MS Windows Fails

Problem: MS Windows hangs, fails, exits to DOS, or reboots when you attempt to attach to a database or table.

Cause: PATHWORKS has not been defined as the network in Windows Setup.

Recommended Action: Define PATHWORKS as the network in Windows Setup.

•	Attach Attempt Fails

Problem: When you attempt to attach to a database or table, the attach fails and the following message is displayed:

[Microsoft][ODBC DLL]Driver's SQLAllocConnect failed.

[Oracle][ODBC]Unsupported version of Oracle SQL/Services Client DLL.

Cause: The wrong version or multiple versions of sqsapiw.dll or sqsapi32.dll are present on the PC.

Recommended Action: Ensure that only one version of sqsapiw.dll or sqsapi32.dll is present on the PC and resides in the \WINDOWS\SYSTEM directory for MS Windows and Windows 95 (16-bit) or the system directory for Windows NT (i.e. \WINNT35\SYSTEM32, Windows 95 (32-bit) \WINDOWS\SYSTEM32). If necessary, copy sqsapiw.dll or sqsapi32.dll directly from the installation diskette to the correct directory on your system.

•	Attach Attempt Fails with Native Error

Problem: When you attempt to attach to a database or table, the attach fails and the native error code -2035 is displayed.

Cause: This is an Oracle SQL/Services error that usually occurs when the server on the Alpha or VAX system fails. This usually means that Oracle SQL/Services was not installed correctly.

Recommended Action: Examine the monitor and dispatcher log files and any log files in the default Oracle SQL/Services account to discover the cause of the problem.


Attaching to a Database

The following problems may occur when you attempt to attach to a database or table:

•	Invalid Class Name Error

Problem: The attach attempt fails and the following error is displayed:

-2032

[Oracle][ODBC][Rdb]%SQLSRV-F-NO_CLS, Invalid Class Name

Cause: An undefined Oracle SQL/Services class name was specified when the data source was configured on the PC with the ODBC Administrator.

Recommended Action: Reconfigure the data source and specify a valid Oracle SQL/Services class name.

•	Network Error

Problem: The attach attempt fails and the following error is displayed:

-2003

[Oracle][ODBC][Rdb]Network Error:Suberror code is nn

Cause: This is usually a PATHWORKS error and nn is the PATHWORKS error code.

Recommended Action: Examine the PATHWORKS errors in the errno.h file (for DECnet) or the sock_err.h file (for the development kit for TCP/IP) or winsock.h file (for TCP/IP). Some of the more common errors are listed here.

--	The following error occurs when Oracle SQL/Services is not running:

[Oracle][ODBC][Rdb]Network Error:Suberror code is 3

--	The following error occurs when the target DECnet node is not defined on the PC:

[Oracle][ODBC][Rdb]Network Error:Suberror code is 49

--	The following error occurs when PATHWORKS times out, usually as a result of the Oracle SQL/Services server failing:

[Oracle][ODBC][Rdb]Network Error:Suberror code is 60


Error Messages

The Oracle ODBC Driver for Rdb returns error messages in one of the following formats:

[Oracle][ODBC]Error message text here

[Oracle][ODBC][Rdb]Error message text here

If the error message does not contain the [Rdb] prefix (as in the first example), the error is an Oracle ODBC Driver for Rdb error and should be self-explanatory.

If the error message contains the [Rdb] prefix (as in the second example), it is not an Oracle ODBC Driver for Rdb error. Note that although the error message contains the [Rdb] prefix, the actual error may be coming from one of several sources.

•	If the error message text starts with the following prefix, you can obtain more information about the error in the file SYS$HELP:rdb_msg.doc on the system on which Oracle Rdb is installed:

%RDB-

•	If the error message text starts with the following prefix, you can obtain more information about the error in the file SYS$HELP:sql$msg.doc on the system on which SQL is installed:

%SQL-

•	If the error message contains the following text, where xx is a numeric value, look up the error in the errno.h PATHWORKS client file if you are using DECnet:

Network Error: Suberror code is xx

If you are using TCP/IP, look up the error in the winsock.h file.

•	If the error message contains the following text, consult the OpenVMS documentation for more information on the error:

%SYSTEM

Along with the error message, a native error in the following format, where xxxx is a numeric value, is displayed:

pfNativeError=xxxx

This is an error returned by Oracle SQL/Services. You can look up this error in the sqlsrv.h file on the OpenVMS Alpha or OpenVMS VAX system on which the Oracle SQL/Services server is installed, or you can refer to the Oracle SQL/Services Errors topic for a listing of these errors.


Programming Considerations
PROGRAMING CONSIDERATIONS

Information that is useful to you if you are writing ODBC applications that call the Oracle ODBC Driver for Rdb include the following topics:

Formatting the connection string

Enabling client logging in a program

Reducing lock timeout

Linking your program

Using lists

Using rowids or dbkeys

Improving concurrency and performance

Using the SQLColumns function

Features, characteristics, and functionality of the Oracle ODBC Driver for Rdb

If you are writing ODBC applications, refer to the Microsoft Open Database Connectivity Software Development Kit Programmer's Reference for more information about the Driver Manager, the ODBC calls, and the ODBC environment in general.


Format of the Connection String

The following list of keywords can be included in the connection string argument of the SQLDriverConnect function call. Missing keywords will be read from the ODBC Administrator entry for the data source. Values specified in the connection string will override those contained in the ODBC Administrator entry. See the Microsoft ODBC Programmer's Reference Manual for more information about the SQLDriverConnect function.

Keyword	Meaning
DSN=	ODBC data source name
UID=	Userid
PWD=	Password (specify PWD=; for an empty password)
PWV=	Secondary password (used with Rdb Distributed Technology Suite (formerly DBI Gateways))
SVR=	Server name (node name or TCP/IP address)
DATABASE=	Oracle SQL ATTACH statement
CLS=	Oracle SQL/Services class name
XPT=	Oracle SQL/Services transport (1=decnet, 2=tcp/ip, 4=ipx/spx, 8=sql*net)
DBA=	Database attribute (W=write access, R=read-only access)
TLO=	Translation option
TLL=	Translation library name
DSO=	Database options (see the explanation for the DBI options field of the setup dialog in the topic Configuring a Data Source for a list of valid values
CSO=	Cursor options (see the explanation for the cursor options field of the setup dialog in the topic Configuring a Data Source for a list of valid values
If the following keyword is specified in the connection string, the Oracle ODBC Driver for Rdb will not read any values from the ODBC Administrator:

DRIVER={Oracle ODBC Driver for Rdb}

Examples of valid connection strings:

1) DSN=Personnel;UID=Kotzwinkle;PWD=;

2) DRIVER={Oracle ODBC Driver for Rdb};UID=Kotzwinkle;PWD=whatever;SVR=Nodel;

CLS=generic;XPT=1;DBA=W;CSO=2;

DATABASE=ATTACH 'filename dua1:[user]personnel.rdb';DSO=0;


Enabling Oracle SQL/Services Client Logging in a Program

To enable Oracle SQL/Services client logging in a program, call the ODBC SQLSetConnectOption function, which sets options that govern aspects of connections. Set the value of the fOption argument to 9001 to indicate Oracle SQL/Services client logging. Also, set an appropriate Oracle SQL/Services logging value for the vParam argument. Refer to the Oracle SQL/Services documentation for more information about logging values and about Oracle SQL/Services client logging in general.

To return information about Oracle SQL/Services client logging, use the ODBC SQLGetConnectOption function, which returns the current setting of a connection option. Set the value of the fOption argument to 9001, which indicates Oracle SQL/Services client logging. The value returned by the pvParam argument is a 32-bit integer value.


Reducing Lock Timeout in a Program

Oracle Rdb will wait indefinitely for lock conflicts between transactions to be resolved. You can limit the amount of time that Oracle Rdb will wait for locks to be resolved by calling the ODBC SQLSetConnectOption function before connecting to the data source. Specify a nonzero value for the SQL_QUERY_TIMEOUT option.

If you specify a lock timeout value using the ODBC SQLSetConnectOption function, it overrides any value specified in the rdbodbc.ini or win.ini file. Refer to the Reducing Lock Timeout topic for more information on specifying a value in the rdbodbc.ini or win.ini file.


Linking with odbc.lib or odbc32.lib

When you link your program, you must link it with the import library odbc.lib (16-bit) or odbc32.lib (32-bit). The import library is included on the Oracle ODBC Driver for Rdb installation disk.


Using Oracle Rdb Segmented Strings
Using Oracle Rdb Lists

SQL operations can be performed on Oracle Rdb list columns without having to use list cursors. List columns are interpreted as the ODBC LONGVARBINARY data type, which allows generic ODBC applications to manipulate columns containing lists with standard SQL language constructs.

In order to use the transparent blob access, parameter markers must be used to reference columns containing lists.

NOTE: Programmers who wish to access individual lists using list cursors may still do so by first calling the ODBC SQLSetConnectOption function and specifying the value SQRDB_BLOB_ACCESS_WITH_LISTS for the SQRDB_BLOB_ACCESS connect option.

The Oracle ODBC Driver for Rdb installation disk contains a file named sqrdb.h, which contains constants that are needed for applications that use list cursors. Include this file in your program. sqrdb.h is shown in the Sample Files topic.

The Oracle ODBC Driver for Rdb installation disk also contains files named example1.txt and example2.txt, which are shown in the Sample Files topic. example1.txt shows how an application can store data as Oracle Rdb lists using list cursors. example2.txt shows how an application can retrieve data stored as Oracle Rdb lists using list cursors.


Using rowids or dbkeys

The term rowid is a synonym for the term dbkey.

Information about using rowids or dbkeys with the Oracle ODBC Driver for Rdb is described in the following topics:

Obtaining information about rowids or dbkeys

INSERT statements that contain rowids or dbkeys

rowids or dbkeys in a WHERE clause


Obtaining Information About rowids or dbkeys

The ODBC SQLSpecialColumns function returns information about the columns in a table. When used with the Oracle ODBC Driver for Rdb, it returns information about the Oracle Rdb rowids or dbkeys associated with an Oracle Rdb table.


INSERT Statements that Return rowids or dbkeys

 When executing SQL INSERT statements that return rowids or dbkeys, use an output parameter marker to retrieve the rowid or dbkey. Call the ODBC SQLBindParameter function to bind an output buffer to the rowid or dbkey parameter marker in the INSERT statement.

Use the RETURNING DBKEY INTO ? clause with the INSERT statement, as shown in the following example. This example assumes two input values and one output value:

INSERT INTO tablename VALUES(?,?) RETURNING DBKEY INTO ?


rowids or dbkeys in a WHERE Clause

rowids or dbkeys may be used in the WHERE clause of an SQL statement; however, the rowid or dbkey value must be presented in a parameter marker.


Improving Concurrency and Performance

To improve concurrency and performance of your application, perform the following:

•	Set the SQL_AUTOCOMMIT option of the ODBC SQLSetConnectOption function to off, and perform manual commit or rollback operations using the ODBC SQLTransact function.

•	If you are performing transactions that do not update the data source, set the SQL_ACCESS_MODE option of the ODBC SQLSetConnectOption function to SQL_MODE_READ_ONLY.

•	If you are not using ODBC escape clauses, set the SQL_NOSCAN option of the ODBC SQLSetConnectOption function or the ODBC SQLSetStmtOption function to TRUE.

•	To retrieve values from SELECT statements, use the ODBC SQLBindCol function instead of the ODBC SQLGetData function.

•	Use the ODBC SQLExtendedFetch function instead of the ODBC SQLFetch function for retrieving data from tables that have a large number of rows.

•	Set the network buffer size to 5000 bytes.


SQLColumns Function

The SQLColumns function returns a result set with one additional column beyond those documented in the Microsoft ODBC Programmer's Reference Manual. The thirteenth column indicates whether or not the column can be updated.

Column Name	Data Type	Value
UPDATABLE	Smallint	SQL_ATTR_READONLY or
	not NULL	SQL_ATTR_WRITE


Supported Functionality

Information about the features, characteristics, and functionality of the Oracle ODBC Driver for Rdb include:

API conformance

SQL Grammar extensions

Oracle ODBC Driver for Rdb features

SQL identifiers

Names and version numbers

Scalar functions

Transaction support

Mapping SQL data types to ODBC data types

Mapping ODBC data types to SQL data types

Transparent access to Oracle Rdb lists (blobs)

You can also call the ODBC SQLGetInfo function in your application to obtain information about functionality supported by the Oracle ODBC Driver for Rdb.


API Conformance

The Oracle ODBC Driver for Rdb supports all Core and Level 1 functions, and several Level 2 functions. The following table lists the Core, Level 1, and Level 2 functions that are supported.

Oracle ODBC Driver for Rdb Supports these ODBC  Functions

Core Functions	Level 1 Functions	Level 2 Functions
SQLAllocConnect	SQLBindParameter	SQLDataSources
SQLAllocEnv	SQLColumns	SQLDescribeParam
SQLAllocStmt	SQLDriverConnect	SQLDrivers
SQLBindCol	SQLGetConnectOption	SQLExtendedFetch
SQLCancel	SQLGetData	SQLForeignKeys
SQLColAttributes	SQLGetFunctions	SQLMoreResults
SQLConnect	SQLGetInfo	SQLNativeSQL
SQLDescribeCol	SQLGetStmtOption	SQLNumParams
SQLDisconnect	SQLGetTypeInfo	SQLParamOptions
SQLError	SQLParamData	SQLPrimaryKeys
SQLExecDirect	SQLPutData	SQLProcedures
SQLExecute	SQLSetConnectOption	SQLProcedureColumns
SQLFetch	SQLSetStmtOption	SQLSetScrollOptions
SQLFreeConnect	SQLSpecialColumns
SQLFreeEnv	SQLStatistics
SQLFreeStmt	SQLTables
SQLGetCursorName
SQLNumResultCols
SQLPrepare
SQLRowCount
SQLSetCursorName
SQLSetParam
SQLTransact


SQL Grammar Extensions

The following information describes extensions to and behavior of the SQL grammar supported by the Oracle ODBC Driver for Rdb.

The subjects listed in the Oracle ODBC Driver for Rdb SQL Grammar Extensions table are a subset of those available through the ODBC SQLGetInfo function. You can retrieve each value in the Oracle ODBC Driver for Rdb SQL Grammar Extensions table in a program by passing the corresponding C language #define to the ODBC SQLGetInfo function.

Oracle ODBC Driver for Rdb SQL Grammar Extensions

Subject	#define	Value
Alter Table clauses	SQL_ALTER_TABLE	ADD, DROP
Column Aliases	SQL_COLUMN_ALIAS	No
Result of concatenation with a null column	SQL_CONCAT_NULL_BEHAVIOR	Null
Correlation names	SQL_CORRELATION_NAME	Any*
Expressions in ORDER BY list	SQL_EXPRESSIONS_IN_ORDERBY	Yes*
Group By clause	SQL_GROUP_BY	Contains Select
Source specific keywords	SQL_KEYWORDS	None
Not null column constraint	SQL_NON_NULLABLE_COLUMNS	Yes
Null sort order	SQL_NULL_COLLATION	Low
Integrity Enhancement Facility	SQL_ODBC_SQL_IEF	Not supported
Order By columns needed in the select list	SQL_ORDER_BY_COLUMNS_IN_SELECT	No
Outer joins	SQL_OUTER_JOINS	Yes (with Oracle Rdb V6.0 or later); No (withDBI)*
Supported positioned SQL statements	SQL_POSITIONED_STATEMENTS	DELETE, UPDATE
Procedures	SQL_PROCEDURES	Yes (with Oracle Rdb V6.0 or later); No (with DBI)*
Supported subqueries	SQL_SUBQUERIES	Comparison, Exists, In, Quantified
Unions supported	SQL_UNION	Union, Union All
* Can be overridden with the DBI Options using the ODBC Administrator.


Oracle ODBC Driver for Rdb Features

The following information describes the capabilities of the Oracle ODBC Driver for Rdb.

The subjects listed in the Oracle ODBC Driver for Rdb Features table are a subset of those available through the ODBC SQLGetInfo function. You can retrieve each value in the Oracle ODBC Driver for Rdb Features table in a program by passing the corresponding C language #define to the ODBC SQLGetInfo function.

Oracle ODBC Driver for Rdb Features

Subject	#define	Value
All procedures returned by SQLProcedures are executable	SQL_ACCESSIBLE_PROCEDURES	No
All tables returned by SQLTables are accessible	SQL_ACCESSIBLE_TABLES	Yes
Maximum number of active connections	SQL_ACTIVE_CONNECTIONS	Not defined
Maximum number of active statements	SQL_ACTIVE_STATEMENTS	Not defined
Supported fetch directions	SQL_FETCH_DIRECTION	Next
File usage	SQL_FILE_USAGE	Not supported
SQLGetData extensions	SQL_GETDATA_EXTENSIONS	None
Multiple result sets	SQL_MULT_RESULT_SETS	Not supported
Driver detects updates when refetching	SQL_ROW_UPDATES	No
Supported concurrency control options	SQL_SCROLL_CONCURRENCY	Lock
Supported cursor types	SQL_SCROLL_OPTIONS	Forward only
Character string to escape search patterns	SQL_SEARCH_PATTERN_ESCAPE	&


SQL Identifiers

The following information describes the SQL identifiers used by the Oracle ODBC Driver for Rdb.

The subjects listed in the Oracle ODBC Driver for Rdb SQL Identifiers table are a subset of those available through the ODBC SQLGetInfo function. You can retrieve each value in the Oracle ODBC Driver for Rdb SQL Identifiers table in a program by passing the corresponding C language #define to the ODBC SQLGetInfo function.

Oracle ODBC Driver for Rdb SQL Identifiers

Subject	#define	Value
Case sensitivity of identifiers	SQL_IDENTIFIER_CASE	Uppercase
Character string to delimit identifiers	SQL_IDENTIFIER_QUOTE_CHAR	Not supported
Maximum columns in a select statement	SQL_MAX_COLUMNS_IN_SELECT	500
Maximum columns in a table	SQL_MAX_COLUMNS_IN_TABLE	500
Maximum column identifier length	SQL_MAX_COLUMN_NAME_LEN	31
Maximum cursor identifier length	SQL_MAX_CURSOR_NAME_LEN	30
Maximum owner identifier length	SQL_MAX_OWNER_NAME_LEN	0
Maximum procedure identifier length	SQL_MAX_PROCEDURE_NAME_LEN	0
Maximum qualifier identifier length	SQL_MAX_QUALIFIER_NAME_LEN	0
Maximum table identifier length	SQL_MAX_TABLE_NAME_LEN	31
Data source's term for an owner	SQL_OWNER_TERM	Not supported
Owner usage	SQL_OWNER_USAGE	Not supported
Data source's term for a procedure	SQL_PROCEDURE_TERM	Not supported
Character string to separate qualifier from qualified name	SQL_QUALIFIER_NAME_SEPARATOR	.
Qualifier usage	SQL_QUALIFIER_USAGE	Not supported
Data source's term for a qualifier	SQL_QUALIFIER_TERM	Not supported
Quoted identifier case	SQL_QUOTED_IDENTIFIER_CASE	Case sensitive
Special characters allowed in table names	SQL_SPECIAL_CHARACTERS	$
Data source's term for a table	SQL_TABLE_TERM	TABLE


Names and Version Numbers

The following information describes the name and version number of Oracle Rdb and the name, version number, and conformance levels of the Oracle ODBC Driver for Rdb.

The subjects listed in the Oracle ODBC Driver for Rdb Names and Version Numbers table are a subset of those available through the ODBC SQLGetInfo function. You can retrieve each value in the Oracle ODBC Driver for Rdb Names and Version Numbers table in a program by passing the corresponding C language #define to the ODBC SQLGetInfo function.

Oracle ODBC Driver for Rdb Names and Version Numbers

Subject	#define	Value
DBMS name	SQL_DBMS_NAME	Rdb
DBMS version number	SQL_DBMS_VER	05.10.0000 or higher
Driver file name	SQL_DRIVER_NAME	sqrdb.dll
Supported ODBC version	SQL_DRIVER_ODBC_VER	02.10.00 (16-bit); 02.50.00 (32-bit)
Driver version number	SQL_DRIVER_VER	2.1.0.0.0
API conformance level	SQL_ODBC_API_CONFORMANCE	Level 1
SAG CLI conformance level	SQL_ODBC_SAG_CLI_CONFORMANCE	SAG-compliant
SQL conformance level	SQL_ODBC_SQL_CONFORMANCE	Core


Scalar Functions

The following information describes the scalar functions supported by the Oracle ODBC Driver for Rdb.

The subjects listed in the Oracle ODBC Driver for Rdb Scaler Functions table are a subset of those available through the ODBC SQLGetInfo function. You can retrieve each value in the Oracle ODBC Driver for Rdb Scaler Functions table in a program by passing the corresponding C language #define to the ODBC SQLGetInfo function.

Oracle ODBC Driver for Rdb Scalar Functions

Subject	#define	Value
Supported conversion scalar functions	SQL_CONVERT_FUNCTIONS	Supported
Supported numeric scalar functions	SQL_NUMERIC_FUNCTIONS	ABS, SIGN, PI
Supported string scalar functions	SQL_STRING_FUNCTIONS	CONCAT, LCASE, LEFT, LTRIM, LENGTH, SPACE, SUBSTRING, UCASE, LOCATE, RIGHT, RTRIM
Supported system scalar functions	SQL_SYSTEM_FUNCTIONS	IFNULL, USERNAME, DATABASE
Supported date and time scalar functions	SQL_TIMEDATE_FUNCTIONS	CURDATE, CURTIME, DAYOFMONTH, DAYOFWEEK, DAYOFYEAR, HOUR, NOW, MINUTE, MONTH, SECOND, YEAR


Transaction Support

The following information describes the transaction support of the Oracle ODBC Driver for Rdb.

The subjects listed in the Oracle ODBC Driver for Rdb Transaction Support table are a subset of those available through the ODBC SQLGetInfo function. You can retrieve each value in the Oracle ODBC Driver for Rdb Transaction Support table in a program by passing the corresponding C language #define to the ODBC SQLGetInfo function.

Oracle ODBC Driver for Rdb Transaction Support

Subject	#define	Value
How COMMIT affects cursors before Oracle Rdb V7.0	SQL_CURSOR_COMMIT_BEHAVIOR	Closes cursors
How ROLLBACK affects cursors before Oracle Rdb V7.0	SQL_CURSOR_ROLLBACK_BEHAVIOR	Closes cursors
How COMMIT affects cursors after Oracle Rdb V7.0	SQL_CURSOR_COMMIT_BEHAVIOR	Closes or preserves cursors
How ROLLBACK affects cursors after Oracle Rdb V7.0	SQL_CURSOR_ROLLBACK_BEHAVIOR	Closes or preserves cursors
Default transaction isolation level	SQL_DEFAULT_TXN_ISOLATION	SQL_TXN_READ_COMMITTED
Number of  connections that can have active transactions	SQL_MULTIPLE_ACTIVE_TXN	Multiple
Statements supported in transactions	SQL_TXN_CAPABLE	DML, DDL (for Oracle Rdb), DML (for DEC DB Integrator Gateway)
Supported transaction isolation levels	SQL_TXN_ISOLATION_OPTIONS	SQL_TXN_READ_COMMITTED SQL_TXN_REPEATABLE_READ SQL_TXN_SERIALIZABLE


Mapping of SQL Data Types to ODBC Data Types

The Mapping of SQL Data Types to ODBC Data Types table shows how SQL data types are mapped to ODBC SQL data types.

Mapping of SQL Data Types to ODBC Data Types

This SQL Data Type	Is Mapped to This ODBC Data Type
BIGINT	SQL_BIGINT
BIGINT(p), where p > 0	SQL_DECIMAL
CHAR(n)	SQL_CHAR
DATE ANSI	SQL_DATE
DATE VMS	SQL_TIMESTAMP
DECIMAL(n,0), where n < 5	SQL_SMALLINT
DECIMAL(n,0), where 5 <= n < 10	SQL_INTEGER
DECIMAL(n,0), where 10 <= n < 19	SQL_BIGINT
DECIMAL(n,p), where n < 19 and p > 0	SQL_DECIMAL
DECIMAL(n,p), where n > 18	SQL_DOUBLE
DOUBLE PRECISION	SQL_DOUBLE
FLOAT	SQL_DOUBLE
INTEGER	SQL_INTEGER
INTEGER(p), where p > 0	SQL_DECIMAL
INTERVAL	SQL_VARCHAR
List of byte varying	SQL_VARBINARY
LONG VARCHAR	SQL_LONGVARCHAR
NUMERIC(n,0), where n < 5	SQL_SMALLINT
NUMERIC(n,0), where 5 <= n < 10	SQL_INTEGER
NUMERIC(n,0), where 10 <= n < 19	SQL_BIGINT
NUMERIC(n,p), where n < 19 and p > 0	SQL_DECIMAL
NUMERIC(n,p), where n > 18	SQL_DOUBLE
QUADWORD	SQL_BIGINT
QUADWORD(p), where p > 0	SQL_DECIMAL
REAL	SQL_REAL
SMALLINT	SQL_SMALLINT
SMALLINT(p), where p > 0	SQL_DECIMAL
TIME	SQL_TIME
TIMESTAMP	SQL_TIMESTAMP
TINYINT	SQL_TINYINT
TINYINT(p), where p >  0	SQL_DECIMAL
VARCHAR(n)	SQL_VARCHAR


Mapping of ODBC Data Types to SQL Data Types

The Mapping of ODBC Data Types to SQL Data Types table shows how ODBC SQL data types are mapped to SQL data types.

Mapping of ODBC Data Types to SQL Data Types

This ODBC Data Type	Is Mapped to This SQL Data Type
SQL_BIGINT	BIGINT
SQL_BINARY	List of byte varying
SQL_BIT	Not supported
SQL_CHAR	CHAR(n)
SQL_DATE	DATE ANSI
SQL_DECIMAL(n,0), where n < 5	SMALLINT
SQL_DECIMAL(n,0), where 5 <= n < 10	INTEGER
SQL_DECIMAL(n,0), where 10 <= n < 19	BIGINT
SQL_DECIMAL(n,p), where p > 0	DECIMAL(n,p)
SQL_DOUBLE	DOUBLE PRECISION
SQL_FLOAT	DOUBLE PRECISION
SQL_INTEGER	INTEGER
SQL_LONGVARBINARY	List of byte varying
SQL_LONGVARCHAR	LONG VARCHAR
SQL_NUMERIC(n,0), where n < 5	SMALLINT
SQL_NUMERIC(n,0), where 5 <= n < 10	INTEGER
SQL_NUMERIC(n,0), where 10 <= n < 19	BIGINT
SQL_NUMERIC(n,p), where p > 0	DECIMAL(n,p)
SQL_REAL	REAL
SQL_SMALLINT	SMALLINT
SQL_TIME	TIME
SQL_TIMESTAMP	DATE VMS or TIMESTAMP
SQL_TINYINT	TINYINT
SQL_VARBINARY	List of byte varying
SQL_VARCHAR	VARCHAR(n) or INTERVAL


Transparent Access to Oracle Rdb Lists (Blobs)

SQL operations can be performed on Oracle Rdb list columns without having to use list cursors. List columns are interpreted as the ODBC LONGVARBINARY data type, which allows generic ODBC applications to now manipulate columns containing lists with standard SQL language constructs.

NOTE: Programmers who wish to access individual lists using list cursors may still do so by first calling the ODBC SQLSetConnectOption function and specifying the value SQRDB_BLOB_ACCESS_WITH_LISTS for the SQRDB_BLOB_ACCESS connect option.


ORACLE SQL/SERVICES ERRORS

Oracle SQL/Services errors that might be displayed while the Oracle ODBC Driver for Rdb is running are listed. These errors always appear in the following format, where xxxx is a numeric value:

pfNativeError=xxxx

An Oracle Rdb, SQL, network, or system error always appears with the Oracle SQL/Services error.

Errors are listed in numerical order. The four-digit number in the left column is the value displayed in the following message:

pfNativeError

-2000,SQLSRV_INVARG

-2001,SQLSRV_INVBUFSIZ

-2003,SQLSRV_NETERR

-2005,SQLSRV_INVASC

-2006,SQLSRV_INVSQLDA

-2007,SQLSRV_PRSERR

-2008,SQLSRV_INVSTMID

-2009,SQLSRV_INVCURNAM

-2011,SQLSRV_INTERR

-2012,SQLSRV_OPNLOGFIL

-2013,SQLSRV_NO_MEM

-2014,SQLSRV_INVSQLCA

-2015,SQLSRV_SQLDA_NOTALL

-2016,SQLSRV_MULTI_ACT

-2019,SQLSRV_INVEXEFLG

-2021,SQLSRV_INVASCSTR

-2025,SQLSRV_DUPCRSNAM

-2026,SQLSRV_INVCOLNUM

-2027,SQLSRV_INVDATTYP

-2028,SQLSRV_INCDATTYP

-2029,SQLSRV_USRDATALL

-2030,SQLSRV_ACTSTM

-2031,SQLSRV_APINOTSUP

-2032,SQLSRV_INV_CLS

-2033,SQLSRV_NO_PRCAVL

-2034,SQLSRV_GETACCINF

-2035,SQLSRV_EXEINTERR

-2036,SQLSRV_HOSTERR

-2037,SQLSRV_XPT_MISSING

-2042,SQLSRV_SRVNOTSUP

-2043,SQLSRV_INVSETLEN

-2044,SQLSRV_INVSQLLEN

-2045,SQLSRV_DLL_LOAD_ERR

-2046,SQLSRV_DLL_ADDR_ERR

-2048,SQLSRV_INVSELLST

-2049,SQLSRV_PWD_EXPIRED

-2050,SQLSRV_CONNTIMEOUT

-2051,SQLSRV_SVCNOTRUN

-2052,SQLSRV_SVC_SHUTDOWN

-2053,SQLSRV_TOOMANYCONNECTS

-2054,SQLSRV_SQLNET_BADINIT

-2055,SQLSRV_SQLNET_BADSERVICE

-2056,SQLSRV_SQLNET_BADCONNECT

-2057,SQLSRV_FTCMNYACT

-2058,SQLSRV_DATA_TOO_LONG


-2000,SQLSRV_INVARG

Explanation: Invalid routine parameter.

User Action: Examine all routine parameters and retry with corrected value(s).


-2001,SQLSRV_INVBUFSIZ

Explanation: Invalid read or write buffer size.

User Action: Correct the value(s) for the read or write buffer size(s).


-2003,SQLSRV_NETERR

Explanation: Network error.

User Action: Find the DECnet, TCP/IP, SQL*Net, or NetWare error file (specific to your platform) and look up the error code to determine a course of action.


-2005,SQLSRV_INVASC

Explanation: Invalid association identifier. The routine parameter for the association identifier is invalid.

User Action: Contact your Oracle Corporation support representative for assistance.


-2006,SQLSRV_INVSQLDA

Explanation: Invalid SQLDA or SQLDA_ID.

User Action: Contact your Oracle Corporation support representative for assistance.


-2007,SQLSRV_PRSERR

Explanation: Parsing error on the protocol message. Internal error.

User Action: Contact your Oracle Corporation support representative for assistance.


-2008,SQLSRV_INVSTMID

Explanation: Invalid statement identifier.

User Action: Contact your Oracle Corporation support representative for assistance.


-2009,SQLSRV_INVCURNAM

Explanation: Invalid cursor name. A nonexistent cursor name was specified.

User Action: Specify a valid cursor name.


-2011,SQLSRV_INTERR

Explanation: Internal error.

User Action: Contact your Oracle Corporation support representative for assistance.


-2012,SQLSRV_OPNLOGFIL

Explanation: Login was specified, but the log file could not be opened.

User Action: Evaluate the platform-specific reasons as to why a log file could not be opened, such as security reasons, disk space availability, and so forth.


-2013,SQLSRV_NO_MEM

Explanation: API memory allocation failed.

User Action: Release memory on your client system before running Oracle SQL/Services.


-2014,SQLSRV_INVSQLCA

Explanation: Invalid routine parameter.

User Action: Examine all routine parameters and retry with corrected value(s).


-2015,SQLSRV_SQLDA_NOTALL

Explanation: Attempt to deallocate static memory.

User Action: Contact your Oracle Corporation support representative for assistance.


-2016,SQLSRV_MULTI_ACT

Explanation: A batched sqlsrv_execute_in_out or sqlsrv_fetch_many context is active.

User Action: Contact your Oracle Corporation support representative for assistance.


-2019,SQLSRV_INVEXEFLG

Explanation: Invalid execute flag.

User Action: Contact your Oracle Corporation support representative for assistance.


-2021,SQLSRV_INVASCSTR

Explanation: Invalid parameter in ASSOCIATE_STR.

User Action: Contact your Oracle Corporation support representative for assistance.


-2025,SQLSRV_DUPCRSNAM

Explanation: Duplicate cursor name.

User Action: Respecify a correct cursor name.


-2026,SQLSRV_INVCOLNUM

Explanation: Column number is not within range.

User Action: Examine all routine parameters and retry with corrected value(s).


-2027,SQLSRV_INVDATTYP

Explanation: Invalid data type.

User Action: Specify a correct data type.


-2028,SQLSRV_INCDATTYP

Explanation: Incompatible data type with column.

User Action: Examine all routine parameters and retry with corrected value(s).


-2029,SQLSRV_USRDATALL

Explanation: The user, not Oracle SQL/Services, has allocated data buffers.

User Action: Contact your Oracle Corporation support representative for assistance.


-2030,SQLSRV_ACTSTM

Explanation: The statement id already has an active cursor.

User Action: Close the cursor or prepare the statement again.


-2031,SQLSRV_APINOTSUP

Explanation: API not supported. An Oracle SQL/Services client is trying to access server information that is not supported on the client.

User Action: Contact your Oracle Corporation support representative for assistance.


-2032,SQLSRV_INV_CLS

Explanation: Invalid service name specified.

User Action: Specify a service name in the class_name field in the association structure that matches one of the service names in the server configuration file (check with your server system manager).


-2033,SQLSRV_NO_PRCAVL

Explanation: No process is available.

User Action: The maximum number of servers has been exceeded on the server system. Try another time, or consult with your server system manager to raise the MAX parameter(s) in the server configuration file.


-2034,SQLSRV_GETACCINF

Explanation: The dispatcher was unable to obtain the appropriate account information to authenticate an associating client.

User Action: Consult with your server system manager to examine the log files for more information.


-2035,SQLSRV_EXEINTERR

Explanation: The executor has encountered an internal error.

User Action: Examine any executor log files and correct the problem with the executor, if possible. If not, contact your Oracle Corporation support representative for assistance.


-2036,SQLSRV_HOSTERR

Explanation: An error occurred while accessing the hosts file for the TCP/IP transport. Either a match was not found for the requested node name or the host file does not exist or cannot be read.

User Action: Examine your platform-specific documentation for information about the location and format of the hosts file.


-2037,SQLSRV_XPT_MISSING

Explanation: A valid transport has been selected, but the code is disabled. For example, this can occur on DOS systems when you link an application with a particular transport disabled.

User Action: Examine MAKE or linking procedures to ensure that the requested transport code is enabled.


-2042,SQLSRV_SRVNOTSUP

Explanation: Server not supported. An Oracle SQL/Services client is requesting an operation that is not supported by the version of the server with which it is connected.

User Action: Contact your Oracle Corporation support representative for assistance.


-2043,SQLSRV_INVSETLEN

Explanation: (1) A length may not be specified for the following column data types:

•	SQLSRV_LIST_VARBYTE

•	SQLSRV_GENERALIZED_NUMBER

•	SQLSRV_GENERALIZED_DATE

•	SQLSRV_INTERVAL.

(2) The SQLOCTET_LEN value does not correspond with the SQLLEN value:

•	SQLSRV_ASCII_STRING

The SQLOCTET_LEN value must equal the SQLLEN value or be an exact multiple of the SQLLEN value if using a multi-octet character set.

•	SQLSRV_VARCHAR and SQLSRV_VARBYTE

The SQLOCTET_LEN value must include the leading count field overhead, which is 4 octets or bytes.

User Action: Specify a valid SQLLEN value or valid SQLLEN and SQLOCTET_LEN values.


-2044,SQLSRV_INVSQLLEN

Explanation: The SQLLEN field in the SQLDA or SQLDA2 has been set to a value greater than the size of the column.

User Action: Set the SQLLEN to a valid value.


-2045,SQLSRV_DLL_LOAD_ERR

Explanation: This error is valid only for Windows applications. An error has been returned from the MS Windows LoadLibrary call.

User Action: Action may vary depending on the network transport:

(TCP/IP) 	Ensure that the TCP/IP DLL (winsock.dll, wsock32.dll) is in the search PATH.

(DECnet)	32-bit applications using Windows 95 require pwsock32.dll in the search PATH. PATHWORKS for Windows 95 must be installed.

(DECnet)	DECnet 32-bit applications using Windows NT require dnetw.dll in the search PATH. PATHWORKS for Windows NT must be installed.

(SQL*Net) 	Ensure that you have all the required SQL*Net DLL files.


-2046,SQLSRV_DLL_ADDR_ERR

Explanation: This error is valid only for Windows applications. An error has been returned from the MS Windows GetProcAddress call.

(TCP/IP)	The expected routines in winsock.dll or wsock32.dll are not available.

(DECnet)	The expected routines in pwsock32.dll or dnetw.dll are not available.

(SQL*Net) 	The expected routines in the required SQL*Net DLL files are not available.

User Action:

(TCP/IP)	Install a winsock compatible version of TCP/IP.

(DECnet)	Install PATHWORKS for Windows NT or PATHWORKS for Windows 95.

(SQL*Net) 	Install the version of SQL*Net required by Oracle SQL/Services.


-2048,SQLSRV_INVSELLST

Explanation: Invalid SQLDA Select list.

User Action: Contact your Oracle Corporation support representative for assistance.


-2049,SQLSRV_PWD_EXPIRED

Explanation: Password expired.

User Action: Change your password.


-2050,SQLSRV_CONNTIMEOUT

Explanation: The server created a connect context for a client, but it did not complete connect processing within the server specified interval.

User Action: None.


-2051,SQLSRV_SVCNOTRUN

Explanation: The requested service is not running (i.e., this service has not been started).

User Action: Start this service.


-2052,SQLSRV_SVC_SHUTDOWN

Explanation: The service was shutdown typically by system management.

User Action: Ask system management why the service is shut down.


-2053,SQLSRV_TOOMANYCONNECTS

Explanation: A connect arrived at the dispatcher when the number of connects was at the maximum level.

User Action: Request system management to increase the maximum number of connects.


-2054,SQLSRV_SQLNET_BADINIT

Explanation: Unable to initialize SQL*Net.

User Action: Make sure that the SQL*Net configuration files have correct parameters. On Windows systems, try exiting Windows and rerunning the application program.


-2055,SQLSRV_SQLNET_BADSERVICE

Explanation: SQL*Net is unable to resolve the service name being specified.

User Action: Verify that the service name exists in the tnsnames.ora file or in the Oracle Names Server.


-2056,SQLSRV_SQLNET_BADCONNECT

Explanation: SQL*Net is unable to connect to the server.

User Action: Verify that the server is available for accepting a connection.


-2057,SQLSRV_FTCMNYACT

Explanation: sqlsrv_fetch_many is already active for this cursor.

User Action: Call sqlsrv_fetch until the requested number of rows have been received or call sqlsrv_close_cursor to cancel fetch-many mode.


-2058,SQLSRV_DATA_TOO_LONG

Explanation: The Oracle SQL/Services executor determined that the length of a data value in an SQLDA or SQLDA2 exceeded the maximum allowed for the value's data type.

User Action: Modify the client application to supply a value of the correct length.


SAMPLE FILES

Sample files include the following:

•	sqrdb.h --- include file for ODBC options

•	example1.txt --- file that stores data as Oracle Rdb lists

•	example2.txt --- file that retrieves data stored as Oracle Rdb lists

For more information about these files, refer to the Supported Functionality topic.


Include File for ODBC Options

This file contains constants that are needed for applications that use list cursors.

/********************************************************************

SQRDB.H - This is the include file for ODBC options that are specific to the Oracle ODBC Driver for Rdb.

 Copyright 1993, 1995 By Oracle Corporation

*********************************************************************/

#ifndef __SQRDB

#define __SQRDB

/*****************************************/

/* Rdb Driver specific CONNECT Options   */

/*****************************************/

#define SQRDB_SSC_LOG      9001   /* Oracle SQL/Services Client Logging */

#define SQRDB_BLOB_ACCESS  9004   /* Specifies how binary data   */

                                  /* (blobs) are accessed.       */

/*************************************************************************/

/* Logging Values associated with the SQRDB_SSC_LOG connect option       */

/*************************************************************************/

#define SQRDB_SSC_LOG_DISABLED      0    /* 0 = Turn off logging.        */

#define SQRDB_SSC_LOG_ASSOCIATION   1    /* To enable more than one type */

#define SQRDB_SSC_ROUTINE           2    /* of logging, use the sum of   */

#define SQRDB_SSC_LOG_PROTOCOL      3    /* the desired logging values.  */

/*************************************************************************/

/* Values associated with the SQRDB_BLOB_ACCESS connect option           */

/*************************************************************************/

#define SQRDB_BLOB_ACCESS_TRANSPARENT   0    /* Access is transparent to */

                                             /* the application.         */

#define SQRDB_BLOB_ACCESS_WITH_LISTS    1    /* Access is controlled by  */

                                             /* the application via the  */

                                             /* use of list cursors.     */

/*****************************************/

/* Rdb Driver specific STATEMENT Options */

/*****************************************/

#define SQRDB_LIST_LEN     9002   /* Maximum length of data that */

                                  /* will be returned for a      */

                                  /* segmented string.           */

                                  /* This option can be used to  */

                                  /* override the default segment*/

                                  /* size of the string.         */

#define SQRDB_CURSOR_TYPE  9003   /* Type of cursor that will be */

                                  /* declared when an SQL        */

                                  /* statement is executed.      */

/************************************************************************/

/* Cursor types associated with the SQRDB_CURSOR_TYPE statement option  */

/************************************************************************/

#define SQRDB_CURSOR_READ          0   /* Read             */

#define SQRDB_CURSOR_UPDATE        1   /* Update           */

#define SQRDB_CURSOR_INSERT        2   /* Insert           */

#define SQRDB_CURSOR_UPDATE_ONLY   3   /* Update-Only      */

#endif /* #ifndef __SQRDB */


File to Store Data as Segmented Strings
File to Store Data As Lists Using List Cursors

This file stores data as Oracle Rdb lists using list cursors.

/* Connect to data source with auto commit disabled */

SQLAllocEnv(&henv)

SQLAllocConnect(henv, &hdbc)

SQLSetConnectOption(hdbc, SQL_AUTOCOMMIT, OFF)

SQLSetConnectOption(hdbc, SQRDB_BLOB_ACCESS, SQRDB_BLOB_ACCESS_WITH_LISTS)

SQLConnect(hdbc, ...)

/* Create a table that contains a list column */

SQLAllocStmt(hdbc, &hstmt0)

SQLExecDirect(

  hstmt0,

  "create table EMP (EMP_ID char(5), ADDRESS list of byte varying(25))",

  SQL_NTS)

/* Open an insert only cursor on the table EMP */

SQLAllocStmt(hdbc, &hstmt1)

SQLSetCursorName(hstmt1, "C1", SQL_NTS)

SQLSetStmtOption(hstmt1, SQRDB_CURSOR_TYPE, SQRDB_CURSOR_INSERT)

SQLExecDirect(

  hstmt1,

  "select EMP_ID, ADDRESS from EMP",

  SQL_NTS)

/* Insert one row into the table EMP */

SQLAllocStmt(hdbc, &hstmt2)

SQLExecDirect(

  hstmt2,

  "insert into cursor C1 (EMP_ID) values('00167')",

  SQL_NTS)

/* Open an insert only cursor on the ADDRESS column of table EMP */

SQLAllocStmt(hdbc, &hstmt3)

SQLSetCursorName(hstmt3, "ADDRESS_CUR", SQL_NTS)

SQLSetStmtOption(hstmt3, SQRDB_CURSOR_TYPE, SQRDB_CURSOR_INSERT)

SQLExecDirect(

  hstmt3,

  "select ADDRESS where current of C1",

  SQL_NTS)

/* Insert values into the ADDRESS column */

SQLAllocStmt(hdbc, &hstmt4)

SQLExecDirect(

  hstmt4,

  "insert into cursor ADDRESS_CUR values('42 Main Street')",

  SQL_NTS)

SQLExecDirect(

  hstmt4,

  "insert into cursor ADDRESS_CUR values('Dayton, OH 45431')",

  SQL_NTS)

/* Commit the transaction */

SQLTransact(hdbc, SQL_COMMIT)


File to Retrieve Segmented Strings
File to Retrieve Lists Using List Cursors

This file retrieves data that is stored as Oracle Rdb lists using list cursors.

/* Connect to data source with auto commit disabled */

SQLAllocEnv(&henv)

SQLAllocConnect(henv, &hdbc)

SQLSetConnectOption(hdbc, SQL_AUTOCOMMIT, OFF)

SQLSetConnectOption(hdbc, SQRDB_BLOB_ACCESS, SQRDB_BLOB_ACCESS_WITH_LISTS)

SQLConnect(hdbc, ...)

/* Open a cursor on the table EMP */

SQLAllocStmt(hdbc, &hstmt1)

SQLSetCursorName(hstmt1, "C1", SQL_NTS)

SQLExecDirect(

  hstmt1,

  "select EMP_ID, ADDRESS from EMP",

  SQL_NTS)

/* Have fetch return the data as a character string */

SQLBindCol(hstmt1, 1, SQL_C_CHAR, ...)

/* Fetch one row from table EMP */

SQLFetch(hstmt1);

/* Open a cursor on the ADDRESS column of table EMP */

SQLAllocStmt(hdbc, &hstmt2)

SQLSetStmtOption(hstmt2, SQRDB_CURSOR_TYPE, SQRDB_CURSOR_READ)

SQLExecDirect(

  hstmt2,

  "select ADDRESS where current of C1",

  SQL_NTS)

/* The data type must be set to BINARY. This will cause the driver to */

/* return the data in whatever form it is stored in the database, */

/* that is, character data will be returned as character data.    */

SQLBindCol(hstmt2, 1, SQL_C_BINARY, ...)

/* Fetch the segments from the ADDRESS column of table EMP */

while (SQLFetch(hstmt2) == SQL_SUCCESS)

/* End the transaction */

SQLTransact(hdbc, SQL_ROLLBACK)


COPYRIGHT AND TRADEMARK ACKNOWLEDGMENTS

Copyright © 1993, 1997, Oracle Corporation. All rights reserved.

IMPORTANT - READ CAREFULLY BEFORE VIEWING AND/OR USING THIS DOCUMENTATION IN ANY WAY. NO PART OF THIS DOCUMENTATION MAY BE REPRODUCED OR TRANSMITTED IN ANY FORM OR BY ANY MEANS, ELECTRONIC OR MECHANICAL, FOR ANY PURPOSE, WITHOUT THE EXPRESS WRITTEN PERMISSION OF ORACLE CORPORATION.

The software contains proprietary information of Oracle Corporation; it is provided under a license agreement containing restrictions on use and disclosure and is also protected by copyright, patent, and other intellectual property law. Reverse engineering of the software is prohibited.

The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. Oracle Corporation does not warrant that this document is error free.

Restricted Rights Legend Programs delivered subject to the DOD FAR Supplement are 'commercial computer software' and use, duplication and disclosure of the Programs shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement. Otherwise, Programs delivered subject to the Federal Acquisition Regulations are 'restricted computer software' and use, duplication and disclosure of the Programs shall be subject to the restrictions in FAR 52.227-14, Rights in Data – General, including Alternate III (June 1987). Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065.

The programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be licensee's responsibility to take all appropriate fail-safe, back up, redundancy and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and Oracle disclaims liability for any damages caused by such use of the Programs.

ORACLE and SQL*Net are registered trademarks of Oracle Corporation, Redwood City, California. Rdb7, Oracle Rdb, and Oracle SQL/Services are trademarks of Oracle Corporation.

All other company  or product names are used for identification purposes only, and may be trademarks of their respective holders.


Glossary

Select a glossary term:

Client

Data source

DECnet

Driver manager

Dynamic SQL

IPX/SPX

Network

ODBC Driver

Oracle ODBC driver for Rdb

Oracle SQL/Services

Service

SQL*Net

TCP/IP

Windows sockets


Client

A client is a software program that accesses data by selecting a service provided by a server using an agreed upon interface. The server responds by receiving and processing client requests, and sending the results back to the client. ODBC Client applications use the ODBC Driver API to call ODBC functions to submit SQL statements and retrieve results.


Network

A network is made up of communications software through which the client APIs communicate with the Oracle SQL/Services server. Message requests from the client and response requests from the server travel over a DECnet, Transmission Control Protocol/Internet Protocol (TCP/IP), SQL*Net, or Internetwork Packet Exchange/Sequenced Packet Exchange (IPX/SPX) communications link.


Oracle SQL/Services

A client/server component of Oracle Rdb that allows application programs running on various types of computers to access databases that use the dynamic interface to SQL.


IPX/SPX

Internetwork Packet Exchange (IPX)/Sequenced Packet Exchange (SPX). IPX is a connectionless protocol that performs the tasks of the Network layer of the Open Systems Interconnection (OSI) model that includes addressing, routing, and switching information packets from one location to another on a network. SPX is a connection-oriented protocol that performs the tasks of the Transport layer of the OSI model one layer above the Network layer. SPX is identical to IPX except that it has the additional tasks of guaranteeing delivery, sequencing of packets, detecting and correcting errors, and suppressing packet duplication. Oracle SQL/Services provides support for IPX/SPX in its MS Windows API. The OpenVMS Alpha and OpenVMS VAX server also supports the IPX/SPX transport.


TCP/IP

Transmission Control Protocol/Internet Protocol. An interprocess communication mechanism used by applications to share data across a network. TCP allows a process on one machine to send a stream of data to a process on another machine. Software implementing TCP usually resides in the operating system and uses the IP to transmit information across the Internet. Oracle SQL/Services provides support for TCP/IP in its Macintosh for MPW, Macintosh for THINK C, MS Windows, Windows 95, Solaris, Digital UNIX, Windows NT X86, Windows NT Alpha, OpenVMS Alpha, and OpenVMS VAX APIs, in addition to its Oracle ODBC Driver for Rdb for the MS Windows, Windows 95, Windows NT X86, and Windows NT Alpha operating systems.


SQL*Net

Oracle Corporation's family of networking products that transparently integrates clients, servers, and gateways to deliver a unified information resource, using industry-standard or proprietary network protocols. Oracle SQL/Services provides support for SQL*Net in its MS Windows, Digital UNIX, OpenVMS Alpha, and OpenVMS VAX APIs, in addition to its Oracle ODBC Driver for Rdb for the MS Windows operating systems.


DECnet

A Digital software facility that implements the DIGITAL Network Architecture (DNA) to let a user access information on a remote computer through telecommunications lines. A DECnet network enables an OpenVMS Alpha or OpenVMS VAX system to function as a network node and, for instance, allows programs running on one node to remotely access an Oracle Rdb database on another node in the same DECnet network. Oracle Rdb lets you access remote databases on remote nodes by using either DECnet Phase IV or DECnet OSI.

Oracle SQL/Services provides support for DECnet in all client APIs except the Solaris API. For APIs that support DECnet and another transport, Oracle SQL/Services uses DECnet as the default.


Windows sockets

An independent specification that defines a network programming interface for MS Windows based on the socket paradigm described in Berkeley Software Distribution (BSD) from the University of California at Berkeley. It encompasses both familiar socket style routines and a set of MS Windows extensions designed to take advantage of the message-driven nature of MS Windows.


ODBC driver

Microsoft's Open Database Connectivity (ODBC) provides a standard interface that allows one application to access many different data sources. The application's source code does not have to be recompiled for each data source. An ODBC driver links the application to a specific data source. An ODBC driver is a dynamic-link library that an application can invoke on demand to gain access to a data source.


Oracle ODBC Driver for Rdb

The Oracle ODBC Driver for Rdb allows Microsoft ODBC MS Windows, Windows 95, Windows NT X86, and Windows NT Alpha applications read and write access to Oracle Rdb databases using the TCP/IP, DECnet, SQL*Net (MS Windows applications only), or IPX/SPX (MS Windows applications only) transport. The Oracle ODBC Driver for Rdb links the application to an Oracle Rdb data source. The Oracle ODBC Driver for Rdb is a dynamic-link library that an application can invoke on demand to gain access to an Oracle Rdb database.


Driver Manager

Loads drivers on behalf of an application.


Data Source

Consists of the data the user wants to access and its associated operating system, DBMS (Oracle Rdb), and network platform used to access Oracle Rdb.


Dynamic SQL

Dynamic SQL allows an application to accept or generate and execute SQL statements at run time when you cannot predict the form or type of SQL statement your program will need to process. Dynamic SQL is part of the ANSI/ISO SQL standard referred to as SQL92.


Service

An Oracle SQL/Services service is a set attributes that describe a service provided by one server to a set clients. The definition of a service includes information such as who can use the service, the database that is accessed by the service, the database engine version used by the service, the process environment used by the service, and the number of executors that will be working on behalf of the service.