Data Files and the Omnis Data Bridge

Document path Reference Contents > General Program Functions > Data Files and the Omnis Data Bridge

There are two methods of attaching the program to the main and keyword datafiles. The normal method is by using the operating system and selecting the datafile (or first segment of a datafile set - typically with an extension of .df1). This method uses the standard operating system file system or server network service and in multi-user conditions such a network service must support Advisory Byte Locking effectively for all clients attached to the common data file. Such network server software known to be reliable includes Windows NT and 2000 servers, Netware and some older AppleShare server software. There are however, known problems with Linux and Macintosh System X servers, particularly when clients are configured for with different network protocols (E.G. AppleTalk and SMB or TCP/IP). In such cases it is necessary for all users to attach to datafiles using a server service called the Omnis Data Bridge (ODB).

Omnis Data Bridge

The Omnis Data Bridge is a background system daemon, that runs invisibly on a server and listens for requests from Omnis clients on a given port. The ODB uses TCP/IP and therefore bypasses the standard file protocols normally employed in a multi-platform environment. Omnis clients can open and use data files by specifying the ODB serverís IP address and port instead of a file name and path to the Omnis data file.

Configuration

After installation, before you can use ODB you must configure the software.

In the ODB folder you will find a XML based configuration file named config.xml. This file contains a number of configuration items and must also contain details about the Omnis native data files to be accessed by ODB.

You can modify the file with the Property List Editor (on Mac OSX installed as part of the developer tools) or any other XML editor or text editor such as Notepad. Here we will assume that you are using a text editor.

To add details of your datafile using a text editor, create a dictionary array entry for the ODBDataBase key. There is no fixed limit to the number of datafiles you can add. You will need a minimum of two as keyword datafiles must also be included. The dictionary entry has to contain the keys ODBDataBaseDesc, ODBDataBaseName and ODBDataBasePath.

<key>ODBDataBase</key>
    <array>
        <dict>
            <key>ODBDataBaseDesc</key>
            <string>Training Demo Links (Do Not Open)</string>
            <key>ODBDataBaseName</key>
            <string>TrainingDemoLink</string>
            <key>ODBDataBasePath</key>
            <array>
                <string>C:\odbridge\TrainingDemo.lkf</string>
            </array>
        </dict>
        <dict>
            <key>ODBDataBaseDesc</key>
            <string>Training Demo Keywords (Do Not Open)</string>
            <key>ODBDataBaseName</key>
            <string>TrainingDemoKey</string>
            <key>ODBDataBasePath</key>
            <array>
                <string>C:\odbridge\TrainingDemo.kwd</string>
            </array>
        </dict>
        <dict>
            <key>ODBDataBaseDesc</key>
            <string>Training Demo File</string>
            <key>ODBDataBaseName</key>
            <string>TrainingDemo</string>
            <key>ODBDataBasePath</key>
            <array>
                <string>C:\odbridge\TrainingDemo.df1</string>
            </array>
        </dict>
    </array>

For the value of ODBDataBaseDesc you should enter a sensible description for the datafile. This description is displayed to the user if you use Prompt for data file to allow the user to select a data file from a list supplied by ODB.

The value of ODBDataBaseName must be a unique name that you will use to identify the datafile, when opening a data file using the Open data file command.

Note NOTE: In multiple datafiles and/or multiple ODB instances situations it is important that every ODBDataBaseName entry is unique.

Note NOTE: If you operate with the Multiple Company Names License option you should read notes in the Multiple Company Names Maintenance window help before committing to the names you choose for ODBDataBaseName entries.

The last item ODBDataBasePaths is an array of full paths pointing to your data file segments on disk. You must enter a full path for each data file segment if the segments are located in different folders, volumes or machines. If all the segments are located in the same folder and are named in the default Omnis naming convention, you only need to supply the full path to the first segment. The full paths are that from the server root and not as seen by client machines.

The following is an example of two datafiles and their keyword files.

