iterate
iterate { Stmt1, . . . , Stmtn } or iterate(procedureName) (obsolete)
The statement block following iterate or the procedure specified in the parameter is executed iteratively. The statement "breaks down" the value found on the stack into its elements. For each element the statements controlled by the iterate statement are called. The current element is on the stack at the beginning of a run.
- The number of elements determines the number of cycles.
- For each cycle, the current element is placed on the stack.
- In the kth cycle the number k is obtained with the instruction Index
- The iteration terminates prematurely if a break-statement is reached in the statement sequence; i.e. then it continues with the statement following the iterate statement.
- Instruction continue starts the next iteration cycle, thus jumping to the beginning of the instruction sequence(example).
- A collection or a vector (exception list widgets see below) may be modified during iteration; the changes do not influence the iteration (os_cursor::update_insensitive - see ObjectStore documentation, or in case of vectors a copy is created). If a collection is modified (extended/empty) during iteration, you should iterate through the collection with a cursor instead.
Iteration is possible via
- a collection
Stack Stack Position Description Stack(In) Top a collection Stack(Out) Top - For each element of the collection, the instructions subject to iteration are executed.
Address-Space overflow cannot be handled and leads to abort in any case - a way out is to do without the changeability of the collection: iterate(UNSAFE). - a collection with index path
Stack Stack Position Description Stack(In) Top an index path Top 1 a collection Stack(Out) Top - The stack-top index path (compare IndexPath statement) controls the order of iteration through the collection.
Address-Space overflow cannot be handled and leads to abort in any case - a way out is to do without the modifiability of the collection: iterate(UNSAFE). - a window object ObjectBoxes, ObjectCombobox
Stack Stack Position Description Stack(In) Top an object box Stack(Out) Top - The above mentioned window objects can be seen as a visual representation of a collection, and, in analogy to the first case, the statement for each object visualised by the object box is called here. Widget brings an object box onto the stack.
Contrary to the iteration over a collection no objects may be inserted or removed from the ObjectList during the iteration over an ObjectList.
Address space overflow is handled by the ClassiX® system. - a vector
Stack Stack Position Description Stack(In) Top a vector Stack(Out) Top - All elements of the vector are iterated over.
The vector may be modified, i.e. it is iterated over a copy of the vector. If the vector remains unchanged, one should save this effort and use iterate(UNSAFE).
Address space overflow is handled by the ClassiX® system.
Another form of iteration over a vector isStack Stack Position Description Stack(In) Top Top 1 Elements ... . . . Top-n element1 Top-(n+1) Stack(Out) - whereby there is no difference between iterate and iterate(UNSAFE), because the vector cannot be modified in the iteration cycle.
Address space overflow is handled by the ClassiX® system.A vector is passed backwards by default, with BACKWARD forward.
Code example:
[ 1€ 2€ 3€ ] iterate { Attention } => 3€ Attention, 2€ Attention, 1€ Attention - one object
Stack Stack Position Description Stack(In) Top one object Stack(Out) Top - A single object defines by means of the virtual functions GetIndexedCount() whether an iteration is defined over any elements of this object (example: CX_CONDITIONED_BAG - elements are the CX_FCONDITION objects; iteration over COM objects).
Otherwise, the object is treated as a collection that only contains this object as an element, i.e. there is only one iteration cycle.
Backward iteration is not possible.Address space overflow is not handled by the ClassiX® system - thus it will always lead to abort.
an iterable object (symbol: )
Stack
A single object that defines an iteration using the virtual method GetDataSource(). This method does not require the object to know the number of iteration passes before the iteration (cardinality).Stack Position Description Stack(In) Top one object Stack(Out) Top -
Example:- Var(file) CreateTransObject(CX_ASCII_FILE) -> file
"CX_SYSTEM_OUT/inputfile.txt" file Put(fileName)
file iterate {
LocalVar(recordVector, value) -> recordVector
0 recordVector GetElement -> value //Erstes Feld des Records
value "break" = if { break } //Iteration vorzeitig abbrechen, wenn das Wort "break" gelesen wird
} - a multilingual character string (multiple string)
Stack Stack Position Description Stack(In) Top multiple string Stack(Out) Top In the cycle k the kth substring is on the stack. During the iteration the string must not be changed.
Address space overflow is not handled by the ClassiX® system - thus it will always be aborted.
iterate(BACKWARD) { Stmt1, . . . , Stmtn } or iterate(stmtName, BACKWARD)
parameters: Name of a statement
Iteration in reverse order. Backward iteration is defined for all variants listed above. An exception is the iteration over a single object
iterate(UNSAFE) { Stmt1, . . . , Stmtn } or iterate(stmtName, UNSAFE)
parameters: Name of a statement
Iteration over a collection defined with iterate(UNSAFE):
In this mode, the collection must not be changed.
The advantage: address space overflow can be handled automatically by the ClassiX® system.
Iteration over a vector with iterate(UNSAFE):
The vector must not be changed during the iteration.
The advantage: performance gain (example).
Address space overflow is handled by the ClassiX® system for both forms.
iterate(UNSAFE+BACKWARD) { Stmt1, . . . , Stmtn } or iterate(stmtName, UNSAFE+BACKWARD) respectively
iterate(BACKWARD+UNSAFE) { Stmt1, . . . , Stmtn } or iterate(stmtName, BACKWARD+UNSAFE)
parameters: Name of a statement
Backwards iteration over a collection, whereby the collection is not changeable. This enables the ClassiX® system to handle address space overflow.
Reverse iteration over a vector - which must remain unchanged during the iteration - with performance gain.
Instruction EndTXN within an iteration cycle: If iteration is performed over a collection with persistent elements¹), the next position within a transaction must be moved on. Furthermore EndTXN may only be used in conjunction with iterate(UNSAFE), never within a normal iterate loop! If the transaction is explicitly terminated within Iterate(UNSAFE) with the statement EndTXN, a new transaction must have been started again before the end of the cycle (implicitly by a statement accessing the object or explicitly with BeginTXN). The following examplesprovide further information ... ¹) the collection itself may be transient or persistent |
When iterating over persistent objects grouped in a vector, no transaction is needed to move on to the next element; after EndTXN within the cycle, you can rely on a new transaction being automatically started before a persistent object is accessed.