remocc

Mark an occurrence of the specified entity for deletion at the next store.

remocc  Entity,OccurrenceNumber

Example: remocc "CUSTOMER", 0

Parameters

Parameters
Parameter Data Type Description
Entity String Entity where an occurrence is to be removed. Can be a string, or a field, variable, function, or parameter that evaluates to a string containing the name.
OccurrenceNumber Number Sequence number (in the component) of the occurrence to be removed; whole (integer) number; the value will be truncated to form an integer.

Return Values

Values returned in $status
Value Meaning
<0 An error occurred. $procerror contains the exact error.
>=0 Sequence number of the occurrence that became current after removing an occurrence.

 

Values commonly returned by $procerror following remocc
Value

Error constant

Meaning
-1 <UGENERR_ERROR> An error occurred. Entity is the outer entity of a Record component.
-1102 <UPROCERR_ENTITY> Entity is not a valid name or the entity is not painted on the component.
-1203 <UPROCERR_RANGE> Value out of range. For example, OccurrenceNumber is greater than the number of occurrences of Entity.

Use

Allowed in all component types.

Description

The remocc statement removes an occurrence of Entity from the component and marks it for deletion from the database when the data is stored. The store command activates the delete trigger of each database occurrence of an outer entity that was marked for removal, and for each of its Down entities. For more information, see trigger delete.

The occurrence will be found if a retrieve/o is used; in this case, retrieve/o sets $status to 3.

If OccurrenceNumber is:

  • < 0, the last occurrence in the component structure is removed.
  • 0, the current occurrence of Entity is removed (default).
  • Greater than the number of occurrences of Entity, $status is set to -1 and no occurrence is removed.

The behavior following remocc is governed by the location of the removed occurrence:

  • If the removed occurrence is not the last occurrence, the next occurrence is made active after a remocc.
  • If the removed occurrence is the last occurrence, the previous occurrence is made active after remocc.
  • If the component contains only one occurrence, that occurrence is removed and a new, empty occurrence becomes the current occurrence.

If you want to filter out occurrences that you have retrieved but do not want to process, rather than using a remocc statement, you should use the discard statement or the u_where clause with the read statement.

Note:  The remocc statement sets the current entity, causing a change in the active path. This can result in data validation triggers being fired.

Removing Occurrences

The statements in the following example remove the current occurrence of the CUSTOMER entity if the INVAMOUNT field is less than or equal to 0: 

trigger leaveModified
  if (INVAMOUNT <= 0)
    remocc "CUSTOMER", 0
    message "Customer with no debt removed."
  endif
end; leaveModified

Related Topics