Project

General

Profile

Quick Start

Introduction

This chapter describes:

  • Where to find a sample project that can be used as a starting point for designing your own conversion project.
  • The steps by which you can convert those Progress ABL sample projects to Java and then compile/run the resulting Java code.
  • How to use a sample project as a template for your own conversion project.
  • How to use a sample project to convert and execute arbitrary ABL code.

As a prerequisite for this chapter, you must follow the instructions in Installation and Setup of the Conversion Environment to build a development environment that allows both automated conversion and the execution of that converted code for test or debug purposes.

The use of a the build system instructions will only result in a system on which the automated conversion process can be run. The minimal conversion system is not suitable for running the converted application. This chapter assumes that you need to execute the converted application. This means you must have a system on which the FWD runtime components are installed. The developer system meets this requirement. For complete information regarding the installation of runtime components of the FWD system, including for use as a production quality runtime installation, please see the Installation, Configuration and Administration Guide.

Obtaining the Sample Projects

There are two sample projects, one for a ChUI application and the other for GUI. These project provide a fully working FWD project that includes the ABL code for a small representative application as well as the configuration and scripting to convert and execute the result in Java.

Pick the project that most closely matches the ABL application you are working on:

Hotel ChUI Demo Application
Hotel GUI Demo Application

How to Setup, Convert and Execute the Sample Project

To test the validity of a developer system, you can use the following documentation to setup, convert and run the associated sample project:

ChUI Setup, Conversion and Execution Instructions
GUI Setup, Conversion and Execution Instructions

The videos and screenshots that have been made can be completely duplicated using the FWD code and these sample projects. These can be used as an educational introduction to the technology.

Converting and Running Arbitrary ABL Code in the Sample Project

Introduction

This procedure allows a wide range of development, testing and debugging to learn and work with FWD. One common case is to isolate errant behavior in converted Progress code. When diagnosing problems it is desirable to develop the simplest Progress ABL test case that demonstrates the correct behavior. Such a test case may then be converted and launched in the FWD runtime to demonstrate the difference and to help determine how the conversion or runtime needs to be altered.

The more "standalone" the test code, the easier it will be to get it going. This means that there is a single external procedure file (.p) which does not call any other external procedures. FWD can handle the most complex procedure dependencies, but for purposes of this discussion, we want to start with a simple, standalone test case. These instructions document some of the different steps needed for more complex cases, but they primarily focus on the simple case.

Assumptions

These instructions assume that you have already successfully converted and run the sample project without any changes.

All instructions will be relative to the conversion project's top-level directory, which named anything. In the ChUI and GUI projects, this is documented as:

Linux Windows
~/projects/hotel/ c:\projects\hotel\

The ant build scripts are run from this directory and the server/client scripts are run from deploy/server/ or deploy/client/ respectively. To make this easy, change your current directory into the top-level project directory:

Linux Windows
cd ~/projects/hotel/ c: && cd \projects\hotel\

Clearing Unnecessary Code and Schemata

If you are sure you don't need to run the sample code, you can delete the ABL code and the Hotel schema file. It is possible that you may want to edit these files for some use cases. Please read all of the rest of the instructions before you delete things.

If you are sure you want to delete these:

