Vous êtes sur la page 1sur 87

DataDirect Connect

for ODBC

Progress Supplement
Release 6.0
March 2009
© 2009 Progress Software Corporation. All rights reserved. Printed in the U.S.A.
DataDirect, DataDirect Connect, DataDirect Connect64, DataDirect Spy, DataDirect Test, DataDirect XML Converters,
DataDirect XQuery, OpenAccess, SequeLink, Stylus Studio, and SupportLink are trademarks or registered trademarks
of Progress Software Corporation or one of its subsidiaries or affiliates in the United States and other countries. Java
and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the
United States and other countries. MySQL and MySQL Enterprise are registered trademarks of MySQL AB in the
United States, the European Union and other countries.
Other company or product names mentioned herein may be trademarks or registered trademarks of their respective
companies.
DataDirect products for the Microsoft SQL Server database:
These products contain a licensed implementation of the Microsoft TDS Protocol.
DataDirect Connect for ODBC, DataDirect Connect64 for ODBC, and DataDirect SequeLink include:
ICU Copyright © 1995-2003 International Business Machines Corporation and others. All rights reserved. Permission
is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, provided that the above copyright notice(s) and this permission notice appear in all
copies of the Software and that both the above copyright notice(s) and this permission notice appear in supporting
documentation.
Software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http:/www.openssl.org/). Copyright ©
1998-2006 The OpenSSL Project. All rights reserved. And Copyright © 1995-1998 Eric Young (eay@cryptsoft.com). All
rights reserved.
DataDirect SequeLink includes:
Portions created by Eric Young are Copyright © 1995-1998 Eric Young (eay@cryptsoft.com). All Rights Reserved.
OpenLDAP, Copyright © 1999-2003 The OpenLDAP Foundation, Redwood City, California, US. All rights reserved.
DataDirect OpenAccess SDK client for ODBC, DataDirect OpenAccess SDK client for ADO, DataDirect Open Access
SDK client for JDBC, and DataDirect OpenAccess SDK server include: DataDirect SequeLink.
No part of this publication, with the exception of the software product user documentation contained in electronic
format, may be copied, photocopied, reproduced, transmitted, transcribed, or reduced to any electronic medium or
machine-readable form without prior written consent of DataDirect Technologies.
Licensees may duplicate the software product user documentation contained on a CD-ROM or DVD, but only to the
extent necessary to support the users authorized access to the software under the license agreement. Any
reproduction of the documentation, regardless of whether the documentation is reproduced in whole or in part,
must be accompanied by this copyright statement in its entirety, without modification.
3

Table of Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Product Platform Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Using this Supplement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Conventions Used in this Supplement . . . . . . . . . . . . . . . . . . . 9
Typographical Conventions. . . . . . . . . . . . . . . . . . . . . . . . . 9
Environment-Specific Information . . . . . . . . . . . . . . . . . . . 10

About the Product Documentation . . . . . . . . . . . . . . . . . . . . . 11


HTML Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
PDF Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Contacting Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . 13

1 Quick Start Connect. . . . . . . . . . . . . . . . . . . . . . . . . . 15


Configuring and Connecting on Windows . . . . . . . . . . . . . . . 16
Configuring a Data Source Through the ODBC
Administrator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Testing the Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Configuring and Connecting on UNIX and Linux . . . . . . . . . . 18

2 Configuring the Product on UNIX/Linux . . . . . . . . . 19


Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Library Search Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
ODBCINI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
ODBCINST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
DD_INSTALLDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

The ivtestlib Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

DataDirect Connect for ODBC Progress Supplement


4 Table of Contents

Data Source Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 24


Configuration Through the System Information File. . . . 25

The demoodbc Application . . . . . . . . . . . . . . . . . . . . . . . . . . . 32


The example Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
DSN-less Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
File Data Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

3 The Progress OpenEdge Wire Protocol Driver. . . . . 39


Driver Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Configuring Data Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Connecting to a Data Source Using a Logon Dialog Box. . . . 45
Connecting to a Data Source Using a Connection String . . . 46
Performance Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Data Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Unicode Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Isolation and Lock Levels Supported. . . . . . . . . . . . . . . . . . . . 52
ODBC Conformance Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Number of Connections and Statements Supported . . . . . . . 53
Threading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

4 The Progress OpenEdge Driver. . . . . . . . . . . . . . . . . 55


Driver Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Configuring Data Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Connecting to a Data Source Using a Logon Dialog Box. . . . 62
Connecting to a Data Source Using a Connection String . . . 63
Performance Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Data Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Isolation and Lock Levels Supported. . . . . . . . . . . . . . . . . . . . 68

DataDirect Connect for ODBC Progress Supplement


Table of Contents 5

ODBC Conformance Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68


Number of Connections and Statements Supported. . . . . . . . 69
Threading. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

5 The Progress SQL92 Driver . . . . . . . . . . . . . . . . . . . . 71


Driver Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Configuring Data Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Connecting to a Data Source Using a Logon Dialog Box . . . . 77
Connecting to a Data Source Using a Connection String . . . . 78
Performance Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Isolation and Lock Levels Supported . . . . . . . . . . . . . . . . . . . . 84
ODBC Conformance Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Number of Connections and Statements Supported. . . . . . . . 84
Threading. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

DataDirect Connect for ODBC Progress Supplement


6 Table of Contents

DataDirect Connect for ODBC Progress Supplement


7

Preface

This supplement to your user’s guide for DataDirect Connect®


for ODBC from DataDirect Technologies includes information that
is specific to the DataDirect Connect for ODBC drivers for Progress.
This information is not included in the standard DataDirect
Connect for ODBC documentation.

Product Platform Support


The Progress drivers enable you to connect to a Progress
database from these platforms:

Windows

■ Windows Server 2008


■ Windows Vista
■ Windows XP
■ Windows Server 2003
■ Windows 2000

UNIX and Linux


■ AIX
■ HP-UX aCC Enabled
■ Linux
■ Sun Solaris

DataDirect Connect for ODBC Progress Supplement


8 Preface

Using this Supplement


The content of this supplement is based on the assumption that
you are familiar with your operating system and its commands. It
contains a chapter for each Progress database driver. Each
chapter is structured in the same way. First, it lists which versions
of the databases the driver supports, the operating environments
on which the drivers run, and the driver requirements for your
operating environment. Next, it explains how to configure a data
source and how to connect to that data source. Finally, the
chapter provides information about data types, ODBC
conformance levels, isolation and lock levels supported, and
other driver-specific information. The Progress drivers comply
with the ODBC specification.

If you are writing programs to access ODBC drivers, you need to


obtain a copy of the ODBC Programmer’s Reference for the
Microsoft Open Database Connectivity Software Development
Kit, available from Microsoft Corporation.

Database drivers are continually being added to each operating


environment. For the latest information about the specific drivers
available for your platform, refer to the readme file in your
software package or refer to the DataDirect Technologies
database support matrix Web pages at:

http://www.datadirect.com/products/odbc/matrix/connectodbc.htm (32-bit)

http://www.datadirect.com/products/odbc64/matrix/connect64odbc.htm (64-bit)

NOTE: This supplement may refer the reader to Web URLs for
more information about specific topics, and may include Web
URLs not maintained by DataDirect Technologies. Because it is the
nature of Web content to change frequently, DataDirect
Technologies can guarantee only that the URLs referenced in this
supplement were correct at the time of publishing.

DataDirect Connect for ODBC Progress Supplement


Conventions Used in this Supplement 9

Conventions Used in this Supplement


The following sections describe the typography, terminology,
and other conventions used in this supplement.

Typographical Conventions

Convention Explanation
italics Introduces new terms with which you may not
be familiar, and is used occasionally for
emphasis.
bold Emphasizes important information. Also
indicates button, menu, and icon names on
which you can act. For example, click Next.
UPPERCASE Indicates keys or key combinations that you can
use. For example, press the ENTER key.

Also used for SQL reserved words.


monospace Indicates syntax examples, values that you
specify, or results that you receive.
monospaced Indicates names that are placeholders for values
italics that you specify. For example, filename.
forward slash / Separates menus and their associated
commands. For example, Select File / Copy
means that you should select Copy from the File
menu.

The slash also separates directory levels when


specifying locations under UNIX.
vertical rule | Indicates an "OR" separator used to delineate
items.

DataDirect Connect for ODBC Progress Supplement


10 Preface

Convention Explanation
brackets [ ] Indicates optional items. For example, in the
following statement: SELECT [DISTINCT],
DISTINCT is an optional keyword.

Also indicates sections of the Windows Registry.


braces { } Indicates that you must select one item. For
example, {yes | no} means that you must specify
either yes or no.
ellipsis . . . Indicates that the immediately preceding item
can be repeated any number of times in
succession. An ellipsis following a closing
bracket indicates that all information in that
unit can be repeated.

Environment-Specific Information
The drivers are supported in the Windows, UNIX, and Linux
environments. When the information provided is not applicable
to all supported environments, the following symbols are used to
identify that information:

The Windows symbol signifies text that is applicable only to


Windows.

The UNIX symbol signifies text that is applicable only to UNIX and
Linux.

DataDirect Connect for ODBC Progress Supplement


About the Product Documentation 11

About the Product Documentation


The main product library consists of the following books:

■ DataDirect Connect Series for ODBC Installation Guide details


requirements and procedures for installing the product.

■ DataDirect Connect Series for ODBC User’s Guide provides


information about configuring and using the product.

■ DataDirect Connect Series for ODBC Reference provides


detailed reference information about the product.

■ DataDirect Connect Series for ODBC Troubleshooting Guide


provides information about error messages and
troubleshooting procedures for the product.

HTML Version
All of these books are placed on your system as HTML-based
online help during a normal installation of DataDirect Connect
for ODBC. They are located in the help subdirectory of the product
installation directory. To use the help, you must have an Internet
browser installed.

On Windows, you can access the entire help system by selecting


the help icon that appears in the DataDirect program group.

On all platforms, you can access the entire help system by


opening the following file from within your browser:

install_dir/help/help.htm

where install_dir is the path to the product installation


directory.

DataDirect Connect for ODBC Progress Supplement


12 Preface

Or, from a command-line environment, at a command prompt,


enter:

browser_exe install_dir/help/help.htm

where browser_exe is the name of your browser executable and


install_dir is the path to the product installation directory.

After the browser opens, the left pane displays the Table of
Contents, Index, and Search tabs for the entire documentation
library. When you have opened the main screen of the help
system in your browser, you can bookmark it in the browser for
quick access later.

NOTE: Security features set in your browser can prevent the help
system from launching. A security warning message is displayed.
Often, the warning message provides instructions for unblocking
the help system for the current session. To allow the help system
to launch without encountering a security warning message, the
security settings in your browser can be modified. Check with
your system administrator before disabling any security features.

Help is also available from the setup dialog box for each driver.
When you click Help, your browser opens to the correct topic in
the help system, without opening the help Table of Contents. A
grey toolbar appears at the top of the browser window.

This tool bar contains previous and next navigation buttons. If,
after viewing the help topic, you want to see the entire library,
click:

on the left side of the toolbar, which opens the left pane and
displays the Table of Contents, Index, and Search tabs.

DataDirect Connect for ODBC Progress Supplement


Contacting Technical Support 13

PDF Version
A PDF version of this supplement is provided in the Progress
driver package. You can view the PDF documentation using the
Adobe Acrobat Reader.

Contacting Technical Support


DataDirect Technologies offers a variety of options to meet your
technical support needs. Please visit our Web site for more
details and for contact information:

http://support.datadirect.com

