Back to Contents

Installation and Setup

This chapter includes instructions for installing Genero BDL on either UNIX or Windows platforms.

Summary:

• 1. Supported Operating Systems
• 2. Hardware Requirements
  • 2.1 Network Card
  • 2.2 Memory and Processor
  • 2.3 Disk Space
• 3. Software Requirements
  • 3.1 Internet access
  • 3.2 Database Client Software
  • 3.3 C Compiler for C Extensions
• 4. Installing the Product
  • 4.1 Genero BDL Packages
  • 4.2 Pre-installation tasks
  • 4.3 Running the installation program
  • 4.4 Post-installation tasks
• 5. Licensing the Product
  • 5.1 License Basics
  • 5.2 Registering the license
  • 5.3 Getting license information
  • 5.4 Removing the license
  • 5.5 Re-installing the license
  • 5.6 The FGLDIR/lock directory
  • 5.7 Using a license server
• 6. Upgrading the Product
  • 6.1 Pre-upgrade tasks
  • 6.2 Licensing an upgraded installation
  • 6.3 Post-upgrade tasks
• 7. Operating System Specific Notes
  • HP/UX
  • IBM AIX
  • Microsoft Windows
  • SCO Unixware

See also: Tools and Components, Localization Support, Environment Variables.

1. Supported Operating Systems

Genero BDL is supported on a large brand of operating systems, such as Linux, IBM AIX, HP-UX, SUN Solaris and Microsoft Windows.

Each Genero BDL package is identified with an operating system code (hpx1100, w32vc71). You must install the Genero BDL package corresponding to the operating system that you use.

For the detailed list of supported operating systems, please refer to the Four J's support web site.

2. Hardware Requirements

Genero BDL does not require any particular hardware except a network card for license control.

2.1 Network Card

A network card is required by the license manager. It is not possible to install Genero BDL on a computer without a network card.

2.2 Memory and Processor

In a runtime environment, memory and processor requirements are dependent on the number of users and the type of database server. Each DVM process requires 2 Mb to 6 Mb, based on the database client software. For example, a typical requirement for a 30 user runtime environment with an Informix database server is a 500 MHz processor with 512 Mb RAM.

2.3 Disk Space

According to the operating system and the type of installation (development or runtime environment), the total disk space required can vary from 20 Mb to 25 Mb.

Warning: During installation, about 15 Mb are needed in the current temporary directory.

3. Software Requirements

Genero BDL requires the following software to be installed on the system:

1. An internet access
2. The database client software
3. A C compiler if you need to compile C extensions

3.1 Internet access

In order to license the product online from the Four J's Web site (http://www.4js.com), you need an Internet browser and an Internet connection.

3.2 Database Client Software

3.2.1 The database client software

To connect to a database server, you need the database client software to be installed on the system where you run the BDL programs.

Below is a list of database client software examples:

• Informix CSDK (with ESQL/C)
• Genero db client (ODBC driver)
• DB2 Connect (with CLI)
• Oracle Client (with OCI)
• Microsoft SQL Server Client (with ODBC driver)
• PostgreSQL client (libpq)
• MySQL client (libmysqlclient)

3.2.2 The database client library must be a shared object

Starting with Genero 2.00, database drivers are provided as pre-linked shared libraries. There is no need to link a runner or driver on site, but the database client software must provide a shared library corresponding to the one used to link the driver. The table in the next section lists supported database client software versions and the corresponding shared libraries that must exist on the system.

3.2.3 Supported database client versions

This table shows the database drivers with the corresponding database client version and shared libraries:

See also Operating System Specific Notes.

3.3 C Compiler for C extensions

If you have C Extensions, you need a C compiler and linker to build the extension library.

For more details about C extensions, see "C Extensions" section in this documentation.

3.3.1 C compiler On UNIX platforms:

Warning: On UNIX platforms, you need a cc compiler on the system where you create the C extension libraries. Some systems may not have a C compiler by default. Make sure you have a C compiler on the system.

3.3.2 C compiler On Microsoft Windows platforms:

Warning: On Windows platforms, it is mandatory to install Microsoft Visual C++ version 7.1 or higher on the system where you create the C extension libraries. You must install the appropriate Genero FGL package according to the version of Visual C++ you have installed. For example, when using Visual C++ 8, you must install the package marked by the w32vc80 operating system identifier.

4. Installing the Product

4.1 Genero BDL packages

The software is provided in self-extractible installation programs. On UNIX platforms, the installation program is a shell script (with a .sh extension). On Windows platforms, it is an executable program (with a .exe extension).

Genero BDL package files follow a specific naming convention:

fjs-product-version-osident.extension

where:

1. product is the product identifier.
2. version is the release number of the software (1.10.1a).
3. osident is the operating system identifier.
4. extension is sh on UNIX platforms and exe on Windows platforms.

Examples:

fjs-fgl-1.10.1a-a640510.sh
fjs-fgl-1.10.1a-lnxlc22.sh
fjs-fgl-1.10.1a-wnt0430.exe

4.2 Pre-installation tasks

Before launching the installation program, make sure:

1. You have a license number and a license key for Genero BDL development or runtime.
   See Licensing for more details.
2. You are using a supported operating system.
3. You are connected to the system as a user with sufficient privileges to install the software in the target directory.
4. Your configuration matches all hardware requirements and software requirements.
5. You have access to all needed DLLs (PATH) or shared libraries (LD_LIBRARY_PATH).
6. You have set the environment variables for the database client software (INFORMIXDIR/INFORMIXC, ORACLE_HOME, DB2DIR, PGDIR, LD_LIBRARY_PATH).
7. You can use the C compiler if you need to create C Extensions.

Warning: Before starting the installation program, make sure that the database client environment variables are set.

4.3 Running the installation program

The product is provided as an auto-extractible installation program (product files and installation program are provided in the same file). The name of the package includes the operating system type and version. Ensure the package name corresponds to your system before starting the installation program.

4.3.1 Installing on UNIX platforms

On Unix platforms, Genero J's BDL is provided as an auto-extractible shell script. Distribution files and installation program are provided in the same file.

The installation program has options. Display the installation program options using the -h option:

To perform the installation, run the auto-extractible shell script with the -i option:

$ /bin/sh fjs-fgl-1.10.1a-aix0430.sh -i

The installation program determines the operating system and checks that all the system requirements are met before starting to copy the product files to your disk.

At this point, follow the online instructions.

4.3.2 Installing on Microsoft Windows platforms

On Microsoft Windows, Genero BDL is provided with a standard Windows setup program. Distribution files and installation program are provided in the same file.

To perform the installation, login as a user with Administrator privileges and simply start the executable program in the "Start" + "Run" window:

At this point, follow the online instructions.

4.4 Post-installation tasks

After installing the product, you can look at the files provided in FGLDIR/release directory.

It is recommended that you first read the license terms provided in the "license.txt" file. Read this file carefully before using the product in production.

The release notes are in the "readme.txt" file. This file contains important last-minute information that may not be found in the documentation.

Development team changes are provided in the "changes.txt" file. This file contain detailed technical information about changes in the BDL source. You should only reference this file when you cannot find an answer in the "readme.txt" file.

According to the database server you want to connect to, you will need to set up the correct database driver in FGLPROFILE. The default database driver is Informix. For more details about database driver configuration, see Connections.

5. Licensing the Product

5.1 License basics

During the installation, you are prompted to license the software. A license must be entered before you can use the product.

During the first installation, you need the license number and license number key supplied with the product package. For example:

F4Z#X34006TG + GFAS9FD78XDT

When upgrading, the product is installed over the existing directory having a valid license. You do not have to re-enter the license keys.

Warning: Neither the serial number nor the installation number will ever contain the letter O: They can only contain the digit 0 (zero).

5.2 Registering the license

To perform a full licensing, you will be prompted for the license number and license number key. An installation number will be generated from the license number and license number key. Go to the http://www.4js.com web site to get the installation number key (or contact your local Four J's support center if you fail to get the key from the web site). Enter the installation number key to complete licensing.

You have 30 days to enter the installation number key. If you cannot get the installation number key, you will have to complete the licensing manually by using the following command:

$ fglWrt -k installation-number-key

5.3 Getting license information

The following command shows the current installation number:

$ fglWrt -a info

5.4 Removing a license

An existing license can be dropped using the following command:

$ fglWrt -d

5.5 Re-installing a license

To re-install a license, use the following command:

$ fglWrt –l

5.6 The FGLDIR/lock directory

When running a BDL program, the license manager uses the FGLDIR/lock directory to store information (number of active users). This directory must have access rights for any user running a BDL program. If it does not exist, it is automatically created.

By default, the FGLDIR/lock directory is created with rwxrwxrwx rights, to let any user access the directory and create files. If you want to restrict the access to a specific group or user, you can use the FGLWRTUMASK environment variable to force fglWrt to use a specific mask when creating the lock directory:

$ FGLWRTUMASK="022"; export FGLWRTUMASK

Warning: The FGLWRTUMASK environment variable must be set for any user executing BDL programs, because the FGLDIR/lock directory can be re-created by any user at first BDL program execution.

5.7 Using a license server

You don't need to install a locale license with fglWrt if you can access a license server on the network. 

To make the runtime system use a license server, you must set the following FGLPROFILE entries:

If needed, you can specify the following optional parameters:

6. Upgrading the Product

6.1 Pre-upgrade tasks

1. Verify the FGLDIR environment is set to the directory you want to upgrade. 
2. Verify the user rights (you should login as the owner of the current installed files) and ensure all binaries can be overwritten.
3. Stop all running programs before starting the installation.

6.2 Licensing an upgraded installation

It is not necessary to re-enter the license of the product, as long the new version is installed into an existing installation directory and the new version to be installed is not a major version number change.

Warning:  If you upgrade to a new release with a major version number change, you will have to re-license the product again.

6.3 Post-upgrade tasks

When migrating to a major Genero FGL version (for example, from 1.20 to 1.33), you must recompile the sources and form files. While recompilation is not needed when migrating to minor versions (for example, from 1.32 to 1.33), it is recommended to benefit from potential p-code optimizations of the new version.

If required, you may need to re-create the C Extension libraries. Starting with version 2.00 C extension libraries must be provided as dynamically loadable modules and thus should not required a rebuild. However, if Genero C API header files have changed, consider recompiling you C extensions. Check FGLDIR/include/f2c for C API header file changes.  

7. Operating System Specific Notes

HP/UX

Thread Local Storage in shared libraries

On HP/UX, the shared library loader cannot load libraries using Thread Local Storage (TLS), like Oracle libclntsh. In order to use shared libraries with TLS, you must use the LD_PRELOAD environment variable. For more details, search for "shl_load + Thread Local Storage" on the HP support site.

PostgreSQL on HP/UX LP64

On HP/UX LP64, the PostgreSQL database driver should be linked with the libxnet library if you want to use networking. You can force the usage of libxnet by setting the LD_PRELOAD environment variable to /lib/pa20_64/libxnet.sl.

IBM AIX

LIBPATH environment variable

The LIBPATH environment variable defines the search path for shared libraries. Make sure LIBPATH contains all required library directories, including the system library path /lib and /usr/lib.

Shared libraries archives

On AIX, shared libraries are usually provided in .a archives containing the shared object(s). For example, the DB2 client library libdb2.a contains both the 32 bit (shr.o) and the 64 bit (shr_64.o) versions of the shared library. Not all products follow this rule: for example Oracle 9.2 provides libclntsh.a with shr.o on 64 bit platforms, and Informix provides both .a archives with static objects and .so shared libraries as on other platforms...

The Genero database drivers are created with the library archives or with the .so shared objects, according to the database type and version. No particular manipulation is needed to use any supported database client libraries on this platform. 

IBM provides a document describing linking on AIX systems. It is recommended that you read this document.

http://www.ibm.com/servers/esdd/pdfs/aix_ll.pdf

The dump command

On IBM AIX, you can check the library dependencies with the dump command:

Unloading shared libraries from memory

In production environments, AIX loads shared libraries into the system shared library segment in order to improve program load time. Once a shared library is loaded, other programs using the same library are just attached to that memory segment. This works fine as long as you don't need to change the shared library (to replace it with a new version for example).

Once a shared library is loaded by the system, you cannot copy the executable file unless you unload the library from the system memory. Thus, you will probably need to unload the Genero shared libraries before installing a new version of the software. This problem occurs when installing in the same directory, but can also happen when installing in a different directory. As shared libraries will have the same name, AIX will not allow to load multiple versions of the same library. Therefore, before installing a new version of Genero, make sure all shared libraries are unloaded from the system memory.

To get the list of shared libraries currently loaded into memory, use the genkld command. The genld command collects the list of all processes and reports the list of loaded objects corresponding to each process. Then, use the slibclean command to unload a shared library from the system shared library segment.

POSIX Threads and shared libraries

When using a thread-enabled shared library like Oracle's libclntsh, the program using the shared object must be linked with thread support, otherwise you can experience problems (like segmentation fault when the runner program ends). IBM recommends using the xlc_r compiler to link a program with pthread support.

By default, the runtime system provided for AIX platforms is linked with pthread support.

Microsoft Windows

Microsoft Visual C version

You need Microsoft Visual C++ compiler to create C Extensions. Make sure you have installed the correct Genero package, according to the MSVC version you have installed on your system. MSVC runtime libraries of different VC++ versions are not compatible. Refer to the name of the Genero package to check the VC++ version compatibility.

Searching binary dependencies

Microsoft Visual C provides the dumpbin utility.

To check for DLL dependency, you can use the /dependents option:

SCO Unixware

Supported locales

Unixware 7.1 only supports a subset of the UTF-8 character set, named ISO-10646-Minimum-European-Subset. This character set does not include all characters defined by UTF-8. Therefore, you can experience problems when running an application using UTF-8 characters that are not in the ISO-10646-Minimum-European-Subset character set.