How to Install and Configure the Multi-Tier Edition JDBC Driver for Informix, on macOS

Get the Informix JDBC driver

A guide for installing the Multi-Tier Edition JDBC Driver for Informix data sources, on macOS.

Before you install

Requirements for Informix

What Informix and its client software must provide before the driver connects.

Pre-Requisites for Connections to Informix

Do OpenLink drivers connect to Informix?

Yes. OpenLink produces data access drivers that connect to Informix.

Informix version support

OpenLink's drivers provide support for Informix v7 onward.

Detecting the Informix DBMS version

For best results, OpenLink components should be chosen to correspond to the Informix DBMS engine. Sometimes, these need not match, but please consult OpenLink Support about your specific scenario.

To learn the Informix DBMS engine version, ensure the Informix environment variables are set, and run $INFORMIXDIR/bin/onstat -V on Unix, or onstat -V from a DOS prompt on Windows.
Example
```
bash-2.05b$ ./onstat -V
Informix Dynamic Server Version 7.31.UC2  Software Serial Number AAD#J249082
```
To learn the "esql" client library version, ensure the Informix environment variables are set, and run $INFORMIXDIR/bin/esql -V on Unix, or esql -V from a DOS prompt on Windows.
Example
```
bash-2.05b$ ./esql -V
IBM Informix CSDK Version 2.81, IBM Informix-ESQL Version 9.53.HC3
Software Serial Number RDS#N000000
```
Windows users may also find this information in the "About Setnet32" tab of the Informix Setnet utility (Start menu >> Programs >> INFORMIX-Connect or INFORMIX-Client SDK).

Understanding the Informix native client

The Informix native client is an IBM product that provides access to Informix databases via the Informix proprietary communications protocol. At the time of writing, this product is called INFORMIX-Connect. However, marketing names are subject to change. In fact, the same product is often referred to as Informix-Net or I-Net.

When do I need the Informix native client?

There are two scenarios in which you would require the Informix native client. You must install the Informix client on the same machine as any Informix Single-Tier driver. Additionally, you must install the Informix client on the same machine as OpenLink's Multi-Tier Request Broker and Informix Database Agent, if the Broker and Informix Agent do not reside on the same machine as the Informix database.

Obtain the Informix native client (a.k.a "Informix Connect", "Informix-Net" "I-Net")

OpenLink Software does not supply the Informix native client. Instead, the Informix native client should ship with the standard Informix DBMS install media. At the time of writing, staff notes that the Informix native client appears on the Informix SDK CDs. However, packaging and marketing labels are subject to change.

If you do not have the Informix client install CD, you should visit the IBM Software Mall to see if the appropriate Informix client version is available for download.

Configure the Informix native client

Perform the following steps on Windows:

1. Expand the Start menu.

2. Expand the Programs menu.

3. Expand the INFORMIX-Connect folder.

4. Launch Informix Setnet32.

5. Click the Environment tab.

6. Pass the full path to the Informix client installation to the INFORMIXDIR variable.

7. Pass the name of the Informix DBMS server (not physical machine) to INFORMIXSERVER.

8. Click the Server Information tab.

9. Pass the name of the Informix DBMS server (not physical machine) to Informix Server.

10. Pass the hostname of the physical Informix server to HostName.

11. Pass the Informix protocol (olsoctcp, onsoctcp) to Protocolname.

12. Pass the service name from /etc/services or \etc\servicse to Service Name.

13. Click the Host Information tab.

14. Pass the hostname of the physical Informix server to Current Host.

15. Pass the Informix username to User Name.

16. Select your password option.

17. Provide a password, as required.

18. Close Informix Setnet32.

19. Expand the Start menu.

20. Expand the Programs menu.

21. Expand the INFORMIX-Connect folder.

22. Launch ILogin Demo.

23. Expand the File menu.

24. Select Run.

25. Fill in the values.

26. Click OK.

Perform the following steps on Unix:

1. Login to the Unix client.

2. su to the Informix user.

3. cd into the root of the Informix client installation.

4. Run the Informix user's .profile.

5. cd into the /etc sub-directory of the Informix installation.

6. vi sqlhosts.

7. Create one line that passes the: Informix DBMS server name, Informix protocol, hostname of Informix server, Informix service from services file.

8. Exit sqlhosts.

Here is a sample Unix $INFORMIXDIR/etc/sqlhosts file:

Example

ol_saturn olsoctcp saturn.testserver.com inf9srv

Note: Don't know what values to pass to Informix SetNet32 or $INFORMIXDIR/etc/sqlhosts? If your Informix server is running on Unix, you will find the appropriate values in the server's /etc/services, Informix .profile, and $INFORMIXDIR/etc/sqlhosts files. If your Informix server is running on Windows, you will find the appropriate values in the server's C:\Windows \System32\Drivers\etc\services file, the Server Instance Manager (Start Menu), and the $INFORMIXDIR\etc\onconfig file.

INFORMIXDIR

The INFORMIXDIR environment variable passes the full path to the root of the Informix installation.

INFORMIXSERVER

The INFORMIXSERVER environment variable passes the name of the Informix server. This is not the physical machine that hosts Informix. This is the name of the Informix DBMS server, which appears in the Informix Server Instances utility (Windows), Informix user .profile (Unix), and $INFORMIXDIR/etc/sqlhosts file.

Identify the Informix instance name

Unix Database Servers

Log in to your Unix database server as the Informix user.
Ensure the Informix environment is correctly set.
Execute this command:
Shell
```
echo $INFORMIXSERVER
```
This should be your Informix instance name. There should be an entry in the $INFORMIXDIR/etc/sqlhosts file that starts with the same $INFORMIXSERVER value.

Note -- there may be multiple $INFORMIXSERVER values, and multiple Informix instances, on a single host.

Windows Database Servers

Log in to your Windows database server.
Launch the Registry Editor (Start menu >> Run... >> regedit)

Drill down to

Registry

HKEY_LOCAL_MACHINE\
SOFTWARE\
INFORMIX\
SQLHOSTS

There should be one or more sub-folders. Each sub-folder represents an Informix instance.

Identify the Informix startup mode (i.e., sockets or shared memory)

Unix Database Servers

Log in to your Unix database server as the Informix user.
Set the Informix environment, if not automatically set by the login.
Execute this command:
Shell
```
echo $INFORMIXSERVER
```
Execute this command:
Shell
```
cat $INFORMIXDIR/etc/sqlhosts
```
Look for the line that begins with the $INFORMIXSERVER value, and note the value that appears in the second column.
- If this value is onsoctcp, ontlitcp, or anything else containing tcp, this $INFORMIXSERVER will accept sockets-based connections.
- If this value is onipcshm, or anything else containing shm, this $INFORMIXSERVER will not accept sockets-based connections; it will only accept shared-memory connections.

Windows Database Servers

Login to your Windows database server.
Open an MS-DOS command prompt.
Run this command:
Registry
```
regedit
```

Drill down to

Registry

HKEY_LOCAL_MACHINE\
SOFTWARE\
INFORMIX\
SQLHOSTS

Look for the value passed to PROTOCOL.
- If this value is onsoctcp, ontlitcp, or anything else containing tcp, this $INFORMIXSERVER will accept sockets-based connections.
- If this value is onipcshm, or anything else containing shm, this $INFORMIXSERVER will not accept sockets-based connections; it will only accept shared-memory connections.

Ramifications

Sockets-based (TCP/IP) connections are supported by Enterprise Edition, Lite Edition, and Express Edition, regardless of whether the OpenLink components are running on the Informix host or elsewhere.

Shared-memory connections are supported only when our Enterprise Edition server-side components (Request Broker and Database Agent) or our Lite Edition client-side components are running on the Informix server host. Shared-memory connections are not supported by our Express Edition, nor by our Lite Edition when not running on the Informix server host.

Identify the Informix tcp service name

Unix Database Servers

Login to your Unix database server as the Informix user.
Ensure the Informix environment is properly set.
Execute this command:
Shell
```
echo $INFORMIXSERVER
```
Execute this command:
Example
```
more $INFORMIXDIR/etc/sqlhosts
```
Look for the line that begins with the $INFORMIXSERVER value, and note the value that appears in the fourth column. This is your service name.

Windows Database Servers

Login to your Windows database server.
Open an MS-DOS command prompt.
Run this command:
Registry
```
regedit
```

Drill down to

Registry

HKEY_LOCAL_MACHINE\
SOFTWARE\
INFORMIX\
SQLHOSTS

Look for the value passed to Service. This is your service name.

Identify the Informix tcp port number

Unix Database Servers

Log in to your Unix database server as the Informix user.
Ensure that the Informix environment has been correctly set.
Execute this command:
Shell
```
echo $INFORMIXSERVER
```
Execute this command:
Example
```
more $INFORMIXDIR/etc/sqlhosts
```
Look for the line that begins with your $INFORMIXSERVER value, and note the value that appears in the fourth column. This is your service name.
Execute this command:
Example
```
more /etc/services
```
Search the output for the line that beings with the service name you found in $INFORMIXDIR/etc/sqlhosts. Note the associated port number.

Windows Database Servers

Log in to your Windows database server.
Open an MS-DOS command prompt.
Run this command:
Registry
```
regedit
```

Drill down to

Registry

HKEY_LOCAL_MACHINE\
SOFTWARE\
INFORMIX\
SQLHOSTS

Look for the value passed to Service.
Exit the Registry.
Use Notepad to open the C:\Windows\System32\Drivers\etc\services or C:\WINNT\System32\Drivers\etc\services file.
Look for the port number that corresponds to the service in the registry.

Identify the Informix database server hostname or IP address

Unix Database Servers

Log in to your Unix database server as the Informix user.
Ensure the Informix environment is set correctly.
Execute this command:
Shell
```
echo $INFORMIXSERVER
```
Execute this command:
Shell
```
cat $INFORMIXDIR/etc/sqlhosts
```
Look for the line that begins with the $INFORMIXSERVER value, and note the value that appears in the third column. This is the hostname that your Informix server was initialized with at startup time.

Windows Database Servers

Login to your Windows database server.
Open an MS-DOS command prompt.
Run this command:
Registry
```
regedit
```

