Project

General

Profile

Wiki » Development Using a Docker Container »

Conversion Project Setup Using Docker

Introduction

This section describes how to create and convert a local copy of a 4GL project. It starts with configurations and scripts to automate converting and running the project using FWD. Additionally, the process will place the source code and schemata in the right project locations. This process is a pre-requisite for both running Reports and Analytics (see Generating Reports and Using Analytics Using Docker) and for Converting the Application Using Docker.

In the commands below, we use the Hotel GUI sample project, but any 4GL project can be substituted if put into the same format. More importantly, your application needs to have a conversion project configuration. If you do not have this, use the Conversion Handbook to create one or contact Golden Code for assistance.

It is assumed that the Docker Development Environment Setup is already complete and either:
  • FWD Development Docker will be used via fbash.sh -l and the appropriate --tag=<tag> if trunk isn't being used
  • FWD trunk has been checked out and built in ~/projects/fwd/trunk directory, or the ~/projects/fwd/<branch> directory, if a feature-specific or project-specific branch is required.

Configuration Project

The configuration project is the framework surrounding the 4GL code and schemata so that the code and schemata can be converted into Java source and Data Model Objects, and subsequently into runnable jars and and usable Javadoc. There are scripts, primarily in bash and ant build.xml that drive the conversion process, and configuration files that give information to the process regarding the 4GL in files like cfg/p2j.cfg.xml and various "hints" files. Lower level details can be found in Chapter 6 of the Conversion Handbook. In Runtime Setup Using Docker there will be descriptions of runtime configuration.

The Hotel GUI sample configuration project contains its own source code and schemata, but this isn't typical of other projects. Most projects will have separate archives of larger amounts of source code and schemata that are gathered from a source control system. Hotel GUI does provide a template to build your project by prompting you with some questions to build out a customized configuration project.

You can use the Hotel GUI's template tool to setup your project's configuration project.

Template Creation from Hotel GUI

There is a script that takes a JSON file as input, and will generate your configuration from it. This is json_template.sh, and it is located in the root of the Hotel GUI project. Below are the steps to setup a configuration project. This must be executed from a Docker container via fbash.sh (described here).

1. Pull the Hotel GUI project from the Bazaar repository in the Docker Development Environment. If you pass a parameter to bzr after the /opt/repos/hotel_gui/, it will check out the project to the directory name that you pass in. If not, it will default to the project name, "hotel_gui".

mkdir ~/projects && cd ~/projects
bzr co /opt/repos/hotel_gui/ <optional_directory>
cd <optional_directory>

2. Create a symlink to the FWD built in Build FWD Using Docker

ln -s /opt/fwd p2j

Note: If you are using dbash.sh, you will need to point the symlink to your local FWD build.

3. Create prepare_template.json file for your project.

Use any editor to create prepare_template.json file, which will will contain all the information necessary to build out the configuration project. Below is a sample for an application that uses PostGreSQL. The table will show all the valid values.