The DataDirect Technologies Web site provides the latest


support information through our global service network. The
SupportLink program provides access to support contact details,
tools, patches, and valuable information, including a list of FAQs
for each product. In addition, you can search our
Knowledgebase for technical bulletins and other information.

To obtain technical support for an evaluation copy of the


product, go to:

http://www.datadirect.com/support/eval_help/index.ssp

or contact your sales representative.

DataDirect Connect for ODBC Progress Supplement


14 Preface

When you contact us for assistance, please provide the following


information:

■ The serial number that corresponds to the product for which


you are seeking support, or a case number if you have been
provided one for your issue. If you do not have a SupportLink
contract, the SupportLink representative assisting you will
connect you with our Sales team.

■ Your name, phone number, email address, and organization.


For a first-time call, you may be asked for full customer
information, including location.

■ The DataDirect product and the version that you are using.

■ The type and version of the operating system where you have
installed your DataDirect product.

■ Any database, database version, third-party software, or


other environment information required to understand the
problem.

■ A brief description of the problem, including, but not limited


to, any error messages you have received, what steps you
followed prior to the initial occurrence of the problem, any
trace logs capturing the issue, and so on. Depending on the
complexity of the problem, you may be asked to submit an
example or reproducible application so that the issue can be
recreated.

■ A description of what you have attempted to resolve the


issue. If you have researched your issue on Web search
engines, our Knowledgebase, or have tested additional
configurations, applications, or other vendor products, you
will want to carefully note everything you have already
attempted.

■ A simple assessment of how the severity of the issue is


impacting your organization.

DataDirect Connect for ODBC Progress Supplement


15

1 Quick Start Connect

This chapter provides basic information for configuring and test


connecting with your drivers immediately after installation. To
take full advantage of the features of the drivers, we
recommend that you read the chapters specific to the drivers you
are using.

Information that the driver needs to connect to a database is


stored in a data source. The ODBC specification describes three
types of data sources: user data sources, system data sources (not
a valid distinction on UNIX/Linux), and file data sources. On
Windows, user and system data sources are stored in the registry
of the local computer. The difference is that only a specific user
can access user data sources, whereas any user of the machine
can access system data sources. On Windows, UNIX, and Linux,
file data sources, which are simply text files, can be stored locally
or on a network computer, and are accessible to other machines.

When you define and configure a data source, you store default
connection values for the driver that are used each time you
connect to a particular database. You can change these defaults
by modifying the data source.

This chapter contains the following sections:

■ “Configuring and Connecting on Windows”


■ “Configuring and Connecting on UNIX and Linux”

DataDirect Connect for ODBC Progress Supplement


16 Chapter 1 Quick Start Connect

Configuring and Connecting on Windows


The following basic information enables you to configure a data
source and test connect with a driver immediately after
installation. On Windows, data sources are defined, configured
and modified through the ODBC Administrator using a driver
Setup dialog box. Default connection values are specified
through the options on the tabs of the Setup dialog box and are
stored either as a user or system data source in the Windows
Registry, or as a file data source in a specified location.

Configuring a Data Source Through the


ODBC Administrator
1 From the DataDirect program group, start the ODBC
Administrator and click either the User DSN, System DSN or
File DSN tab to display a list of data sources.

■ User DSN: If you installed default DataDirect ODBC user


data sources as part of the installation, select the
appropriate data source name and click Configure to
display the driver Setup dialog box.

If you are configuring a new user data source, click Add to


display a list of installed drivers. Select the appropriate
driver and click Finish to display the driver Setup dialog
box.
■ System DSN: To configure a new system data source, click
Add on the System DSN tab to display a list of installed
drivers. Select the appropriate driver and click Finish to
display the driver Setup dialog box.

DataDirect Connect for ODBC Progress Supplement


Configuring and Connecting on Windows 17

■ File DSN: To configure a new file data source, click Add on


the File DSN tab to display a list of installed drivers. Select
the appropriate driver and click Next. Specify a name for
the data source and click Next. Verify the data source
information; then, click Finish to display the Setup dialog
box.

The General tab of the Setup dialog box appears by default.

NOTE: The General tab displays only fields that are required
for creating a data source. The fields on all other tabs are
optional, unless noted otherwise.
2 The following two options appear on the General tab of all
driver Setup dialog boxes:

Data Source Name: Type a string that identifies this data


source configuration, such as Accounting.

Description: Type an optional long description of a data


source name, such as My Accounting Database.

Provide the requested information for all other options on


the General tab; then, click Apply to configure the data
source.

Testing the Connection


1 After you have configured the data source, you can click Test
Connect on the Setup dialog box to attempt to connect to
the data source using the connection properties specified in
the dialog box. Some drivers immediately return a message
indicating success or failure. For most drivers, a logon dialog
box appears as described in each individual driver chapter.

DataDirect Connect for ODBC Progress Supplement


18 Chapter 1 Quick Start Connect

2 Supply the requested information in the logon dialog box and


click OK. Note that the information you enter in the logon
dialog box during a test connect is not saved.

■ If the driver can connect, it releases the connection and


displays a Connection Established message. Click OK.

■ If the driver cannot connect because of an improper


environment or incorrect connection value, it displays an
appropriate error message. Click OK.

3 On the driver Setup dialog box, click OK. The values you have
specified are saved and are the defaults used when you
connect to the data source. You can change these defaults by
using the previously described procedure to modify your data
source. You can override these defaults by connecting to the
data source using a connection string with alternate values.
See individual driver chapters for information about using
connection strings.

Configuring and Connecting on UNIX and


Linux
See Chapter 2 “Configuring the Product on UNIX/Linux” on
page 19 for detailed information about how to configure a data
source and test connect with a driver immediately after
installation.

DataDirect Connect for ODBC Progress Supplement


19

2 Configuring the Product on


UNIX/Linux

This chapter contains specific information about using


DataDirect Connect for ODBC in the UNIX and Linux
environments. It discusses the following:

■ “Environment Variables” on page 19


■ “The ivtestlib Tool” on page 23
■ “Data Source Configuration” on page 24
■ “The demoodbc Application” on page 32
■ “The example Application” on page 32
■ “DSN-less Connections” on page 33
■ “File Data Sources” on page 36

Environment Variables
The first step in setting up and configuring the drivers for use is
to set several environment variables. The following procedures
require that you have the appropriate permissions to modify
your environment and to read, write, and execute various files.
You must log in as a user with full r/w/x permissions recursively
on the entire DataDirect Connect for ODBC installation directory.

DataDirect Connect for ODBC Progress Supplement


20 Chapter 2 Configuring the Product on UNIX/Linux

Library Search Path


The library search path variable can be set by executing the
appropriate shell script located in the ODBC home directory.
Determine which shell you are running by executing:

echo $SHELL

from your login shell.

C shell (and related shell) users must execute the following


command before attempting to use ODBC-enabled applications:

source ./odbc.csh

Bourne shell (and related shell) users must initialize their


environment as follows:

. ./odbc.sh

Executing these scripts sets the appropriate library search path


environment variable (LD_LIBRARY_PATH on Solaris and Linux,
SHLIB_PATH on HP/UX, and LIBPATH on AIX). The library search
path environment variable must be set so that the ODBC core
components and drivers can be located at the time of execution.
After running the setup script, execute:

env

to verify that the installation_directory/lib directory has been


added to your shared library path.

The Progress client-based drivers must have additional


environment variables set. Consult the driver requirements in
each of the individual driver chapters for additional environment
variable information.

DataDirect Connect for ODBC Progress Supplement


Environment Variables 21

ODBCINI
DataDirect Connect for ODBC Setup installs in the product
installation directory a default system information file, named
odbc.ini, that contains data sources. See “The ivtestlib Tool” on
page 23 for an explanation of the odbc.ini file. The system
administrator can choose to rename the file and/or move it to
another location. In either case, the environment variable
ODBCINI must be set to point to the fully qualified path name of
the system information file.

For example, to point to the location of the file for an


installation on /opt/odbc in the C shell, you would set this
variable as follows:

setenv ODBCINI /opt/odbc/odbc.ini

In the Bourne or Korn shell, you would set it as:

ODBCINI=/opt/odbc/odbc.ini;export ODBCINI

As an alternative, you can choose to make the system


information file a hidden file and not set the ODBCINI variable.
In this case, you would need to rename the file to .odbc.ini (to
make it a hidden file) and move it to the user’s $HOME directory.

The driver searches for the location of the system information


file as follows:

1 The driver checks the ODBCINI variable

2 The driver checks $HOME for .odbc.ini

If the driver does not locate the system information file, it


returns an error.

DataDirect Connect for ODBC Progress Supplement


22 Chapter 2 Configuring the Product on UNIX/Linux

ODBCINST
DataDirect Connect for ODBC Setup installs in the product
installation directory a default file, named odbcinst.ini, for use
with DSN-less connections. See “DSN-less Connections” on
page 33 for an explanation of the odbcinst.ini file. The system
administrator can choose to rename the file or move it to
another location. In either case, the environment variable
ODBCINST must be set to point to the fully qualified path name
of the odbcinst.ini file.

For example, to point to the location of the file for an installation


on /opt/odbc in the C shell, you would set this variable as follows:

setenv ODBCINST /opt/odbc/odbcinst.ini

In the Bourne or Korn shell, you would set it as:


ODBCINST=/opt/odbc/odbcinst.ini;export ODBCINST

As an alternative, you can choose to make the odbcinst.ini file a


hidden file and not set the ODBCINST variable. In this case, you
would need to rename the file to .odbcinst.ini (to make it a
hidden file) and move it to the user’s $HOME directory.

The driver searches for the location of the odbcinst.ini file as


follows:

1 The driver checks the ODBCINST variable


2 The driver checks $HOME for .odbcinst.ini

If the driver does not locate the odbcinst.ini file, it returns an


error.

DataDirect Connect for ODBC Progress Supplement


The ivtestlib Tool 23

DD_INSTALLDIR
This variable provides the driver with the location of the product
installation directory so that it can access support files.
DD_INSTALLDIR must be set to point to the fully qualified path
name of the installation directory.

For example, to point to the location of the directory for an


installation on /opt/odbc in the C shell, you would set this
variable as follows:

setenv DD_INSTALLDIR /opt/odbc

In the Bourne or Korn shell, you would set it as:

DD_INSTALLDIR=/opt/odbc;export DD_INSTALLDIR

The driver searches for the location of the installation directory


as follows:

1 The driver checks the DD_INSTALLDIR variable

2 The driver checks the odbc.ini or the odbcinst.ini files for the
InstallDir keyword (see “Configuration Through the System
Information File” on page 25 for a description of the
InstallDir keyword)

If the driver does not locate the installation directory, it returns


an error.

The next step is to test load the driver.

The ivtestlib Tool


The second step in preparing to use a driver is to test load it. The
ivtestlib tool is provided to test load drivers and help diagnose
configuration problems in the UNIX and Linux environments,
such as environment variables not correctly set or missing

DataDirect Connect for ODBC Progress Supplement


24 Chapter 2 Configuring the Product on UNIX/Linux

database client components. This tool is installed in the bin


subdirectory in the product installation directory. It attempts to
load a specified ODBC driver and prints out all available error
information if the load fails.

For example, if drivers are installed in /opt/odbc/lib, the following


command attempts to load the Progress Wire Protocol driver on
Solaris:

ivtestlib /opt/odbc/lib/ivoe1024.so

NOTE: On Solaris, AIX, and Linux, the full path to the driver does
not have to be specified for ivtestlib. The HP-UX version of
ivtestlib, however, requires the full path.