<key>ODBDataBase</key>
    <array>
        <dict>
            <key>ODBDataBaseDesc</key>
            <string>Training Demo 1 Links (Do Not Open)</string>
            <key>ODBDataBaseName</key>
            <string>TrainingDemo1Link</string>
            <key>ODBDataBasePath</key>
            <array>
                <string>C:\odbridge\TrainingDemo1.lkf</string>
            </array>
        </dict>
        <dict>
            <key>ODBDataBaseDesc</key>
            <string>Training Demo 1 Keywords (Do Not Open)</string>
            <key>ODBDataBaseName</key>
            <string>TrainingDemo1Key</string>
            <key>ODBDataBasePath</key>
            <array>
                <string>C:\odbridge\TrainingDemo1.kwd</string>
            </array>
        </dict>
        <dict>
            <key>ODBDataBaseDesc</key>
            <string>Training Demo 1 File</string>
            <key>ODBDataBaseName</key>
            <string>TrainingDemo1</string>
            <key>ODBDataBasePath</key>
            <array>
                <string>C:\odbridge\TrainingDemo1.df1</string>
            </array>
        </dict>
        <dict>
            <key>ODBDataBaseDesc</key>
            <string>Training Demo Links (Do Not Open)</string>
            <key>ODBDataBaseName</key>
            <string>TrainingDemoLink</string>
            <key>ODBDataBasePath</key>
            <array>
                <string>C:\odbridge\TrainingDemo.lkf</string>
            </array>
        </dict>
        <dict>
            <key>ODBDataBaseDesc</key>
            <string>Training Demo Keywords (Do Not Open)</string>
            <key>ODBDataBaseName</key>
            <string>TrainingDemoKey</string>
            <key>ODBDataBasePath</key>
            <array>
                <string>C:\odbridge\TrainingDemo.kwd</string>
            </array>
        </dict>
        <dict>
            <key>ODBDataBaseDesc</key>
            <string>Training Demo File</string>
            <key>ODBDataBaseName</key>
            <string>TrainingDemo</string>
            <key>ODBDataBasePath</key>
            <array>
                <string>C:\odbridge\TrainingDemo.df1</string>
            </array>
        </dict>
    </array>

Port Number

In addition to adding details of your data files to the configuration file, you may also need to change the port on which ODB listens to requests from clients. The port number by default is set to 5913. You need to change it, if that port is already in use. Simply change the number value of the ODBSocketPortNumber key.

    <key>ODBSocketPortNumber</key>
    <integer>5913</integer>

Note NOTE: It is possible to have multiple instances of the Omnis Data Bridge in operation on the same machine. However, they will each have to have a unique port through which communications are maintained.

Other configuration items

In addition to data file details, the configuration file contains these additional items.

ODBErrors: This array contains the basic error text used for concatenating various error messages and error numbers. You may change the content of the text, but you must not delete an item or remove or change the order of the %s and %d placeholders.

ODBErrorsClient: An array of text for reporting errors to the client. You may change the content of the text, but you must not delete an item.

ODBErrorsServer: An array of errors reported on the server. When a server specific error occurs, these are written to the file messages.txt.

ODBSocketTimeOut: This time out value specifies the number of seconds ODB will wait for data once it has received the first part of a message from a client. If the remainder of the message is not received within this time ODB will give up and close the connection. By default this is set to 60 seconds, which should be more than enough time to account for network slowdowns.

ODBKeepStatistics: This Boolean value if set to YES (/true if editing manually) tells ODB to maintain statistics of all server access. Because this causes additional mutex calls on all requests, there may be a substantial impact on performance. This option should not be enabled unless it is required to track down some problems. See also ODBWriteStatistics.

ODBWriteStatistics: This number value, if non-zero, tells ODB to write statistics to the file info.txt every n seconds. This file can be viewed from any text editor. Because this causes additional mutex calls on all requests, there may be a substantial impact on performance. This option should not be enabled unless it is required to track down some problems. See also ODBKeepStatistics.

Using ODB

Once you have updated the configuration file with the details of your data files, you can launch ODB using the Terminal. This section explains how you launch, shutdown and connect to the Omnis Data Bridge.

On Macintosh OSX Macintosh OS X

Launching ODB

Launch the Terminal program and type:

cd /Network/Applications/OmnisDataBridge

and press return. Then type

./odb start

and press return.

If ODB has started you should see

Executing start...
...see messages.txt for success

You can check the file messages.txt in the ODB folder to check if ODB has started successfully. If an error has occurred this file will contain details of the error.

ODB is now listening for requests from your clients.

Shutting down ODB

To shut down ODB from the Terminal program, type:

cd /Network/Applications/OmnisDataBridge

and press return. Then type

./odb shutdown

and press return.

If ODB has received the shut down request, you should see

Executing shutdown...
...see messages.txt for success

If there are users connected, shutdown will fail. It is not safe to shutdown ODB while users are still connected. You should ask the users to disconnect (close their datafiles by exiting Caliach Vision) before trying again.

It is however possible to force ODB to shutdown with users still connected.

Type

./odb kill

and press return.

You may risk data file corruption if a user is writing to the datafile while shutting down.

On Linux Linux

Launching ODB

The Linux rpm is installed into:

/usr/local/rainingdata/databridge10

There is an odbset script which is run by the rpm during installation, this generates an odbI386 script.

To run the script and launch the ODB, type:

cd /usr/local/rainingdata/databridge10
./odbI386 start

Note that the filename databridge10 will change to databridge11, 12, etc with version changes.

Shutting down ODB

To stop the ODB, type:

./odbI386 shutdown

If there are users connected, shutdown will fail. It is not safe to shutdown ODB while users are still connected. You should ask the users to disconnect (close their datafiles by exiting Caliach Vision) before trying again.

It is however possible to force ODB to shutdown with users still connected.

Type

./odbI386 -kill

and press return.

You may risk data file corruption if a user is writing to the datafile while shutting down.

On Windows NT/2000/XP Windows

Launching ODB

Once you have updated the configuration file with the details of your data files, you can launch ODB running the ODBService.exe located in the ODB folder.

