Lookup

lookup

From a lookup file, returns the first record that matches a specified expression

lookup("Regions", in.store_no).region_name


Which matching record is returned ?

The following functions always retrieve the first matching record in the dataset:

• lookup

• lookup_local

• lookup_range

• lookup_range_local

When you need to retrieve sequential or specific matches, you exercise record-by-record control over retrieval of multiple matching records by combining calls to the lookup, lookup_next, lookup_previous, lookup_nth, and lookup_last functions.

lookup_local

Returns the first matching record that appears in a partition of a lookup file. Behaves like lookup, except that this function searches only one partition of a lookup file.

lookup_unload -

Removes from memory a previously loaded or created dynamic lookup file. Use this function to free the memory allocated by the lookup_load and lookup_create functions.

You use lookup_unload to unload a lookup file from memory that was originally loaded by lookup_load or created by lookup_create. Unlike the other lookup functions, lookup_unload does not search for or retrieve data from a lookup file.

The function returns the lookup identifier lookup_return_id of type lookup_identifier_type.

The exact use of the function depends on how you loaded or created the dynamic lookup file, in one of the following cases:

If you used a lookup template component, calling lookup_unload does not reset the value of the lookup_id. You can reset its value by using the following lookup_unload return assignment pattern:

let lookup_identifier_type my_lookup_identifier = lookup_load("PathToData.dat", "PathToIndex.dat", "My Lookup Template");

my_lookup_identifier = lookup_unload(lookup_id = my_lookup_identifier, lookup_template = "My Lookup Template");

If you used a lookup template type, calling lookup_unload changes its lookup_template_type handle argument: it resets the value of the handle’s id field to -1. A good practice is to follow this pattern:

let my_lookup_template_type my_lookup_handle = lookup_load("PathToData.dat", "PathToIndex.dat");

lookup_unload(my_lookup_handle);

The id field is built into every user-defined lookup template type and into every handle instance of such a type (such as the my_lookup_handle). This id field is always of predefined type lookup_identifier_type. This use of lookup_unload does not require a return assignment.

The scope of validity of a lookup identifier is local to the component that calls it.

lookup_create

Dynamically creates — or reserves space for — a lookup dataset in memory.

The function can use either a LOOKUP TEMPLATE component or a lookup template type to reference the lookup data, or it can be used to initialize an in-memory lookup from a database lookup handle

Using lookup versus lookup_local

Should I use a lookup or lookup_local function to access my lookup file?

Lookup files can be either serial or partitioned (multifiles). Use the lookup function with serial lookup files, and use lookup_local for partitioned lookup files.

Serial lookup file

If you have a serial lookup file, use the lookup function to access it. When a serial lookup file is accessed in a component, the Co>Operating System loads the entire file into memory. In most cases the file is memory-mapped; this means that every component in your graph that uses that lookup file (and is on the same machine) shares a copy of that file. If the component is running in parallel, the different partitions also share a single copy of the lookup file (if they are running on the same machine).

Multifile lookup file

If you have a multifile lookup file, use the lookup_local function to access it. The depth of the lookup file (the number of ways it is partitioned) must match the layout depth of the component accessing it. For example, if you have a REFORMAT component running eight ways parallel, your multifile lookup file must be partitioned eight ways. Be sure to partition the data going into the component performing the lookup_local on the same key as the lookup file.