trigger read

System trigger that fetches an occurrence from the database.

Declaration: trigger read
Applies to: Entity
Activation: Activated whenever an occurrence must be fetched from the database. This can be in response to the retrieve command, or any other ProcScript command that needs data in the hit list, such as edit, setocc, erase, reconnect, creocc -1, print, and so on.

In Form components, it can be activated as a result of structure editor functions, such as ^NEXT_OCC, which result in an occurrence being requested for the first time.
Default behavior: None.
Behavior upon completion: If $status is less than zero, database I/O is terminated. No further read triggers are activated for the current I/O request.

Description

The purpose of the read trigger is to retrieve an occurrence required by the component, so it must include a read statement. You can tailor this statement in many ways to ensure only the information you want is selected from the database, and optionally sorted. For more information, see read .

Note:  The read trigger should only contain logic for handling an occurrence, not for a collection of occurrences. Selection and sorting criteria in the read statement are only used the first time the read trigger is activated for an entity; thereafter, it is only used to fetch an occurrence.

Uniface does not immediately fetch all occurrences into a component for reasons of memory, performance, and transaction control. For example, when an occurrence becomes visible or becomes the current occurrence for the first time since being retrieved, the read trigger is activated as many times as necessary to get that occurrence into the component.

The first time that the read trigger is activated for an entity, the read statement is executed, triggering the following actions:

  • The read statement generates a database select statement using any specified read statement parameters, such as such as u_where, where, u_condition, order by and so on.
  • The database builds a hitlist and returns a pointer to that hitlist to Uniface
  • Uniface fetches the first occurrence from the hitlist and activates any field-level formatFromDbms triggers that contain ProcScript.

When the read trigger of the next and subsequent occurrences is fired, other occurrences can be fetched from the hit list on an as-needed basis, without having to start the whole database I/O transaction again. Any read statement parameters, such as u_where and so on are only used on the first read statement. On consequent reads these parameters are ignored.

After the read trigger is activated, $rettype function indicates the type of retrieval request that activated it (such as retrieve or ^Next occurrence). This can be useful for conditional processing. For more information, see $rettype.

Outer and Inner Entities

Outer entities have their read triggers activated first because key transport must take place before the inner entities can be retrieved. If the outer entity's Database Behavior property is N (Not in Database), the read triggers of the inner entities are not activated. In this case, you must ensure that the outer entity's read trigger explicitly retrieves the inner entity. For example: 

; outer entity ENT1 is a modeled non-database entity
; inner entity ENT2 is a modeled database entity

trigger read 
   retrieve/e "ENT2" ;fires the read trigger ENT2
end

Related Topics