Session Rules Books

The following text highlights sections of the Rulebook that need attention or cause problems:

[Request Broker]
BinaryDirectory  = c:\openlink\openlink software\uda\multi-tier\v5.1\bin
CommandLine		=	 ;+debug
Protocols		  = tcp
;MaxAgents	= 0				 ; if >0, max. # of processes spawned by broker
;MaxConnections	= 0				 ; if >0, max. # of connections from clients
HostNameResolver = Yes	; Resolve IP addresses to hostnames
LingerTimeout	 = 0	; if >0, time in seconds a disconnected agent wil linger

BinaryDirectory can cause problems on machines with multiple installations. Insure that BinaryDirectory passes the correct path.

CommandLine can cause problems by overriding Broker startup options passed on the command line. For instance, you may start the Broker with oplrqb +loglevel 7 +logfile oplrqb.log. This causes the Broker to run in the background and write debug output to a file. However, if -dv is passed to CommandLine, the Broker will run in foreground mode and write diagnostic output to the screen.

HostNameResolver may need to be disabled to prevent "unable to authorize shutdown" errors associated with the Request Broker.

Set LingerTimeout to reduce overhead associated with fresh agent spawns. Use of LingerTimeout insures agents persist after disconnect. This allows new connections to utilize old agents. Thus, problems associated with resources are reduced or eliminated.

[Protocol TCP]
PingWatchdog = No	; Send check-alive packets
PingInterval = 600	;	every <PingInterval> seconds
;IPAddress		= 127.0.0.1		 ; Overrules found interface address
PortLow		= 5025
PortHigh	= 6000
Listen		 = 5025

Use PingWatchDog sparingly. It is associated with problems. Additionally, know that PingWatchDog only terminates connections when an entire client machine is unpingable. It does not reap connections when a specific client application dies.

Set IPAddress to one IP address, when a server has multiple addresses. Then, pass the specific IP address in client data source names. This presents "Remote System" errors that occur when a Broker runs on one address, and a canonical hostname--passed in a client data source--resolves to another IP.

Insure that both PortLow and PortHigh are set. This insures that the Request Broker will have a definitive port range that it can utilize for database agent connections. Failure to set PortHigh results in "Remote System" and other errors that occur when a Broker hits an occupied port and fails to search for a new one.

Listen is the TCP port that users reference in their client Data Source Names. (OpenLink 1.x and 3.x Brokers do not have Listen. Substitute PortLow instead.)

[Communications]
SendSize		 = 16000	; Send buffer size
ReceiveSize	 = 4096	; Receive buffer size
DataEncryption = No	; Crypting of outgoing packets
BrokerTimeout  = 30	; Timeout for utilities to contact the broker
ReceiveTimeout = 10	; Maximum time allowed for for OpenLink Service Agents
RetryTimeout	= 5	; Initial retry interval -- doubles on failure

You should not modify these values, unless a support problem mandates a change. Consult the FAQ associated with the use and meaning of these particular settings.

[Security]
StartupBy	  = .*	; users who can startup oplrqb
ShutdownBy	 = .*	; users who can shutdown oplrqb
ShutdownFrom  = NKHATAM,localhost.*,127.0.0.1
ValidUidRange = 0, 50000	; Valid range for OpSysLogin
;TraceRulebook  = debug.bk		; Write merged rulebook (debug)
;IncludeRulebook= samplesv.bk	; Default location in BinaryDirectory

These parameters are associated with "You are not authorized to initiate shutdown" errors. If this error occurs, you can take the following action:

• Comment out ShutdownBy and ShutdownFrom.
  
• Forcibly terminate the Broker.
  
• Restart the Broker and test normal shutdown.
  
• Uncomment ShutdownBy and ShutdownFrom.
  
• Insure * and your specific uid is passed to ShutdownBy.
  
• Insure *, 127.0.0.1, and the specific IP address are passed to ShutdownFrom.
  
• Forcibly terminate the Broker.
  
• Restart the Broker and test normal shutdown.
  
• Set HostNameResolver=No
  
• Forcibly terminate the Broker.
  
• Restart the Broker and test normal shutdown.

[Environment INFORMIX2000]
INFORMIXSERVER	  = alpha
INFORMIXDIR		  = C:\Informix
Path					= C:\Informix\BIN;C:\WINNT\System32
ONCONFIG			  = ONCONFIG
DELIMIDENT			= Y	; Allow quoted identifiers
OPL_INF_MULTISESS  = Y	; Allow multiple sessions
OPL_SPACEPADCHAR	= Y	; Pad CHAR fields with spaces
CURSOR_SENSITIVITY = LOW	; Set to HIGH after loading oplrvc.sql
;FET_BUF_SIZE			 = 65535			 ; Size of the fetch buffer
;FORCE_ONLINE_DATABASE = 1		; Force mode to (0) SE or (1) ONLINE