Drill down to

Registry

HKEY_LOCAL_MACHINE\
SOFTWARE\
INFORMIX\
SQLHOSTS

Look for the value passed to HOST. This is the hostname that your Informix server was initialized with at startup time.

Database Configuration for Unicode

Informix 9.x

When a database is created, the DB_LOCALE in effect at the time is stored in the system catalog and used throughout the lifetime of the database. Using DBACCESS, create a new database with DB_LOCALE set beforehand to "EN_US.UTF8". Specifying UTF8 as the codeset allows the creation of schema objects with names which can contain multibyte characters.

The database locale being used by a database can be viewed in DBACCESS using the menu commands: Database> Info > NLS.

The documentation for Informix GLS states that DB_LOCALE is also used to correctly interpret the locale sensitive datatypes NCHAR and NVARCHAR. The code set specified in DB_LOCALE specifies which characters are valid in any character column as well as the names of database objects.

Configuring Informix for XA support

XA support has been tested against versions 9.x and 10.x

Enable Database Logging

For XA to be supported, Informix must be capable of supporting transactions. This means that the database must have logging enabled.

Useful Links

IBM document (1996): http://www.umiacs.umd.edu/~jhu/DOCS/TX4.2/html/erzhae/erzhae18.html

Client components

Installation Guide

Installation of the Multi-Tier "Enterprise" Edition Generic Client JDBC Drivers, on macOS Operating Systems

Download the OpenLink Generic JDBC Driver for macOS, which comes in a .dmg file.
Double-click the .dmg file to start the installation process.
Confirm the warning message to proceed with the installation.
Read and accept the License Agreement for the OpenLink Generic JDBC Driver.
Choose the destination volume for the installation (typically your macOS boot volume).
Select the installation type:
- Easy Install (recommended).
- Custom Install (for experienced users who want to choose specific components).
  - If you have installed OpenLink or iODBC components in the past, select "Upgrade" to continue. Otherwise, click "Install."
If you chose the custom installation option, select the desired components to install.
- Click Next.
- Enter your macOS Username and Password when prompted to complete the installation.
After installation, your database driver is ready for use.
For configuring the OpenLink Generic JDBC Driver, use the following parameters in the Connection URL:
- Driver Name: opljdbc3.jar, megathin3.jar
- Driver Class Name: openlink.jdbc3.Driver
- Connection URL: jdbc:openlink://<Hostname>:[portnumber] [/UID] [/PWD] [/READONLY] [/SVT] [/APPLICATION] [/FBS|FETCHBUFFERSIZE] [/ENCRYPTED] [/CHARSET] [/UNICODE] [/DLF] [/DATABASE] [/OPTIONS] [/DRIVER]
  - Description of Parameters:
  - Hostname: Network Alias or IP address of the machine running the OpenLink Request Broker instance.
  - Port Number: TCP port on which the Request Broker listens.
  - /UID: Database username.
  - /PWD: Database password.
  - /READONLY: Read-write or read-only session mode.
  - /SVT: A valid domain alias from the [Domain Aliases] section of the OpenLink server component's oplrqb.ini file. Default domain aliases represent the type of database agent to which the application intends to connect.
  - /APPLICATION: The Application name to enable connectivity when restrictive server-side rules screen by application name.
  - /FBS (or /FETCHBUFFERSIZE): The Fetch Buffer Size representing the number of rows to return during one fetch operation.
  - /ENCRYPTED: Sets the Encrypted flag for outgoing packets. ('1', '0', 'Y', 'N', 'y', or 'n'. Disabled by default.)
  - /CHARSET: Specifies the charset of remote databases. Default value is read from System.getProperty("file.encoding").
  - /UNICODE: Instantiates unicode. The unicode connection isn't used by default. ('1', '0', 'Y', 'N', 'y', or 'n'. Disabled by default.)
  - /DLF: Pushes large, binary objects to the end of the resultset. Smaller data types are retrieved first, enhancing performance. ('1', '0', 'Y', 'N', 'y', or 'n'. Disabled by default.)
  - /DATABASE: Actual database name within a particular database environment.
  - /OPTIONS: Optional parameter to pass specialized database native client connection parameters.
  - /DRIVER: The Driver name contained in curly brackets ({}). Used for DSN-Less connections to remote ODBC Drivers.
Examples of Connection URLs:
- jdbc:openlink://localhost:5000/SVT=Ingres II/DATABASE=iidbdb/UID=ingres/PWD=ingres
- jdbc:openlink://192.128.13.119:5000/SVT=Oracle 8.1.x/DATABASE=ORCL/UID=scott/PWD=tiger
- jdbc:openlink://saturn:5000/SVT=Progress 91D/DATABASE=isports/OPTIONS=-S isports -N tcp -H saturn
- jdbc:openlink://localhost:5000/SVT=SQLServer 2000/DATABASE=Northwind/UID=sa/OPTIONS=-S SATURN

Configuration Guide

Configuration of the Multi-Tier "Enterprise" Edition Generic Client JDBC Drivers, on macOS

The OpenLink installer should set your CLASSPATH. You should have a pre-existing JAVA_HOME directory that points to the root of your JAVA installation. No further configuration should be needed.
Driver Name: opljdbc3.jar, megathin3.jar
Driver Class Name: openlink.jdbc3.Driver
Connection URL: jdbc:openlink://<Hostname>:[portnumber] [/UID] [/PWD] [/READONLY] [/SVT] [/APPLICATION] [/FBS|FETCHBUFFERSIZE] [/ENCRYPTED] [/CHARSET] [/UNICODE] [/DLF] [/DATABASE] [/OPTIONS] [/DRIVER]
- Hostname - Network Alias or IP address of the machine that runs an OpenLink Request Broker instance.
- Port Number - TCP port on which the Request Broker listens.
- /UID - Database username.
- /PWD - Database password.
- /READONLY - Read-write or read-only session mode.
- /SVT - A valid domain alias from the [Domain Aliases] section of the OpenLink server component's oplrqb.ini file. Default domain aliases represent the type of database agent to which the application intends to connect, e.g., DB2, Informix 2000, Oracle 8.1.x. Custom aliases may take any form.
- /APPLICATION - The Application name. Enables connectivity when restrictive server-side rules screen by application name.
- /FBS (or /FETCHBUFFERSIZE) - The Fetch Buffer Size. The Fetch Buffer Size is an integer that represents the number of rows to return during one fetch operation.
- /ENCRYPTED - Sets the Encrypted flag for outgoing packets. /ENCRYPTED may pass '1', '0', 'Y', 'N', 'y', or 'n'. (This feature is disabled by default.)
- /CHARSET - Specifies the charset of remote databases. The default value is read from System.getProperty("file.encoding").
- /UNICODE - Instantiates unicode. The unicode connection isn't used by default. The value may be '1', '0', 'Y', 'N', 'y', 'n' (This feature is disabled by default.)
- /DLF - Pushes large, binary objects to the end of the result set. Smaller data types are retrieved first. This enhances performance. /DLF may be set to '1', '0', 'Y', 'N', 'y', or 'n'. (This feature is disabled by default.)
- /DATABASE - Actual database name within a particular database environment.
- /OPTIONS - Optional parameter that passes specialized database native client connection parameters. Do not use this parameter unless you need to pass Progress socket parameters or database native client parameters that enable a local OpenLink database agent to locate a remote database. Example parameters would be Oracle Net10 Service Names, Ingres vnodes, remote Informix instance names, or DB2 remote database aliases.
- /DRIVER - The Driver name contained in curly brackets ({}). Used for DSN-Less connections to remote ODBC Drivers.
Examples of Connection URLs:

jdbc:openlink://localhost:5000/SVT=Ingres II/DATABASE=iidbdb/UID=ingres/PWD=ingres
jdbc:openlink://192.128.13.119:5000/SVT=Oracle 8.1.x/DATABASE=ORCL/UID=scott/PWD=tiger
jdbc:openlink://saturn:5000/SVT=Progress 91D/DATABASE=isports/OPTIONS=-S isports -N tcp -H saturn
jdbc:openlink://localhost:5000/SVT=SQLServer 2000/DATABASE=Northwind/UID=sa/OPTIONS=-S SATURN

Walkthrough with screenshots

Installation walkthrough with screenshots

The same installation, step by step, with the screens you will see.

OpenLink Multi-Tier Server Components Installation and Configuration

Installation

The OpenLink Multi-Tier server components installers for Mac OS X are distributed as Disk Image (.dmg) files. You need to download one Multi-Tier Request Broker installer and one agent installer designed to connect to the database that you want to query. Then, run the following installation procedure for each of the two installers.

Double-click the disk image to extract the installer .mpkg file:

You will encounter a warning message that will ask you if you are sure that you want to install the software. Click Continue:

This is the Welcome dialog for the OpenLink Multi-Tier Request Broker:

Review the Read Me file for installation requirements and known issues:

Read the Software License Agreement before continuing your installation:

Agree to the terms set forth in the license:

At some point, OpenLink's Request Broker installers will specifically prompt for the location of a local license file. Click the Browse button to locate commercial or evaluation file on your Windows machine. Check the "I don't want to install a license file" check box, if you do not have one.

Use the Browse or Choose button to locate a locate a local file on your local Mac. Newer installers should have a checkbox that allows you to implement licenses after installation has occurred.

Select a destination volume for the driver installation:

Choose to perform a custom or default installation of the driver:

If you chose the custom option, select which of the following components to install:

Note: The software must be installed as a user with Administrative privileges on the machine:

Your installer may prompt you to specify the port on which the OpenLink Request Broker service will listen. This is the port on which the OpenLink server components will listen for ODBC connections. The default is 5000. There may also be check a checkbox to automate broker startup.

Your installer may prompt you to specify the port on which the OpenLink Admin Assistant will run. The Admin Assistant is a Web-based GUI that enables you to configure your OpenLink server components. The default is 8000. You may also configure your Admin Assistant username and password. Both default to admin.

The installer may ask you if you want to launch your Admin Assistant before the installer completes.

The installation is complete:

Configuration

OpenLink's server components require minimal configuration. In most instances, the installation process includes steps to ensure that the primary configuration file (oplrqb.ini) is configured for basic connectivity. Use the following steps to check and enhance your individual agent settings.