If the load is successful, ivtestlib returns a success message along


with the version string of the driver. If the driver cannot be
loaded, ivtestlib returns an error message explaining why.

The next step is to configure a data source through the system


information file.

Data Source Configuration


In the UNIX and Linux environments, a system information file is
used to store data source information. The DataDirect Connect
for ODBC product Setup installs a default version of this file, called
odbc.ini, in the product installation directory. This is a plain text
file that contains data source definitions. The Progress driver
package includes an additional file in the odbcini folder,
progodbc.ini, from which you can copy Progress data source
definitions into the main odbc.ini file. The Progress drivers do not
use the UNIX ODBC Administrator described in the DataDirect
Connect for ODBC and Connect XE for ODBC User’s Guide.

DataDirect Connect for ODBC Progress Supplement


Data Source Configuration 25

Configuration Through the System


Information File
To configure a data source, you edit the odbc.ini file with a text
editor. The content of the odbc.ini file is divided into three
sections.

At the beginning of the file is a section named [ODBC Data


Sources] containing data_source_name=installed-driver pairs.
Copy the appropriate Progress driver descriptions into this
section, for example:

Progress Wire Protocol=DataDirect 6.0 Progress Wire


Protocol.

The driver uses this section to match a data source to the


appropriate installed driver.

The [ODBC Data Sources] section also includes data source


definitions. The default odbc.ini contains a data source
definition for each driver. Each data source definition begins
with a data source name in square brackets. Copy the
appropriate Progress data source definitions into this section, for
example, the [Progress Wire Protocol] definition. The data
source definitions contain connection string attribute=value
pairs with default values. You can modify these values as
appropriate for your system. Descriptions of these attributes are
in each individual driver chapter.

The second section of the file is named [ODBC File DSN] and
includes one keyword:

[ODBC File DSN]


DefaultDSNDir=

This keyword defines the path of the default location for file
data sources (see “File Data Sources” on page 36).

DataDirect Connect for ODBC Progress Supplement


26 Chapter 2 Configuring the Product on UNIX/Linux

NOTE: This section is not included in the default odbc.ini that is


installed by the product installer. You can add this section
manually.

The third section of the file is named [ODBC] and includes several
keywords:
[ODBC]
IANAAppCodePage=4
InstallDir=ODBCHOME
Trace=0
TraceFile=odbctrace.out
TraceDll=ODBCHOME/lib/odbctrac.so

The IANAAppCodePage keyword defines the default value that


all UNIX/Linux drivers use if individual data sources have not
specified a different value. See the individual driver chapters and
refer to “Values for the Attribute IANAAppCodePage" in the
DataDirect Connect for ODBC and Connect XE for ODBC Reference
for details. The default value is 4.

The InstallDir keyword must be included in this section. The value


of this keyword is the path to the installation directory under
which the /lib and /messages directories are contained. The
installation process automatically writes your installation
directory to the default odbc.ini.

For example, if you choose an installation location of /opt/odbc,


then the following line is written to the [ODBC] section of the
default odbc.ini:
InstallDir=/opt/odbc

DataDirect Connect for ODBC Progress Supplement


Data Source Configuration 27

NOTE: If you are using only DSN-less connections through an


odbcinst.ini file and do not have an odbc.ini file, then you must
provide [ODBC] section information in the [ODBC] section of the
odbcinst.ini file. The drivers and Driver Manager always check
first in the [ODBC] section of an odbc.ini file. If no odbc.ini file or
[ODBC] section exists, they check for an [ODBC] section in the
odbcinst.ini file. See “DSN-less Connections” on page 33 for
details.

Tracing
ODBC tracing allows you to trace calls to ODBC drivers and
create a log of the traces for troubleshooting purposes.

The [ODBC] section of the system information file includes three


keywords related to tracing: Trace, TraceFile, and TraceDll. For
example:

Trace=1
TraceFile=odbctrace.out
TraceDll=ODBCHOME/lib/odbctrac.so

In this example, tracing is enabled, trace information is logged in


a file named odbctrace.out, and odbctrac.so performs the
tracing.

You enable tracing by setting the value of Trace to 1. Set the


value to 0 to disable tracing. Tracing continues until you disable
it. Be sure to turn off tracing when you are finished reproducing
the issue because tracing decreases the performance of your
ODBC application.

To specify the path and name of the trace log file, enter it as the
value for TraceFile. If no location is specified, the trace log
resides in the working directory of the application you are using.

DataDirect Technologies ships a default shared object,


odbctrac.so, to perform tracing. If you want to use a custom

DataDirect Connect for ODBC Progress Supplement


28 Chapter 2 Configuring the Product on UNIX/Linux

shared object instead, enter the path and name of the shared
object as the value for TraceDll.

For a more complete discussion of tracing, refer to “ODBC Trace”


in the DataDirect Connect for ODBC and Connect XE for ODBC
Troubleshooting Guide.

See “Sample Default System Information File” for an example of


the default odbc.ini file.

Sample Default System Information File


The following is an example of the progodbc.ini file that is
included the Progress driver package in the odbcini directory.
When copying and modifying these data source definitions,
replace all occurrences of ODBCHOME with your product
installation directory path. Values that you must supply are
enclosed by angle brackets (< >). You must supply the values and
remove the angle brackets before that data source section will
operate properly. Commented lines are denoted by the # symbol.

[ODBC Data Sources]


Progress Wire Protocol=DataDirect 6.0 Progress Wire Protocol.
Progress OpenEdge=DataDirect 6.0 Progress OpenEdge
Progress SQL92=DataDirect 6.0 Progress SQL92

[Progress Wire Protocol]


Driver=ODBCHOME/lib/ivoe1024.so
Description=DataDirect 6.0 Progress OpenEdge Wire Protocol
DatabaseName=<database_name>
EnableTimestampWithTimezone=1
HostName=<Progress_server>
LogonID=
Password=
PortNumber=<Progress_server_port>

DataDirect Connect for ODBC Progress Supplement


Data Source Configuration 29

[Progress OpenEdge]
Driver=ODBCHOME/lib/ivpro1024.so
Description=DataDirect 6.0 Progress OpenEdge
DatabaseName=<database_name>
EnableTimestampWithTimezone=1
HostName=<Progress_server>
LogonID=
Password=
PortNumber=<Progress_server_port>

[Progress SQL92]
Driver=ODBCHOME/lib/ivpro924.so
Description=DataDirect 6.0 Progress SQL92
DatabaseName=<database_name>
HostName=<Progress_server>
LogonID=
Password=
PortNumber=<Progress_server_port>

[ODBC]
IANAAppCodePage=4
InstallDir=ODBCHOME
Trace=0
TraceFile=odbctrace.out
TraceDll=ODBCHOME/lib/odbctrac.so

To modify or create data sources in the default odbc.ini file, use


the following procedures.

First, open the default odbc.ini. Then, open the progodbc.ini file
from which you can copy Progress data source descriptions and
definitions.

To modify a default Progress data source:

1 Using a text editor, open the odbc.ini file and the


progodbc.ini file
2 Copy the appropriate Progress data source descriptions and
definitions from progodbc.ini to odbc.ini.

DataDirect Connect for ODBC Progress Supplement


30 Chapter 2 Configuring the Product on UNIX/Linux

3 Modify the default attributes in the copied Progress data


source definitions as necessary based on your system specifics,
for example, enter the server name and port number of your
system in the appropriate location.
Consult the "Connection String Attributes" table of each
driver chapter for other specific attribute values.
4 After making all modifications, save the odbc.ini file and close
the text editor.

IMPORTANT: The "Connection String Attributes" table of each


driver chapter lists both the long and short name of the attribute.
When entering attribute names into odbc.ini, you must use the
long name of the attribute. The short name is not valid in the
odbc.ini file.

To create a new data source:

1 Using a text editor, open the odbc.ini file.


2 Copy an appropriate existing Progress default data source
definition and paste it to another location in the file.

3 Change the data source name in the copied data source


definition to a new name. The data source name is between
square brackets at the beginning of the definition, for
example, [Progress OpenEdge].

4 Modify the attributes in the new definition as necessary based


on your system specifics, for example, enter the server name
and port number of your system in the appropriate location.
Consult the "Connection String Attributes" table of each
driver chapter for other specific attribute values.

5 In the [ODBC] section at the beginning of the file, add a new


data_source_name=installed-driver pair containing the new
data source name and the appropriate installed driver name.

6 After making all modifications, save the odbc.ini file and close
the text editor.

DataDirect Connect for ODBC Progress Supplement


Data Source Configuration 31

IMPORTANT: The "Connection String Attributes" table of each


driver chapter lists both the long and short name of the
attribute. When entering attribute names into odbc.ini, you
must use the long name of the attribute. The short name is not
valid in the odbc.ini file.

Translators
DataDirect provides a sample translator named "OEM to ANSI"
that provides a framework for coding a translation library. Refer
to the readme.trn file in the /src/trn subdirectory in the product
installation directory for details.

To perform a translation with a particular driver, you must


include the TranslationSharedLibrary keyword in that driver’s
data source definition in the odbc.ini file. The
TranslationSharedLibrary keyword represents the full path to
the translation library.

For example:

[Progress Wire Protocol]


Driver=ODBCHOME/lib/ivoe1024.so
Description=DataDirect 6.0 Progress OpenEdge Wire Protocol
TranslationSharedLibrary=ODBCHOME/lib/ivtrn24.so

The TranslationOption keyword is the ASCII representation of


the 32-bit integer translation option. Use of the
TranslationOption keyword is optional.

DataDirect Connect for ODBC Progress Supplement


32 Chapter 2 Configuring the Product on UNIX/Linux

The demoodbc Application


DataDirect ships an application, named demoodbc, that is
installed in the demo subdirectory in the product installation
directory. Once you have set up your environment and data
source, use the demoodbc application to test your connection.
The syntax to run the application is:

demoodbc -uid user_name -pwd password data_source_name

For example:

demoodbc -uid johndoe -pwd secret DataSource3

The demoodbc application is coded to execute a Select statement


from a table named emp. If you have an emp table in your
database, the results are returned. If you do not have an emp
table, you receive the message: Invalid object name ’EMP’. This
message confirms a successful connection to the database.

Refer to the readme file in the demo subdirectory for an


explanation of how to build and use this application.

The example Application


DataDirect ships an application, named example, that is installed
in the example subdirectory in the product installation directory.
Once you have configured your environment and data source,
use the example application to test passing SQL statements. To
run the application, enter example and follow the prompts to
enter your data source name, user name, and password.

If successful, a SQL> prompt appears and you can type in SQL


statements, such as SELECT * FROM table_name. If example is
unable to connect to the database, an appropriate error message
appears.

DataDirect Connect for ODBC Progress Supplement


DSN-less Connections 33

Refer to the readme file in the example subdirectory for an


explanation of how to build and use this application.

DSN-less Connections
Connections to a data source can be made via a connection
string without referring to a data source name (DSN-less
connections). This is done by specifying the "DRIVER=" keyword
instead of the "DSN=" keyword in a connection string, as
outlined in the ODBC specification. A file named odbcinst.ini
must exist when the driver encounters DRIVER= in a connection
string.

DataDirect Connect for ODBC Setup installs a default version of


this file in the product installation directory (see “ODBCINST” on
page 22 for details about relocating and renaming this file). This
is a plain text file that contains default DSN-less connection
information. You must edit this file with a text editor to add the
Progress driver information. A file named progodbcinst.ini is
included in the Progress package file in the odbcini folder. You
must open this file with a text editor and copy its contents to the
appropriate location in the main odbcinst.ini file. The content of
progodbcinst.ini is divided into several sections.

