OpenLink Database Agents Administration

Introduction

Obtaining Database Agent Information

Configuring OpenLink Database Agents

Wizards Based Configuration
Forms Based Configuration

Database Specific Settings

Informix | Ingres | Progress | Oracle | Sybase | MS SQLServer | DB2 | Solid | Postgres | Velocis | Unify

Introduction

OpenLink Database Agents are the only database specific components within the OpenLink Multi-Tier middleware framework. It is these components that actually initiate and maintain database sessions with your OpenLink Clients, basically playing the role of a data access server.

Database Agents are servers implementing client data access interfaces such as ODBC, JDBC, UDBC, and OLE-DB using the lower level native call level interfaces provided by each supported database engine. These call level interfaces are themselves increasing based on the X/Open SQL Call Level Interface (CLI) specification. The older database engines that do not support or implement the X/Open SQL CLI specification simply provide  traditional Embedded SQL interfaces.

The fact that a Database Agents are built using natives interfaces provided by database engine vendors has some very important implications:

1. Through the eyes of a backend database, a  database agent is a database client, no different to any other native client provided or bundled with the backend database engine.
   
   
2. A database agent inherits all of the functionality of a traditional database client, this includes: Distributed Database, SQL syntax, Stored Procedure support, and anything else that may be specific to the relevant database engine.
   
   
3. Configuring a database agent is no different to configuring a native database client, they share operating system environment variable dependencies etc..
   
   
4. Resource utilization is identical to resource consumption for native clients, this means that if you have special setting for your native client sessions, you will be able to apply these when configuring your database agents.
   
   
5. Any efficiencies or deficiencies in the database engines CLI client to database server  inter process communications (IPC) also affects a database agent.

Obtaining Database Agent Information

OpenLink Database agents have a specific naming convention, reflecting the fact that these components are specific to both a particular database engine, and in some case specific versions of a given database engine.

The OpenLink executable binary file naming convention consists of three distinctive logical parts:

• Database Engine - first three characters
  
• Database Version - next two-three characters (depending on database engine version number-functionality issues)
  
• OpenLink Service Provider Identifier - the characters "_sv"

The table below shows you how the current pool of OpenLink Database agents are identified based on the convention described above:

Version, Release, and Functionality Related Information

In a manner similar to the Request Broker, you can obtain component version, release, and functionality related information about your database agent through your operating system's command line interface.

To obtain the information about your database agent simply type in the name of the binary executable file for the relevant agent and the "-?" switch. The example below shows how this is done assuming you are seeking information about the OpenLink Virtuoso™ database agent:

virt_sv -?

The output returned is depicted below:

OpenLink Virtuoso Database Agent
Version 1.2 (Release 3.2) as of Fri Feb 05 1999 (cvsid 00048).
Compiled for Linux 2.0.36 (i586-pc-linux-gnulibc1)
Copyright (C) OpenLink Software.

Usage:
virt_sv [-CmijrlLd] [+noautocommit] [+maxrows num] [+initsql arg] [+jetfix] [+norowsetlimit] [+loglevel num] [+logfile arg] [+debug]

+noautocommit turn autocommit off by default
+maxrows maximum allowed rows to fetch
+initsql execute SQL from this file for every connection made
+jetfix Jet Engine Compatibility Features
+norowsetlimit turn off rowset size limit
+loglevel log level
+logfile log file
+debug debug mode

Deciphering The Information Output

Version Number - this is a component identifier that indicates the version number specific of a specific database agent.

Release Number - this is an identifier for a collection of OpenLink Components, numerous components with different version numbers make up an OpenLink Data Access Drivers commercial release. This is how you determine to what commercial release your database agent belongs.

Compilation Date - indicates the date the database agent component was compiled.

CVSID - this is a source code archive identifier that relates to the actual source code archive from which a database agent has been assembled.

Binary Platform - indicates what platform the database agent has been built to run on.

USAGE - describes the command line options that are to be used with a particular database agent, these can be database agent specific. The command line options are to be used within the Database Agent configuration section of "Session Rules Book" (the file oplrqb.ini), this is the section that handles database agent specific items.  You can add these entries as required to the rule book, you do so by manually editing the rule book file or via the Web based Admin Assistant (see section on Configuring Database Agents).

Configuring OpenLink Database Agents

All database engines operate under a client-server paradigm, that is to say there are always two distinct processes involved in a database session, the database server and the database client. The database server must be up and running before a database client can communicate with a database. Database client and server processes may or may not reside on the same physical machine, at the same time this has no bearing on the fundamentals of database client and server process interaction as just explained.

Every database engine has one or more key values that need to be set in order for database clients to be able to communicate with database servers. These values take the form of host operating system environment variables, database connection string formats/parameters, or a combination of both.

