iterate

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 is

  Stack

  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

  Stack	Position	Description
  Stack(In)	Top	one object
  Stack(Out)	Top	-

  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).
  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.

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.