trigger create

Trigger that handles a user’s request to add or insert a new occurrence of the entity in a Form.

Declaration: trigger create
Applies to: Entity
Activation: Activated by the structure editor functions ^ADD_OCC or ^INS_OCC.
Default behavior:

If no ProcScript is present in this trigger, an implicit creocc is done to create an empty occurrence before or after the current occurrence, depending on the structure editor function used.

Behavior upon completion: None.

Description

This trigger is typically used either to prevent users from adding new occurrences or to initialize fields of a new occurrence. 

trigger create
  if ($rettype = 65)
     creocc "INVOICE", $curocc + 1
     ; Add occurrence after current occ
  else
     creocc "INVOICE", $curocc
     ; Insert occurrence before current occ
  endif
  ; Add additional code here...
end; create

You may choose to change the position where occurrences are inserted or added. The following ProcScript module inserts a new occurrence before the first occurrence and adds an occurrence after the last occurrence: 

trigger create
  if ($rettype = 65)
     creocc "INVOICE", -1
  else
    creocc "INVOICE" , 1
  endif
end; create

Caution:

When you add or insert an occurrence, the default behavior of Uniface is to give focus to the newly created occurrence. This action represents a change to the active path in the component. Uniface carries out all outstanding data validation checks for the changed part of the active path, which means that the following triggers could potentially also be activated.

  • validate and loseFocus triggers of fields
  • validateKey, leaveModifiedKey, validate, and leaveModified triggers of entity occurrences.

Using ^INS_OCC

If the structure editor function ^INS_OCC is used, the empty occurrence is inserted before the current occurrence, that is, the new occurrence is inserted at position $curocc, while the previous current occurrence is shifted down one position.

Using ^ADD_OCC

If the structure editor function ^ADD_OCC is used, the empty occurrence that is created appears below the current occurrence (at position $curocc+1).

Preventing New Occurrences

You should put ProcScript in this trigger to prevent the user from creating new occurrences. You can do this simply by putting a return-1 statement in this trigger. Alternatively, placing a single executable statement such as done disables the creation of new occurrences. (A statement such as end, which is not executable, does not disable the trigger.) This happens because adding ProcScript in the trigger overrides the default functionality (which is to create an empty occurrence).

Initializing New Occurrences

If you want to initialize the new occurrence with values, for example, from a related entity, use the creocc statement to make an empty occurrence, then set the appropriate values for this newly created occurrence. The /init switch is often used on the initialization assignments for new occurrences.

You can test the value of $rettype to determine whether the user activated this trigger with ^INS_OCC or ^ADD_OCC. The following values are returned by $rettype in this trigger:

  • 65, when the occurrence was added.

  • 73, when the occurrence was inserted.

(These values are the ASCII character codes ‘A’ for Add and ‘I’ for Insert.)

You can use the values returned by $rettype to mimic the default behavior of Uniface and add additional code to set default values for fields in the created occurrence. This is shown in the following example:

Changing the Default ProcScript

If you want to define a new default ProcScript for this trigger, do not use a specific entity name, but instead use the function $entname to get the name of the current entity. This is shown in the following example which inserts new occurrences before the first occurrence and adds new occurrences after the last occurrence: 

trigger create
  if ($rettype = 65)
    creocc $entname, -1
  else
    creocc $entname, 1
  endif
end; create

Related Topics