(Required) The number of the file or subfile to search. If this parameter is a subfile, it must be accompanied by the IENS parameter.

(Optional) The IENS that identifies the subfile, if FILE is a subfile number. To identify a subfile, rather than a subfile entry, leave the first comma-piece empty. For example, a value of ",67," indicates that the subfile within entry #67 should be used. If FILE is a file number, this parameter should be empty. Defaults to no subfile.

(Optional) The fields to return with each entry found. This parameter can be set equal to any of the specifications listed below. The individual specifications should be separated by semicolons (";").

NOTE: In most cases, a developer will want to include the "@" specifier (described below) to suppress the default output values normally returned by the Finder and then specify the fields and other elements to return here in the FIELDS parameters. This gives the developer full control over exactly what will be returned in the output list and makes the call more self-documenting in the developer's code. 

• Field Number: This specifier causes the Finder to return the value of the field for each record found. For example, specifying .01 returns the value of the .01 field. You can specify computed fields. You cannot specify word processing or multiple fields. By default, fields will be returned in external format. The "I" suffix (described below) can be appended to the field number to get the internal format of the field
  
  
• IX:  This returns for each record, the value(s) from the index on which the lookup match was made. The number of index values returned will depend on the number of data value subscripts in the starting lookup index. If a subscript in the index is derived from a field, the external format of that field will be returned by default. Otherwise, the value will be returned directly as it appears in the index. The "I" suffix (described below) can be appended to IX to get the internal index values. The index values are returned in the "ID" nodes as described in the "Output" section below.

  NOTE: For records located on a mnemonic index entry, the value from the index entry will always be returned, rather than its corresponding external field value.

• FID:  This returns the fields display identifiers (i.e., field identifiers). By default, the field values are returned in external format. The "I" suffix (described below) can be appended to FID to get the internal format of the field identifiers.
  
  
• WID:  This returns the fields WRITE (display only) identifiers. The Finder executes each WRITE identifier's M code and copies contents of ^TMP("DIMSG",$J) to the output. You must ensure that the WRITE identifier code issues no direct I/O, but instead calls EN^DDIOL. NOTE: The "I" suffix, described below, cannot be used with "WID" and will generate an error.
  
  
• E suffix:  You can append an "E" to a field number, the specifier "IX", or the specifier "FID" to force the fields to be returned in external format. You can use both the "E" and "I" suffix together (ex., .01EI) to return both the internal and external value of the field.
  
  
• I suffix:  You can append an "I" to a field number, the specifier "IX", or the specifier "FID" to force the fields to be returned in internal format. You can use both the "E" and "I" suffix together (ex., .01IE) to return both the internal and external value of the field.
  
  
• - prefix:  A minus sign (-) prefixing one of the other field specifiers tells the Finder to exclude it from the returned list. This could be used, for example, in combination with the "FID" specifier to exclude one of the identifier fields. For example, if field 2 was one of the field identifiers for a file, "FID;-2" would output all of the field identifiers except for field 2.
  
  
• @:  This suppresses all the default values normally returned by the Finder, except for the IEN and any fields and values specified in the FIELDS parameter. It is recommended that developers ALWAYS use the "@" specifier in Finder calls. Use of the "@" specifier allows the developer to control exactly what will be returned in the output. See below for the default values normally returned by the Finder.
• 22.2 Computed expression: Any computed expression valid in the context of the the File can be used to retrieve the value of that expression for the records found.

Default Values

If you do not pass anything in the FIELDS parameter, the Finder returns:

1. The IEN
2. The .01 field in internal format
3. Any field display identifiers
4. Any WRITE (display-only) identifiers
5. The results of executing the Finder's IDENTIFIER parameter

If you do pass a FIELDS parameter, the Finder returns (unless you use the @ field specifier):

1. The IEN
2. The .01 field in internal format
3. The fields and values specified by the FIELDS parameter
4. Any WRITE (display-only) identifiers
5. The results of executing the Finder's IDENTIFIER parameter