At the beginning of the file is a section named [ODBC Drivers]


that lists installed drivers, for example,

DataDirect 6.0 Progress OpenEdge Wire Protocol=Installed

This section also includes additional information for each driver.

DataDirect Connect for ODBC Progress Supplement


34 Chapter 2 Configuring the Product on UNIX/Linux

To add the Progress drivers to odbcinst.ini, you must copy the


installed driver information from progodbcinst.ini to the
appropriate location in odbcinst.ini. Also, you must copy the
additional Progress driver information sections to the
appropriate locations in odbcinst.ini. For example, for the
Progress Wire Protocol driver, copy:

[DataDirect 6.0 Progress OpenEdge Wire Protocol]


Driver=ODBCHOME/lib/ivoe1024.so
APILevel=1
ConnectFunctions=YYN
DriverODBCVer=3.52
SQLLevel=0

When copying and modifying these data source definitions,


replace all occurrences of ODBCHOME with your product
installation directory path.

The final section of the file is named [ODBC]. The [ODBC] section in
the odbcinst.ini file fulfills the same purpose in DSN-less
connections as the [ODBC] section in the odbc.ini file does for
data source connections. See “Configuration Through the System
Information File” on page 25 for a description of the other
keywords this section.

NOTE: The odbcinst.ini file and the odbc.ini file include an [ODBC]
section. If the information in these two sections is not the same,
the values in the odbc.ini [ODBC] section override those of the
odbcinst.ini [ODBC] section.

DataDirect Connect for ODBC Progress Supplement


DSN-less Connections 35

Sample odbcinst.ini File


The following is an example of the progodbcinst.ini file in the
odbcini folder that is included the Progress driver package.
[ODBC Drivers]
DataDirect 6.0 Progress OpenEdge Wire Protocol=Installed
DataDirect 6.0 Progress OpenEdge=Installed
DataDirect 6.0 Progress SQL92=Installed

[DataDirect 6.0 Progress OpenEdge Wire Protocol]


Driver=ODBCHOME/lib/ivoe1024.so
APILevel=1
ConnectFunctions=YYN
DriverODBCVer=3.52
SQLLevel=0

[DataDirect 6.0 Progress OpenEdge]


Driver=ODBCHOME/lib/ivpro1024.so
APILevel=1
ConnectFunctions=YYN
DriverODBCVer=3.52
SQLLevel=0

[DataDirect 6.0 Progress SQL92]


Driver=ODBCHOME/lib/ivpro924.so
APILevel=1
ConnectFunctions=YYN
DriverODBCVer=3.52
SQLLevel=0

[ODBC]
#This section must contain values for DSN-less connections
#if no odbc.ini file exists. If an odbc.ini file exists,
#the values from that [ODBC] section are used.

DataDirect Connect for ODBC Progress Supplement


36 Chapter 2 Configuring the Product on UNIX/Linux

File Data Sources


The Driver Manager on UNIX and Linux supports file data sources.
The advantage of a file data source is that it can be stored on a
server and accessed by other machines, either Windows, UNIX, or
Linux. See “Quick Start Connect” on page 15 for a general
description of ODBC data sources on both Windows and
UNIX/LInux.

A file data source is simply a text file that contains connection


information. It can be created with a text editor. The file
normally has an extension of .dsn.

For example, a file data source for the Progress Wire Protocol
driver would be similar to the following:

[ODBC]
Driver=DataDirect 6.0 Progress OpenEdge Wire Protocol
PortNumber=2055
HostName=LOCALHOST
LogonID=JOHN
DatabaseName=Payroll

It must contain all basic connection information plus any optional


attributes. Because it uses the "DRIVER=" keyword, an
odbcinst.ini file containing the driver location must exist (see
“DSN-less Connections” on page 33).

The file data source is accessed by specifying the "FILEDSN="


instead of the "DSN=" keyword in a connection string, as
outlined in the ODBC specification. The complete path to the file
data source can be specified in the syntax that is normal for the
machine on which the file is located. For example, on UNIX and
Linux:

FILEDSN=/home/users/john/filedsn/Progresswp2.dsn

DataDirect Connect for ODBC Progress Supplement


File Data Sources 37

If no path is specified for the file data source, the Driver


Manager uses the [ODBC File DSN] setting in the odbc.ini file to
locate file data sources (see “Configuration Through the System
Information File” on page 25 for details). If the [ODBC File DSN]
setting is not defined, the Driver Manager uses the installation
directory setting in the odbc.ini file. The Driver Manager does
not support the SQLReadFileDSN and SQLWriteFileDSN
functions.

As with any connection string, you can specify attributes to


override the default values in the data source:

FILEDSN=/home/users/john/filedsn/Progresswp2.dsn;UID=james;PWD=test01

DataDirect Connect for ODBC Progress Supplement


38 Chapter 2 Configuring the Product on UNIX/Linux

DataDirect Connect for ODBC Progress Supplement


13

3 The Progress OpenEdge Wire


Protocol Driver

The DataDirect Connect for ODBC Progress OpenEdge Wire


Protocol driver (the Progress OpenEdge Wire Protocol driver)
supports:

Progress OpenEdge Release 10.1A and 10.1B

The Progress OpenEdge Wire Protocol driver is supported in the


Windows, UNIX, and Linux environments. See "Environment-
Specific Information" in the DataDirect Connect for ODBC and
Connect XE for ODBC User’s Guide for detailed information about
the environments supported by this driver.

See the readme file shipped with your DataDirect product for
the file name of the Progress OpenEdge Wire Protocol driver.

Driver Requirements
There are no client requirements for the Progress OpenEdge
Wire Protocol driver.

Configuring Data Sources


After you install the driver, you need to configure a data source
or use a connection string to connect to the database. If you
want to use a data source, but need to change some of its
values, you can either modify it or override its values through a

DataDirect Connect for ODBC Progress Supplement


40 Chapter 3 The Progress OpenEdge Wire Protocol Driver

connection string. See Chapter 1 "Quick Start Connect" on


page 15 for an explanation of different types of data sources.

If you choose to use a connection string, you must use specific


connection string attributes. See "Connecting to a Data Source
Using a Connection String" on page 46 and Table 3-1 on page 48
for a complete description of driver connection string attributes
and their values.

On UNIX and Linux, data sources are configured and modified by


editing the system information file (by default, odbc.ini) and
storing default connection values there. Refer to the Chapter 2
"Configuring the Product on UNIX/Linux" on page 19 for detailed
information about the specific steps needed to set up the UNIX
and Linux environments and to configure a data source.

Table 3-1 on page 48 lists driver connection string attributes that


must be used in the system information file. Note that only the
long name of the attribute can be used in the file.

On Windows, data sources are configured and modified through


the ODBC Administrator using a driver Setup dialog box. Default
connection values are specified through the options on the tabs
of the Setup dialog box. Connection string attributes that
override these options have the same names as the options unless
noted otherwise. The connection string attribute name does not
have spaces between the words. For example, the option name
Application Using Threads is equivalent to the connection string
attribute name ApplicationUsingThreads.

NOTE: By default, edit boxes and drop-down lists on the Setup


dialog box are empty unless a specific default is otherwise noted.

DataDirect Connect for ODBC Progress Supplement


Configuring Data Sources 41

To configure a Progress OpenEdge Wire Protocol data source on


Windows:

1 Start the ODBC Administrator; then, select a tab:

■ User DSN: If you are configuring an existing user data


source, select the data source name on the User DSN tab
and click Configure to display the driver Setup dialog box.

If you are configuring a new user data source, click Add


on the User DSN tab to display a list of installed drivers.
Select the Progress OpenEdge Wire Protocol driver and
click Finish to display the driver Setup dialog box.
■ System DSN: To configure a new system data source, click
Add on the System DSN tab to display a list of installed
drivers. Select the Progress OpenEdge Wire Protocol
driver and click Finish to display the driver Setup dialog
box.

■ File DSN: If you are configuring an existing file data


source, select the data source name on the File DSN tab
and click Configure to display the driver Setup dialog box.

If you are configuring a new file data source, click Add on


the File DSN tab to display a list of installed drivers. Select
the Progress OpenEdge Wire Protocol driver, and click
Next. Specify a name for the data source, and click Next.
Verify the data source information; then, click Finish to
display the driver Setup dialog box.

DataDirect Connect for ODBC Progress Supplement


42 Chapter 3 The Progress OpenEdge Wire Protocol Driver

The General tab of the Setup dialog box appears by default.

NOTE: The General tab displays only fields that are required for
creating a data source. The fields on all other tabs are optional,
unless noted otherwise.

2 On the General tab, provide the following information; then,


click Apply.

Data Source Name: Identifies this Progress OpenEdge data


source configuration. Examples include Accounting or
PROGServ1.

Description: An optional long description of a data source


name. For example, My Accounting Database or Progress on
Server number 1.

Host Name: The name of the system where the database is


stored.

Port Number: The system port number setup for the database
listener process.

DataDirect Connect for ODBC Progress Supplement


Configuring Data Sources 43

Database Name: The name of the database to which you


want to connect by default.

User ID: The default logon ID (user name) used to connect to


your Progress OpenEdge database. This ID is case-sensitive.
Your ODBC application may override this value or you may
override it in the Logon dialog box or connection string.

The equivalent connection string attribute is LogonID.

3 Optionally, click the Advanced tab to specify data source


settings.

On this tab, provide any of the following optional


information; then, click Apply.

Default Isolation Level: Select the default isolation level for


concurrent transactions. The values are READ COMMITTED,
READ UNCOMMITTED, REPEATABLE READ, and
SERIALIZABLE. The initial default is REPEATABLE READ.

DataDirect Connect for ODBC Progress Supplement


44 Chapter 3 The Progress OpenEdge Wire Protocol Driver

Fetch Array Size: The number of rows the driver retrieves


when fetching from the server. This is not the number of rows
given to the user. The default is 50 rows.

You should set this option to the approximate number of


rows being fetched. This reduces the number of round trips
on the network, thereby increasing performance.
This connection option can affect performance. See
"Performance Considerations" on page 50 for details.
The equivalent connection string attribute is ArraySize.

Enable Timestamp with Timezone: Select this check box to


expose timestamps with timezones to the application. By
default, the check box is selected.

When selected, the format is:


YYYY-MM-DD HH:MM:SS.SSS+HH:MM.

The equivalent connection string attribute is


EnableTimestampWithTimezone.

Use Wide Character Types: Select this check box to describe


character data types to the application as SQL_WCHAR. When
not selected, the default, character data types are described
to the application as SQL_CHAR.

4 At any point during the configuration process, you can click


Test Connect to attempt to connect to the data source using
the connection properties specified in the driver Setup dialog
box. A logon dialog box appears; see "Connecting to a Data
Source Using a Logon Dialog Box" on page 45 for details.

■ If the driver can connect, it releases the connection and


displays a "connection established" message. Click OK.

■ If the driver cannot connect because of an improper


environment or incorrect connection value, it displays an
appropriate error message.

Click OK.

DataDirect Connect for ODBC Progress Supplement


Connecting to a Data Source Using a Logon Dialog Box 45

5 Click OK or Cancel. If you click OK, the values you have


specified become the defaults when you connect to the data
source. You can change these defaults by using this
procedure to reconfigure your data source. You can override
these defaults by connecting to the data source using a
connection string with alternate values.

