retrieve

Activate the read trigger for the first outermost entity and all related entities, or for a specific entity.

retrieve/e {Entity}

retrieve/x {Entity}

retrieve/a {Entity}

retrieve/o {Entity}

retrieve/reconnect {Entity}

Example: retrieve/e CUSTOMER.SALES

Qualifiers

Qualifiers
Qualifier	Description
/e	Activates the read trigger of the current entity ($entname) or of Entity.
/x	Retrieves an additional occurrence of the specified entity without discarding the hitlist. For more information, see retrieve/x.
/a	Retrieves multiple additional occurrences of the specified entity without discarding the hitlist. For more information, see retrieve/a.
/o	Attempts to locate an occurrence of an entity using the current primary key value. For more information, see retrieve/o.
/reconnect	Reconnects data loaded from an XML stream with the occurrences in a database or component. For more information, see retrieve/reconnect.

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

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

Tip: After the read trigger is activated, $rettype function indicates the type of retrieval request that activated it. This can be useful for conditional post-retrieval processing. For more information, see $rettype.

Values returned in $status
Value	Meaning
`0`	Data was successfully retrieved. Or, no entities are painted on the component.
`-1`	Record not found: end of file encountered.
`-2`	Occurrence not found: table is empty. (No hits were found in the table or file.)
`-3`	Exceptional I/O error (hardware or software).
`-4`	Open request for table or file failed. The table or file is not in the component structure, or it does not exist.
`-9`	An attempt to open a DBMS failed because the maximum number of DBMS logons has already been reached.
`-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/e
Value	Error constant	Meaning
`-2` through `-12`	`<UIOSERR_*>`	Errors during database I/O.
`-16` through `-30`	`<UNETERR_*>`	Errors during network I/O.
`-4`	`<UIOSERR_OPEN_FAILURE>`	The table or file could not be opened. The entity is not in the component structure or the corresponding table or file does not exist in the database.
`-9`	`<UIOSERR_LOGON_ERROR>`	DBMS logon error; for example, the maximum number of DBMS logons has already been reached.
`-35`	`<UGENERR_4GL_SAYS_ERROR>`	A trigger returned a negative value in `$status`.
`-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

Without the /e switch, the retrieve statement activates the read trigger of the first outermost entity on the component. If the /e switch is specified, it activates the read trigger of the current entity ($entname) or of Entity.

Activating the read trigger causes the Read triggers of any inner entity to be activated. Any previously built hitlists are discarded. However, if the outer entity is in the application model, but its Database Behavior is N (Not in Database), the read triggers of the inner entities are not activated. In this case, ensure that the read statement in the outer entity's read trigger explicitly retrieves the inner entity. For example:

;Read trigger of ENT1
; ENT1 is a modeled non-database entity, drawn as an outer entity
; ENT2 is a modeled database entity, drawn as an inner entity of ENT1
read
retrieve/e "ENT2"

If a retrieve statement is used in a retrieve trigger, the read triggers that it activates depend on the profile supplied by the user or by ProcScript in the retrieve trigger. If a specific primary key value for an outer entity is supplied, only the read trigger of a single outer entity (and all its inner entities) is activated.

In Form components, the retrieve statement activates the read triggers only for entities painted on the screen. As a result, the retrieve statement does not fetch all the occurrences in the hitlist, only enough occurrences to populate the component with data. (This functionality is influenced by the select cache mechanism.) To retrieve all the occurrences into the component, you need, use a setocc "*",-1.

Caution: A setocc "*",-1 has drastic consequences if the user issues an ^ERASE on a form component.

You cannot use a Uniface variable-length field to provide the selection criteria. This also applies to any fields in the variable portion of an entity.

A retrieve statement in the retrieveSequential trigger behaves exactly the same as one in the retrieve trigger. However, the retrieveSequential trigger is only activated when a component has Record behavior. This type of component only allows one occurrence of the outer entity.

Displaying an Unrelated Entity

The following example shows some ProcScript that uses the retrieve/e statement to display an unrelated entity.

In the component in the following illustration, there is no direct relationship between occurrences in B and occurrences in C. However, occurrences in C share a common foreign key with occurrences in B.

Unrelated Inner Entities

Component with one outer entity A and wo inner entities B and C.

In the getFocus trigger of entity C, there is a retrieve/e statement to display the relevant occurrence of B. This can be necessary when there is no direct relationship between two inner entities.

trigger getFocus
  ; Set up foreign key in other entity (entity C)
  ; and then get the correct occurrence of B

  PRODUCT_VERSION.B = PRODUCT_VERSION.C
  retrieve/e "B"
end

If you have two or more unrelated outer entities, you will need to include additional retrieve statements. The single default retrieve statement will only cause the first outer entity (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.

When the retrieve trigger is activated, the default single retrieve statement only retrieves data 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 will ensure that the component is correctly populated with data when the ^RETRIEVE structure editor function is activated. Be aware that the ProcScript compiler will generate the warning that there is no path to entity B. It is your responsibility to define this path if it is required.