Function CDM_CreateDocument


Definition:#include <CDM.h>
Prototype:CDM_Document CDM_CreateDocument(CDM_Collection Collection, char *XID, CDM_ByteSequence RawData, CDM_AnnotationSet Annotations, CDM_AttributeSet Attributes, char *Encoding);
Arguments:

Collection: Collection Object. (CDM_Collection)
ExternalId: Document's External Id (disk location of original text file). (char *)
RawData: Document's Text. (CDM_ByteSequence)
Annotations: Document's Annotations (CDM_AnnotationSet)
Attributes: Document's Attributes (CDM_AttributeSet)
Encoding: Document's Encoding (Optional) (char *)

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

Description:

This function creates a new Document object in an existing Collection object. It accepts five (or six) arguments: the Collection object in which the new Document is going to be created (Document's Parent), the External Id of the Document (which represents the full path in disk of the original file that contains the Document's text), the text (RawData or ByteSequence) of the new Document, an initial Annotation set, an initial Attribute set and (optionally) the encoding of the Document.

The Collection object must be a valid object (corresponding to an open Collection) returned by either CDM_CreateCollection or CDM_OpenCollection.

The External Id must be a valid (absolute) path. A local copy of this argument will be created for use by this function. The existance of this path will not be checked. This path value will be converted automatically to a valid platform dependant path. As a result, for this value can be safely used the notation used for paths under the unix operating system. That means that the path:

/Users/petasis/Collections
will be converted interanlly to the following path, assuming windows as operating system :
C:\Users\petasis\Collections

The RawData parameter must contain the desired for the new Document text, in UTF-8 format. A local copy of this variable will be also created. If the text is not in UTF-8 (i.e. contains text just red from a file using the standart C library routines and is in the ISO 8859-7 encoding) then must be converted to UTF using CDM_ExternalToUtf. If the origin of this string is Tcl, then it is already in UTF format, as Tcl uses ONLY UTF for encoding strings internally.

The Annotations parameter must contain an Annotation set created with CDM_CreateAnnotationSet. A reference to this object will be kept.

The Attributes parameter must hold a valid Attribute set created with CDM_CreateAttributeSet. A reference to this object will also be kept.

Finally, an optional encoding can be specified. A local copy of this string will be created. The value of this parameter must be a standart Tcl encoding value (like iso8859-7 or cp1253). For all available Tcl encodings please refer to the Tcl manuals. If this parameter is ommitted, then a default value will be used. This value will be inherited from the parent Collection object. It is important for the encoding to correctly describe the text. If the given UTF string cannot be converted to the Document's encoding, then the text will be filled with the character "?" in places where the conversion will fail.

Return Value:

This function returns a Document object (of type CDM_Document) that can be used as a reference to all functions that require a Document object as input. This object will be valid until the Collection that holds this Document object is closed (through CDM_Close) and the parent Collection removed from memory. If this object is used after its parent 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_CreateDocument (Tcl API).

See Also:

CDM_CreateAnnotationSet, CDM_CreateAttributeSet, CDM_CreateCollection, CDM_ExternalToUtf, CDM_OpenCollection, tip_CreateDocument, The Tcl Encoding manual.


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