|Contents:||Main||Chapter||See Also:||Getting Started Manual||Advanced User Manual|
This procedure finds records in a file based on input value(s). The caller must specify a file number and the input values to be used for the lookup. The caller can also specify the index(s) to be used in the search, the data to output, and a number of records to retrieve. The caller can also pass screening logic. By default, the Finder returns the IEN and the .01 field of the entries along with all identifiers. The developer can override the default output and return other information for the entries.
This call was designed as a non-interactive lookup, to find entries that are at least a partial match to the lookup values input to the call. This procedure cannot file data or add new records.
NOTE: The Finder does NOT honor the Special Lookup or Post-Lookup Action nodes defined in the data dictionary for a file.
(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.
If you do not pass anything in the FIELDS parameter, the Finder returns:
If you do pass a FIELDS parameter, the Finder returns (unless you use the @ field specifier):
(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.
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:
(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.
The format of the Output List is:
2. Packed Output Format
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").
First we do a lookup on the Option file, using the "C" index (Upper Case Menu Text). We'll let the Finder return default output, so we get the .01 field, the IEN, and the Identifier field (#1, Menu Text).
>D FIND^DIC(19,"","","","STAT","","C","","","OUT") OUT("DILIST",0)=2^*^0^ OUT("DILIST",0,"MAP")=FID(1) OUT("DILIST",1,1)=DISTATISTICS OUT("DILIST",1,2)=ZISL STATISTICS MENU OUT("DILIST",2,1)=15 OUT("DILIST",2,2)=187 OUT("DILIST","ID",1,1)=Statistics OUT("DILIST","ID",2,1)=Statistics Menu
Here we look on the OPTION file for entries that are at least partial matches to "DIS". We use the "B" index and, since we don't include the M flag to search multiple indexes, we look ONLY on the "B" index. We use the "@" in the FIELDS parameter to suppress the default values and specify that we want the .01 field NAME, field 1 DESCRIPTION, and the index values in the output.
>D FIND^DIC(19,"","@;.01;1;IX","","DIS",5,"B","","","OUT") OUT("DILIST",0)=2^5^0^ OUT("DILIST",0,"MAP")=IX(1)^.01^1 OUT("DILIST",2,1)=11 OUT("DILIST",2,2)=15 OUT("DILIST","ID",1,0,1)=DISEARCH OUT("DILIST","ID",1,.01)=DISEARCH OUT("DILIST","ID",1,1)=Search File Entries OUT("DILIST","ID",2,0,1)=DISTATISTICS OUT("DILIST","ID",2,.01)=DISTATISTICS OUT("DILIST","ID",2,1)=Statistics
Next, we do a call almost identical to Example 2, but this time we use the M flag to indicate that we want to search all the lookup indexes starting from "B". This time we get more records back and looking at the index values in the entries OUT("DILIST","ID",seq#,0,subscript_location), we see that the new entries were found on an index other than the "B" index (since the values don't match the .01 field). In fact, they were found on the index for the field UPPER CASE MENU TEXT (index "C" on the file).
>D FIND^DIC(19,"","@;.01;1;IX","M","DIS",5,"B","","","OUT") OUT("DILIST",0)=5^5^1^ OUT("DILIST",0,"MAP")=IX(1)^.01^1 OUT("DILIST",2,1)=11 OUT("DILIST",2,2)=15 OUT("DILIST",2,3)=468 OUT("DILIST",2,4)=470 OUT("DILIST",2,5)=469 OUT("DILIST","ID",1,0,1)=DISEARCH OUT("DILIST","ID",1,.01)=DISEARCH OUT("DILIST","ID",1,1)=Search File Entries OUT("DILIST","ID",2,0,1)=DISTATISTICS OUT("DILIST","ID",2,.01)=DISTATISTICS OUT("DILIST","ID",2,1)=Statistics OUT("DILIST","ID",3,0,1)=DISK DRIVE RAW DATA STATISTICS OUT("DILIST","ID",3,.01)=XUCM DISK OUT("DILIST","ID",3,1)=Disk Drive Raw Data Statistics OUT("DILIST","ID",4,0,1)=DISK DRIVE REQUEST QUEUE LENGT OUT("DILIST","ID",4,.01)=XUCM DSK QUE OUT("DILIST","ID",4,1)=Disk Drive Request Queue Length OUT("DILIST","ID",5,0,1)=DISK I/O OPERATION RATE OUT("DILIST","ID",5,.01)=XUCM DSK IO OUT("DILIST","ID",5,1)=Disk I/O Operation Rate
In this example, we'll use the K flag to do a lookup on a file with a Primary Key made up of the .01 field (NAME) and field 1 (DATE OF BIRTH). We'll suppress all of the output with "@" and then ask only for both the internal and external index values. Notice that the P flag causes the output to be returned in Packed format. The MAP node tells us what is in each "^" piece of the output.
>K VAL S VAL(1)="ADD",VAL(2)="01/01/69"
>D FIND^DIC(662001,"","@;IXIE","PK",.VAL,"","","","","OUT") OUT("DILIST",0)=1^*^0^ OUT("DILIST",0,"MAP")=IEN^IX(1)I^IX(2)I^IX(1)^IX(2) OUT("DILIST",1,0)=15^ADDFIFTEEN^2690101^ADDFIFTEEN^JAN 01, 1969
Here we'll demonstrate how the B flag works. We have a file whose .01 field points to the NEW PERSON file. When we do a lookup without the B flag, we find several entries, but if you look at the .01 field, you see that not all of them begin with our lookup value "M". The entry "CALIFORNIA,MR" was found because his initials "MC" begin with "M" and "WYNNETTE,TAMMY" was found because her nickname "MILLY" begins with "M".
>D FIND^DIC(662002,"","@;.01","P","M","","B","","","OUT") OUT("DILIST",0)=5^*^0^ OUT("DILIST",0,"MAP")=IEN^.01 OUT("DILIST",1,0)=7^CALIFORNIA,MR OUT("DILIST",2,0)=3^MANN,MANFRED OUT("DILIST",3,0)=4^MITTY,WALTER OUT("DILIST",5,0)=1^WYNETTE,TAMMY OUT("DILIST",6,0)=13^WYNETTE,TAMMY
When we use the B flag, the FINDER looks ONLY at the "B" index of the NEW PERSON file.
>D FIND^DIC(662002,"","@;.01","PB","M","","B","","","OUT") >ZW OUT OUT("DILIST",0)=2^*^0^ OUT("DILIST",0,"MAP")=IEN^.01 OUT("DILIST",1,0)=3^MANN,MANFRED OUT("DILIST",2,0)=4^MITTY,WALTER
This example shows use of the new INDEX parameter array that can control lookup on a pointed-to file. In this example, the .01 field of our file 662002 points to the New Person file 200. Here is a demonstration of the different results you get when you control the list of indexes used when the Finder goes off to file 200 to look for matches to your lookup value. We show the same call, with and without the new INDEX parameter array.
First we make a call without the new parameter, using a lookup value of "T", and looking at the "B" and "E" indexes on our starting file 662002. There are many lookup indexes on the pointed-to file 200 (the NEW PERSON file), including indexes on both the NICKNAME and the INITIALS field. Because we didn't specify which indexes to use, FileMan uses all lookup indexes during the lookup on the pointed-to file. In this call, we pick up several entries. The NICKNAME for Roger Marsh happens to be "TOAD", and the INITIALS field for Tammy Wynette is "TW".
This time, INDEX still contains "B" and "E", so we still look at those indexes on our starting file 662002, but we set the new parameter so that we only look at the "B" and "BS5" indexes on the pointed-to file 200. This time we do not find any entries whose INITIALS or NICKNAME field start with "T". We just pick up the person whose last name starts with "T".
TKW("DILIST",1,0)=12^TIMOTHY, GREG ^12^TIMOTHY,GREG
|120||Error occurred during execution of a FileMan hook.|
|202||An input parameter is missing or not valid.|
|204||The input value contains control characters.|
|205||The File and IENS represent different subfile levels.|
|206||The data requested for the record is too long to pack together.|
|207||The value is too long to encode into HTML.|
|301||The passed flags are unknown or inconsistent.|
|304||The IENS lacks a final comma.|
|306||The first comma-piece of the IENS should be empty.|
|401||The file does not exist.|
|402||The global root is missing or not valid.|
|406||The file has no .01 field definition.|
|407||A word-processing field is not a file.|
|420||The index is missing.|
|501||The file does not contain that field.|
|520||That kind of field cannot be processed by this utility.|
|8090||Pre-lookup transform (7.5 node).|
|8095||First lookup index is compound, so "M"ultiple index lookups not allowed.|
The Finder may also return any error returned by $$EXTERNAL^DILFD.
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.
|Space Bar Recall||
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.
|Lookup Value Transforms List||
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".
|Data Type Transforms||
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 "&" and all "^" characters with the string "^". 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.
|WRITE ID 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.
|Repeating a Field in FIELDS parameter||
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.
Reviewed/Updated: October 2016