Configuring your OpenLink database agent is all about creating session initialization templates in the Sessions Rules Book which map key database client values with OpenLink Agent Tempalate Attributes.

OpenLink provides two user friendly utilities for configuring your database agents, namely the OpenLink Admin Assistant and the OpenLink Configuration Utility ( "oplcfg" ). A third option is to edit the rule book manually, but the availability of these utilities makes this a less recommended option, certainly one for experienced OpenLink users only.

OpenLink Configuration Utility ("oplcfg")

At the end of the end of your OpenLink server components installation process, the installation program will automatically start the "oplcfg" utility, thereby enabling you to configure your database agent(s) as part of the installation process.

If you have already installed your server components successfully but need to make changes to your initial database agent setting then you can initialize the "oplcfg" utility from the your host operating system's command line prompt, simply enter the following command from within the "bin" sub-directory under your base OpenLink server components installation directory:

oplcfg

You will then be presented with a character based menu system as depicted below:

 OpenLink Server Components Configuration Utility

1.  Request Broker

11. PostgresSQL

2.  Informix 5

12.  Progress 6

3.  Informix 6

13.  Progress 7

4.  Informix 7

14.  Progress 8

5.  Progress 6

15.  Solid

6.  Virtuoso

16.  Sybase 4

7.  OpenProgress

17.  Sybase 10

8.  Oracle 6

18.  Sybase 11

9.  Oracle 7

19.  Unify 2000

10. Oracle 8

20.  Velocis

U.  Undo last change

V.  View the current Rules Book

C.  Clear log file

L.  View log file

B.  Backup Rules Book

R.  Restore Rules Book

I.  Verify Rules Book

N.  Reinitialize running Broker

S.  Startup  Request Broker

D.  Shutdown Request Broker

Choose an item or type q to quit :

You then enter a number that matches the database engine that you will be configuring your database agent(s) to work with.

You will be prompted for each value.

Once this is completed you will have to edit the rule book (the file "oplrqb.ini") manually in order to set up any database session specific values. Another option is to start up the Admin Assistant which provides an intuitive GUI for configuring your database agents.

OpenLink Admin Assistant

The preferred and much more flexible way of configuring your database agents is through the OpenLink Admin Assistant. This is a powerful HTML based GUI that is usable from any Web Browser, it provides you with two approaches to configuring database agents using Wizards or forms.

Wizard Based Database Agent Administration

This approach to database agent administration is going to be exemplified using OpenLink Virtuoso™ as the database agent that is being administered. Please note that nothing in this example is database specific beyond the actual values entered. A database specific section follows which addresses these issues on database engine specific basis.

1. Start the Admin Assistant by entering the following URL into your browser: http://<IP Address or Network Alias of machine hosting the OpenLink Database Agents to be Administered>:<Admin Assistant Port number>/
   
   For a network machine aliased as "mainserver" using the default OpenLink Admin Assistant port "8000" the URL required would be entered as follows: http://mainserver:8000/
   
   You will be presented with a screen similar to the one below:
   
   
   
   
   
2. Expand the "Server Components Administration", and "Database Agent Administration" menus. Once this is done you need to then click on the "OpenLink Database Agent Settings (Wizard)" hyperlink. This will bring you to the first Database Agent Wizard dialog as depicted below:
   
   
   
   
   
3. From the list of pre-configured database agents select one that matches the database engine that your database agent will be communicating with, note that every database supported by OpenLink will have a pre-configured default agent initialization template listed.
   
   
   
   
   
4. Click the "Edit" button to commence re configuring this database agent for your specific needs. Enter a name in the "Agent Name" field that is to be used to identify the database agent configuration section that your are configuring (it is recommended that you keep the default, if you do opt for a new name please do not enter names that contain spaces and remember that you need a mapping rule to accept the new name), also enter text into the "Comment" field describing your database agent. Once completed click on the "Next" button.
   
   
   
   
   
5. You can force your OpenLink clients to connect to a database using a pre-assigned username and password combination, this is done by entering the values that you want to enforce into the "User Name" and "Password" fields in the Wizard dialog depicted below. This activity implies that irrespective of what username password combination is entered at OpenLink client configuration or connect time, the values that you provide will take precedence. If you do not want to enforce username and password combinations for your OpenLink clients simply leave the "User Name" and "Password" fields blank. Click on the "Next" button to continue.
   
   
   
   
   