Connecting to a Data Source Using a Logon


Dialog Box
Some ODBC applications display a logon dialog box when you
are connecting to a data source. In these cases, the data source
name has already been specified.

In this dialog box, do the following:

1 In the Host Name field, type the name of the system where
the database is stored.

2 Type the Port Number setup for the database listener


process.

3 Type the name of the database to which you want to


connect.

DataDirect Connect for ODBC Progress Supplement


46 Chapter 3 The Progress OpenEdge Wire Protocol Driver

4 Type your user name.

5 Type your password.

6 Click OK to complete the logon.

Connecting to a Data Source Using a


Connection String
If you want to use a connection string for connecting to a
database, or if your application requires it, you must specify
either a DSN (data source name), a File DSN, or a DSN-less
connection in the string. The difference is whether you use the
DSN=, FILEDSN=, or the DRIVER= keyword in the connection
string, as described in the ODBC specification. A DSN or FILEDSN
connection string tells the driver where to find the default
connection information. Optionally, you may specify
attribute=value pairs in the connection string to override the
default values stored in the data source.

The DSN connection string has the form:

DSN=data_source_name[;attribute=value[;attribute=value]...]

The FILEDSN connection string has the form:

FILEDSN=filename.dsn[;attribute=value[;attribute=value]...]

The DSN-less connection string specifies a driver instead of a data


source. All connection information must be entered in the
connection string because no data source is storing the
information.

DataDirect Connect for ODBC Progress Supplement


Connecting to a Data Source Using a Connection String 47

The DSN-less connection string has the form:

DRIVER=[{]driver_name[}][;attribute=value[;attribute=value]
...]

Table 3-1 gives the long and short names for each attribute, as
well as a description. You can specify either long or short names
in the connection string. Connection string attribute names are
the same as the option names on the driver Setup dialog box
tabs unless otherwise noted. The connection string attribute
name does not have spaces between the words. For example, the
connection string attribute name ApplicationUsingThreads is
equivalent to the option name Application Using Threads.

The defaults listed in the table are initial defaults that apply
when no value is specified in either the data source definition or
in the connection string. If you specified a value for the attribute
when configuring the data source, that value is the default.

An example of a DSN connection string with overriding attribute


values for Progress OpenEdge is:

DSN=PROGRESS;DB=PAYROLL;UID=JOHN;PWD=XYZZY

A FILEDSN connection string is similar except for the initial


keyword:

FILEDSN=ProgOpen.dsn;DB=PAYROLL;UID=JOHN;PWD=XYZZY

A DSN-less connection string must provide all necessary


connection information:

DRIVER=DataDirect 6.0 Progress OpenEdge Wire


protocol;DB=PAYROLL;UID=JOHN;PWD=XYZZY;HOST=LOCALHOST;
PORT=2055

DataDirect Connect for ODBC Progress Supplement


48 Chapter 3 The Progress OpenEdge Wire Protocol Driver

Table 3-1. Progress OpenEdge Wire Protocol Connection String Attributes

Attribute Description
ArraySize (AS) The number of rows the driver retrieves from the server for a
fetch. This is not the number of rows given to the user. The
initial default is 50 rows.
You should set this connection string attribute to the
approximate number of rows being fetched. This reduces the
number of round trips on the network, thereby increasing
performance.
This attribute can affect performance. See "Performance
Considerations" on page 50 for details.
The equivalent Setup dialog box option is Fetch Array Size.
DatabaseName (DB) The name of the database to which you want to connect.
DataSourceName (DSN) A string that identifies a Progress OpenEdge data source
configuration. Examples include Accounting or PROG-Serv1.
DefaultIsolationLevel (DIL) DefaultIsolationLevel={READ COMMITTED | READ
UNCOMMITED | REPEATABLE READ | SERIALIZABLE}. Specifies
the default isolation level for concurrent transactions. The
initial default is REPEATABLE READ.
EnableTimestampWith EnableTimestampWithTimezone={0 | 1}. Determines whether
Timezone (ETWT) the driver exposes timestamps with timezones to the
application.
When set to 1 (the initial default), timestamps with
timezones are exposed to the application, and the format is
YYYY-MM-DD HH:MM:SS.SSS+HH:MM.
The equivalent Setup dialog box option is Enable Timestamp
with Timezone.
HostName (HOST) The name of the system where the database is stored.

DataDirect Connect for ODBC Progress Supplement


Connecting to a Data Source Using a Connection String 49

Table 3-1. Progress OpenEdge Wire Protocol Connection String Attributes (cont.)

IANAAppCodePage (IACP) For a list of valid values for this attribute, refer to the
DataDirect Connect for ODBC and Connect XE for ODBC
Reference. You need to set this attribute if your application
is not Unicode-enabled and/or if your database character set
is not Unicode (refer to the DataDirect Connect for ODBC and
Connect XE for ODBC Reference for details). The value you
specify must match the database character encoding and the
system locale.
The Driver Manager checks for the value of
IANAAppCodePage in the following order:
■ In the connection string
■ In the Data Source section of the system information file
(odbc.ini)
■ In the ODBC section of the system information file
(odbc.ini)
If no IANAAppCodePage value is found, the driver uses the
default value of 4 (ISO 8859-1 Latin-1).

LogonID (UID) The default logon ID (user name) used to connect to your
Progress OpenEdge database. This ID is case-sensitive.
The equivalent Setup dialog box option is User ID.
Password (PWD) A case-sensitive password.
PortNumber (PORT) The system port number setup for the database listener
process.
UseWideCharacterTypes UseWideCharacterTypes={0 | 1}. Determines whether
(UWCT) character data types are described to the application as
SQL_CHAR or SQL_WCHAR.
When set to 0 (the initial default), character data types are
described to the application as SQL_CHAR.
When set to 1, character data types are described to the
application as SQL_WCHAR.

DataDirect Connect for ODBC Progress Supplement


50 Chapter 3 The Progress OpenEdge Wire Protocol Driver

Performance Considerations
The following connection options can enhance driver
performance. You can also enhance performance through
efficient application design. Refer to the DataDirect Connect for
ODBC and Connect XE for ODBC Reference for details.

The option names found on the tabs of the driver Setup dialog
box are the same as the connection string attribute names unless
otherwise noted in parentheses. The connection string attribute
name does not have spaces between the words. For example, the
option name Application Using Threads is equivalent to the
connection string attribute name ApplicationUsingThreads.

Fetch Array Size (ArraySize): If your application fetches more


than 50 rows at a time, you should set Fetch Array Size to the
approximate number of rows being fetched. This reduces the
number of round trips on the network, thereby increasing
performance. For example, if your application normally fetches
200 rows, it is more efficient for the driver to fetch 200 rows at
one time over the network than to fetch 50 rows at a time during
four round trips over the network.

NOTE: The ideal setting for your application will vary. To


calculate the ideal setting for this option, you must know the size
in bytes of the rows that you are fetching and the size in bytes of
your Network Packet. Then, you must calculate the number of
rows that will fit in your Network Packet, leaving space for
packet overhead. For example, suppose your Network Packet size
is 1024 bytes and the row size is 8 bytes. Dividing 1024 by 8 equals
128; however, the ideal setting for Fetch Array Size is 127, not
128, because the number of rows times the row size must be
slightly smaller than the Network Packet size.

DataDirect Connect for ODBC Progress Supplement


Data Types 51

Data Types
Table 3-2 shows how the Progress OpenEdge data types are
mapped to the standard ODBC data types.

Table 3-2. Progress OpenEdge Data Types

OpenEdge ODBC
Bigint SQL_BIGINT
Binary SQL_BINARY
Bit SQL_BIT
Blob SQL_LONGVARBINARY
Clob SQL_LONGVARCHAR
Date SQL_TYPE_DATE
Decimal SQL_DECIMAL
Double precision SQL_DOUBLE
Float SQL_FLOAT
Integer SQL_INTEGER
Lvarbinary SQL_LONGVARBINARY
Lvarchar SQL_LONGVARCHAR
Real SQL_FLOAT
Smallint SQL_SMALLINT
Time SQL_TYPE_TIME
Timestamp SQL_TYPE_TIMESTAMP
Timestamp with Time Zone SQL_CHAR
Tinyint SQL_TINYINT
Varbinary SQL_VARBINARY
Varchar SQL_VARCHAR

DataDirect Connect for ODBC Progress Supplement


52 Chapter 3 The Progress OpenEdge Wire Protocol Driver

Refer to "Retrieving Data Type Information" in the DataDirect


Connect for ODBC and Connect XE for ODBC User’s Guide for
information about retrieving data types.

Unicode Support
This driver supports the Unicode ODBC W (Wide) function calls,
such as SQLConnectW. This allows the Driver Manager to transmit
these calls directly to the driver. Otherwise, the Driver Manager
would incur the additional overhead of converting the W calls to
ANSI function calls, and vice versa.

Refer to the DataDirect Connect for ODBC and Connect XE for ODBC
Reference for related details about UTF-16 applications on UNIX
and Linux, and for a more detailed explanation of the role of
Unicode in internationalization and localization.

Isolation and Lock Levels Supported


Progress OpenEdge supports isolation level 0 (READ
UNCOMMITTED), isolation level 1 (READ COMMITTED), isolation
level 2 (REPEATABLE READ), and isolation level 3 (SERIALIZABLE).

Refer to "Locking and Isolation Levels" in the DataDirect Connect


for ODBC and Connect XE for ODBC User’s Guide for details.

DataDirect Connect for ODBC Progress Supplement


ODBC Conformance Level 53

ODBC Conformance Level


The driver supports the function SQLSetPos. The driver also
supports the core SQL grammar.

Refer to "ODBC API and Scalar Functions" in the DataDirect


Connect for ODBC and Connect XE for ODBC User’s Guide for a list
of the API functions supported by the Progress OpenEdge Wire
Protocol driver.

Number of Connections and Statements


Supported
The Progress OpenEdge database system supports multiple
connections and multiple statements per connection.

Threading
The Progress drivers operate on a Thread Per Connect basis.

DataDirect Connect for ODBC Progress Supplement


54 Chapter 3 The Progress OpenEdge Wire Protocol Driver

DataDirect Connect for ODBC Progress Supplement


55

4 The Progress OpenEdge Driver

The DataDirect Connect for ODBC Progress OpenEdge driver (the


Progress OpenEdge driver) supports:

Progress OpenEdge Release 10.0B

The Progress OpenEdge driver is supported in the Windows,


UNIX, and Linux environments. See "Environment-Specific
Information" in the DataDirect Connect for ODBC and Connect XE
for ODBC User’s Guide for detailed information about the
environments supported by this driver.

See the readme file shipped with your DataDirect product for
the file name of the Progress OpenEdge driver.

Driver Requirements
To access a Progress OpenEdge Release 10 database with the
OpenEdge driver, your client must have the Progress
OpenEdge 10.0B client software installed.

NOTE: The Progress OpenEdge driver does not support Progress


databases created prior to OpenEdge Release 10.0B.

Before using the driver, you must set the DLC environment
variable to your OpenEdge DLC directory. For example:

set DLC=C:\OpenEdge

DataDirect Connect for ODBC Progress Supplement


56 Chapter 4 The Progress OpenEdge Driver

Configuring Data Sources


After you install the driver, you need to configure a data source
or use a connection string to connect to the database. If you want
to use a data source, but need to change some of its values, you
can either modify it or override its values through a connection
string. See Chapter 1 "Quick Start Connect" on page 15 for an
explanation of different types of data sources.

