VA FileMan Programmer Manual: $$FIND1^DIC( )

Contents:

Main

Database Server (DBS) API

$$FIND1^DIC( ): Finder (Single Record)

This extrinsic function finds a single record in a file based on input value(s). If more than one match is found, the function returns an error. The caller must specify a file number and the input value(s) to be used for the lookup. The caller can also specify the index(s) to be used in the search, and can also pass screening logic.

NOTE: $$FIND1 does NOT honor the Special Lookup or Post-Lookup Action nodes defined in the data dictionary for a file.

Format

$$FIND1^DIC(FILE,IENS,FLAGS,[.]VALUE,[.]INDEXES,[.]SCREEN,MSG_ROOT)

Input Parameters

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.
IENS	(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.
FLAGS	(Optional) Flags to control processing. This parameter lets the caller adjust the Finder's algorithm. The possible values are:
	A	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. 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	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.
	C	The C flag causes the Finder to 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".
	K	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.
	M	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.
	O	Only find an exact match if possible. The Finder first searches for an exact match on the requested Index(es); if one is found, it is returned. Only if it does not find one in the file does it search for a 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. NOTE: The presence of a partial match does not constitute an error condition, because a single exact match is present. If the FLAGS parameter does not contain O (or an X, see below), the presence of both partial and exact matches is treated as an error condition. 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.)
	Q	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.
	U	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.
	X	EXact match only. The Finder returns only an 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 match, 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.
[.]VALUE	(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: Control characters. This value always results in no matches. Control characters are not permitted in the database. ^ (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. "" (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. " " (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 VA FileMan's user interface. If FileMan has no such previous selection for this user, or if this selection is now prohibited from selection somehow (see discussions 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). "`"-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). 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 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. (This parameter is revised.)
[.]INDEXES	(Optional) The indexes the Finder should search for a match. 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 given order. 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 documention 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". (This parameter is revised.)
[.]SCREEN	(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:
	Naked indicator	Zero-node of entry's record.
	D	Index being traversed.
	DIC	Open global reference of file being traversed.
	DIC(0)	Flags passed to the Finder.
	Y	Record number of entry under consideration.
	Y() array	For subfiles, descendents give record numbers for all upper levels. Structure resembles the DA array as used in a call to the classic FileMan edit routine ^DIE.
	Y1	IENS equivalent to Y array.
	The code can also safely change any of these values. For example, "I Y>99" ensures that only a record numbered 100 or higher can be accepted as a match. See "Details and Features" in this section for an explanation of the other conditions and screens involved in finding an entry. If duplicate entries exist, but only one passes the screens, then that one is returned and no error is generated. 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 for 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 user's 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:
	^-Piece	Contents
	Piece 1	File number of the pointed-to file.
	Piece 2	Message defined for the pointed-to file.
	Piece 3	Order defined for the pointed-to file.
	Piece 4	Prefix defined for the pointed-to file.
	Piece 5	y/n indicating if a screen is set up for the pointed-to file.
	Piece 6	y/n indicating if the user can add new entries to the pointed-to file.
	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)" (This parameter is revised.)
MSG_ROOT	(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).

Output

The function evaluates to an internal entry number (IEN) if a single match is found, 0 if no matches are found, or "" if an error occurred.

Examples

Example 1

Here we look for an option DIFG on the OPTION file. We use the M flag to search all indexes and the X flag to specify that we want exact matches only. It returns the IEN of the entry found.

>W $$FIND1^DIC(19,"","MX","DIFG","","","ERR")
327

Example 2

This time we look for an option that is not on the OPTION file. We set up the call exactly the same as Example 1. This time it returns 0 because no matching entry was found.

>W $$FIND1^DIC(19,"","MX","DIFG ZZZZ","","","ERR")
0

Example 3

Now we'll do the exact same call as in Example 1, but this time we won't include the X flag, so it will find not only "DIFG", but also any partial matches to "DIFG". Since there are several, it can't find just one match, so the call fails. The return is null and an error message is returned as well.

>W $$FIND1^DIC(19,"","M","DIFG","","","ERR")
DIERR=1^1

ERR("DIERR")=1^1
ERR("DIERR",1)=299
ERR("DIERR",1,"PARAM",0)=2
ERR("DIERR",1,"PARAM",1)=DIFG
ERR("DIERR",1,"PARAM","FILE")=19
ERR("DIERR",1,"TEXT",1)=More than one entry matches the value(s) 'DIFG'.
ERR("DIERR","E",299,1)=

Example 4

Now we'll do two different calls to find an entry on a test file. There are two entries whose .01 field equals "ADDFIFTEEN". In the first call, we'll do the lookup on the "B" index and the call fails because there are two entries that match the lookup value.

>W $$FIND1^DIC(662001,"","","ADDFIF","B","","ERR")

>ZW ERR
ERR("DIERR")=1^1
ERR("DIERR",1)=299
ERR("DIERR",1,"PARAM",0)=2
ERR("DIERR",1,"PARAM",1)=ADDFIF
ERR("DIERR",1,"PARAM","FILE")=662001
ERR("DIERR",1,"TEXT",1)=More than one entry matches the value(s) 'ADDFIF'.
ERR("DIERR","E",299,1)=

But if we try the call again and this time use the "BB" index for the file, which indexes the .01 field NAME and also field 1, DATE OF BIRTH, we can pass lookup values for both the fields, and the call is successful because we now have a single match. The two entries with the same .01 field have different values in their DATE OF BIRTH field.

>K VAL S VAL(1)="ADDFIF",VAL(2)="1/1/69"

>W $$FIND1^DIC(662001,"","",.VAL,"BB","","ERR")
15

Error Codes Returned

120	Error occurred during execution of a VA 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.
299	More than one entry matches that value.
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.

Details and Features

The details and features of $$FIND1^DIC and FIND^DIC are the same except that FIND^DIC has three features ("HTML Encoding," "WRITE ID nodes," and "Repeating a field in FIELDS parameter") that $$FIND1^DIC does not have. The table below describes the details and features of $$FIND1^DIC.

Lookup Index	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.
Screens Applied	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. (Revised) 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.
Partial Matches	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.
Upper Case	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.
Long Input	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). (Revised)
Comma-piecing	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. VA 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. (Revised) 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. (Revised)

Reviewed/Updated: March 10, 2007