Insert

Insert

Parameters: an access expression, name of the back reference.

Stack

Stack	Position	Description
Stack(In)	Top	Target object
	Top 1	Object to be inserted
Stack(Out)	Top	-

The object from Stack-Top-1 is inserted into Collection c, which is reached from the target object via the access expression. Both objects must be either transient or persistent. If the collection selected in the target object has been declared in the DDI as m-1 or m-m reference, the name of a back reference must be specified as the second operand. The back reference (pointer or collection) is set after checking the type specified in the DDI. Insert is controlled by entries in the DDI and terminates with an error if an attempt is made to violate any of the specifications in the DDI. This is the case when

• the data type of the object to be inserted does not match the reference data type entered in the DDI (i.e. the object to be inserted is not an instance of the class entered in the DDI or a class derived from it)
• the object o containing collection c does not match the BackReference data type entered in the DDI (i.e. object o is not an instance of the class entered in the DDI as BackReference type or a class derived from it)
• the reference found at the start of the operation contains a type conflict with the DDI in terms of outward or backward reference
• with an m-1 relation the back reference does not point to object o at all
• for an m-n relation object o is not an element of the backreference collection.
  With O1, O2, ..., On Ox Insert(coll, backRef), the objects O1, ..., On are inserted into the collection coll, which was reached via object Ox:

Attention!
obsolete, please use link.
Insert should only be called on objects if the access path to a CX_CONDITIONED_BAG is evaluated or the object itself is a CX_CONDITIONED_BAG. In these cases Insert must be used.

Stack

Stack	Position	Description
Stack(In)	Top	Target object
	Top 1	]
	top 2	On
	. . .	. . .
	Top n-1	O1
	Top n-2	[
Stack(Out)		-

Insert

Stack

Stack	Position	Description
Stack(In)	Top	a collection
	Top 1	Object to be inserted
Stack(Out)	Top	-

The object from Stack-Top-1 is inserted into the collection lying on the Stack-Top.

Attention: Inserting clustered objects into a SET or BAG leads to enormous performance problems. See also: Clustering and Collections.

Caution: This form of insert instruction cannot be applied to collections that belong to a 1-n or m-n relation entered in the DDI (see example).

With O1, O2, ..., On coll Insert the objects O1, ..., On are inserted into the collection from the stack top (i.e. vice versa!):

Stack

Stack	Position	Description
Stack(In)	Top	Collection
	Top 1	]
	top 2	On
	. . .	. . .
	Top n-1	O1
	Top n-2	[
Stack(Out)		_

The last variant of Insert copies all elements from the collection (source) to the collection (target) and thus behaves exactly like the operator +=. Here the collections may also have different types (transient/persistent).

Stack

Stack	Position	Description
Stack(In)	Top	Collection (target)
	Top 1	Collection (Source)

Note: A transaction starts with a persistent object / collection.

232555, Insert is also supported for CX_JSON_ARRAY and behaves the same as the Append method.

Stack	Position	Description
Stack(In)	Top	CX_JSON_ARRAY
	Top-1	Element to be inserted
Stack(Out)	Top	-