If you choose to use a connection string, you must use specific


connection string attributes. See "Connecting to a Data Source
Using a Connection String" on page 63 and Table 4-1 on page 64
for a complete description of driver connection string attributes
and their values.

Refer to "Quick Start Connect" in the DataDirect Connect for


ODBC and Connect XE for ODBC Reference for a detailed
explanation of different types of data sources.

On UNIX and Linux, data sources are configured and modified by


editing the system information file (by default, odbc.ini) and
storing default connection values there. Refer to the Chapter 2
"Configuring the Product on UNIX/Linux" on page 19 for detailed
information about the specific steps needed to set up the UNIX
and Linux environments and to configure a data source.

Table 4-1 on page 64 lists the connection values, in the form of


connection string attributes, that must be used in the system
information file. Note that only the long name of the attribute
can be used in the file.

On Windows, data sources are configured and modified through


the ODBC Administrator using a driver Setup dialog box. Default
connection values are specified through the options on the tabs
of the Setup dialog box. Connection string attributes that
override these options have the same names as the options unless
noted otherwise. The connection string attribute name does not
have spaces between the words. For example, the option name

DataDirect Connect for ODBC Progress Supplement


Configuring Data Sources 57

Application Using Threads is equivalent to the connection string


attribute name ApplicationUsingThreads.

NOTE: By default, edit boxes and drop-down lists on the Setup


dialog box are empty unless a specific default is otherwise noted.

To configure a Progress OpenEdge data source on Windows:


1 Start the ODBC Administrator; then, select a tab:

■ User DSN: If you are configuring an existing user data


source, select the data source name on the User DSN tab,
and click Configure to display the driver Setup dialog box.
If you are configuring a new user data source, click Add
on the User DSN tab to display a list of installed drivers.
Select the Progress OpenEdge driver, and click Finish to
display the driver Setup dialog box.
■ System DSN: To configure a new system data source, click
Add on the System DSN tab to display a list of installed
drivers. Select the Progress OpenEdge driver, and click
Finish to display the driver Setup dialog box.

■ File DSN: If you are configuring an existing file data


source, select the data source name on the File DSN tab
and click Configure to display the driver Setup dialog box.

If you are configuring a new file data source, click Add on


the File DSN tab to display a list of installed drivers. Select
the Progress OpenEdge driver, and click Next. Specify a
name for the data source, and click Next. Verify the data
source information; then, click Finish to display the driver
Setup dialog box.

DataDirect Connect for ODBC Progress Supplement


58 Chapter 4 The Progress OpenEdge Driver

The General tab of the Setup dialog box appears by default.

NOTE: The General tab displays only fields that are required
for creating a data source. The fields on all other tabs are
optional, unless noted otherwise.

2 On the General tab, provide the following information; then,


click Apply.

Data Source Name: Identifies this Progress OpenEdge data


source configuration. Examples include Accounting or
PROGServ1.
Description: An optional long description of a data source
name. For example, My Accounting Database or Progress on
Server number 1.

Host Name: The name of the system where the database is


stored.

Port Number: The system port number setup for the database
listener process.

DataDirect Connect for ODBC Progress Supplement


Configuring Data Sources 59

Database Name: The name of the database to which you


want to connect by default.

User ID: The default logon ID (user name) used to connect to


your Progress OpenEdge database. This ID is case-sensitive.
Your ODBC application may override this value or you may
override it in the Logon dialog box or connection string.

The equivalent connection string attribute is LogonID.

3 Optionally, click the Advanced tab to specify data source


settings.

On this tab, provide any of the following optional


information; then, click Apply.

DataDirect Connect for ODBC Progress Supplement


60 Chapter 4 The Progress OpenEdge Driver

Default Isolation Level: Select the default isolation level for


concurrent transactions. The values are READ COMMITTED,
READ UNCOMMITTED, REPEATABLE READ, and SERIALIZABLE.
The initial default is REPEATABLE READ.

Fetch Array Size: The number of rows the driver retrieves


when fetching from the server. This is not the number of rows
given to the user. The default is 50 rows.

You should set this option to the approximate number of


rows being fetched. This reduces the number of round trips
on the network, thereby increasing performance.

This connection option can affect performance. See


"Performance Considerations" on page 66 for details.

The equivalent connection string attribute is ArraySize.

Enable Timestamp with Time Zone: Select this check box to


expose timestamps with timezones to the application. By
default, the check box is selected.

When selected, the format is:


YYYY-MM-DD HH:MM:SS.SSS+HH:MM.

The equivalent connection string attribute is


EnableTimestampWithTimezone.

DataDirect Connect for ODBC Progress Supplement


Configuring Data Sources 61

4 At any point during the configuration process, you can click


Test Connect to attempt to connect to the data source using
the connection properties specified in the driver Setup dialog
box. A logon dialog box appears; see "Connecting to a Data
Source Using a Logon Dialog Box" on page 62 for details.

■ If the driver can connect, it releases the connection and


displays a "connection established" message. Click OK.

■ If the driver cannot connect because of an improper


environment or incorrect connection value, it displays an
appropriate error message.
Verify that all required client software is properly
installed. If it is not, you will see the message:
Specified driver could not be loaded due to system
error [xxx].
Click OK.
5 Click OK or Cancel. If you click OK, the values you have
specified become the defaults when you connect to the data
source. You can change these defaults by using this
procedure to reconfigure your data source. You can override
these defaults by connecting to the data source using a
connection string with alternate values.

DataDirect Connect for ODBC Progress Supplement


62 Chapter 4 The Progress OpenEdge Driver

Connecting to a Data Source Using a Logon


Dialog Box
Some ODBC applications display a logon dialog box when you are
connecting to a data source. In these cases, the data source name
has already been specified.

In this dialog box, do the following:


1 In the Host Name field, type the name of the system where
the database is stored.
2 Type the Port Number setup for the database listener process.

3 Type the name of the database to which you want to connect.

4 Type your user name.

5 Type your password.

6 Click OK to complete the logon.

DataDirect Connect for ODBC Progress Supplement


Connecting to a Data Source Using a Connection String 63

Connecting to a Data Source Using a


Connection String
If you want to use a connection string for connecting to a
database, or if your application requires it, you must specify
either a DSN (data source name), a File DSN, or a DSN-less
connection in the string. The difference is whether you use the
DSN=, FILEDSN=, or the DRIVER= keyword in the connection
string, as described in the ODBC specification. A DSN or FILEDSN
connection string tells the driver where to find the default
connection information. Optionally, you may specify
attribute=value pairs in the connection string to override the
default values stored in the data source.

The DSN connection string has the form:

DSN=data_source_name[;attribute=value[;attribute=value]...]

The FILEDSN connection string has the form:

FILEDSN=filename.dsn[;attribute=value[;attribute=value]...]

The DSN-less connection string specifies a driver instead of a


data source. All connection information must be entered in the
connection string because no data source is storing the
information.

The DSN-less connection string has the form:

DRIVER=[{]driver_name[}][;attribute=value[;attribute=value]
...]

Table 4-1 gives the long and short names for each attribute, as
well as a description. You can specify either long or short names
in the connection string. Connection string attribute names are
the same as the option names on the driver Setup dialog box
tabs unless otherwise noted. The connection string attribute
name does not have spaces between the words. For example, the

DataDirect Connect for ODBC Progress Supplement


64 Chapter 4 The Progress OpenEdge Driver

connection string attribute name ApplicationUsingThreads is


equivalent to the option name Application Using Threads.

The defaults listed in the table are initial defaults that apply
when no value is specified in either the data source definition or
in the connection string. If you specified a value for the attribute
when configuring the data source, that value is the default.

An example of a DSN connection string with overriding attribute


values for Progress OpenEdge is:

DSN=PROGRESS;DB=PAYROLL;UID=JOHN;PWD=XYZZY

A FILEDSN connection string is similar except for the initial


keyword:
FILEDSN=ProgOpen.dsn;DB=PAYROLL;UID=JOHN;PWD=XYZZY

A DSN-less connection string must provide all necessary


connection information:

DRIVER=DataDirect 6.0 Progress OpenEdge;DB=PAYROLL;


UID=JOHN;PWD=XYZZY;HOST=LOCALHOST;PORT=2055

Table 4-1. Progress OpenEdge Connection String Attributes

Attribute Description
ArraySize (AS) The number of rows the driver retrieves from the server for a
fetch. This is not the number of rows given to the user. The
initial default is 50 rows.
You should set this connection string attribute to the
approximate number of rows being fetched. This reduces the
number of round trips on the network, thereby increasing
performance.
This attribute can affect performance. See "Performance
Considerations" on page 66 for details.
The equivalent Setup dialog box option is Fetch Array Size.
DatabaseName (DB) The name of the database to which you want to connect.
DataSourceName (DSN) A string that identifies a Progress OpenEdge data source
configuration. Examples include Accounting or PROG-Serv1.

DataDirect Connect for ODBC Progress Supplement


Connecting to a Data Source Using a Connection String 65

Table 4-1. Progress OpenEdge Connection String Attributes (cont.)

DefaultIsolationLevel (DIL) DefaultIsolationLevel={READ COMMITTED | READ


UNCOMMITED | REPEATABLE READ | SERIALIZABLE}. Specifies
the default isolation level for concurrent transactions. The
initial default is REPEATABLE READ.
EnableTimestampWith EnableTimestampWithTimezone={0 | 1}. Determines whether
Timezone (ETWT) the driver exposes timestamps with timezones to the
application.
When set to 1 (the initial default), timestamps with
timezones are exposed to the application, and the format is
YYYY-MM-DD HH:MM:SS.SSS+HH:MM.
The equivalent Setup dialog box option is Enable Timestamp
with Timezone.
HostName (HOST) The name of the system where the database is stored.
IANAAppCodePage (IACP) For a list of valid values for this attribute, refer to the
DataDirect Connect for ODBC and Connect XE for ODBC
Reference. You need to set this attribute if your application
is not Unicode-enabled and/or if your database character set
is not Unicode (refer to the DataDirect Connect for ODBC and
Connect XE for ODBC Reference for details). The value you
specify must match the database character encoding and the
system locale.
The Driver Manager checks for the value of
IANAAppCodePage in the following order:
■ In the connection string
■ In the Data Source section of the system information file
(odbc.ini)
■ In the ODBC section of the system information file
(odbc.ini)
If no IANAAppCodePage value is found, the driver uses the
default value of 4 (ISO 8859-1 Latin-1).

LogonID (UID) The default logon ID (user name) used to connect to your
Progress OpenEdge database. This ID is case-sensitive.
The equivalent Setup dialog box option is User ID.

DataDirect Connect for ODBC Progress Supplement


66 Chapter 4 The Progress OpenEdge Driver

Table 4-1. Progress OpenEdge Connection String Attributes (cont.)

Password (PWD) A case-sensitive password.


PortNumber The system port number setup for the database listener
(PORT) process.

Performance Considerations
The following connection options can enhance driver
performance. You can also enhance performance through
efficient application design. Refer to the DataDirect Connect for
ODBC and Connect XE for ODBC Reference for details.

The option names found on the tabs of the driver Setup dialog
box are the same as the connection string attribute names unless
otherwise noted in parentheses. The connection string attribute
name does not have spaces between the words. For example, the
option name Application Using Threads is equivalent to the
connection string attribute name ApplicationUsingThreads.

Fetch Array Size (ArraySize): If your application fetches more


