Understanding and Replacing Deprecated Jam5 Syntax
with Jam7 Syntax

sm_bitop -- Changing Properties on Widgets

• sm_bitop

  sm_bitop(field_number, action, bit)
sm_a_bitop(array_name, action, bit)
sm_e_bitop(array_name, element, action, bit)
sm_i_bitop(array_name, occurrence, action, bit)
sm_n_bitop(field_name, action, bit)
sm_o_bitop(field_number, occurrence, action, bit)
sm_t_bitop(array_number, action, bit)


  Status

  Jam5 & Jam6 Function
  Deprecated & Undocumented in Jam7/Prolifics
  Functional Through Jam7/Panther (Prolifics 4)
  

  Description:

  The sm_bitop function was used to query and manipulate a variety of validation and data editing properties on widgets, arrays, groups, or occurrences. When changing the property, function could be used to set the protection to a particular state, or just to change it to the opposite of the current state. All of these commands were replaced in Jam7 by direct property access using the -><property> syntax.

  For example:
  sm_a_bitop(:codeval_fld, BIT_SET, N_VALIDED)
@field_num(tmp_codeval_fld)->valided = PV_YES

  The sm_bitop family of functions takes 3 or 4 arguments, depending upon the variant. The first 1 or 2 arguments are used to specify the widget, array, group and/or occurrence. The final 2 arguments are always the same: the first specifis the action to occur, the second specifies the bit (or property) to be accessed.

  To translate sm_bitop calls into Jam 7 syntax, several conversion tables are provided below.

  First, look up the variant of the sm_bitop call to determine how the field/array/occurrence/element is being accessed in the Jam5 sm_bitop Function Variant Table. This table also gives the corresponding Jam7 form for accessing the property of the field, array, occurrence, or element.

  Second, if either of the last two arguments (<action> or <bit>) are numeric use the numeric translation tables to convert these the number to the name.

  Third, determine which Jam7 property corresponds to the <bit> argument in the sm_bitop call, using the Jam5 - Jam7 Property Conversion Table. The table lits properties that are no longer relevant in Jam7; however, their properties are still defined in the program and calls to modify or query those properties in Jam7 will usually not generate errors. There is no reason not to remove calls using obsolete properties.

  Fouth, determine the <action> being done in the sm_bitop call. The four possibilities are:

  • BIT_TST: this function is querying for the current value. Replace the function call with a query to the Jam7 Property. If the value of the Jam7 property is the same as the BIT_SET value in the Jam7 Property conversion table, then the sm_bitop function returns 1 (i.e. TRUE). If the Jam7 property value is not the BIT_SET value, which is not necessarily the BIT_CLR value, then the function returns 0 (i.e. FALSE). If the BIT_TST is applied on an array, the function returns 1 only if the BIT_SET value was correct for all occurrences in the array, otherwise the function returns 0.
  • BIT_SET or BIT_CLR: the function is changing a property. Set the Jam7 property to the BIT_SET or BIT_CLR value in the Jam5 - Jam7 Property Conversion Table below.
  • BIT_TOGL: the property is being toggled. This must be converted to a query and followed immediately by a modification. See the toggle example below and determine the property replacement from the <bit> argument using BIT_TST. Determine what the value is and then set the property to the opposite value. Combine all these elements to determine a replacement.

  Fifth, if the function examines it's return value, look up the meaning of the return value in the Jam5 sm_bitop Return Value Table below.

  Finally, combine all these elements to determine the Jam7 replacement.

  JPL Examples

  sm_n_bitop("codeval_fld", BIT_CLR, N_MDT)
