This chapter includes instructions for installing Genero BDL on either UNIX or Windows platforms.
Summary:
See also: Tools and Components, Localization Support, Environment Variables.
The following table shows the operating systems supported. The identifier is part of the installation package name:
| Identifier | OS Name | Processor | OS Version |
hpx1100 |
HP/UX | Risc 32b | 11 |
h641100 |
HP/UX | Risc 64b | 11 |
aix0433 |
IBM AIX | Risc 32b | 4.3.3 |
a640433 |
IBM AIX | Risc 64b | 4.3.3 |
a640510 |
IBM AIX | Risc 64b | 5.1.0 |
lnxlc22 |
Linux | X86 32b | Linux distribution with glibc 2.2 (see below) |
lnxlc23 |
Linux | X86 32b | Linux distribution with glibc 2.3 (see below) |
w32vc60 |
Microsoft Windows | X86 32b | NT4/SP6, 2000/SP4 + Visual C++ 6.0 |
w32vc70 |
Microsoft Windows | X86 32b | NT4/SP6, 2000/SP4 + Visual C++ 7.0 |
w32vc71 |
Microsoft Windows | X86 32b | NT4/SP6, 2000/SP4 + Visual C++ 7.1 |
osf0510 |
Tru64 | Alpha 64b | 5.1 |
sco0505 |
SCO Open Server | X86 32b | 5.05 |
sls0260 |
SunOS | Sparc 32b | 5.6 |
s640800 |
SunOS | Sparc 64b | 5.8 |
uxw0711 |
SCO Unixware | X86 32b | 7.1.1 |
The following list identifies certified Linux distributions according to the glibc version:
Genero BDL does not require any particular hardware except a network card for license control.
A network card is required by the license manager. It is not possible to install Genero BDL on a computer without a network card.
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.
According to the operating system and the type of installation (development or runtime environment), the total required disk space can vary from 20 Mb to 25 Mb.
Genero BDL requires the following software to be installed on the system:
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.
In order to run BDL programs, you must create a DVM with the fglmkrun tool by giving the target database driver. This tool needs a C linker to create the DVM executable program.
For more details about DVM creation, see the "Creating a DVM" section below.
3.2.1 C linker On UNIX platforms:
You only need to have a C linker on the system where you create the virtual machine; you can then deploy the created DVM on the production sites. However, you should pay attention to dynamically linked executables. Use the file, ldd or dump command to check if an executable is dynamically linked. See system-specific help for these commands.
3.2.2 C linker On Microsoft Windows platforms:
w32vc60 operating system
identifier.Common system libraries such as Math (libm.a) and TCP/IP (libsocket.a) are also required, but such libraries are usually part of the system by default.
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:
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:
Examples:
fjs-fgl-1.10.1a-a640510.sh
fjs-fgl-1.10.1a-lnxlc22.sh
fjs-fgl-1.10.1a-wnt0430.exe
Before launching the installation program, make sure:
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:
$ /bin/sh fjs-fgl-1.10.1a-aix0430.sh -hTo 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:
fjs-fgl-1.10.1a-wnt0430.exeAt this point, follow the online instructions.
After installing the product, read the release notes in the "README" file provided in the installation directory, under the 'release' directory. The "README" file contains important last-minute information that may not be found in the documentation.
It is also recommended that you read the license terms provided in the "LICENSE" file. Read this file carefully before using the product in production.
You may need to run the fglinstall tool to install the 4gl libraries and messages files. You can also re-run the setup script fglmkrtm which is automatically called at the end of the installation.
If the DVM creation failed at the end of the installation, you can try to create it again by doing the following steps:
$ . /usr/local/fgl/envcomp $ echo $INFORMIXDIR $ type cc
cc is hashed (/usr/bin/cc) $ fglmkrun -d ix930 -l esql $ fglinstallDuring the installation, you are prompted to license the software. A license must be entered before you can use the product.
For 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 existing directory having a valid license. You do not have to re-enter the license keys.
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
The following command shows the current installation number:
$ fglWrt -a info
An existing license can be dropped using the following command:
$ fglWrt -d
To re-install a license, use the following command:
$ fglWrt –l
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
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.
You likely need to re-create a new DVM as described in the "Creating a DVM" section.
You need to create a DVM because it must be linked to a database driver that is specific to the database server you are using. Additionally, you can create a DVM that includes your own C functions that can be called from the 4gl code. This feature is described in C Extensions.
The Genero BDL runtime system is a virtual machine that interprets p-code
(42m) files. It is similar to a java virtual machine. The DVM is a C
executable program (usually
named fglrun) that needs to access a database server through the
database client library provided by the database vendor (Informix CSDK ESQL/C,
Oracle Call Interface, IBM DB2 Call Level Interface). This database client
library is used by the BDL database driver which is specific to the database
vendor. Several database drivers are provided in the Genero BDL package as
C libraries (libix*.a, libifx*.a, libora*.a, libdb2*.a).
The fglmkrun tool uses one of these
libraries to create the DVM executable program, according to the
-d option.
To link a DVM, fglmkrun needs a C linker (cc) or the tool provided by the database client software, such as the 'esql' tool provided in the Informix CSDK.
7.2.1 On UNIX platforms:
You need an ANSI compatible C compiler and linker on the development computer. The C compiler is used during the installation to create a DVM by linking operating system, database client and runtime libraries together. Check that the installed C compiler conforms to ANSI standards. ANSI-compatible C compilers accept the -c flag to produce object files and the -o flag to produce executable files. You can define the C compiler for Four J's BDL with the FGLCC environment variable. When using IBM Informix ESQL/C, you can set the C compiler with the INFORMIXC environment variable to force the ESQL compiler to use your C compiler.
7.2.2 On Microsoft Windows platforms:
You need Microsoft Visual C++ version 6 to be installed on the Windows platform where you want to link DVMs. Basically, you need the CL.EXE compiler to compile your C Extensions and the LINK.EXE linker to link the DVM.
On UNIX platforms, start a sh Bourne shell, a ksh Korn shell or a bash shell and set the BDL environment variables with the 'envcomp' script:
$ . /opt/devtools/fgl/envcomp
$ echo $FGLDIR
/opt/devtools/fgl
On Microsoft Windows, you must start a CMD window with the "Workplace Window" shortcut of the "Genero Business Development Language" Start menu.
The database client software environment variables must be set (INFORMIXDIR, ORACLE_HOME, DB2DIR, PGDIR). Check the database client software documentation for more details.
On UNIX platforms, make sure you have a linker (ld) and if possible, a C compiler (cc) installer. If you have a GNU compiler installed, you can verify the gcc version with the -v option:
$ gcc -v
Reading specs from ...
Configured with ...
Thread model: posix
gcc version 3.2 20020903 (Reh Hat Linux 8.0 3.2-7)
C:\> C:\PROGRA~1\MICROS~2\VC98\BIN\VCVARS32.BAT
Setting environment for using Microsoft Visual C++ tools.
C:\> CL
Microsoft (R) 32-bit C/C++ Optimizing Compiler Version 12.00.8168 for 80x86
Copyright (C) Microsoft Corp 1984-1998. All rights reserved.
...
...
C:\> LINK
Microsoft (R) Incremental Linker Version 6.00.8168
Copyright (C) Microsoft Corp 1992-1998. All rights reserved.
...
...
With fglmkrun, a DVM may be created with a static or dynamic database interface. DVMs created with a static interface are statically linked to a database interface library and can only connect to the database server the library was designed for. DVMs with the dynamic database interface can load database drivers at runtime according to FGLPROFILE settings. With dynamic DVMs, BDL programs can connect to different database servers simultaneously, using CONNECT TO instructions.
fglmkrun options
The fglmkrun tool expects a set of options as normal commands. Some options require a value, for example:
$ fglmkrun -o myrun -d ix914 -l "cc -static"
You can see the list of supported options by giving the -V
option to fglmkrun.
To see what happens behind fglmkrun, you
can use the -v option, which enables the verbose mode.
To create a static DVM, use the -d option with one of the database
identifiers that is listed using the -dl option. The name of the
database driver following the -d option is a code that starts with
the type of driver (ix, ifx, ora, db2,
msv, pgs) and the database client software version
number, without dots. For example: ix914, ifx930,
ora901, db281.
C:\> fglmkrun -dl
List of database interfaces codes you can give to the -d option:
Code DB Client Env Architecture
--------------------------------------------
nodb N/A N/A
dynamic N/A Dynamic
ifx9** Ifx ESQL 9.** Static
ora81* Oracle 8.1.* Static
ora90* Oracle 9.0.* Static
ora92* Oracle 9.2.* Static
pgs71* PostgreSQL 7.1.* Static
pgs72* PostgreSQL 7.2.* Static
pgs73* PostgreSQL 7.3.* Static
db27* IBM DB2 7.* Static
db28* IBM DB2 8.* Static
msv70 SQL Server 7.0 Static
msv80 SQL Server 2000 Static
adb12 Adabas D 12 Static
ix501 Informix 5.01 Static
ix711 Informix 7.11 Static
ix720 Informix 7.20 Static
ix9** Ifx ESQL 9.** StaticThe linker to be used is specified with the -l option. By
default, on UNIX, fglmkrun uses cc (or gcc if it is
installed). On Microsoft Windows the default is LINK. On Both UNIX
and Microsoft Windows, if you have Informix CSDK environment, fglmkrun uses esql
as the default linker. The fglmkrun tool can also automatically detect the Informix
ESQL/C version in order to select the proper database driver library (you do not
have to specify the driver type with -d option).
Unix Only Options
The -dcl option can be used to specify the database client
software libraries.
$ fglmkrun -o myrun -d ix914 -l cc \
-dcl "-L$INFORMIXDIR/lib/esql -L$INFORMIXDIR/lib -lifsql
-lifgen -lifos -lifasf -lifgls -lifglx"
Use the -usl option to specify operating system libraries such
as libm.a or libsocket.a. In most cases system libraries needed by
the runtime system are automatically added by fglmkrun, according to the type of
database driver.
By default, fglmkrun can automatically recognize the operating system and
select the system libraries. If the tool does not
recognize the system, you can force a specific OS with the -s option.
You can get the list of operating system identifiers with the -sl option.
Linker Flags
If you need to pass special flags to the linker, use the -lkf option:
C:\> fglmkrun -d ora901 -lkf "/NOLOGO /STACK:1000000,1000000 /SUBSYSTEM:console"
C Extensions Options
You can create a DVM with your own C functions, as described in the C Extensions section.
To create a DVM with C extensions, you must provide the extension
definition file with the -ext option and your C sources, object
files or libraries respectively with the -acs, -aob
and -alb options.
For example:
$ fglmkrun -v -o myrun -d ora901 \
-ext myext.c \
-acs "query.c params.c" \
-aob "files.o" \
-alb "mathlib.a utils.a parser.a"
C Compiler Flags
If you need to pass special flags to the C compiler, use the -cpf option:
$ fglmkrun -d ifx930 -cpf "-O2 -Wall"
Static or dynamic DVM?
According to the operating system and the database interface, you may need to create a statically linked DVM or a dynamic DVM using shared objects. Statically linked DVMs are usually portable, however there are exceptions. Dynamically linked DVMs are portable, as long as the production environment provides the same shared objects (i.e. dynamic libraries) as on the system where the DVM is linked.
You can see if an executable file is linked statically using a system tool
like ldd or dump (on AIX):
$ ldd -r myrunner
libifsql.so => /opt/informix/lib/esql/libifsql.so
(0x40014000)
libifasf.so => /opt/informix/lib/libifasf.so (0x4004a000)
...
This example shows a DVM linked statically:
$ ldd -r myrunner
not a dynamic executable
Specifying the output file
With fglmkrun, you can define the output
file with the -o option. The default is "$FGLDIR/bin/fglrun"
on UNIX or "%FGLDIR%\bin\fglrun.exe" on Windows:
$ fglmkrun -o $FGLDIR/bin/myrun -d ora901
Environment Variables
| Variable name | Description |
| FGLDIR | Used to install the DVM program in bin directory, when
the -o
option is not provided. |
| FGLDBS | Defines the database interface type. Can be overwritten with the -d option. |
| FGLLIBSQL | Defines the target database libraries used for linking. Can be overwritten with the -dcl option. |
| FGLLIBSYS | Defines the system libraries used for linking. Can be overwritten with the -usl option. |
| FGLCC | Defines the command for C sources compilation and linking. |
| FGLCFLAGS | Defines the flags for C sources compilation. Can be overwritten with the -cpf option. |
| FGLLFLAGS | Defines the flags to link the DVM. Can be overwritten with the -lkf option. |
Creating an Informix DVM:
First, make sure the Informix environment is set (INFORMIXDIR).
To create an Informix specific DVM, use -d option with an
"ix" or "ifx" database driver. When using "ix"
drivers you link a DVM with the Standard Database Interface architecture, 100%
compatible with IBM Informix 4GL. When using "ifx" drivers you link with
the Open Database Interface architecture. See Connections
for more details about SDI / ODI architectures.
We recommend that you link Informix DVMs with the standard compilation
tool provided with the latest Informix CSDK packages. This tool is called 'esql'.
You can specify the esql linker with the -l option, but fglmkrun
uses it by default if the Informix environment is set. When using esql, you do
not need to specify any database client library or system library because these
libraries are automatically added by the compilation tool.
If you don't have Informix CSDK with esql, you must provide the Informix API
libraries and the system libraries. You can specify these libraries with the
-usl and -dcl options.
The ESQL/C linker must be used and the INFORMIXC environment variable must be set to the C linker you want to use.
We recommend that you use the native linker of your system. However, you can also use the GNU gcc compiler if it is installed.
The following example shows a DVM creation with the GNU gcc, with an Informix interface::
$ INFORMIXC="gcc"
$ export INFORMIXC
$ fglmkrun -o runifx -d ifx930 -l esql
Runner successfully created.To create a statically linked DVM when
using gcc, you
must pass the -static option to both gcc and esql:
$ INFORMIXC="gcc -static"
$ export INFORMIXC
$ fglmkrun -o runifx -d ifx930 -l "esql -static"
Runner successfully created.
Creating an Oracle DVM:
The DVMs created with "ora" drivers need the ORACLE Client Shared Library (i.e. $ORACLE_HOME/lib/libclntsh*) for linking and for execution. You can rebuild the libclntsh library with the genclntsh tool provided by ORACLE in $ORACLE_HOME/bin.
It is mandatory to create ORACLE DVMs in the same environment as the production site: Specific system libraries and link options are needed to link ORACLE client programs, according to the environment.
By default, the tool searches for the system libraries required by ORACLE. This list is defined in $ORACLE_HOME/lib/sysliblist.
ORACLE provides an special makefile to set all required variables for linking programs: '$ORACLE_HOME/rdbms/lib/env_rdbms.mk'. This file is specific to the operating system. Check your installation and search for TTLIBS, LLIBTHREAD and LDFLAGS in this file.
To detect the system libraries and the link flags, a makefile can be used to include the ORACLE environment makefile and generate some output to set the environment variables to link the DVM:
default: orasyslibs
include $(ORACLE_HOME)/rdbms/lib/env_rdbms.mk
orasyslibs::
@echo
@echo 'FGLLIBSQL="$(TTLIBS) $(LLIBTHREAD)"'
@echo 'export FGLLIBSQL'
@echo
@echo 'FGLLIBSYS=""'
@echo 'export FGLLIBSYS'
@echo
To create an Oracle-specific DVM, use the -d option with an "ora"
database driver:
$ fglmkrun -o runora -d ora901
Runner successfully created.Creating an IBM DB2 DVM:
To create IBM DB2 DVMs, the DB2 Client Library is needed. The library is
named libdb2.so and is provided in '$DB2DIR/lib'.
To create a DB2 specific DVM, use the -d option with an
"db2" database driver:
$ fglmkrun -o rundb2 -d db281
Runner successfully created.Creating a Microsoft SQL Server DVM:
To create Microsoft SQL Server DVMs, you need ODBC and the Microsoft SQL
Server Client Software. The ODBC library is
named odbc32.lib and is provided in Microsoft Visual C++ libraries.
To create an SQL Server specific DVM, use the -d option with an
"msv" database driver:
$ fglmkrun -o runmsv -d msv80
Runner successfully created.Creating a DVM with Dynamic Database Interface:
To create a DVM with dynamic database interface, use the "-d dynamic" option:
$ fglmkrun -o rundyn -d dynamicThis creates a DVM that is able to load one or more database drivers at runtime, as shared libraries (on UNIX) or DLLs (on Windows).
You need then to create a shared database library with the fglmksdl tool.
If you have created a DVM with dynamic database interface, you must create shared database driver libraries with the fglmksdl tool.
On UNIX platforms:
You create a shared database driver library, having the .so, .sl
or .a extension, according to the operating system.
Example:
$ fglmksdl -d ora901
Library successfully created.By default fglmksdl creates the shared library in FGLDIR/bin, with the following naming convention:
dbmdriver.extension
where:
-o
option.On Microsoft Windows platforms:
You create a DLL database driver library, having the .DLL
extension.
Example:
$ fglmksdl -d ora901
Library successfully created.By default fglmksdl creates the DLL library in FGLDIR/bin, with the following naming convention:
dbmdriver.DLL
where:
-o
option.Thread local storage and shared libraries
On HP/UX 11, the shared library loader cannot load libraries using thread local storage, like Oracle libclntsh. So you may not be able to use shared libraries on this system. For more details, search for "shl_load + Thread Local Storage" on the HP support site.
Linking on AIX
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
LIBPATH environment variable
The LIBPATH environment variable defines both the default library path information during link and the shared object search path at runtime. When using the AIX linker, if you do not specify any -L flags, or if you specify the nolibpath option, the default library path information if written in the loader section of the output file. The default library path information is used at runtime if the shared object cannot be found in one of the directories specified in the LIBPATH environment variable. Make sure LIBPATH contains all required library search directories, including the system library path /lib and /usr/lib.
The dump command
On IBM AIX, you can check the library dependencies with the dump Unix command:
$ dump -H fglrunCreating shared database libraries
To create a shared database library, you may need to use the ld system linker with special flags as in the following example:
$ fglmksdl -d ora815 -l "ld -bM:SRE -bnoentry -bexpall -lc"
Unloading shared libraries from memory
You may need to use the slibclean Unix command to unload a shared library from the system shared library segment. Once a shared library is loaded by the system, you cannot rebuild the executable file unless you unload the library from the system with slibclean.
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 to use the xlc_r compiler to link a program with pthread support, simply specify that compiler as link tool to fglmkrun by using the -l xlc_r option:
$ fglmkrun -d ora920 -l xlc_r
Linker options
You may need to set the STACK linker option to a specific value; you can do
this with the -lkf option:
C:\> fglmkrun -d ora901 -lkf "/NOLOGO /STACK:1000000,1000000 /SUBSYSTEM:console"
Unixware 7.1 does not provide shared library versions of libm.a and libgen.a. Therefore, you will not be able to use shared libraries on this system.