DRAFT

OdxNet Omnidex Network Services

ODXNET (Omnidex Network Server) is the client/server listener program that runs as a socket listening process on a UNIX or Windows server, trafficking client requests. ODXNET uses pooled processes to increase connection speed and preconnected processes can also be configured to further improve connection speed.

By default, ODXNET creates pooled processes for each application type (ODBC, JDBC, OmniAccess) automatically when the listener is started. Each client connection attempts to use a pooled process unless explicitly directed through an option to have a new process created.

Each application type comes with a generic application pool that is used by ODXNET. Environment specific application pools can be setup in the ODXNET configuration file for the listener.

OdxNet Setup

Setting up ODXNET varies depending on the operating system and intended use.

Modify the ODXNET configuration file

First, create or modify the ODXNET configuration file. This file contains settings that ODXNET will use at run-time.

The configuration file should be used in a production environment but can be optionally omitted for a test environment. Most of the required settings have defaults that will be used if the configuration file is omitted. However, some scenarios, such as setting up a Windows NT Service or creating environment specific application pools, require settings that can only be defined in the configuration file.

Set the required environment variables.

Certain operating system Environment variables should be set up that OdxNet may need for proper access to Omnidex libraries.

Start the listener process.

The simplist way to start OdxNet is to simply enter the name at the operating system command line.

os> odxnet

This will start ODXNET using default configuration values and listening on PORT 7555.

Set up the client.

Omnidex client must be installed on each client machine intending to connect to an Omnidex environment.

Test the connection.

It is always a good idea to test the connection before trying to use a client application with the data source. The Windows client tool DS EDIT is ideal for this. Run the client application.

OdxNet Command Line Options

C:\dev\odx> odxnet -?


Omnidex Network Server                              Tue Dec 01 08:57:46 2009
(C) Dynamic Information Systems Corporation                   Version 5.0.00

