DataReel 4.2 Beta Readme File


 Contents
Overview
Features
License
Supported Platforms
Supported Compilers
Package Map
Major Library Changes in Version 4.2
Include and Source File Changes in Version 4.2
Outstanding Issues in Version 4.2
Wish List for Version 4.2
Example Programs
Documentation
Unzipping
Building BCC Static WIN32 Library
Building MSVC/C++.NET DLL
Building MSVC Static Library
Building UNIX Share/Static Libraries


 Overview

What is DataReel?
DataReel is a free cross-platform database and communications toolkit used to rapidly develop and deploy multi-threaded database and communications applications. The DataReel toolkit is composed of a modular C++ library designed to build cross-platform infrastructures for end-user applications, embedded systems, and reusable libraries. It was produced by independent work and contract work released to the public through non-exclusive license agreements. The initial work began independently in 1997 and was augmented from 1999 to 2002 by code produced under contract to support various applications.

Why Use DataReel?
DataReel is simple. DataReel simplifies complex time consuming database, socket, and multi-threaded programming tasks. DataReel is flexible. Using DataReel gives your developers the flexibility to develop core application components independently of complex user interfaces. DataReel is portable. DataReel not only offers portability but also interoperability between multiple platforms. DataReel is modular. DataReel is a modular approach to network and database programming making code adaptation and cross-platform testing easy.

Who Can Use DataReel?
The DataReel toolkit is available to commercial, individual, and academic developers.

Who Can Contribute?
The DataReel project accepts bug-fixes, enhancements, and additions from all developers.


 Features

Database
Sockets
Threads
General
 WIN32/UNIX Interoperability
 32-Bit DB Engine
 64-Bit DB Engine
 Large file support
 CRC Checking
 Portable File Locking
 Portable Record Locking
 B-tree Indexing
 Persistent Objects
 Supports OODM Design
 Supports RDBMS Design
 Supports Multi-threading
 Supports Client/Server Apps
 Built-in Network Database
 Real-time TCP Streaming
 Real-time UDP Streaming
 RS232 streaming
 WIN32/UNIX Interoperability
 Winsock/BSD Wrappers
 Object-Oriented Design
 Stream Sockets
 Datagram Sockets
 RS232 Support
 Supports Multi-threading
 Embedded Ping
 Embedded FTP
 Embedded Telnet
 Embedded SMTP
 Embedded POP3
 Embedded HTTP
 URL Parsing
 HTML Parsing
 HTML Generator
 Base 64 Encoding
 WIN32/UNIX Interoperability
 Windows/POSIX Wrappers
 Object-Oriented Design
 Thread Creation/Construction
 Thread Destruction
 Cancellation
 Exit
 Join
 Suspend
 Resume
 Sleep
 Priority Functions
 Thread Specific Storage
 Thread Pooling
 Mutex Locks
 Conditional Variables
 Semaphore Synchronization
 String Classes
 Memory Buffers
 Device Caching
 Linked List Classes
 Binary Search Tree
 Stack Classes
 Queue Classes
 Date/Time Classes
 Data Encryption
 Configuration Manager
 Log Generator
 Postscript Text Generator
 Portable TERM I/O
 Text Utilities
 String Utilities
 Portable Directory Funcitons
 Portable File Functions


 License

The DataReel library is copyrighted by glNET Software, Copyright © 2001-2002, all rights reserved. DataReel is an open-source library available to commercial, individual, and academic developers. The open-source archive is distributed under the OSI approved GNU Lesser General Public License (LGPL) with provisions for use in commercial and non-commercial applications under the terms of the LGPL. glNET Software as the original author and copyright holder of the DataReel open-source library offers an amendable run-time license for commercial users that cannot apply the terms of the LGPL to their application. Please submit any licensing questions to DataReel support. Please report any suspected licensing violations to glNET Software.

DataReel Copyright © 2001-2002 glNET Software

Amenable Run-Time License
What is the RTL? The glNET Software run-time license (RTL) agreement is designed to meet the needs of developers when using open-source code and run-time libraries in commercial applications. It is intended to protect trade secret and company confidential information by allowing you to distribute binaries without any source code or references to the open-source copyright. No agreement supercedes the law so any valid licensing agreement must conform to local, state, federal, and/or international law. The RTL is a custom made agreement adapted to your specific needs accounting for applicable local, state, federal, and/or international laws relative to the terms of the agreement. If the terms of the open-source distribution agreement are too restrictive for your application or usage would constitute a violation of an existing law the RTL is a mechanism used to account for these obstacles that would otherwise prevent you from using the code. The RTL can also be adapted to customer-supplied agreements.

