Project

General

Profile

Development Environment Setup

This chapter is out of date and is no longer being maintained. It is only being retained for historical purposes. The replacement chapter can be found in Development Environment Setup.

FWD is both a set of automated conversion tools as well as a runtime used to provide an environment and set of 4GL-compatible services for the proper execution of a converted application.

This chapter describes how to create a FWD development system. This requires an installation of the FWD project and its related runtime components for the purpose building a development environment. This environment is suitable for converting a 4GL application into a Java application. This installation described here is also suitable for the purposes of building, modifying, or enhancing the FWD technology.

With these instructions a user can establish an installation in which they can:

  • prepare a Progress 4GL application project for conversion;
  • run the analysis and reporting tools to inspect or otherwise process the 4GL source code;
  • run the automated conversion tools to translate the 4GL source into an equivalent Java application;
  • build/compile the results of conversion such that the application is ready to execute;
  • build the FWD code to allow use for conversion or runtime;
  • add, remove or otherwise modify, enhance or customize the FWD conversion or runtime code; and
  • source level debug the converted application and/or the FWD runtime code.

It is assumed that all of the runtime components (client, application server and database server) will be run on the same system as where the FWD project is modified and built. More flexible installations are possible, but such installations are out of scope for this book. For complete information regarding runtime installation, please see the FWD Runtime Installation, Configuration and Administration Guide.

Hardware Requirements

Prepare a system meeting the following hardware requirements:

Feature Requirement
CPU Any recent Intel-compatible CPU will work. It is recommended to stay with a 32-bit x86 processor since it greatly simplifies the installation of the runtime components. FWD has been tested to work on systems which can run 64-bit code, however the installation requirements of such an environment are beyond the scope of this book. Please see the FWD Runtime Installation, Configuration and Administration Guide.

At this time the conversion process is single-threaded. While a multi-core CPU can be highly useful in running the conversion JVM, the benefit of those cores will not be as high due to this fact.

The FWD runtime is highly threaded, so a multi-core CPU environment will be of great benefit for this purpose.

Both AMD and Intel CPUs have been tested and have been found to work well. If the JVM being used works well on a given CPU, then that CPU is OK. CPUs such as the Intel Core-2 Duo have been found to be quite suitable for both conversion and runtime performance.
RAM It is recommended to have at least 2GB of RAM and if possible 4GB of RAM. This will allow the comfortable hosting of the development environment, and both the conversion and runtime FWD processing. Small conversion projects can convert in less memory and the converted application may run in less, but for reasonable sized projects (1 million lines of code), the 2GB-4GB requirement should be considered a minimum.
Disk Space The conversion process stores a great deal of state on the disk. Even medium sized projects may take 5GB of disk space to convert fully. Larger projects will require more space. It may also be useful to store more than one conversion project on the system.

In addition, to the degree that a database data is being migrated, such migrations require space for the .d data export files as well as a significant amount of disk space for the imported database.
Since Progress 4GL databases are very heavy in index usage and Progress is optimized to keep the index data small. Since the same logical indexes are maintained in the target runtime environment, the target database will have to maintain those indexes on disk. Common relational databases do not optimize the space of indexes to the same degree as Progress. This means it should be expected that the imported database will require significantly more disk space than the original Progress database.

Consider the number of conversion projects, data export files and databases (including copies and test environments) and calculate disk space accordingly.

Software Requirements

Prepare a system meeting the following software requirements:

Requirement Version Notes
Linux (or another UNIX-compatible operating system) n/a Java processes are normally platform neutral. When applications or tools are written in pure Java, it is possible for such processing to be run on any operating system or hardware platform that supports the proper level of the J2SE (Java 2 Standard Edition) required.

At this time, while the vast majority of the client FWD code is written in pure Java, there is a small amount of platform-specific code (written in C) used for character mode user interface processing and for process launching. That platform-specific code is implemented using the Java Native Interface (JNI) and is often referred to as “native” code. A customized version of that native code is included in the FWD project. This code is currently compiled as both 32-bit and 64-bit shared libraries for Linux.