Insure that the appropriate environment variables are set in the Environment section that pertains to the OpenLink database agent. Failure to set environment variables will produce "Server Handle" or variable specific error messages.

[Domain Aliases]
Informix 2000						 = inf2000

Insure that the value passed in the DSN's "Domain" or "ServerType?" field appears in the Rules Book's Domain Aliases section. Otherwise, "Broker is unable to resolve your request" errors will occur. (JDBC users must check the value passed to SVT.) If you choose to add an alias, you must also insure that corresponding Mapping Rules, Database Agent configuration sections, and Environment sections are present and configured, as well.

[Mapping Rules]
;*:*:blank:*:*:*:rw	  = reject You should specify a username and password
*:*:Admin:msdos:*:jet:* = reject Admin user account is not registered
inf2000:*:*:*:*:*:*	  = reject The Informix 2000 Database Agent is not configured
inf2000:*:*:*:*:jet:*	= reject The Informix 2000 Database Agent is not configured for jet

Insure that one or more Mapping Rules correspond to the domain alias. The first field of the Mapping Rules passes the value that appears on the right hand side of the Domain Aliases pair. Absence of Mapping Rules will produce "Mapping Not Found" errors.

[generic_inf2000]
Description = Default settings for Informix 2000 agent
Program	  = inf9_mv.exe
Environment = INFORMIX2000
OpsysLogin  = Yes
ReUse		 = always
;Directory	 = c:\temp
;ConnectOptions =
;ReadOnly	=
;CommandLine	=
;Database	=
;Userid		=
;Password	=

The Database Agent configuration sections hardcode values that will be enforced during every connection that uses the section. (DSN settings will be overriden by values hardcoded in the Rules Book.) Environment, Program, and ReUse variables should be set. However, other parameters should not be set to insure flexibility.

Take note of the Opsyslogin, Database, and Userid and Password parameters:

• Opsyslogin substitutes database level authentication with operating system level authentication. This eradicates problems associated with security flaws in certain Ingres and Informix databases. Suspect problems with Opsyslogin if authentication errors reference /etc/shadow, /etc/password, or other operating system files. Be advised - product flaws may occur if the drivers' security routines are written to o/s specific security modules and ported to other machines. Suspect this problem, if no amount of configuration will remedy problems associated with Opsyslogin.

• Database must be used to pass the full path to Progress databases when JDBC Type 3 connections are employed. Type 3 JDBC connection URLs cannot parse the slashes in paths.

• Userid and Password are often uncommented to enforce passage of blank usernames and passwords to unsecured Progress databases. However, this can cause problems, if usernames and passwords are subsequently added to Progress _User tables. Suspect Userid and Password if Progress SQL89 agents produce inexplicable authentication errors.

[generic_inf2000_jet]
Description = Default settings for Informix 2000 agent for jet
Program	  = inf9_mv.exe
Environment = INFORMIX2000
OpsysLogin  = Yes
ReUse		 = always
;Directory	 = c:\temp
;ConnectOptions =
;ReadOnly	=
CommandLine = +jetfix
;Database	=
;Userid		=
;Password	=

The preceding Database Agent configuration section is specific to connections involving Microsoft Access client connections. The fundamental difference is the enabling of +jetfix. Be advised - Problems can occur when users edit the Access configuration section when modification needs to be made to the general section.

[Zero Config]
SQLServer (NKHATAM) = "ServerType=SQLServer"
Sybase (NKHATAM)	 = "ServerType=Sybase"
ODBC (NKHATAM)		= "ServerType=Odbc"
JDBC 1.2 (NKHATAM)  = "ServerType=Jdbc 1.2"
JDBC 1.3 (NKHATAM)  = "ServerType=Jdbc 1.3"
JDBC 1.4 (NKHATAM)  = "ServerType=Jdbc 1.4"

Zero Config broadcasts pre-configured sets of connection options over the network. You can easily configure DSNs by choosing the name of the Zero Config section that passes the desired parameters.

[Persistent Services]
Configurator = www_sv

[www_sv]
Program	  = w3config/www_sv.exe
Directory	= w3config
CommandLine = 

[Environment WWW_SV]

The preceding section pertains to the Admin Assistant. You can place a semicolon in front of *Configurator* to disable the Admin Assistant. You can also pass +loglevel 7 to CommandLine to produce debug level Admin Assistant logs. Finally, interested parties should review ~/openlink/bin/w3config/www_sv.ini for additional Admin Assistant configuration settings.