Do I need the RTL? You do not need the RTL for your commercial application if you compile the library and link to it without making any changes to the source code.

Who needs the RTL? You should obtain the RTL to protect your trade secret and company confidential information if you make changes to the source code and do not wish to release those changes to the public or make any references to the DataReel copyright or open source license.

Are there any RTL licensing fees? The source code and all subsequent versions are free to use with no royalties or reoccurring licensing fees. There is a one time processing fee of $29.00 US per license agreement. Additional costs may include legal fees only if required when preparing the agreement. For information on obtaining the glNET Software RTL please contact:

glNET Software
P.O. Box 820314
South Florida, FL. 33082-0314
FAX: 1-800-339-7068
http://www.glnetsoftware.com/contact.htm

GNU Lesser General Public 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA


 Supported Platforms

The following is the current list of operating systems used for development and cross-platform testing. If the operating system you are using is not listed please contact DataReel support as this list may change without notice.

Supported and Original Test Platforms


 Supported Compilers

The following is the current list of compilers used for development and cross-platform testing. If the compiler you are using is not listed please contact DataReel support as this list may change without notice.

C++ Compiler list


 Package Map

The DataReel Windows and UNIX archives are identical and can be unpacked on either platform depending on the decompression tools available to you. In order to remain consistent with multiple archiving schemes all files and directories conform to the ISO 9660 8.3 naming convention. The directory structure for the distribution is as follows:

DataReel Directory


 Major Library Changes in Version 4.2


 Outstanding Issues in Version 4.2

The gxsTelnetClient class exhibited undefined behavior when communicating with network devices that have weak telnetd implementations. The problem involves the proper terminal type negotiation when the telnet session is started with the possibility of further problems if the any terminal type negotiation is required later in the telnet session. The immediate fix was to add the gxsTelnetClient::RecvInitSeq() function used to process the initial connection sequence sent by the telnet server when the telnet session is first established. This fixes the initial connection sequence but undefined behavior may result if further negotiation is required during the telnet session. The gxsTelnetClient class must handle the SB TERMINAL TYPE SEND SE/SB TERMINAL TYPE IS req/resp in accordance with the telnet RFCs to ensure that all terminal negotiations are being handled correctly or at least by some baseline standard.

