clear

Clear data from the component or entity.

clear{/e  Entity}

Qualifiers

Qualifiers
Qualifier Description
/e Clears data from the specified entity, rather than the component

Parameters

Parameters
Parameter Data Type Description
Entity String Entity to be cleared. Can be a string, or a field, variable, function, or parameter that evaluates to a string containing the entity name.

Return Values

Values returned in $status
Value Meaning
0 Data was successfully cleared, or no entities are painted on the component.
-3 Exceptional I/O error (hardware or software).
-16 Network error: unknown.
Values commonly returned by $procerror following clear
Value Error constant Meaning
-2 through -12 <UIOSERR_*> Errors during database I/O.
-16 through -30 <UNETERR_*> Errors during network I/O.
-1102 <UPROCERR_ENTITY> The entity name provided is not a valid name or the entity is not painted on the component.

Use

Allowed in all component types.

Not allowed in the getFocus and startModification triggers of an entity.

Caution: Never use the clear/e statement in the getFocus or startModification triggers. This can cause Uniface to enter an infinite loop.

Description

If the argument Entity is omitted, all data in the component is cleared.

The clear statement clears all data from the component (by default) or, when the /e switch is given, from Entity. Data in the database is not affected by the clear statement; any locked occurrences remain locked. The active path for the component is reset.

One use for the clear statement is when data has been added in a different component and the data displayed on the current form needs to be redisplayed.

Component with Record behavior

Use clear/e with care on a component with Record behavior. A Record component has only one outermost entity. If you have painted more than one outermost entity, when the Record component is compiled, Uniface expands the first outermost entity painted (that is, the upper, left-most) so that all other outermost entities become inner to the first. This means that using clear/e to clear data from the first outmost entity on a Record component clears data from all the entities painted on the component.

The following example clears the data entered when the user makes an entry that is not valid: 

trigger leaveModified 
  if ((salary > 100000) & (job != "PRESIDENT"))
      message "Salary not valid"
      clear/e "entity"
  endif
end; leaveModified

In the example shown in following figure, component X calls Service Z to create a new occurrence of entity C:

Using the clear statement to refresh updated data

Graphical content.

The ProcScript for the Detail trigger is as follows: 

trigger detail
; save foreign key for occurrences displayed in entity C
; set up foreign key, ready for retrieve
; retrieve new data entered on service Z

  $1 = FOREIGN_KEY.C
  activate "Z".EXEC($1)
  clear/e "C"
  FOREIGN_KEY.C = $1
  retrieve/e "C"
end

Related Topics