retrieve/o

Attempt to locate an occurrence of an entity using the current primary key value.

retrieve/o  {Entity}

Parameters

Parameters
Parameter Data Type Description
Entity String Entity of the occurrence to be located.

Return Values

Values returned in $status
Value Meaning
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 unremoved.
2 The entity is painted as an up (foreign) entity and one hit was found in the database.
1 The entity is painted as an up (foreign) 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 A new occurrence was created.
-1 Record not found: end of file encountered.
-2 The entity is an Up entity and the key value was not found during the database lookup.
-3 Exceptional I/O error (hardware or software).
-4 Open request for table or file failed. The entity is not in the component structure, or the table or file does not exist.
-7 The key exists in the database but was not found in the hitlist. This occurs when the user tries to enter a duplicate key.
-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/o
Value Error constant Meaning
-2 through -12 <UIOSERR_*> Errors during database I/O.
-16 through -30 <UNETERR_*> Errors during network I/O.
-2 <UIOSERR_OCC_NOT_FOUND> The entity is an Up entity and the key value was not found during the database lookup.
-7 <UIOSERR_DUPLICATE_KEY> The key exists in the database but was not found in the hitlist. This occurs when the user tries to enter a duplicate key.
-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/o statement tries to find an occurrence with the current primary key, both in the DBMS and in the component. If the primary key data is not available, it tries to find an occurrence using the candidate key data, if available.

The leaveModifiedKey trigger often contains a retrieve/o statement to prevent the user from entering a primary key value which is already in use.

Note:  The retrieve/o statement does not activate the read trigger of an entity. By definition, it makes the retrieved occurrence current. In Form components, if no primary key fields are in the layout, the retrieve/o statement positions the cursor at an arbitrary place.

If an entity is defined as non-database, retrieve/o does not search the component for an occurrence. If this is required, define the entity as stored in a database, but remove the write statement from the write or writeUp triggers for the entity. This should be done in the modeled entity. This ensures that an entity does not get stored in the database, and has the same effect as defining the entity as non-database.

When the retrieve/o statement is executed, Uniface searches for the occurrence in the following way:

  1. 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 the occurrence was removed, it is restored, unless the profile contained a wildcard.
  2. 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 it is present in the database, $status is set to -7.

The above steps are equivalent to Uniface doing a setocc to the appropriate occurrence.

Using retrieve/o

The following example shows the default ProcScript present in the leaveModifiedKey trigger. Note that a retrieve/e statement is used if a single occurrence is found in an up entity. The example shows the use of checks on $status to determine the result of a retrieve/o statement: 

retrieve/o
if ($status < 0)
if ($status=-15) message $text(2202);Multiple hits: in foreign entity
if ($status=-14) message $text(2205);Multiple hits: not in foreign entity
   if ($status=-11) message $text(2009);Occurrence currently locked
   if ($status=-7) message $text(2006);Duplicate key
   if ($status=-4) message $text(2003);Cannot open table or file
   if ($status=-3) message $text(2002);Exceptional I/O error
   if ($status=-2) message $text(2200);Key not found:in foreign entity
else
   if ($status=1) message $text(2201);Key not found:foreign entity w/WRITE UP
   if ($status=2);One occurrence found in foreign entity
      retrieve/e
      if ($status < 0) message $text(2002);I/O error detected
   endif
   if ($status=3) message $text(2203);Occurrence un-removed
   if ($status=4) message $text(2204);Key found:occurrence repositioned
endif
return ($status)

Related Topics