%META:TOPICPARENT{name="TroubleshootingUDAUsingEvidence"}% ===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 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.