Launch the Multi-Tier Administrative Assistant in a Web browser. The URL convention is:

http://ip_address_of_machine_with_mt_server components:mt_admin_port

Click the Server Components Administration link.

Click the Database Agent Administration link.

Click the Database Settings by Wizard link.

Select the configuration section that you want to review. The naming convention for default database agent configuration sections is generic_ followed by an abbreviation for the OpenLink agent.

The Agent Details dialog allows you to rename the default agent configuration section and provide an optional comment. This is an advanced feature that should not be pursued for basic connectivity.

Click Edit to continue.

The first Connection Parameters dialog allows you to hardcode a single username and password for all connections that use this agent configuration section for ODBC connectivity.

User Name - A valid database uid.

Password- A valid database password.

Click Next to continue.

The second Connection Parameters dialog allows you to hardcode a single Database, Read/Write access mode, and Connection Options for all connections that use this agent configuration section for ODBC connectivity.

Database Name- Takes a database name or Oracle SID.

Read Only specifier- Specifies whether the connection is Read-only or Read/Write.

Connect Options- This field passes parameters that enable users to connect to MySQL, PostgreSQL, Microsoft SQL Server, and Sybase databases anywhere on the network. It also passes parameters that enable users to connect to any DBMS that does not reside on the same machine as the OpenLink Request Broker and Agent. Review Complete Settings and Usage for Connect Options

Click Next to continue.

The second Connection Parameters dialog allows you to hardcode Server Options, a Domain, and a Host Name for all connections that use this agent configuration section for ODBC connectivity.

Server Options- Server Options are typically Progress specific options which are passed to the database at startup. You want to ensure that the options passed to the actual database match the options passed in the Server Options field or ServerOptions parameter. These options must also match actual options passed to the database at startup time.

Domain- The value must match a [Domain Alias], which is contained in the Server's Session Rules Book. This Alias typically represents the name and version of an OpenLink Agent. That agent version may differ from the DBMS version to which it connects. Note that advanced users may create custom domain names that follow their own, desired conventions.

Host Name- Host name or IP address of the machine that contains the OpenLink Request Broker.

Click Next to continue.

The Secure SSL Connection dialog allows you to designate an SSL certificate. It also allows you to enforce SSL-only connectivity.

SSL Key File- Passes the location of an SSL certificate.

SSL Required - Check to force the broker to accept only SSL-based connections.

Click Next to continue.

The first Application & Database Specific Parameters dialog allows you to enable opsyslogin. Opsyslogin forces connections to authenticate their usernames and passwords against the operating system instead of the database.

Require Operating System Identity- If checked, the Request Broker will test to see that the username and password which are supplied to it are valid for the machine. If the authentication parameters are valid, it will start the database agent under the identity of the user. If unchecked, the username and password will be passed to the backend database for authentication.

Click Next to continue.

The second Application & Database Specific Parameters dialog allows you to disable autocommit and enable Jet Engine catalogs.

No auto commit on startup- Changes the default commit behaviour of the OpenLink driver. The default mode is AutoCommit (box unchecked).

Jet engine catalogs- Check this checkbox if you intend to use this driver with Microsoft Access. This option facilitates translation of certain datatypes by the Microsoft Jet Engine. If you utilize MS applications, and you notice that money and other datatypes are mishandled, test with +jetfix.

Click Next to continue.

The third Application & Database Specific Parameters dialog allows you to limit your rowset size and pass an initial SQL script.

Limit result set to n records- Allows you to define a limit on the maximum number of rows to be returned from a query. The default value of 0 means no limit.

Initial SQL script- Lets you specify a file containing SQL statements that will be run automatically against the database upon connection.

Click Next to continue.

The Startup parameters screen enables you to identify the OpenLink database agent to use for your ODBC connections. It also allows you to hardcode specific environment variables for the connection. Proper environment variables are essential for ODBC connectivity.

Executable name- Allows you to choose which OpenLink agent should serve all connections associated with this agent configuration section.

Environment Variables- OpenLink's agents are written using the database native CLI. Consequently, they use the same environment variables that database native clients use to connect to the relevant DBMS. Use this box to set them. Complete List of Variables by Database

Click Next to continue.

The Process Mapping dialog enables you to set your agent reuse rules. Reuse rules dictate whether or not an agent will be used for subsequent connections. Reuse of agents reduces overhead associated with agent spawning.

Click Next to continue.

The Save Settings dialog allows you to save your new agent settings. Check the Reinitialize checkbox to reinitialize the OpenLink Request Broker with these settings. Your new settings will not be unforced unless the Request Broker is restarted or reinitialized.

Click Save to complete the agent configuration process.

Proceed to Commercial Licensing Documentation:

Should you decide to purchase a commercial license at the end of your evaluation period, be sure to consult our documentation which explains the placement and uptake of commercial license files and the use of our OpenLink License Manager technology: License Technology & Application

Configuration and upgrades

Administering the Multi-Tier components

ZeroConfig DSNs, the Admin Assistant and custom aliases, with screenshots.

Configuring Multi-Tier ZeroConfig DSNs by Wizard

The Multi-Tier Admin Assistant provides an HTTP-based interface to the server settings including those found in the Rulebook. This interface has been extended to support configuration of the ZeroConf settings in the Server Component Administration section, called Zero Config Administration.

The Zero Config Administration pages are very much like Client Data Source configuration pages -- they have the same layout and descriptions as they are essentially data sources stored on the server.

To make a new Zero Configuration entry, follow this sequence:

From the Server Components Administration menu, chose the Zero Config Administration sub menu, and then Zero Config Administration by Wizard. A list of current configurations is shown:
Press the Add button. Enter a suitable name for the configuration:
Enter the database details. The parameters are identical to those in the ODBC DSN configuration wizard. For each parameter you wish to configure, you need to enable it by checking the box on the left side. Each field is disabled until the check box is marked.
Enter the additional connection parameters. In same way as previous page, each parameter field needs to be enabled by the check mark on the left side.
The complete configuration parameters are now shown:
The Zero Config entry now appears in the list:

Configuring Multi-Tier ZeroConfig DSNs by Form

In the Server Components Administration menu, drill down to Zero Config Administration --> Zero Config Administration by Form. The list of current configurations will be shown. Chose one to edit or delete, or click Add to make a new configuration.

All parameters required in the form are the same as for any other DSN configuration. The Host and Port fields are not available, because this information is supplied by the Request Broker hosting the service.

Configuring a Multi-Tier Client to use a ZeroConfig DSN through the Windows ODBC Driver Manager

When configuring a DSN in the Windows ODBC Driver Manager, the Server field will offer a drop-down menu of available Zero Config targets --

Configuring a Multi-Tier Client to use a ZeroConfig DSN through the HTTP-based Admin Assistant

When configuring a DSN in the HTTP-based Admin Assistant, the Server field will offer a drop-down menu of available Zero Config targets --

During the configuration of a DSN in the Admin Assistant it is currently not possible to dynamically discover and present the Zero Config entries. However, you can manually put a Zero Config entry in the Server field.

Administration of the Multi-Tier Request Broker through Admin Assistant Wizards

Specify the location of your Request Broker and its dependent components. Also set restrictions on number of Agents, and number of connections.

Click the Next button.
Linger Timeout: The number of seconds an OpenLink Agent without connections will linger before being terminated by the OpenLink Request Broker, Specify 0 here to disable lingering. Lingering is a feature for avoiding repetative load/unload overhead of agents that are frequently used for short, quick concurrent open/close connections.

This setting is global to all agents. For specific agent settings, use the LingerTimeout value in the agent environment section.

Set Resolving of IP addresses to hostnames. The logging will show the hostname instead of the IP number if this option is selected. Switch off hostname lookup to avoid possible delays when frequently looking up unknown (new) IP numbers through a distant uncached DNS table. This parameter will have a direct affect on the type of match that is to be used for the StartupBy, ShutdownBy and ShutdownFrom parameters under the Security section.

Click the Next button.
To help with troubleshooting, turn on session logging and extra information. Or run the broker in foreground mode to view the trace. Then click on the Next button.
Enter buffer size values for the inbound and outbound network messages for each OpenLink Agent (it is advisable to take the default values presented). Then click the Next button.
Enter values for Database Agent session initialization, Broker Contact, and initialization failure retry counts by entering values into the respective fields as depicted below (it is advisable take the defaults). Then click on the Next button.
Check the related boxes presented in order to select the Network Transport Protocol to be used by your Request Broker and Database Agents when communicating with your OpenLink Data Access Clients. Then click on the next button.
You can choose to enable the OpenLink Ping WatchDog. All OpenLink components automatically use the keep-alive feature built in to most current implementations of TCP/IP stack. If keep-alive is not available the Ping WatchDog can be enabled in attempt to compensate for this. Click the Next button to continue.
If you have more than one Network Interface Card (NIC) installed on your OpenLink Server machine, then you can enter a value in the Force IP Address field that represents the IP address that you want the Request Broker to listen at.
Enter the port number on which the OpenLink Request Broker will listen for client connections. Each OpenLink Request Broker running on the same host must have a unique port number assigned to it.

You can also designate port number ranges to be used by the Broker to advertise other OpenLink services (e.g., JDBC Agent used by OpenLink Drivers for JDBC). Once completed, click the Next button to continue.
Click on the Save button to save your changes permanently.
Click the Exit button to leave the Broker Settings Wizard.

Administration of the Multi-Tier Request Broker through Admin Assistant Forms

You can configure your Request Broker via Forms or Wizards. You select this option from the Admin Assistant and you will be presented with a screen similar to the snapshot below.

Each Broker session settings field contains a description of the values that need to be entered into each of the forms fields. In addition a brief description of the use of each of these values is provided below each field.

Creating Custom Aliases for use by Multi-Tier Data Access Clients

Understanding how to maintain Session Aliases is a critical part of understanding how to create session rules. You can create, modify, edit, and delete Session Aliases in two ways: you either use the Admin Assistant's GUI interface, or you manually edit the session rulebook using a text editor (only recommended for advanced users).

