Release 10.1A: OpenEdge Data Management:
DataServer for ODBC

> ## Configuring from the command line

> You may configure a remote DataServer broker process from the command line. You may use the _probrkr.exe executable directly or use the odbman.bat Progress Explorer utility, the command line equivalent of using the Progress Explorer.

> Before you start the configuration tasks, make sure that you have installed your ODBC software and any data-source-specific client software on your host machine. Also make sure that you have registered all of your data sources. See the "Configuring the ODBC driver and registering the data source" section for details.

> To configure from the command line:

> - When using the OpenEdge broker (_probrkr.exe), you set the environment variables described in this section from the command line using environment-variable commands at the DOS shell prompt.

> - When using the `odbman` Progress Explorer utility, set the environment variables described in this section in the environment section of your broker properties file for the specific broker instance definition.

> - You must set and export environment variables in the same environment (DOS shell) from which you plan to run the DataServer.

> Table 3–2 describes the environment variables that you must set.

> Table 3–2: Environment variables for the remote DataServer
> Variable | Description
> --- | ---
> `DSLOGDIR` (Optional) | The pathname of the log file that OpenEdge uses to keep track of DataServer processes and error messages. By default, OpenEdge writes to `%DSLOGDIR%\dataserv.lg` where `%DSLOGDIR%` is resolved to directory path of the log file "`dataserv.lg`".
> `ODBSRV` | The pathname of the OpenEdge server executable. This variable is required only when the DataServer is spawned using the OpenEdge broker (`_probrkr.exe`). When using odbman, this setting is satisfied by the `srvrExecFile` setting in the broker properties file.
> `PROBRKR` | The pathname of the broker executable. When using the OpenEdge broker (_probrkr.exe), set this variable on the host machine to the broker executable name. When using odbman, this setting is satisfied by the broker instance definition in the broker properties file.

> Once you have completely set up your environment, you can build the schema holder for your ODBC data source and connect using the client executable. See the "Creating a schema holder" section for instructions.

> ##### The ubroker.properties file

> When using the Progress Explorer administration framework, you configure the DataServer for ODBC by editing the `%DLC%\properties\ubroker.properties` file. This file stores configuration definitions for all instances of the following OpenEdge products:

> - NameServers

> - AppServers

> - DataServers

> - Databases

> - WebSpeedŽ Transaction Servers

> When you use this file to configure the DataServer for ODBC, you provide information that enables the host to start a broker that spawns the appropriate DataServer process (`_odbsrv.exe`).

> Each configuration definition contains the environment variable and property settings for a broker instance. The command-line utilities use this file to store, validate, and manage the configurations for these brokers. A single copy of this file maintains all supported broker configurations for each OpenEdge installation.

> ##### Editing the ubroker.properties file

> The simplest way to make configuration changes to the `ubroker.properties` file is to copy an existing broker or NameServer definition and then modify the copied values as required for your configuration. To generate a new universally unique identifier (uuid), use the`` `genuuid``` script found in the `bin` directory of your installation. For more information, see the `ubroker.properties.README` file. You must ensure that all related properties and sections of the file are properly specified for each broker or NameServer instance.

> Note: Be sure to preserve the original `%DLC%\properties\ubroker.properties` file. Rename the original file and work with a copy of the file. You must name the copy of the file `ubroker.properties`.

> Table 3–3 describes the sections in the `ubroker.properties` file that apply to the DataServer for ODBC. The file configures a default NameServer named `NameServer.NS1` and a default broker named `odbbroker1`, which you can use either as is or as templates for your own configuration specifications.

> Table 3–3: DataServer for ODBC sections of the ubroker.properties file
> Product | Section | Description
> --- | --- | ---
> All products |
>     ParentGroup
> | Defines the name of each NameServer and product broker parent entity.
>     Environment
> | Default environment variable settings for all NameServers and product brokers.
>     UBroker
> | Defines default property settings for all product brokers.
> NameServer |
>     NameServer
> | The parent entity of NameServers. It defines default property settings for all NameServer instances.
>     NameServer.NS1
> | A sample property entity of a NameServer instance. It defines property settings for this NameServer instance.
>     Environment.NS1
> | A sample environment entity of a NameServer instance. It defines environment variable settings for this NameServer instance.
> DataServer |
>     UBroker.OD
> | The parent entity of DataServer for ODBC brokers. It defines default property settings for all of these broker instances.
>     UBroker.OD.odbbroker1
> | A sample property entity of a DataServer for ODBC broker instance. It defines default property settings for the broker instance named `odbbroker1`. Note that although many of the settings in this section can work in your environment, some of them are for demonstration purposes only. You must specify the appropriate settings for the following: `srvrExecFile`: Specify the pathname of the DataServer executable that the broker runs. The default is `@{DLC}/bin/_odbsrv.exe`, which runs the default DataServer from your OpenEdge install path. `srvrStartupParam`: Specify the OpenEdge startup parameters for the DataServer. Do not modify the default parameters, although you can add parameters if necessary. The `-svub` switch is required for a broker connection in the Progress Explorer administration framework.
>     Environment.odbbroker1
> | A sample environment entity of a DataServer for ODBC broker instance. It defines environment variable settings that apply to the broker instance named `odbbroker1`. Be sure to set the variables to the appropriate values; the values in the file are for demonstration purposes only. Add to this section any environment variables that you want to apply to the DataServer’s environment. See the "Configuring the remote DataServer" section for the environment variable settings required to configure the DataServer for ODBC.

