Four utilities are provided to help upgrade your application to JAM 6. Because
JAM 6 applications are automatically compatible with JAM 7, no further
conversion is required for upgraded applications.
- f5to6 - converts JAM 5 screens to JAM 6 format.
- dd5to6 - converts JAM 5 data dictionaries to JAM 6 repositories and LDBs.
- m2asc - converts JAM 5 menu bars to JAM 6 format.
- dd2rec - converts JAM 5 data dictionary records to data structures.
The f5to6 Utility
JAM 6 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 JAM 6
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 JAM 6 a tad more tricky than the JAM upgrades you have performed in
The utility f5to6 is designed purely for the purpose of converting JAM 5 screens
to JAM 6 screen format. Although JAM 6 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 f5to6 be used to convert all your JAM 5 screens to
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 f5to6. 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 f5to6 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 JAM 6, 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 f5to6 to specify the same file name for input and
output and consequently overwrite your JAM 5 input screen binary with a JAM 6
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 JAM 6 world. JAM/Pi allowed JAM 5 users to
create JAM applications in GUI environments. Much of the complexity of
converting JAM 5 screens to JAM 6 arises from the need to convert the JPL
extensions used in JAM 5 to specify GUI-specific field and screen attributes to the
JAM 6 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:
f5to6 [-5bcdfklm] [-g type] [-v num] [-s color] JAM5_screen
The name of the JAM 5 screen that you wish to convert.
The name that you would like the converted screen to have.
-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.
-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 JAM 6 cmap file.
If the option is not used, Windows' applications will convert the colors
correctly only if colorpriority is undefined or not set to system.
Colors for Motif applications may differ if the -sX option is not used.
f5to6 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 JAM 6 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 JAM 6 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 JAM
6 Static Label widgets.
Any fields which are in JAM 5 groups are converted as follows:
- If they do not have JAM 5 checkboxes assigned to them, they are converted to
toggle button widgets.
- If they have JAM 5 checkboxes but are JAM 5 radio buttons, they are
converted to radio button widgets.
- If they have JAM 5 checkboxes and are JAM 5 checkboxes, they are converted
to check box widgets.
Any fields unconverted so far are checked for the menu bit.
- If the menu bit is set, the fields are converted to JAM 6 push buttons.
Any fields still unconverted are checked to see if they are protected from both data
entry and tabbing:
- If not, they are converted to text widgets.
- If so, they are checked for protection against clearing, and if that is found they
are made into dynamic labels.
- Otherwise they are converted to text widgets. This last set of fields, (those
which are protected from both data entry and tabbing into) are hidden if the
BLANK attribute is set, regardless of whether they were converted into text
widgets or dynamic labels.
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
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 JAM 6, 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 f5to6 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 JAM 6, 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.
Keep JPL Extensions Around
By default, f5to6 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 re-interpreted if
the target screen is run through f5to6 a second time. They are modified so that the
first angle bracket in the lead-in to each extension becomes an exclamation point.
Allow Output File to Overwrite an Existing File
By default, if the output file specified already exists, f5to6 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.
Assuming System Colors or Scheme by Default
f5to6 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:
Use this option to preserve widget and screen colors for Windows JAM/Pi
applications if colorpriority was set to system in the JAM.INI file.
Use this argument if you want your Motif application to maintain the same color
scheme established in JAM/Pi.
Convert all colors of screens and widgets according to the Scheme in the
configuration map file.
For Windows applications, if colorpriority is not set to system-or is not
defined-the colors will be unchanged. For Motif applications, the colors may
differ if the color option is not set.
Conversion of Menu Arrays to List Boxes
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.
Conversion of Borders
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
By default f5to6 only designates a border for the JAM 6 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, f5to6 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.
Conversion of Onscreen Control Fields
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 JAM 6, onscreen control fields are still supported, but they are on their way to
obsolescence. Control strings under JAM 6 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 f5to6 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 f5to6 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 f5to6 to delete the onscreen control fields from the
Please note that there is no deterministic way for f5to6 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 f5to6 has no access to. f5to6 can make
certain good guesses which it does as follows:
- If the menu field or array is the last (or only) field on the screen, there can be
no associated control field.
- If the menu field or array has a submenu attribute specified in JAM 5, f5to6
assumes there is no corresponding control field.
- If the menu field or array has a return value attribute specified in JAM 5,
f5to6 assumes there is no corresponding control field.
- In all other cases, f5to6 assumes that the field or array immediately following
the menu field or array is an onscreen control field. These fields are either
flagged as obsolete, copied to control string properties, and/or deleted
depending on the presence or absence of the -c and/or -d command line flags.
Reasons not to use the -c command line flag:
- Your application uses C language or JPL routines to set the value of a control
field. (If your application sets the value of the actual menu field, there is no
- Your application processes the screen in question (possibly every screen)
without using the JAM executive. In other words, the screen is processed
directly by using sm_input.
- The screen you are converting has (for obscure reasons) different
dimensionality between the menu fields and their associated control fields. For
example, there is a single array for a set of menu description fields, but each
control field is a single field.
Reasons not to use the -d command line flag:
- All reasons not to use -c apply also to -d.
- You probably do not want to use -d independently of -c because you will lose
- Your application uses C language or JPL routines to inspect the value of a
control field. (If your application inspects the value of the actual menu field,
there is not a problem.)
- Your application makes use of field numbers to set the values of or otherwise
access fields on the screen. All fields following the deleted control field would
be re-numbered on the converted screen, leading to erroneous field processing.
Conversion of Keyset Designations
In JAM/Pi, the designation of a keyset was re-interpreted as designating a menu
script. Since f5to6 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.
Protected Field Heuristics
f5to6 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.
Release 5 Widgets
f5to6 attempts to convert every widget it can according to the heuristics discussed
above under the heading General Behavior on page 4. If, however, the -5 option
is specified, the widget is left unconverted as a JAM release 5 field on a release 6
screen. JAM 6 attempts to deal with such fields to achieve a stricter backwards
compatibility, but these fields are much harder to manipulate in the JAM 6 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 dd5to6 Utility
The dd5to6 utility converts JAM 5 data dictionaries into JAM 6 repositories and
LDBs. The utility should be invoked from the command line with the following
dd5to6 [-flv] [-p prefix] [-e ext] [-d dd] [-o repository]
The name of the JAM 5 data dictionary, which must be preceded by the -d option.
If no input file is specified this argument defaults to data.dic.
The name of the JAM 6 repository, which must be preceded by the -o option. If no
output file is specified this argument defaults to data6.dic.
-f Output file may overwrite an existing file.
-l Generate a screen library, ldb.lib, to be used as the LDB.
-v Prints the name of each screen as it is generated.
-p<str> Uses the specified prefix for generated JAM screens. The default is R5dd.
-e<str> Uses the specified extension for generated JAM screens. The default is
-d<str> Uses the specified data dictionary as input. The default is data.dic.
-o<str> Uses the specified library as output. The default is data6.dic.
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 JAM 6 library, is output. This library is
intended to be used as a JAM 6 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:
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, dd5to6 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 JAM 6 menus between binary and ASCII formats. It
also upgrades JAM 5 menus to JAM 6 menus. To upgrade menus, the utility should
be invoked from the command line with the following syntax:
m2asc -c [-fv] JAM5_menu [JAM5_menu ...]
The name of the JAM 5 binary menu file to convert.
-c Converts JAM 5 binary file to JAM 6 binary file.
-f Output file may overwrite an existing file.
-v Generates a list of the files as they are processed.
When run with the -c option, this utility converts JAM 5 menu bar binaries to
JAM 6 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] [-o output_file] [-g language] dictionary
The name of the JAM 5 data dictionary to convert.
The programming language in which to create the structure. Currently only C is
The name of the output file.
-f Overwrites an existing output file.
-l Converts record names to lower case.
-p Creates the output files in the same directory as the data dictionary.
-v Generates a list of the records as they are written.
-o str Directs output to named file. -o- outputs to the screen.
-g str Generates records as an array of structures in the language specified.
The data structures generated by dd2rec can be used for backward compatibility
via the sm5strct.c functions listed in Table on page .