The steps that follow guide you through the Session Alias management process using the Admin Assistant's GUI. Before performing any of these steps you may need to start the Admin Assistant, by following the steps below:

Start the Request Broker
Start a Web Browser session
Enter the appropriate URL into your browser (adjusting the port number, if you changed the Admin Assistant port number during installation):
- If the Request Broker is running on the same machine as your web browser, enter:
  URL
```
http://localhost:8000/
```
- If the Request Broker is running on another machine than your web browser, enter:
  Example
```
http://<hostname or IP address>:8000
```

Domain Aliases

The steps that follow show you how to manage Domain Aliases:

Follow the "Server Components Administration"->"Session Rules Administration"->"Session Rules Book Aliases"->"Edit Domain Aliases" menu tree which brings you to a screen identical to the one depicted below.

The Admin Assistant presents you with a list of pre-configured Domain Aliases, click on the "Edit" hyperlink to change settings, the "Remove" hyperlink to delete an Alias, and the "Add" button at the bottom of the screen to create a new Domain Alias.
The example below assumes that you are modifying a Domain Alias named "ora8" with the attribute values "Oracle 8". This implies that you want to take note of Domain Connection Attributes from a Multi-Tier Client that start with the value "Oracle 8" evaluation against a mapping rules template. Once you have completed your input click the "Update" button.
You then commit your changes to the rule book by clicking on the "Reinitialize the Multi-Tier Request Broker with these settings" hyperlink. See screen shot below:
Admin Assistant confirms commitment of your changes to the rule book.

User Aliases

The steps that follow show you how to manage User Aliases using the Admin Assistant:

Follow the "Server Components Administration"->"Session Rules Administration"->"Session Rules Book Aliases"->"Edit User Aliases" menu tree which brings you to a screen similar to the one depicted below.

The Admin Assistant presents you with a list of pre-configured User Aliases if any exist, if this is your first time there will be not items listed. Click on the "Add" hyperlink to create a new User Alias.
The example below assumes that you are creating an User Alias named "Sales" with attribute values of "Test" or "Mary", the use of the caret symbol (character "^") and the Dollar symbol indicate the start and end of regular expression evaluation values respectively. The Pipe symbol (character "|") indicates an OR condition. Thus the entry depicted below implies that you want to take note of User Connection Attributes from a Multi-Tier Client that hold the values "Test" or "Mary" for evaluation against a mapping rules template. Once you have completed your input click the "Add" button.
You then commit your changes to the rule book by clicking on the "Reinitialize the Multi-Tier Request Broker with these settings" hyperlink. See screen shot below:
Admin Assistant confirms commitment of your changes to the rule book.

OpSys (Operating System) Aliases

The steps that follow show you how to manage OpSys Aliases using the Admin Assistant:

Follow the "Server Components Administration"->"Session Rules Administration"->"Session Rules Book Aliases"->"Edit Operating System Aliases" menu tree which brings you to a screen identical to the one depicted below.
The Admin Assistant presents you with a list of pre-configured OpSys Aliases if any exist, if this is your first time no items will be listed. Click on the "Add" hyperlink to create a new OpSys Alias.
The example below assumes that you are creating an OpSys Alias named "ClientOS" with attribute values of "win32" or "unix". The Pipe symbol (character "|") indicates an OR condition. Thus the entry depicted below implies that you want to take note of OpSys Connection Attributes from a Multi-Tier Client that start with the values "win32" or "unix" for evaluation against a mapping rules template. Once you have completed your input click the "Add" button.
Commit your changes to the rule book by clicking on the "Reinitialize the Multi-Tier Request Broker with these settings" hyperlink. See screen shot below:
Admin Assistant confirms commitment of your changes to the rule book.

Machine Aliases

The steps that follow show you how to manage User Aliases using the Admin Assistant:

Follow the "Server Components Administration"->"Session Rules Administration"->"Session Rules Book Aliases"->"Edit Operating Machine Aliases" menu tree which brings you to a screen identical to the one depicted below.
The Admin Assistant presents you with a list of pre-configured OpSys Aliases if any exist, if this is your first time no items will be listed. Click on the "Add" hyperlink to create a new Machine Alias.
The example below assumes that you are creating an Machine Alias named "MyNetwork" with an attribute value of "123.123.123". This implies that you want to take note of Machine Connection Attributes from a Multi-Tier Client that start with the value "123.123.123" (you would do this to identify the Network portion of the client machines IP address). Once you have completed your input click the "Add" button.
Commit your changes to the rule book by clicking on the "Reinitialize the Multi-Tier Request Broker with these settings" hyperlink. See screen shot below:
Admin Assistant confirms commitment of your changes to the rule book.

Application Aliases

The steps that follow show you how to manage User Aliases using the Admin Assistant:

Follow the "Server Components Administration"->"Session Rules Administration"->"Session Rules Book Aliases"->"Edit Application Aliases" menu tree which brings you to a screen identical to the one depicted below.
The Admin Assistant presents you with a list of pre-configured Application Aliases, click on the "Edit" hyperlink to change settings, the "Remove" hyperlink to delete an Alias, and the "Add" button at the bottom of the screen to create a new Application Alias.
The example below assumes that you are modifying an Application Alias named "msoffice" with attribute values of "MSACCESS" or "EXCEL" or "MSQRY32". The Pipe symbol (character "|") indicates an OR condition. Thus, the entry depicted below implies that you want to take note of Application Connection Attributes from a Multi-Tier Client that hold the values "MSACCESS" or "EXCEL" or "MSQRY32" for evaluation against a mapping rules template. Once you have completed your input click the "Update" button.
Commit your changes to the rule book by clicking on the "Reinitialize the Multi-Tier Request Broker with these settings" hyperlink.
Admin Assistant confirms commitment of your changes to the rule book.

Determining The Values of Multi-Tier Client Generated Connection Attributes

To manage Aliases for non-user-configurable Connection Attributes, determine the relevant values with the following steps:

Start the Request Broker in Debug Mode
Then make a connection from your Multi-Tier Client

Your Request Broker's debug window will contain something similar to the following:

Shell

oplrqb: client-machine.YourDomain called (123.123.123.100.1510)
oplrqb: request: domain=Oracle 8 database= serveropts=
oplrqb: connectopts= user= opsys=win32 readonly=0
oplrqb: application=OPLSCAN processid=384

Take note of the values assigned to the following Connection Attributes: opsys, readonly, and application. Apply these values to the appropriate Aliases that your are attempting to configure.

Advanced Server Components Configuration (Multi-Tier)

Server-side Configuration for SSL

In order to make use of this functionality, you need to create a certificate on the server running the request broker. On Unix platforms we have provided a bin/mkcert.sh script as part of the installation. On other platforms you may have to run openssl by hand or use another system to generate the PEM file (such as generating it on a unix server and copying the files across).

A sample run of the mkcert.sh script, showing the various questions it asks to identify your organization, follows:

Shell

bash$ cd /usr/openlink/bin/
bash$ ./mkcert.sh mykey
Checking OpenSSL: OpenSSL 0.9.7d 17 Mar 2004
Generating a 512 bit RSA private key
.++++++++++++
.......++++++++++++
writing new private key to 'mykey.key'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Host name (externally visible) [host.example.com]:purple
Organization (eg. company) [OpenLink Software]:
Organizational Unit [Research & Development]:Product Development
State or Province Name (full name) []:Surrey
Locality Name (eg. city) []:Croydon
Country Name (2 letter code) [US]:UK
1024 semi-random bytes loaded
Generating DH parameters, 512 bit long safe prime, generator 2
This is going to take a long time
..+........................+...........................+.......+...........
[]
.+.....++*++*++*++*++*++*
subject= /CN=purple/O=OpenLink Software/OU=Product Development/ST=Surrey/L=Croydon/C=UK
notBefore=Nov 12 10:43:14 2004 GMT
notAfter=Nov 10 10:43:14 2014 GMT
MD5 Fingerprint=E0:DB:53:E7:E7:68:21:53:1C:2B:1E:8E:D9:BF:25:F0
Created private key parameters in mykey.key
Created public key parameters in mykey.cer
bash$

Having created the key-pair, you now need to tell the request broker to use them. This requires the following lines to be present in the rulebook (oplrqb.ini):

INI

[Request Broker]
....
SSLKeyFile = mykey.pem
SSLRequired = No

The SSLKeyFile is the filename of the key you just created; to deny connections without SSL, set SSLRequired

Yes instead.

You can also put these options in the individual database agent sections, such that one key is used for e.g. Ingres, and another for SQL Server, or one for your sales database and another for people coming in from VPN IP#s (by editing the mapping rules to match on a per-IP# basis). For example:

INI

[generic_sqlserver]
.....
SSLKeyFile = mykey-sqlserver.pem
SSLRequired = Yes                  ; All SQLServer connections
MUST use SSL

As an alternative to editing oplrqb.ini by hand, you can use the web-based Administrator GUI, either the form or wizards, to set the SSL Key File and SSL Required fields, thus:

Figure: 1. Server-side SSL Configuration of Request Broker via Web Assistant

Figure: 2. Server-side SSL Configuration at the database agent level via Web Assistant

Advanced configuration for Informix

Optional features of the Informix drivers, each with its own settings.

ODBC to Jet Data Type Mapping in our Data Access Drivers for Informix

Numeric Data Type Mappings in our Data Access Drivers for Informix

The table below details how the OpenLink data access drivers fetch numeric data from Informix.

The SQL type reported for a SELECT column varies depending on the native Informix type of the column, its precision, and its scale. The C type used to fetch the data is also shown, together with the effect of the JetFix switch.

Changes to the type mappings required to implement the JetFix option are shown in italics.

Table 1. Numeric Data Type Mappings

Precision of C Data Types

The C data type used to fetch a numeric value is determined by the maximum precision supported by the type.

If a numeric type exists which can represent the data to be fetched without loss of precision, then this is used as the preferred fetch type.

If a numeric type capable of supporting the required precision does not exist, then the data is fetched in character form, unless the JetFix switch is on. In this case, the data is fetched using the CTYPE_FLT64 fetch type, which has sufficient range to store the maximum numeric values supported by Informix. However, CTYPE_FLT64 may result in a loss of precision, if the precision of the data to be fetched exceeds 15 decimal digits.

