trigger retrieve

Location for ProcScript that retrieves data from the database.

Description

This trigger is generally used to retrieve data. By default, the <Retrieve> trigger contains the following code:

trigger retrieve
  retrieve
  if ($status < 0)
    message $text(1762) ;error
  endif
end

If you want to allow the user to access only a subset of the available data, you can:

• Define a retrieve profile by assigning specific values to fields followed by the retrieve statement to get the data.
• Use the u_where clause in the read statement in the read trigger to restrict the user's access to a range of values.

Retrieve Trigger Processing

A retrieve statement in this trigger first builds the hitlist for the data (using any profile information provided), and then activates the entity-level read triggers for each painted occurrence.

It only retrieves enough data to populate the form. This has implications when used in conjunction with the erase statement. The erase statement erases only those occurrences that have been retrieved; it does not erase all the occurrences in the hitlist, but only those that have been displayed.

If ProcScript in this trigger activates the Read trigger and a negative value in the activated read trigger is returned, I/O processing is terminated after the read trigger completes.

Retrieving Multiple Outer Entities

If you have painted two or more outer entities on a component, you need to include additional retrieve statements. (When you paint two or more outer entities on a component, they are usually unrelated entities, although this is not necessarily the case. Painting related entities ‘outer’ to each other causes Uniface to assume that the entities are not related; it makes no attempt to locate a modeled relationship.)

The default retrieve statement in the retrieve trigger causes the first outer entity (that is, the top, left-most entity painted) and its related entities to be retrieved. To retrieve any other outer entities, you need to include additional retrieve/e statements in the retrieve trigger of the first outer entity.

When the retrieve trigger is activated, the default single retrieve statement retrieves data only from entity A. To retrieve data for entities B and C, the following ProcScript should be placed in the retrieve trigger:

trigger retrieve
retrieve
if ($status <0)
  message "Retrieve did not succeed; see message frame"
endif
retrieve/e "B"
if ($status <0)
  message "Retrieve on B did not succeed; see message frame"
endif
end; retrieve

This ensures that the form is correctly populated with data when the ^RETRIEVE structure editor function is activated. Be aware that the ProcScript compiler generates the warning that there is no path to entity B. It is your responsibility to define this path if it is required. For more information about painting unrelated entities, see the Uniface online help.

trigger retrieve
PK.DOC_CODE = "D*"
retrieve
if ($status <0)
  message "Retrieve did not succeed; see message frame"
endif
end; retrieve