prevnext database example crashes under HPUX11 and Solaris 8 when native 32/64-bit integer types are used. Traced the problem to the gxDatabase::FindPrevBlock() function. The following statement causes a core dump with native types due to the type cast used: (*((gxUINT32*)(buf+(FAU_t)i)) This problem has been noted but not corrected since native types are only used for debugging with IDEs.

The Multicast examples program will not compile using BCC32 5.5 The compiler complains about the IP_MULTICAST_TTL definition, the ip_mreq multicast address join structure, and the IP_ADD_MEMBERSHIP definition. These items are part of the Winsock library yet the BCC compiler will not recognize them.

The BCC32 5.5 compiler will not allow the use of I/O stream manipulator functions prefaced with a scope operator (::hex, ::dec, etc). This usage is required by the GXSTD macro. To correct the problem all BCC code must be compiled using the __USE_ANSI_CPP__ preprocessor directive.

gxscomm2 r_win32.cpp example program hangs when executed under Windows 2000 and Windows XP compiled with MSVC 6.0 SP5.

A run-time problem was discovered in the multithreaded example programs when compiled under gcc version 2.96. Using the pthread_join() function and the C++ "endl" I/O manipulator causes the program to hang. To fix the problem all occurrences of "endl" in all files have been replaced with the "\n" new line escape sequence.


 Wish List for Version 4.2


 Example Programs

The DataReel library includes over 100 console based example programs. The examples are fully functional programs used to test and demonstrate each component of the library individually. The example programs are located within subdirectories of the "examples.gen", "examples.db", "examples.mt", and "examples.soc" directories. NOTE: In version 4.2.1 Beta you must build the DataReel library before building any of the example or utility programs. All examples and utilities are built using an include makefile located in the env subdirectory.

WIN32 Makefiles
msvc.mak - Microsoft Visual C/C++ 6.0 SP3 or Microsoft Visual C++ .NET
bcc32.mak - Borland BCC32 5.5

UNIX Makefiles
hpux10.mak - HPUX front-end compiler
hpux11.mak - HPUX aCC compiler
linux.mak - gcc compiler
solaris.mak - Sun WorkShop C++ compiler


 Documentation

NOTE: The DataReel 4.2 documentation set is under construction and will not be released until all the beta testing is completed. All updates to this readme file and any other documentation updates will be posted to the DataReel Website.

The DataReel 4.1 documentation set covers the class library, example programs, and the utility programs. The class library is documented by category with a detailed description and usage note for each function. The DataReel example programs have been converted to an HTML format with comments/remarks denoted by red lettering. Utility programs are documented with a brief description and usage information.

The complete DataReel 4.1 documentation set is available in an HTML format. Parts of this documentation set may be produced in other formats and re-distributed with applicable source code modules. The DataReel HTML documentation set is distributed with each DataReel source code distribution. Updated versions and all changes are posted to the DataReel Web Site:

http://www.datareel.com/docs.htm


 Unzipping

The entire DataReel distribution requires approximately 8 MB of free disk space to unpack. Two distributions are available, one for Windows and one for UNIX. The DataReel Windows and UNIX archives are identical and can be unpacked on either platform depending on the decompression tools available to you.

Windows Installation
To unpack this distribution on a Windows platform you will need a copy of PKZIP version 2.03 for DOS or WINZIP version 6.1 or higher for WIN32. To unzip using PKZIP 2.03 follow these instructions:

C:\>mkdir datareel
C:\>copy dreelXXX.zip c:\datareel
C:\>cd datareel
C:\datareel>pkunzip -d dreelXXX.zip
UNIX Installation
To unpack this distribution you need a copy GZIP/GUNZIP version 1.2.4 or higher. To unpack using GZIP and the UNIX tar utility follow these instructions:
% gzip -d dreelXXX.tgz
% tar xvf dreelXXX.tar
To unpack using GUNZIP and the UNIX tar utility follow these instructions:
% gunzip dreelXXX.tgz 
% tar xvf dreelXXX.tar
To unpack using the UNIX uncompress utility follow these instructions:
% zcat dreelXXX.tar.Z | tar xvf -
NOTE: You can also use the UNIX uncompress utility to unpack GZIP files:
% zcat dreelXXX.tgz | tar xvf -
NOTE: You can also use UNZIP for UNIX version 5.12 or higher to unpack the zip archive:
% mkdir datareel
% cp dreelXXX.zip datareel/dreelXXX.zip
% cd datareel

% unzip -a -L dreelXXX.zip
The unzip "-a" option will auto-convert all text files to a UNIX format and the "-L" option will make the directory and file names all lower case.


 Building BCC Static WIN32 Library

The BCC32 makefiles requires you to build the BCC static library are located in the winslib subdirectory. To build the library using the BCC make utility execute the following command:

C:\DataReel\winslib>make -f bcc32.mak 
This will build the 32-bit static library. To build the 64-bit library you must uncomment the following line in the winslib\bcc32.env file and rebuild the static library:
64BIT_DEFMACS = -D__64_BIT_DATABASE_ENGINE__

C:\DataReel\winslib>make -f bcc32.mak clean
C:\DataReel\winslib>make -f bcc32.mak
NOTE: Before building the example programs or the utility programs using the BCC compiler you must set the absolute path to the DataReel library in the env\bcc.mak file:
GCODE_LIB_DIR = C:\DataReel 
If you are using the Borland IDE to build the library, examples, or utility programs please refer to the winslib\bcc32.env file for the required preprocessor directives, library dependencies, compiler and linker flags.


 Building MSVC/C++.NET DLL

The MSVC/C++.NET makefiles requires you to build the MSVC DLL are located in the dll subdirectory. To build the DLL using the MSVC/ C++.NET nmake utility execute the following command:

C:\DataReel\dll>nmake -f msvc.mak 
The will build both the 32-bit release and debug DLLs and place them in the C:\DataReel\dll\release and C:\DataReel\dll\debug directories. If you are using the MSVC or C++.NET Visual Studio to build the library, examples, or utility programs please refer to the dll\msvc.env file for the required preprocessor directives, library dependencies, compiler and linker flags.

To build the 64-bit DLL execute the following commands:

C:\DataReel\dll>nmake -f msvc.mak clean
C:\DataReel\dll>nmake -f msvc.mak 64BITCFG=1
NOTE: Before any dynamically linked executable can be launched you must install the DLL or set a path to the DLL. The DLL can be installed in the directory with the executable, in the Windows system directory, or be visible in any set path. To set the DLL path for the current console window execute the following command:
C:\>set path=%path%;C:\DataReel\dll\release;C:\DataReel\dll\debug


 Building MSVC Static Library

To build the static library using the MSVC/C++.NET nmake utility execute the following command:

C:\DataReel\winslib\>nmake -f msvc.mak 
This will build the 32-bit debug library. To build the release library utility execute the following commands:
C:\DataReel\winslib\>nmake -f msvc.mak clean
C:\DataReel\winslib\>nmake -f msvc.mak FINAL=1
To build the 64-bit static library execute the following commands:
C:\DataReel\winslib\>nmake -f msvc.mak clean
C:\DataReel\winslib\>nmake -f msvc.mak FINAL=1 64BITCFG=1
If you are using the MSVC or C++.NET Visual Studio to build the library, examples, or utility programs please refer to the winslib\msvc.env file for the required preprocessor directives, library dependencies, compiler and linker flags.

NOTE: None of the example or utility programs will link to the MSVC/C++.NET static library. If wish to link to the static library instead of the dynamic one you must modify the msvc include makefile located in the env subdirectory.


 Building UNIX Share/Static Libraries

The UNIX makefiles requires you to build the UNIX static/shared libraries located in the unixlib subdirectory. To build the library using the UNIX make utility execute the following command for one of the supported UNIX platforms:

% make -f linux.mak
% make -f solaris.mak
% make -f hpux10.mak
% make -f hpux11.mak 
This will generate the "libgxcode.a" static 32-bit library and the "libgxcode.so.4.X" shared 32-bit library. To build the 64-bit library for Linux, Solaris, or HPUX 11 you must uncomment the following line in the unixlib/linux.mak, unixlib/solaris.mak, or unixlib/hpux11.mak makefile and rebuild the library:
64BIT_DEFMACS = -D__64_BIT_DATABASE_ENGINE__ -D_LARGEFILE64_SOURCE

% make -f linux.mak clean
% make -f linux.mak

% make -f solaris.mak clean
% make -f solaris.mak

% make -f hpux11.mak clean
% make -f hpux11.mak
NOTE: By default the example and utility programs will link to the static version unless the libgxcode.so.4.X is symbolically linked or renamed to libgxcode.so in the unixlib build directory. Before executing any executable linked to a shared UNIX library you must make the library visible to the system's dynamic loader. To do this either install the library in a default lib directory such as /lib, /usr/lib, /usr/X11/lib or set the LD_LIBRARY_PATH environment variable equal to the absolute path of the directory containing the library. NOTE: Before setting the LD_LIBRARY_PATH check to see if the variable has already been set:
echo $LD_LIBRARY_PATH 

If the LD_LIBRARY_PATH variable is not set execute one of the 
following commands depending on which shell you are using:

/bin/csh
setenv LD_LIBRARY_PATH /usr/local/datareel/dreelXXX/lib

/bin/sh
LD_LIBRARY_PATH=/usr/local/datareel/dreelXXX/lib 
export LD_LIBRARY_PATH

If the LD_LIBRARY_PATH variable is set execute one of the following 
commands depending on which shell you are using:

/bin/csh
setenv LD_LIBRARY_PATH /usr/local/datareel/dreelXXX/dlib:${LD_LIBRARY_PATH}
   
/bin/sh   
LD_LIBRARY_PATH=/usr/local/datareel/dreelXXX/dlib:${LD_LIBRARY_PATH}
export LD_LIBRARY_PATH
To install the library in the DataReel lib directory execute a "make install" from the command line. This will copy the libgxcode.a and libgxcode.so.4.X files to the DataReel lib directory and create a symbolic link from libgxcode.so.4.X to libgxcode.so. NOTE: When a UNIX compiler sees both a static and shared library in the same directory it will always link to the shared library first.


DataReel Copyright © 2001-2002 glNET Software, All Rights Reserved