Getting Started with P2J Development

Authors	Greg Shah Eric Faulhaber
Date	November 29, 2013
Access Control	CONFIDENTIAL

Introduction
Learning the Progress 4GL
Obtaining the P2J Code
Obtaining the P2J Documentation
Learning About P2J

Introduction

P2J is an acronym for "Progress 4GL to Java". This is a source language to source language translation technology which features a fully automated conversion process and a runtime environment that provides such a high level of compatibility that the converted Java result is a drop-in replacement for the original 4GL application.

TODO list:

Read this document completely. Ask your team leader questions as needed.
If you are not already a Progress 4GL developer, teach yourself the basics of 4GL development. You don't need to be an expert 4GL developer, but you need to be able to read 4GL, understand what the code is doing and write programs using the most common features.
In the later stages of learning the 4GL, you may want to use P2J (get the code) to convert and run 4GL sample programs.
Learn about P2J.
You should be ready to pick up some P2J development tasks at this point. Debugging and documentation tasks will probably come first to allow you to dig into the code and work things before writing any substantial new code.

Learning the Progress 4GL

The Progress 4GL language is sometimes also called Progress OpenEdge or the Progress "Advanced Business Language"/ABL. Though there are newer versions, they are all just incremental differences over the original 4GL language. The new names are a weak marketing attempt to get people to accept the 4GL (since 4GL has a bad reputation in the market). We just call it by its old name of Progress 4GL.

To "ramp-up" on the 4GL:

1. Download the Progress 4GL documentation. There are 2 versions of interest:

Progress 4GL v9.1E: http://download.psdn.com/documentation/openedge/pdf_zip_files/91e/progress_documentation_9.1e_pdfs.zip
Progress ABL v11: http://download.psdn.com/documentation/openedge/pdf_zip_files/110/oepdfs.zip.

Most of our work will be done with the latest version of the documentation. However, the v9.1 versions have 2 documents that don't exist in the later versions:

Language Tutorial for Character
Progress Handbook

For this reason, it is important that you download the v9.1E documentation.

2. Inside the 9.1E docs archive, you will find a PDF called ltu.pdf ("Language Tutorial for Character"). This is a tutorial to introduce the 4GL programming language for a Unix environment. Read this tutorial and try to get the basic idea of what 4GL code looks like and means. You aren't expected to be an expert, but it is important to be able to read code and write testcases in the language.

3. Read and study the "Progress Handbook" which describes more detail on certain important language topics. This document can also be found in the 9.1E archive (proghand.pdf).

It is very useful to have the Progress 4GL Reference manual open while reading. This allows you to quickly read in more depth about specific language statements, built-in functions or other features.

4. Write test code to ensure that you have a valid understanding of the language. You will be provided with credentials for access to a customer's 4GL development system, where you can interact with Progress 4GL directly. Don't spend too much time on any particular topic as the idea is just for you to be able to read and write basic programs in the 4GL language. If you need to write code before you have these credentials, you can write code and use P2J (get the code) to convert and run these programs. It is important that you don't use any 4GL features that are unsupported by P2J, but for the basics it should work well.

Please ask questions early and often. Your team leader can help. Or if you have experienced P2J developers at your location, they can be invaluable. The Progress 4GL is strange, proprietary, inconsistent and archaic. It has many quirks and rough edges. It doesn't always make sense. Ask questions to speed the process by which you properly understand the language.

Obtaining the P2J Code

The P2J code is stored/managed in Bazaar. There is a subdirectory in /opt/code/ on filesrv01 which contains the project. Assuming that you have the Bazaar repository directory attached via sshfs as ~/repo/, the latest version of P2J can be checked out of Bazaar using this command:

bzr checkout ~/repo/p2j_repo/p2j

This will create a p2j/ subdirectory under the current directory. You can build it using:

cd p2j && ant all

If you have been instructed to obtain a different version of P2J (using a specific tag), then you can use this:

bzr checkout -r THE_TAG_TO_CHECKOUT ~/repo/p2j_repo/p2j

Obtaining the P2J Documentation

The P2J documentation is stored/managed in Bazaar. There are two subdirectories in /opt/code/ on filesrv01 which contain projects. Assuming that you have the Bazaar repository directory attached via sshfs as ~/repo/, you would see the following:

Path	Purpose
`~/repo/p2j_books/conversion_handbook/`	Describes how to setup a P2J conversion project for an application, how to configure/customize it and how to run the conversion.
`~/repo/p2j_books/conversion_reference/`	Provides a complete and comprehensive mapping of the Progress 4GL code that can be converted and its converted Java result.
`~/repo/p2j_books/developer_guide/`	Describes the P2J project from a developer's perspective. It also provides guidelines, tips and techniques for the future development of converted applications.
`~/repo/p2j_books/runtime_installation_configuration_and_administration_guide/`	Details on how to install, configure and administer converted applications and the P2J runtime.
`~/repo/p2j_books/templates/`	The LibreOffice book chapter template.
`~/repo/p2j_training/developer1/`	Class slides for the Developer 1 class (the basics of how to manage and develop an application post-conversion).

To check out one of the above projects:

bzr checkout <project_path>

Generally, there is a PDF in each directory that represents a recent "build" of the book. It may not be fully up to date, but it usually is good enough.

Learning About P2J

P2J is a very complex technology that has 2 "sides": conversion and runtime. The conversion is an automated process of language to language translation. It has many aspects of compilers, translators, parsers, lexers, preprocessing, tree manipulation. The runtime is the compatibility environment that enables converted Java applications to run as a drop-in replacement to the original 4GL. This is a custom application server and clients that have extensive libraries for compatibility. The ramp-up time for these different and complicated technologies is non-trivial. The following is a list of the steps in that ramp-up:

1. Review these links on the external Golden Code website:

http://www.goldencode.com/services/prog4gl/p2j/tech/conversion.html
http://www.goldencode.com/services/prog4gl/p2j/tech/runtime.html

It also makes sense to review the rest of the pages related to this services offering, especially the FAQs:

http://www.goldencode.com/services/prog4gl/p2j/faq/process.html
http://www.goldencode.com/services/prog4gl/p2j/faq/runtime.html

Then send a detailed list of questions to your team leader based on this review.

2. Read the P2J Developer Guide (found in bzr at ~/repo/p2j_books/developer_guide/).

3. Read the P2J Conversion Handbook (found in bzr at ~/repo/p2j_books/conversion_handbook/). The entire book is pretty useful, but there are parts that are more oriented as reference materials. Those parts can be skimmed to just get the idea.

4. Read Part 2 of the P2J Conversion Reference (found in bzr at ~/repo/p2j_books/conversion_reference/). Skim the rest of the book to get an idea of what else is there. This is very good reference material.

5. DO NOT bother using the p2j_project_guide.html in the root of the p2j project. It is far out of date. The P2J books listed above are the better resource.

6. Review the package.html document in the following packages of the P2J project:

For conversion/TRPL:

com/goldencode/p2j/pattern/package.html com/goldencode/expr/package.html
For the runtime:

com/goldencode/p2j/security/package.html com/goldencode/p2j/net/package.html com/goldencode/p2j/directory/package.html

7. Review the classes/interfaces in the following packages to get a better understanding of the runtime code:

com/goldencode/p2j/main/ (this includes the bootstrapping code for both the application server and the clients)
com/goldencode/p2j/util/ (most of the base language 4GL compatibility stuff is here including the data types and the block/transaction processing)
com/goldencode/p2j/persist/ (database layer)
com/goldencode/p2j/ui/ (user-interface layer)

Ask LOTS of QUESTIONS of your team leader!!!