than 50 rows at a time, you should set Fetch Array Size to the
approximate number of rows being fetched. This reduces the
number of round trips on the network, thereby increasing
performance. For example, if your application normally fetches
200 rows, it is more efficient for the driver to fetch 200 rows at
one time over the network than to fetch 50 rows at a time during
four round trips over the network.

NOTE: The ideal setting for your application will vary. To calculate
the ideal setting for this option, you must know the size in bytes
of the rows that you are fetching and the size in bytes of your
Network Packet. Then, you must calculate the number of rows
that will fit in your Network Packet, leaving space for packet
overhead. For example, suppose your Network Packet size is 1024

DataDirect Connect for ODBC Progress Supplement


Data Types 67

bytes and the row size is 8 bytes. Dividing 1024 by 8 equals 128;
however, the ideal setting for Fetch Array Size is 127, not 128,
because the number of rows times the row size must be slightly
smaller than the Network Packet size.

Data Types
Table 4-2 shows how the Progress OpenEdge data types are
mapped to the standard ODBC data types.

Table 4-2. Progress OpenEdge Data Types

OpenEdge ODBC
Bigint SQL_BIGINT
Binary SQL_BINARY
Bit SQL_BIT
Blob SQL_LONGVARBINARY
Char SQL_CHAR
Clob SQL_LONGVARCHAR
Date SQL_TYPE_DATE
Decimal SQL_DECIMAL
Double precision SQL_DOUBLE
Float SQL_FLOAT
Integer SQL_INTEGER
Lvarbinary SQL_LONGVARBINARY
Lvarchar SQL_LONGVARCHAR
Real SQL_FLOAT
Smallint SQL_SMALLINT
Time SQL_TYPE_TIME
Timestamp SQL_TYPE_TIMESTAMP
Timestamp with Time Zone SQL_CHAR

DataDirect Connect for ODBC Progress Supplement


68 Chapter 4 The Progress OpenEdge Driver

Table 4-2. Progress OpenEdge Data Types (cont.)

Tinyint SQL_TINYINT
Varbinary SQL_VARBINARY
Varchar SQL_VARCHAR

Refer to "Retrieving Data Type Information" in the DataDirect


Connect for ODBC and Connect XE for ODBC User’s Guide for
information about retrieving data types.

Isolation and Lock Levels Supported


Progress OpenEdge supports isolation level 0 (READ
UNCOMMITTED), isolation level 1 (READ COMMITTED), isolation
level 2 (REPEATABLE READ), and isolation level 3 (SERIALIZABLE).

Refer to "Locking and Isolation Levels" in the DataDirect Connect


for ODBC and Connect XE for ODBC User’s Guide for details.

ODBC Conformance Level


The driver supports the function SQLSetPos.

Refer to "ODBC API and Scalar Functions" in the DataDirect


Connect for ODBC and Connect XE for ODBC User’s Guide for a list of
the API functions supported by the Progress OpenEdge driver.
The driver supports the core SQL grammar.

DataDirect Connect for ODBC Progress Supplement


Number of Connections and Statements Supported 69

Number of Connections and Statements


Supported
The Progress OpenEdge database system supports multiple
connections and multiple statements per connection.

Threading
The Progress drivers operate on a Thread Per Connect basis.

DataDirect Connect for ODBC Progress Supplement


70 Chapter 4 The Progress OpenEdge Driver

DataDirect Connect for ODBC Progress Supplement


71

5 The Progress SQL92 Driver

The DataDirect Connect for ODBC Progress SQL92 driver (the


Progress SQL92 driver) supports:

Progress Version 9.1D and 9.1E

The Progress SQL92 driver is supported in the Windows, UNIX,


and Linux environments. See "Environment-Specific
Information" in the DataDirect Connect for ODBC and Connect XE
for ODBC User’s Guide for detailed information about the
environments supported by this driver.

See the readme file shipped with your DataDirect product for
the file name of the Progress SQL92 driver.

Driver Requirements
To access a Progress Version 9.1D or 9.1E database with the
Progress SQL92 driver, your system must have the following
software installed:

■ On the client computer: Progress SQL92 Client Access


version 9.1D or 9.1E

■ On the server computer: Progress Version 9.1D or 9.1E

NOTE: The Progress SQL92 driver does not support Progress


databases prior to Progress Version 9.1D and does not support
Progress OpenEdge Release 10 databases.

DataDirect Connect for ODBC Progress Supplement


72 Chapter 5 The Progress SQL92 Driver

Before using the driver, you must set the DLC environment
variable to your Progress DLC directory. For example:

set DLC=C:\PROGRESS

Configuring Data Sources


After you install the driver, you need to configure a data source
or use a connection string to connect to the database. If you want
to use a data source, but need to change some of its values, you
can either modify it or override its values through a connection
string. See Chapter 1 "Quick Start Connect" on page 15 for an
explanation of different types of data sources.

If you choose to use a connection string, you must use specific


connection string attributes. See "Connecting to a Data Source
Using a Connection String" on page 78 and Table 5-1 on page 80
for a complete description of driver connection string attributes
and their values.

Refer to "Quick Start Connect" in the DataDirect Connect for


ODBC and Connect XE for ODBC Reference for a detailed
explanation of different types of data sources.

On UNIX and Linux, data sources are configured and modified by


editing the system information file (by default, odbc.ini) and
storing default connection values there. Refer to the Chapter 2
"Configuring the Product on UNIX/Linux" on page 19 for detailed
information about the specific steps needed to set up the UNIX
and Linux environments and to configure a data source.

Table 5-1 on page 80 lists the connection values, in the form of


connection string attributes, that must be used in the system
information file. Note that only the long name of the attribute
can be used in the file.

DataDirect Connect for ODBC Progress Supplement


Configuring Data Sources 73

On Windows, data sources are configured and modified through


the ODBC Administrator using a driver Setup dialog box. Default
connection values are specified through the options on the tabs
of the Setup dialog box. Connection string attributes that
override these options have the same names as the options
unless noted otherwise. The connection string attribute name
does not have spaces between the words. For example, the
option name Application Using Threads is equivalent to the
connection string attribute name ApplicationUsingThreads.

NOTE: By default, edit boxes and drop-down lists on the Setup


dialog box are empty unless a specific default is otherwise noted.

To configure a Progress SQL92 data source on Windows:

1 Start the ODBC Administrator; then, select a tab:

■ User DSN: If you are configuring an existing user data


source, select the data source name on the User DSN tab
and click Configure to display the driver Setup dialog box.

If you are configuring a new user data source, click Add


on the User DSN tab to display a list of installed drivers.
Select the Progress SQL92 driver, and click Finish to
display the driver Setup dialog box.
■ System DSN: To configure a new system data source, click
Add on the System DSN tab to display a list of installed
drivers. Select the Progress SQL92 driver, and click Finish
to display the driver Setup dialog box.

■ File DSN: If you are configuring an existing file data


source, select the data source name on the File DSN tab,
and click Configure to display the driver Setup dialog box.

If you are configuring a new file data source, click Add on


the File DSN tab to display a list of installed drivers. Select
the Progress SQL92 driver, and click Next. Specify a name
for the data source, and click Next. Verify the data source
information; then, click Finish to display the driver Setup
dialog box.

DataDirect Connect for ODBC Progress Supplement


74 Chapter 5 The Progress SQL92 Driver

The General tab of the Setup dialog box appears by default.

NOTE: The General tab displays only fields that are required
for creating a data source. The fields on all other tabs are
optional, unless noted otherwise.

2 On the General tab, provide the following information; then,


click Apply.

Data Source Name: Identifies this Progress SQL92 data source


configuration. Examples include Accounting or PROGServ1.

Description: An optional long description of a data source


name. For example, My Accounting Database or Progress on
Server number 1.

Host Name: The name of the system where the database is


stored.

Port Number: The system port number setup for the database
listener process.

DataDirect Connect for ODBC Progress Supplement


Configuring Data Sources 75

Database Name: The name of the database to which you


want to connect by default.

User ID: The default logon ID (user name) used to connect to


your Progress SQL92 database. This ID is case-sensitive. Your
ODBC application may override this value or you may
override it in the Logon dialog box or connection string.

The equivalent connection string attribute is LogonID.

3 Optionally, click the Advanced tab to specify data source


settings.

On this tab, provide any of the following optional


information; then, click Apply.

Default Isolation Level: Select the default isolation level for


concurrent transactions. The values are READ COMMITTED,
READ UNCOMMITTED, REPEATABLE READ, and
SERIALIZABLE. The initial default is REPEATABLE READ.

DataDirect Connect for ODBC Progress Supplement


76 Chapter 5 The Progress SQL92 Driver

Fetch Array Size: The number of rows the driver retrieves


when fetching from the server. This is not the number of rows
given to the user. The default is 50 rows.

You should set this option to the approximate number of


rows being fetched. This reduces the number of round trips
on the network, thereby increasing performance.
This connection option can affect performance. See
"Performance Considerations" on page 82 for details.
The equivalent connection string attribute is ArraySize.

4 At any point during the configuration process, you can click


Test Connect to attempt to connect to the data source using
the connection properties specified in the driver Setup dialog
box. A logon dialog box appears; see "Connecting to a Data
Source Using a Logon Dialog Box" on page 77 for details.

■ If the driver can connect, it releases the connection and


displays a "connection established" message. Click OK.

■ If the driver cannot connect because of an improper


environment or incorrect connection value, it displays an
appropriate error message.

Verify that all required client software is properly


installed. If it is not, you will see the message:
Specified driver could not be loaded due to system
error [xxx].
Click OK.
5 Click OK or Cancel. If you click OK, the values you have
specified become the defaults when you connect to the data
source. You can change these defaults by using this procedure
to reconfigure your data source. You can override these
defaults by connecting to the data source using a connection
string with alternate values.

DataDirect Connect for ODBC Progress Supplement


Connecting to a Data Source Using a Logon Dialog Box 77

Connecting to a Data Source Using a Logon


Dialog Box
Some ODBC applications display a logon dialog box when you
are connecting to a data source. In these cases, the data source
name has already been specified.

In this dialog box, do the following:


1 In the Host Name field, type the name of the system where
the database is stored.
2 Type the Port Number setup for the database listener
process.
3 Type the name of the database to which you want to
connect.

4 Type your user name.

5 Type your password.

6 Click OK to complete the logon.

DataDirect Connect for ODBC Progress Supplement


78 Chapter 5 The Progress SQL92 Driver

Connecting to a Data Source Using a


Connection String
If you want to use a connection string for connecting to a
database, or if your application requires it, you must specify
either a DSN (data source name), a File DSN, or a DSN-less
connection in the string. The difference is whether you use the
DSN=, FILEDSN=, or the DRIVER= keyword in the connection
string, as described in the ODBC specification. A DSN or FILEDSN
connection string tells the driver where to find the default
connection information. Optionally, you may specify
attribute=value pairs in the connection string to override the
default values stored in the data source.

The DSN connection string has the form:

DSN=data_source_name[;attribute=value[;attribute=value]...]

The FILEDSN connection string has the form:

FILEDSN=filename.dsn[;attribute=value[;attribute=value]...]

The DSN-less connection string specifies a driver instead of a data


source. All connection information must be entered in the
connection string because no data source is storing the
information.

The DSN-less connection string has the form:

DRIVER=[{]driver_name[}][;attribute=value[;attribute=value]
...]

Table 5-1 gives the long and short names for each attribute, as
well as a description. You can specify either long or short names
in the connection string. Connection string attribute names are
the same as the option names on the driver Setup dialog box tabs
unless otherwise noted. The connection string attribute name
does not have spaces between the words. For example, the

