Is Defined and Is Visible tests

From m204wiki
Revision as of 22:35, 22 October 2013 by JAL (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

These two forms of tests (and their negations) are available for any field in a Model 204 file. They are useful for SOUL code for which these are both true:

  • It is (or may be) in the context of a Model 204 group (of files).
  • It contains field references that may be nonsensical in one or more members of the group.

An example of a nonsensical reference is a reference to a field that is missing in one file in the group yet defined in at least one other group member.

If working with SOUL File class objects, the Defined and Visible tests let you bracket field accesses (and certain updating statements) in group context if the rules described in Request cancelled if group field reference is nonsensical for file would cause undesirable request cancellation.

Examples of the tests are shown below with If blocks:

If GRPFLD1 Is Defined Then Add GRPFLD1 = %val End If If GRPFLD2 Is Visible Then Delete GRPFLD2 End If

The tests can be used wherever SOUL tests can be made, which is, loosely speaking, as a SOUL expression (not including the Print/Audit statement, nor "values" in the Find and field update statements). Typically, however, the tests will be used in the If, ElseIf, and Repeat statements.

These tests, like the Is Present test, can only be used in a record context, such as a For Each Record loop. The syntax is:

fld Is [Not] Defined fld Is [Not] Visible

Where:

fld The name of a field, or a User Language fieldname variable (%%var) containing the name of a field.
Is Defined This test returns the value 1 if the field is defined in the current file (as given by the $CurFile function); otherwise it returns the value 0.
Is Not Defined This test returns the value 0 if the same Is Defined test would return 1, and it returns the value 1 if Is Defined would return 0.
Is Visible This test returns the value 1 if the field is defined in the current file (as given by the $CurFile function) and does not have the INVISIBLE field attribute in that file; otherwise it returns the value 0.
Is Not Visible This test returns the value 0 if the same Is Visible test would return 1, and it returns the value 1 if Is Visible would return 0.

See Using Is Defined and Is Visible to avoid cancellation for more examples of the use of Is Defined and Is Visible.

Note: If a fieldname variable is used in any of the above tests, and it contains a string that is not defined in the current file (nor in any member of the current group, if the reference is in group context), the request is cancelled. This cancellation is consistent with the handling of fieldname variables throughout SOUL, and it has nothing to do with the request cancellation introduced for SOUL protection against nonsensical field references (Request cancelled if group field reference is nonsensical for file).