Open lookup file

Syntax

Open lookup file {lookup-name,data-file-name,file-class-name,index-field}
Open lookup file lookup-name,data-file-name,file-class-name,index-field    (Studio 10 and later)

Description

This command opens an Omnis data file for use as a lookup file. You give each lookup file a reference name which you use in subsequent lookup() functions to select a particular data file and file class. You can open any Omnis data file as a lookup file, including any data file accessed via the Omnis Data Bridge (ODB).

In a lookup file, you can use the file classes to look up field values based on an indexed search. Each file class should consist of at least two fields: the first is the index (usually a character field), the second is any field type. For example, the data file Lookup.df1 has a file class called fCities with the following structure:

The parameters for Open lookup file are separated by ",". The first parameter is a label that you create to become the reference to that lookup "channel". If you omit this label, Omnis assumes that you will use only one lookup file whereupon you can use lookup() without its first parameter. The label you give to each lookup is case-insensitive and if you use the same one twice, the previous lookup file is closed. A flag true is returned if the data file is found and opened.

The example at the bottom opens a data file called Lookup.df1 and assigns the label "City" to the lookup channel. The City lookup uses the file class fCities within that data file and uses the first index to search for the required data. The OK message uses lookup() to search the first indexed field for an exact match with the value "I". If the match is found, the value of field 2 in the matched record is returned and displayed as part of the OK message. If no match is found, lookup() returns an empty value.

Note that the index and field are specified as numbers because your particular library may not include the file class used in the lookup data file. If you omit either number, the default is to use the first field as the index, and the second as the field value to be returned in the lookup() function.

Omnis opens the data file using the following rules. Omnis first tries to open the file using the supplied data-file-name. If this fails, and if the data-file-name does not contain any special characters used in pathnames (for example, under Windows ‘:’ and ‘\’), then Omnis searches for the file.

Under Windows and Linux, Omnis searches the paths included in the Omnis environment variable. The Omnis environment variable must contain a semicolon separated list of pathnames, for example:

C:\OMNIS\LOOKUPS#D:\OMNIS\LOOKUPS

Under macOS, Omnis searches the System folder, Omnis folder and then the root of each mounted volume, in that order.

The flag is set if the lookup is successful, that is, the data file is opened, the file slot exists and the indexed field is indeed indexed. The lookup file is closed if the command is reversed (see Begin reversible block).

You can close lookup files using Close lookup file, but this is not necessary: all lookup files associated with a library are closed automatically when the library quits.

You can maintain the data within the lookup file from within the library by:

• Adding the appropriate file classes to your library,

• Changing the data file to the lookup file using Open data file,

• Opening a window and editing/ inserting data in the usual way, and

• Returning to the original data file.

You can also load multiple data files with Open data file.

Example

Open lookup file {City,Lookup.df1,fCities,1}
If flag true 
  OK message {The city you require is [lookup('City','I',2)]}
End If 
# You can open more than one file class within a particular data file by assigning a different label to each lookup 
Open lookup file {City2,Lookup.df1,fCities2}
Open lookup file {City,Lookup.df1,fCities}
Open lookup file {Country,Lookup.df1,fCountries}
# You can also open a lookup file accessed using the Omnis Data Bridge (ODB) 
Open lookup file {City,odb://127.0.0.1:5900:LookUpData,fCities,1}