Occurrences

An occurrence is the runtime instance of an entity. Although the entity determines the fields an occurrence may have, and some of its default properties and behavior, each occurrence is unique and contains one set of the fields, whether they contain data or not.

For database entities, occurrences represent the rows in a database table.

When a new component instance is created, an empty occurrence of each entity in the component structure is also created. This occurrence can then be populated with data, either by retrieving data from the database or by the user entering and saving data.

Uniface validates the entity occurrences if data in one or more fields in an occurrence have been modified or if one or more occurrences of an entity have not yet been validated successfully.

Layout of Occurrences

In presentation components, you can determine the arrangement and appearance of occurrences and their fields. When you design the layout, you determine:

  • How many occurrences will be visible in the component
  • Which fields will be included (it is possible to display only a selection of the fields defined by the entity)
  • How the fields will be arranged within an occurrence

You can set various properties that control the default appearance of an entity's occurrences, and you can dynamically change their appearance using $entityproperties and $curentproperties.

Current Occurrence

An occurrence can only be processed if it is the current occurrence of a given entity in the component structure. Therefore, before modifying or manipulating an occurrence, you must make it the current occurrence.

You can set the current occurrence programmatically using the setocc (or websetocc) ProcScript command. The user can also set the current occurrence by clicking anywhere inside the occurrence, such as in a field, or on a field label.

In a complex component structure, there can be multiple current occurrences (outlined in orange in the following illustration), analogous to a tree. At each level of nested occurrences within a branch of that tree, there is exactly one occurrence that is the current occurrence.

Multiple Current Occurrences

Multiple current occurrences

Processing can only occur on the current occurrence of the innermost entity. In this example, it is OUTERPK3/MIDDLEPRIMK 3001/INNERFF 312.

When an operation occurs on a specific occurrence or collection of occurrences (entity), Uniface temporarily makes that occurrence or collection active in the active path. After the operation has finished, the active path is restored to what it was before.

The current occurrence is only of interest when it is in the active path, which defines the data on which processing occurs.

The active path goes from the current occurrence of the outer entity down to the current occurrence of the innermost entity. In this example, it is OUTERPK3/MIDDLEPRIMK 3001/INNERFF 312. For more information, see Active Path for Runtime Processing.

Selected Occurrence

Specific occurrences may be selected for further processing. For example, you may want to format selected occurrences differently, or change the value of a field in multiple occurrences to the same thing. Each occurrence has a built-in Boolean attribute, called $selected, that indicates whether it is selected.

The user can select occurrences, either singly or using Ctrl+Click or Shift+Click to select multiple occurrences. (Ctrl+A is not supported.)

The developer can select (or clear) a single occurrence programmatically by setting the $selected attribute using the occurrence handle. For example:

variables
  handle hOcc
endvariables
hOcc = $occhandle("ENT")  ; A handle to the current occurrence
  ...
  hOcc->$selected = 1     ; Mark the occurrence as selected
  ...
  hocc->$selected = 0     ; Clear the selection

To manipulate multiple selected occurrences, you can use a collection handle get the set of selected occurrences. To add or remove occurrences from the set of selected occurrences, you use the $selectedoccs attribute and $clearselection operation on $collhandle. For example:

variables
   handle hOcc1, hOcc2
   struct vstruct1, vstruct2
endvariables
  ...
  vstruct1 = $collhandle("ENT")->$selectedoccs ;Struct of occurrence handles
  ...
  $collhandle("ENT")->$clearselection() ; Clear the $selected attribute on all occs
  ...                     
end

Related Topics