erase

Activate the delete or deleteUp trigger for all occurrences in the component.

erase{/e {Entity}}

Qualifiers

Qualifiers
Qualifier	Description
/e	Erases all occurrences of Entity in the component, including inner entities if the relationship between these entities and the erased entity is Cascading Delete.

Parameters

Parameters
Parameter	Data Type	Description
Entity	String	Name of the entity to be erased. If omitted, all occurrences of the current entity ($entname) are erased.

Return Values

Values returned by $status
Value	Meaning
`1`	erase is not allowed. (For example, the component was activated with run/query.)
`0`	Data was successfully erased, or no entities are painted on the component.
`-2`	Occurrence not found: table is empty.
`-3`	Exceptional I/O error (hardware or software).
`-5`	Update request for non-updatable occurrence.
`-6`	Exceptional I/O error on write request; for example, lack of disk space, no write permission, or violation of a database constraint. Check the message frame for details.
`-11`	Occurrence already locked.
`-16`	Network error: unknown.

Values commonly returned by $procerror following erase
Value	Error constant	Meaning
`-2` through `-12`	`<UIOSERR_*>`	Errors during database I/O.
`-16` through`-30`	`<UNETERR_*>`	Errors during network I/O.
`-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 painted on the component.

Use

Allowed in all component types.

Description

The erase statement activates the delete triggers at entity level for all occurrences in the component. This means that occurrences which have not been fetched are not erased. Use this statement to allow the user to erase all the occurrences in the component.

The erase statement attempts to delete all the occurrences of the outermost entity that have been fetched into the component. This includes occurrences not currently displayed, and also any occurrences fetched due to ProcScript. Uniface attempts to erase all occurrences, not just those visible on the component. If the hitlist contains several occurrences, they are not deleted unless they have been explicitly fetched into the component.

Related Entities

If the entity to be erased has related entities, the behavior of erase depends on the delete constraints of the relationship:

Cascading Delete—the erase statement deletes related entities.
Nullify Delete—it nullifies the foreign key in related entities.
An erase is not allowed if there is a Restricted Delete relationship between entities and there are still occurrences of the many entity.

If Uniface detects that an entity is painted as an up entity on a component, the deleteUp trigger is activated instead of the delete trigger. If the occurrence in the up entity should be deleted in the normal I/O procedure, include a delete statement in this trigger.

Note: Deleting an occurrence of an up entity can have serious consequences for database integrity.

Deleting all Occurrences in the Database

If it is necessary to delete all occurrences in the database, you should use setocc"*",-1 to retrieve all occurrences into the component structure. The retrieve statement only builds the hitlist, and does not actually fetch the data. Then use the erase statement to remove the data. Simply using retrieve then erase does not necessarily delete all the occurrences, because erase only deletes fetched occurrences. You should only allow this if you want all your data to be deleted.

Clearing the Message Frame

If the message level for the application is greater than zero, the erase statement also clears the message frame. (If the message level is 0, the message frame is never cleared.) The message level can be set with the /pri switch or defined in the application definitions.

Using erase in the erase Trigger

The ^ERASE function can be quite drastic. It is common to disable the erase trigger by omitting the erase statement from it, or to ask for confirmation for the drastic action of erasing all occurrences. For example:

trigger erase ; of component

if ($totocc(CUSTOMER) >= 1)
   askmess "%%$totocc(CUSTOMER) occurrences. Erase them all?"
   if ($status = 0)
      return
   endif
endif

erase

if ($status <0)
   message "Erase error; see message frame"
   rollback
else
   if ($status = 1)
      message "Erase is not allowed"
   else
      message "Erase was successful"
      commit
      if($status < 0)
         rollback
      endif
   endif
endif

end ; erase