forentity

Defines a loop that processes all the occurrences of an entity.

forentity EntityName
Your ProcScript
endfor

Parameters

Parameters
Parameter	Data Type	Description
EntityName	String	Entity name; can be a string, or a field, variable, function, or parameter that evaluates to a string.

Return Values

None

Values Commonly Returned by $procerror after forentity
Value	Error constant	Meaning
`-1102`	`UPROCERR_ENTITY`	EntityName is not a valid name or the entity is not in the component structure

Use

Allowed in all component types.

Description

The forentity statement starts a loop that processes each occurrence of the specified entity. The loop executes the code in the block until one of the following conditions is met:

There are no more occurrences to process ($curocc is larger than the last occurrence).
There are no occurrences of the entity ($empty is true)
A break statement is encountered

The forentity statement processes each occurrence in the hitlist, so the value of $curocc is changed with each iteration. After the forentity loop completes, $curocc is set to the last occurrence processed.

Processing the Hitlist

Statements that also set the value of $curocc, such as remocc and discard, may cause forentity to skip processing of some occurrences.

For example, the intent of the following code is to delete every occurrence of an entity. However, every second occurrence is skipped, because both remocc and endfor increase the $curocc value by 1:

trigger detail ; of field DELETE
forentity "ENTITY1"
  remocc  
endfor 
end; detail

Note: For this reason, it is recommended that you avoid using remocc and discard in forentity blocks.

Finding an Occurrence with a Specified Field Value

In the following example, the forentity loop processes an the entity PERSON.ORG. Processing stops if the value of the FULLNAME field of the current occurrence is "Donald Duck".

variables
   numeric vLoops
   string vFullName
endvariables

retrieve/e "PERSON.ORG"
vLoops = 0

forentity "PERSON.ORG" 
	vLoops += 1	
    vFullName = FULLNAME.PERSON.ORG
    if (vFullName = "Donald Duck")
       putmess "Loop processing stopped on Name: %%vFullName Loop count: %%vLoops"
       break
    endif
    putmess "Processing  %%vFullName,  Loop count: %%vLoops "
endfor

The resulting output looks like this:

Processing  Bruce Banner,  Loop count: 1
Processing  Lois Lane,  Loop count: 2
Processing  Bruce Wayne,  Loop count: 3
Processing  Clark Kent, count: 4
Loop processing stopped on Name: Donald Duck, Loop count: 5

Calculating Values

The following code loops through all the ORDERLINE occurrences an ORDERS, to calculate the TOTAL value.

trigger preSerialize
TOTAL.ORDERS = 0 ;initialize field value
forentity "ORDERLINE" ;loop through each ORDERLINE entity
  LINE_TOTAL.ORDERLINE = UNIT_PRICE.ORDERLINE * QUANTITY.ORDERLINE ;calculate the LINE_TOTAL
  TOTAL.ORDERS += LINE_TOTAL.ORDERLINE ;calculate the TOTAL
endfor
end; preSerialize

History
Version	Change
9.5.01	Introduced