Locating Fields
The field functions can be used to get or change information on any field within a form set. By default, these field functions will assume that you are referencing a field located on the current section. To locate specific fields, elsewhere in the document, requires additional information. Any field’s location can be precisely determined by the following hierarchy:
Field -> Section -> Form -> Group
Fields occur on sections. Sections occur on forms. Forms are defined within a form group (called a Line of Business in the insurance market). The form groups are specified by the user during form set selection.
Typically you will not have to specify all four components of the hierarchy to locate a given field for the DAL fields functions. By default, all field functions will search the current section which is the section that contains the script being executed. If the field you wish to reference occurs on the current section, then you do not have to specify any other information.
| Note | You can also use the asterisk (*) as a wildcard, however, for optimal performance, avoid using wildcards (*) when searching for field, section, or form names. |
To locate a field on a section other than the current one requires additional information. Each field function accepts optional parameters to identify a specific field, section, form, and/or group to search. In addition, each of these parameters will support an optional occurrence count to further identify the precise location of the field being requested.
A given field name is usually unique to a section. However, that same field name might also be used on any number of other sections. Further, there may be any number of occurrences of a section on a given form. Likewise, there may be additional copies of a form included in the form set. And finally, any two forms might share one or more sections in common.
Since it is possible to have any number of a similar named objects within a form set, the occurrence count, used with the object’s name, is sometimes necessary to identify a specific object. The following table explains the method that DAL field functions will use to locate fields:
|
Field Name |
Section Name |
Form Name |
Group Name |
Description |
|
*omitted* |
*omitted* |
*omitted* |
*omitted* |
In the absence of any of these parameters, the function will assume that you wish to use the current field. |
|
"FLD" |
*omitted* |
*omitted* |
*omitted* |
Find FLD on the current section. |
|
"FLD" |
"IMG" |
*omitted* |
*omitted* |
Find the first occurrence of IMG (a section) on the current form. If located, find FLD on that section. |
|
"FLD" |
*omitted* |
"FRM" |
*omitted* |
Find the first occurrence of FRM (a form) in the current group. If located, find the first occurrence of FLD on that form. FLD may occur on any section on FRM since that parameter was omitted. |
|
"FLD" |
*omitted* |
*omitted* |
"GRP" |
Find the first occurrence of FLD within the group, GRP. This field may be on any section on any form within that group. |
|
"FLD" |
"IMG" |
"FRM" |
*omitted* |
Find the first occurrence of FRM in the current group. Find the first occurrence of IMG on that form. Find FLD on that section. |
|
"FLD" |
"IMG" |
*omitted" |
"GRP" |
Find the first occurrence of IMG within the group, GRP. This section may occur on any form since that parameter was not specified. Then find FLD on that section. |
|
"FLD" |
"IMG" |
"FRM" |
"GRP" |
Find the first occurrence of FRM within the group, GRP. Then find the first occurrence of IMG. Finally, locate FLD on that section. |
Notice that many of these descriptions referred to the first occurrence of a particular object. This is the default search method unless an occurrence count is specified on the object name. For instance, if there are three occurrences of the field "MYFIELD" on a particular form, you would distinguish them as "MYFIELD\1", "MYFIELD\2", and "MYFIELD\3". (In practice you do not have to specify "\1" to identify the first occurrence except on those field functions that match on partial names.)
The backslash is not a valid character in any object name. When found, the field functions will assume that the number following the backslash identifies the particular occurrence of that named object you are requesting.
Field, section, and form names may specify occurrence numbers. Group does not require an occurrence number because form groups are unique within the form set. The following table demonstrates several uses of occurrence indicators.
|
Field Name |
Section Name |
Form Name |
Group Name |
Description |
|
"FLD" |
"IMG\2" |
*omitted* |
*omitted* |
Find the second occurrence of IMG (a section) on the current form. If located, find FLD on that section. |
|
"FLD\3" |
*omitted* |
"FRM\2" |
*omitted* |
Find the second occurrence of FRM (a form) in the current group. If located, find the third occurrence of FLD on that form. The third occurrence of FLD may occur on any section on FRM since that parameter was omitted. |
|
"FLD\8" |
*omitted* |
*omitted* |
"GRP" |
Find the eighth occurrence of FLD within the group, GRP. This field may occur on any section or form within that group. |
|
"FLD" |
"IMG\5" |
*omitted* |
"GRP" |
Find the fifth occurrence of IMG (a section) within the group, GRP. If located, find FLD on that section. |
Finally, it should be noted that if a named object, or occurrence of that object, cannot be located then the search will end in failure. For instance, if in the last example there are not 5 occurrences of IMG within the named group, then the function will cease looking for FLD and return without success.