Omnis Technical Note TNSQ0009

Connecting to Sybase from Mac OSX

For Omnis Studio 3.x/4.0
By Gary Ashford

When I start Studio for Mac OSX, the Sybase DAM isn't available. Why is this?

The Sybase DAM, in common with other DAMs for Mac OSX, depends on its corresponding bundle file before it can be used. In turn, the Sybase bundle depends on several Sybase client libraries being present on your system before it can be loaded. The most common cause of the Sybase DAM failing to load is the failure of the dynamic loader to locate one or more of these libraries.

When this is the case, the Mac OSX Console log displays an error message containing the name of the first library which could not be located. This message will be of the form:

2005-09-21 12:53:23.399 Omnis[948] CFLog (21): Error loading Applications/Omnis Studio 4.0.1/Omnis.app/Contents/MacOS/xsybase.bundle/Contents/MacOS/xsybase: error code 4, error number 0
(Library not loaded: libsybcomn.dylib
Referenced from: /Applications/Omnis Studio 4.0.1/Omnis.app/

The Omnis trace log will also display an error message stating that the xsybase bundle could not be loaded.

So, what is a bundle?

Bundle files are a convenient way of allowing CFM Carbon Applications- such as Studio to access Mach-O/ unix style libraries provided by clientware vendors. The bundles used by Studio are stored inside the main Omnis.app package: Omnis.app:Contents:MacOS.
The bundle required by the Sybase DAM is named xsybase.bundle.

Which libraries are needed before the bundle will load?

The Sybase bundle is dependent on the following six Sybase client libraries:
libsybtcl.dylib, libsybdb.dylib, libsybintl.dylib, libsybct.dylib, libsybcs.dylib & libsybcomn.dylib

In versions of Sybase Open Client prior to 12.5.1, these libraries are named:
libtcl.dylib, libsybdb.dylib, libintl.dylib, libct.dylib, libcs.dylib & libcomn.dylib respectively.
They were renamed in 12.5.1 because of a potential library name conflict with Mac system libraries, (most notably libtcl.dylib- which is required for tcl scripting).
If these libraries are present on your system you will need to create symbolic links to these libraries using the library names expected by the xsybase.bundle. See below.

How do I get the Dynamic Loader to locate these libraries?

There are two ways. The first involves the creation of symbolic links from a location known to be on the standard library search path. The second involves getting the dynamic loader to look in additional locations.

1. Creating Symbolic Links

To do this, you need to use the Terminal utility and you will need to have root privileges:

> su (prompts you for the root password)
> cd /usr/lib
> ln -s /Applications/Sybase/System/OCS-12_5/lib/libsybtcl.dylib libsybtcl.dylib
> ln -s /Applications/Sybase/System/OCS-12_5/lib/libsybdb.dylib libsybdb.dylib
> ln -s /Applications/Sybase/System/OCS-12_5/lib/libsybintl.dylib libsybintl.dylib
> ln -s /Applications/Sybase/System/OCS-12_5/lib/libsybct.dylib libsybct.dylib
> ln -s /Applications/Sybase/System/OCS-12_5/lib/libsybcs.dylib libsybcs.dylib
> ln -s /Applications/Sybase/System/OCS-12_5/lib/libsybcomn.dylib libsybcomn.dylib

The above assumes Open Client 12.5.1 (or higher) is installed on your system in the default location as shown. If your client libraries are located elsewhere you should modify the paths to the symbolic links accordingly.
If you are using an older version of Sybase Open Client you will also need to modify the library names for parameter 1 (on the left) to reflect the names of libraries actually present on your system.
Parameter 2 (on the right) reflects the names of the libraries required by the bundle file. The library names shown are correct for Omnis Studio 4. Bundles supplied with Omnis Studio 3 were built against an earlier version of Open Client and in this case you should also change parameter 2 to reflect the old library names (see above).

If you are unsure which libraries your xsybase.bundle needs and you have Mac Developer Tools installed, you can use the otool command to list the dynamic dependencies for the bundle, e.g.

> cd omnis.app/Contents/MacOS/xsybase.bundle/Contents/MacOs
> otool -L xsybase

Following successful creation of these symbolic links, the dynamic loader should be able to resolve the dynamic dependencies of xsybase.bundle the next time Studio starts up. You should see a message in the Omnis trace log stating that xsybase.bundle was loaded successfully.

2. Setting DYLD_LIBRARY_PATH

Setting the DYLD_LIBRARY_PATH environment variable directs the dynamic loader to look in additional locations when attempting to resolve dynamic dependencies. Unlike Unix operating systems where environment variables can be set on the command line before starting Omnis, the Mac relies on a user startup script/configuration file named environment.plist; an XML file which contains a list of environment variables to be set when the user logs on to Mac OS X.

The DAMs work around the need for this file as far as possible by providing their own DAMxxx.INI files found in the Omnis XCOMP:INI folder. Once the bundle has loaded, the DAM can issue shell commands to set environment variables directly. The snag is that you obviously can't use the DAMSYBSE.INI file to set the DYLD_LIBRARY_PATH variable because the bundle will not be loaded at the point were this variable needs to be set.

Editing (or creating) an environment.plist file for the current user is the best way to ensure that DYLD_LIBRARY_PATH gets set each time your user logs on. environment.plist resides in the .MacOSX folder (a hidden folder) of your user's home folder. If this does not exist, you can create it using a terminal window as follows:

> mkdir .MacOSX

So that you can find this folder later using the Mac Finder, you could also create a symbolic link to this folder using a non-hidden filename, e.g.

> ln -s .MacOSX MacOSX

Next, you should create a file named environment.plist inside this folder. You can edit this file using the Property List Editor utility if you have it or failing that- with a standard text editor.
There is also a free utility called PlistEdit Pro available for download from the Apple website.
Using Property List Editor or Plist Pro, you should insert a Key String pair as follows:

DYLD_LIBRARY_PATH = /Applications/Sybase/System/OCS-12_5/lib

If using a text editor, insert the XML directly as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>DYLD_LIBRARY_PATH</key>
<string>/Applications/Sybase/System/OCS-12_5/lib</string>
</dict>
</plist>

You will need to log out and in again for this change to take effect, but when Omnis starts-up, the dynamic loader should look in the folder specified above for the client libraries. You should then see a message in the Omnis trace log stating that the xsybase.bundle was loaded successfully.

Note for Omnis Studio 3.x users:
As mentioned previously, the xsybase.bundle distributed with versions of Studio 3 was built against a version of Sybase Open Client prior to 12.5.1 and hence has dependencies on libraries which use the older-style library names. In this case you will still need to create symbolic links either in the /usr/lib folder or in the /Applications/Sybase/System/OCS-12_5/lib folder from the names expected by the bundle to those present on your system.

A note about DAMSYBSE.INI
The Mac OSX DAMs have associated .ini files which reside in the Omnis XCOMP:INI folder. (In Studio 3.x, these were located in the XCOMP folder, but were later moved as they caused trace log errors on startup).
Once the bundle (and hence the DAM) has loaded, the DAM reads the contents of the .ini file and sets environment variables accordingly. The default contents of DAMSYBSE.INI are :

SYBASE=/usr/sybase           (or /Applications/Sybase/System)
SYBASE_OCS=OCS-12_5

If you are using the environment.plist file mentioned above, you may decide to centralise all of your environment variable assignments here, in which case all of your .ini files can be empty. Alternatively you could place all environment variables which would normally be placed in seperate .ini files into the first ini file that is used (bundles are loaded in alphabetical order).

The Sybase interfaces file
Sybase Open Client for Mac OSX uses the interfaces file to store connection information.
If no interfaces file is present following installation of Open Client, you can create one in the SYBASE folder, e.g. in /Applications/Sybase/System. Each datasource entry is a DSN name followed by a master and a query assignment, e.g.

dsnName
   master tcp ether xxx.xxx.xxx.xxx port
   query tcp ether xxx.xxx.xxx.xxx port

where xxx.xxx.xxx.xxx represents the IP address of the Sybase server and port represents the port number that the server is listening on (default value is usually 5000).
It is also important to note that the dsnName is case-sensitive; the hostname parameter specified from Omnis must match with the name chosen here.