sm_protect, sm_unprotect
sm_aprotect(field_number, protection_mask)
sm_aunprotect(field_number, protection_mask)
sm_protect(field_number)
sm_unprotect(field_number)
sm_1protect(field_number, protection_mask)
sm_1unprotect(field_number, protection_mask)
. . . and other variants listed below.
Status
-
Jam5 & Jam6 Function
Deprecated & Undocumented in Jam7/Prolifics
Functional Through Jam7/Panther (Prolifics 4)
Description:
-
The sm_*_protect functions were used to
set and clear protection values on widgets and on individual
occurrences within a widget array. In Jam5, as now in Jam7, the four types of
protections were focus protection, clearing protection, input
protection and validation protection. (See the Editor's Guide more
information about the meaning of these protections.) In Jam7 this set
of functions was replaced by direct property access.
The sm_protect and sm_unprotect set of functions changed all four
protections at once. The others used the <protection_mask>
to determine which protections to change. Whether the protection was
being set or unset dependeded upon which functional form was used. If
the function is a variant of sm_protect then the protections
are being set, which corresponds to protection = YES in Jam7.
Similarly, if the function is a variant of sm_unprotect, then the
protections are being cleared, or set to protection = NO. (None of
these functional forms allowed users to query protection values -- for
this programmers would have used sm_bitop. Note that it was also possible
to use sm_bitop to change protections, so code to change protections
could use either sm_bitop, or sm_protect or a mixture of both.)
The protection mask was a combination of the bit values of one or more of the protections being changed. Since these protections were not pre-defined constants in jpl in Jam5, jpl programmers would either have created variables for the protections, or they could have used hard-coded numerical values. The constants were available in an include file for calling from C.
To create a Jam7 replacement for old code, determine how to access the widget using the sm_protect Variant Conversion Table below, and then determine the protection property(s) to set based upon the protection mask using the Protection Mask Conversion Table below. Then combine these into the appropriate widget or element property change. Note that the old 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, 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.
|
Variants that changed all four protections on a single field |
|
|
Jam5 sm_protect variant |
Jam7/Prolifics Property Access |
|
sm_protect(<field_number>) |
@fld_num(<field_number>)->all_protect = PV_YES |
|
sm_umprotect(<field_number>) |
@fld_num(<field_number>)->all_protect = PV_NO ** |
|
sm_n_protect("<field_name>") |
@widget("<field_name>")->all_protect = PV_YES |
|
sm_n_unprotect("<field_name>") |
@widget("<field_name>")->all_protect = PV_NO ** |
|
Variants that changed all occurrences in an array. |
|
|
sm_aprotect(<field_number>, <protect_mask>) |
@fld_num(<field_number>)-><protect_property> = PV_YES |
|
sm_aunprotect(<field_number>, <protect_mask>) |
@fld_num(<field_number>)-><protect_property> = PV_NO |
|
sm_n_aprotect("<field_name>", <protect_mask>) |
@widget("<field_name>")-><protect_property> = PV_YES |
|
sm_n_aunprotect("<field_name>", <protect_mask>) |
@widget("<field_name>")-><protect_property> = PV_NO |
|
Variants that Changed a single field |
|
|
sm_1protect(<field_number>, <protect_mask>) |
@fld_num(<field_number>)-><protect_property> = PV_YES |
|
sm_1unprotect(<field_number> <protect_mask>) |
@fld_num(<field_number>)-><protect_property> = PV_NO |
|
sm_n_1protect("<field_name>", <protect_mask>) |
@widget("<field_name>")-><protect_property> = PV_YES |
|
sm_n_1unprotect("<field_name>", <protect_mask>) |
@widget("<field_name>")-><protect_property> = PV_NO |
|
Variants that Changed the protection for a single element of an array. |
|
|
sm_e_protect("<field_name>", <element>) |
@widget("<field_name>")[[<element>]]->all_protect = PV_YES |
|
sm_e_unprotect("<field_name>", <element>) |
@widget("<field_name>")[[<element>]]->all_protect = PV_NO ** |
|
sm_e_1protect("<field_name>", <element>, <protect_mask>) |
@widget("<field_name>")[[<element>]]-><protect_property> = PV_YES |
|
sm_e_1unprotect("<field_name>", <element>, <protect_mask>) |
@widget("<field_name>")[[<element>]]-><protect_property> = PV_NO |
** See the Note below for special considerations on setting all_protect = PV_NO.
|
Jam5 Protection Mask |
Hex Value |
Jam7 Protection Property |
|
EPROTECT |
0x01 |
input_protection |
|
TPROTECT |
0x02 |
focus_protection |
|
CPROTECT |
0x04 |
clearing_protect |
|
VPROTECT |
0x08 |
no_validation |
|
ALLPROTECT |
0x10 |
all_protect |
JPL Examples
call sm_n_protect(":field_name")
@widget(":field_name")->all_protect = PV_YES
call sm_n_1unprotect("field1", TPROTECT)
@widget("field1")->focus_protection = PV_NO
call sm_aprotect(array1_num, TPROTECT | EPROTECT)
@field_num(array1_num)->focus_protection = PV_YES
@field_num(array1_num)->input_protection = PV_YES
call sm_e_1unprotect("text_field", 1, 4)
@widget("text_field")[[1]]->clearing_protect = PV_NO
Special Note for all_protect = PV_NO
-
Because all_protect only takes two values (PV_YES & PV_NO),
setting the all_protect = PV_NO is not intuitive. If the current
protections on a widget are mixed (i.e. focus_protection = PV_NO, but
clearing_protect, no_validation and input_protection = PV_YES), then
in Jam7 if the all_protect property on that widget were queried,
the response would be PV_NO. Since all four protections are not set,
they are not all protected, so all_protect = PV_NO. This is
important because before setting a property, Jam checks to see if that
property is already set. Thus, when you set all_protect = PV_NO and
the current protections are mixed, Jam checks the properties, sees
that all_protect is currently PV_NO and does nothing, leaving the
mixed protection state in effect.
This effect is not symmetrical. Setting all_protect = PV_YES, sets all four protections to PV_YES, unless all four already were set anyway.
Thus, one way around the ambiguity of setting all_protect = PV_NO is to set all_protect = PV_YES, right before you set all_protect = PV_NO. Since the all_protect = PV_YES guarantees that all four protections are set, when the all_protect = PV_NO is encountered, you are guaranteed that all four protections will be unset. Alternatively, some programmers eschew all_protect = PV_NO altogether, choosing to always unset protections individually.