6. Enter a value in the "Database Name" field that identifies the actual database within your database engine's environment that you want to connect your OpenLink clients with, the format of these values vary by database engine type. You can control what type of session(s) your OpenLink clients conduct with your backend database by choosing the appropriate value from the "Read Only Specifier" listbox. If you are connecting to a database that does not reside on the same machine as your database agent, or circumstances require you to use the networking middleware provided by your database vendor (which is already installed on the same machine as the database agent), then you can enter the remote database connection values required by your remote database into the "ConnectOptions" field. Once completed click the "Next" button to continue.
   
   
   
   
   
7. Some database engines allow their clients to configure session resources, in situations where this holds true you can use the "Server Options" field to set these values for your database agent sessions.
   
   You can also configure your database agents such that the database agent that services OpenLink clients acts as a PROXY to other database agents residing on a remote OpenLink server(s) within your network infrastructure. This is basically a 3-Tier or N-Tier Distributed Database Agent configuration and the key configuration values go into the "Domain Type" and "Host Name" fields.
   
   Domain Type - this is your OpenLink agent Server type (Virtuoso, Oracle. Informix, ODBC, PROXY, etc..), in the case of a typical 3-tier configuration you would enter the value PROXY, this implies that you are going to a PROXY agent rather than an database agent.
   
   Host Name - this is how you identify the machine hosting the Request Broker that binds your OpenLink clients with the OpenLink agent designated by the value entered into the "Domain Type" field.
   
   In most case all of these fields can simply be left blank. Click on the "Next button to continue.
   
   
   
   
   
8. For security purposes there are times when you want to validate your OpenLink clients at the operating system level before they actually initiate sessions with your backend database. In some cases backend databases presume that your ability to attempt database connection implies your being a valid operating system users, this can be a major security hole for those database engines that do not conduct their own username and password verification. By checking the "Require Operating System Identity" checkbox your database agent will validate OpenLink clients at the operating system level before attempting a connection to your backend database. Click the "Next" button to continue.
   
   
   
   
   
9. You can enforce consistent transaction behavior across your OpenLink clients through the "No Auto Commit On Startup" field, this ensures that database commands originating from OpenLink clients do not contain trailing "Commit" instructions. Without this restriction database integrity could easily be compromised by incomplete transactions creating broken records. You enable this protection by checking the "No Auto Commit On Startup" checkbox.
   
   You can also enforce application specific datatype translation handling specifically for Microsoft Jet Engine based OpenLink ODBC clients by checking the "Jet Engine Catalogs" checkbox. This is a very application specific feature that is only required for when Microsoft's Jet engine is the OpenLink ODBC client.  Note that applications such as MS Access and some aspects of VB use the Jet Engine.
   
   Click the "Next" button to continue.
   
   
   
   
   
10. There are times when you may want to restrict the number of records that your database agent transmits to your OpenLink clients. In such scenarios you can enter a numeric value into the "Limit result set" field that represents the maximum number of records from a database query resultset that your database agent should transmit back to your OpenLink clients. This features protects your network from "Innocent Queries From Hell", these are queries that end-user unknowingly generate when using visual query tools, especially as they familiarize themselves with the concepts of SQL querying.
    
    There are also times when critical database functionality may not be implemented as part of the ODBC. JDBC., UDBC,or OLE-DB specifications, but you need to make use of such functionality in order to run your database infrastructure smoothly. When this situation arises you are able to use the "Initial SQL script" field to enter a value that points to a script file containing a set of SQL instructions that implemented the desired functionality.
    
    In some cases you may find yourself having to deal with the fact that although the functionality may be implemented at the ODBC, UDBC, JDBC, OLE-DB specification level, the client application connecting to your database via OpenLink simply isn't making use of this functionality. In this scenario the "Initial SQL Script" field comes in handy. A typical example is default Transaction Isolation Levels handling.
    
    Click "Next" to continue.
    
    
    
    
    
11. You identify the binary executable file that represents the specific database agent for your backend database by entering the binary files name in the "Executable Name" field. This is set for you by default and unless you rename this file yourself it does not need to be changed.
    
    Many database environments are driven by operating system level environment variables, the "Environment Variables" field allows you to set or re-configure these values (see database specific settings section). Click the "Next" button to continue.
    
    
    
    
    
12. There may be some database agent specific options that you need to apply specifically to sessions with your backend database (see usage part of "obtaining database agent information" section for list of values), you enter these values into the "Other Options" field.
    
    You also need to indicate the directory in which your database agent executable binary file resides, this is only required if you have moved these files from their default location after installation.  This field will accept either a full path or a path relative to the Request Broker.  Click the "Next Button" to continue.
    
    
    
    
    
