1. Install OpenEdge products

OpenEdge offers development and production licenses for PAS for OpenEdge. For staging a production configuration, install the production license which implements stronger security and limits external management of your server instances.

If you are less familiar with the OpenEdge installation process, see Install OpenEdge

For more information about the differences between development and production instances of PAS for OpenEdge, see About development and production instances.

2. Create a PAS for OpenEdge instance

After installing OpenEdge, use pasman create to create an instance for testing. This instance acts as the staging area for deploying your existing application to a production instance before you move to a live environment. While Windows commands are generally shown here, UNIX has equivalent commands that produce similar results. Notes are included where helpful.

1. Open the Proenv application using the Windows start menu, or by locating it at $DLC/bin/proenv.sh. Proenv sets the environment variables and paths for running OpenEdge commands.
   Note: $DLC is a UNIX-style environment variable syntax for the directory of your Progress installation. On Windows, use %DLC% to go to the Progress installation directory.
2. Change to the OpenEdge working directory ($WRKDIR or %WRKDIR%), which is where your new instance is created and related files and logs are stored. In this example, the directory is called WRK:

   proenv>cd %WRKDIR% proenv>cd C:\OpenEdge\WRK

3. Run the pasman create command to create a named instance called myProdInstance:

   pasman.{sh|bat} create -v -p 8817 -P 8818 -m myAdmin:myPwd -Z prod myProdInstance

   In this example, the following options are specified:
   • -v—Specifies verbose console output.
   • -p—TCP port that listens for HTTP messages. This example uses 8817.
   • -P—TCP port that listens for HTTPS messages. This example uses 8818.
   • -m uid:pwd—Username and password combination that replaces the default tomcat:tomcat used by Apache Tomcat. The example uses myAdmin:myPwd for demonstration purposes only.
   • -Z—Identifies security model of the instance. The example uses prod to lock the server with production server security settings. This option disables development accounts and transports by default.
   • instance_pathname—Specifies the absolute path to the directory where instance is created and the instance name. The example uses myProdInstance. If no path is specified, the instance is created in the current directory. In this example, the instance is created in the current and recommended directory, WRK, because no path is specified.
   Note: The pasman command manages and configures PAS instances using a variety of actions. The create action creates a new instance from a template. It takes several mandatory and optional options. For more information about PASMAN options, type pasman help create in the Proenv window, or view Use PASMAN to create an instance.
4. Run pasman test to confirm that the ProtocolHandlers initialize on the port you provided.

   pasman.{sh|bat} test -I myProdInstance

   The pasman test command displays the PAS for OpenEdge environment variables and confirms that the server can initialize.

   

3. Create an oemerge file using the paspropconv utility

Your existing ubroker.properties must be converted to the new openedge.properties format used by PAS for OpenEdge. To complete this step, you can use the ubroker.properties file that supports your classic AppServer application, or the ubroker.properties file included with the exercise files which supports an example classic AppServer application.

OpenEdge provides a migration tool called paspropconv in the $DLC/bin directory of the OpenEdge installation. The paspropconv utility creates a temporary file of changes called ubrokername.oemerge that must be reviewed before merging with the openedge.properties file of the new instance.

1. Ensure that you have access to a ubroker.properties file for your classic AppServer application. For the purposes of this tutorial, move the ubroker.properties file and the contents of the classicAppServerCode directory to the working directory using Proenv. For example:

   move C:\Downloads\classicAppServerCode %WRKDIR%

2. Change to the instance-name/conf directory to run the conversion tool in a location where the configuration files are stored. For example:

   cd %WRKDIR%\myProdInstance\conf

3. Run the paspropconv utility which takes an existing ubroker.properties file as input and creates a merge file with converted properties and recommendations for your new server. This tool is written in Perl and uses double hyphens (--) to run properly. For this example, the classicAppServerCode directory contains existing files from a classic AppServer application:

   paspropconv --ubrokerPropsFile C:\OpenEdge\WRK\classicAppServerCode\ubroker.properties --ubrokerName UBroker.AS.app_customername_prod --pasoeAppName myProdInstance

   Where:

   --ubrokerPropsFile	Path to the existing classic AppServer ubroker.properties file.
   --ubrokerName	Fully qualified name of the broker whose properties you are converting. In this example, UBroker.AS.app_customername_prod.
   --pasoeAppName	Name of the new instance. In this example, myProdInstance.

   The paspropconv utility generates the following files to the current directory (instance-name/conf):

   • myProdInstance.app_customername_prod.oemerge—The merge file for PAS for OpenEdge.
   • app_customername_prod_setenv.bat—The environment file for Windows.
   • app_customername_prod_setenv.sh—The environment file for UNIX.
   • paspropconv.log—The log file for the property conversion.

4. Move the setenv script to the instance-name/bin directory

1. From the directory where you ran the paspropconv utility (for example, instance-name/conf), move the environment variable file for your operating system into the instance-name/bin directory. For example:

   (Windows OS) >move app_customername_prod_setenv.bat ../bin (UNIX OS) >mv app_customername_prod_setenv.sh ../bin

5. Review and update the oemerge file

