View source for Is Defined and Is Visible tests

These two forms of tests (and their negations) are available for any field in a <var class="product">Model 204</var> file.
They are useful for <var class="product">SOUL</var> code for which these are both true:
<ul>
<li>It is (or may be) in the
context of a <var class="product">Model 204</var> group (of files).
<li>It contains field
references that may be nonsensical in one or more members of the group.
</ul>

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
<var class="product">SOUL</var> <var>[[File classes|File]]</var> class objects, the <var>Defined</var> and <var>Visible</var> tests let you bracket field accesses
(and certain updating statements)
in group context if the rules described in
[[File classes#Request cancelled if group field reference is nonsensical for file|Request cancelled if group field reference is nonsensical for file]] would cause undesirable request cancellation.
 
Examples of the tests are shown below with <var>If</var> blocks:
<p class="code">If GRPFLD1 Is Defined Then Add GRPFLD1 = %val
End If
 
If GRPFLD2 Is Visible Then Delete GRPFLD2
End If
</p>
 
The tests can be used wherever <var class="product">SOUL</var> tests can be made, which is, loosely
speaking, as a <var class="product">SOUL</var> expression (not including the <var>Print</var>/<var>Audit</var>
statement, nor "values" in the <var>Find</var> and field update statements).
Typically, however, the tests
will be used in the <var>If</var>, <var>ElseIf</var>, and <var>Repeat</var>
statements.
 
These tests, like the
<var>Is Present</var> test, can only be used in a record
context, such as a <var>For Each Record</var> loop.
The syntax is:
<p class="syntax"><span class="term">fld</span> Is [Not] Defined
 
<span class="term">fld</span> Is [Not] Visible
</p>
Where:
<table>
<tr><th>fld</th>
<td>The name of a field, or a <var class="product">User Language</var> fieldname variable (<code>%%var</code>) containing the name of a field.
</td></tr>

<tr><th><var>Is Defined</var></th>
<td>This test returns the value <code>1</code> if the field is defined in the current file (as given by the <var>$CurFile</var> function); otherwise it returns the value <code>0</code>.
</td></tr>

<tr><th nowrap="true"><var>Is Not Defined</var></th>
<td>This test returns the value <code>0</code> if the same <var>Is Defined</var> test would return <code>1</code>, and it returns the value <code>1</code> if <var>Is Defined</var> would return <code>0</code>.
</td></tr>

<tr><th><var>Is Visible</var></th>
<td>This test returns the value <code>1</code> if the field is defined in the current file (as given by the <var>$CurFile</var> function) and does not have the <var>INVISIBLE</var> field attribute in that file; otherwise it returns the value <code>0</code>.
</td></tr>

<tr><th><var>Is Not Visible</var></th>
<td>This test returns the value <code>0</code> if the same <var>Is Visible</var> test would return <code>1</code>, and it returns the value <code>1</code> if <var>Is Visible</var> would return <code>0</code>.
</td></tr>
</table>
 
See [[File classes#Using Is Defined and Is Visible to avoid cancellation|Using Is Defined and Is Visible to avoid cancellation]] for more examples of the use of <var>Is Defined</var> and <var>Is Visible</var>.
 
<p class="note">'''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 <var class="product">SOUL</var>, and it has nothing to do with the request cancellation
introduced for <var class="product">SOUL</var> protection against nonsensical field references
([[File classes#Request cancelled if group field reference is nonsensical for file|Request cancelled if group field reference is nonsensical for file]]). </p>

[[Category: User Language syntax enhancements]]