Understanding and Replacing Deprecated Jam5 Syntax with Jam7 Syntax

Understanding and Replacing Deprecated Jam5 Syntax
with Jam7 Syntax

JPL Variable and Field Assignment -- Using Cat to Assign Values

The cat verb was used to make variable assignments in Jam5. The target (or l-value) of the assignment was the first word after the cat verb. Targets could be either a variables defined in jpl with vars, fields on the screen or references to fields on the screen. The rest of the statement following the target was the source (or r-value) of the assignment and could be a combination of variables, field names, references to fields or hard-coded constants. Colon expansion occured before the variable assignment occured and both the target and the source could contain variables to be colon-expanded.

In Jam5, the cat verb was used for variable and widget assignment and there were two different targets of cat statements

variable/widget names
field references to widgets on the current screen

If the target of a cat assignment begins with a pound sign (#), a plus sign (+) or a minus sign (-), then it is a field reference-this is easily seen because variable names cannot have these characters as part of the name. Regular variable names consist of alphanumeric characters, the underscore (_), the exclamation point (!), the period (.) and the dollar sign ($). (Note that the ! was added to variable names in Jam7-the rest of these characters could have been used in variable names in Jam5)

cat statements referencing variables by name. These can be directly replaced by shifting the target and adding the appropriate equals sign (If necessary, use the ## concatenation operator, which was also introduced in Jam 7. In Jam5, adjacent strings were, under most circumstances, concatenated together.)

Old: cat field1 "This is a test"
New: field1 = "This is a test"

Old: cat field2 "This" "is" :test_field
New: field2 = "This" ## "is" ## test_field

Old: cat zip(6,5) "-" zip_extension
New: zip(6,5) = "-" ## zip_extension

Cat statements using field number references. Cat statements could specify the target of an assignment to a widget by using the field numbers that widgets are assigned when the widgets are placed on the screen in the editor. Such references could either be absolute references that referred to a specific widget, (i.e. cat #5 "test1" ) or could be relative references, where the reference was relative to the currently field on the screen at runtime (cat #+1 "my_data"). To replace or update such references it is necessary to examine the screen to determine which widget the code would have been referring to and use the appropriate widget name as the target of a standard widget assignment using an =.
cat #5 "212-267-7722"
This must be replaced by the name of the widget being referred to. If this widget is named ph_number, then the replacement code would be: ph_number = "212-267-7722".
cat +1 "my_data" or cat #+1 "my_data"
This assigns the field that is +1 after the current widget to be the value "my_data". Note that the first form that omits the # will be recognized as a syntax error in Jam7, but would have been accepted in Jam5. Only the second form, which includes the #, works in Jam7, but is undocumented.
cat #-2 "me_too"
This is similar to the above, but refers to the field that is 2 fields before the current one.
cat #+0 "data value" or cat #-0 "data_value"
@widget("@current") = "data_value"
This zero value performs an assignment to the current widget. Instead of using the widget name in the replacement code, the suggested new code will work at all times.
cat #:OV_FLDNUM 0
@field_num(OV_FLDNUM) = 0.
Colon Expansion occurs before variable assignment, so OV_FLDNUM must contain a number specifying the field to receive the value zero.
Note: In general, the usage of hard-coded widget field numbers should be eliminated, since field numbers are entirely dependent upon the specific layout of widgets on a screen. A little widget rearrangement on a screen could change the field numbers on all widgets on a screen. In addition, when a screen is converted from Jam5 to Jam7, the actual # of fields on a screen will often change, which will also require field number recalculation.