Open the command prompt and navigate to the ODB folder.

Type

ODBService

And press return. You should see the following text:

Omnis Data Bridge
ODBService -install to install the service
ODBService -remove to remove the service
ODBService -debug  to run as a console app for debugging
StartServiceCtrlDispatcher being called.
This may take several seconds. Please wait.

Wait until the prompt appears and type

ODBService -install

The ODB service will now be installed and you can use the service to start and stop ODB or to configure ODB to be launched during startup of the machine.

To Launch ODB: Navigate to Administrative Tools / Services. (you should see a list of services) or launch the Services Control Panel (on NT4).

Double click the Omnis Data Bridge service to open the properties window (not on NT4).

Click the Start button.

You can check the file messages.txt in the ODB folder to check if ODB has started successfully. If an error has occurred this file will contain details of the error.

ODB is now listening for requests from your clients.

Shutting down ODB

To shut down ODB, navigate to Administrative Tools / Services or launch the Services Control Panel (on NT4).

Double click the Omnis Data Bridge service to open the properties window (not on NT4).

Click the Stop button.

You can check the file messages.txt in the ODB folder to check if ODB has shut down successfully. If an error has occurred this file will contain details of the error.

Setting Up Caliach Vision

Unless you otherwise configured Caliach Vision users can only attach to a datafile using conventional operating system selection. The Omnis Data Bridge method of attachment is only possible if there is one or more optODBDatafile0 entries in the File -- Terminal Preferences (stored in the Terminal/Terminal.inf file). Because Caliach Vision must have these settings before it attaches to the datafile each user installation of Caliach Vision must have the correct Terminal Preferences entries.

There can be up to 36 optODBDatafileN entries, one for each datafile set (datafile and keyword file) that users can attach to through the ODB. The N should be replaced by 0 through 9 and A through Z in consecutive order (I.E. if there is a missing one, subsequent will be ignored).

The value of each should be in the comma-separated form of:

DatafileODBName,KeywordODBName,IPAddress:Port,DirectPath,LinkfileODBName

Parameter

Contents

Purpose

DatafileODBName

This must be the same (case-sensitive) as the ODBDataBaseName name of the datafile entered in the config.xml server ODB configuration file. E.G:

TrainingDemo

Note NOTE: When you Apply Terminal Settings a check is made that all DatafileODBName entries are unique, and if not a warning is given.

This name links the user to a datafile being managed by the Omnis Data Bridge on the server.

KeywordODBName

This must be the same (case-sensitive) as the ODBDataBaseName name of the associated keyword file which also must be entered in the config.xml server ODB configuration file. E.G:

TrainingDemoKey

This name allows the program to associate the datafile with it's keyword file which must also be managed by the Omnis Data Bridge on the server.

IPAddress:Port

This must be the IP Address of the server followed by a colon and the port number as in the ODBSocketPortNumber entered in the config.xml server ODB configuration file - 5913 by default. E.G:

128.112.45.25:5913

Essential for the workstation to communicate with the ODB.

DirectPath

This is the full path from the workstation to the directory on the server that may contain the server-based directory tree. This directory need not contain the datafiles that the ODB is managing but it should contain the other items normally bundled in the same directory as the datafiles. For example, the ProgCode.usa and ProgCode.upt files. The path should terminate in a directory delimiter character. E.G.:

Windows: X:\OurData\Others\
Mac: Server:OurData:Others:
Linux: mnt/Server/OurData/Others/

Note NOTE: When you Apply Terminal Settings a check is made that all DirectPath entries are seen as directories, and if not a warning is given.

Other than the two datafiles, it is through this path that the program locates any server-based files it needs.

LinkfileODBName

This must be the same (case-sensitive) as the ODBDataBaseName name of the associated link file which also must be entered in the config.xml server ODB configuration file. E.G:

TrainingDemoLink

This name allows the program to associate the datafile with it's link file which must also be managed by the Omnis Data Bridge on the server.

Operation of Caliach Vision when using the ODB

Once you have at least one entry in the Terminal Preferences for optODBDatafile0, the system will assume that you will be connecting to the datafile via the Omnis Data Bridge. When the user operates File -- Change Data File, or otherwise is expected to select a datafile, they will be offered the option of using a connection to the Omnis Data Bridge with the following question:

Datafile method question

If you answer No, the normal operating system datafile selection dialog will be presented. If you answer Yes, you will then be prompted to select a datafile from the ODB:

ODB datafile selection

If you have multiple entries in your Terminal Preference that contain different IP Address and Port entries, you must first select the IP Address and Port of the ODB instance you require:

IP Address and Port Selection

After you have attached to a datafile through an ODB service, the datafile path that shows on the Navigator and About Caliach Vision windows will be in the form of:

odb://128.112.45.25:5913:TrainingDemo

See also: -

Compiled in Program Version 3.10. Help data last modified 17 FEB 2012 06:54. No class.

Document path Reference Contents > General Program Functions > Data Files and the Omnis Data Bridge