Review the instance-name.uBrokerName.oemerge file, which is named after the uBrokerName you specified for the conversion. Read each section in the file carefully to understand the changes that will be made to your openedge.properties file.

The uncommented properties at the bottom of the oemerge file are the properties that will be merged into the openedge.properties file for your new instance. Review and update the uncommented properties based on your server configuration. Pay particular attention to the PROPATH entries and the database connections.

5a. Update PROPATH entries in the oemerge file (where required)

Confirm or update the PROPATH entries to point to any additional or shared code locations. Some subdirectories in your PROPATH may point to your old server. Update these entries to point to the locations on your new server, or ensure you have access to the old file locations and they are specified on your PROPATH. In this sample, you will update the PROPATH to point to the location of event procedures on the PAS for OpenEdge instance.

1. The sample myProdInstance.app_customername_prod.oemerge file indicates that the following startup procedures are required:

   sessionShutdownProc=session_shutdown.p sessionStartupProc=session_startup.p

2. If your classic AppServer configuration used a directory called events to store the startup and shutdown procedures, then copy that directory to your new server. For example:

   (Windows OS) proenv>Xcopy /I %WRKDIR%\classicAppServerCode\events %WRKDIR%\myProdInstance\openedge\events (UNIX OS) proenv>cp -avr $WRKDIR/classicAppServerCode/events $WRKDIR/myProdInstance/openedge/events

3. Reference the location of your new events directory in the PROPATH section of your oemerge file, or ensure your new server still has access to the old directory location. For example, append the following entry to your PROPATH in the [AppServer.Agent.app_name] portion of your oemerge file:

   [AppServer.Agent.myProdInstance] PROPATH=${CATALINA_BASE}/openedge,${CATALINA_BASE}/openedge/events, [...]

   Note: The events directory is one entry in a list of many in the PROPATH. Keep the rest of the entries the same, or change them if you have additional locations for your code.
   Note: PAS for OpenEdge does not support accessing the Windows registry. Use environment or Java system variables.

5b. Update database connections in the oemerge file (where required)

You can reference your existing classic AppServer application database by updating your .pf file that connects to the database, or by updating the database connection string directly in your oemerge file under the agentStartupParam property. In this example, you will copy the default OpenEdge database to the working directory and connect to that database using a .pf file.

1. If your existing classic AppServer application uses parameter files (.pf) to connect to a database or initialize other values, then confirm that those files are available to the new server, or change them to point to the correct file location in the agentStartupParam property in [AppServer.SessMgr.app_name]. For example:

   [AppServer.SessMgr.myProdInstance] agentLogEntryTypes=ASPlumbing,DB.Connects agentStartupParam=-T "C:\OpenEdge\WRK\myProdInstance/temp" -pf C:\OpenEdge\WRK\classicAppServerCode\databases.pf

   Note:

   The contents of the .pf file should specify the database connection string. For example:

   -db C:\OpenEdge\WRK\database\sports2020.db -H localhost

   To configure a new database connection using the sample database provided with the OpenEdge installation, follow these steps:

   1. In your work directory, create a directory called database using Proenv. For example:

      cd %WRKDIR% mkdir database

   2. Run the procopy command to copy the sports2020 database from the $DLC directory to the $WRKDIR:

      procopy %DLC%\sports2020.db %WRKDIR%\database\sports2020.db

      Note: Sports2020 is the sample OpenEdge database shipped with OpenEdge 12.
   3. (Optional) Edit the oemerge file to use the Sports2020 database on agent startup:

      [AppServer.SessMgr.myProdInstance] agentStartupParam=-T "${catalina.base}/temp" -db C:\OpenEdge\WRK\database\sports2020

      Note: In the previous example, the databases.pf file points to the same location as the direct database connection string in the agentStartupParam property. You can keep the agentStartupParam assigned to the databases.pf file if it contains the correct path to your database.

6. Merge the changes using the oeprop utility

After generating the oemerge file using the paspropconv utility and tailoring the file to suit your environment, you can merge the properties with the openedge.properties file for your PAS for OpenEdge instance using the oeprop utility.

1. Go to the /bin directory of your PAS for OpenEdge instance. For example:

   cd %WRKDIR%\myProdInstance\bin

2. To apply the changes from your oemerge file, use the oeprop utility to merge the converted properties into the openedge.properties file for your new server. For example:

   oeprop.{sh|bat} -f ..\conf\myProdInstance.app_customername_prod.oemerge

   Note: For more information about the oeprop utility, type oeprop -help in the Proenv window, or see OEPROP.
3. Verify the changes were merged by reviewing the openedge.properties file in the instance-name/conf directory. The following properties (among others) were updated if you used the tutorial files:

   [myProdInstance.ROOT.APSV] adapterEnabled=1 [AppServer.SessMgr.myProdInstance] agentStartupParam=-T "${catalina.base}/temp" pf C:\OpenEdge\WRK\classicAppServerCode\databases.pf [AppServer.Agent.myProdInstance] PROPATH=${CATALINA_BASE}/openedge,${CATALINA_BASE}/openedge/events,${CATALINA_BASE}/webapps/ROOT/WEB-INF/openedge,[. . .] sessionShutdownProc=session_shutdown.p sessionStartupProc=session_startup.p