DataDirect Connect for ODBC Progress Supplement


Connecting to a Data Source Using a Connection String 79

connection string attribute name ApplicationUsingThreads is


equivalent to the option name Application Using Threads.

The defaults listed in the table are initial defaults that apply
when no value is specified in either the data source definition or
in the connection string. If you specified a value for the attribute
when configuring the data source, that value is the default.

An example of a DSN connection string with overriding attribute


values for Progress SQL92 is:

DSN=PROGRESS;DB=PAYROLL;UID=JOHN;PWD=XYZZY

A FILEDSN connection string is similar except for the initial


keyword:

FILEDSN=Prog92.dsn;DB=PAYROLL;UID=JOHN;PWD=XYZZY

A DSN-less connection string must provide all necessary


connection information:
DRIVER=DataDirect 6.0 Progress SQL92;DB=PAYROLL;
UID=JOHN;PWD=XYZZY;HOST=LOCALHOST;PORT=2055

DataDirect Connect for ODBC Progress Supplement


80 Chapter 5 The Progress SQL92 Driver

Table 5-1. Progress SQL92 Connection String Attributes

Attribute Description
ArraySize (AS) The number of rows the driver retrieves from the server for a
fetch. This is not the number of rows given to the user. The
initial default is 50 rows.
You should set this connection string attribute to the
approximate number of rows being fetched. This reduces the
number of round trips on the network, thereby increasing
performance.
This attribute can affect performance. See "Performance
Considerations" on page 82 for details.
The equivalent Setup dialog box option is Fetch Array Size.
DatabaseName (DB) The name of the database to which you want to connect.
DataSourceName (DSN) A string that identifies a Progress data source configuration.
Examples include Accounting or PROG-Serv1.
DefaultIsolationLevel (DIL) DefaultIsolationLevel={READ COMMITTED | READ
UNCOMMITED | REPEATABLE READ | SERIALIZABLE}. Specifies
the default isolation level for concurrent transactions. The
initial default is REPEATABLE READ.
HostName (HOST) The name of the system where the database is stored.

DataDirect Connect for ODBC Progress Supplement


Connecting to a Data Source Using a Connection String 81

Table 5-1. Progress SQL92 Connection String Attributes (cont.)

IANAAppCodePage (IACP) For a list of valid values for this attribute, refer to the
DataDirect Connect for ODBC and Connect XE for ODBC
Reference. You need to set this attribute if your application
is not Unicode-enabled and/or if your database character set
is not Unicode (refer to the DataDirect Connect for ODBC and
Connect XE for ODBC Reference for details). The value you
specify must match the database character encoding and the
system locale.
The Driver Manager checks for the value of
IANAAppCodePage in the following order:
■ In the connection string
■ In the Data Source section of the system information file
(odbc.ini)
■ In the ODBC section of the system information file
(odbc.ini)
If no IANAAppCodePage value is found, the driver uses the
default value of 4 (ISO 8859-1 Latin-1).

LogonID (UID) The default logon ID (user name) used to connect to your
Progress SQL92 database. This ID is case-sensitive.
The equivalent Setup dialog box option is User ID.
Password (PWD) A case-sensitive password.
PortNumber The system port number setup for the database listener
(PORT) process.

DataDirect Connect for ODBC Progress Supplement


82 Chapter 5 The Progress SQL92 Driver

Performance Considerations
The following connection options can enhance driver
performance. You can also enhance performance through
efficient application design. Refer to the DataDirect Connect for
ODBC and Connect XE for ODBC Reference for details.

The option names found on the tabs of the driver Setup dialog
box are the same as the connection string attribute names unless
otherwise noted in parentheses. The connection string attribute
name does not have spaces between the words. For example, the
option name Application Using Threads is equivalent to the
connection string attribute name ApplicationUsingThreads.

Fetch Array Size (ArraySize): If your application fetches more


than 50 rows at a time, you should set Fetch Array Size to the
approximate number of rows being fetched. This reduces the
number of round trips on the network, thereby increasing
performance. For example, if your application normally fetches
200 rows, it is more efficient for the driver to fetch 200 rows at
one time over the network than to fetch 50 rows at a time during
four round trips over the network.

NOTE: The ideal setting for your application will vary. To calculate
the ideal setting for this option, you must know the size in bytes
of the rows that you are fetching and the size in bytes of your
Network Packet. Then, you must calculate the number of rows
that will fit in your Network Packet, leaving space for packet
overhead. For example, suppose your Network Packet size is 1024
bytes and the row size is 8 bytes. Dividing 1024 by 8 equals 128;
however, the ideal setting for Fetch Array Size is 127, not 128,
because the number of rows times the row size must be slightly
smaller than the Network Packet size.

DataDirect Connect for ODBC Progress Supplement


Data Types 83

Data Types
Table 5-2 shows how the Progress SQL92 data types are mapped
to the standard ODBC data types.

Table 5-2. Progress SQL92 Data Types

Progress SQL92 ODBC


Bigint SQL_BIGINT
Binary SQL_BINARY
Bit SQL_BIT
Char SQL_CHAR
Date SQL_TYPE_DATE
Decimal SQL_DECIMAL
Double precision SQL_DOUBLE
Float SQL_FLOAT
Integer SQL_INTEGER
Lvarbinary SQL_LONGVARBINARY
Real SQL_FLOAT
Smallint SQL_SMALLINT
Time SQL_TYPE_TIME
Timestamp SQL_TYPE_TIMESTAMP
Tinyint SQL_TINYINT
Varbinary SQL_VARBINARY
Varchar SQL_VARCHAR

Refer to "Retrieving Data Type Information" in the DataDirect


Connect for ODBC and Connect XE for ODBC User’s Guide for
information about retrieving data types.

DataDirect Connect for ODBC Progress Supplement


84 Chapter 5 The Progress SQL92 Driver

Isolation and Lock Levels Supported


Progress SQL92 supports isolation level 0 (READ UNCOMMITTED),
isolation level 1 (READ COMMITTED), isolation level 2
(REPEATABLE READ), and isolation level 3 (SERIALIZABLE).

Refer to "Locking and Isolation Levels" in the DataDirect Connect


for ODBC and Connect XE for ODBC User’s Guide for details.

ODBC Conformance Level


The driver supports the function SQLSetPos.

Refer to "ODBC API and Scalar Functions" in the DataDirect


Connect for ODBC and Connect XE for ODBC User’s Guide for a list of
the API functions supported by the Progress SQL92 driver. The
driver supports the core SQL grammar.

Number of Connections and Statements


Supported
The Progress SQL92 database system supports multiple
connections and multiple statements per connection.

Threading
The Progress drivers operate on a Thread Per Connect basis.

DataDirect Connect for ODBC Progress Supplement


85

Index

A connecting via connection string


Progress OpenEdge 63
Progress OpenEdge Wire Protocol 46
AIX Progress SQL92 78
See UNIX and Linux connecting via logon dialog box
ArraySize Progress OpenEdge 62
Progress OpenEdge 64 Progress OpenEdge Wire Protocol 45
Progress OpenEdge Wire Protocol 48 Progress SQL92 77
Progress SQL92 80 data types
Progress OpenEdge 67
Progress OpenEdge Wire Protocol 51
Progress SQL92 83
C DatabaseName
Progress OpenEdge 64
connection string attributes Progress OpenEdge Wire Protocol 48
Progress OpenEdge 64 Progress SQL92 80
Progress OpenEdge Wire Protocol 48 DataDirect Connect for ODBC drivers
Progress SQL92 80 Progress OpenEdge 55
connections supported Progress OpenEdge Wire Protocol 39
Progress OpenEdge 69 Progress SQL92 71
Progress OpenEdge Wire Protocol 53 DataSourceName
Progress SQL92 84 Progress OpenEdge 64
contacting Technical Support 13 Progress OpenEdge Wire Protocol 48
conventions, typographical 9 Progress SQL92 80
DefaultIsolationLevel
Progress OpenEdge 65
Progress OpenEdge Wire Protocol 48
D Progress SQL92 80
demoodbc application 32
data source documentation, about 11
configuring driver requirements
Progress OpenEdge 56 Progress OpenEdge 55
Progress OpenEdge Wire Protocol 39 Progress OpenEdge Wire Protocol 39
Progress SQL92 72 Progress SQL92 71
UNIX and Linux 24

DataDirect Connect for ODBC Progress Supplement


86

E Progress OpenEdge 65
Progress OpenEdge Wire Protocol 49
Progress SQL92 81
EnableTimestamp
Progress OpenEdge 65
Progress OpenEdge Wire Protocol 48
environment-specific information 10 O
ODBC conformance
H Progress OpenEdge 68
Progress OpenEdge Wire Protocol 53
Progress SQL92 84
HostName OEM to ANSI translation 31
Progress OpenEdge 65
Progress OpenEdge Wire Protocol 48
Progress SQL92 80
HP-UX
See UNIX and Linux
P
Password
Progress OpenEdge 66
I Progress OpenEdge Wire Protocol 49
Progress SQL92 81
PortNumber
IANAAppCodePage Progress OpenEdge 66
Progress OpenEdge 65 Progress OpenEdge Wire Protocol 49
Progress OpenEdge Wire Protocol 49 Progress SQL92 81
Progress SQL92 81 Progress OpenEdge driver
isolation levels See also Progress OpenEdge Wire Protocol
Progress OpenEdge 68 driver
Progress OpenEdge Wire Protocol 52 connection string attributes 64
Progress SQL92 84 connections supported 69
ivtestlib tool 23 data source
configuring 56
connecting via connection string 63
connecting via logon dialog box 62
L data types 67
driver requirements 55
Linux isolation levels 68
See UNIX and Linux locking levels 68
locking levels ODBC conformance 68
Progress OpenEdge 68 statements supported 69
Progress OpenEdge Wire Protocol 52 threading 69
Progress SQL92 84
LogonID

DataDirect Connect for ODBC Progress Supplement


87

Progress OpenEdge Wire Protocol driver


See also Progress OpenEdge driver
T
connection string attributes 48
connections supported 53 Technical Support, contacting 13
data source translators 31
configuring 39 typographical conventions 9
connecting via connection string 46
connecting via logon dialog box 45
data types 51
driver requirements 39 U
isolation levels 52
locking levels 52 Unicode support (Progress OpenEdge Wire
ODBC conformance 53 Protocol) 52
statements supported 53 UNIX and Linux
threading 53 data source configuration 24
Unicode support 52 drivers
Progress SQL92 driver Progress OpenEdge 55
connection string attributes 80 Progress OpenEdge Wire Protocol 39
connections supported 84 Progress SQL92 71
data source environment
configuring 72 DD_INSTALLER 23
connecting via connection string 78 introduction 19
connecting via logon dialog box 77 ivtestlib tool 23
data types 83 library search path 20
driver requirements 71 ODBCINST 22
isolation levels 84 system information file (.odbc.ini) 24
locking levels 84 variables 19
ODBC conformance 84 versions supported 7
statements supported 84 UseWideCharacterTypes, Progress OpenEdge
threading 84 Wire Protocol 49

S W
Solaris Windows
See UNIX and Linux drivers
statements supported Progress OpenEdge 55
Progress OpenEdge 69 Progress OpenEdge Wire Protocol 39
Progress OpenEdge Wire Protocol 53 Progress SQL92 71
Progress SQL92 84
SupportLink 13
system information file (.odbc.ini) 24

DataDirect Connect for ODBC Progress Supplement