It is possible to upgrade a local model from an earlier release simply by opening it with the later release. This is often useful for testing purposes, however as described above this is not the recommended approach for a formal release upgrade.
This section includes the following topics:
Before upgrading, see the CA Plex home page at CA Technical Support (http://ca.com/support) for additional information or fixes that may have been made available after this guide was published.
Multiple releases of CA Plex and its generated applications can be installed on the same machine. For example, CA Plex r7.2.1, r7.2, r7.1, r7.0, and r6.1 can be installed and run on the same machine.
It is a good practice to update local models to the group model regularly. Therefore, we recommend that you update the group model and make offline backups of all group and local models before you start the upgrade. Then create new local models (and build files) after upgrading the group model to the new release.
All group models and associated library models must be upgraded at the same time.
Logging in to a group model causes it to be upgraded to CA Plex r7.2.1. Thereafter, once you save the group model, you will not be able to access the model with a previous release. For this reason, it is necessary for all developers in your work group to upgrade to the new release of CA Plex at the same time. Two developers cannot work on the same model simultaneously if they are using different releases of CA Plex.
It is possible to upgrade a local model from an earlier release simply by opening it with the later release. This is often useful for testing purposes, however as described above this is not the recommended approach for a formal release upgrade.
This section explains upgrade requirements related to upgrading from r6.0, r6.1, r7.0, r7.1 and r7.2.
When upgrading from CA Plex r6.0, r6.1, r7.0, r7.1, r7.2 to CA Plex r7.2.1 you do need to regenerate and recompile existing C++ functions.
To better support Windows Vista security requirements and multi-user deployments, the algorithm that the WinC runtime uses to locate and create runtime .INI files has been changed.
Review these changes carefully, especially, if you have developed custom .INI file handling or deploy CA Plex applications in server-based multi-user environments.
In a typical end-user environment, your applications are installed in the Program Files folder including an .ini file. The files in Program Files are read‑only for standard users.
When the Plex WinC application starts, it searches for a writeable .INI file. If the file is not found, a new .INI file is created in the end-user’s personal folder (My Documents on Windows XP, or Documents on Windows Vista). The .INI file is located in a sub-folder with the same name as the executable. For example, MyApp.exe would have the .INI file "My Documents\Myapp\Myapp.ini"
Therefore, in this example, each standard user who runs the application will have their own copy of the application’s .INI file.
The full set of rules is set out below and provides flexibility for other deployment scenarios dependent on the access rights of the user who runs the application:
If a Plex generated executable is called app.exe, then the respective .ini file will be app.ini.
At run time, an application app.exe searches for an app.ini file as follows:
When upgrading to CA Plex r7.2.1, it's not mandatory to regenerate or rebuild existing Java, C# or RPG functions.
Considering Java 1.8 support - you can use 1.8 compiler to regen/rebuild the Java functions.
Considering C#, to use .Net Framework 4.6 across Plex built application and Plex runtime - require regen/rebuild.
The following sections explain the NET Server Runtime upgrade considerations - Version Property.
Unless you have a specific technical reason, the Version property for the .NET listener must be left blank. The value of 600 or 610 must be deleted if it is present.
At CA Plex r7.1, if this property is empty, the default version number from the Plex .NET runtime is taken.
The Version property is provided for backwards compatibility reasons. For example, to use r6.0 WinC clients to connect to the r7.1 version of .NET runtime, you must set this property to 600.
This section explains upgrade requirements related to upgrading from r5.5 (including r5.5 SP1).
Windows functions (WinC and WinNTC) created with CA Plex earlier releases must be recompiled to be compatible with the CA Plex r7.2.1 C++ run‑time system.
A single Windows application cannot contain DLLs created with different releases of CA Plex. CA Plex includes a run-time version check whenever a generated DLL calls another. A run-time error occurs if you attempt to make a call between DLLs created with incompatible releases. In your development environment, you need to rebuild all of your application DLLs when you move from CA Plex r5.5 or earlier up to CA Plex r7.2.
For more information about run-time applications, see the Running Applications Created with Different Versions of CA Plex in the online help.
If you have used the COM Component Import feature, CA recommends that you reimport and regenerate the imported COM packages as part of the release upgrade process. This is due to fixes and improvements to the COM import and wrapper generation processes at this release. You may need to revise the wrapper attributes of the package before it compiles. Note the following:
To avoid these limitations, the following upgrade procedure is recommended:
The above procedure will upgrade the COM package while preserving existing action diagram code.
This section discusses the upgrade requirements for Java functions.
You do not need to regenerate existing Java functions if you are upgrading from r5.5 SP1 (Build 5.5.93).
The CA Plex r7.2.1 Java run time (obrun.jar) is backwards compatible with earlier releases. You can use the new runtime with functions created at r5.5 and previous releases. This enables you to take advantage of fixes and improvements in the new runtime without necessarily upgrading to the full CA Plex r7.2.1.
If you regenerate a Java function at CA Plex r7.2.1, then you must also regenerate all other 5.5-generated functions in the call graph of that Function. This is due to changes in the parameter formats at CA Plex r5.5 SP1 and later. We recommend a full regeneration and recompilation of all Java functions when upgrading from CA Plex r5.5 (Build 5.5.63) or previous releases. This reduces the number of generated classes and identifies any source code objects that need to be modified for compatibility with the new format of generated Java code.
If you want to use the CA Plex r7.2.1 Java run time (obrun.jar) with a CA Plex r5.5 Java application, you need to have these settings in your ob600xxx.properties file:
In CA Plex r7.2.1, r7.2, r7.1, r7.0, r6.1, and r6.0, the Java and C# generators generate all Exec SQL statements as prepared statements by default. The SRC SQL statement type SYS triple can be used to indicate source code objects that must not be generated with prepared statements.
Generating prepared statements may improve performance and scalability in cases where the same SQL statement is executed repeatedly. However, the results may also depend on application and DBMS-specific factors. CA recommends benchmarking with different values for SRC SQL statement type SYS for determining the optimum setting in each case.
Also, generating prepared statements assumes that all parameters to the Exec SQL statement correspond to columns in a table. This assumption is not always true because the Exec SQL statement can be used to implement a wide variety of SQL code. The SRC SQL statement type SYS triple can be used to indicate source code objects that should not be generated with prepared statements. When upgrading Java applications from r5.5 or earlier, it may be necessary to add such triples to some source code objects to avoid errors.
This change does not affect Exec SQL usage with C++.
Java applications that target the Oracle database and use optional varchar fields may behave differently after upgrading from r5.5 or earlier. Depending on how the varchar is modeled in Plex, unexpected optimistic locking errors may occur after upgrade. For example:
"Instance of .... changed by another user"
The typical solution is to add FLD null VAL triples to the varchar field where the target value is empty. For more information, search the CA Support Online web site for problem CPLEX 1296.
The Java source code you entered into source code objects in your model may need to be modified. This is because of the changes in the structure of the Java classes created by the generator at CA Plex r5.5 SP1. The source code objects supplied in CA’s pattern libraries (such as the JAVAAPI library) are already modified. Re-extract from the shipped JAVAAPI library before regenerating and compiling with CA Plex r7.2.1.
Problems in Java source code result in an unexpected type error at compile time. For example:
C:\GENJAVA\MyFunction_ObFnc.java:line number: unexpected type
required: variable found : value
To fix such problems use the assign method instead of the = operator.
Prior to r5.5 SP1, you could use the operator = to assign the return value of a method to an output parameter of your source code API. For example:
&(4:) = anyMethod(&(1:), &(2:), &(3:));
From r5.5 SP1 onwards, the code in the previous example needs to be modified to include the assign method instead of the = operator, as follows:
&(4:).assign(anyMethod(&(1:), &(2:), &(3:)));
The registry keys for the CA Plex Windows Application Server environment settings have changed because of the rebranding from Advantage to AllFusion.
The CA Plex r7.2.1 installation program automatically copies pre-existing environment settings to the new key values. However, if you do not see the copied settings in the CA Plex Windows Application Environment Manager, execute the migration2.exe program (in the AppServer\Bin folder).
Note: No parameters are required to execute the migration program.
You do not need to regenerate or rebuild existing RPG functions when upgrading to CA Plex r7.2.1.
As discussed earlier, it is recommended that you create new local models, and therefore new build files as part of the upgrade process. If you use an old BLD file with CA Plex r7.2.1, CA Plex sends an error message (E-BLD-1777) each time you open the Generate and Build window. If you want to continue using the old BLD, review your Generate and Build Options to ensure they are compatible with CA Plex r7.2.1.
Pre 7.0 build files will cause the Build Directories section of the Generate and Build Options to be displayed using the AS/400 brand name instead of System i.
To prevent the error message being displayed you can add the following entry to the BLD file:
The Name Allocation option called Truncate Long File Names at Generation is no longer switched on by default. This means that the file names longer than 8 characters will no longer be truncated unless you explicitly select this option. This may have an upgrade impact if your model contains names that were truncated at previous releases.
The following sections provides the upgrade requirements related to upgrading from r5.1
At r5.0 of CA Plex, the inheritance engine was changed to address limitations and bugs in inheritance behavior. Additional changes were also made to support the new Dependency Browser in r5.0. For some customers, these changes caused significant problems when the time came to upgrade to the new release. CA Plex r5.1 included some fixes for these problems, but some significant problems remained.
CA Plex r5.5 resolves the known bugs in the inheritance engine. No changes were made to the inheritance engine between r5.5 and r5.5 SP1. There are differences in inheritance engine behavior compared to earlier releases that will impact some customers. In the following sections three different cases are described.
In some cases inherited function calls may be resolved differently in the action diagram with the result that a different call is created in the generated code. In a typical model, this only affects a very small percentage of functions (if any). These cases can be identified through testing of the generated application, comparisons of generated source, or comparisons of action diagram code. If you require further assistance in identifying such problems, contact CA Technical Support.
You can resolve these problems by adding the appropriate replacement triples to return the function to its required behavior. Ideally such triples can be entered in your standards layer model, thus minimizing the amount of changes required.
CA Plex r3.5 introduced support for multiple function inheritance by changing the behavior of the FNC is a FNC verb. As a result, even existing CA Plex functions could inherit from more than one function without keying any extra triples. Another consequence of this was to allow two or more different inherited Calls triples to be Visible in the Object Properties corresponding to the same original action diagram call. Only one call is appropriate in any inheriting action diagram and CA Plex determines which of the available functions should actually be called when it is loaded.
Prior to r5.0, CA Plex did not explicitly handle such action diagram calls. As a result, the resolution of the call did not always follow the usual rules of the inheritance engine. At r5.0 and later a mechanism was put in place to handle such calls. This mechanism has been refined a number of times, most recently at r5.5.
A common example of multiple inherited action diagram call can be seen in instances of the Filter.FilteredGrid function. Consider these triples:
EditDetailFilter is a ENT STORAGE/RelationalTable EditDetailFilter is a ENT FOUNDATI/EditDetail EditDetailFilter is a ENT FOUNDATI/Filter EditDetailFilter.Edit replaces FNC UIBASIC/Grid ...by FNC EditDetailFilter.FilteredGrid
When you look at the calls for the EditDetailFilter.Edit you will see calls to two different BlockFetch functions:
Note that both calls are visible (the Vis column is checked). You can see this same behavior in r5.0 and r5.1. So which BlockFetch is actually called in the action diagram? This determination is made at action diagram load time. The result is sensitive to changes in the inheritance engine in recent CA Plex releases. The intention is that the Filter.BlockFetch should be called. To get this result at r5.5, CA has entered an additional replacement triple on the FOUNDATION pattern library:
FOUNDATI/Filter.FilteredGrid replaces FNC UIBASIC/UIBasic.Grid.BlockFetch ....by FNC FOUNDATI/Filter.Filter.BlockFetch
Previously, the BlockFetch function was not explicitly replaced. Instead the replacement was made only on the scoping view:
FOUNDATI/Filter.FilteredGrid replaces VW UIBASIC/UIBasic.Grid ...by VW FOUNDATI/Filter.Filter
With the revised algorithm used in CA Plex r5.5, this was not sufficient to force the required function replacement to occur. By adding an additional, explicit replacement on the BlockFetch itself, CA has been able to retain the required behavior in r5.5. Similar actions may be necessary in your own functions that exhibit this behavior.
Consider the following set of triples:
This type of scenario is known as diamond inheritance due to the shape of the resulting inheritance hierarchy as follows.
The inheritance hierarchy starts at An Entity, diverges, and then the two branches are brought back together at Our Entity. This situation is quite complex but the examples in real customer models are often even more complex with further branches and layers of inheritance involved.
The only way to determine which function is actually called is to examine the action diagram code. This example again shows the changes in the inheritance engine over recent releases: At r5.0, Our Entity.Your Validation Function is actually called, but in all other releases including r5.5 it is Our Entity.Our Validation.
In some cases the sequence of inherited parameters on a generated function call may change compared to earlier releases. In many cases, such changes have no negative consequences since all functions concerned are regenerated in the course of upgrading to the new release. However, there are cases where such changes may be significant:
These cases can be identified by testing the generated application, comparisons of generated source, or comparisons of action diagram code. If you require further assistance in identifying such problems, contact CA Technical Support.
The sequence of inherited Event constructs and Subroutines can be altered compared to previous releases. Changes to the sequence of Subroutines have no negative consequences for the generated application. In general, this is also true for Event constructs. However, the sequence of Events may be significant if you referenced the same logical event on multiple Event constructs or used an unqualified Event construct. For example:
Events Handler Event //unqualified event triggered for every event Go Sub Generic Event Processing Event Delete Go Sub Delete Processing Event Delete Go Sub More Delete Processing
If the previous sequence of Event constructs is different, then the behavior of the generated application will change. In practice, this functionality is rarely exploited and it is even rarer for the inheritance engine changes to cause significant differences in the sequence. As in other cases, such problems can be identified through testing of the generated application, comparisons of generated source or comparisons of action diagram code.
In principle, similar considerations apply to the sequence of inherited code blocks in Collection Points (Pre and Post Points). Testing by CA has not revealed examples of such results but you should be aware that the possibility exists.
In addition to the upgrade requirements documented in the earlier sections, review the following sections when you are upgrading from r5.0.
In r5.0 and later, CA Plex supports two sets of GUI controls in Windows clients. By default, WinC applications use MFC controls for all types of controls, except the grid. The alternative set of GUI controls is called Winwidgets, which was the default before r5.0.
There are advantages and disadvantages associated with each set of controls. Winwidgets controls have been used in all releases of CA Plex since 1.0. Consequently, they represent a mature technology that has been implemented successfully for many years by many CA Plex customers. When upgrading from an earlier release of CA Plex, it is often simpler to use the Winwidgets controls since this is likely to minimize any backwards compatibility problems.
MFC controls provide a range of advantages including:
With some exceptions (see the following section), all the functionality previously available with Winwidgets controls should also be available with the MFC controls. However, to safeguard against unexpected upgrade issues, run-time options are available that enable you to revert to the Winwidgets controls.
A separate option is available for each type of control:
[NativeControls] ;GUI controls either display as MFC controls (1) or Winwidgets (0). ;These settings have no effect on the WinC grid which is always Winwidgets ListBox=1 SpinButton=1 SingleLineEdit=1 SingleLineEditNumeric=1 MultiLineEdit=1 ComboBox=1 RadioButton=1 CheckBox=1 PushButton=1 Statics=1
Set the required option to 0 if you want to revert the control concerned to Winwidgets. The MultilineEdit setting is an exception -- Setting this value to 0 invokes an earlier implementation of the native control as Winwidgets do not provide a multi-line edit control.
Known upgrade issues are listed below. Report any undocumented upgrade issues to CA Technical Support if they cause a problem in your application.
Disabled text color. When MFC controls are disabled, the text displays in the Windows standard color (typically, light gray). The Text Color property is ignored when controls are disabled. Note that for edit controls you can use the combination of properties
to define a read-only edit control that does support the Text Color property.
As of CA Plex r4.5, when calling Java functions from the command line or from hand-coded Java, the function name must be prefixed with its package (package.func).
Note that at CA Plex r5.0 Service Pack 1 and later, there is a PackageList .properties file entry that can be used to provide a list of packages that are searched if no package is specified within the call. Typically, a function’s package is generated directly into the code for each function call. However, this may not be the case in a dynamic partitioning scenario. For example, at generation time the target of a function call could be a Windows function (in which case no package will be included in the generated call). At run time, if the target function is switched to Java then the PackageList can be used to locate the function.
This section explains upgrade requirements related to r4.5.
CA Plex r5.0 and later includes enhancements to the inheritance engine that may change the properties of inherited objects in some circumstances.
Consider the following example:
A is a B
B is a C
A replaces C by D
When B is a C arrives on A, A no longer inherits from C, as B did, but it now inherits from D.
In previous releases, anything inherited from D, which is in contention with that inherited from B, defers to the version inherited from B. In r5.0, anything contentious inherited from D takes precedence over things from B which arose from its inheritance from C. In other words A is a D takes precedence over A is a B and B is a C. This result is now consistent with the general rules of inheritance, where later triples take precedence over earlier triples.
It is possible to duplicate triples for an object by entering a triple, changing configuration to an earlier level and entering the same property. For example:
A type Character (Level 3)
A type Numeric (Level 1)
With the configuration set to the later level (Level 3 in the example) both triples would show in the Model Editor prior to r5.0 and are passed on to the inheritance engine. The last triple in sequence (as seen in the Model Editor) takes precedence. So in the previous example, A would be Numeric.
In CA Plex r5.0, the later hides earlier principle is applied to the levels and only A type Character is seen in the Model Editor and passed on for inheritance.
At r5.0, a fix was added so that internal RPG functions now have their own meta-variable space, and no longer share the meta-variable space of their calling functions. This change is in accordance with the published functionality regarding the scope of meta-variables (which states that a meta-variable’s state only persists on calls to functions of type Meta) and is consistent with other generators.
This fix highlighted a place within the class libraries where meta-variable state information was expected to pass from an external function to an internal function. It was calling the OBASE/Set current date and time function in the OBASE variants AS400 5250 and Windows/AS400.
To assist customers in tackling any upgrade issues associated with this fix, the following Plex.ini file option can be used in CA Plex r5.1:
[RPG Generator] Share Meta-Variables With Internal Functions=1
An entry of 1 reverts to pre-r5.0 behavior. If no entry is present, the default setting of 0 is used, providing the same behavior as r5.0.
The Java Generator at CA Plex r4.5 and earlier required two single quote characters ('') to be used in messages and source code and required a single quote to be used at run time. For example, this was required when embedding parameters in the source code for use with the Exec SQL statement. This behavior was inconsistent with other generators.
This problem was corrected in CA Plex r5.0. Now only a single quote character (') is required. However, any existing messages or source code that used the previous workaround need to be edited when upgrading to r5.0.
The Java Generator at CA Plex r4.5 and earlier required that two backslash characters (\\) be used in values whenever you required a single backslash character to be used at run time. This behavior was inconsistent with other generators.
This problem was corrected in CA Plex r5.0. Now only a single backslash character (\) is required. However, any existing values using the previous workaround will need to be edited when upgrading to r5.0.
This section explains upgrade requirements related to r4.0.
CA Plex r4.5 introduced a change to the resolution of replacement triples attached to scoping objects to provide better control over replacement and performance improvements. This fix is not enabled by default. It requires a setting to be added to the Plex.ini file because it can cause significant backwards compatibility issues when it is enabled. For a full discussion, search the online help for the topic Replacement and scoped objects.
In addition to the instructions in Upgrading from CA Plex r4.0, review the following sections.
In r4.0, the behavior of the For Update option on Position and Fetch action diagram statements was changed to support pessimistic concurrency. It is possible that these changes may significantly change the behavior of ODBC-based applications (including NT BackOffice applications). For more information about backwards compatibility options, see the topic Row Locking in SQL Implementations in the online help.
The documented behavior of the CONCAT operator is that trailing blanks are removed from field values. In practice, it was possible to retain trailing blanks in C++ functions in cases where the values concerned were not displayed on panels. This inconsistency was corrected in CA Plex r4.0 in that trailing blanks are now removed in all cases. The recommended technique for including blanks in concatenated strings is to use the Format Message statement with the blanks embedded in the message.
The YOBDDL program resides within the CA Plex library on the System i. When building the System i Field Values File within CA Plex, a copy of the YOBDDL program is created in the System i Object Library. This copy is called YOBVALSV. A copy is not made if YOBVALSV already exists.
The YOBDDL program was modified for r4.0 of CA Plex. For this reason, the old versions of YOBVALSV need to be deleted from each of your System i Object Libraries. Enter the following command on the System i:
The new version of YOBVALSV needs to be placed in to each of the System i Object Libraries. This can be done by either:
Failure to perform these steps results in a level-check at run time when attempting to access the field values selection list.
If you have used the GetLocationInformation and SetLocationInformation APIs, note that the structure ObLocationInfo was changed for CA Plex r4.0. If you have created source code objects that implement these APIs, you must edit the code to avoid compile errors.
The following three fields are removed:
ObLongFld m_fDataConvObLongFld m_fObTranObCharFld m_ObTranDLL
and replaced with the following single field:
See the Odap.mdl sample model for examples of the required source code.
CA Plex r4.0 introduced a new feature called custom C++ build options. The linker option /OPT:NOWIN98 is used by default. Without this option the size of compiled DLLs is significantly increased. If your local model was created before r4.0 of CA Plex, this option does not appear by default and should be added manually. For more information, see the online help topic Customizing C++ Builds.
The source code required to load the run-time property DLL was changed in CA Plex r4.0. If your application uses the SetProperty API, change the source code that loads the run-time property DLL, as follows:
#ifdef _DEBUG ObPropertyAPI::SetValue(Ob600Prpd.dll, OB_ATOM_ATOM_INSTALL, 0, 0) #else ObPropertyAPI::SetValue(Ob600Prp.dll, OB_ATOM_ATOM_INSTALL, 0, 0) #endif
The functions with panels were moved from the container Services to the container UI in CA Plex r4.0. If you have previously used one of these patterns in CA Plex r3.5, you must rescope some of these functions inherited from that pattern. After extracting from the new version of the library, you can see your existing panel functions in the Object Browser under Services as real (in yellow), and new functions with the same names under UI (not yet real, in gray). Rescope the existing panel functions by dragging them from the Services function and dropping them onto the UI function. (Note that the UI function must be made real before doing this.)
In addition to the instructions in Upgrading from CA Plex r4.0 and Upgrading from CA Plex r3.5, note that CA Plex r3.1 was the last release of CA Plex that supported the creation of 16-bit Windows applications.
You cannot upgrade CA Plex 2.51 or earlier without first upgrading to CA Plex r3.0. Follow the upgrade instructions published with CA Plex r3.0.