APPX 6.1 (and greater) Upgrade Instructions

This page provides the information needed to upgrade an existing APPX 5.4.5 (or higher) installation to APPX 6.1 and 6.2

Overview

Release 6.1 (and greater) has significant changes to the format & content of the System Administration files and Application Design files. As a result, these files must be migrated to the new format. A migration utility for the System Admin (6SA) and Application Design (6AD) is provided. You should install this in your Release 5.4.x or 5.5.x installation (5.5.1 is recommended).

This application requires Release 5.4.5 or higher (5.5.1 is recommended), it will not run on earlier releases. Also note that Locked applications cannot be migrated, they must be unlocked, migrated and then re-locked in 6.1.

As part of the upgrade, you may need to export your data in CSV format. APPX 5.x has some known bugs in CSV export module (#4766,#4814). There is a patch for APPX version 5.5.1 that resolves these issues. It is recommended to run the conversion utilities under release 5.5.1 with the patch installed to avoid these CSV export problems. You can download the patch from here. Please Note that this patch is only tested for the sake of this conversion and has not been thoroughly tested by APPX software to be suitable for production environment.

The Structure files are incompatible between 6.x and all previous releases. After installing 6.1 and migrating your applications, you will have to create new Struct files for all end user data files. This also means you cannot share the APPXIO files between Release 5 & 6. Files that are stored in an RDBMS can be shared if you choose, although this is not recommended.

The basic approach we will use for upgrading is:

1. Install APPX 6.1 (and greater) in a new folder as if it was a new installation
2. Install the migration applications in your existing 5.4.x or 5.5.x installation
3. Run the migration utility for your System Administration files
4. Install the migrated System Admin files in your new 6.1 installation & confirm all is well
5. Run the migration utility for your applications
6. Install the migrated applications
7. Convert 0DX data files (optional)
8. Copy the end user data to Release 6.1 (and greater)
9. Make any required changes to your applications

This approach allows you to maintain your existing 5.x installation while migrating/installing Release 6.1 (and greater). You can test Release 6.1 (and greater) independently of your existing 5.x installation. When you are ready to switch you just need to refresh the end user data.

The entire process may take a few hours, depending on the amount of data involved. Users can continue to work with your Release 5.x applications and data while you are migrating, subject to the usual requirement of not copying files that others are actively updating. If you are comfortable with APPX in character mode, we recommend using character mode to run the migration utility for faster conversion.

It is assumed the reader is familiar with APPX System Administration concepts and knows how to define new applications, new databases, etc. It is also assumed the reader knows how to copy files, set/check permissions, etc.

1. Install APPX 6.1 (and greater) in a new folder

Install a fresh copy of APPX in a new folder on your server. Refer to APPX600LinuxNewInstallation for Linux/Unix servers and APPX600WindowsNewInstallation for Windows servers. If you are using APPX_MONITOR_KEY, this must be set to a different value than your 5.x installation.

2. Install the Migration Applications in Release 5.x

There are 2 migration applications: 6SA for the System Administration files, and 6AD for Application Design files. Download the Migration Utility to a temporary location on the APPX server and follow these steps:

1. Add application 6SA/00 to your Applications file.
2. Create the Design Files for 6SA/00.
3. Add application 6AD/00 to your Application file.
4. Create the Design Files for 6AD/00.
5. Define Database 6SA, with a startup application of 6SA/00.
6. Define Database 6AD, with a startup application of 6AD/00.
7. Download and install the conversion applications.
   1. Now you are ready to install the applications from the downloaded file. The applications are supplied in a zip file format (Intel based systems) or tar format (RISC based systems). Save this file in your $APPXPATH/00/ folder, and extract from there. When prompted, replace all existing files. If you do not get this warning, you may have extracted the file in the wrong location. On Window's you'll probably get an overwrite warning, but on Unix/Linux, TAR probably won't provide a warning. So make sure you've got the applications unbundled into the correct location so that you end up with $APPXPATH/00/6SA and $APPXPATH/00/6AD/. Once the applications are extracted, continue with the next steps.
8. Change the FMS Type of Data Files in 6SA Application to Type 1.
9. Create Data Files for Database 6SA, Application 6SA
10. Change the FMS Type of Data Files in 6AD Application to Type 1.
11. Create Data Files for Database 6AD, Application 6AD

You are now ready to migrate your System Administration files.

3. Run the migration utility for your System Administration files

Before migrating your System Admin files, you should verify the integrity of the files and correct any errors. The Verify step can be found in System Administration -> System Setup -> System Administration File Management -> Verify Files. Correct any errors before proceeding. Also, if you have any startup hooks (such as SESSION START), disable them temporarily. You can re-enable them after you migrated System Administration files.

Continue by running Database 6SA from the APPX Main Menu. You will see this menu:

Click the 'Convert' button to proceed. A report will be produced showing the files that were converted. If any errors are shown, fix them before continuing.

The conversion step creates a new set of System Administration files in Release 6.1 format. These are located in $APPXPATH/6SA/6SA/Data.

Enable any hook record (in your 5.x release) you disabled during this process.

4. Install the migrated System Admin files in your new 6.1 (and greater) installation

You are now ready to install the new System Administration files in your Release 6.1 folder. Follow these steps:

1. Make sure no Release 6.1 APPX sessions are running. In particular, make sure to terminate the License Server if it's running.
2. Copy the contents of this folder {$APPX_5.x_DATA_PATH}/6SA/6SA/Data/ to {$APPX_6.1_DATA_PATH}/0SA/Data/ folder. Do NOT copy the Struct folder.
3. Check permissions of {$APPX_6.1_DATA_PATH}/0SA/Data in your Release 6.1 installation to make sure APPX users have read/write access.
4. Delete these specific .key files in {$APPX_6.1_DATA_PATH}/0SA/Data:
   • EDITMSG.key
   • SCJOB.key
   • SCPROJ.key
   • SCSTE.key
   • SCTASK.key
   • SECDEPT.key
   • SECROLE.key
   • SECWG.key
5. If your operating system does not have en_US.utf8 locale or you are using a different locale by overriding LANG environment variable, you must recreate the key files for DICTNARY and TOKEN files for all your applications. To do that, go to System Administration -> Database/Applications -> Design File Management -> Leave the application blank and set the version to 00 then go to "File Selection". Select all Token files by clicking on "Select" and setting the file name to "TOKEN" (To select all TOKEN files from all applications under version 00, only fill in the file name). Go back and click on "Rebuild Key Files". Do this for "DICTNARY" as well.
6. Log on to APPX 6.1, go to System Administration -> System Setup -> System Administration File Management and run 'Create Files'. This will create new .key files for the ones you just deleted. This is necessary because the keys in those files contain Unicode fields. Release 5.x cannot create a Unicode aware key file, so we must recreate it under 6.1
7. Finally, compare your Release 5.x 'appx.env' file to your Release 6.1 (and greater) 'appx.env' file, and add any necessary settings to the Release 6.1 (and greater) version. Do not simply copy your Release 5.x file to 6.1 (and greater), as you will lose some Release 6.1 (and greater) settings. This is a good time to review these settings to see if they are still required. If you are not sure what a setting is used for, use the Environment Variable Wizard to check it.

If you changed your 'appx.env' file, log off & on again. Check your System Administration files to make sure everything was migrated correctly, i.e., Users, Printers, Forms, Applications, Databases, etc.

Role Based Security: If you are using Role Based Security, you should copy it to your new 6.1 installation. Copy all the files in $APPXPATH/0SA/ACL to $APPXPATH/0SA/ACL in your Release 6.1 installation. Create the $APPXPATH/0SA/ACL folder if necessary. Since the Structure files are different between 5 & 6, we must delete all the 'Struct' folders in $APPXPATH/0SA/ACL in the Release 6.1 folder after the copy is complete. They will get recreated when the applications are migrated.

If all is well, continue with migrating your Applications.

5. Run the migration utility for your applications

You are now ready to begin migrating your applications. This is a good time to review your applications and decide which ones need to be migrated. For example, it's possible you have old applications that are not used any longer.

Once you have decided which applications you will migrate, you should run 'Verify Files' on each application and address any errors.

When you are ready to proceed, run Database 6AD from the version 5.x main APPX menu:

The path shown will be different on your system. You can choose a different path by clicking 'Edit ConversionResults Pathname'.

When you are satisfied with the location, click 'Select Applications and Convert':

On this screen you can enter individual Application/Versions, or you can use the 'Load All Apps for Specific Version' button to automatically load all the applications for the entered version.

When you are ready to proceed, click the 'Process' button.

The conversion utility does some preliminary checks on your applications and tries to detect ILF statements that may be incompatible with release 6.x of APPX. You can either fix those issues in APPX 5.x and run the conversion again, or you can fix them in release 6.x of APPX after the conversion has been done.

The applications will be processed and a report produced showing the applications and files that were processed. Check the report for any error messages. Note that not every application uses all possible design files, so the 'FI_STRUCT_NOT_FOUND' message is not necessarily an error.

It is not necessary to convert all your applications at once. For example, if you have a test version and a test database, you may want to just migrate those initially.

When this step completes, you can proceed to installing the migrated applications in Release 6.1 (and greater).

6. Install the migrated applications

To install the migrated applications, simply copy the folder(s) from the 'ConversionResults' path to $APPXPATH in Release 6.1.

For example, let's assume our conversion results path was R:\appx\data\ConversionResults. We converted 2 applications, both in version GA. The migrated applications will be in R:\appx\data\ConversionResults\GA. Our Release 6 version is installed in R:\appx600new\, so I would copy (or move) the 'GA' folder to 'R:\appx600new\data'. If I converted more than one version at a time, there would be multiple folders in the conversion results folder, and they would all be copied/moved to $APPXPATH in Release 6.1.

The migration tool does not create the structure files or process the Data Dictionary. This must be done in Release 6.1 for every application.

The easiest way to do this is to go to 'System Administration' -> 'Database/Applications' -> 'Design File Management' and select the version of your converted applications (leave the application ID blank). Run 'Create Files', then 'Process Data Dictionary' from 'Design File Management' screen. Repeat this for each version you migrated. You can also go through this for each specific migrated application.

If your operating system does not have en_US.utf8 locale or you are using a different locale by overriding LANG environment variable, you must recreate the key files for DICTNARY and TOKEN file for all your applications. To do that, go to System Administration -> Database/Applications -> Design File Management -> Leave the application blank and set the version to your application's version then go to File Selection. Select all Token files by clicking on "Select" and just setting the file name to "TOKEN". Go back and click on "Rebuild Key Files". Do this for "DICTNARY" file as well. Repeat this for all versions of your applications.

7. Convert 0DX Data Files (Optional)

If your application uses 0DX map definitions, you need to convert those to release 6.x format. If you don't use 0DX or you don't have any map definitions in 0DX application, you can skip this step. A quick way to find out if your application has any map definitions is to verify the 0DX files under all databases (by leaving the database blank). If you see any of the 0DX files have any records in them, you need to do this step.

To convert your map definitions, you need to follow the following steps:

1. In APPX 5.x, export your 0DX files to CSV format. You have to do this for each database that has map definitions.

2. In APPX 6.x, go to Database Management and run Create Files for 0DX for each Database that you are using 0DX

3. Still in APPX 6.x, Go to Application Design and run 0DX-00 CONVERT 5.X DATA FILES job. Leave the database blank. You can do this step from Application Design menu of any application, for example 1EX 00, or DMO 00 work just fine.

3. Still in APPX 6.x, enter the path to 3 0DX exported CSV files which you created on step 1 and the database you want to import the data under, then click on the "Continue" button.

You will get a report that summarizes the conversion. If the report generates an error similar to "Error *: MAPDEF file open failed" then inside APPX 6.x, go to Database Management and run Create Files for 0DX for each Database that you are using 0DX. ( go back to step 7.2 above )

8. Copy the end user data to Release 6.1 (and greater)

Next, we must copy the end user data to our Release 6.1 (and greater) installation. As mentioned previously, the Structure files are completely different between Release 5.x and Release 6.1 (and greater), so we must create new Structure files in Release 6.1.

Make sure to exclude 0DX data files from this step since they are already converted in previous step.

FMS Type 9 files (APPX large file format) have changed on release 6.1 (and greater). If you are using FMS Type 9 in your APPX 5.x version, you need to export them under release 5.x and then import them to APPX release 6.x.

If you are using an FMS group to redirect APPXIO files from their standard location, then you will have to change the Release 6.1 (and greater) FMS group to point to a different location, otherwise Release 5.x & Release 6.1 will be accessing the same Structure files and that will not work.

If you are using an FMS group to point to an RDBMS it will technically work, since each release of APPX has its own Structure files but this is not recommended. Instead, change the FMS group in Release 6.1 (and greater) so that its files are unique. For example, you could add a prefix to the table naming scheme and then use the RDBMS utilities to copy the existing data to the new naming scheme.

Do not copy the 'Struct' folders, or alternatively, delete them after copying. For example, to copy database '123', we would copy all the files in R:\appx\data\123 to R:\appx600\data\123. After the copy is complete, we would delete all the Struct folders in R:\appx600\data\123.

To create the new Structure files, we have to run 'Create Files' for each application in the database. The easiest way to do this is to go to 'Databases/Applications' in System Administration, choose the Database, then click 'Related Applications'. For each application in the list, click 'Database Management', then 'Create Files.

Recommended Step: We recommend changing all of your APPXIO FMS type 1 files to FMS type 9 to take advantage of large file length and new large record length (up to 4MB). Converting an alpha field to a Unicode field requires 4 times more space. Using FMS type 9 can accommodate the need for larger record length and file length easily. You can use "Change FMS" option under "File Management" Menu to do this.

Enable any hook record (in your 6.1 release) you disabled during System Admin file migration.

Once this step is complete, you should be able to run your applications under Release 6.1, subject to the application issues in the next section.

9. Make any required changes to your applications

There are some differences in Release 6 that may have an impact on your applications.

1. All --- TEMP fields are now Unicode fields. If you are using --- TEMP to interface with external programs or O/S level subroutines, this may have an impact if they not expecting to receive UTF-32 encoded data. Also, CNV BIN on a --- TEMP 2 or ---TEMP 4 no longer works since those fields are larger than 4 bytes in size (in this case APPX will give you compilation error during Em build). A number of --- WORK RAW xx fields have been added - you can use these in place of --- TEMP fields if you need a non Unicode field.

2. --- STREAM BUFFER field is also converted to Unicode. STREAM functions are reading and writing data in utf8 encoding unless the mode is specified as binary.

3. Older subroutines in 0LA have various issues:

• FIND STRING LENGTH - limited to strings of 32k
• INSERT STRING - limited to strings of 32k
• REMOVE STRING - limited to strings of 32k

You should use the newer .TEXT routines for string functions.

4. Any direct CALL statements to engine ,RT functions will have to be reviewed and possibly changed.

5. A group field containing a Unicode field can only be moved to or from another group field. A Unicode field cannot be moved to or from a Group. This is detected at compile time so you can batch compile your applications to find these errors.

6. APPX now uses a LF character (ASCII 10) instead of a ¶ (ASCII 182) as a line feed character in text fields. Existing text data will display the ¶ character instead of a new line. To correct this, you need to search any text fields for a ¶ and replace it with a LF character. If you were already using APPX_END_PARAGRAPH to set the line feed to 0x10, this is no longer necessary as your data is already using a LF.

7. Field Type of fields that are storing pointer values have been changed from Numeric (binary) to ALPHA(8). Most of these fields are used internally and you shouldn't worry about them if you have not used them in your application. Here are the list of pointer fields in APPX:

• 0AD IMGEDIT INT ADDR
• 0AD SEGEN SE POINTER
• 0DB MIGRATE PORT STREAM
• 0LA ILF STACK DETACHED
• 0LA ILF STACK PRIVATE
• 0LA ILF STACK RELATED
• 0LA ILF STACK SUBPROCESS
• 0LA PRNTOPT CTL
• 0LA SCANCTX CFI
• 0LA SCANCTX CTL ARB
• 0LA SCANCTX MARB
• 0LA SCANCTX SARB
• 0LA SCANCTX TAG ARB
• 0LA SCANINFO NEXT REC
• 0LA SCANINFO PCB
• 0LA SCANINFO PREV REC
• 0LA SCANOPT CTL
• 0LA STACK PCB POINTER
• 0LA STREAM FILE POINTER
• 0LA STREAMS FILE POINTER

8. 0LA RETURN CODE is still a 4 byte binary field. So, you cannot expect to receive an 8 byte pointer (in 64-bit release) in the return code field.

9. Regular Expression library has changed to support Unicode characters. The new library doesn't like blank or unescaped patterns. You will get a run-time error if it doesn't like the pattern.

10. As the result of the fix for bugs #799, #2498, and #4792, the way APPX finds a subroutine called by a GOSUB statement has changed. If you received "Duplicate Label" or "Could Not Compile GOSUB" error during em creation, it is because you called a subroutine without specifying an application id or called an internal subroutine (a subroutine within another subroutine) with an application id. We recommend making changes to your application to fix these errors, however, you can set APPX_USE_PRE_61_GOSUB environment variable to revert back to old behavior.

11. 0DX RAWXML, RAWXMLAT, and XELEMENT file structures have been changed to support Unicode characters. All Attribute Names, Element Names, and Values have been converted to Unicode fields.

Comments:

Read what other users have said about this page or add your own comments.

---

-- Jean Neron - 2018-02-15