17.1.Rulebook Settings

17.1.1.[Request Broker]

Table17.1.

Parameter Default Comment
BinaryDirectory Absolute path to the bin directory which has the Broker program. Example: /home/openlink/openlink/bin
CommandLine The command line parameters to use as a default. These parameters are also passed on to each program referenced in [Persistent Services]
Protocols tcp Name of protocol to use tcp/spx/DECnet
MaxAgents 0 if >0, maximum number of processes spawned by broker
MaxConnections 0 if >0, maximum number of connections from clients
HostNameResolver Yes Resolve IP addresses to hostnames Yes/No. Use Yes to give a more readable name in the logs. Set to No to avoid possible delays when frequently looking up unknown (new) IP numbers through a distant uncached DNS table. This parameter will have a direct affect on the type of match that is to be used for the StartupBy, ShutdownBy and ShutdownFrom parameters under the Security section.
LingerTimeout 0 if >0, time in seconds that a disconnected agent will linger ready for re-use before giving up, and terminating.

17.1.2.[Protocol TCP]

Table17.2.

Parameter Default Comment
PingWatchdog No Send check-alive packets Yes/No
PingInterval 600 Number of seconds between each Ping
IPAddress 127.0.0.1 Overrules found interface address
PortLow 5000 Optional lower limit of port number to be used in allocation by the Broker for communication with an Agent.
PortHigh 60000 Optional upper limit of port range usage by Broker.
Listen 5000 Port that the client should contact the broker on.

17.1.3.[Protocol SPX]

This section is only relevant, and required when using the SPX protocol.

Table17.3.

Parameter Default Comment
SAPBroadcast Yes Broadcast SAP registration packets
SAPInterval 100 Number of seconds between each SAP broadcast
SAPServiceType 0x321F Type of the SAP service
SAPServiceName OPENLINK name of the SAP service
HostFile HOSTS.IPX For IPX/SPX name to address translation

17.1.4.[Protocol DECnet]

This section is only relevant, and required when using the DECnet protocol.

Table17.4.

Parameter Default Comment
ObjectName OPLRQB Name of the DECnet server object

17.1.5.[Communications]

Table17.5.

Parameter Default Comment
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 120 Maximum time allowed for OpenLink Service Agents (JDBC_SV, ODBC_MV, PROXY_SV) to instigate a session with database agents (ora7_sv, inf7_mv etc.)
RetryTimeout 5 Initial retry interval in seconds. Doubles on failure to a maximum of 30 seconds

17.1.6.[ZeroConf]

Table17.6.

Parameter Default Comment
<ServiceName> <Connection String Attributes> User defined ZeroConfig entry

17.1.7.[Security]

Table17.7.

Parameter Default Comment
StartupBy .* Users who can startup oplrqb
ShutdownBy .* Users who can shutdown oplrqb
ShutdownFrom localhost.*,127\.0\.0\.1 Hostnames that can shutdown
ValidUidRange 0, 50000 Valid range for OpSysLogin
TraceRulebook Write merged rulebook (debug) Example: /tmp/debug.book
IncludeRulebook Name of file in current directory holding additional rulebook sections. (Example: generic.book). There may be more than one occurance of IncludeRulebook so multiple books can be included. The sections specified in the included files cannot overrule the sections contained in the main broker rulebook. Only unique sections are included.

The StartupBy, ShutdownBy and ShutdownFrom parameters use full Regular Expressions. Separate multiple expressions with a comma.

Table17.8.Regular Expression Examples

Expression Interpretation Comment
.* Any character, any number of times Any user or location.
localhost.* localhost followed by zero or more characters Will match: localhost, localhost2, localhost.company.com
127\.0\.0\.1 exact IP 127.0.0.1 Current machine when HostNameResolver=No
.*\.company\.com Any text before .company.com Used to match any sub domain of company.com. For example: sales.company.com, john.company.com

17.1.8.[generic_agentname]

Each Database Agent will have a section that is typically called "generic_" followed by a database label. For example: [generic_virt], [generic_odbc], [generic_db2].

Table17.9.

Parameter Default Comment
Program name of the executable to run
Environment specify Environment section to use
CommandLine commandline options (optional)
ServerOptions force dbms client specific options (optional)
Directory where to chdir before starting the server
Database force name of the database (optional)
ConnectOptions force dbms specific connect options (optional)
UserID force userid (optional)
Password force password (optional)
ReadOnly No force read-only mode (optional)
OpsysLogin No when set to Yes, the Request Broker will do an operating system login before spawning. This implies ReUse = ifsame user. (optional)
NeedsCLI (VMS only) Use CLI to spawn the agent
ReUse never Defines how an agent will be re-used. See below for details of the ReUse Parameter.

For the CommandLine parameter, you can specify a selection of the following options:

+noautocommit

This means that all connections routed (by the mapping rules) through this agent section will have autocommit behaviour turned off. This is useful if your client-side application relies on manual commits of its transactions; you can define a mapping rule to match that application and add +noautocommit while other applications use a different agent section.

