README.txt

Zope Sybase DA

This is the Digital Creations Sybase database adapter product for the Z Object Publishing Environment.

A database adapter is used in conjunction with Zope SQL methods to provide access to relational database data in Zope.

A database adapter is not a general purpose database interface for Python. The Zope Sybase database adapter uses an extension module, sy_occ, that provides extensive, but partial, access to the Sybase Open Client C application programming interface. The sy_occ extension could be used to develop a high-level interface, but that's not what this software is.

*** IMPORTANT ***

This product is distributed as a NON-BINARY release!

This product requires compiled Python extensions that are NOT included as a binary with this release. You must build or install the required extensions using the instructions below before the product will work properly!

Installation

The Zope Sybase database adapter uses a binary Sybase extension module named sy_occ. Before using the Zope Sybase DA, you must build the extension from the sources included in the product distribution.

The source files and associated files required to build the required Sybase extension module are included in this product distribution. Follow the steps below to build the extension on UNIX platforms. Note that the included files do not support building on win32 platforms at this time. Additionally, please note that Zope Sybase DA has only been verified to work on Linux 2.X and Solaris, though it should work on most other UNIX platforms.

Ensure that you have Python 1.5 or greater installed.
Ensure that you have Sybase installed on your machine, INCLUDING THE FILES AND LIBRARIES NECESSARY TO DEVELOP Sybase APPLICATIONS. If you do not have the developer files installed, you will need to install them before proceeding. Please contact the Sybase maintainers with all questions pertaining to the use or installation of development files.
Ensure that you have extracted the SybaseDA product distribution in your top-level Zope directory. This should have created a subdirectory named lib/python/Products/SybaseDA containing the product files as well as this README file.
Build the extension.
Set the environment variable, SYBASE, to point to the Sybase installation directory on your local machine. For example, if Sybase is installed in the directory mnt/sybase1192 on your machine, then:
```
          SYBASE=/mnt/sybase1192
          export SYBASE
```
Change to the src directory of your SybaseDA product, and copy, depending on your platform, the file "Setup.linux" or the file "Setup.solaris" to the file "Setup". For example:
cp Setup.linux Setup

If you're building on a different UNIX platform, you will need to generate your own Setup file. Consult the Python and Sybase documentation for more information.

While remanining in the src directory of the SybaseDA product, use the Python platform-independent make file make file to create the make file for building the sybase extension by issuing the command:
```
          make -f Makefile.pre.in boot
```
Note that if the Python interpreter that will be used to run Zope is not run with the command python, then you must supply the command used to run Python as an option on the command. For example, if you run Python with the command python1.5.2, then use:
```
          make -f Makefile.pre.in boot PYTHON=python1.5.2
```
Finally, use the make file created above to build the extension by issueing the command:
```
          make
```
This should create the file sy_occ.so in your src directory. This file is a dynamically-linked library. Some versions of Unix (e.g. HP/UX) use a different suffix for dynamically-linked libraries.

Note that the current version of the Zope Sybase DA supports Sybase Adaptive Server v11.5 and higher. If errors occur when trying to build the extension, you may need to modify the Setup file to ensure that the correct Sybase include and lib directory options are being passed to the compiler. In particular, older versions of Sybase use lib files with different names, so you will likely need to modify the -l switches in the Setup file.

After you have built the sy_occ module successfully, start Python and type "import sy_occ", to make sure you can import the module without problems. Finally, copy the output file sy_occ.so up one directory into your SybaseDA product directory.
Set needed environment variables
To use the DCSybase DA, you need to make sure that the environment variable SYBASE is set to the directory of your Sybase installation. This environment variable must be available to the running Zope process for the Zope Sybase DA to function. If you are using only PCGI with your Zope installation, you can add a line such as::

SYBASE=/opt/Sybase

to your PCGI resource file to have the variable automatically added to the environment of the Zope process. If you are running ZServer, edit your start script to set the SYBASE environment variable before running the z2 script.

If you are using some other publishing methods, you will need to set the SYBASE variable in your own environment or in the environment of the user that starts the Zope process.

On some platforms, you may also need to add the path to the "lib" subdirectory of your Sybase installation to the environment variable LD_LIBRARY_PATH. Because the binary Sybase module used by SybaseDA is dynamically linked with the Sybase libraries, the Sybase lib directory may need to be on your LD_LIBRARY_PATH so that the system's run time linker can find the Sybase shared libraries. As with the SYBASE environment variable above, you can set the LD_LIBRARY_PATH in your PCGI resource file, in your ZServer start script, or by making sure that the user that starts the Zope process has the environment variable set.
Restart your Zope process, ensuring that the proper environment variables have been set.

Transaction Processing

To help assure data integrity Zope uses Sybase multi-statement transactions by issuing a "begin transaction" command the first time a connection is used in a Zope transaction (web request).

Some sql statements (e.g. "create table") are not allowed in Sybase multi-statement transactions. If you need to use one of these statements, you will need to create a non-transactional database connection by un-checking the "Transactional checkbox" when creating or editing a database connection.