Table 2. Precision of C Data Types

Informix Jetfix Testing

To verify the effect of the +jetfix switch, two tables were created and then linked into Access -- once with JetFix enabled, and once with JetFix disabled.

The first table contained five MONEY columns of various precisions and scales.

The second table was identical except that it used DECIMAL instead of MONEY columns.

The resulting Jet data type mappings as shown in the 'Table Design' view are detailed below:

Table 3. Informix ODBC to Jet Data Type Mapping

Configuring OS-Level Authentication ( OpSysLogin )

The Multi-Tier OpSysLogin feature authenticates users at the operating system level. This provides enhanced security for databases with known security issues, such as older versions of Informix, Ingres, or Progress, which lack internal user authentication.

Note: The OpSysLogin feature requires that the Request Broker run with permissions of the root user. After enabling the feature as described below, we recommend using the Multi-Tier security Utility to enable ordinary users to launch the Broker with root permissions.

Use the following instructions to configure OpSysLogin, if required for your deployment.

Log in to the Request Broker host.
Open the active Rulebook (e.g., oplrqb.ini) in a text editor.

Locate the [generic_xxxxx] section, which corresponds to the relevant Database Agent. For example:

INI

[generic_inf2000]
Description = Default settings for Informix 2000 agent
Program     = inf9_mv
Environment = INFORMIX2000
;OpsysLogin  = No
ReUse       = always
;CommandLine    =
;ConnectOptions =
;Directory      = /tmp
;Database       =
;Userid         =
;Password       =
;ReadOnly       = Yes

Locate the OpsysLogin parameter.
Ensure that no semicolon (";") appears in front of OpSysLogin.
Set
INI
```
OpsysLogin = Yes
```
Save your changes and exit the file.
Restart or reinitialize (oplshut +reinit) your Request Broker service.

Multi-Tier security Utility

Due to the Unix security model, certain kernel calls can only be used when the process is run by, or with the permissions of, the root user.

One of these function calls was needed for the PingWatchDog protocol (deprecated since UDA Release 4.x). Database security considerations, including the OpSysLogin feature, can also lead to this need. In both case, the Request Broker must be run as root.

This can be accomplished in two ways:

The user logs in as root before launching the Request Broker.
The Request Broker is flagged to run under root privileges, and the user enabled to launch it from any normally privileged account.

The first option requires that all the user(s) who launch the Broker must know the root password, which should not generally be given to ordinary users.

Therefore we have built a solution which enables the second option, without all user(s) needing to know the root password. The system administrator or other user who does know the root password can activate this solution by executing the following commands as root (adjusting the file path as needed for the local installation):

Shell

$ cd /opt/openlink/bin
$ ./security -s

This will have the following effects --

The permissions of the oplrqb executable are changed so it takes on the identity of "root" when launched.
The Broker now knows the filesystem location of the Rulebook file, oplrqb.ini, and will not accept certain startup flags so it cannot be tricked to read in a different Rulebook file at launch.
The Rulebook file can now only be written to by the "root" account; other accounts will only be able to read this file.

Any time a user tries to launch or terminate the broker, the StartupBy or ShutdownBy value within the [Security] section of the Rulebook is checked to see whether the user is allowed to do so. To have full effect, the default wildcard values for these keywords should be replaced with relevant specific username(s).

As noted above, the Rulebook can now only be written to by the "root" user. This means that ordinary users cannot modify this file, which often seems like an unpleasant side effect. To overcome this, some system administrators are temped to modify the mode of the Rulebook file, reopening security risks. This should be avoided. Instead, the IncludeRuleBook parameter within the [Security] section should be used to divide the Rulebook into parts which others can manage as appropriate. The system administrator can split up the Rulebook into different files which than can be included from the master Rulebook. This makes specific sections available to normal users, but allows the system administrator to decide which sections can (or cannot!) be overruled by normal users. The included Rulebooks cannot overrule any section within the master Rulebook. This is a very powerful way of dealing with high security installations within large companies.

Configure Informix Unicode Support

For an Informix agent (on Windows or Unix), specify the CLIENT_LOCALE environment variable setting in the [Environment INFORMIX] section of the rulebook. For an Informix Unix Lite driver, set the CLIENT_LOCALE environment variable appropriately.

Advanced configuration for all databases

Settings of the Multi-Tier components that apply whichever database you connect to.

Automate Request Broker Startup (Sample Script)

OpenLink Product Support does not provide customized shell scripts to automate Broker startup or any other feature of our software. However, we do provide a sample shell script as a courtesy to those individuals who may want general guidance before creating their own scripts.

Example