(Optional) Flags to control processing. This parameter lets the caller adjust the Finder's algorithm. The possible values are:

Allow pure numeric input to always be tried as an IEN. Normally, the Finder will only try pure numbers as IENs if: 1) the file has a .001 field, or 2) its .01 field is not numeric and the file has no lookup index.

When this flag is used, records that match other numeric interpretations of the input will be found in addition to a record with a matching IEN. For example, a lookup value of "2" would match a record with a lookup field of "2JOHN" as well as a record with an IEN of 2. If more than one match is found, all matching records are returned.

NOTE: If the numeric lookup value is preceded by an accent grave character ('), lookup interprets the input as an IEN, and only attempts to match by IEN. The A flag is not required in this case.

B index used on lookups to pointed-to files. Without the B flag, if there are cross-referenced pointer fields in the list of indexes to use for lookup then: (1.) for each cross-referenced pointer field, FileMan checks ALL lookup indexes in each pointed-to file for a match to X (time-consuming), and (2.) if X matches any value in any lookup index (not just on the .01 field) in a pointed-to file and the IEN of the matched entry is in the home file's pointer field cross-reference, FileMan considers this a match (perhaps not the lookup behavior desired).

The B flag prevents this behavior by looking for a match to X only in the "B" index (.01 field) of files pointed to by cross-referenced pointer fields. This makes lookups quicker and avoids the risk of FileMan matching an entry in the pointed-to file based on something other than the .01 field.

See the "Details and Features" section for an explanation of the "Lookup Index" and the "Examples" section for more information on use of the B flag.

Use the Classic way of performing lookups on names, i.e., like the classic FileMan lookup routine ^DIC. If C is passed in the FLAGS parameter and, for example, the user enters a lookup value of "Smi,J", the Finder will find "Smith,John" but also "Smiley,Bob J." The Finder takes the first comma piece of the lookup value "Smi", and looks for partial matches to that. It then takes the second comma piece of the lookup value "J" and looks for partial matches to "J" on the second or any other piece of the value on the entry being examined. It uses any punctuation or space for a delimiter.

The default, without passing C in the FLAGS parameter, will look for partial matches ONLY on the second piece, thus in our example, finding "Smith,John" but not "Smiley,Bob J.". The old style of comma-piece processing can be quite slow, especially with common names like "Smith".

Primary Key used for starting index. If no index is specified in the INDEXES parameter, this flag causes the Finder to use the Uniqueness index for the Primary Key as the starting index for the search. Without the K flag, or if there is no Primary Key for this file (in the KEY file), the Finder defaults to the "B" index.

Multiple index lookup allowed. If more than one index is passed in the INDEXES parameter, all indexes in the list are searched. Otherwise, the M flag causes the Finder to search the starting index and all indexes that alphabetically follow it. This includes both indexes from the traditional location in the data dictionary, as well as lookup indexes defined on the INDEX file that have an "L" (for LOOKUP) in the new "Use" field.

The starting index is taken from the INDEXES parameter. If that is null, the search begins with the default starting Index (see K flag description above).

NOTE: If the first index passed in the INDEXES parameter is a compound index, the M flag is removed and only that one index is searched. See "Lookup Index" in the "Details and Features" section for more information. 

Only find exact matches if possible. The Finder first searches for exact matches on the requested Index(es); if any are found, it returns all exact matches to the lookup value. Only if it finds none in the file does it search for partial matches, returning every partial match. For example, if the lookup value is "EINSTEIN" and the file contains entries "EINSTEIN" and "EINSTEIN,ALBERT", only the first record is returned. If the first record did not exist, the Finder would return "EINSTEIN,ALBERT" as a match. If FLAGS does not contain an O, the Finder returns all matches, partial and exact.

If the lookup is done on a compound index, exact matches must be made for every data value subscript in the index in order to consider the entry to be an exact match.  (This flag is revised.)

Pack output. This flag changes the Finder's output format to pack the information returned for each record onto a single node per record. A MAP node is introduced to make it easier to locate different data elements in the output. See the "Output," the "Details and Features," and the "Examples" sections for more information.

Quick lookup. If this flag is passed, the Finder assumes the passed value is in internal format. The Finder performs NO transforms of the input value, but only tries to find the value in the specified lookup indexes. Therefore, when the Q flag is passed, the lookup is much more efficient. If the FLAGS parameter does not contain a Q, the Finder assumes the lookup value is an external or user-entered value and performs all normal transforms as documented below.

Unscreened lookup. This flag makes the Finder ignore any whole file screen (stored at ^DD(file#,0,"SCR")) on the file specified in the FILE parameter.

NOTE: Passing this flag does not make the Finder ignore the SCREEN parameter.

EXact matches only. The Finder returns every exact match to the lookup value on the requested Index(es). Any partial matches present in the file are ignored, and transforms, such as changing the lookup value to uppercase, are not performed. For example, in the scenarios described under the O flag, the Finder behaves identically in the first situation, but under the second it returns no matches, since "EINSTEIN,ALBERT" is not an exact match to "EINSTEIN". If both the O and X flags are passed, the O flag is ignored. If the lookup is done on a compound index, exact matches must be made for every data value subscript in the index.

(Required) The lookup value(s). These should be in external format as they would be entered by an end-user, unless the Q flag is used. Except for special lookup values listed below, the lookup value is matched to entries on the lookup INDEXES specified in the call. If the lookup index is compound, then lookup values can be provided for each of the data value subscripts in the index. In that case, VALUE is passed by reference as an array where VALUE(n) represents the lookup value to be matched to the nth subscript in the index. If only one lookup value is passed in VALUE, it is assumed to apply to the first data value subscript in the index. 

In addition, certain values generate special behavior by the Finder as follows:

1. Control characters. This value always results in no matches. Control characters are not permitted in the database.
   
   
2. ^ (Up-arrow [shift-6]). This value always results in no matches. This single character value signifies to VA FileMan that the current activity should be stopped.
   
   
3. "" (The empty string). On single field indexes, this value always results in no matches. The empty string, used by VA FileMan to designate fields that have no value, cannot be found in FileMan indexes. However, if the lookup uses a compound index, VALUE(n) can be null for any of the lookup values as long as at least one of them is non-null. If VALUE(1) is null, it may make the lookup slower. If VALUE(n) is null, all non-null values for that subscript position will be returned.
   
   
4. " " (The space character). This value indicates that the Finder should return the current user's previous selection from this file. This corresponds to the "space-bar-recall" feature of FileMan's user interface. If VA FileMan has no such previous selection for this user, or if this selection is now prohibited from selection somehow (see discussion of SCREEN, below), then the Finder returns no matches. The Finder itself never preserves its found values for this recall; applications wishing to preserve found values should call RECALL^DILFD. The special lookup characters should appear either in VALUE or in VALUE(1).
   
   
5. "`"-Number (accent-grave followed by a number). This indicates that the Finder should select the entry whose internal entry number equals the number following the accent-grave character. This corresponds to an equivalent feature of FileMan's user interface. If this entry is prohibited from selection, the Finder returns no match. The use of '-number input does not require passing A in the FLAGS parameter. The special lookup characters should appear either in VALUE or in VALUE(1).
   
   
6. Numbers. The Finder tries strictly numeric input as an IEN under any of the following four conditions: 1) The caller passes A in the FLAGS parameter, 2) the file has a .001 field, 3) the file's .01 field is not numeric and the file has no lookup index, or 4) The INDEXES parameter contains "#" as one of its index names. In all cases, the numeric lookup value is expected to be in either VALUE or VALUE(1). In condition 4, if the "#" is the only INDEX, and if the lookup value does not match an IEN, the lookup fails, otherwise, the Finder continues the search using the other indexes.
   
   In conditions 1, 2 and 3, strictly numeric input differs from `-numeric input in that whether or not a record corresponding to this IEN exists or is selectable, the Finder proceeds with a regular lookup, using the numeric value to find matches in the file's indexes. Even used this way, however, numeric input has the following special restriction: it is not used as a lookup value in any indexed pointer or variable pointer field (unless Q is passed in the FLAGS parameter).
   
   For example, suppose an application performs a Finder call on the EMPLOYEE file, passing a lookup value of 12; that the EMPLOYEE file points to the State file, in which Washington is record number 12; and that the EMPLOYEE file's pointer to the State file is indexed. The application would not be able to use the input value of 12 to find every employee who lives in Washington state.

(Optional) The maximum number of entries to find. If the Finder actually matches the input to this many entries, it breaks out of its search and returns what it has found so far. In such a situation, there is no way for the Finder to resume its search later where it left off. A value of "*" designates all entries.

Defaults to "*".

(Optional) The indexes the Finder should search for matches. This parameter should be set to a list of index names separated by ^ characters. This parameter specifies both which indexes to check and the order in which to check them. The caller does not need to pass the M flag for the INDEXES parameter to work properly. For example, a value of "B^C^ZZALBERT^D" specifies four indexes to check in the order shown.

If the first index passed is a compound index, only that one index can be in the list. Attempting to put more than one index in the list when the first one is compound will generate an error. If the first index in the list is a single subscript index, however, compound indexes can follow that one in the list. In that case, the lookup expects only one lookup value and only the first subscript of any compound index is checked for matches.

If no index name, or only one index name, is passed in the INDEXES parameter, and if the FLAGS parameter contains an M, then the Finder will do the search using the starting index, as well as all indexes that follow the starting one alphabetically (unless the starting index is compound - see paragraph above). See also the documentation on the M flag.

If the index is not specified, the default starting index will be "B" unless the FLAGS parameter contains a K, in which case the default will be the Uniqueness Index defined for the Primary Key on the file. 

Mnemonic cross-references folded into the specified index are included in the output.

When the first subscript of one of the indexes on the file you are searching indexes a pointer or variable pointer, then the Finder searches the pointed-to file for matches to the lookup value. Array entries can be passed in the INDEXES parameter to control this search on the pointed-to file. Suppose the name of the array is NMSPIX. Then you can set NMSPIX("PTRIX",from_file#,pointer_field#,to_file#)="^"_delimited_index_list. This array entry allows the user to pass a list of indexes that will be used when doing the search on the pointed-to file.

For example, if your file (662001) has a pointer field (5) to file 200 (NEW PERSON), and you wanted the lookup on field 5 to find entries in the NEW PERSON file only by name ("B" index), or by the first letter of the last name concatenated with the last 4 digits of the social security number ("BS5" index), set NMSPIX("PTRIX",662001,5,200)="B^BS5".

(Optional) Entry Screen. The screen to apply to each potential entry in the returned list to decide whether or not to include it. This may be set to any valid M code that sets $TEST to 1 if the entry should be included, to 0 if not. This is exactly equivalent to the DIC("S") input variable for the Classic FileMan lookup ^DIC. The Finder will execute this screen in addition to any SCR node (whole-file screen) defined on the data dictionary for the file. Optionally, the screen can be defined in an array entry subscripted by "S" (for example, SCR("S")), allowing additional screen entries to be defined for variable pointer fields as described below.

The entry screen code can rely upon the following:

The code can also safely change any of these values.

For example, "I Y<100" ensures that only records with an internal entry number less than 100 are accepted as matches. See "Details and Features" in this section for an explanation of the other conditions and screens involved in finding an entry. Defaults to adding no extra conditions to those listed in that section.

Variable Pointer Screen. If one of the fields indexed by the cross-reference passed in the INDEXES parameter is a variable pointer, then additional screens equivalent to the DIC("V") input variable to Classic FileMan lookup ^DIC can also be passed. Suppose the screens are being passed in the SCR array. Then for a simple index with just one data value field, the code can be passed in SCR("V"). For simple or compound indexes, screens can be passed for any indexed fields that are variable pointers in the format SCR("V",n) where "n" represents the subscript location of the variable pointer field on the index.

The Variable Pointer screen restricts the users ability to see entries on one or more of the files pointed-to by the variable pointer. The screen logic is set equal to a line of M code that will return a truth value when executed. If it evaluates TRUE, then entries that point to the file can be included in the output; if FALSE, any entry pointing to the file is excluded. At the time the code is executed, the variable Y(0) is set equal to the information for that file from the data dictionary definition of the variable pointer field. You can use Y(0) in the code set into the variable pointer screen parameter. Y(0) contains:

All of this information was defined when that file was entered as one of the possibilities for the variable pointer field.

For example, suppose your .01 field is a variable pointer pointing to files 1000, 2000, and 3000. If you only want the user to be able to enter values from files 1000 or 3000, you could set up SCR("V") like this:

S SCR("V")="I +Y(0)=1000!(+Y(0)=3000)"

(Optional) The text to accompany each found entry to help identify it to the end user. This should be set to M code that calls the EN^DDIOL utility to load identification text. The identification text generated by this parameter is listed AFTER that generated by any WRITE identifiers on the file itself. The code should not issue WRITE commands.

For example, a value of "D EN^DDIOL(""KILROY WAS HERE!"")" would include that string with each entry returned, as a separate node under the "ID","WRITE" nodes of the output array.

This code relies upon all of the same input as the SCREEN parameter described above and can safely change the same things. Defaults to no code.

(Optional) The array that should receive the output list of found entries. This must be a closed array reference and can be either local or global.

If the TARGET_ROOT is not passed, the list is returned descendent from ^TMP("DILIST",$J).

(Optional) The array that should receive any error messages. This must be a closed array reference and can be either local or global. For example, if MSG_ROOT equals "OROUT(42)", any errors generated appear in OROUT(42,"DIERR").

If the MSG_ROOT is not passed, errors are returned descendent from ^TMP("DIERR",$J).

The examples in this section assume that the output from the Finder was returned in the default location descendent from ^TMP("DILIST",$J), but it could just as well be in an array specified by the caller in the TARGET_ROOT parameter described above.

There are two different formats possible for the output, (1) Standard output format, and (2) Packed output  (format returned when the P flag is included in the FLAGS parameter).

1. Standard Output Format

The format of the Output List is:

• Header Node

  Unless the Finder has run into an error condition, it will always return a header node for its output list, even if the list is empty, because no matches were found. The header node, on the zero node of the output array, has this format:

  ^TMP("DILIST",$J,0) = # of entries found ^ maximum 
  requested ^any more? ^ results flags
  

  1. The # of entries found will be equal to or less than the maximum requested.
     
     
  2. The maximum requested should equal the NUMBER parameter, or, if NUMBER was not passed, "*".
     
     
  3. The any more? value is 1 if there are more matching entries in the file than were returned in this list, or 0 if not.
     
     
  4. The results flag at present is usually empty. If the output was packed and some of the data contained embedded "^" characters, the results flag contains the H flag. In the future the Finder may return other flags as well in this piece, so check whether it contains H, not whether it equals it. For more information see "Details and Features."

• Record Data

  Standard output for the Finder returns its output with each field of each matching record on a separate node. Records are subscripted in this array by arbitrary sequence number that reflects the order in which the record was found.

  • .01 Field

    Unless suppressed with the "@" in the FIELDS parameter (the suggested practice), the .01 field of each record is returned under the 1 subtree of the array, in internal format.

    ^TMP("DILIST",$J,1,seq#) = .01_field_value_in_
    internal_format

    NOTE: This is different from the Lister, which returns the indexed field values in the 1 subtree.

  • IEN

    Each record's IEN is returned under the 2 subtree:

    ^TMP("DILIST",$J,2,seq#) = IEN

  The other values returned for each record are grouped together under the "ID" subtree, then by record.

  • Field Values or Field Identifiers

    The output format is the same whether the field value is one of the Field Identifiers from the data dictionary for the file or the field was requested in the FIELDS parameter.

    Field identifiers and field values are subscripted by their field numbers. Each node shows up as:

    ^TMP("DILIST",$J,"ID",seq#,field #) = field_
    value

    If both the "I" and "E" suffix are specified, an additional subscript level with the values of "E" and "I" is used to distinguish the external and internal values of the field. If a field is only returned in one format, the extra subscript is never included. Values output with the extra format specifier look like:

    ^TMP("DILIST",$J,"ID",seq#,field#,"E" or "I") 
    = field_value

  • Output for field specifier "IX" in FIELDS

    A field specifier of "IX" in the FIELDS parameter retrieves the value of the indexed field(s). In the output, the values of these fields are returned as follows, where the final subscript is a sequential number indicating the subscript location in the index.

    ^TMP("DILIST",$J,"ID",seq#,0,1) = first_
    subscript_index_value
    
    ^TMP("DILIST",$J,"ID",seq#,0,2) = second_
    subscript_index_value
     

    If both the "I" and "E" suffix are specified, an additional subscript level with the values of "E" and "I" is used to distinguish the external and internal values from the index. If the subscript on the index is not derived from a field, i.e. if it's a computed subscript, then the internal and external value both will be the same, the value directly from the index.

  • WRITE Identifiers

    WRITE (display-only) identifiers are grouped under the "WRITE" subtree of the "ID" tree, then by record number. It is the caller's responsibility to ensure that none of the WRITE identifiers issue direct READ or WRITE commands and that they issue any output through EN^DDIOL so it can be collected by the Finder. The output from all the WRITE identifiers for a single record is listed as individual lines of text:

    ^TMP("DILIST",$J,"ID","WRITE",seq#,line #) = 
    text generated by WRITE IDs
    

  • IDENTIFIER parameter

    Any text generated by the caller's IDENTIFIER parameter is returned in the last lines of the WRITE identifier text.

• Map Node for Unpacked Format 

  In order to facilitate finding information in the output, a Map Node is built for unpacked format. This node is returned in ^TMP("DILIST",$J,0,"MAP").

  The Map node for unpacked format describes Field Identifier data in the "ID" output data nodes. It contains "^"delimited pieces described below. The position of the piece in the map node corresponds to the order in which it can be found in the "ID" output nodes. If the data is returned in internal format, the piece will be followed by "I" (ex., "2I" means that the internal value of field 2 was returned in the output).

  • #: Individually requested field number, where # is the field number, for each field requested in the FIELDS parameter
  • FID(#): Field Identifier, where # is the field number.

If the P flag is used to request packed output, the Finder packs all the return values into one output node per record. You must ensure that all requested data will fit onto a single node. Overflow causes error 206. Return values containing embedded "^" characters make the Finder encode the output data using HTML encoding (described in "Details and Features").

• Header Node

  Identical to Standard Output Format

• Record Data

  Values in the output are delimited by "^" characters. Piece 1 is always the IEN. The values of other pieces depend on the value of the FIELDS parameter. If the FIELDS parameter is not passed, each record's packed node will follow this format:

  ^TMP("DILIST",$J,seq#,0)=IEN^Internal_.01_field_value^
  field_Identifiers^Write_Identifiers^Output_from_
  Identifier_parameter
  

  Field Identifiers are sequenced by field number. Output values specified by the FIELDS parameter are packed in the order in which they occur in the FIELDS parameter. WRITE identifiers are packed in the same order as their subscripts occur in the ID subtree of the file's data dictionary.

  To parse the output of the packed nodes, use the MAP node described below.

• Map Node for Packed Format 
• Because the packed format is not self-documenting and because individual field specifiers such as FID can correspond to a variable number of field values, the Finder always includes a map node when returning output in Packed format. This node is returned in ^TMP("DILIST",$J,0,"MAP").

  Its value resembles a data node's value in that it has the same number of ^-pieces, but the value of each piece identifies the field or value used to populate the equivalent location in the data nodes. The possible values for each piece in the map node are:

  • IEN: the IEN
  • 01: the .01 field
  • FID(#): Field identifier, where # is the field number of the identifier
  • WID(string): WRITE identifier, where string is the value of the subscript in the ^DD where the identifier is stored (such as "WRITE")
  • IDP: Identifier parameter
  • IX(n): Indexed field values, where "n" refers to the subscript position in the index.
  • #: Individually requested field, by field number

  NOTE: For any piece except IEN, WID or IDP, if the internal value is to be returned, the piece will be followed by "I". Thus instead of IX(1), you would see IX(1)I, indicating that the internal index value was being returned.

  For example, the map node for a Finder call on the Option file, if FIELDS=> "3.6I;3.6;4", might look like this:

  ^TMP("DILIST",$J,0,"MAP") = "IEN^.01^3.6I^3.6^4"

If the "Use" flag for an index entry in the new INDEX file is set to "L" for Lookup, the index name must be "B" or must alphabetically follow "B". Also, traditional indexes whose names follow "B" are considered to be Lookup type indexes.

What does this mean? For a Finder call (FIND^DIC or $$FIND1^DIC), it means that if M is passed in the FLAGS parameter and a list of indexes is not specified in the INDEXES parameter, then FileMan will automatically use any lookup type index it finds by ordering through the index name alphabetically, starting with the beginning index ("B", unless a different one is specified in the input parameters). Any index, however, can be used for lookup if it is specified in the INDEXES parameter. The developer should be careful to make sure the MUMPS-type indexes are formatted similar to VA FileMan regular indexes, with the data subscripts followed by the IEN at the level of the file/subfile passed in the FILE input parameter.

Valid Entry Conditions. To be considered for selection, an entry must have a properly formatted index to get the Finder's attention and a defined zero-node with a non-null first piece.

File Pre-Lookup Action (7.5 Node). Prior to performing any search of the database whatsoever, the Finder executes the 7.5 Node for the file. This code may alter the variable X, the lookup value, to alter the value used by the Finder in its search.

NOTE: The 7.5 node only works on a simple index, not a compound one. It assumes just one lookup value X. 

Call Pre-Selection Action. The SCREEN parameter is executed once a potential match has been identified (as described under the "Input Parameters" section).

File Pre-Selection Action. If the file has a pre-selection action defined (the SCR node), then after passing the pre-selection action for the call, the entry must also pass the action for the whole file.

For most values on most indexes, an input value partially matches an entry if the index value begins with the input value (e.g., index value of "EINSTEIN,ALBERT" partially matches input value of "EINSTEIN"). The exception is numeric input. On a numeric field's index, a numeric input must match exactly.

If the lookup value is numeric but the cross-referenced field is free-text, the Finder will find all partial matches to the numeric lookup value. For example, lookup value 1 matches to 1, 199, 1000.23 and 1ABC. 

Although the Finder honors the space bar recall feature whenever passed the input value " ", selections made through the Finder are not stored for later use by space bar recall because the Finder has no way of knowing whether the selection results from interaction with the user. Only deliberate user selections should affect the space bar recall value. As a result, to support this feature, applications should call RECALL^DILFD when managing the user interface whenever the user makes a selection.

The original lookup value(s) passed to the Finder are not the only values used during the lookup. Certain transforms are done on the original lookup value and matches are made for these transformed values along with the original ones. The Q flag suppresses all of these transforms and looks on the index(s) only for the original lookup value. See "Upper Case", "Long Input", "Comma-Piecing" and "Data Type Transforms" immediately below.

The first basic transform ensures that lookups succeed when users leave their Caps Lock keys off. If the VALUE parameter contains any lower case characters, the Finder will also look for an all-upper-case version of the value.

The second basic transform ensures that lookups work properly when lookup and field values are longer than the maximum length of a data-values subscript in the index. (This is 30 characters for traditional indexes, but is set by the developer for indexes defined in the new INDEX file). 

The third and final basic transform provides a special feature of VA FileMan's lookup. This feature, known as comma-piecing, helps the user enter fewer characters to distinguish between similar entries. FileMan uses lookup values that contain embedded commas to build a pattern match based on all the comma-pieces. For example, distinguishing between "KENNEDY,ROBERT FRANCIS" and "KENNEDY,JOHN FITZGERALD" would normally take nine keystrokes-"KENNEDY,J"-but comma-piecing lets the user do it in three: "K,J".

Although commas are used to trigger the comma-piecing feature, the characters used to break up the entry in the file can be any kind of punctuation, not only commas. For example, "T,R" matches "THE ROAD LESS TRAVELED".

If the new C flag is used in the FLAGS parameter, then the second comma piece of the lookup value can be a match to any of the pieces in the file entry following the first one.  So, for example, "B,S" distinguishes "BACH,JOHANN SEBASTIAN" from his sons "BACH,JOHANN CHRISTIAN" and "BACH,JOHANN CHRISTOPH FRIEDRICH".

Indexes store the internal format of fields values, but users typically enter the external format as lookup values. Therefore, the Finder attempts to do conversions of the lookup values when it searches an index on a Date, Set of Codes, Pointer or Variable Pointer field.

For example, a lookup value of "t" would also be evaluated as today's date in internal FileMan format, if the Finder is searching the index on a date type field, since VA FileMan normally recognizes a user entry of "T" at a date prompt as meaning "TODAY".

If a Q flag is passed in the FLAGS parameter, no data type transforms are attempted.

NOTE: The data type transform for indexes on pointer and variable pointer fields involves a complete lookup on the pointed-to file. For example, if an application calls the Finder with the input value "W" on a file with an indexed pointer to the State file, the Finder locates every state starting with W (Washington, West Virginia, Wisconsin and Wyoming). It will return every record in the pointing file that points to one of those states.

Also, if the pointed-to file has indexed pointers or variable pointers, the search continues to these pointed-to files.

Therefore, to make more efficient searches, and to find just the entries desired, applications should make use of all available features of the Finder to narrow down the search. For example, use the INDEXES parameter when appropriate to limit the list of indexes searched, and the B flag when appropriate to make sure that only the "B" index is searched on any pointed-to file. 

Since the Finder uses the "^" character as its delimiter for Packed output, it cannot let any of the data contain that character. If any does, it will encode all of the data using an HTML encoding scheme.

In this scheme, all "&" characters are replaced with the substring "&amp;" and all "^" characters with the string "&#94". This keeps the data properly parsable and decodable. The data for all records found, not just the ones with embedded "^"s, will be encoded if embedded "^"s are found in the data of any of the records.

If the Finder has encoded the output, it will include an H flag in ^-piece four of the output header node.

Data can be decoded using the VA FileMan library function call $$HTML^DILF(encoded string,-1). It can properly decode individual fields or complete packed data nodes.

The Finder executes each individual WRITE ID node from the data dictionary. If an individual node results in creating multiple lines in the output from the EN^DDIOL call(s) it contains, then in Standard Output Format the results will appear on multiple lines in the output array. Thus, there is not a direct correlation between the number of WRITE ID nodes and the number of nodes that will be returned in the output array of a Finder call for each record. In Packed output format, each WRITE ID node appears in a separate "^" piece, and line feeds are designated with a tilde "~" character.

If a field is listed multiple times in the FIELDS parameter, it is returned multiple times in Packed output, but only once in unpacked output. This is because the field number is one of the subscripts of unpacked output. The exception is when the occurrences are for different formats, internal and external.