LookUp

Syntax

LOOKUP expression class_name [
SECURE | KEYONLY ] [ GS status ]

Parameters

LookUp can be abbreviated as LU.

expression
The primary key value to match.
This value must share the same primitive as the primary key. For MCP-based systems you cannot specify a double byte text string for single byte primary key or single byte text string for double byte primary key.
class_name
The persistent class to read from.
SECURE
Facilitates record locking of the database in applications that do not force integrity. Refer to Secure for more information.
KEYONLY
The KeyOnly command option is not supported on applications that are deployed to Windows.
For MCP-based systems, refer to KeyOnly.
GS status
If used, the success or failure of the Lookup is stored in a user-defined attribute, <status>, instead of Glb.Status. A value of “*****” indicates that a record was not found.

Description

The LookUp (singleton) logic command reads a single persistent class record whose primary key value matches that of a specified value into memory from the database. The LookUp logic command performs a single record retrieval.

Refer to LookUp Variants for more information on the LookUp logic command.

Automatic LookUps

If a primary key is included in another ispec as an attribute, the value of the key is validated as part of the segment cycle. That is, an automatic Lookup is performed as if a LookUp logic statement was included in the logic. To activate this behavior, you must add an “AutoLookUp” dependency.

For example, consider the Cust ispec with a Customer key. Customer is also an attribute of the Sale event, and the Sale event has an “AutoLookUp” dependency to Cust. During the automatic validation phase of the segment cycle for the Sale event, the Customer value is used in a LookUp command to ensure that the customer exists.

An automatic Lookup is also performed if all the keys of an automaint memo component are included in an ispec and an AutoLookUp dependency exists.

The following rules apply for an auto-lookup on an Ispec in an inheritance hierarchy:

Validation proceeds from the class containing the key(s), which is defined in the hierarchy closest to the transaction Ispec. The values of a set of keys defined on a class are unique for that class.
When the validation is being performed on an Ispec in the hierarchy above the transaction Ispec, which is either the base class or on an intermediate class, having one or more keys defined, an instance of that Ispec is populated by the corresponding record from the database.

Failure Behavior

If no record is retrieved, the Glb.Status built-in segment attribute (or the variable specified by the GS command option) is set to “*****” and processing continues.

Example

This example illustrates code from a report that makes use of the P_DateTime profile to retrieve all SaleEvent records in chronological order. The SaleEvent records do not contain the name of each product sold (just the Product ID), so the singleton Lookup command is used to retrieve the corresponding product record, based on the Product ID coming from the SaleEvent record just read. At that point, the ProductName and the SaleEvent details are moved from each retrieved record into the SaleDetail frame and printed.

Determine Actual SaleEvent.P_DateTime 
   Lookup SaleEvent.P_ProductID Product
   SaleDetail.ProductName  := Product.ProductName
   SaleDetail.ProductID    := SaleEvent.ProductID
   SaleDetail.Quantity     := SaleEvent.SoldQuantity
   SaleDetail.Print()
End

For this example, output from the report is as follows, in Product ID order:

Product Name	Product ID	Sold Quantity
Outfit for Dogs	1	10
Outfit for Dogs	1	10
Outfit for Dogs	1	10
Outfit for Dogs	1	10
Outfit for Dogs	1	10
Outfit for Dogs	1	10
Chips for cats	2	14
Chips for cats	2	14
KittenCaps	4	10
KittenCaps	4	30
Toys for Cats	5	40