Rexx MySQL

REXX MySQL Library

PURPOSE

The purpose of this project is to create a wrapper library to the MySQL C API for use in REXX Scripts that will provide the full power of MySQL to REXX users. The REXX MySQL API is geared to behave exactly like the MySQL C API, so users of the C API should have no problem using the REXX MySQL Library.

BACKGROUND

I wrote this program while working at TRZ Communications Services, Inc. Please realize that this software was written for specific reasons and may not handle everything you want to do with MySQL in REXX. That being said if you understand why this package was developed, then you can see if it is right for you.

This pacakage was originally written to work with IBM Object Rexx version 1.0. It was written for such an old version of REXX because it had to match a legacy system at the company where I was working. It has since been updated to run with Open Object Rexx, and should work fine with minor tweeking for any REXX interpreter.

The system which this was built for was running Windows NT. Its primary functionality was written in C but was extended by REXX. REXX scripts were executed in a multi-threaded environment. At the time, and possibly still, Rexx/SQL was not thread safe. Hence, I created this library which is thread safe.

The other major factor for writing this library is to have the full power of MySQL in REXX, not just the subset of things provided through ODBC. So think of this as a wrapper class for the C MySQL API, as the majority of the its functions are available through this library.

FUTURE

I do not plan to release or work on this library going forward as I am not using REXX these days.

This hasn't been updated in ages and is mostly here just for legacy.

STABILITY

I have tested this library extensively on Windows NT. I have not tested it very much on any other version of Windows. It should work fine on Windows XP but I have not tested it very much.

The Linux support is new in version 1.0.1, and the majority of the code is exactly the same as the Windows version. I have not tested the code very much be have no reason to believe that it will not work.

Please let me know your experiences with the library, either emailing me or posting to the Sourceforge Forum.

As you should always do when using open source software, test throughly with your own setup before using in a production environment.

PROBLEMS

To limit the possibility of problems or if you are having problems, I recommend that you download the latest version of the library directly from the official sourceforge.net project site.

http://sourceforge.net/projects/rexx-mysql

If you are still having problems post a message on the Sourceforge forum or contact me via email.

LICENSE

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

VERSION

The current version of the REXX MySQL Library is version 1.0.1.

HELP

If you are interested in helping with this project, please contact me via email.

INSTALL

LINUX INSTALLATION

The Linux installation process is pretty simple. Just type make, then make install. If you want to remove the packages type make uninstall.

        tar zxf librexxmysql-1.0.1.tar.gz
		cd librexxmysql-1.0.1/src
		make
		make install

The Makefile uses libtool to handle creating the library, installing it, and uninstalling it.

Please note that you need to have the following software installed before compiling this package.

ooRexx 3.0.0 or greater
MySQL Client 4.0 or greater

Pthreads is also needed but most Linux distro's come with it installed.

Please skip to the POST INSTALLATION step.

WINDOWS INSTALLATION

To install this package on Windows you have two choices. The easy option which is to use the precompiled binaries from the Sourceforge site. The harder option is to get the source and compile it on Windows.

PREINSTALLATION

Have Open Object Rexx 3.0 or greater installed on your system. Also have MySQL 4.0 or greater installed on your system.

BINARY INSTALLATION

This method is the easiest and is recommeded if you just want to use the library.

Download the project files from Sourceforge
Unzip them.
In the winxp directory is a binary dll, that I compiled on my Windows XP machine.
Place that anywhere in the windows PATH and you should have access to the library.
** HINT ** popular locations for PATH ( c:\windows\system32\, or the working directory )

This should work on most versions of Windows. I don't know about the older versions like Windows 95, 98, or ME. I've only checked XP.

SOURCE INSTALLATION

This method is only harder because it requires you have Visual Studios Installed. I've included a Visual Studios Solution file in the src directory. Just load that in Visual Studios. I have configured the project to look for required libraries and header files based on the standard location for files, so this *should* work out of the box. However, it may not so here's a list of where it is looking, change them if you need to.

mysql.h --> c:\mysql\include\mysql\mysql.h
libmySQL.lib --> c:\mysql\lib\opt ( Release ) or c:\mysql\lib\debug ( Debug )
rexx.h --> c:\Program Files\ooRexx\api
rexx.lib --> c:\Program Files\ooRexx\api
rexxapi.lib --> c:\Program Files\ooRexx\api

To build the library, go to 'Build' menu, select 'Build Solution'. The compiled files will be placed in either the 'Debug' or 'Release' directory depending on which version you built. Grab the 'rexx_mysql.dll' file and proceed with the instructions for the binary installation.

POST INSTALLATION

This section is not OS dependant and should be always be run. It will test that the libraries are installed properly and working.

In a terminal / command shell go the librexxmysql-X.X.X/scripts directory. Then we are going to run the test REXX scripts.

The first script is the connection_test.rex script. It will test that the library can load and that a connection can be made to a MySQL server. To run the script type 'rexx connection_test.rex'. The script will prompt your for the information it needs. Follow it's instructions.

After the first script succeeds, we need to run the complete test. This is the comprehensive_test.rex script. It will test all of the functions available through the library. Please read through the output of the script carefully as some error messages are expected ( testing mysql_error & mysql_errno ). To run the script type 'rexx comprehensive_test.rex' and follow the prompts. The script will gather all the information it needs. Please also note that the user / password you give this script must have root priviliges, as it needs to create a database, some tables, add some data to them, run some searches, delete the data, drop the tables and drop the database. If the script runs completely it should not leave any data on your server.

If both of these scripts run successfully, the your installation is successful and complete.

CHANGES

2005-12-30 ** Version 1.0.1

- Linux support added
- Tested with MySQL 5.0
- Fixed minor problem with MySQL_Stat function
- Moved code from one central file into several smaller files
- broke out my utility functions for setting / getting REXX variables
- broke out my funcs for thread local storage
- broke main file into a header and code file
- Linux Makefile uses libtool to generate shared library
- Windows now uses Visual Studio 7 Project files
- Fixed licenses on test REXX scripts
- Updated Installation instructions.
- Updated README
- Binary DLL is recompiled with this release

2005-04-20 ** Version 1.0.0

- first version no changes

Daniel Mikusa