>> Begin file
#!/bin/sh
#
# Run the OpenLink Request Broker
# For entry in /etc/rc2.d/SnnOpenLinkBroker, where nn is 90 or higher.
# Typically, nn is 98 so that it precedes the CDE login process which
# does not return.
BIN_DIR=/usr/openlink/bin
if [ "$1" = stop ]
then
echo "Shutting down OpenLink Request Broker ..."
# This code derived from the OpenLink rqbshut script.
#######################################################################
process=oplrqb
set - `ps -e | grep " $process\$" | grep -v grep`
if [ $# -eq 0 ]
then
echo $0: $process is not running
exit 1
fi
kill $1 2>/dev/null
if [ $# -eq 0 ]
then
echo $0: unable to shutdown $process
exit 1
fi
echo $0: $process shutdown complete
exit 0
echo "Shut down process but not exiting script"
fi
# Else, assume start.
# BIN_DIR=/export/home/openlink/sschadt/bin
exe=$BIN_DIR/oplrqb
if [ -x $exe ]
then
# See OpenLink installation guide for alternatives.
if id | grep "uid=0" >/dev/null 2>&1
then
# Start broker under its owner's identity.
#  set - `ls -l $exe`   (this line was clearing out $1)
# See if the file exists and use $? to determine outcome
ls -l $exe >/dev/null 2>&1
if [ $? -eq 0 ]
then
id="$1"
echo "The id being used is '$id'"
echo "Starting OpenLink Request Broker with '"$id"' identity."
su "$id" -c "$exe &"
echo "ps -ef | grep opl ..."
ps -ef | grep opl
exit $?
fi
fi
echo "Starting OpenLink Request Broker."
$exe >/dev/null 2>&1 &
exit $?
else
echo "OpenLink Request Broker not found: $exe"
exit 1
fi
<< end of file

Configuring Firewalls to permit Multi-Tier Connectivity

If you use our Multi-Tier components through with a firewall, several ports must be opened to permit requests from Generic Clients to Request Broker and Database Agents (and their responses).

Some ports are user or admin configurable; some are not.

Unconfigurable Ports

TCP and UDP ports 60001 must be open. These ports are used by the Request Broker and the OpenLink License Manager, and cannot be changed.

Configurable Ports

Configurable ports are specified in the [Protocol TCP] section of your Session Rulebook (default, oplrqb.ini). You can use any text editor to open your Rulebook, and edit this section:

INI

[Protocol TCP]
PingWatchdog       = No
PingInterval       = 600
;IPAddress          = 127.0.0.1
Listen             = 5000
PortLow            = 5000
PortHigh           = 5025

The Request Broker listens on the TCP port specified in the Rulebook as Listen. (Release 3.x and earlier listened at PortLow.)
Listen and PortLow are generally best set to the same value.
The Request Broker restricts Database Agents to use only ports in the range between (and including) those specified in the Rulebook as PortLow and PortHigh. Specific Agent ports are requested from and assigned by the operating system when an Agent is instantiated; they are not preemptively reserved.
The span between PortLow and PortHigh is generally best set to twice the licensed number of Database Sessions. At minimum, this span should be the licensed number of Database Sessions plus 5 (and thus, not less than 10).

General Guidance, for Windows, Linux, and other Unix-like OS (except macOS)

If you receive the above error message, check whether the OpenLink License Manager is running on the licensed host -- i.e., the Request Broker host for the Enterprise Edition (Multi-Tier); the client driver host for the Lite or Express Editions (Single-Tier); or the Virtuoso server host.

on Windows, use the Task Manager or similar.
on Unix-like OS, use a command like this (may vary, depending on your active shell) --
Shell
```
ps -ef | grep oplmgr | grep -v grep
```

If the License Manager is already running, make sure that networking and firewalls are properly configured.

If networking and firewall are configured properly, and the License Manager is running, but the error persists, then kill the oplmgr process (e.g., kill -9 <PID>), and proceed as below.

If the License Manager is not running, do this:

Ensure the proper license file(s) is/are in place, and named as we shipped them (e.g., pro9_lt.lic, oplrqb.lic, ee_inf_lt.lic).
Remove or rename any expired or otherwise extraneous OpenLink license files.
Create or modify the OPL_LICENSE_DIR environment variable, and ensure that it includes each and every directory that contains one of your active OpenLink license file(s).
Start the License Manager --
- On Windows, use the Services or Component Services control panel (often found in the Administrative Tools sub-folder).
- On Unix-like OS, set the OpenLink environment by running the appropriate script for your shell (adjusting the path as appropriate) --
  
  shell command
  
  sh, bash, zsh and related . /path/to/openlink.sh
  
  ksh and related source /path/to/openlink.sh
  
  csh, tcsh and related source /path/to/openlink.csh
  - Our recent distributions start the License Manager as part of the above scripts; if you see no message about oplmgr starting, then also execute this command --
    Shell
```
oplmgr +start
```
Confirm that the License Manager has started successfully --
- on Windows, use the Task Manager or similar.
- on Unix-like OS, use a command like this (may vary, depending on your active shell) --
  Shell
```
ps -ef | grep oplmgr | grep -v grep
```
Test a connection.

shell	command
`sh, bash, zsh` and related	`. /path/to/openlink.sh`
`ksh` and related	`source /path/to/openlink.sh`
`csh, tcsh` and related	`source /path/to/openlink.csh`

Special Guidance for Release 6.x or 7.x on macOS Snow Leopard (10.8.x) and later

Note: This guidance is not relevant for Release 8.x drivers, nor with Release 6.x or 7.x installers with .mpkg dated 2014-12-04 or later.

Changes in the Gatekeeper in Snow Leopard (10.8.x), Mavericks (10.9.x), Yosemite (10.10.x), El Capitan (10.11.x), Sierra (10.12.x), High Sierra (10.13.x), Mojave (10.14.x), and Catalina (10.15.x) required updated License Manager binaries and startup scripts. Installers produced after 2014-12-04 for Release 6.x and 7.x, and all installers for Release 8.x, include these updates. Updated oplmgr installers are also available for users with drivers installed, or driver installers dated, prior to 2014-12-04.

If your Release 6.x or 7.x driver installer .dmg contains an .mpkg dated before 2014-12-04, please download this second installer package for use on macOS Catalina (10.15.x), Mojave (10.14.x), High Sierra (10.13.x), Sierra (10.12.x), El Capitan (10.11.x), Yosemite (10.10.x), Mavericks (10.9), Snow Leopard (10.8.x), or Lion (10.7.x) -- oplmgr.pkg
Double-click to run the .pkg.
This installer should automatically move any previously installed license files from --
Files
```
/Library/Application Support/openlink/bin/*.lic
```
-- to --
Files
```
/Library/Application Support/openlink/Licenses/*.lic
```
-- but some users have reported otherwise, so you may need to do this relocation yourself, with /Applications/Utilities/Terminal.app --
Shell
```
cd "/Library/Application Support/openlink/Licenses"
sudo mv ../bin/*.lic .
```
Confirm that the oplmgr process is running with this Terminal.app command --
Shell
```
ps -ef | grep oplmgr | grep -v grep
```
If it's running, output should look something like this --
Example
```
0   111     1   0 Wed09AM ??         0:00.57 /Library/Application Support/OpenLink/bin/oplmgr -fd /Library/Application Support/OpenLink/Licenses
```
If it's not running, try a reboot, or manually execute the following Terminal.app command, and then check for the process again --
Shell
```
sudo /Library/Application\ Support/OpenLink/bin/oplmgr -fd /Library/Application\ Support/OpenLink/Licenses &
```
Once the oplmgr process is running, try testing the driver again.

Pre-requisites for relinking Database Agents

Requirements for all Database Agents

Make a backup copy of your existing Agent(s).
Insure that you have a C compiler and library linker installed on your database server.
Set key OpenLink linking-script environment variables, which themselves reference key database environment variables required for making native connections to your database engine. You may prefer to adjust these values in the "dbpaths" file situated in the same directory as your database agent link script.
- DB2
  INI
```
DB2DIR=$DB2INST
```
- Informix
  INI
```
INFORMIX5DIR=$INFORMIXDIR
INFORMIX6DIR=$INFORMIXDIR
INFORMIX7DIR=$INFORMIXDIR
```
- Ingres
  INI
```
INGRES6DIR=$II_SYSTEM/ingres
INGRES7DIR=$II_SYSTEM/ingres
```
- Oracle
  INI
```
ORACLE6DIR=$ORACLE_HOME
ORACLE7DIR=$ORACLE_HOME
ORACLE8DIR=$ORACLE_HOME
```
- Progress / OpenEdge
  Shell
```
export PROGRES8DIR=$DLC
export PROGRES9DIR=$DLC
export PROGRES10DIR=$DLC
```
- Solid
  INI
```
SOLIDDIR=$SOLID
```
- Sybase
  INI
```
SYBASE10DIR=$SYBASE
SYBASE11DIR=$SYBASE
SYBASE4DIR=$SYBASE
```
- Unify
  INI
```
UNIFYDIR=$UNIFY../lib
```
- Velocis
  INI
```
VELOCISDIR=$VELOCIS
```
- Virtuoso
  INI
```
VIRTUOSODIR=$VIRTUOSO
```
The ".../openlink/lib" (or similar) subdirectory that you are working with should be included in your system PATH. If it is not already, add this directory to the system PATH now.

Additional Informix-specific requirements

Informix users must have an $INFORMIXDIR/lib/esql/ directory for successful relinking. This may be obtained and installed as part of the freely downloadable Informix Client SDK, available from IBM, if not already present as part of your installation.

Additional Progress-specific requirements

All Progress users must have a $DLC/probuild/4gl/ directory, which requires a development license from Progress.
All Progress users must set and export DLC and PROLOAD environment variables. DLC points to the root of the Progress installation. PROLOAD points to the $DLC/probuild/ directory.
Progress 6 users must have an HLI/C license from Progress. For Progress 7, 8, and 9, this is not required

Relinking Database Agents for all DBMS

Ensure that all pre-requisites listed above have been addressed.
Navigate to the "lib" sub-directory of your OpenLink server components installation directory, e.g., "/usr/openlink/lib".
If relinking a SQL-89 Agent for Progress (proNNN_sv) --
1. Confirm that the Progress environment variable DLC is set correctly.
2. Confirm that the Progress environment variable PROLOAD is set correctly.
3. Run the appropriate mkdlcX script, where X is the major version number of your Progress installation (i.e., 6, 7, 8, or 9). This will produce a file called dlcX.o.
4. If you receive an error stating that any Progress library cannot be found, edit the mkdlcX script and remove the reference(s) to that file; then re-run the mkdlcX script. Repeat this step as needed.
Run the appropriate link script (ldXXXNN) which will attempt to build a new database agent.
At the end of the relink process, the new database agent executable will be automatically placed in the "bin" subdirectory directory of your OpenLink server components installation. The new database agent binary will be named according to the typical OpenLink conventions, i.e., XXXNN_sv or XXXNN_mv.
Navigate to the "lib" sub-directory of your OpenLink server components installation; typically --
Shell
```
cd ../bin
```
Locate your newly linked agent. If it has a different name than the original agent, you can rename both so that the new one takes the place of the old, or you can edit your Broker Rulebook (oplrqb.ini) and change all occurrences of the old database agent name to the new agent name.
Restart your Broker.
Test.

Creating Custom Relink Scripts for Drivers and Agents for Progress/OpenEdge

Creating Custom Relink Scripts for Drivers and Agents for Progress/ OpenEdge

Custom relink scripts may be needed when our standard scripts are incompatible with your database installation and/or environment. The Progress probuild utility enables you to create such custom scripts.

Locate the buildenv script, typically found in the $DLC/probuild/eucapp directory.
Ensure that the environment variable settings in the buildenv script are accurate for your system.
Set and export
Example
```
PROLOAD=$DLC/probuild
export PROLOAD
```
Type the following command at your command line:
Example
```
$PROLOAD/eucapp/probuild
```
At the Install Link Script Into prompt, enter the full path to your ~/openlink/bin directory.
Click Continue.
Select ESQL/C Large Client Full from the product list.
Click Continue.
Give your relink script an appropriate name. For example:
Example
```
ldpro7
ldpro8
ldpro9
```
Give the executable to be produced an OpenLink-style Database Agent name. For example:
Example
```
pro73e_sv
pro83b_sv
pro91b_sv
```
Click Continue.
Do not specify any special configurable elements.
Click Continue.
Locate the database agent object code in the /lib sub-directory of your OpenLink installation. Object code files are named similarly to pro7_sv.o, pro8_sv.o, and pro9_sv.o.
Enter the full path to the relevant Database Agent object code (proxxx_sv.o) under "Object Files.'
Click Continue.
Exit probuild.
Repeat the relink process with your new relink script.

Changing or Resetting Access Restrictions for the Multi-Tier Request Broker's Admin Assistant

Changing User Access

Load the Admin Assistant in a browser. The default URL is http://broker-hostname-or-ip-address:8000/.
Drill down to Server Components Administration -> Admin Assistant Settings -> Configure the List of Users Allowed to use the Admin Assistant. When prompted to log in, use the defaults or whatever you've set previously.
Click Edit, Remove, or Add as appropriate, until the list reflects your intention.
Optionally, drill down to Server Components Administration -> Admin Assistant Settings -> Configure the Admin Assistant's Remote Access Filters. Here you can restrict the IP addresses which may use Web browsers to access the Admin Assistant.
When you've finished, stop and restart the Request Broker, which will automatically restart the Admin Assistant.
Test your new settings.

Resetting to Defaults

The default username and password of the Multi-Tier Admin Assistant are both admin. If you cannot log in with these values, you may have changed them during installation. You can reset these through the following steps:

Access the machine which hosts the Multi-Tier server components.
Open a CMD/DOS or Unix terminal session.
Navigate to the /bin/w3config sub-directory of the server-side installation.
Run setup or setup.exe. This program will reset both username and password to the defualt -- i.e., "admin".

Set Isolation Levels

You may use OpenLink's +initsql parameter to change your database isolation level. The following instructions will assist you with this task:

1. Insure that your database supports the operation which you want to implement. Verify the syntax which that database will accept.

2. Create a file in the /bin sub-directory of your OpenLink server components installation. This file should contain only the isolation level syntax. For example:

Example

-Dsrv TXN_ISOLATION, SERIALIZABLE

3. Open the oplrqb.ini file which resides within the same /bin sub-directory.

4. Locate the [generic_XXXXX] section which corresponds to the database agent which you use. For example:

INI

[generic_inf7]
Program     = inf7_mv.exe
Environment = INFORMIX7
OpsysLogin  = Yes
ReUse       = always
;Directory   = c:\temp
;ConnectOptions =
;ReadOnly  =
;CommandLine =

5. Locate the "CommandLine" parameter, and pass the file which you have created. For example:

INI

CommandLine = +initsql yourisolationfile

6. Remove any semicolon (;) which may appear in front of CommandLine.

7. Save your changes and exit the oplrqb.ini file.

8. Restart the OpenLink Request Broker by typing the following commands from the same /bin sub-directory:

Shell

./oplshut
./oplrqb +loglevel 7 +logfile oplrqb.log

9. Test.

Details of Multi-Tier Rulebook ConnectOptions , and Single-Tier and Multi-Tier DSN Options

For connections to DB2

Option Setting	Details	Example
`<Native DB2 DSN>` (no flag)	Pass a native DB2 DSN, if the DB2 DBMS runs on a different machine than the OpenLink Request Broker and Database Agent.	`My_DB2_DSN`

For connections to Informix

Option Setting	Details	Example
`<Informix Instance Name>` (no flag)	Pass an Informix Instance Name, if connecting via TCP/IP stack (i.e., not shared memory).	`inf10inst1`

For connections to Ingres

Option Setting	Details	Example
`<Ingres vnode>` (no flag)	Pass an Ingres vnode, if the Ingres DBMS runs on a different machine than the OpenLink Request Broker and Database Agent.	`Ing_vnode`

For connections to Microsoft SQL Server

Option Setting	Details	Example
`-H <hostname or IP address>`	Required Fully-qualified domain name (i.e., DNS-resolvable hostname) or IP address of the SQL Server host machine.	`-H sql-host.example.com`
`-V <version>`	Required TDSVer value. Optimal settings are `10.0` for SQL Server 2008 and later, `9.0` for SQL Server 2005 , `8.0` for SQL Server 2000, `7.0` for SQL Server 7.x.	`-V 9.0`
`-P <port number>`	TCP Port at which the target SQL Server instance is listening. Not required if `-I` or `-S` is properly set. Required otherwise.	`-P 1433`
`-I <instance-name>`	SQL Server instance name on the specified host (`-H`). Only the actual "`InstanceName`". This option should be used in preference to the `-S` option below for connecting to a named instance.	`-I mssql2k5`
`-S <FQDN of database host>\\<instance-name>`	*Not recommended. `-H` and `-I` are preferred.* Specifies a target SQL Server instance by combining the host and instance names as "`<FQDN>\\<instance>`", e.g., "`sql-host.example.com\\demo-instance`". Note the double backslash ("`\\`") required between the host and instance names.	`-S sql-host.example.com\\mssql2k5`
`-F <fail-over server name>`	Specifies the fail-over server name for Database Mirroring.	`-F failover-host.example.com`
`-O <value>`	Determines whether stored procedures are created on the server for every call to `SQLPrepare()`. Acceptable values are "2" (Full), "1" (Partial, the default), and "0" (None). Effects of this setting.	`-O 1`
`-L <language>`	The name of a Microsoft SQL Server-supported national language. The default language is English.	`-L English`
`-C <character set>`	The name of the character set the OpenLink driver should deliver to the client application, to be translated from the Server's character set. By default, this is taken from the application's environment. Only valid for non-Unicode drivers. Unicode drivers always deliver UCS-2 on Windows and UCS-4 on Mac OS X and Unix-like OS.	`-C ISO-8859-1`
`-A`	Turn off ANSI `NULL` handling. Effects of this setting.	`-A`
`-E`	Require SSL Strong Data Encryption for communications between Database Agent or Lite Driver and SQL Server. If SQL Server is not configured to support SSL, connections will fail. This is not necessary when the SQL Server is configured to require SSL communications; the Agent/Driver automatically support that requirement.	`-E`
`-R`	Require SSL Server Certificate Verification for SSL communications. Has no effect if SSL is not active. Not necessary in most cases. Will cause failure in server-forced SSL connections if `-D` (below) is not also set correctly.	`-R`
`-D <path to file>`	Full path including filename of Certificate Authority File to be used for SSL Certificate Verification.	`/usr/local/certs/auth.caf`
`-Z`	Turn on Snapshot Serializable Isolation.	`-Z`
`-M`	Turn on Multiple Active Result Sets (MARS), enabling concurrent processing of multiple statements, queries, and/or result sets, on a single database connection.	`-M`
`-N <size>`	Network Packet Size determines the number of bytes per network packet transferred between the Microsoft SQL Server and the Database Agent or Lite Driver. This attribute can have significant impact on performance. The default, and often optimal, setting is `8000`. The maximum supported by Microsoft SQL Server is `32767`.	`-N 0`

For connections to MySQL

Option Setting	Details	Example
`-H <hostname or IP address>`	Required Fully-qualified domain name (i.e., DNS-resolvable hostname) or IP address of the MySQL host machine.	`-H mysql-host.example.com`

For connections to JDBC Data Sources

Option Setting	Details	Example
`<JDBC Connection URL>` (no flag)	Required. Pass a JDBC connect URL as appropriate for the target JDBC Driver.	`jdbc:openlink://test.example.com:5000/UID=sa/PWD=admin/READONLY=N/FBS=10/SVT=SQLSERVER/DATABASE=pubs/OPTIONS=-H sqlhost.example.com -V 8.0 -P 1433/`
NOTE. The JDBC Driver classname must be passed as the Database DSN attribute, and the associated jar file must be in the active CLASSPATH.

For connections to ODBC Data Sources

Option Setting	Details	Example
`<local ODBC DSN>` (no flag)	Required. Pass an ODBC DSN as defined on the Broker host.	`my_odbc_dsn`

For connections to Oracle

Option Setting	Details	Example
*`<Oracle SQLNet or Net Service Name>`** (no flag)	Pass an Oracle Service Name, as defined in `tnsnames.ora`.	`oracle.example.com`
`<Oracle Connection String>` (no flag)	Pass an Oracle connection string.	`"scott/tiger@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=oracle-host.example.com)(PORT=1521)))(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=oracle.example.com)))"`

For connections to PostgreSQL

Option Setting	Details	Example
`-H <hostname or IP address>`	Required Fully-qualified domain name (i.e., DNS-resolvable hostname) or IP address of the PostgreSQL host machine.	`-H postgresql-host.example.com`

For connections to Progress / OpenEdge

The following options are not required for Shared Memory-mode connections -- which are only possible with SQL-89 drivers, and only when those drivers have been linked to exactly the same Progress library versions as are installed on the current host.

These options are all required for Sockets-mode connections. Any connection may be made in sockets mode if Progress instance has been started with this mode enabled.

Connection must be made in sockets mode when using --

a Single-Tier Driver (whether SQL-89 or SQL-92),
a SQL-92 Driver (whether Single-Tier or Multi-Tier),
a Multi-Tier Database Agent (whether SQL-89 or SQL-92) that is not located on the same host as the Progress instance, and
a SQL-89 Driver (whether Single-Tier or Multi-Tier) that has not been linked to the exact same Progress library versions as are installed on the current driver host.

Option Setting	Details	Example
`-S <socket service name or port number>`	Socket service port number, or associated service name as set in `/etc/services` or equivalent.	`-S 1234`
`-H <hostname or IP address>`	Fully-qualified domain name (i.e., DNS-resolvable hostname) or IP address of the Progress host machine.	`-H progress-host.example.com`
`-N tcp`	Always use this value.	`-N tcp`

For connections to Sybase

Option Setting	Details	Example
`-H <hostname or IP address>`	Required Fully-qualified domain name (i.e., DNS-resolvable hostname) or IP address of the Sybase host machine.	`-H sybase-host.example.com`
`-V <version>`	Required TDSVer value. Sets the Sybase network protocol version the driver will use to communicate with the target instance. Acceptable values are `4.6` for Sybase SQL Server 4.x, and `5.0` for all other Sybase versions.	`-V 5.0`
`-P <port number>`	Required Sybase listen port	`-P 4100`
`-S <instance names>`	Sybase instance name. Generally not necessary when host and port are correctly specified, but sometimes required even then.	`-S MySybaseInstance`
`-N <size>`	Network Packet Size determines the number of bytes per network packet transferred from the Sybase server to the Database Agent or Lite Driver. This attribute can have significant impact on performance. When set to `0` (default), the driver uses the default packet size as specified in the Sybase server configuration. When set to `-1`, the driver computes the maximum allowable packet size on the first connect to the data source and saves the value in the system information. When set to an integer from 1 to 10, this indicates a multiple of 512 bytes (for example, Packet Size of 6 means to set the packet size to 6 * 512 equal 3072 bytes). For this setting to have any impact, the server must be configured for a maximum network packet size greater than or equal to the value specified here.	`-N 0`
`-C <character set>`	The name of the character set the OpenLink driver should deliver to the client application, to be translated from the Server's character set. By default, this is taken from the application's environment. Only valid for non-Unicode drivers. Unicode drivers always deliver UCS-2 on Windows and UCS-4 on Mac OS X and Unix-like OS.	`-C ISO-8859-1`
`-O <value>`	Determines whether stored procedures are created on the server for every call to `SQLPrepare()`. Acceptable values are "2" (Full), "1" (Partial, the default), and "0" (None). Effects of this setting.	`-O 1`

Upgrades and existing installations

Finding out what is installed, and moving to a newer release.

Upgrades & Pre-Existing Installations

Identifying Pre-existing Installations

Use the following instructions to search for pre-existing OpenLink components on partner-supplied machines and other hardware:

1. Open Windows ODBC Data Sources Administrators or Mac iODBC Data Sources Administrators. Click on the Drivers tab. Look for OpenLink driver entries.

2. Open Windows registries. Expand the HKEY_ LOCAL_ MACHINE\SOFTWARE\ODBC\ODBCINST.INI tree structure. Look for OpenLink driver entries.

3. Use the Windows explorer to search for oplrqb.exe, olod*.dll, or lite32.

4. Open the Windows Services utility and look for an OpenLink Request Broker or License Manager service.

5. Log in to Mac OS X machines and open the Applications folder. Look for an OpenLink=>Universal Data Access Drivers folder structure.

6. Log in to Unix machines and use the find / -name file -print command to search for the following files: oplrqb, oplodbc.s*, openlink.ini

Discovery of one or more of these files confirms the presence of OpenLink's Multi-Tier, Single-Tier or Express Edition drivers. If you want to install new software, you have two options:

7. Remove the old software and start fresh.

8. Obtain version information from the existing software and obtain new components from the same build.

Upgrades & Pre-Existing Installations

Mixing & Matching Components from Different Versions

OpenLink Software does not support mixed-version installations. Mismatched client and server software may not hinder your ability to connect and query. However, version incompatibility issues will arise over time. In fact, if you mix OpenLink 3.x and OpenLink 4.x software, you can expect specific problems with stability, transactions, and threading. These problems may only be resolved by upgrading the older component.

Be advised: Under rare circumstances, you may be forced to deploy a mixed installation. As stated previously, 3.x and 4.x components tend to generate problems. However, 4.x client components appear to work well with 5.x server components.

Upgrades & Pre-Existing Installations

Detecting Sofware Versions

You may employ a variety of methods to obtain your product version information. Windows and Mac Single-Tier users should open their ODBC Administrator. The Single-Tier driver version appears on the Drivers tab of this Administrator. Users simple scroll through the Driver list box, locate their driver, and record the version string, which appears to the right of the driver name.

Windows & Mac Client Drivers (Express Edition/Single-Tier/Multi-Tier)

1. Open your ODBC Data Sources Administrator or iODBC Data Sources Administrator.
2. Click the Drivers tab.
3. Scroll through the list box until you locate the OpenLink driver.
4. View the driver version information that appears to the right of the driver name.

Unix Client Drivers (Single-Tier/Multi-Tier)

1. Login to the client machine.
2. cd into the root of the OpenLink installation.
3. Execute the openlink.sh or openlink.csh shell script.
4. cd into the /samples/ODBC (MT) or /bin (ST) sub-directory of the installation.
5. Use odbctest or iodbctest to connect to your Data Source.
6. View the driver version information that appears above the SQL> prompt.
7. Alternatively, run one of the following commands from the /lib sub-directory:

HP-UX	strings *.sl	grep "Driver"	sort -u
All Other Unix	strings *.so	grep "Driver"	sort -u

Multi-Tier Server Components (All Platforms)

1. Open a DOS Command Prompt, Unix console terminal, or similar command line utility.
2. cd into the /bin sub-directory of the OpenLink server components installation.
3. Type the broker or agent name and append -? or ?v to the end of the name. For example:

oplrqb -?
ingii_mv -?
sql_mv -?

4. Record the version information that is returned by the broker or agent.

Upgrades & Pre-Existing Installations

Running Multiple Versions Simultaneously

You can run multiple driver versions for comparative and diagnostic purposes. Take the following action to proceed:

Single-Tier & Express Edition Drivers

Multi-Tier Drivers

1. Shutdown your License Manager, if you have OpenLink 6.0 drivers installed.
2. Install your new drivers in a separate directory.
3. Place your new license files in the /bin sub-directory of the new installation.
4. Restart your License Manager, if you have OpenLink 6.0 drivers installed.
5. Use a text editor to open the oplrqb.ini files that appear in the /bin sub-directories of both Multi-Tier server component installations.
6. Locate the [Protocol TCP] section. For example:

INI

  [Protocol TCP]
PingWatchdog = No
PingInterval = 600
Listen     = 5000
PortLow    = 5000
PortHigh    = 5025
;IPAddress    = 127.0.0.1

7. Insure that each Listen port references a different, unused TCP/IP port. (Use PortLow for OpenLink 1.x-3.x.)

8. Save any changes to the oplrqb.ini files.

9. Start your Request Brokers.

BE ADVISED: The above instructions may not bring success in all scenarios. The following issues could present challenges that warrant attention from OpenLink Product Support:

1. Differing Windows driver versions may share the same .dll name. This could provide configuration challenges.

2. Some Windows installers may force you to remove an older installation.

3. OpenLink's 1.x and 3.x use UDP ports to broadcast license information. You need to contact Product Support for specialized configuration in this instance.

Upgrades & Pre-Existing Installations

Installing New Software on Top of Old Software

You can install new software on top of existing software. However, this is not the preferred course of action, in many circumstances. You should install new software to new directories, if you are attempting to compare software performance or troubleshoot problems.

Uninstalling Our Components

Removing installations of our components takes different steps for different platforms.

Windows

You may use the uninstall utility to remove existing Windows software. You may also use the Add/Remove Programs utility, which appears in the Control Panel.

Mac OS X

The following sequence will cleanly remove all iODBC and Data Access components added by our installers.

Double-click the Uninstall.command script (/Applications/OpenLink/Universal Data Access Drivers (* Tier Edition)). If the script is not present, skip ahead to #3.
Answer the questions posed by the script. Please note that you must answer with the mixed-case, full-word answers. Anything other than `Yes`, `All`, or `Quit`, will be interpreted as `No`, including `y`, `Y`, and `yes`.

Verify that all of the following directories (including contents), and specified individual files, have been removed --

Example

/Applications/iODBC
/Applications/OpenLink*
/Library/Application Support/iodbc
/Library/Application Support/openlink
/Library/Frameworks/iODBC*
/Library/Java/Extensions/libopljodbc*.jnilib
/Library/Java/Extensions/opljdbc*.jar
/Library/Java/Extensions/virtjdbc*.jar
/Library/LaunchDaemons/com.openlinksw.*
/Library/ODBC/OpenLink*
/Library/Receipts/iODBC*
/Library/Receipts/Opl*
/Library/Receipts/UDA*
/Library/Receipts/VIRT*
/Library/Receipts/Virt*
/Library/StartupItems/Oplmgr
/Users/*/Library/Preferences/com.openlinksw*
/Users/*/Library/Saved Application State/com.openlinksw*
/private/var/db/receipts/com.openlinksw.*

You can copy and paste the following command into Terminal.app to remove all of the above --

Shell

sudo rm -rf /Applications/iODBC /Applications/OpenLink* "/Library/Application Support/iodbc" "/Library/Application Support/openlink" /Library/Frameworks/iODBC* /Library/LaunchDaemons/com.openlinksw.* /Library/ODBC/OpenLink* /Library/Receipts/iODBC* /Library/Receipts/Opl* /Library/Receipts/UDA* /Library/Receipts/VIRT* /Library/Receipts/Virt* /Library/StartupItems/Oplmgr /Library/Java/Extensions/libopljodbc* /Library/Java/Extensions/opljdbc* /Library/Java/Extensions/virtjdbc* /Users/*/Library/Preferences/com.openlinksw* /Users/*/Library/Saved\ Application\ State/com.openlinksw* /private/var/db/receipts/com.openlinksw.*

Unix-like OS -- AIX, HP-UX, Linux, Solaris, etc.

We do not provide an uninstall utility for Unix-like platforms. rm and rmdir should be used to remove existing deployments.

Upgrades & Pre-Existing Installations

Performing Upgrades

Express Edition Upgrades

1. Terminate active ODBC connections.
2. Back up your license file.
3. Make sure you have the appropriate version JDK/JRE installed.
4. Perform your upgrade.

Single-Tier Upgrades

1. Terminate active ODBC connections, which use OpenLink's drivers.
2. Back up license files.
3. Back-up existing odbc.ini and openlink.ini files. (Unix Only)
4. Terminate the License Manager service if you use OpenLink 6.0 or newer drivers.
5. Proceed with the upgrade.

Multi-Tier Upgrades
1. Terminate active ODBC connections, which use OpenLink's drivers.
2. Stop your Request Broker and License Manager services. (License Managers are an OpenLink 6.0 and higher feature.)
3. Back-up your license and oplrqb.ini files.
4. Back-up odbc.ini files. (Unix Client Installs Only.)
5. Proceed with their upgrades.

BE ADVISED: Some installers present two options: 1) Upgrade Driver Name, 2) Install New Driver. The first option should overwrite older drivers. DSNs that use those drivers will be affected. They should be migrated to the new driver. However, to insure the integrity of existing DSNs, choose the second option. This option installs the new driver alongside the old driver. Pre-existing DSNs should not be affected in any way.