+maxrows

This defines the maximum number of rows to fetch from any query.

+initsql

Specifies a file with a set of SQL statements to execute immediately each connection is established. For example, this might be useful to set transaction isolation levels, if your application assumes them to be set a specific way already.

+jetfix

This enables various workarounds for operation with the Microsoft Jet Engine, e.g. through Access or MS Query. Particularly, the mapping of datatypes may be changed for greater accuracy using these applications.

+norowsetlimit

This disables any rowset-size limit; it is useful in cursor operations on large tables.

Agent ReUse parameter

Table17.10.

ReUse Value When is agent re-used
never never reuse this instance (default)
always always try to reuse this instance
upto <n> allow at most n connection to the same instance
ifreadonly allow only the read-only requests
ifsame database allow requests that alias to the same db.
ifsame process same calling process id (pid)
ifsame options same connect options specified
ifsame application if originated from same appl. alias
ifsame user if request for same username
ifsame machine group connections from same machine
ifsame opsys group connections with compatible operating sys.

17.1.9.[Domain Aliases]

This section is used to change a domain name specified in the connect string of a DNS with an internal alias. This alias is used in the first colon delimited field of a mapping rule.

This example will map two different Progess domains to one agent. An alternative is shown for mapping three different Oracle types to the one Oracle agent.

[Domain Aliases]
^Progress 90A$|^Progress 90B$ = pro90b
Oracle 9i                     = ora90
^Oracle 9.0$                  = ora90
^Oracle 9.0.x$                = ora90

17.1.10.[Database Aliases]

This section will replace a database name specified in the connect string of a DNS with an internal alias. This alias is used in the second colon delimited field of a mapping rule.

This example looks for a substring 'demo' and will replace with an alias of 'demo'. Thus anydemo, demo, demo123 are all matched, and converted to demo.

[Database Aliases]
demo = demo

17.1.11.[User Aliases]

This section will replace a user name specified in the connect string of a DNS with an internal alias. This alias is used in the third colon delimited field of a mapping rule.

The example below shows how certain users or an empty user are handled. In this case they are rejected.

[User Aliases]
scott|system = insecure
^$           = blank
[Mapping Rules]
*:*:blank:*:*:*:rw     = reject You should specify a username
*:*:insecure:*:*:*:rw  = reject The user is not allowed

17.1.12.[Opsys Aliases]

This section will replace an operating system indentifier with an internal alias. This alias is used in the fourth colon delimited field of a mapping rule.

This example will map anything containing the substring 'java' to an alias of 'java'. Two variations of windows are given an alias of 'msdos'. Everything else will be matched to .* so it is mapped to the alias 'other'.

[Opsys Aliases]
java        = java
win32|msdos = msdos
.*          = other

17.1.13.[Machine Aliases]

This section will replace a machine name with an internal alias. This alias is used in the fifth colon delimited field of a mapping rule.

This example will map two different machine names to one of 'adminpc'. Also anything containing the word 'sales' such as mysales, sales, sales2 is then mapped to 'sales' alias.

[Machine Aliases]
fredspc|johnspc    = adminpc
sales              = sales

17.1.14.[Application Aliases]

This section will replace the application name with an internal alias. This alias is used in the sixth colon delimited field of a mapping rule.

This example would match MSACCESS (a program requiring the Jet option), and map it to an alias of jet. The second alias mapping would match various Office applications and convert them to a single alias.

[Application Aliases]
MSACCESS           = jet
MSQRY.*|EXCEL|WORD = msoffice

17.1.15.[Mapping Rules]

This section is used to determine which agent shall handle the incoming request. The mapping rules are checked once all the alias mappings have been performed. Each mapping rule is tried from top to bottom until a match with the current parameters has been found. There is no regular expression or glob handling in the mapping rules. The 7 colon delimited mapping parameters must each match up exactly. There is a special mapping rule of '*' that denotes a dont care parameter. Do not confuse this special '*' with the regular expression '*', or glob '*'.It is not possible to use the '*' with any other text such as 'demo*'.

On the right side of the '=' is either an accept, or reject statement. The accept statment has the word 'accept' followed by the section name that identifies the agent. A reject statement has the word 'reject' followed by a text string that is the error message reported to the client.

This is an example mapping section.

[Mapping Rules]
;*:*:blank:*:*:*:rw     = reject You should specify a username and password
*:*:Admin:msdos:*:jet:* = reject Admin user account is not registered
sql2000:*:*:*:*:*:*     = accept generic_sql2000
ora81:*:*:*:*:jet:*     = reject The Oracle 8 Database Agent is not configured for jet
*:*:*:java:*:*:*        = accept jodbc_client

Here is a snippet of the debug output showing how a request is shown to be matched.

request: domain=Oracle 8.1 database=db serveropts=
connectopts= user=scott opsys=win32 readonly=0
application=ODBCAD32 processid=520
solve mapping: ora8sv:db:scott:win32:MASTERSRVR:ODBCAD32:rw
using mapping: ora8sv:*:*:*:*:*:*