13. Your database agents act as servers to your OpenLink clients, this implies that as server processes they do consume server operating system resources. You can control resource consumption by predefining how many database agent instances are to be started as a result of OpenLink clients connections, and the basis upon which these instance are reused by subsequent OpenLink client connections.  The "Never", "Always", and "Conditionally" radio button allows you to choose the option that best suits your infrastructure's needs.
    
    The "Accept Up To" field allows you to enter a numeric value that indicates the maximum number of new database agent processes that can be instantiated on a given OpenLink server operating environment.
    
    
    
    
    
    If you choose the "Conditionally" radio button and then click the "Next" button you will be presented with an additional dialog with a list of checkboxes. These checkboxes allow you to customize the sets of circumstances under which you want an OpenLink client connection to result in the instantiation of a new database agent instances. Click the "Next" button to continue.
    
    
    
    
    
14. At the end of this Wizard interaction you can opt to make you database agent settings available to the next OpenLink client without shutting down and restarting the Request Broker, you do this by checking the "Reinitialize" checkbox and then clicking the "Save" button to save your settings.
    
    
    
    
    
    

Forms Based Database Agent Administration

You can also administer database agents through the Admin Assistant using a "Forms" as opposed to "Wizards" based approach, the steps that follow guide you through this process using the same example (configuring the a database agent for the OpenLink Virtuoso™ database).

1. Start the Admin Assistant by entering the following URL into your browser: http://<IP Address or Network Alias of machine hosting the OpenLink Database Agents to be Administered>:<Admin Assistant Port number>/
   
   For a network machine aliased as "mainserver" using the default OpenLink Admin Assistant port "8000" the URL required would be entered as follows: http://mainserver:8000/
   
   Expand the menus for "Server Components Administration", and "Database Agent Administration". Once this is done you need to then click on the "Database Agent Settings (Form)" hyperlink. This will bring you to a database agent listing as depicted below:
   
   
   
   
   
2. As our example for this exercise is based on the OpenLink Virtuoso database agent, click on the "Edit" hyperlink for the "generic_virt" default database agent (note you can substitute this with the default database agent that matches your backend database). Once these actions are completed you will be presented with the main database agent initialization template form. Complete the values for the fields that apply to needs and then click on the "Update" button at the bottom of the form to save your changes.
   
   
   
   
   
3. Click on the "Reinitialize Your OpenLink Request Broker With New Settings" hyperlink, this enables your new setting to be applied to subsequent connections from OpenLink clients without disrupting existing OpenLink client sessions.
   
   
   
   

Database Specific Settings

OpenLink database agents are database clients built using the SQL Call Level or Embedded SQL interfaces of the respective supported backend database engines. Thus, the process of configuring or administering a database agent is similar in essence to what you would have to do if you were administering a native database client.

Database engines use environment variables to creating a database specific operating space within which database clients and servers interact, these environments typically address the following important database session related issues:

• Database server identification - your database client needs to be able to connect to the appropriate database server, many database implementations support multiple   database servers instances listening for client connections at different network ports on the same machine (e.g. OpenLink Virtuoso, Microsoft SQL Server, Sybase, Progress, Informix etc.).
  
• Database engine base installation directory - many database engine environments comprise shared or dynamically linked libraries and other runtime components that are required by database clients. Thus, there is a need for database clients to have a sense of what the actual base or root point of the database engine installation is, this enables the construct of a component search path (similar to the "PATH" operating system environment variable) at runtime.
  
• Database session resource allocation - most database engines allow database session resources to be configured for clients via environment variables (sometimes these variables simply identify resource configuration files).
  
• Database session optimization - some database environments allow query optimizers, network packet sizes, and records transmission values for database clients to be configured via environment variables.

The sections that follow address specific environment settings that affect the configuration of your OpenLink database agents, the values provided can supplanted values used in the Admin Assistant configuration examples provided in the prior section.

Virtuoso Specific Configuration Issues

When configuring a Virtuoso database agent the critical configuration items are:

• Database Identification  - this is the Virtuoso Database Server's port number, which identifies the actual Virtuoso server process that links you to an actual virtuoso database file. This is the value that you enter into the "Database Name" field of either your Admin Assistant form or wizard dialog.

Application Server & 3-Tier Architecture Configuration

There may be situations in which you are unable to install your OpenLink Request Broker and Database Agents on the same machine as the one hosting your Virtuoso database server. Irrespective of the reasons that lead you to this scenario,  it is possible to configure your OpenLink database agents hosted on your Application Server machine such that they connect to a remote Virtuoso database on your Database Server machine using virtuoso's database specific networking as opposed to OpenLink's Database Independent Networking. The end result being a 3-tier distributed OpenLink architecture in which the communication between OpenLink clients and database agents use OpenLink's Database independent Networking, while the communication between the Virtuoso database agent and the Virtuoso database server uses Virtuoso database specific networking.

Configuration Steps:

Assuming you have a Virtuoso Database Server called "mainserver2" that has a Virtuoso server process listening for clients at port 1112