There may also be certain file-system path dependencies, character/file encoding dependencies and/or other dependencies which would require a Linux or UNIX compatible system on which to run the conversion process. In particular, it is likely that the conversion process cannot be run unchanged on a Windows platform.

FWD has been successfully run on a variety of recent Linux distributions from Ubuntu, SuSE, Red Hat and CentOS. There are no specific dependencies on any particular distribution. It is expected that any UNIX-compatible system would work properly.
Java Development Kit (JDK) 6.0 or later The Sun JDK 1.6 on Linux is a well tested option. Various versions from 1.6.0_04-b12 through 1.6.0_16-b01 have been tested and have been found to work well.

Either the 32-bit or 64-bit version may be used.

At the time of this writing, there has been no conversion project so large as to require more than 4GB of memory to successfully complete. For this reason, there is no strong requirement for the 64-bit JVM.

For client usage, the 32-bit JVM is best.

Since the memory requirements of server processes can be large, it is expected that the 64-bit version may be necessary for some installations. The application server process (JVM) is where the majority of working memory exists for each client (accessing the system). The actual memory used will depend on the queries, the block flow, recursion and other features of the original 4GL. The application code is actually running in the common server process, which is different from how Progress 4GL works (where the application runs in the client process unless an “appserver” is in use). However, for a development environment, it is less likely that 64-bit is needed.

In general, try to use the 32-bit version unless there is a specific reason to do otherwise.

The PATH for the user should be set to include the directory containing the command line executables (e.g. java or javac) of this installation. In Linux this would be the bin/ directory. In other words, this should be the default installation for any shell or command prompt from which the FWD technology will be built or used.
It is also recommended to set the user's CLASSPATH (on Unix/Linux) as follows:
export CLASSPATH=.
Apache Ant 1.6 or later Due to the ANTLR dependencies, version 1.5.3 does not work. Please ensure that Ant can be found via the user's PATH.
GNU Compiler Collection (GCC) C compiler and binutils 4.7.3 or later The native portions of FWD must be built using gcc, make and related tools.
NCURSES Development Headers n/a In prior releases of Debian/Ubuntu distributions, the ncurses.h header file was present in a standard gcc installations, but recent versions (e.g. Ubuntu 12.10 and later) no longer provide this by default. Make sure to install the libncurses5-dev package to get the suitable headers.
unzip n/a Among many options, the commonly available unzip utility can be used to extract files from a ZIP archive. This will need to be used to extract the FWD archive.

Install FWD Project Code

The FWD project code should be available as a ZIP format archive file. This archive should include all of the source code and supporting files needed to build the FWD project on a given system.

For the sake of this example, assume that the zip file name is ~/p2j_20100620.zip and that the p2j code is to be installed in a directory named ~/projects. Given these assumptions, installation is as simple as the following commands to extract the zip file:

cd ~/projects
unzip ~/p2j_20100620.zip

A directory ~/projects/p2j will be created with the entire contents of the FWD project. For the remainder of the chapter, the environment variable $P2J will be a reference to ~/projects/p2j.

This can be "saved" into the environment to simplify subsequent commands:

export P2J=~/projects/p2j

Build FWD

The FWD project must be built. This will compile all code and then create jar files and native libraries that store the compiled code. The commands:

cd $P2J
ant all

All of the FWD conversion and most of the runtime tools are stored in a file called p2j.jar. That file in turn is dependent upon other jar files, which have been specified in the p2j.jar file's manifest. This means that as long as the p2j.jar can be found in the Java CLASSPATH and those other jar files exist in the same directory, the tools will work properly.

The p2j.jar can be found in the $P2J/build/lib/ directory, along with each of the dependent jar files which are shipped with the FWD project. It is best to use those versions since they are tested and are known to work.

When running FWD commands, it will be necessary to use the -classpath $P2J/build/lib/p2j.jar:. parameter on the java command line.

Besides p2j.jar the build process also produces shared library libp2j.so, which provides native support for child process creation at runtime via Java Native Interface (JNI). It resides in $P2J/build/lib/ directory and is only used at runtime, if the converted application makes use of Progress 4GL commands that deal with process creation (INPUT THROUGH, INPUT-OUTPUT THROUGH, OS-COMMAND, UNIX etc).

