| Upgrade Guide | |
This chapter only discusses issues that pertain to upgrading screens in JAM 5 applications to Panther.
To further upgrade your application to Panther, refer to Chapter 1, "Upgrading to Panther from JAM 7."
To upgrade your reports to ReportWriter 7, refer to page 1-52.
Upgrading From JAM 5 |  |
Although Panther differs considerably in its appearance from JAM 5, in its underlying functionality it remains closely related to JAM 5. The most obvious change is that JAM's interface has moved from a character to a graphical orientation. This is most evident in the graphical editor and in the more object-oriented terminology used throughout the product. This document discusses how to upgrade your applications from JAM 5 to Panther.
Warning: Be sure to back up your JAM 5 application before you start to upgrade it.
Upgrade Paths | |
There are three potential paths to follow when upgrading a JAM 5 application:
These three paths are listed in ascending order of difficulty and effectiveness. Each path encompasses the previous one, but takes it several steps further.
Migration is the fastest and most direct way to get up and running with Panther. Migration means that your application remains virtually the same and runs with JAM 5 compatibility in the Panther environment. Once migrated, you can immediately begin to use the features of Panther to extend and modify your application. Although this compatibility will eventually be phased out of future releases, using it may buy you the time you need to plan a proper conversion. Experience has proven that migration works best for character-based applications, since graphical applications present more challenging issues. If you used JAM/Pi to build your application, then migration is not recommended.
Conversion is potentially a more complicated process than migration. Its goal is to map your application's functionality into Panther constructs without altering it too much. A suite of conversion utilities, including a screen conversion utility, \f5upg, are provided to perform the bulk of this mapping. Once again, character applications convert more easily than graphical applications, but the utility does use a series of heuristics in an attempt to map JAM/Pi constructs into Panther. The reason that graphical applications take more work to convert is that JAM/Pi has undergone an extensive reworking as it was folded into Panther. The appearance of your graphical application after conversion will most likely be different than it was before, so you should examine each screen carefully and manually adjust them as necessary.
Finally, you might want to fully upgrade your application to Panther. Here, your application must be extensively modified to take full advantage of the advanced features provided in Panther. At this time, fully upgrading an application is a manual process.
The best way to decide which path to follow is to read through the rest of this chapter, keeping in mind the specifics of your application and the upgrade options available. We first cover the steps that are common to all upgrade paths, and then branch into some of the more advanced upgrade steps.
Upgrading the Operating Environment | |
First of all, there are several steps common to each of the methods. These steps must be performed for all upgrades.
Panther is distributed with new configuration files. If you modified any of these files in previous releases, you must reevaluate and transfer the changes into the new environment. You can edit the ASCII version of these files directly.
Once you have made your changes, be sure to convert the file to binary using the appropriate Panther utility:
Table 4-1 shows the setup variables from JAM 4 that are no longer supported in Panther. References to these variables should be removed from your setup and configuration files.
Be sure that your environment is pointing to the correct Panther configuration. This usually involves changing your SMVARS environment variable.
The Motif XJam file and the Windows ini file should be updated just like the configuration files. Any changes that you made to these files should be reevaluated and transferred to the Panther versions.
Support for color aliases has now moved from the GUI resource and initialization files to the JAM configuration map file, clrcmap. Any color aliases that you added should therefore be moved to the configuration map file. Remember to use the utility cmap2bin to convert this file to binary format.
While the format of most configuration files has not changed, an important exception is the Data Dictionary. In fact, both its role and its name have changed. Panther uses this file as a development tool; a repository of reusable widget definitions, stored in JAM library format. It is no longer used to create the runtime Local Data Block (LDB). You must use the dd5upg utility to convert your Data Dictionary to a repository. If your application relies on the LDB, use dd5upg -l to create a Panther library (ldb.lib) which is automatically loaded into the LDB at runtime. For details on using dd5upg, refer to "The dd5upg Utility".
Panther no longer supports LDB initialization through ini files. We do however provide sample code that you can use to mimic JAM 5 behavior. You must choose whether to convert over to the new Panther conventions or simply link in the sample code.
An LDB in Panther is simply a library of screens. Panther performs initialization by either setting the initial text of the LDB widgets or by explicitly placing values into them through JPL statements. The sample code we provide, sm5ldb.c, enables ini files to work as they did in JAM 5, providing near seamless compatibility. Similar support is available for LDB scopes, Form structures, Data Dictionary records, and the old menu bar API.
Any changes that you made to the main routines in JAM 5, jmain.c and jxmain.c, should be reevaluated and transferred to the main routines provided with Panther. One way to locate these changes is to compare the distributed JAM 5 main routines with the JAM 5 main routines that you have been using. Then carry these changes forward to the Panther main routines, if appropriate.
Any functions that you added to the function list file funclist.c must be added to the new Panther funclist.c. You can use the same structure for declaring functions that you used in JAM 5.
In looking at the function list in Panther, you'll notice that it includes prototypes for most of the JAM library functions. These are declared using a macro called SM_INTFNC. If you prototyped any of these functions for use in JAM 5, then you'll want to change these declarations to use the macro SM_OLDFNC instead.
The difference between the two macros is in their use of a new flag that has been added to the intrn_use member of the installation structure. This flag, DEREF_ARGS, allows function arguments to be automatically dereferenced without the need for colon expansion. If you were not in the habit of enclosing arguments in quotes when calling prototyped library functions in JAM 5, then you'll want to declare these library functions without the DEREF_ARGS flag. Declaring them with the SM_OLDFNC macro accomplishes this. SM_OLDFNC, SM_INTFNC, and DEREF_ARGS are all defined in the include file sminstfn.h.
Functions that were supported in JAM 5 for compatibility with JAM 4 are no longer supported. All usage of JAM 4 functions must be updated to use Panther functions. Table 4-2 lists the obsolete JAM 4 functions and their Panther equivalents.
Converting an Application | |
Converting a JAM 5 application to Panther is an iterative process that should be mapped out carefully.
A suite of utilities are provided to aid in converting the various pieces of your application. These are summarized in Table 4-3.
Sample source code is also provided that maps some JAM 5 features and function calls to Panther equivalents at runtime. These are summarized in Table 4-4. Detailed documentation for this code is provided in the source files themselves.
The design and features in your particular application dictate which utilities and source modules are required in your conversion.
As you work to establish a configuration and executable for your application you will undoubtedly notice that some features of JAM 5 are no longer supported in Panther. When this happens you must chose among converting to the new Panther conventions, finding a new approach, or linking in sample code we've provided to mimic the JAM 5 behavior.
As mentioned before, LDB initialization is a prime example of this. Panther supports this directly through the initial text property of an LDB widget. However, an alternative, and perhaps more flexible, approach is to explicitly place values into the widgets through JPL or C statements. Finally you can continue to use the ini files from JAM 5 by linking with the sample code we provide (sm5ldb.c) and calling sm5_ldb_init from your main routine. The choice is yours. Different applications and schedules require different choices.
Once you've built a Panther environment for your application, the next step is getting your screens to operate within it. Here the differences between migration and conversion become apparent.
All JAM 5 screens will execute under Panther without conversion. Panther recognizes that the screen was created in JAM 5 and translates fields, attributes and edits into widgets and properties. Widgets of this type are called "Release 5" widgets. You can expect these widgets for the most part to look and act as they did under JAM 5 control in both character and GUI environments. This is what we call migration, since with some subtle differences, your application remains the same.
The fact is, not everything translates automatically to Panther equivalents, and the appearance of certain fields/groups/messages will change under Panther. Since Panther is much more graphically oriented, you'll notice that many messages now appear in dialog boxes rather than on the status line. In addition, the border surrounding most windows looks slightly different by default. The rules governing the tabbing order between fields and groups have also changed slightly. Most of these differences can be resolved by either editing the screen or setting one or more of the option variables through your SMVARS file or source code provided in sm5init.c.
Users of JAM/Pi will immediately note that none of the extensions to JPL are interpreted by default. Users of JAM/Reportwriter will find likewise. JAM/Pi extensions and Reportwriter scripts have been fully integrated into widget properties for Panther. They can only be activated by passing the screen through the f5upg conversion utility. The utility supports a -5 option which performs these and other minor translations on the screen, avoiding a full conversion of the screen (f5upg can be used to continue the conversion at a later time).
Perhaps the most noticeable difference for GUI users is in widget positioning. The positioning algorithm in Panther places widgets at approximately the same positions they held under JAM/Pi. For both migration and conversion, you will need to closely examine your screens under Panther and, more than likely, touch up the positioning of fields, boxes and lines. In most cases character users are spared this step.
Most users will find that a full conversion to Panther is desirable. The f5upg utility defaults to performing a conversion and has many command line options available to help you in this process. Not all options are required for all screens and, indeed, some options are not desirable at all. We suggest that you look at all the available options and determine a set that most closely represents a conversion path for most of your screens. The remainder will need to be handled on an individual basis. The utility is based on heuristics controlled by command line options, so you may want to assess each screen and try different options.
Unless the -5 switch was used, screens that come out of f5upg consist entirely of Panther widgets. These may have different appearance and behavior than they had in JAM 5. The f5upg utility establishes each widget's type based on the rules established for JAM/Pi. Plan on examining each screen to confirm that the conversion operated as intended and to resolve ambiguities that the utility was unable to handle.
For the most part, you can expect your application to run correctly. With minor exceptions, JAM events, JPL commands and library functions all perform as you remember. There are, however, several issues you may encounter.
As mentioned previously, there is a new function prototyping feature called field dereferencing that may cause your code to malfunction. Using this feature, JAM treats any string not surrounded by quotes as a field name, and attempts to extract a value from it which it then passes to the function being called. If you do not routinely place quotes around individual function arguments you will either need to correct your code or alter all the function prototypes in functlist.c to turn off the dereferencing feature. This can be accomplished by declaring the functions with the SM_OLDFUNC macro instead of INTFNC.
Users of JAM/Pi should recall that widget types routinely changed from label to text and visible to invisible depending on protection settings and content. This behavior is no longer supported by Panther. The easiest way around this change in behavior is to settle on a single type for each widget for the duration of the screen. In lieu of this you'll have to rework your code to manage the display in two overlapping widgets of different types. In addition, you must to explicitly set the hidden property of widgets to get them to disappear, otherwise they merely deactivate.
Another potential issue deals with JAM 5 menus. Menu control strings are now a property of the menu fields themselves and, as a result, the control fields no longer have special meaning. The f5upg utility optionally migrates the content of the control fields to this new property, but if your code routinely reconstructs these fields, it will have to be changed to work with the properties instead. Please note that the old behavior continues to be supported by Release 5 widgets.
Plan on a full regression test of your application. Examine the behavior between and within screens. Undoubtedly you will like some new features and want to incorporate them right away; others you will want to avoid until later. Expect character applications to convert easier than GUI applications. Expect a majority of the code to convert easily, and some to be more difficult. Each application is different and it is important to treat them as such.
The f5upg Utility | |
Panther has an entirely new look and feel to its interface and its screens. This is a natural consequence of the changing computer software market and the rapidly expanding requirements for GUI technology and, even in character mode, applications that are as GUI-like as possible. In order to accommodate this new demand, we have added a significant amount of functionality to JAM and a new conceptual paradigm about JAM objects and their relationships to one another. In many cases, the old JAM 5 world will map with relative ease into the new Panther framework, but in order to bring the product into stricter compliance with GUI standards, there were some unique challenges that may make your upgrade from JAM 5 to Panther a tad more tricky than the JAM upgrades you have performed in the past.
The utility f5upg is designed purely for the purpose of converting JAM 5 screens to Panther screen format. Although Panther can read and process JAM 5 screens, certain JAM 5 features will be obsolete in future versions of the product, so it is strongly recommended that f5upg be used to convert all your JAM 5 screens to Panther.
If you are currently using JAM with a version earlier than 5, you must use the various utilities (f3to5, f4to5, etc.) to convert your screen binaries to JAM 5 format before you can use f5upg. If you use those utilities now or if you have used them in the past, you will notice that there is a rather large difference between those utilities and the f5upg utility.
The reason for this difference is that conversion of JAM screens in earlier versions of the product was a deterministic operation. In other words, there were no conceptual shifts in how JAM dealt with objects from version to version, so the conversion utilities merely had to map one binary representation of a concept into another. For the conversion from JAM 5 to Panther, the process is not strictly deterministic, but must use various heuristics specified by the user as command line options to effect the desired conversions. It is possible that you will need to use different combinations of command line options for different screens in the application you are converting, although in all likelihood most of your screens will be converted the same way.
Although it is possible with f5upg to specify the same file name for input and output and consequently overwrite your JAM 5 input screen binary with a Panther screen binary of the same name, we would strongly recommend that you not use this approach. Keep your JAM 5 screens available for the entire time you are upgrading your application until you are completely satisfied with the conversion. It might be that on looking at a particular converted screen, you could get something more along the lines of what you want by using a different combination of options to control the conversion heuristics.
Even if you did not use it, you should be aware of the product JAM/Pi, or Presentation Interface, which was a layered product in the JAM 5 world and is now fully integrated with JAM in the Panther world. JAM/Pi allowed JAM 5 users to create JAM applications in GUI environments. Much of the complexity of converting JAM 5 screens to Panther arises from the need to convert the JPL extensions used in JAM 5 to specify GUI-specific field and screen attributes to the Panther environment. If you did not use JAM/Pi in JAM 5, much of the remaining part of this document may appear more complicated than necessary.
The utility should be invoked from the command line with the following syntax:
f5upg [-5bcdfklmp] [-g type] [-v num] [-s color] JAM5_screen JAM7_screen
JAM5_screen
JAM7_screen
-5 Leaves fields as release 5 widgets by default.
-b Forces border unless noborder is specified.
-c Converts onscreen control fields to properties.
-d Deletes onscreen control fields.
-f Allows output file to overwrite existing file.
-k Keeps JPL extensions on the output screen.
-l Converts menu arrays to list boxes by default.
-m Converts keyset designations to menu designations.
-p Includes the GUI interface values for the hmargin, vmargin, hbuffer, vbuffer properties in the converted screens.
-s Assumes system colors (or scheme) by default.
-g type Sets graphic conversion type:
N = none (default),
S = simple.
-v num Sets verbosity level. The default is 1.
-s color Determines color conversion method for screens and widgets:
X - For Motif applications, maintain JAM/Pi color scheme.
W - For Windows applications, maintain the JAM/Pi color scheme.
R - Reset colors according to Scheme in the Panther cmap file.
If the option is not used, Windows' applications will convert the colors correctly only if color priority is undefined or not set to system. Colors for Motif applications may differ if the -sX option is not used.
f5upg assumes that the file name arguments are full path names, and treats them as such. There is no attempt to find screens along any particular path. First the utility ensures that the arguments are correct and consistent, then it attempts to find and open the input file as a JAM 5 screen. It then goes through the screen and convert JAM 5 screen and field objects and attributes to Panther screen and widget properties, according to some deterministic rules and a set of heuristics which are controlled by the command line options detailed below. Finally, the output file is written as a Panther screen.
Depending on the verbosity level set, informational status messages are printed to standard output and error messages are printed to standard error, and may be re-directed to log files by the operating system as desired.
When no command line options are set, all JAM 5 display text is converted to Panther Static Label widgets.
Any fields which are in JAM 5 groups are converted as follows:
Any fields unconverted so far are checked for the menu bit.
Any fields still unconverted are checked to see if they are protected from both data entry and tabbing:
All JAM/Pi extensions found in screen JPL modify properties of the screen as specified. All JAM/Pi extensions found in field JPL modify the properties of the resulting widget as specified, including, possibly, the widget type.
The verbosity level is set with the -v command line option. The -v option is followed by a number ranging from zero to three. When 0 is specified, only critical errors are displayed to standard error. Verbosity levels 1, 2, and 3 all provide increasing levels of informational messages about the progress of the conversion, the heuristics being employed, and the use of features which may be rendered obsolete in future versions of JAM. These messages generally scroll to the terminal very fast, so if you need them it is recommended that output be directed to a log file.
By default, the verbosity level is set to 1.
This is only of interest to JAM/Pi users. In that product, boxes and lines could be specified as attributes of a given screen in that screen's JPL with the box, hline, and vline extensions. In Panther, boxes and lines are not attributes of screens, but screen objects in their own right. The -g option controls how these JAM/Pi extensions are converted.
Specifying -gN merely throws away those graphic objects. Depending on the verbosity level, when f5upg encounters the JAM/Pi extension for a box or line in a screen JPL, a message is printed to standard output warning the user that the extension could not be converted. This is the default.
Specifying -gS attempts a simple conversion of those graphic objects. In JAM/Pi, boxes and lines were drawn between grid units on the screen for positioning purposes. In Panther, since these are objects in their own right, they take up grid units. As a result, this simple conversion will likely require subsequent manual manipulation in the editor to properly position the graphic element in question.
By default, f5upg removes any JAM/Pi extensions found in screen or field JPL before writing out the output screen. If the -k command line flag is specified, the utility leaves those extensions there. This does not harm the JPL, since the extensions are treated as comments by the JPL parser, but they really have no use. You should keep them around only if they serve as documentation to you. Most likely, they will just be a source of confusion.
The JPL extensions kept around are modified so that they are not reinterpreted if the target screen is run through f5upg a second time. They are modified so that the first angle bracket in the lead-in to each extension becomes an exclamation point. For example, #<<nominimize>> <<font(myfont)>>becomes#!<nominimize>> !<font(myfont)>>
By default, if the output file specified already exists, f5upg aborts without performing the conversion in question. However, if the -f option is specified, the output file is overwritten if it exists. Note that this means it is possible, in principle, to specify the same path for the input and output files. This is not recommended, however, because you will have lost your JAM 5 source file.
f5upg provides a color option to specify how screen and widget colors will be converted. Depending on your use of the -s option, you can direct color conversion of your screen and widget colors in any of four different ways. The arguments to the color option work as follows:
By default, as mentioned above, JAM 5 menu fields are converted to push buttons. This is not necessarily optimal if your application had menu arrays, in particular scrolling menu arrays. If you specify the -l command line flag, all menu arrays are converted to list boxes rather than push buttons. Any single non-scrolling menu fields (not part of an array) are still converted to push buttons, even if -l is specified. (A non-scrolling list box with one element doesn't make sense).
Please be warned that the way JAM menu fields work means that their conversion to list boxes will likely cause them to operate in a way that is slightly different from most GUI standards. This is why the -l option is not the default behavior.
Note also that if there are JAM/Pi extensions specifying widget type, this option will be overridden for that field.
In JAM 5, screens were created without borders by default. JAM/Pi screens, on the other hand, had borders unless the JAM/Pi extension noborder was set in the screen JPL. JAM/Pi users might, therefore, have created JAM screens without ever giving them borders and enjoyed the experience of the screens with borders nonetheless.
By default f5upg only designates a border for the Panther screen if there was a border specified in the JAM 5 character mode instantiation of the screen. However, if you set the -b command line flag, f5upg gives all screens a border even if the character mode JAM 5 screen did not have one. Only those screens marked as noborder will, in fact, not have a border.
Under JAM 5, the typical configuration of a menu involved a field (or array) with the menu bit set followed immediately on the screen by a corresponding field (or array) which held a control string. These control fields, usually hidden from view, were fields in their own right, and had field numbers, and could be accessed via the sm_getfield and sm_putfield. This was not the only way menu fields could be used, however. Menu fields could have return values or submenus set, or the application might have managed the screen outside of the control of the JAM executive, such that a control field was not necessary.
In Panther, onscreen control fields are still supported, but they are on their way to obsolescence. Control strings under Panther are typically designated as properties of the push button or list box widgets in question, not as separate fields on the screen.
By default, when f5upg encounters a JAM 5 field with the menu bit set, it leaves it in place and generates a level 1 warning to the user stating that a menu was found and that an onscreen control field may have been used, and that this feature will soon be obsolete. Two command line flags can alter this behavior: the flags -c and -d. -c cause f5upg to copy control strings from onscreen control fields to the properties of the actual push button or list box widget derived from the initial menu field or array, and -d causes f5upg to delete the onscreen control fields from the screen.
Please note that there is no deterministic way for f5upg to know whether a given field did or did not have an associated control field in JAM 5. It depends on the application using that screen, which f5upg has no access to. f5upg can make certain good guesses which it does as follows:
Reasons not to use the -c command line flag:
Reasons not to use the -d command line flag:
-c apply also to -d.
-c because you will lose information.
In JAM/Pi, the designation of a keyset was reinterpreted as designating a menu script. Since f5upg has no way of knowing whether a given screen was designed for use under JAM/Pi or not, use the -m option to move the designation of a keyset to the menu script property.
f5upg converts any data entry fields that are protected from both data entry and tabbing into to Dynamic Label Widgets. In addition, if the field is marked as non-display, it is hidden. This heuristic is performed by default because it is assumed that the vast majority of screens would be best converted in this way.
f5upg attempts to convert every widget it can according to the heuristics discussed above under "General Behavior". If, however, the -5 option is specified, the widget is left unconverted as a JAM release 5 field on a Panther screen. Panther attempts to deal with such fields to achieve a stricter backwards compatibility, but these fields are much harder to manipulate in the Panther editor, and are more difficult to convert to future releases of the product. You may wish to do the conversion with the -5 option and later do a full conversion. Please note that the presence of a JAM/Pi extension specifying widget type overrides this option, and the field is converted nonetheless.
The dd5upg Utility | |
The dd5upg utility converts JAM 5 data dictionaries into JAM/Panther repositories. The utility should be invoked from the command line with the following syntax:
dd5upg [-cflv] [-pprefix] [-eext]JAM5ddrepository
JAM5dd
repository
-c
-f
-l
-v
-p<str>
R5dd.
-e<str>
SMFEXTENSION.
By default, the utility looks for the file data.dic in the current directory. That file is read and a file named data6.dic, a Panther library, is output. This library is intended to be used as a Panther repository.
Each field in the original data dictionary has a scope associated with it. Each scope produces one or more screens in the new library that contain the entries of that scope. By default, the screens are named:
R5dd
<scope>
<sequence#>
An output screen is populated with as many fields of a given scope as possible. If there are more fields of a scope than will fit on one screen, a new screen is started with the next sequence number tacked onto the name. Sequence numbers start at 0.
For example, if the input data dictionary has five entries of scope 1 and three entries of scope 2, the output library will contain the following screens:
R5dd10.jam (has 5 fields)
R5dd20.jam (has 3 fields)
If the -l option is used, dd5upg also creates the library ldb.lib to be used as the local data block. This library contains the same screens as data6.dic, except that they are named ldb1.jam, ldb2.jam, etc.
The m2asc Utility | |
The m2asc utility converts Panther menus between binary and ASCII formats. It also upgrades JAM 5 menus to Panther menus. To upgrade menus, the utility should be invoked from the command line with the following syntax:
m2asc -c [-fv] JAM5_menu [JAM5_menu ...]
JAM5_menu
-c
-f
-v
When run with the -c option, this utility converts JAM 5 menu bar binaries to Panther menu bar binaries.
The dd2rec Utility | |
The dd2rec utility converts JAM 5 data dictionary records to programming language data structures. The utility should be invoked from the command line with the following syntax:
dd2rec [-flpv] [-ooutput_file |-o-] [-glanguage]dictionary
dictionary
-f
-l
-p
-v
-o output_file
-o-
-g language
The data structures generated by dd2rec can be used for backward compatibility via the sm5strct.c functions listed in in Table 4-4.