Progress
DataServer for
Microsoft SQL Server
Guide


Configuring from the Command Line

You may configure a remote DataServer broker process from the command line. You may use the _probrkr.exe executable (the command line equivalent of using ProControl) or use the mssman.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:

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 Progress uses to keep track of DataServer processes and error messages. By default, Progress writes to $DSLOGDIR/dataserv.lg in the current directory.
MSSSRV
The pathname of the Progress server executable. This variable is required only when the DataServer is spawned using the Progress broker (_probrkr.exe). When using mssman, this setting is satisfied by the srvrExecFile setting in the broker properties file.
PROBRKR
The pathname of the broker executable. When using the Progress broker (_probrkr.exe), set this variable on the host machine to the broker executable name. When using mssman.bat, 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 SQL Server™ database 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 SQL Server™ by editing the %DLC%/properties/ubroker.properties file. This file stores configuration definitions for all instances of the following Progress products:

When you use this file to configure the DataServer for SQL Server™, you provide information that enables the host to start a broker that spawns the appropriate DataServer process (_msssrv.exe or a custom executable that you built with PROBUILD).

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 Progress installation.

Editing the ubroker.properties File
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.

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. You must ensure that all related properties and sections of the file are properly specified for each broker or NameServer instance.

Table 3–3 describes the sections in the ubroker.properties file that apply to the DataServer for SQL Server™. The file configures a default NameServer named NameServer.NS1 and a default broker named mssbroker1, which you can use either without editing or as templates for your own configuration specifications.

Table 3–3: DataServer for SQL Server™ 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.MS 
The parent entity of DataServer for SQL Server™ brokers. It defines default property settings for all of these broker instances.
UBroker.MS.mssbroker1 
A sample property entity of a DataServer for SQL Server™ broker instance. It defines default property settings for the broker instance named mssbroker1.
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/_msssrv.exe, which runs the default DataServer from your Progress install path.
srvrStartupParam: Specify the Progress 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.mssbroker1 
A sample environment entity of a DataServer for SQL Server™ broker instance. It defines environment variable settings that apply to the broker instance named mssbroker1.
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 SQL Server™.

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

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

 #
 # Environment for MSS Dataserver Broker: odbbroker1
 #
 [Environment.mssbroker1] 
     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 SQL Server™, you validate the file by using the mssconfig.bat utility. See the "MSSCONFIG Utility" entry in "Server Related Command Line Utilities and Startup Parameters," for more information.

Configuring Multiple Brokers

You can configure multiple brokers by adding more UBroker.MS.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.MS (parent entity) section, but can override them.

If you want to access multiple SQL Server™ databases 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 SQL Server™ 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 in "Connecting the DataServer", for more information about connecting the DataServer to the NameServer and the broker. See the Progress Installation and Configuration Guide Version 9 for Windows or the Progress Installation and Configuration Guide Version 9 for UNIX for more information about the NameServer’s role in a configuration.

NOTE: Do not simultaneously run some DataServers for SQL Server™ 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 © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095