ODXNet - Omnidex Network Server

   odxnet runs as a socket listening process to enable client/server
   connections to Omnidex.  Valid directives are:

   odxnet [<cnfgfile>]
            [-port=n]
            [-maxsons=n]
            [-bufsize=n]
            [-nopools]
            [-usegenpools]
            [-nohostaddresslookup]
            [-NoPrintfs]
            [-idletimeout=numminutes]
            [-nontservice]
            [-debug=ALL | PROCESS | APPS | CONNECTIONS]
            [-tfile=<traceFilename>]
            [-topts=<traceOptions>]
   odxnet [-shutdown]
            [-delay=n]
            [<cnfgfile>]
            [-port=n]
   odxnet [<cnfgfile>]
            [-ntservice=<unique service name>]
            -ntsrvaction=<INSTALL | INSTALL_AUTO | DELETE |
                           START | STOP | PAUSE | CONTINUE>
   odxnet [-admin=[GENERAL | SONLIST | ALL]
            [<cnfgfile>]
            [-port=n]
   odxnet -help | -?
   odxnet -version
Start the Listener

The following directives are provided to start ODXNET from the command line.

odxnet [<cnfgfile>]
[-port=n]
[-maxsons=n]
[-bufsize=n]
[-nopools]
[-nohostaddresslookup]
[-NoPrintfs]
[-idletimeout=numminutes]
[-sleep]**Unix only**
[-nodaemon | -daemon]**Unix only** 
[-nontservice]**Windows only**
[-debug=ALL | PROCESS | APPS | CONNECTIONS]
[-dfile=<filename>]
cnfgfile

Configuration file specification. See Configuration File for details on the settings contained in this file.

os> odxnet /usr/omnidex/demo/odxnet_7444.cfg

A configuration file should always be used if possible as it contains settings that cannot be defined from the command line, like the NSADMIN password. In this case, an ODXNET listener started without a configuration file, cannot be accessed from NSADMIN.

Some of the options defined in the configuration file can be over-ridden by passing the same option with a different value. For example, assume preconnected processes are defined in the configuration file, odxnet_7444.cfg. The following will cause the listener to be started without starting any preconnected processes.

os> odxnet /usr/omnidex/demo/odxnet_7444.cfg -nopools
-port=n

This option sets or specifies the listener port-id number for the ODXNET process. This option is required if a configuration file is not being used. This is the number is specified in the client data source file.

os> odxnet -port=1232
-maxsons=n

Maximum number of son processes to allow for this listener.

odxnet -port=1232 -maxsons=120

-bufsize=n

Buffer size to use for send/receive and compression exercises.

os> odxnet -port=1232 -bufsize=512
-nopools

Starts ODXNET without starting any default or configured pooled processes.

os> odxnet -port=1232 -nopools
-nohostaddresslookup

Skip dsn lookup for incoming client to translate its IP address to a network name.

os> odxnet -port=1232 -nohostaddresslookup
-NoPrintfs

Skip displaying information to the console when ODXNET is running.

os> odxnet -port=1232 -NoPrintfs
-idletimeout=numminutes

The server side connection is closed after client connection has been idle numminutes.

os> odxnet -port=1232 -idletimeout=20
-sleep

This is a Unix only directive.

os> odxnet -port=1232 -sleep
-nodaemon | -daemon

This is a Unix only directive.

-nodaemon causes odxnet to run interactively in foreground of the Unix session in which it was started. -daemon is the default.

os> odxnet -port=1232 -nodaemon
-nontservice

This is a Windows only option.

This option allows a listener to be run interactively when odxnet has already been installed as a service. See also: Windows Service.

os> odxnet -port=1232 -nontservice
Stop the Listener

The following directives have been provided to shutdown a running ODXNET process. These directives do not apply to an ODXNET process that is running as a Windows Service.

odxnet [-shutdown]
    [-delay=n]
    [<cnfgfile>]
    [-port=n]

The listener port id must be passed with the -shutdown directive. This can be passed with the -port=n option, where n is the listener port id, or in the configuration file.

-shutdown

Use this option to halt a running ODXNET process.

os> odxnet -port=1232 -shutdown

If the process is running interactively, you can terminate the listener from a separate server session with the -shutdown command. Or, within the same server session, CTRL + c will also terminate the listener process.

-delay=n

Stops accepting new client requests and shuts down the listener after n seconds, to allow active queries to complete.

os> odxnet -port=1232 -shutdown -delay=90
-port=n

The listener port id number to shutdown. If omitted, the configuration filespec containing the listener port id, must be passed.

os> odxnet -port=1232 -shutdown
cnfgfile

The configuration file containing the listener port id number that will be shut down. If omitted, the -port=n option must be passed.

os> odxnet /usr/omnidex/demo/odxnet_7444.cfg -shutdown
Display Child Process Information

The following directive has been provided to display information about child processes connected to the current listener.

odxnet [-admin=[GENERAL | SONLIST | ALL]]
    [<cnfgfile>]
    [-port=n]
-admin=[GENERAL | SONLIST | ALL]

This option displays information about all the child processes currently connected to the specified, running listener. This option is used after the listener has been started.

GENERAL - displays statistics concerning the number of clients connected.

SONLIST - displays a list of the child processes running through the listener.

ALL - displays both the GENERAL and SONLIST information.

os> odxnet -port=1232 -admin=ALL

cnfgfile The ODXNET configuration file containing the listener port ID. If omitted, the -port=n option must be passed, where n is the listener port ID.

os> odxnet /usr/omnidex/demo/odxnet_7444.cfg -admin=ALL
-port=n

The listener port ID. If omitted, the ODXNET configuration file containing the listener port ID must be passed.

odxnet -port=7444 -admin=GENERAL

-help | -?

This option displays helpful information about running odxnet.

os> odxnet -help
os> odxnet -?

Getting Version Information

-version

This option displays the following version information:

Network Server OmniAccess IndexAccess Software Build Software Package ID Compilation Timestamp odxnet -version

Pooled Processes

Pooled processes are processes established when the ODXNET listener is started, that run on the server waiting for client requests. Libraries are loaded and memory is allocated in advance, eliminating much of the overhead of connecting to an environment. ODXNET automatically creates 5 pooled processes for each client application type, ODBC, JDBC and CLOA, when the listener is started. These processes are reused and can automatically grow and shrink in number as needed.

Pooled processes are not the same as preconnected processes, which establish connections to a specific environment catalog. Pooled processes are generic processes can connect to any Omnidex environment.

Pooled processes can be defined explicitly for an application type in the ODXNET configuration file. At this time, the only configuration available for pooled processes is whether or not to use them for an application type. See Configuration below for details.

If an ODXNET configuration file is not used, pooled processes for the different application types will be created when the ODXNET listener is started, using default settings, unless the -nopools option is used. In which case, no processes will be started and no connections will be opened to any Omnidex environments until a client request is received. However, client connection times can be greatly reduced by using a waiting process, therefore, we do not recommend using the -nopools option unless specific application needs require it.

Pooled Process Configuration

Configuring pooled processes is done in the ODXNET configuration file.

At the beginning of the configuration file is a section labeled “[General]”. In this section is a directive called “SkipProcessPooling” which, by default, is set to zero ( 0 ), meaning OFF. If you want to prevent any pooled processes from being established, change this setting to 1.

A little farther down the configuration file is a section labeled “[Applications]”. Applications refers to the three different application types available for Omnidex development, that will go through Omnidex Network Services. The types are ODBC, JDBC and CLOA, specified as ODXODBC, ODXJDBC and OMNIACCESS respectively in the ODXNET configuration file. You can turn off pooled processes for one of these application types by commenting out the application tag in this section.

For example, if your application is strictly ODBC, meaning no JDBC or CLOA applications will run through this ODXNET listener, you can comment out both the JDBC and CLOA tags. This will allow pooled process to be established for ODBC application but not JDBC and CLOA applications.

[Applications]

ODXODBC=Omnidex ODBC Driver
;ODXJDBC=Omnidex JDBC Driver
;OMNIACCESS=Omnidex Access API

DSEDIT required both ODBC and CLOA pooled processes in order to test a connection. If you've turned off pooled processes for either of these application types, DSEDIT will not be able to test a connection.

Each application type, from the Applications section, has its own sub-section with configuration information specific to that application type. These sections are labeled “[ODXODBC]”, “[ODXJDBC]” and “[OMNIACCESS]”.

[ODXODBC]

LibraryName=odxdbcnet
; Library name where the connect and transmit 
; interface routines are kept.

TransmitRoutineName=odbc_transmit
; Routine name

This section defined the library and transmit routines used by each application type.

Preconnected Processes

Preconnected processes are multiple, pre-defined connections to a specific Omnidex environment, that are established when the ODXNET listener is first started. These connections run on the server, waiting for client requests, similar to pooled processes except that they are connected to a specific environment. This is particularly useful in multi-user and web environments where many connections to the same environment are required.

As connections are used, more connections are automatically created behind the scenes, so a free connection is always ready. When a connection is freed by the client, it is returned to the “pool” where it will wait for a new client, or closed if the pool size is unnecessarily large.

All of these connections use connect options defined in the ODXNET configuration file, which overrides any settings specified in the client's datasource.

Each time a client request comes through the listener for a datasource that is configured with preconnected processes, one of the pre-established connections will be used. The number of connections can grow dynamically as demand increases, up to a limit that is defined in the configuration file.

Any connect options passed from the client will be ignored when connecting to a preconnected process.

Preconnected Process Configuration

Configuring preconnected processes is done in the ODXNET configuration file.

Each application type, from the Applications section in the ODXNET configuration file, has an “[apptype Environments]” section, (where apptype is ODXODBC, ODXJDBC or OMNIACCESS), that allows you to define preconnected processes. In this section, you can name an environment that will be automatically connected to when the ODXNET listener is started.

[ODXODBC Environments]

; Fill this section with a list of various environments that you wish to track ;SAMPLE=My sample database

In this example, SAMPLE is the environment name, although it is commented out. This environment name must match the data source name defined in the client data source. When ODXNET receives a client request, it attempts to match up the data source name with a preconnected process environment name. If a match is found, the client receives one of the preconnected processes. If no match is found, a new connection is created using a pooled process.

The text “My sample database” is a description for informational purposes only. It is not used by ODXNET in any way. ODXODBC means that preconnected processes will be started for use by ODBC applications. JDBC and OmniAccess applications cannot use the ODBC preconnected processes, as they require different libraries that are preloaded with the pooled processes.

Each application type can contain multiple environment names. The environment name is a label that links to two sections, one that defines the preconnected processes pool size, growth rate, etc…, and one that defines the connection information like environment file spec, user name and password.

Each environment name defined in the Environments section will have its own sub-section, where the preconnected process behavior is defined. This is where you tell ODXNET how many connections to establish at start up, the maximum number of connections to have open at any one time, growth rate and more.

[ODXODBC SAMPLE]

StartupInfo=$SECTION
; Specifies environment to preconnect to

UsePooleProcesses=1
; Flag to determine if Pooled Processes are used
; 0 Don't start or use pooled processes for this application
; 1 Start and use pooled processes for this application

InitialProcessCount=10
; Number of processes to startup

ProcessLimit=60
; Maximum number of pooled processes allowed for this application

GrowthThreshold%=80
; Trigger to indicate more processes should be started
; Happens when this percentage of the processes that have started
; are owned by clients

Growth%=20
;Amount of processes to grow by when GrowthThreshold% is reached.
;Number of processes added is Growth Percent of number of processes already
; started up to the ProcessLimit

ReUseProcesses=1
; Flag to determine if application processes are reused
; 0 Don't reuse processes, instead start a new process
; 1 Reuse processes

 

Each environment name defined in the Environments section will also have a start up info sub-section. This section contains the environment file spec, connect options, user name and password if applicable, and an optional SQL statement.

[ODXODBC SAMPLE StartupInfo]

; This section contains information used by ODXODBC when starting on the server

EnvName=C:\omnidex\oa\oracle\orders.env
; specifies env file to preconnect to. Leaving blank will skip preconnection
; Ignored when *not* a pooled process, i.e. when its a new process

;Options=

;Username=
; username to pass to oaconnect
; Ignored when *not* a pooled process, i.e. when its a new process

;Password=
; password to give oaconnect
; Ignored when *not* a pooled process, i.e. when its a new process

;SQL="select * from customers where customer_no=1 with opt=none"
; sql statement must be enclosed in quotes.
 
Back to top
programs/odxnet/home.txt · Last modified: 2016/06/28 22:38 (external edit)