Upgrades & Pre-Existing Installations

Reasons to Upgrade

Consultants should encourage end-users to upgrade to the latest software version. The latest software contains desirable new features and fixes for bugs. Additionally, support options are limited, when legacy software is involved. Development does not back-patch legacy bugs, and Support staff may have difficulties recreating legacy problems.

The following table lists new features for recent software builds:

Build	Features
4.x	ODBC 3.5 compliancy. Multi-Threaded client & server components. Substantially-revised communications layer.
5.x	Unicode support. Zero Config. Best communications layer.

← Informix JDBC driver

Before you install

Requirements for Informix

Basic DBMS & DBMS Version Support

Database Native Client Requirements

Key Database Native Variables (Set Before OpenLink Install)

Database Native Settings You Need to Know

Database Configuration for Unicode

Database Configuration for XA Support

Do OpenLink drivers connect to Informix?

Informix version support

Detecting the Informix DBMS version

Understanding the Informix native client

When do I need the Informix native client?

Obtain the Informix native client (a.k.a "Informix Connect", "Informix-Net" "I-Net")

Configure the Informix native client

Perform the following steps on Windows:

Perform the following steps on Unix:

INFORMIXDIR

INFORMIXSERVER

Unix Database Servers

Windows Database Servers

Unix Database Servers