> The following example illustrates the DataServer sections of the `ubroker.properties` file:

>     #
>      #  Default properties for broker instances serving ODBC DataServers
>      #
>      [UBroker.OD]
>          srvrExecFile="@{Startup\DLC}\bin\_odbsrv.exe"
>          srvrStartupParam=-svub -S X -N TCP -U X -P X -hs 0 -s 40
>          operatingMode=State-aware
>          classMain=com.progress.ubroker.broker.ubroker
>          portNumber=4444
>          defaultService=0
>          initialSrvrInstance=0
>          minSrvrInstance=0
>          maxSrvrInstance=256
>          brkrLoggingLevel=3
>          description=ODBC DataServer Broker
>      #
>      # Sample ODBC DataServer Broker definition
>      #
>      [UBroker.OD.odbbroker1]
>          srvrExecFile="@{Startup\DLC}\bin\_odbsrv.exe"
>          srvrStartupParam=-svub -S X -N TCP -U X -P X -hs 0 -s 40
>           srvrLogFile=@{WorkPath}\odbbroker1.server.log
>           brokerLogFile=@{WorkPath}\odbbroker1.broker.log
>           portNumber=4444
>           defaultService=1
>           appserviceNameList=odbbroker1
>           controllingNameServer=NS1
>           environment=odbbroker1
>           uuid=172.18.103.53:1f415c:d6330e5d24:-7f1e
>           description=A sample ODBC DataServer Broker

>      #
>      # Environment for ODBC Dataserver Broker: odbbroker1
>      #
>      [Environment.odbbroker1]
>          DSLOGDIR=@{WorkPath}

> For a complete description of the parameters included in each of these sections, see the comments in the `%DLC%\properties\ubroker.properties` file.

> The `ubroker.properties` file is read on startup of the AdminServer process. For changes in any used environment variables to take effect, the AdminServer must be restarted.

> ##### Validating ubroker.properties content

> Whenever you create your own version of the `ubroker.properties` file, you should use the relevant validation utility to validate your changes and make sure that there are no syntax errors or conflicts. When configuring the DataServer for ODBC, you validate the file by using the `odbconfig` utility. See the "ODBCONFIG utility" section for more information.

> ##### Configuring multiple brokers

> You can configure multiple brokers by adding more `UBroker.OD.``broker–name` and `Environment.``broker–name` sections. Each broker instance must have a unique name. The broker instances inherit the properties that you define in the `UBroker.OD` (parent entity) section, but can override them.

> If you want to access multiple ODBC data sources and configure one or more brokers, each broker must run in a separate directory and a distinct environment.

> ##### Using the NameServer

> By default, your DataServer for ODBC broker instances are defined with a controlling NameServer and are provided with a default Data Service. Progress Software Corporation recommends using a NameServer configuration at all times. In such cases, the DataServer client’s initial connection is to the NameServer. However, you can alternatively connect the DataServer directly to the broker instance by setting the `-DataService` value to none in the connection parameters of your schema holder. If you will always use a `-DataService` value of none, you should remove the controlling NameServer from your broker instance definition. See the "Starting and stopping a broker process from the Progress Explorer and connecting a client" section for more information about connecting the DataServer to the NameServer and the broker. See OpenEdge Getting Started: Installation and Configuration for more information about the NameServer’s role in a configuration.

> Note: Do not simultaneously run some DataServers for ODBC under brokers with controlling NameServers and others directly under brokers (that is, without controlling NameServers). This defeats the purpose of using a NameServer to control brokers. If you do this, the benefits of the NameServer are lost and load balancing is ineffective. Progress Software Corporation recommends that you always use a NameServer, with one exception: you can choose initially to connect directly to a broker to simplify confirming an initial connection. Once you establish a connection, Progress recommends that you reintroduce the NameServer into your configuration.

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095