1. Ensure that you have a usable connection to Virtuoso using its native networking.
   
   
2. Add the following value to the "Database Name" field within the Admin Assistant Forms or Wizards used to configure your database agent. If you choose to set this value on the client simply enter the same values into the "Database Name" Attribute associated with the configuration of your OpenLink client (see OpenLink ODBC or JDBC or UDBC client configuration for more details):
   
   mainserver2:1112

You can see illustrations of the various distributed client-server architectures supported by OpenLink database agent by clicking here.

Informix Specific Configuration Issues

When configuring an Informix database agent the critical configuration items are:

• Database Identification - this is an actual database name e.g "stores7", which identifies the actual Informix database file that you want to be connected with. This is the value that you enter into the "Database Name" field of either your Admin Assistant's database agent configuration form or wizard dialog. If you choose to have database identification take place at the client rather than server, you enter this value into the "Database Name" field or connection attribute when configuring your OpenLink client.
  

Informix provides a number of environment variables for configuring database clients, the basic set required for successfully connecting your database agent to an Informix database server are tabulated below:

Security Enhancement

Due to the fact that Informix leaves username and password verification to the host operating system, it is possible to close what could be an ODBC, UDBC, JDBC, or OLE-DB security loophole by utilizing the OpenLink database agent "OpsysLogin" facility which can be enabled through the Admin Assistant. By enabling this feature your Informix database agent will verify user accounts at the operating system level before attempting to connect to your Informix database. It is important to note that "super-user" or Administrator (depending on operating system) privileges are required to successfully use this feature. This implies that the account that starts the request broker must possess one of the aforementioned system level privileges. These privileges aren't required for your actual OpenLink client sessions.

Rebuilding Informix Database agents

OpenLink provides a relinkable library and script files that enable you to rebuild your database agents as shared, as opposed to statically linked binaries, or for the purposes of getting a closer database implementation fit, should  your Informix database environment be a more recent release than the actual version used by OpenLink to build the database agent installed on your system. Please read the Relinking OpenLink Database Agents document for details on how to perform this task.

Application Server & 3-Tier Architecture Configuration

There may be situations in which you are unable to install your OpenLink Request Broker and Database Agents on the same machine as the one hosting your Informix database server. Irrespective of the reasons that lead you to this scenario,  it is possible to configure your OpenLink database agents hosted on your Application Server machine such that they connect to a remote Informix database on your Database Server machine using Informix database specific networking (I-Connect or I-Net) as opposed to OpenLink's Database Independent Networking. The end result being a 3-tier distributed OpenLink architecture in which the communication between OpenLink clients and database agents use OpenLink Database independent Networking, while the communication between the Informix database agent and the Informix database server uses I-Connect or I-Net (depending on Informix version).

Configuration Steps:

Assuming you have an Informix Database Server machine called "mainserver2" that has an Informix I-Connect or I-Net server process running (this is setup and configured via the SQLHOSTS file on the database server machine).

1. On your Application Server (the machine hosting your database agent) create an I-connect or I-Net Connection Alias called "mainserver2" (for purpose of this example only) if a working Connection Alias doesn't already exist on this machine.
   
   
2. Ensure that you have a usable connection to your remote  Informix database using Connection Alias "mainserver2".
   
   
3. Add the following values to the "Database Server Options" field within the Admin Assistant Forms or Wizards used to configure your database agent. If you choose to set this value on the client simply enter the same value into to the "Database Name" Attribute associated with the configuration of your OpenLink client (see OpenLink ODBC or JDBC or UDBC client configuration for more details):
   
   mainserver2
   
   You can also set the INFORMIXSERVER environment variable to "mainserver2".

You can see illustrations of the various distributed client-server architectures supported by OpenLink database agent by clicking here.

Ingres Specific Configuration Issues

When configuring an Ingres database agent the critical configuration items are:

• Database Identification - this is an actual database name e.g "demo", which identifies the actual Ingres database that you want to be connected with. This is the value that you enter into the "Database Name" field of either your Admin Assistant's database agent configuration form or wizard dialog. If you choose to have database identification take at the client rather than server, you enter this value into the "Database Name" field or connection attribute when configuring your OpenLink client.

Progress provides a number of environment variables for configuring database clients, the basic set required for successfully connecting your database agent to an Progress database server are tabulated below:

Database Agent Specific Settings

Security Enhancement:

Due to the fact that Ingres 6.4  leaves username and password verification to the host operating system (Ingres II does not have this problem), it is possible to close what could be an ODBC, UDBC, JDBC, or OLE-DB security loophole by utilizing the OpenLink database agent "OpsysLogin" facility which can be enabled through the Admin Assistant. By enabling this feature your Ingres database agent will verify user accounts at the operating system level before attempting to connect to your Ingres database. It is important to note that "super-user" or Administrator (depending on operating system) privileges are required to successfully use this feature. This implies that the account that starts the request broker must possess one of the aforementioned system level privileges, on the other hand these privileges aren't required for your actual OpenLink client sessions.

Rebuilding Ingres Database agents

OpenLink provides a relinkable library and script files that enable you to rebuild your database agents as shared, as opposed to statically linked binaries, or for the purposes of getting a closer database implementation fit, should  your Ingres database environment be a more recent release than the actual version used by OpenLink to build the database agent installed on your system. Please read the Relinking OpenLink Database Agents document for details on how to perform this task.

Application Server & 3-Tier Architecture Configuration

There may be situations in which you are unable to install your OpenLink Request Broker and Database Agents on the same machine as the one hosting your Ingres database server. Irrespective of the reasons that lead you to this scenario,  it is possible to configure your OpenLink database agents hosted on your Application Server machine such that they connect to a remote Ingres database on your Database Server machine using Ingres database specific networking (Ingres Net) as opposed to OpenLink's Database Independent Networking. The end result being a 3-tier distributed OpenLink architecture in which the communication between OpenLink clients and database agents use OpenLink Database independent Networking, while the communication between the Ingres database agent and the Ingres database server uses Ingres Net.

Configuration Steps:

Assuming that you have an Ingres Database server machine called "mainserver2"  that has an Ingres Net server process running.

1. On your Application Server (the machine hosting your database agent) create an Ingres Net vnode called "mainserver2" (for purpose of this example only) if you do not have a working vnode on this machine.
   
   
2. Ensure that you have a usable connection to your remote Ingres database using the vnode "mainserver2".
   
   
3. Add the following values to the "Server Options" field within the Admin Assistant Forms or Wizards used to configure your database agent. If you choose to set this value on the client simply enter the same value into to the "Database Name" Attribute associated with the configuration of your OpenLink client (see OpenLink ODBC or JDBC or UDBC client configuration for more details):
   
   mainserver2

You can see illustrations of the various distributed client-server architectures supported by OpenLink database agent by clicking here.

Progress Specific Configuration Issues

When configuring a Progress database agent the critical configuration items are:

• Database Identification - this is an actual database name e.g "demo" or "isports", which identifies the actual Progress database file that you want to be connected with. You may need to specify to full path to this file, this is also recommended. This is the value that you enter into the "Database Name" field of either your Admin Assistant form or wizard dialog. If you choose to have database identification take at the client rather than server, you enter this value into the "Database Name" field or connection attribute when configuring your OpenLink client.

Progress provides a number of environment variables for configuring database clients, the basic set required for successfully connecting your database agent to an Progress database server are tabulated below:

To connect to multiple databases through a single OpenLink client connection and/or to make use array type columns you must run the OpenLink provided "setup.p" utility. Please refer to the setup.p document for detailed information on the use of this script.

Configuring Progress Session Resources

You can control default behavior and progress server session resource allocation by entering standard progress session parameters in the "Server Options" field within the Admin Assistant's database agent configuration wizard dialogs or forms.

The following values  are set for you by default at installation time and displayed as depicted below within the "Server Options" fields of the Admin Assistant Forms and Wizard dialogs.

-T /tmp -d mdy -TB 31 -TM 31

The -d mdy option should not be changed inside the Rule Book since it enables the best compatibility with OpenLink.  This will not affect any other Ingres applications.

Database Agent Specific Issues

Progress database servers support sockets and shared memory based methods of Inter Process Communication (IPC), unfortunately the shared memory approach which is much faster than sockets and the preferred approach by many users bears a cost of version incompatibility. This implies that your OpenLink database agents need to be an exact version match with your backend Progress database server in order to successfully initiate shared memory based database sessions (note: these agents are built using the Progress Embedded SQL package).

Rebuilding Progress Database agents

To get around the issue explained above OpenLink provides a relinkable library and script file that enables you to build an OpenLink database agent that has an exact match to the version of Progress that you have installed. See the document on Relinking Progress Agents for details.

If shared memory based IPC isn't an option for you then start your Progress server with the -S, -N, and -H options indicating the use of a sockets based Progress database server. This mode of operation is Progress version independent.

Application Server & 3-Tier Architecture Configuration

There may be situations in which you are unable to install your OpenLink Request Broker and Database Agents on the same machine as the one hosting your Progress database server. Irrespective of the reasons that lead you to this scenario,  it is possible to configure your OpenLink database agents hosted on your Application Server machine such that they connect to a remote Progress database on your Database Server machine using Progress database specific networking (Progress Client Networking) as opposed to OpenLink's Database Independent Networking. The end result being a 3-tier distributed OpenLink architecture in which the communication between OpenLink clients and database agents use OpenLink Database independent Networking, while the communication between the Progress database agent and the Progress database server uses Progress Client Networking.