{
  "appname": "test",
  "projname": "test",
  "include_spec": "*.[fhi]",
  "program_spec": "*.[pPwW]",
  "pkgroot": "com.goldencode.test",
  "propath_bld": ".:",
  "propath": ".:",
  "admversion": "ADM2.2",
  "dbnames": "test",
  "test": {
    "dbimport_file": "test",
    "dbtype": "postgres",
    "dbhost": "localhost",
    "dbport": "5432",
    "dbadmin": "fwd_admin",
    "dbadminpass": "admin",
    "dbuser": "fwd_user",
    "dbuserpass": "user",
    "collation": "en_US@iso88591_fwd_basic" 
  },
  "win_proj": "no",
  "dateFormat": "mdy",
  "numberGroupSep": ",",
  "numberDecimalSep": ".",
  "p2j_entry": "start.p",
  "embedded_host": "localhost",
  "admin_port": "7443",
  "directory_xml_file": "directory.xml" 
}
Key Sample Description
appname test This is the name of your application, how will be known by FWD; it must include only letter or digits, with the first character being a letter, all lowercase. If your application name is My App, enter myapp.
projname test This is a more descriptive name of our application, typically the appname with the suffix "_gui" or "_chui" so as to more fully describe it. Typically it can be the same as the appname.
include_spec *.[fhi] FWD needs to know a regular expression which matches all your include files; this can be of the *.[fhi] format. If you are running the conversion on an operating system where file names are case-sensitive, make sure to match upper case extensions, too, with a regex like *.[fFhHiI]. The default value for this entry will be *.[fhi].
program_spec *.[pPwW] Same with include files, FWD needs to know a regular expression which matches all your program files. The default value for this entry will be *.[pPwW]. If you want to specify an explicit file list to be converted, they can be defined in the <file-set/> section of the p2j.cfg.xml file with inclusions and exclusions of both files and directories of programs you wish to convert. See Chapter 6 Project Setup for syntax details.
pkgroot com.goldencode.test All your converted Java sources need to be placed in a root package - this must follow the Java format for package names; the default value will be test.<appname>, where <appname> will be the value you entered in the first step. If you want to change it, you can use something like com.mycompany.myapp.
propath_bld .: At this step, FWD needs to know the PROPATH you are using during the building of the application, this can usually come from your progress.ini file; by default, this will be set to .:. Use the : as a path separator even if you are working with a GUI project.
propath .: At this step, FWD needs to know the PROPATH you will use during runtime of the application; by default, this will be set to .:. Use the : as a path separator even if you are working with a GUI project.
admversion ADM2.2 Setup as the adm.version property in build.properties for GUI applications only. Seems to be unused, otherwise.
dbnames test If you have only one database schema in use (even if is accessed by multiple databases), just enter the legacy database name. Otherwise, if your application uses multiple databases, enter all the names separated by a comma, with the name of your default database first. The script will automatically prepare the conversion, import and runtime to work with all the specified database schemas.
dbtype postgres or h2 Enter the DB type to use. Similar information will be needed, regardless, with the exception of dbport for postgres and dbpath for H2.
dbhost localhost Specify the host name or IP address of the machine running your PostgreSQL Database Server (localhost for H2).
dbimport_file test Specify the default schema file to specify. This will be configured in cfg/p2j.cfg.xml in the namespace/importFile value. See Chapter 6 Project Setup for details.
dbport 5432 Specify the port of the target PostgreSQL Database Server (for PostgreSQL).
dbpath ../db/ Specify the path to the H2 database (for H2).
dbadmin fwd_admin Provide the name of the SQL admin for your database.
dbadminpass admin Provide the password associated with your SQL admin, for your database.
dbuser fwd_user You must provide a SQL user for your database - this will automatically be created by FWD.
dbuserpass user You must provide a password for the SQL user specified above.
collation en_US@iso88591_fwd_basic The sorting collation to use for the database. A detailed discussion on collation can be found in this wiki.
win_proj yes or no Making this choice helps shortcut other build-time values: 
Key              Yes           No
---------------------------------------
path_separator   ;             :
file_separator   \\            /
case_sensitive   FALSE         TRUE
unix_escapes     FALSE         TRUE
propathsep       ;             :
opsys            WIN32         UNIX
winsys           MS-WINDOWS    ""
dateFormat mdy Enter the date format used by your OpenEdge installation; by default, this will be mdy, but can be dmy or any other version.
numberGroupSep , Enter the number group separator used by your OpenEdge installation; by default, this will be ,.
numberDecimalSep . Enter the decimal separator used by your OpenEdge installation; by default, this will be ..
p2j_entry start.p Enter the name of the program used to start the legacy OpenEdge application. This is the 4GL procedure name. If you don't know it, enter something like TODO.p and you can edit it later.
embedded_host localhost The hostname of the embedded web server.
admin_port 7443 The port to use for web client access.
directory_xml_file directory.xml Enter the directory filename, including path (relative to the server.xml file location.

4. Generate the configuration project

./json_template.sh -do

At this point your configuration project will have been created, and will require 4GL source code and schemata to be added to it.

5. Save this project directory as the initial configuration project

zip -r ~/myfirstproject.zip *

This command creates an archive file named myfirstproject.zip containing the recursed directory structure in your HOME directory. You can save this on another system by transferring it, or even place the contents into a source control system.

Taking Over the Template

The initial project was generated by the json_template.sh script using inputs from the JSON file. If all the values used were accurate, files like cfg/p2j.cfg.xml, build.properties will contain the critical values for conversion. They should be examined and understood. Many details about these file can be found in Chapter 6 Project Setup.

p2j.cfg.xml
This is the main brain for conversion. It has a cfg/global/parameter named basepath which contains the value ./abl. This is the root directory where the 4GL source code is expected for conversion. Place all 4GL code rooted at that directory. The $P2J_PATH is the project directory itself, which is used often in the file. The propath will tell the conversion program where to look for source files.

The profile section lets you build separate configurations within the same application. Most only have one, and each could have its own set of files (defined by the file-set), and set of databases, given in multiple namespace sections. Notice that all importFile values are kept under the ./data/ directory by standard. This is where your .df schemata file(s) would be placed.

build.properties
This is an input file to the ant tool. It defines properties which are used as input values to the ant build.xml file, which is the main driver for the ant build. Properties in the build.properties file can be overridden on the command line to ant with the -D<property>=<value> option.

build.xml and build_db.xml
These are input files to ant. The build.xml is the main file, and build_db.xml is a "adjunct" file to handle database requests, like creation and import. There are other tools that allow for database creation and import, so the ant tool is not a strict requirement for handling the database management. They consist of a series of tasks that are struct together by making them dependent on one another in a proper change. Executing ant -p "dumps" all the dependencies and their descriptions. There are many places that the template tool leaves behind "Hotel" information, so there is work to make the build.xml your own.

The targets that are left in the build.xml are ready to use, provided your source code is placed in the expected locations, and the database information was entered into the JSON correctly. Subsequent sections will direct you to the proper targets, depending upon whether you are converting for runtime or analytics.

Place Source Code and Schemata

At its most simple, the 4GL source gets placed under ./abl/ and the schemata gets placed under ./data/, although the schemata location can be flexible. The source can have their own directory structure under ./abl/, but the p2j.cfg.xml propath should match up accordingly. Place all .df files where you want (typically under ./data/), but the p2j.cfg.xml importFile= value in the schema namespace should point to that location, such as importFile="data/hotel.df". The project should then be ready for conversion. Of course there may be subtleties in the 4GL code itself that won't be determined until conversion attempts are made. That is what the purpose of analytics is, and is recommended to do first, which happens to be the next section.

Hotel GUI as a Sample

The Hotel GUI sample uses an automated technique for retrieval of code called "bootstrapping". This can be a model that is followed, or other methods can be used. Ultimately the configuration project and all source code and schemata need to be in place, along with access to a FWD branch or trunk, for conversion to take place. The automated setup is a repeatable way to setup the build environment that is used as an example. You may want to target your application to utilized this same setup.

Automated Setup of the Build Environment

This must be executed from a Docker container via fbash.sh (described here).

1. Pull the Hotel GUI project from the Bazaar repository in the Docker Development Environment. If you pass a parameter to bzr after the /opt/repos/hotel_gui/, it will check out the project to the directory name that you pass in. If not, it will default to the project name, "hotel_gui".

cd ~/projects
bzr co /opt/repos/hotel_gui/ <optional_directory>

2. Bootstrap the conversion by pulling the latest the project and code. Most complex projects would have code stored externally and might involve a network mount or xfer. For this example, all necessary code is stored in the development Docker image's /opt/repos directory. For information on creating any necessary mounts see here. The options to ./bootstrap_conversion.sh differ between which repository is being used, so update the options accordingly.

Notes:
  • The bootstrap script defaults to $USER for the username, so if you need to force a different user you will need to pass -u <user> (where <user> is the user to use to access resources).
  • Since you are running inside a Docker container, you need to have access to any mount from within the container, if that is the option you've chosen.
  • The <path_to_fwd> would be /opt/fwd when using fbash.sh or where you had built your version of FWD as mentioned in Docker Development Environment Setup, such as ~/projects/fwd/trunk.

The -e option directs you to xfer, the -n directs the script to not reset the project to initial setup, and the -f sets up the necessary p2j symlink to the value specified. If you are using a Docker image that contains FWD, the pre-built FWD is contained in the /opt/fwd directory. Full usage:

Usage:  ./bootstrap_conversion.sh [-eln] [-s<local_directory_for_source_archives>] -f<path_to_fwd> -u<user>
OR      ./bootstrap_conversion.sh -r
Where:
e       = All source archives and bzr projects are found using EXTERNAL paths on XFER. Defaults to INTERNAL GCD paths on DEVSRV01.
l       = Hybrid local, where source archives are found using ${HOME}/secure and bzr projects are found using EXTERNAL paths on XFER.
n       = No reset of the package prior to executing scripts.
r       = Just run the reset process and then exit. This is useful to cleanup from a prior run of the bootstrap processing.
s       = Local directory into which the source archives will be copied and from which they will be accessed. Defaults to current directory.
f       = Local path to the ALREADY EXISTING AND COMPILED FWD branch to use, or a FWD Docker image. REQUIRED (no defaults)
u       = Use this user, instead of fwd when checking code out.

3. Pull the latest project and code from xfer.

cd hotel_gui
./bootstrap_conversion.sh -ef /opt/fwd

This will pull from the local repository the following:
  • possenet project is checked out from /opt/repos/possenet/
  • skeleton project is checked out from /opt/repos/skeleton/
  • the code is included in the project. Some projects keep it in a separate location.

The project and source code are now ready to build.

Note: The same conversion project directory cannot be used simultaneously for both Analytics and Conversion. Instead, you must duplicate the setup to create two independent project directories if Analytics and Conversion are needed simultaneously.

Under the Hood

The bootstrap_conversion.sh script uses the ./bootstrap directory for hook files to facilitate setup of the conversion.

The set_project_properties.sh hook file sets the variables which hold the ZIP filenames used by the other hooks: main_src_archive, missing_classes, and missing_includes. Set the needs_ flags accordingly, as well. It is the first hook called.

For specific projects, these samples would be modified for that projects format and requirements.

The reset_project.sh hook is responsible for cleaning up any project files before starting a new conversion. It would be called unless the -n option is passed, and it would only be called if the -r option is passed.

The copy_src_archives.sh hook is responsible for retrieving all the archive files holding the source (as set in set_project_properties.sh) into an accessible location.

The apply_and_patch_src.sh hook is responsible for positioning all the files in the main_src_archive to match the appropriate setup for the build.

The apply_and_patch_schema.sh hook positions any schema that is part of the project, and makes necessary adjustments to it.

The post_setup_cleanup.sh hook is available for any cleanup of files that may have been positioned temporarily during the bootstrap process.

Working as a Team

If your environment is a shared environment, you would need to take into account the location where the project is placed would need to be available to others on the system. This can be done by locating the project in an area such as /opt, which can be made accessible to the team via group permissions. In order to start working in that area, sudo has to create the initial directory on the host (not in the Docker container):

sudo mkdir /opt/projects
sudo chown root:users -R /opt/projects

All your teammates would need to be in the users group (or whichever group you choose to create), which can be accomplished by creation of the group (if it isn't there) and then modifying users so they have membership:

sudo groupadd users
sudo usermod -aG users $USER

This would add the current user to the group, and you can substitute other users for $USER. For a lot of users, you could use a little bash loop:

for user in user1 user2 user3 user4 user5; do sudo usermod -aG users $user; done

Container Considerations

When you start a container with dbash.sh or fbash.sh, that container would not have access to /opt/projects from within it. To gain access, you can include the --manual_mount=/opt/projects:/opt/projects option, and you will mount the directory into the container. All changes will be persistent.

You can further simplify things, and better match up with the documentation, if you create a symlink to the /opt/projects location in your home directory:

cd ~
ln -s /opt/projects ~/projects

After doing that, within the container you start with dbash.sh --manual_mount=/opt/projects:/opt/projects (or fbash.sh with the same options) you can then utilize ~/projects within the container. It will be linking to the real location, but you can work from within your home directory.

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