Linux Windows
rm -fr abl/* data/hotel.df data/dump/hotel/ del /q abl\* data\hotel.df
rmdir /q /s data\dump\hotel\

To ensure that the FWD server does not try to connect to the Hotel database, use a text editor to modify the directory deploy/server/directory.xml (Linux) or deploy\server\directory.xml (Windows). Search for the section /server/standard/database/ by finding the text "database". Remove the enclosed "container" section called "hotel" (remove this element and all nested elements.

Please note that if you are adding your own schema, you may want to just modify this database section of the directory, instead of removing it. See the Schema Changes section below for details.

Place the ABL Code

The following trivial code can be used as an example in the instructions below.

   MESSAGE "Hello World!" VIEW-AS ALERT-BOX.

Save it to a file named abl/hello_world.p (Linux) or abl\hello_world.p (Windows).

Instead of this example, you can use your own code. When you do that, make sure to pick code that is known to work (see Supported ABL Features). Otherwise, you can expect to have problems in conversion or at runtime.

Place the code (external procedures and include files) in abl/ (Linux) or abl\ (Windows). The code would be stored in the subdirectory structure the code normally expects when it would be compiled or executed in OpenEdge.

Adjust the PROPATH

FWD is dependent upon the equivalent of the PROPATH for both conversion and for runtime. This is the same concept as in OpenEdge, but the way that it is set is different.

By default, the sample projects are setup as if the abl/ (Linux)/abl\ (Windows) directory are included in the propath. The GUI project has an additional entry for abl/common/ (Linux)/abl\common\ (Window).

If all include files and run statements are relative to the "root" of where the source code resides, then there is nothing else to do.

If compiling or executing relative to these default directories is not sufficient for your application code to work (to find its include files or procedures to compile/execute), then you will need to adjust the FWD equivalent of the PROPATH. This is done in 2 places.

Conversion

Use a text editor to modify the propath value in cfg/p2j.cfg.xml (Linux) or cfg\p2j.cfg.xml (Windows).

The default ChUI value looks like this:

<parameter name="propath"          value="${P2J_HOME}:${P2J_HOME}/abl" />

This is the default GUI value:

<parameter name="propath"          value="${P2J_HOME}:${P2J_HOME}/abl:${P2J_HOME}/abl/common/" />

Notice that these values are always specified using : and / characters. Likewise, the ${P2J_HOME} is used to make the values relative to the top-level project directory. Usually it is best to add your entries to the end of the value.

For example, if you have a subdirectory abl/includes/ (Linux) or abl\includes\ (Windows) that is needed for your code to compile, then you would edit the ChUI version as follows:

<parameter name="propath"          value="${P2J_HOME}:${P2J_HOME}/abl:${P2J_HOME}/abl/includes" />

Runtime

The runtime PROPATH is stored in the FWD Application Server's "directory" which is the primary configuration file for the system.

Use a text editor to modify the /server/standard/runtime/default/file-system/propath value in the deploy/server/directory.xml (Linux) or deploy\server\directory.xml (Windows).

Search for the propath text, you will find the following XML nodes.

ChUI:

<node class="string" name="propath">
  <node-attribute name="value" value=".:"/>
</node>

GUI:

<node class="string" name="propath">
  <node-attribute name="value" value=".;common\;"/>
</node>

Notice that these values will be delimited using the file and path separators of the original runtime system. If the OpenEdge system ran on Linux/UNIX then you would use the : and / characters. For a Windows system, you would use ; and \. Do NOT use the values that match the system on which you are running FWD. Usually it is best to add your entries to the end of the value.

For example, if you have a subdirectory abl/includes/ (Linux) or abl\includes\ (Windows) that is needed for your ChUI code to execute and the code was running on UNIX, then you would edit as follows:

<node class="string" name="propath">
  <node-attribute name="value" value=".:includes/"/>
</node>

Schema Changes

If you limit the code to temp-table usage or if the code has no database usage, then there are no schema changes to implement.

Otherwise, you have two choices: edit or add/replace.

Edit

This approach is used to upgrade the existing sample project's schema and exported data to work with your added code.

1. Edit the existing data/hotel.df (Linux) or data\hotel.df (Windows) to apply the minimum schema changes needed. How to manually merge the .df changes is beyond the scope of this document. Please note that FWD ignores the trailer (metadata at the end) of the .df, so those values do not need to be updated.

2. In order to populate the database, you can add .d files to the data/dump/hotel/ (Linux) or data\dump\hotel\ (Windows) directory. Each .d file to be included must have a filename that matches the DUMP-NAME value in that table's associated ADD TABLE section of the hotel.df

Add/Replace

You may choose to use one or more of your own .df files. This is useful when you want to drop the hotel.df completely or when your schema is not amenable to being merged into the hotel.df.

1. Place the .df file(s) in the data/ (Linux@ or data\ (Windows) directory. The convention is to use the logical database name (in all lowercase) for the filename (e.g. <logical_db_name>.df).

2. Use a text editor to modify the cfg/p2j.cfg.xml (Linux) pr cfg\p2j.cfg.xml (Windows). Follow the instructions in Schema Loading to configure the conversion to be properly aware of the new schemata.

3. For each .df file, create a new directory (with the same logical database name) in data/dump/ (Linux) or data\dump\ (Windows).

Linux Windows
mkdir data/dump/<logical_db_name>/ md data\dump\<logical_db_name>\

4. For each .df file, add the matching .d files to the data/dump/<logical_db_name>/ (Linux) or data\dump\<logical_db_name>\ (Windows) directory. Each .d file to be included must have a filename that matches the DUMP-NAME value in that table's associated ADD TABLE section of the .df

5. Use a text editor to change the build.xml (this is in the top-level project directory). This is needed to enable the database creation and import for H2 or PostgreSQL. Search for this section:

<property name="db.name"              value="hotel" />

Change the value from "hotel" to your "<logical_db_name>". If you have multiple schemata, you will have to edit all of the "targets" of the build.xml which are dependent upon that value. These will have to be duplicated and differentiated (db.name2, db.name3...).

6. Use a text editor to change the deploy/server/directory.xml (Linux) or deploy\server\directory.xml (Windows). Search for the section /server/standard/database/ by finding the text "database". In the enclosed "container" section called "hotel" there will be multiple references to hotel (including the container name itself) which you must replace with your <logical_db_name>. If you have multiple schemata, you will need to duplicate the container inside the database section, so that each logical database has a separate section. The logical database names will need to be replaced in each section. For details on the structure of this section, please see Database Configuration.

Convert and Build

Specifying the Programs to Convert

By default, the conversion process will convert all files under the abl directory which have a file extensions of .p, .P, .w, or .W. These are assumed to be external procedures. If all the external procedures that are added follow this naming pattern, they will get picked up automatically when conversion is run. In this case there is nothing else to do.

If any external procedures (including database trigger procedures that are referenced in the schema) are named with a pattern that does not match, you will have to create a conversion filelist. This is an explicit list of the programs to be converted and it overrides the wildcard pattern listed above.

Linux Windows
Run find ./abl/ -name "*.[pPwW]" > file-cvt-list.txt to create the same list that would be created dynamically using the wildcard pattern. For the ChUI sample project, the resulting file would look like this:
./abl/rates.p
./abl/empty-db.p
./abl/rooms-add.p
./abl/rooms-overview.p
./abl/rooms.p
./abl/menu.p
./abl/guests.p
./abl/rates-report.p
./abl/checkout.p
./abl/exit.p
./abl/login.p
./abl/main.p
./abl/reservations.p

You can edit this file to add or remove any other external procedures/schema triggers as needed. Make sure each file as a full relative path from the top-level of the project, including the ./abl/ directory.
Run(the windows file system is case insensitive. *.p and *.P are the same patterns):
dir abl\*.p /b/s >> file-cvt-list.txt
dir abl\*.w /b/s >> file-cvt-list.txt
For the ChUI sample project, the resulting file would look like this:
C:\project\hotel\abl\checkout.p
C:\project\hotel\abl\empty-db.p
C:\project\hotel\abl\exit.p
C:\project\hotel\abl\guests.p
C:\project\hotel\abl\login.p
C:\project\hotel\abl\main.p
C:\project\hotel\abl\menu.p
C:\project\hotel\abl\rates-report.p
C:\project\hotel\abl\rates.p
C:\project\hotel\abl\reservations.p
C:\project\hotel\abl\rooms-add.p
C:\project\hotel\abl\rooms-overview.p
C:\project\hotel\abl\rooms.p

You can edit this file to add or remove any other external procedures/schema triggers as needed. Make sure each file as a full relative path from the top-level of the project, including the abl\ directory:
abl\checkout.p
abl\empty-db.p
abl\exit.p
abl\guests.p
abl\login.p
abl\main.p
abl\menu.p
abl\rates-report.p
abl\rates.p
abl\reservations.p
abl\rooms-add.p
abl\rooms-overview.p
abl\rooms.p

The explicit source list must be named file-cvt-list.txt and that file must exist in the top-level project directory. The build.xml has this filename encoded in it (you could change it if you wanted to do so).

Running the Conversion/Build Process

Apache Ant is used to script the conversion, build and database creation/import. To see the list of "build targets", you can run ant -p.

The most common way to convert and build is to use either ant deploy.all or ant deploy. Both will run the conversion, compile the Java code, build and deploy the resulting jar files.

In addition, the deploy.all will create and import a database instance that is ready for use. This must be done at least once OR you can use the ant import.db to create and import the database.

Once you have an imported database, re-running ant deploy.all will rebuild your database (re-import the original data). If you want to just convert/compile/jar/deploy without the database create/import, then use ant deploy. The existing database will not be touched in that case.

Run the Converted Result

There is a slightly different process for running the system, depending on ChUI vs GUI and on local vs web.

Specifying the Default Startup Program

Local clients are started using scripts. These scripts provide an override mechanism to specify the "startup procedure" (the equivalent of the -p option for OpenEdge). This means that by passing a parameter, the user can execute any of the converted programs.

At this time, there is no way to provide this override in the URL for the web client. For this reason, any use of the web client (ChUI or GUI) requires an update to the FWD Application Server's directory. To set this, you must do the following:

1. Determine the Java class name that matches the ABL startup procedure.

Open the name_map.xml file with a text editor and look for the full name of your ABL program which acts as an entry point for your application. If your program is named start-my-app.p and resides in abl/my/app/ folder, look for my/app/start-my-app.p. You will find a line like this:

  <class-mapping jname="my.app.StartMyApp" pname="my/app/start-my-app.p"/>

2. Use a text editor to modify the directory (deploy/server/directory.xml in Linux or deploy\server\directory.xml in Windows). Search for p2j-entry text and you will find a XML node like this:

            <node class="string" name="p2j-entry">
              <node-attribute name="value" value="com.goldencode.hotel.Start.execute"/>
            </node>

Change the value to be com.goldencode.hotel.my.app.StartMyApp.execute.

If you are only running the local (i.e. non-web) client, then you do not have to edit the directory. It can still be beneficial to do so, to eliminate the need to pass the startup procedure parameter to the scripts.

Start the Server

Linux Windows
In a terminal session:
cd deploy/server
./server.sh
In a command prompt:
cd deploy\server
server.cmd

The server is ready for client connections when you can see a line like this in the server's log file (server.log in the same directory as the server startup script):

[01/19/2017 14:07:54 EET] (SessionManager.listen():INFO) {00000000:00000001:standard} Server ready

Local Client Launch

The local ("fat") client is started using scripts.

Client Type Driver Linux Windows
ChUI Console (NCURSES/WIN32 APIs)
cd deploy/client/
./client-terminal.sh client:cmd-line-option:startup-procedure=my/app/start-my-app.p
cd deploy\client\
client-terminal.cmd "client:cmd-line-option:startup-procedure=my/app/start-my-app.p"

Note: using "" braces is mandatory on Windows to properly pass option to client driver.
ChUI Swing
cd deploy/client/
./client-swing.sh client:cmd-line-option:startup-procedure=my/app/start-my-app.p
cd deploy\client\
client-swing.cmd "client:cmd-line-option:startup-procedure=my/app/start-my-app.p"

Note: using "" braces is mandatory on Windows to properly pass option to client driver.
GUI Swing
cd deploy/client/
./client.sh client:cmd-line-option:startup-procedure=my/app/start-my-app.p
cd deploy\client\
client.cmd "client:cmd-line-option:startup-procedure=my/app/start-my-app.p"

Note: using "" braces is mandatory on Windows to properly pass option to client driver.

If you have configured the p2j-entry in the directory (see Specifying the Default Startup Program above), then you do not need to pass the client:cmd-line-option:startup-procedure=... parameter. Otherwise, you will need to specify the PROPATH-relative name to the program that should be the startup procedure. If you want to know more details about this parameter, see the bootstrap configuration reference.

No login is needed. This server's directory is setup with "open" security (which is how OpenEdge is always setup). In this configuration, the application is solely responsible for implementing its own authentication, authorization, access control and auditing.

Web Client Launch

To start the FWD web client, you need to open the appropriate URL in your browser. The recommended browsers are Chrome or Mozilla Firefox, though Safari, IE 11 and Edge also work.

If prompted, accept the certificate, and after that enter your operating system login credentials. After pressing Login, you might need to accept the certificate again; after this step, application screen will appear. A better approach is to import the root CA for the sample project's self-signed certificate. This can be imported to remove the non-trusted self-signed cert browser issues. See the following for ChUI or GUI.

For this to work, you must have followed the instructions in Specifying the Default Startup Program above.

Client Type Driver URL
ChUI Web https://localhost:7443/chui
GUI Web - Virtual Desktop https://localhost:7443/gui
GUI Web - Embedded Mode At this time it takes additional development effort to enable ABL code in embedded mode. This is not yet documented, but you can edit existing Hotel GUI ABL code (and the embedded application code and reconvert/run that to see the changes. For details on running in embedded mode, please see Hotel GUI Embedded Web Client

Using the Sample Project as a Template

You can save a great deal of time by using one of the sample projects as a template for your own project. Follow these instructions, depending on which application type is the closest match:

ChUI Template Usage
GUI Template Usage

Get Help

Register for an account to join the FWD community. Using this account, you can post a question or search for answers on the forums.

Contact Golden Code Development, the creators of the FWD project, for professional services, including adding features to FWD, assessment work, proofs of concept, full migrations, or anything in between.


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