Understanding and Replacing Deprecated Jam5 Syntax
with Jam7 Syntax

Color and Text Atribute Functions

• sm_chg_attr
  sm_o_achg

  sm_chg_attr(int field_number, int display_attribute)
sm_e_chg_attr(string field_name, int element, int display_attribute)
sm_n_chg_attr(string field_name, int display_attribute)
sm_o_chg_attr(int field_number, int element, int display_attribute)
sm_o_achg(int field_number, int occurrence, int display_attribute)
sm_i_achg(string field_name, int occurrence, int display_attribute)


  Description:

  The sm_chg_attr and sm_o_achg functions changed the colors on fields and on individual occurrences in a scrolling array, respectively. All Jam5 functions used the same text color and attribute values, and whenever a single color was set, all of the foreground and background colors and text properties were set at once via a bit value in which all the desired properties were bit-wise or'ed to create one number. This composite number is the display_attribute parameter in all the functions listed above.

  sm_chg_attr was the main function to change attributes on fields. sm_o_achg was used to change the color on a particular occurrence in an array; those properties would then scroll with that occurrence as the user moved throughout the array, even if the occurrence scrolled offscreen or was offscreen when the function call was made.

  In Jam7, various properties were created representing the foreground and background color, as well as other properties for each text property that was previously set via the display_attribute composite value. One advantage of this is that it is not necessary to know all the values when setting an individual property. When setting values via the display_attribute, all foreground and background properties were affected.

  In Jam7, the text colors were expanded, so that in addition to using the basic color scheme, separate color schemes could be created, as well as an unlimited number of colors created using color-names defined in separate configuration files. The colors in Jam7 map into the colors supplied for the 'basic' scheme, unless special processing in the video or color map file overwrote the Jam5 basic color scheme. Assuming that this was not done, to convert color settings to Jam7, set the fg_color_type and bg_color_type on each widget to BASIC. Then set the fg_color_num and bg_color_num to the color values listed in the first table. The Jam5 and Jam7 constant names are the same, as are the hex values that represented those colors. All the constants are defined for use in C in the smattrib.h file. Unlike in Jam5, all the color names are also defined in JPL. Bitwise or'ing the HILIGHT and B_HILIGHT constant sets the color as the bright version of the color. (e.g., HILIGHT | GREEN, sets the color as "bright green") Be sure to note the different color settings for foreground and background colors.

  The other text properties are set separately. The second table lists the Jam5 Foreground Text Property that would have been combined as part of the display_attribute value, as well as the Jam7 Property that corresponds to that bit. Each Jam7 property can be set to either PV_YES or PV_NO.

  Since Jam5 constants were not available at run-time, programmers may have combined hex values and then defined the hex or decimal number as a constant in the file, or in the ldb. To determine the settings used, it is necessary to convert any decimal values to a hex value, and then determine what combination of colors and text properties are represented by that hex value.

  Jam5 & Jam7 Color Constants

  Foreground Colors		Background Colors
  Jam5 Attribute	Hex Value	Jam5 Attribute	Hex Value
  BLACK	0x0000	B_BLACK	0x0000
  BLUE	0x0001	B_BLUE	0x0100
  GREEN	0x0002	B_GREEN	0x0200
  CYAN	0x0003	B_CYAN	0x0300
  RED	0x0004	B_RED	0x0400
  MAGENTA	0x0005	B_MAGENTA	0x0500
  YELLOW	0x0006	B_YELLOW	0x0600
  WHITE	0x0007	B_WHITE	0x0700
  Foreground Hilight (Bright)		Background Hilight (Bright)
  HILIGHT	0x0080	B_HILIGHT	0x8000

  
  

  Jam5 Foreground Text Property to Jam7 Text Property Conversion Table.

  Jam 5 Foreground Property	Hex Value	Jam7 Property (values: PV_YES or PV_NO)
  BLANK	0x0008	As such, this property does not exist. This is the same as setting the foreground color to the background color, which can be done directly.
  REVERSE	0x0010	reverse
  UNDERLN	0x0020	underline
  BLINK	0x0040	blink
  DIM	0x1000	dim
  STANDOUT	0x0800	No corresponding property. (Perhaps this effect could be replaced by using the 'bold' font property.)
  ACS (Alternate Character Set)	0x2000	See Notes below.

  JPL Examples

  call sm_n_chg_attr("acct_status", 34724)
  
  The display_attribute value corresponds to 0x87A4. The 1st digit (counting from the right) represents the foreground color (4 = RED), the 3rd digit represents the background color (7 = WHITE). The value 0x8000 can only represent the Background Hilight (B_HILIGHT). This leaves 0x00A0, which is not a value in the table. Since this column normally contains foreground properties, 2 different properties are probably added together. The only things that could add to get 0x00A0 are Underline (0x20 = UNDERLN) and Foreground Hilight (0x0080 = HILIGHT). Now, having completely decomposed the value into the various properties, we can replace this statement with individual property settings as follows:
  

             @widget("acct_status")->fg_color_num = RED | HILIGHT
             @widget("acct_status")->bg_color_num = B_WHITE | B_HILIGHT
             @widget("acct_status")->underline = PV_YES

  Also note that since a display attribute set all the properties at once that the following text property settings are implied (although if the were not set before, they do not need to be unset):

             @widget("acct_status")->reverse = PV_NO
             @widget("acct_status")->blink = PV_NO
             @widget("acct_status")->dim = PV_NO

  call sm_o_achg(array_fldnum, occ, CYAN | HILIGHT | B_BLACK | B_HILIGHT)
  

             @field_num(array_fldnum)[occ]->fg_color_num = CYAN | HILIGHT
             @field_num(array_fldnum)[occ]->bg_color_num = B_BLACK | B_HILIGHT

  Notes

  • Even if you choose to continue to use the sm_chg_attr and sm_o_achg functions in Jam7 and beyond, for programmer sanity, make use of the constants being available at runtime in JPL in Jam7. Applying this to the first example, a more rational way to write the function call in Jam7 is:
    sm_n_chg_attr("acct_status", RED | HILIGHT | UNDERLN | B_WHITE | B_HILIGHT).

  • A common mistake is to not use the B_ prefix for background colors.

  • Not all properties will appear in all environments or with all fonts. For example, by default, in Microsoft Windows, Blink and Dim will not appear, while Reverse and Underline will.

  • If code uses the ACS (alternate character set) value, then more extensive font processing is being used. This processing is beyond the level of this technical tip.

  ---