Is Defined and Is Visible tests: Difference between revisions
Jump to navigation
Jump to search
mNo edit summary |
|||
| Line 1: | Line 1: | ||
these two forms of tests (and their negations) are available for any field in a <var class="product">Model 204</var> file. | |||
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) | 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. | references that may be nonsensical in one or more members of the group. | ||
</ul> | |||
An example of a nonsensical reference is a reference to | An example of a nonsensical reference is a reference to | ||
a field that is missing in one file in the group yet defined in | a field that is missing in one file in the group yet defined in | ||
| Line 10: | Line 13: | ||
If working with | If working with | ||
<var class="product"> | <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) | (and certain updating statements) | ||
in group context if the rules described in | in group context if the rules described in | ||
[[File classes#Request cancelled if group field reference is nonsensical for file| | [[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: | Examples of the tests are shown below with <var>If</var> blocks: | ||
| Line 23: | Line 26: | ||
</p> | </p> | ||
The tests can be used wherever <var class="product"> | The tests can be used wherever <var class="product">SOUL</var> tests can be made, which is, loosely | ||
speaking, as a <var class="product"> | speaking, as a <var class="product">SOUL</var> expression (not including the <var>Print</var>/<var>Audit</var> | ||
statement, | statement, nor "values" in the <var>Find</var> and field update statements). | ||
nor "values" in the <var>Find</var> and field update statements). | |||
Typically, however, the tests | Typically, however, the tests | ||
will be used in the <var>If</var>, <var>ElseIf</var>, and <var>Repeat</var> | will be used in the <var>If</var>, <var>ElseIf</var>, and <var>Repeat</var> | ||
| Line 35: | Line 37: | ||
context, such as a <var>For Each Record</var> loop. | context, such as a <var>For Each Record</var> loop. | ||
The syntax is: | The syntax is: | ||
<p class=" | <p class="syntax"><span class="term">fld</span> Is [Not] Defined | ||
fld Is [Not] Visible | <span class="term">fld</span> Is [Not] Visible | ||
</p> | </p> | ||
Where: | Where: | ||
<table | <table> | ||
<tr><th>fld | <tr><th>fld</th> | ||
</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>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> | </td></tr> | ||
<tr><th><var>Is Defined</var> | |||
</th><td>This test returns the value <code> | <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> | </td></tr> | ||
<tr><th | |||
</th><td>This test returns the value <code> | <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> | </td></tr> | ||
<tr><th><var>Is Visible</var> | |||
</th><td>This test returns the value <code> | <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> | </td></tr> | ||
</table> | |||
See [[File classes#Using Is Defined and Is Visible to avoid cancellation| | 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>. | ||
and <var>Is Visible</var>. | |||
< | <p class="note">'''Note:''' | ||
If a fieldname variable is used in any of the above tests, | If a fieldname variable is used in any of the above tests, | ||
and it contains a string that | and it contains a string that | ||
| Line 66: | Line 72: | ||
group, if the reference is in group context), the request is cancelled. | group, if the reference is in group context), the request is cancelled. | ||
This cancellation is consistent with the handling of fieldname variables | This cancellation is consistent with the handling of fieldname variables | ||
throughout <var class="product"> | throughout <var class="product">SOUL</var>, and it has nothing to do with the request cancellation | ||
introduced for <var class="product"> | introduced for <var class="product">SOUL</var> protection against nonsensical field references | ||
([[File classes#Request cancelled if group field reference is nonsensical for file| | ([[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]] | [[Category: User Language syntax enhancements]] | ||
Revision as of 22:34, 22 October 2013
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).