Dictionary :: temporaryExtent - Create temporary extent
Temporary or transient extents can be created in order to store results of queries within an application. Transient extents are created in main storage, while temporary extents are stored in a temporary database. Both are available as long as the database handle referring to them is opened. They will be removed automatically when closing the database.
The function provides an extent definition for a temporary or transient extent, which is based on a complex data type definition passed in sTypeName.
The extent name passed in sExtentName has to be be unique and must differ from other temporary extent names. When passing an empty extent name, a unique name will be created by the system.
A key name can be passed in sKeyName in order to select an access key. When passing an empty key name, the access key is set to the primary key defined in the complex data type.
The extent can be marked as instance owner by passing true in bOwner. When not owning instances, a base extent can be passed in vBaseExtent.
In order to store instances of different types in the collection, true has to be passed in bWeakTyped.
The function returns the name of the extent definition created. In case of errors, the function throws an exception.
When a temporary extent has been created once, you can open any number of property handles for accessing the extent.
Implementation details
- sTypeName
- Type name
The type name is the name of a data type (usually) defined in the database. The type name might be passed as simple identifier or as scoped name with preceding namespace names separated by double colon '::'.
In order to pass no type name, an empty string ( String() ) may be passed.
- sExtentName - Extent name
- sKeyName
- Key name
The key name must be the name of a key defined for the given structure. Thekey name is passed as string with maximum 40 characters.
In order to pass no key name, an empty string ( String() ) has to be passed.
- vBaseExtent
- Base extent name
A base extent or base collection can be passed as access path that defines a super set for a collection. The extent name might be passed as scoped name with preceding namespace names separated by double colon '::'.
Passing an empty value or "" as extent name indicates no extent name.
- bWeakTyped
- Weak-typed option
This option must be true when a collection may refer to instances of different types, which are based on the same base type.
- bOwner
- Owning collection
This option must be set to true when the collection owns the instances. In this case the collection may not refer to instances from other collections. Removing instances from an owning collection will result in deleting instances completely.