retrieve/x

Retrieve an additional occurrence of the specified entity without discarding the hitlist.

retrieve/x Entity

Parameters

Parameters
Parameter	Data Type	Description
Entity	String	Entity for which additional occurrences are to be retrieved.

Return Values

The retrieve/x statement can set $status; however, since retrieve/x can activate Read triggers, the value in $status after retrieve/x can have been set by the ProcScript in the read trigger.

The values returned in $status following retrieve/x are:

Values returned in $status
Value	Meaning
`5`	One hit was found in the database.
`4`	The occurrence was found in the component. The current occurrence is removed and the cursor repositioned on the found occurrence.
`3`	The occurrence was found among the removed occurrences; it was restored.
`1`	The entity is an Up entity with code in the writeUp trigger and the key value was not found during the database lookup. It is assumed that this is a new occurrence.
`0`	The occurrence does not exist.
`-3`	Exceptional I/O error (hardware or software).
`-11`	Occurrence already locked.
`-14`	The entity is a Down entity and multiple hits were found during the database lookup (ambiguous key).
`-15`	The entity is an Up entity and multiple hits were found during the database lookup.
`-16`	Network error: unknown.

Values commonly returned by $procerror following retrieve/x
Value	Error constant	Meaning
`-2` through `-12`	`<UIOSERR_*>`	Errors during database I/O.
`-16` through `-30`	`<UNETERR_*>`	Errors during network I/O.
`-14`	`<URETERR_MULTIPLE_DOWN>`	The entity is a normal Down entity and multiple hits were found during the database lookup (ambiguous key).
`-15`	`<URETERR_MULTIPLE_UP>`	The entity is an Up entity and multiple hits were found during the database lookup.
`-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

The retrieve/x statement allows you to retrieve an additional occurrence of an entity without discarding the current hitlist. This is useful when you want to retrieve an occurrence that does not match the profile provided, but which is still related to occurrences already fetched.

Note: If there is a partially completed stepped hitlist, it is completed before the new occurrence is retrieved.

The retrieve/x statement tries to find an occurrence with the current primary key, (not the candidate key) both in the DBMS and in the component. Uniface searches for the occurrence in the following way:

It inspects the component. If Uniface finds a matching occurrence, the current occurrence is removed and the cursor scrolls forward or backward to the found occurrence. If that occurrence was removed, it is put back, unless the profile contained a wildcard.
If Uniface does not find a matching occurrence in the component, the entire hitlist is inspected:
- If it finds a match in the hitlist, occurrences are fetched until the matching occurrence is found.
- If the occurrence is not found in the hitlist, but is present in the database, the occurrence is loaded and added to the hitlist. (The read trigger is activated to fetch the occurrence into the component.) If Entity is painted as a down entity, the new occurrence is added to the hitlist even if it is not related to the up entity.