retrieve/a

Retrieve multiple additional occurrences of the specified entity without discarding the hitlist.

retrieve/a   {Entity}

Parameters

Parameters
Parameter Data Type Description
Entity String Entity to be retrieved. Can be omitted in entity and field-level triggers, where there is a current entity.

Return Values

Values returned in $status
Value Meaning
0 No hits were found using the profile.
<0 An error occurred. $procerror contains the exact error.

Since retrieve/a can activate read triggers, the values in $status and $procerror after retrieve/a might have been set by the ProcScript in the read trigger. Keep this in mind when testing following a retrieve/a statement.

>0 Success. Number of occurrences that match the retrieve/a profile occurrence.
Values commonly returned by $procerror following retrieve/a
Value Error constant Meaning
-2 through -12 <UIOSERR_*> Errors during database I/O.
-16 through -30 <UNETERR_*> Errors during network I/O.
-1102 <UPROCERR_ENTITY> The entity name provided is not a valid name or the entity is not in the component structure

Use

Allowed in all component types.

Description

retrieve/a uses the current occurrence of Entity as a profile to retrieve multiple occurrences matching that profile statement. It is an extension of the retrieve/x statement.

When using the retrieve/a statement, you need to create a separate occurrence for the new retrieve profile.

Uniface searches for the occurrence in the following way:

  1. If the currently active hitlist is stepped and not yet completed, it is completed first.
  2. A where clause is generated based on the retrieve profile (the current occurrence of Entity). A database query for retrieving multiple records is executed.
  3. The hits from the new hitlist returned by the DBMS are added to the existing hitlist.
  4. The retrieve profile occurrence is deleted.
  5. The extended hitlist is completed if it was stepped.
  6. Duplicate entries from the hitlist are removed.
  7. The first newly added occurrence is loaded.

Using retrieve/a

The following example retrieves occurrences with a new profile using retrieve/a : 

clear
PK = 1
retrieve
creocc ; create occurrence for profile
PK = ">10"
retrieve/a ; retrieve

Related Topics