(Required) The file number or an explicit global root in the form ^GLOBAL( or ^GLOBAL(X,Y,.

(Optional) A string of alphabetic characters which alter how DIC responds. At a minimum this string must be set to null. A detailed description of these characters can be found later in this section, under DIC(0) Input Variables in Detail.

NOTE: If DIC(0) is null or undefined, no terminal output will be generated by the DIC routine.

The acceptable characters are:

If DIC(0) does not contain an A, then the variable X must be defined equal to the value you want to find in the requested Index(es).

If a lookup index is on a pointer or variable pointer field, FileMan will search the "B" index on the pointed-to file for a match to the lookup value X (unless the developer uses the DIC("PTRIX") array to direct the search to a different index on the pointed-to file).

If the lookup index is compound (i.e., has more than one data subscript), then X can be an array X(n) where "n" represents the position in the subscript. For example, if X(2) is defined, it will be used as the lookup value to match to the entries in the second subscript of the index. If only the lookup value X is passed, it will be assumed to be the lookup value for the first subscript in the index, X(1).

(Optional) A prompt that is displayed prior to the reading of the X input. If DIC("A") is not defined, the word Select, the name of the file, [i.e., $P(^GLOBAL(0),"^",1)], a space, the LABEL of the .01 field, and a colon will be displayed. If the file name is the same as the LABEL of the .01 field, then only the file name will be displayed. DIC(0) must contain an A for this prompt to be issued. For example, if the EMPLOYEE file had a .01 field with the LABEL of NAME, then FileMan would issue the following prompt:

    Select EMPLOYEE NAME:  

By setting DIC("A")="Enter Employee to edit: ", the prompt would be:

    Enter Employee to edit: 

Notice that it is necessary for the prompt in DIC("A") to include the colon and space at the end of the prompt if you want those to be displayed.

If the lookup index is compound (i.e., has more than one data subscript), then DIC("A") can be an array DIC("A",n) where "n" represents the position in the subscript. For example, DIC("A",2) will be used as the prompt for the second subscript in the index. If only the single prompt DIC("A") is passed, it will be assumed to be the prompt for the first subscript in the index DIC("A",1).  

If DIC("A",n) is undefined for the "n^th" subscript, then the "Lookup Prompt" field for that subscript from the INDEX file will be used as the prompt, or if it is null, the LABEL of the field from the data dictionary.

(Optional) The default answer which is presented to the user when the lookup prompt is issued. If a terminal user simply presses the Enter/Return key, the DIC("B") default value will be used, and returned in X. DIC("B") will only be used if it is non-null.

If the lookup index is compound (i.e., has more than one data subscript), then DIC("B") can be an array DIC("B",n) where "n" represents the position in the subscript. For example, DIC("B",2) will be used as the default answer for the prompt for the second subscript in the index. If only the single default answer DIC("B") is passed, it will be assumed to be the default answer for the prompt for the first subscript in the index DIC("B",1).  

When calling DIC with LAYGO allowed, you can specify that a certain set of fields will be asked for in the case where the user enters a new entry. This list is specified by setting the variable DIC("DR") equal to a string that looks exactly like the DR-string of fields that is specified when calling ^DIE. Such a list of what VA FileMan calls forced identifiers overrides any identifiers that would normally be requested for new entries in this file.

NOTE: As of Version 22 of VA FileMan, the developer is no longer required to set DIC("P"). The only exception to this is for a few files that are not structured like a normal VA FileMan file, where the first subscript of the data is variable in order to allow several different "globals" to use the same DD. An example of this is the VA FileMan Audit files where the first subscript is the file number of the file being audited.

This variable is needed to successfully add the FIRST subentry to a multiple when the descriptor (or header) node of the multiple does not exist. In that situation, DIC("P") should be set equal to the subfile number and subfile specifier codes for the multiple. (See the "File Header" section of the Global File Structure chapter.) If the descriptor node for the multiple already exists, DIC("P") has no effect.

In order to automatically include any changes in the field's definition in DIC("P"), it is best to set this variable to the second ^-piece of the 0-node of the multiple field's definition in the DD. (See the "Field Definition" section of the Global File Structure chapter in this manual.)

Thus, for example, if file 16150 had a multiple field #9, set DIC("P") like this:

    S DIC("P")=$P(^DD(16150,9,0),"^",2)

For more information, see "Adding New Subentries to a Multiple" below.

DIC("PTRIX",f,p,t)=d where

f is the from (pointing) file number,

p is the pointer field number,

t is the pointed-to file number, and

d is an "^" delimited list of index names.

When doing a lookup using an index for a pointer or variable pointer field, this new array allows the user to pass a list of indexes that will be used when searching the pointed-to file for matches to the lookup value.

For example, if your file (662001) has a pointer field (5) to file 200 (NEW PERSON), and you wanted the lookup on file 200 to be either 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): .

    DIC("PTRIX",662001,5,200)="B^BS5"

Note that if the call allows records to be added to a pointed-to file, then the list in the "PTRIX" entry should contain the "B" index. However, the "B" index would not need to be included in the list if the first index in the "PTRIX" array entry is a compound index whose first subscript is the .01 field.

(Optional) DIC("S") is a string of M code that DIC executes to screen an entry from selection. DIC("S") must contain an IF statement to set the value of $T. Those entries that the IF sets as $T=0 will not be displayed or selectable. When the DIC("S") code is executed, the local variable Y is the internal number of the entry being screened and the M naked indicator is at the global level @(DIC_"Y,0)"). Therefore, to use the previous example again, if you wanted to find a male employee whose name begins with SMITH, you would:

    S DIC="^EMP(",DIC(0)="QEZ",X="SMITH"
    S DIC("S")="I $P(^(0),U,2)=""M"""
    D ^DIC

(Optional) Present every match to the lookup value, quitting only when user either selects one of the presented entries, enters ^^ to quit, or there are no more matching entries found.

Currently, if one or more matches are found in the first pass through the indexes, then FileMan quits the search, whether or not one of the entries is selected. Only if no matches are found in the first pass does FileMan continue on to try transforms to the lookup value. This includes transforms to find internal values of pointers, variable pointers, dates or sets.

Another feature of the "T" flag is that indexes are truly searched in the order requested. If, for example, an index on a pointer field comes before an index on a free-text field, matches from the pointer field will be presented to the user before matches to the free-text field.

When used in combination with the "O" flag, all indexes will be searched for an exact match. Then, only if none are found, will FileMan make a second pass through the indexes looking for partial matches.

If the .01 field is a variable pointer, it can point to entries in more than one file. You can restrict the user's ability to input entries from certain files by using the DIC("V") variable. It is used to screen files from the user. Set the DIC("V") variable to a line of M code that returns a truth value when executed. The code is executed after someone enters data into a variable pointer field. If the code tests false, the user's input is rejected; FileMan responds with ?? and a "beep."

If the lookup index is compound (i.e., has more than one data subscript), and if any of the subscripts index variable pointer fields, then DIC("V",n) can be passed where "n" represents the subscript position of the variable pointer field in the index. For example, if DIC("V",2) is passed in, it will be used as the screen for files pointed-to by the variable pointer field indexed in the second subscript of the index. If only the entry DIC("V") is passed, it will be assumed to be the variable pointer file screen for the first subscript in the index, DIC("V",1).  

When the user enters a value at a variable pointer field's prompt, VA FileMan determines in which file that entry is found. The variable Y(0) is set equal to 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 DIC("V") variable. 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 DIC("V") like this:

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

(Optional) An M command string which is executed when DIC displays each of the entries that match the user's input. The condition of the variable Y and of the naked indicator is the same as for DIC("S"). If DIC("W") is defined, it overrides the display of any identifiers of the file. Thus, if DIC("W")="", the display of identifiers will be suppressed.

NOTE: DIC("W") is killed by ^DIC calls.

 (Optional) The number "n" should be an integer set to the number of entries to be displayed on the screen at one time when using "?" help in a lookup. Usually, file# will be the number of the file on which you're doing the lookup. However, if doing a lookup using an index on a pointer field, and if DIC(0) contains "L", then the user also is allowed to see a list of entries from the pointed-to file, so in that case file# could be the number of that pointed-to file. For example, when doing a lookup in test file 662001, if the developer wants only five entries at a time to be displayed in question-mark help, set DIC("?N",662001)=5

 (Optional) Used to control entries displayed during online "?" help only. If provided, this index will be used to display the entries from the file specified by file#. Otherwise, VA FileMan uses the first lookup index specified for the ^DIC call. This value is used as the INDEX parameter to the Lister call to display the entries. See documentation for LIST^DIC for more information.

 (Optional) Used to control entries displayed during online "?" help only. This array can be set to define a starting value for an entry in the lookup index used to list entries from the file. Integer value "n" is associated with the "n^th" data value subscript in the index (e.g., regular old-style indexes always have just one indexed data value so "n" would be 1). If a starting value is defined for subscript "n," then starting values must also be defined for all of the subscripts preceding "n."

This information is used to set the FROM parameter for a call to LIST^DIC in order to display the entries in the file specified by file#. Therefore, the entries must meet the same rules as the FROM parameter described in that call. See documentation for LIST^DIC for detailed information.

If DIC(0) contains an "L" and the first indexed field is a pointer, then after displaying the current entries on the file, VA FileMan allows the user to see entries on the pointed-to file. In that case, the developer may request starting values for any pointed-to file in the pointer chain. If the user enters "^value" when asked whether they wish to see the entries in the file, the value entered by the user will override the starting list value passed by the developer in this array.

 (Optional) Used to control entries displayed during online "?" help only. This array can be set to define partial match value(s) for each of the "n" subscripts on the lookup index used during online help. The information is used to set the PART parameter for a Lister call to display the entries. See documentation for LIST^DIC for more information. As with DIC("?PARAM",file#,"FROM",n), if DIC(0) contains "L", the developer can define partial match values for any pointed-to file in the pointer chain.

(Optional) If this variable is set equal to the file number, then the users will be able to add a new entry to the file whether or not they have LAYGO access to the file. This variable, however, does not override any LAYGO node that may exist on the .01 field, i.e. ^DD(file#,.01,"LAYGO",#,0). M code in the LAYGO node will still be executed, and must set the truth value to TRUE for an entry to be added.

NOTE: In addition, DIC(0) must contain L to allow addition of entries to the file.

(Optional) This input variable identifies the subscript at which the data is to be stored. This means DINUM must be a canonic number and that no data exists in the global at that subscript location, e.g., $D(@(DIC_DINUM_")"))=0.

DIC always returns the variable Y. The variable Y is returned with one of these three formats:

This variable is only set if DIC(0) contains a Z. When the variable is set, it is equal to the entire zero node of the entry that was selected.

This variable also is only set if DIC(0) contains a Z. When the variable is set, it is equal to the external form of the .01 field of the entry.

The following are examples of returned Y variables based on a call to the EMPLOYEE file stored in ^EMP(:

    S DIC="^EMP(",DIC(0)="QEZ",X="SMITH"
    D ^DIC

Returned are:

    Y      = "7^SMITH,SAM"
    Y(0)   = "SMITH,SAM^M^2231109^2
    Y(0,0) = "SMITH,SAM"
	

If the lookup had been done on a file whose .01 field points to the EMPLOYEE file, the returned variables might look like this:

    Y      = "32^7"  [ Entry #32 in this file and #7 in 
                       EMPLOYEE file.]
    Y(0)   = "7^RX 2354^ON HOLD"
    Y(0,0) = "SMITH,SAM"  [.01 field of entry 7 in 
                           EMPLOYEE file]

Contains the value of the field where the match occurred.

If the lookup index is compound (i.e., has more than one data subscript), and if DIC(0) contains "A" so that the user is prompted for lookup values, then X will be output as an array X(n) where "n" represents the position in the subscript and will contain the values from the index on which the entry was found. Thus, X(2) would contain the value of the second subscript in the index. If possible, the entries will be output in their external format (i.e., if the subscript is not computed and doesn't have a transform). If the entry is not found on an index (example, when lookup is done with X=" " (the space-bar return feature)), then X and X(1) will contain the user input, but the rest of the X array will be undefined.  

This is only defined if DIC has timed-out waiting for input from the user.

This is only defined if the user entered an up-arrow.

DIC asks for input from the terminal and asks again if the input is erroneous. A response of null or a string containing ^ is accepted. Input is returned in X when DIC quits. If DIC(0) does not contain the character A, the input to DIC is assumed to be in the local variable X.

 Without the B flag, if there are cross-referenced pointer or variable pointer fields in the list of indexes to use for lookup and if DIC(0) contains "M" and there is no screening logic on the pointer that controls the lookup on the pointed-to file, then:

1. For each cross-referenced pointer field, VA FileMan checks ALL lookup indexes in each pointed-to file for a match to X (time-consuming);
2. If X matches any value in any lookup index (not just the "B" index) on the pointed-to file and the IEN of the matched entry is in the home file's pointer field cross-reference, VA FileMan considers this a match. This may perhaps not be the lookup behavior you wanted, see Examples section.

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 or variable pointer fields. This makes lookups quicker and avoids the risk of VA FileMan matching an entry in the pointed-to file based on some unexpected indexed field in that file.

Normally, when DIC does a lookup and finds an entry that matches the input, that entry is presented to the user only once even if the entry appears in more than one cross-reference. This is called cross-reference suppression and can be overridden by including a C in DIC(0). If, for example, a person with the name ZACHARY,DAVID is an entry in a file, then his name will appear in the B cross-reference of the file. If he has a nickname of ZACH which is in the C cross-reference of the file, then when a user enters ZACH as a lookup value, the name, ZACHARY,DAVID, will appear only once in the choices. But if there is a C in DIC(0), then ZACHARY,DAVID will appear twice in the choices; once as a hit in the B cross-reference and again as a hit in the C cross-reference.

The file entry names that match the input will be echoed back to the terminal screen; and if there is more than one such name, the user will be asked to choose which entry is wanted. E is important because it is the way to tell DIC that you are in an interactive mode and are expecting to be able to receive input from the user.

Prevents saving the entry number of the matched entry in the ^DISV global. Ordinarily, the entry number is saved at ^DISV(DUZ,DIC). This allows the user to do a subsequent lookup of the same entry simply by pressing the space bar and Enter/Return key. To avoid the time cost of setting this global, include an F in DIC(0).

If DIC(0) contains I, any special user-written lookup program for a file will be ignored and DIC will proceed with its normal lookup process.

You can write a special lookup program to be used to find entries in a particular file. This special program can be defined by using the Edit File option of the Utility Functions submenu (see the "Special Lookup Programs" section in the Advanced File Definition chapter.) When a lookup program is defined, VA FileMan will bypass the normal lookup process of DIC and branch to the user written program. This user written lookup program must respond to the variables documented in this section and provide the functionality of DIC as they pertain to the file.

If DIC(0) contains L and the user's input is in valid format for the file's .01 field, then DIC will allow the user to add a new entry to the file at this point (Learn-As-You-GO), as long as at least one of these four security-check conditions is true:

• The local variable DUZ(0) is equal to the @-sign.
  
  
• If Kernel's File Access Security System (formerly known as Kernel Part 3) is being used for security, the file is listed in the user's record of accessible files with LAYGO access allowed.
  
  
• If file access management is not being used, a character in DUZ(0) matches a character in the file's LAYGO access code or the file has no LAYGO access code.
  
  
• The variable DLAYGO is defined equal to the file number.

NOTE: Even if DIC(0) contains L and one of these security checks is passed, LAYGO will not be allowed if a test in the data dictionary's LAYGO node fails.

If DIC(0) contains M, DIC will do a multiple lookup on all of the file's cross-references from B on to the end of the alphabet. For example, if a given file is cross-referenced both by Name and by Social Security Number, and the user inputs 123-45-6789, DIC, failing to find this input as a Name, will automatically go on to look it up as a Social Security Number.

NOTE: For finer control in specifying the indexes used for lookup, see the alternate lookup entry points IX^DIC and MIX^DIC1.

If DIC(0) contains an uppercase N, the input is allowed to be checked as an internal entry number even if the file in question is not normally referenced by number. However, input is only checked as an IEN if no other matches are found during regular lookup.

If DIC(0) does not contain an uppercase N, the user is still allowed to select by entry number by preceding the number with the accent grave character ( ` ). When a ` is used, the lookup is limited to internal entry numbers only.

Placing an uppercase N in DIC(0) does not force IEN interpretation; it only permits it. In order to force IEN interpretation, you must use the accent grave (`) character.

NOTE: With this flag, when DIC(0) contains an L, users may be allowed to force the internal entry number when adding new entries to the file. If the user enters a number N that is not found on any of the cross-references, and if the .01 field is not numeric and the file is not DINUMed, and if VA FileMan can talk to the users (DIC(0)["E"), then the user will be asked whether they want to add the new entry, and will be prompted for the value of the .01 field. The entry will be added at the record number N that was originally entered by the user. Note that if there is a .001 field on the file, the number N must also pass the INPUT transform for the .001 field.

 If the lowercase "n" flag is put into DIC(0), then if the lookup value is numeric and if a lookup is done on a free text or set of codes field, partial matches on pure numerics will be found. Suppose a free text field has records with the values 2, 223, and 22A, and the lookup value is 2. Without the flag, only the records with the values 2 and 22A are found. With the flag, all three are found.

If DIC(0) contains the letter O, then for each index searched, FileMan looks first for exact matches to the lookup value before looking for partial matches. If an exact match is found, then FileMan returns only that match and none of the partial matches on the index. Thus if an index contained the entries "SMITH,SAM" and "SMITH,SAMUEL" and if the user typed a lookup value of "SMITH,SAM", then only the "SMITH,SAM" entry would be selected, and the user would never see the entry "SMITH,SAMUEL". Note that if partial matches but no exact matches are found in the first index(es) searched, but if exact matches are found in an index searched later, then the partial matches from the first index(es) are returned along with the exact match from the later index(es).

If DIC(0) contains Q and erroneous input is entered, two question marks (??) will be displayed and a "beep" will sound.

If DIC(0) does not contain S, the value of the .01 field and Primary Key fields (if the file has a Primary Key  ) will be displayed for all matches found in any cross-reference. If DIC(0) does contain S, the .01 field and Primary Key fields will not be displayed unless they are one of the indexed fields on which the match was made.

"T flag in DIC(0). Present every match to the lookup value, quitting only when user either selects one of the presented entries, enters ^^ to quit, or there are no more matching entries found.

Currently, if one or more matches are found in the first pass through the indexes, then FileMan quits the search, whether or not one of the entries is selected. Only if no matches are found in the first pass does FileMan continue on to try transforms to the lookup value. This includes transforms to find internal values of pointers, variable pointers, dates or sets.

Another feature of the "T" flag is that indexes are truly searched in the order requested. If, for example, an index on a pointer field comes before an index on a free-text field, matches from the pointer field will be presented to the user before matches to the free-text field. When used in combination with the "O" flag, all indexes will be searched for an exact match. Then, only if no matches are found, will FileMan make a second pass through the indexes looking for partial matches.

Normally the lookup value is expected to be in external format (for dates, pointers and such). FileMan first searches the requested index for a match to the user input as it was typed in. Then, if no match is found, FileMan automatically tries certain transforms on the lookup value.

For instance, if one of the lookup indexes is on a date field, FileMan tries to transform the lookup value to an internal date, then checks the index again. The "U" flag causes FileMan to look for an exact match on the index and to skip any transforms. Thus the lookup value must be in internal format. This is especially useful for lookups on indexed pointer fields, where the internal entry number (i.e., internal pointer value) from the pointed-to file is already known.

Ordinarily this flag would not be used along with the "A", "B", "M", "N" or "T" flags. However, in many cases it makes sense to combine this with the "X" flag.

If DIC(0) contains X, for an exact match, the input value must be found exactly as it was entered. Otherwise, the routine will look for any entries that begin with the input X. Unless 'X-act match' is specified, lowercase input that fails in the lookup will automatically be converted to uppercase, for a second lookup attempt. The difference between X and O (described above) is that X requires an exact match. If there is not one, either DIC exits or tries to add a new entry. With O, if there is not an exact match, DIC looks for a partial match beginning with the input.

If DIC(0) contains Z and if the lookup is successful, then the variable Y(0) will also be returned. It will be set equal to the entire zero node of the entry that has been found. Another array element, Y(0,0), is also returned and will be set equal to the printable expression of the .01 field of the entry selected. This has no use for Free Text and Numeric data types unless there is an OUTPUT transform. However, for Date/Time, Set of Codes and Pointer data types, Y(0,0) will contain the external format.

NOTE: As of Version 22 of VA FileMan, the developer is no longer required to set DIC("P"). The only exception to this is for a few files that are not structured like a normal VA FileMan file, where the first subscript of the data is variable in order to allow several different "globals" to use the same DD. An example of this is the VA FileMan Audit files where the first subscript is the file number of the file being audited.

NOTE: The value of the unsubscripted DA node should not be defined when doing lookups in a subfile -- that's the value you're trying to obtain!