Configuration Steps:

Assuming you have an Progress Database Server machine called "mainserver2" that has a sockets based Progress Server process running, you would enter the following (assuming a TCP/IP based network):

1. Ensure that you have a usable connection to Progress using its native networking (Progress Client Networking) using the following remote database connection parameters:-S mainserver2 -H mainserver -N tcp .
   
   
2. Add the following values to the "Database Server Options" field within the Admin Assistant Forms or Wizards used to configure your database agent. If you choose to set this value on the client simply enter the same value into to the "Database Name" Attribute associated with the configuration of your OpenLink client (see OpenLink ODBC or JDBC or UDBC client configuration for more details):
   
   -S mainserver2 -H mainserver -N tcp

You can see illustrations of the various distributed client-server architectures supported by OpenLink database agent by clicking here.

Oracle Specific Configuration Issues

When configuring an Oracle database agent the critical configuration items are:

• Database Identification - this is an actual Oracle System Identifier (SID) e.g "ORCL", which identifies the actual Oracle environment that you want to be connected with. This is the value that you enter into the "Database Name" field of either your Admin Assistant's database agent configuration form or wizard dialog. If you choose to have database identification take at the client rather than server, you enter this value into the "Database Name" field or connection attribute when configuring your OpenLink client.

Oracle provides a number of environment variables for configuring database clients, the basic set required for successfully connecting your database agent to an Oracle database server are tabulated below:

Database Agent Specific Settings

The "odbccat.sql" scripts explained:

These scripts exist for each version of Oracle supported, the files "odbccat6.sql", "odbccat7.sql", and "odbccat8.sql" representing Oracle versions 6 up to version 8 respectively. These scripts are to be applied to your Oracle instance to enable efficient and extended functionality between OpenLink and Oracle when handling ODBC, JDBC, UDBC, and OLE-DB catalog calls such as SQLForeignKeys() and SQLPrimaryKeys() functions. These functions have significant impact on the performance of your OpenLink clients.

To run these scripts you need to   start the Oracle server manager (svrmgr or sqldba if you do this from the command line). Connect as internal and run the script by locating the relevant script file as you would any other Oracle SQL script file.

Rebuilding Oracle Database agents

OpenLink provides a relinkable library and script files that enable you to rebuild your database agents as shared, as opposed to statically linked binaries, or for the purposes of getting a closer database implementation fit if your Oracle database environment is a more recent release than the actual version used by OpenLink to build the database agent installed on your system. Please read the Relinking Oracle Agents document for details on how to perform this task.

Application Server & 3-Tier Architecture Configuration

There may be situations in which you are unable to install your OpenLink Request Broker and Database Agents on the same machine as the one hosting your Oracle database server. Irrespective of the reasons that lead you to this scenario,  it is possible to configure your OpenLink database agents hosted on your Application Server machine such that they connect to a remote Oracle database on your Database Server machine using Oracle database specific networking (SQL*Net or Net8) as opposed to OpenLink's Database Independent Networking. The end result being a 3-tier distributed OpenLink architecture in which the communication between OpenLink clients and database agents use OpenLink Database independent Networking, while the communication between the Oracle database agent and the Oracle database server uses Oracle SQL*Net or Net8.

Configuration Steps:

Assuming you have an Oracle Database Server machine called "mainserver2" that has an  Oracle Listener process running, you would enter the following (presuming that your SQL*Net or Net8 alias for this Listener is also named "mainserver2"):

1. On you Application Server (the machine hosting your database agents) create a SQL*Net or Net8 Alias named "mainserver2" (for purposes of this example only).
   
   
2. Ensure that you have a usable connection to the remote Oracle database server using the SQL*Net or Net8 alias "mainserver2"
   
   
3. Add the following values to the "Server Options" field within the Admin Assistant Forms or Wizards used to configure your database agent. If you choose to set this value on the client simply enter the same value into to the "Database Name" Attribute associated with the configuration of your OpenLink client (see OpenLink ODBC or JDBC or UDBC client configuration for more details):
   
   mainserver2

You can see illustrations of the various distributed client-server architectures supported by OpenLink database agent by clicking here.

Sybase Specific Configuration Issues

When configuring a Sybase database agent the critical configuration items are:

• Database Identification - this is an actual Sybase database name e.g "pubs", which identifies the actual Sybase database that you want to be connected with. This is the value that you enter into the "Database Name" field of either your Admin Assistant's database agent configuration form or wizard dialog. If you choose to have database identification take at the client rather than server, you enter this value into the "Database Name" field or connection attribute when configuring your OpenLink client.