@widget("codeval_fld")->mdt = PV_NO

  result = sm_a_bitop("tst_array", BIT_TST, N_UPPER)
  

      temp = @widget("tst_array")->convert_case
  	if (result == PV_UPPER)
  		result = 1
  	else
  		result = 0

  test = sm_bitop(:widget_fld, BIT_TOGL, N_SELECTED)
  

      test = @field_num(widget_fld)->selected
  	if (test = PV_YES)
  		@field_num(widget_fld)->selected = PV_NO
  	else
  		@field_num(widget_fld)->selected = PV_YES

  Conversion Tables

  sm_bitop Function Variant Table

  sm_bitop functional variant	Jam7 property access equivalent
  sm_bitop(field_number, action, bit)	@field_num(field_number)->property
  sm_a_bitop(array_name, action, bit)	@widget(array_name)->property
  sm_e_bitop(array_name, element, action, bit)	@widget(array_name)[[element]]->property
  sm_i_bitop(array_name, occurrence, action, bit)	@widget(array_name)[occurrence]->property
  sm_n_bitop(array_name, action, bit)	@widget(array_name)->property
  sm_o_bitop(field_number, occurrence, action, bit)	@field_num(field_number)[occurrence]->property
  sm_t_bitop(array_number, action, bit)	@field_num(array_number)->property

  Notes on sm_bitop Function Variant Table:

  • The sm_bitop variants differentiated between a field that was an array and a field that contained just a single occurrence. This distinction is no longer relevant. If you set the protection on a field and do not specify an element or occurrence, then the protection is applied to all occurrences of the field. This is true even if the field number specified is not the first field of the array.
  • The sm_n_bitop function could also be passed a group name. If so, then the edit's were applied to the group's properties.
  • The sm_i_bitop and sm_o_bitop functions were restricted to the N_VALIDED and N_MDT bits.

  sm_bitop Numerical Value Table #1

  <action>	Decimal Value
  BIT_CLR	1
  BIT_SET	2
  BIT_TOGL	3
  BIT_TST	4

  sm_bitop Numerical Value Table #2

  <bit>	Decimal Value
  N_VALIDED	9
  N_MDT	10
  N_EPROTECT	20
  N_TPROTECT	21
  N_CPROTECT	22
  N_VPROTECT	23
  N_ALLPROTECT	24
  N_RTJUST	7
  N_REQD	8
  N_CLRINP	11
  N_MENU	12
  N_UPPER	13
  N_LOWER	14
  N_RETENTRY	15
  N_FILLED	16
  N_NOTAB	17
  N_WRAP	18
  N_ADDLEDS	19
  N_SELECTED	25
  N_ALL	0
  N_DIGIT	1
  N_YES_NO	2
  N_ALPHA	3
  N_NUMERIC	4
  N_ALPHNUM	5
  N_FCMASK	6

  Jam5 sm_bitop to Jam7 Property Conversion Table

  <bit>	Jam 7 Property	BIT_SET	BIT_CLR
  N_VALIDED	->valided	PV_YES	PV_NO
  N_MDT	->mdt	PV_YES	PV_NO
  N_EPROTECT	->input_protection	PV_YES	PV_NO
  N_TPROTECT	->focus_protection	PV_YES	PV_NO
  N_CPROTECT	->clearing_protect	PV_YES	PV_NO
  N_VPROTECT	->no_validation	PV_YES	PV_NO
  N_ALLPROTECT	->all_protect	PV_YES	PV_NO **1
  N_RTJUST	->justification **3	PV_RIGHT **2	PV_LEFT
  N_REQD	->required **4	PV_YES	PV_NO
  N_CLRINP	->select_on_entry	PV_YES	PV_NO
  N_MENU	**6
  N_UPPER	->convert_case	PV_UPPER	PV_MIXED
  N_LOWER	->convert_case	PV_LOWER	PV_MIXED
  N_RETENTRY	**6
  N_FILLED	->must_fill **4	PV_YES	PV_NO
  N_NOTAB	->autotab	PV_NO	PV_YES
  N_WRAP	->word_wrap**5	(PV_YES)	(PV_NO)
  N_ADDLEDS	**6
  N_SELECTED	->selected	PV_YES	PV_NO
  N_ALL	->keystroke_filter	PV_UNFILTERED	PV_UNFILTERED **7
  N_DIGIT	->keystroke_filter	PV_DIGITS_ONLY	PV_UNFILTERED **7
  N_YES_NO	->keystroke_filter	PV_YES_NO	PV_UNFILTERED **7
  N_ALPHA	->keystroke_filter	PV_ALPHABETIC	PV_UNFILTERED **7
  N_NUMERIC	->keystroke_filter	PV_NUMERIC	PV_UNFILTERED **7
  N_ALPHNUM	->keystroke_filter	PV_ALPHANUMERIC	PV_UNFILTERED **7
  N_FCMASK	->keystroke_filter	PV_REG_EXP **8	PV_UNFILTERED **7

  Notes For Jam5 sm_bitop to Jam7 Property Conversion Table

  1. all_protect stuff for all_protect = PV_NO - testing and setting.
  2. Unlike most of the deprecated code, this must be changed. In Jam7 and Prolifics, there is a bug using sm_bitop( , , N_RTJUST). When the value is changed (SET, CLR or TOGL) previously entered/displayed text may not be visible on the screen and users may be prevented from typing new text into the widget. Since this bug does not occur when using the new syntax, it will probably never be fixed.
  3. The Jam7 JPL Reference Guide also lists a third justification value -- PV_CENTER -- which wasn't available in JAM5. However, in testing there doesn't seem to be a widget that will take this kind of justification so this property may, in fact, be an error in the manual.
  4. Aren't the properties must_fill and required the same thing? Nope! required means that the field must have something (anything) in it. If users leave it blank they'll get an error when tabbing out of the field. must_fill means that if the field has something in it, the field must be filled to the maximum length and contain no spaces-i.e. no partial fill-ins; however, it can be blank. See the Editor's Guide for details.
  5. N_WRAP is only a query field. The corresponding linkages for BIT_SET & BIT_CLR are shown above, but no commands to change the values should actually occur in real code. In Jam7, this can be changed only using the word_wrap property.
  6. N_RETENTRY, N_ADDLEDS and N_MENU don't work in Jam 7. N_MENU was used to check if a field was a menu field--these no longer exist--so calls using this will need to be rewritten in conjunction with how your app was re-written in Jam7 to deal with menu mode. (Direct corollaries for the other two are unknown-if you actually have code that uses it let me know.)
  7. Using sm_bitop to BIT_SET always overrides the current keystroke_filter on the widget and replaces it with the one you are setting. However, BIT_CLR works differently. BIT_CLR only sets the keystroke_filter to unfiltered if and only if the keystroke_filter specified in the function call is the one currently set on the widget. For example, if a widget is set to "Digits Only" and you call sm_bitop( , BIT_CLR, N_ALPHA), the widget's keystroke filter is unchanged. Only if you call sm_bitop( , BIT_CLR, N_DIGIT) would the keystroke_filter be set to "Unfiltered".
  8. Regular expression (N_FCMASK) can only be set in Jam7 via sm_bitop if the field was originally defined as having a regular expression edit mask. (This restriction does not apply to using Jam7 properties, only to using sm_bitop in Jam7.)

  sm_bitop Return Value Table

  Return Value	Jam5 Meaning
  -1	The field or occurrence was not found.
  -2	The action or bit specified was not valid.
  -3	The request was not valid (e.g. an attempt to set the right justified property on a multi-line text widget with word wrap set to yes.)
  1	BIT_TST: the result matched the BIT_SET value. (For arrays, this must be the case for all occurrences.) BIT_TOGL: the value before it was changed was equal to the BIT_SET value. BIT_SET: the value was changed successfully.
  0	BIT_TST: the result did not match the BIT_SET value. (Or for arrays, one or more of the occurrences did not match the BIT_SET value.) BIT_TOGL: the value before it was changed was not set to the BIT_SET value. BIT_CLR: the value was changed successfully.

  Note on sm_bitop Return Value Table: When using the Jam7 property access, if the conditions for -1, -2, or -3 are met , then there will be a JPL error that will display on the screen. This would not have occurred using sm_bitop, whether using sm_bitop in Jam5 or Jam7.

  ---