Function CDM_CreateCollection


Definition:#include <CDM.h>
Prototype:CDM_Collection CDM_CreateCollection(char *Name, CDM_AttributeSet Attributes, char *Encoding);
Arguments:

Name: The Collection's desired disk location (Name) (char *)
Attributes: A set of Attributes (CDM_AttributeSet)
Encoding: The Collection's Encoding (Optional) (char *)

C/C++ API Sections
Tcl API Sections
Description
Return Value
Notes
See Also
Index

Description:

This function creates a new Collection object. It accepts three arguments: the Collection's name which must be the absolute path of the Collection on disk, a set of Attributes (created with CDM_CreateAtttributeSet) that will be inserted into the new Collection and the encoding of the Collection. The Collection's encoding will be the default encoding that will be used when a new Document will be created in this Collection. Note that each Document can have a different encoding than the encoding of the container Collection. The only place that this encoding will be used, is in the case where a new Document of unspecified encoding will be created.

If the Collection encoding argument is ommited, it defaults to "CDM_DefaultEncoding". "CDM_DefaultEncoding" is a global variable (of type char *), that has as initial value the system encoding. This variable is also exported at the Tcl level under the same name and as a result its value can easily be changed by the end user.

Note that the new Collection will be created only in memory. Nothing will be saved on the disk. In order for the Collection to be saved in disk, the function CDM_Sync must be called after the new Collection is created in memory. This is usually done after all of the desired Documents have been added to the newly created Collection.

Return Value:

This function returns a Collection object (of type CDM_Collection) that can be used as a reference to all functions that require a Collection argument as input. This object will be valid until the Collection that is referred by this object is closed (through CDM_Close) and the Collection removed from memory. If this object is used after the referred Collection has been closed, an undefined behaviour will occur.

If an error occurs, then NULL will be return and an error message will be left at the current active Tcl interpreter (CDM_Interp).

Note that the returned object is property of the CDM and should never be freed or modified in any way by the caller.

Notes:

This function is equivelant to tip_CreateCollection (Tcl API).

See Also:

CDM_Close, CDM_CreateDocument, CDM_CreateAttribute, CDM_CreateAttributeSet, CDM_Sync, tip_CreateCollection

CDM_DefaultEncoding


Generated by: petasis@aias on Wed Aug 16 10:31:57 PM EEST 2006.