Windows Database Servers

Ramifications

Unix Database Servers

Windows Database Servers

Unix Database Servers

Windows Database Servers

Unix Database Servers

Windows Database Servers

Database Configuration for Unicode

Informix 9.x

Configuring Informix for XA support

Enable Database Logging

Useful Links

Client components

Installation Guide

Configuration Guide

Walkthrough with screenshots

Installation walkthrough with screenshots

OpenLink Multi-Tier Server Components Installation and Configuration

Installation

Configuration

Configuration and upgrades

Administering the Multi-Tier components

Domain Aliases

User Aliases

OpSys (Operating System) Aliases

Machine Aliases

Application Aliases

Determining The Values of Multi-Tier Client Generated Connection Attributes

Advanced Server Components Configuration (Multi-Tier)

Server-side Configuration for SSL

Advanced configuration for Informix

Numeric Data Type Mappings in our Data Access Drivers for Informix

Precision of C Data Types

Informix Jetfix Testing

Configure Informix Unicode Support

Advanced configuration for all databases

Unconfigurable Ports

Configurable Ports

Related Documentation

Related Documentation

General Guidance, for Windows, Linux, and other Unix-like OS (except macOS)

Special Guidance for Release 6.x or 7.x on macOS Snow Leopard (10.8.x) and later

Related Documentation

Related Documentation

Issue:

Resolution:

To Uninstall

Configure Intersolv, Merant or DataDirect Driver Managers to Use OpenLink Drivers

Customize Your Multi-Tier Security

Hide Login Boxes on Windows Clients

Pre-requisites for relinking Database Agents

Requirements for all Database Agents

Additional Informix-specific requirements

Additional Progress-specific requirements

Relinking Database Agents for all DBMS

Related

Changing User Access