Should (re)building of libp2j.so alone be necessary for any reason, the following build step can be run:

cd $P2J
ant native

The above compiles libp2j.so and copies it to $P2J/build/lib/ directory. From there it can be picked up when setting up the runtime environment. More details can be found in chapter Runtime Environment Overview.

Patch NCURSES

Please see Patching NCURSES for the details.

Fix TERMINFO Definitions

Please see Patching TERMINFO for the details.

Install FWD Collation Services for H2 Database

The H2 database (http://www.h2database.com) is used in embedded mode for temporary table support and for internal runtime housekeeping. In addition to the _temp database, in which all temporary tables are created, one embedded H2 database instance is used for each permanent database used by your application. Also, H2 can be used as a backend for the permanent database, either in embedded or server mode.

FWD uses version 1.2.147 of the H2 database. This version of H2 is included in the build directory as a dependent jar file.

To ensure that the H2 database is able to collate its string data in the same manner as Progress, it is necessary to provide the Java virtual machine with some guidance as to how we want text values sorted within H2. The HotSpot JVM does not use operating system specific locales to gather this information. Instead, collation rules are implemented in a cross-platform manner, using J2SE's service provider architecture.

FWD uses a custom implementation of java.text.spi.CollatorProvider for this purpose. This resource is shipped with FWD, within the p2jspi.jar file. It must be installed and made available to the FWD runtime using the Java Extension Mechanism. This provides J2SE's Locale and related classes with access to the custom collation services that are needed by FWD. To enable this support, the p2jspi.jar file must be copied from the $P2J/build/lib directory to the Java Extension directory for the target JVM. For a Sun JVM, this directory is located at $JAVA_HOME/jre/lib/ext. Note that administrator rights may be required, depending upon where the JVM is installed.

On the Ubuntu 9.04 distribution, the $JAVA_HOME corresponds to the path /usr/lib/jvm/java-6-sun/. This path must be found if the JAVA_HOME environment variable is not set. Do not make the mistake of putting the p2jspi.jar into the /usr/lib/jvm/java-6-sun/ext/ directory. That is an empty directory which is NOT used for extensions. The correct directory is /usr/lib/jvm/java-6-sun/jre/lib/ext/ in this example.

Once the p2jspi.jar file is installed for the JVM which the FWD application server uses, be sure the FWD directory has the appropriate collation specified for each database used by your application (including the _@temp@ database). The FWD directory path for this setting is:

database/{database_name}/p2j/embedded-collation

where {database_name} is _temp for the temporary table database, or the appropriate physical database name for any permanent database used by the application. The value should be set to the string value en_US_FWD (currently the only custom collation supported by FWD).

If the p2jspi.jar file is installed properly and the FWD directory has the embedded-collation property set correctly, the FWD runtime environment will initialize the embedded H2 databases to use the en_US_FWD collation upon server startup. If the server cannot find a setting for embedded-collation in the FWD directory for the _temp database, the following warning is issued to the server log file:

Embedded primary database _temp collation not set;  using default Java collation

If the server cannot find an embedded-collation setting for another database, the following warning is written to the log:

Embedded dirty database {database_name} collation not set;  using default Java collation

where {database_name} is the name of the affected database.

If the JVM cannot find the en_US_FWD collation rules upon server startup, the following error message is issued to the server log:

Error setting FWD-specific collation;  please ensure p2jspi.jar is installed in Java extension directory

This is a fatal error, which indicates that the p2jspi.jar file is not properly installed as a Java Extension for the server's JVM. In this case, double check that you have installed the jar file for the JVM actually being used to launch the FWD server (avoiding a common mistake when multiple JVMs are installed on a development system), and ensure that you have copied the jar to the correct ext subdirectory (since the HotSpot JVM misleadingly has two of them, as discussed above).

Database Server

At this time, the FWD project can use PostgreSQL and H2 as its backing Relational Database Management System (RDBMS). Note that currently H2 is not recommended for production use, but can be successfully used for testing or development. Additional database types will be supported as customer demand requires. The following instructions will help you get your FWD database server “up and running” in an environment where you can run and test your converted application, but they are not necessarily appropriate for a production FWD installation. When considering a production installation, please consult the FWD Runtime Installation, Configuration and Administration Guide.

The installation and setup of a local database server is not necessary in the following cases:

  • The Progress 4GL code does not access any database features.
  • The Progress 4GL code's use of database features is limited to temp-table (or work-table) usage.
  • The necessary test database(s) are accessible over the network on another system.

If any of the above conditions exist, then this section's instructions can be skipped.

PostgreSQL server

To ensure the behavior of the new system matches that of the old as closely as possible, certain legacy features must be supported by the database server in the converted application. These features require special attention when installing the database server.

For instance, a Progress database by default will sort string data differently than a standard PostgreSQL database for the same locale. To make PostgreSQL sort these data in a similar manner to the pre-conversion system, it is necessary to install a custom locale at the operating system level, which the PostgreSQL database cluster can then use to collate its string data.

Likewise, built-in functions used in the where clauses of 4GL data access language statements (e.g., FOR, FIND, etc.) require special consideration. These functions are converted to user-defined functions within the Hibernate Query Language (HQL) queries used by the converted application. This approach presumes support for user-defined functions exists in the backing database. To provide such support, FWD relies upon PL/Java, an open source project which enables Java as a procedure language within a PostgreSQL database.

Step 1: Install a Custom Locale

In order to ensure that text data sorts properly (compatibly with the Progress database sorting), a custom locale must be installed.

The PostgreSQL database cluster used for a converted application must be initialized using a custom locale which defines how FWD databases should sort textual data in indexes and query results. The FWD project provides a custom locale for this purpose: en_US@p2j_basic, which must be installed into the Linux operating system on the database server machine, before the PostgreSQL FWD cluster is created. This locale is intended to mimic, as closely as possible, a Progress database's default collation behavior using the ISO-8859-1 character set. Only this default case is supported at this time, and dynamic collation changes made by individual 4GL language statements currently are not supported by FWD.

The following instructions will install this onto a Linux system (at this time, there is no analog to this procedure for the Windows operating system).

  1. Ensure the Linux package which provides the libc locale database sources is installed on the target machine.
  2. Run localedef --help and review the bottom of the output to determine which directories contain these source files (as well as the path which contains the system's binary locales). The source will often reside in some derivative of i18n, such as /usr/share/i18n. The binaries will often reside in subdirectories of /usr/lib/locale.
  3. Login as the system's superuser.
  4. Change to the directory containing the charmap files (e.g., /usr/share/i18n/charmaps). Locate the archive containing the ISO-8859-1 charmap definition. Decompress it if necessary (it may be gzip'd or otherwise archived).
  5. Copy the custom FWD locale source file from the p2j/locale subdirectory into the system's locales source directory (e.g., /usr/share/i18n/locales).
  6. Run the locale compiler (the following lines should be emitted as a single command on one line):
Step 2: Install PostgreSQL Database Server Software

Install the PostgreSQL server and client software. The PostgreSQL database version 8.x (8.2 or higher is recommended) will serve as the back end to your converted application. The simplest way - recommended for test and development environments at a minimum - is to use your platform's package manager to install a binary distribution of the PostgreSQL server. Be sure to install client software at the same time, which you will need for database administration, testing, ad-hoc queries, etc. This document assumes the psql client is installed, but other PostgreSQL client software can be used as well.

If you have a need to compile PostgreSQL with custom settings, you will need to consult the PostgreSQL documentation, as that requirement is beyond the scope of this document.

In either case, stop before you initdb a new cluster.

Step 3: Create a FWD-Specific Database Cluster

You will create a cluster which is specifically for use with your converted FWD application. It should be separate from any database cluster used for non-FWD applications, because it will be built atop our custom, en_US@p2j_basic locale described above. Thus, it will collate string data like a Progress database, which may not be appropriate for other applications.

If you installed the PostgreSQL server software from a binary package, the package probably created a default database cluster. We will not use this default cluster, since we have to create a cluster which uses the custom, en_US@p2j_basic locale described above. A locale cannot be applied to a PostgreSQL cluster once it has been created, so we must create a new cluster. In this case, consult the packager's documentation (or the postgresql.conf file if a default cluster was installed) to determine the data subdirectory in which PostgreSQL stores its databases.

If you built PostgreSQL yourself, and installed it from scratch, take note of the data directory you specified. You will need it to initialize a cluster.

PostgreSQL provides the initdb utility to create a new database cluster. We need to specify an extra option to this utility, to override the default locale with the en_US@p2j_basic locale we installed previously:

su - postgres
initdb --locale=en_US@p2j_basic -D {data_dir}

where {data_dir} is your data subdirectory.

Step 4: Create a Database User Account

Create a database user account with which your application will access the database. The converted application uses a single database user for all database access required by application business logic. Thus, each user of the application will not have a corresponding database user account. User and group accounts and application security in general are managed at the application server, not at the database.

The database user you create here should have sufficient rights to log into the database and to read and write normal application data, but should not have superuser rights (i.e., should not be able to create/drop databases, grant/revoke privileges, etc.). The postgres user is not re-used for this purpose, because that account does have superuser rights to the database.

PostgreSQL provides the createuser and dropuser utilities to manage database roles and privileges. Please consult the PostgreSQL documentation for instructions on the use of these utilities and/or the DDL statements used to manage user accounts.

Step 5: Install User Defined Function (UDF) Support

Install PL/Java, version 1.4 for Progress-compatible, built-in function support in database queries.

PL/Java enables the use of Java as a procedure language within a PostgreSQL database. This allows the definition of User Defined Functions (UDFs) implemented in Java, for use in SQL statements. This is necessary for FWD to execute queries containing the equivalent of Progress built-in functions. To ensure the converted application behaves identically to the original application, the FWD runtime environment provides compatible Java implementations of Progress built-in functions, such as LOOKUP(), NUM-ENTRIES(), and so forth. These functions can be used in where clauses for data access language statements like FIND and FOR, and the conversion process will generate Data Manipulation Language (DML) statements which expect these functions to be executed within the context of those queries at the database server. Accordingly, we need a way to execute the compatible Java implementations of these functions at the database server, which requires Java be available as a procedure language within PostgreSQL.

This architecture is much more efficient than executing the functions at the application server. The latter approach would require that we return a superset of the possible results from the database server to the application server, then execute the built-in functions at the application server to perform the final step of filtering. In most cases, this would involve pushing significant amounts of data between database server and application server - an expensive operation - only to throw away all of those results which do not match the criteria specified by the built-in function portions of the query. With PL/Java, this filtering is performed at the database server instead.

There are two phases of enabling FWD's built-in function support. The first, described in this section, is to install the PL/Java software on the database server. This provides the basic support of defining and enabling Java as a procedure language in PostgreSQL. The second phase is to install a FWD-specific jar file into each database which requires Progress-compatible, built-in function support. That step is described in the Data Migration chapter of this handbook.

Obtain and Unpack PL/Java

PL/Java is a third party, open source project (http://pgfoundry.org/projects/pljava/), which is not (in its entirety) shipped with the FWD distribution. It is comprised of a Java component, which is platform neutral, and a platform-specific component, which must be binary-compatible with the version of PostgreSQL you are using. The binary distribution of PL/Java which is available at the time of this writing is compiled for use with the 32-bit version of PostgreSQL 8.3.x. It can be found in the pl subdirectory of the FWD project.

If you are using a newer version of PostgreSQL or a 64-bit version, you will need to build PL/Java on the machine on which PostgreSQL is installed. Building PL/Java from source can be a bit tricky and is a topic beyond the scope of this chapter. Please refer to the PL/Java project documentation and the Advanced Setup chapter __ of this book, if you have this need.

Unpack (or build) the PL/Java binary code in a directory of your choice on the database server (e.g., /opt/pljava). This directory will be referred to below as {pljava_home}.

PostgreSQL Configuration Changes

Once you have downloaded and unpacked the PL/Java binary distribution (or built PL/Java from source), you will need to configure PostgreSQL to use it.

PL/Java provides a native library (pljava.so) which must be made accessible to the PostgreSQL server. You can either copy this file alongside PostgreSQL's other libraries in PostgreSQL's lib subdirectory, or you can tell PostgreSQL where to find it. The latter is accomplished by editing the dynamic_library_path setting in the postgresql.conf file. By default, this setting reads:

#dynamic_library_path = '$libdir'

Change it to:

dynamic_library_path = '$libdir:{pljava_home}'

where {pljava_home} is replaced with the location of the pljava.so file on your database server system. Note that this is a path name, not a file name; it specifies the directory containing the pljava.so file, not the file itself.

While you are editing postgresql.conf, add the following settings as well (customarily located in the CUSTOMIZED OPTIONS section):

custom_variable_classes = 'pljava'
pljava.classpath = '{pljava_home}/pljava.jar'

where {pljava_home} is replaced with the location of the pljava.jar file on your system.

Finally, you may want to limit the amount of heap each PL/Java-launched JVM can use, since you will have one JVM instance running per connection which uses Java UDFs. To do this, add a line to the same section in postgresql.conf:

pljava.vmoptions = '-Xmx8m'

The option(s) specified here will be passed by PL/Java to the JVMs it launches. 8 megabytes should be more than enough to support all of the standard UDFs that are part of FWD, though you should experiment with this number, especially if you implement your own UDFs (see the Java Inside the Database - User Defined Functions chapter).

Next, we need to ensure some environment variables are set for the postgres user (the Linux user account which is used to launch the database server). Doing so provides the PL/Java software running in the server's context with the information necessary to find and launch the Java Virtual Machine, in order to execute Java UDFs. These environment variables are most easily set by modifying the shell configuration (e.g., .bash_profile if using bash) for the postgres user, which ensures they are available to the postmaster (the main PostgreSQL server process).

Add the following lines to the shell configuration file:

JAVA_HOME={location_of_JRE_installation}
CLASSPATH=
LD_LIBRARY_PATH=$JAVA_HOME/jre/lib/i386:$JAVA_HOME/jre/lib/i386/server

where:

{location_of_JRE_installation} should be set to the top-level directory of the Java 6.0 JRE installed in the previous step.

CLASSPATH is nulled out to ensure the JVM launched by the PostgreSQL back end process does not inherit a default CLASSPATH setting for the machine, but rather relies solely upon the classpath set when installing the p2jpl.jar (discussed in the Data Migration chapter of the FWD Conversion Handbook).

LD_LIBRARY_PATH is set to allow PL/Java to find the libraries needed to launch the JVM. Note that we specify the HotSpot server compiler (.../jre/lib/i386/@server@) when setting this variable. This is intended to improve performance with the assumption that a JVM, once launched, is long-lived due to connection pooling. Note also the reference to i386, which presumes a 32-bit JVM. Adjust this setting accordingly if using a 64-bit JVM.

On some Linux distributions, there may be a better place to set environment variables used by PostgreSQL. For example, Ubuntu-based PostgreSQL packages create an environment file alongside the standard configuration files, specifically for this purpose. Consult your platform-specific documentation for these particulars.

When you have finished making the above changes, restart the backend PostgreSQL process.

Bootstrap PL/Java for a Database

The following commands must be executed (once and only once) against each PostgreSQL database which will use Java UDFs:

cd /opt/pljava
psql -U {super_user} -f install.sql {database_name}

{super_user} is a user with rights to modify the target database

{database_name} is the target database

PL/Java Uninstallation

In the event you later need to uninstall PL/Java from your database server, the following commands must be executed against each database into which PL/Java was installed:

cd /opt/pljava
psql -U {super_user} -f uninstall.sql {database_name}

{super_user} is a user with rights to modify the target database

{database_name} is the target database

Next, back out the changes made in the PostgreSQL Configuration Changes section above and restart the backend PostgreSQL process.

H2 server

Similar to the PostgreSQL server, using H2 as a backend for a permanent database requires some special attention to certain issues. These issues are related to how H2 sorts its strings, the unknown value and how built-in functions are registered.

Step 1: Install FWD Collation Support Services

In order to ensure that text data sorts properly (compatibly with the Progress database sorting), the JVM in which H2 is running must have access to custom collation rules. Follow the instructions in the Install FWD Collation Services for H2 Database section above. As you do this, keep in mind that if you are running H2 as a standalone database server, you must install the p2jspi.jar file in the Java extension directory for the JVM which will be used for the H2 server, which is not necessarily the same JVM running the FWD application server (it may be on a different machine altogether).

After the p2jspi.jar file is installed for the appropriate JVM, the H2 database must be initialized so that the en_US_FWD collator provider will be used. This is done by setting the actual collation used by the database, using the SET COLLATION command:

SET COLLATION en_US_FWD;

This command must be executed before any table is created in the database. During DDL generation, the command is automatically emitted so that is executed after all tables were dropped and before any table is created.

If you are not using the schema script generated by FWD during the M0 portion of the conversion process, then you must make sure that the collation is set before any table is created in the database.

Step 2: Sorting Unknown Value

Progress' unknown value is mapped by FWD to the null value in an H2 database. By default, for an ascending order, H2 sorts the null value low (i.e., it places the rows with null s in the sorted column at the beginning of the result set). This contradicts the Progress behavior, which requires unknown value to be sorted high when an ascending order is used (i.e. place them at the end of the result set). To solve this, H2 provides a system property (h2.sortNullsHigh) which, if set to true, will cause H2 to sort the null value high.

The recommended way of setting this property is by passing it as a parameter to the command used to start the FWD server (if the database is used in embedded mode) or the H2 server (if multiple connections are required to the database):

java -Dh2.sortNullsHigh=true ...
Step 3: User Defined Function (UDF) Support

Being written in pure Java, the Java support for user defined functions is available by default in H2. During the M0 part of the conversion, FWD will automatically output the DDL necessary to create the aliases for the user-defined functions, when the H2 dialect is used.

If the permanent database is used in embedded mode, no special setup is required; but, if a separate H2 server is used, the p2jpl.jar must be added to the H2 server JVM's classpath. See the Installation chapter of the FWD Conversion Handbook on how to start the H2 server.

Step 4: Creating a Database

In H2, a database is created when the first connection is made, if it does not already exist. The connection which creates the database is also responsible for creating a user and setting its password; until changed, all subsequent connections will have to authenticate using that user's name and password.

See the Data Migration section of the Database creation and import chapter in the FWD Conversion Handbook for details on how the H2 database can be created during schema installation.

Test Conversion

Once the FWD development environment is installed, it is important to test the conversion process.

Included in the project is the p2j/testcases/uast directory, which contains a large variety of test cases, most of which are "standalone". This means that there is a single external procedure file (.p) which does not call any other external procedures. Thus there are no dependencies on other procedures. FWD can handle the most complex procedure dependencies, but for testing purposes it is useful to start with a simple, standalone sample.

The p2j/testcases/uast directory contains a project configuration, which provides information to the FWD conversion engine necessary to convert the source files contained in this directory. These instructions assume the 4GL source code to be converted resides in this pre-existing project directory.

A good example of a 4GL procedure that includes temp-table access (but not database table usage), user interface processing and some business logic is the file p2j/testcases/uast/primes.p. The remainder of these instructions assume that this file is the primary source code being converted.

The p2j/testcases/uast/ask.p will also be converted. This is a simple harness program which prompts the user for the name of a program to run. It is useful in a test environment when you have converted more than one program, and you wish to run different programs without resetting the server's configuration and restarting the server between runs.

These instructions assume that you are running Linux and using the bash shell. Change your current directory into the "project" directory:

cd $P2J/testcases/uast

This is the directory which is the root for the configuration, schemas, 4GL source code, etc. that are to be converted. In this case, it already exists. The source files happen to reside in the "project root". But that is neither desirable nor common outside of the most basic test environment. If you had a different project already set up, you would switch to that directory instead.

Run the automated conversion process. The test cases being converted are primes.p and ask.p. Both files are found in the "project root" (i.e., $P2J/testcases/uast/). This means there is no relative pathing needed when specifying the filenames.

java -classpath $P2J/build/lib/p2j.jar:. com.goldencode.p2j.convert.ConversionDriver -d2 f2+m0+cb primes.p ask.p

When this successfully completes, change directory to the root of the FWD tree.

cd $P2J

Rebuild FWD which will now include the sample converted files. To do this, run:

ant jar

At this point the converted com/goldencode/testcases/Primes.class (and all the other supporting classes and inner classes, from the UI and database too) as well as the com/goldencode/testcases/Ask.class will be included in the $P2J/build/lib/p2j.jar.

Run the Converted Sample Code

The following steps will prove whether the runtime is properly setup or not. Change directory to the location of the pre-configured FWD server.

cd $P2J/testcases/simple/server

There is a simple runtime configuration that allows a server to be started to execute converted test cases. It exists in the above directory along with a script to start the server.

The default configuration will automatically run the converted version of ask.p. That program will prompt the user to run another converted program and then it will run that program if it exists.

Start the FWD server:

./server.sh

Open a new bash shell. The server has now "taken over" your previous shell. Open a new shell using the facility with which you are most comfortable.

Change directory to the location of the sample FWD client script:

cd $P2J/testcases/simple/client

There is a "simple" runtime configuration that allows a client to be started which is designed to connect to the "simple" server.

Check whether the server started properly. Watch the server's primary log file to confirm that it starts up properly:

tail -f ../server/server.log

The server is fully started when you see text similar to this:

[07/18/2008 15:19:18 EDT] (SessionManager.listen():INFO) {00000000:00000001:standard} Server ready

Run the FWD client:

./client.sh

No login is needed. This simple server's directory is setup with "open" security (which is how Progress is always setup). In this configuration, the application is solely responsible for implementing its own authentication, authorization, access control and auditing. This is useful for test cases but it is not normally used in a production environment.

If everything is working, you will be prompted for the name of the program you wish to run:

To run the converted Primes.java program, enter primes.p at this prompt (note that this is the original, Progress name, not the name of the converted Java class).

The converted program should run as expected. The following screen should be seen in the lower left corner:

Press space. This screen should appear:

If that screen is visible, everything with the converted code and the runtime (both server and client) is working as expected. This does not test any local database server that may have been installed. A less trivial application conversion and data import would be necessary for that purpose.

If there are any problems, you can check the ../server/server.log or ../server/stdout.log to look for server side issues. For any catastrophic, client-side issues, check the client directory for a file named p2j_{username}_{pid}.log (where username is your Unix user name and pid is the process ID of the client process). This file is written to the current working directory from which the client was launched. The naming convention is intended to produce a uniquely named log file across multiple runs of the client, and across multiple users on a particular workstation.

Subsequent Setup

The instructions in this chapter are sufficient for getting a running FWD development environment. It is important to understand the tasks that may be necessary in addition to the steps documented here. This chapter does not document any steps that setup a specific application or database. The following tasks may be necessary to provide an environment that supports a specific application conversion project or imported test database. It is likely this additional work is necessary to constitute a complete test or development environment that allows work on a specific converted application. Please use the referenced documentation to accomplish these tasks.

Task Reference
Copy a working conversion project to a new development system. Backup and Restore of a Conversion Project chapter, FWD Conversion Handbook
Configure or customize the FWD runtime environment. FWD Runtime Installation, Configuration and Administration Guide
Create a new conversion project from scratch. FWD Conversion Handbook
Install and setup a converted application for testing or debugging. Running and Testing Converted Code chapter, FWD Conversion Handbook
Migrate data from a Progress database into a relational database for use with the converted application. Data Migration chapter, FWD Conversion Handbook
Setup FWD dependencies (3 rd party software projects that have been customized) for modification, build and debugging. Advanced Setup chapter, FWD Developer Guide (this book).

© 2004-2017 Golden Code Development Corporation. ALL RIGHTS RESERVED.