Sybase provides a number of environment variables for configuring database clients, the basic set required for successfully connecting your database agent to an Sybase database server are tabulated below:

Rebuilding Sybase Database agents

OpenLink provides a relinkable library and script files that enable you to rebuild your database agents as shared, as opposed to statically linked binaries, or for the purposes of getting a closer database implementation fit, should  your Sybase database environment be a more recent release than the actual version used by OpenLink to build the database agent installed on your system. Please read the Relinking OpenLink Database Agents document for details on how to perform this task.

Application Server & 3-Tier Architecture Configuration

There may be situations in which you are unable to install your OpenLink Request Broker and Database Agents on the same machine as the one hosting your Sybase database server. Irrespective of the reasons that lead you to this scenario,  it is possible to configure your OpenLink database agents hosted on your Application Server machine such that they connect to a remote Sybase database on your Database Server machine using Sybase database specific networking (Open Client) as opposed to OpenLink's Database Independent Networking. The end result being a 3-tier distributed OpenLink architecture in which the communication between OpenLink clients and database agents use OpenLink Database independent Networking, while the communication between the Sybase database agent and the Sybase database server uses Sybase Open Client.

Configuration Steps:

Assuming you have an Sybase Database Server machine called "mainserver2" that has a  Sybase Server named "mainserver2" up and running:

1. On your Application Server (the machine hosting your database agents) create an Open Client Database Connection Alias named "mainserver2" (for purposes of this example only).
   
2. Ensure that you have a usable connection to the remote Sybase database server using the Open Client Database alias "mainserver2"
   
3. Add the following values to the "Server Options" field within the Admin Assistant Forms or Wizards used to configure your database agent. If you choose to set this value on the client simply enter the same value into to the "Database Name" Attribute associated with the configuration of your OpenLink client (see OpenLink ODBC or JDBC or UDBC client configuration for more details):
   
   mainserver2
   
   You may also enter the following values into the "Database Server Options" field:
   
   -S mainserver2

You can see illustrations of the various distributed client-server architectures supported by OpenLink database agent by clicking here.

Microsoft SQL Server Specific Configuration Issues

There aren't any specific environment variables that need to be configured the enable a basic database connection. All of the key setting are automatically resolved by the OpenLink installation program.

Application Server & 3-Tier Architecture Configuration

There may be situations in which you are unable to install your OpenLink Request Broker and Database Agents on the same machine as the one hosting your Microsoft SQL Server database server. Irrespective of the reasons that lead you to this scenario,  it is possible to configure your OpenLink database agents hosted on your Application Server machine such that they connect to a remote Microsoft SQL Server database on your Database Server machine using Microsoft SQL Server database specific networking (NETLIB) as opposed to OpenLink's Database Independent Networking. The end result being a 3-tier distributed OpenLink architecture in which the communication between OpenLink clients and database agents use OpenLink Database independent Networking, while the communication between the Microsoft SQL Server database agent and the Microsoft SQL Server database server uses Microsoft SQL Server's NETLIB.

Configuration Steps:

Assuming you have an Microsoft SQL Server Database Server machine called "oplwinnt" that has a Microsoft SQL Server Server named "oplwinnt" up and running:

1. On you Application Server (the machine hosting your database agents) create a NETLIB Database Connection Alias named "oplwinnt" (for purposes of this example only).
   
   
2. Ensure that you have a usable connection to the remote Microsoft SQL Server database server using the Open Client Database alias "oplwinnt" (this is the value you provide whenever you are prompted for a Server Name by native SQL Server utilities)
   
   
3. Add the following values to the "Server Options" field within the Admin Assistant Forms or Wizards used to configure your database agent. If you choose to set this value on the client simply enter the same value into to the "Database Name" Attribute associated with the configuration of your OpenLink client (see OpenLink ODBC or JDBC or UDBC client configuration for more details):
   
   oplwinnt
   
   You may also enter the following values into the "Database Server Options" field:
   
   -S oplwinnt

You can see illustrations of the various distributed client-server architectures supported by OpenLink database agent by clicking here.

DB2 Specific Configuration Issues

Agent Section

OpsysLogin=No; Validation of users is left to DB2

Database Agent default name: db2_sv

PostgresSQL Specific Configuration Issues

Agent Section

OpSysLogin= Yes; Users are validated against the operating system.

Database Agent default name: pgr95_sv

Unify

Agent Section

OpsysLogin=Yes; Users are validated against the operating system.

Database Agent default name: uni_sv

Velocis

Agent Section

OpsysLogin=No; Users validated against the DBMS.

Database Agent default name: velo_sv