Function CDM_GetByExternalId


Definition:#include <CDM.h>
Prototype:CDM_Document CDM_GetByExternalId(CDM_Collection Collection, char *XID);
Arguments:

Collection: A Collection object. (CDM_Collection)
XID: The External Id of the desired Document. (char *)

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

Description:

This function will return the Document object that has the same External Id as the value of the "XID" parameter. The value of the "XID" parameter is assumed to be encoded using the UTF-8 encoding (thus enabling the existance of non Latin characters in the value). If more than one Documents having the same External Id are found in the specified Collection, then the Document that was created first will be returned.

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 a Document with the requested external Id does not exist, or 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:

Note that a Collection can have more than one Documents with the same External Id. These Documents will all have the same External Id but they will have different Document Ids.

This function will make the proper arrangements so as a call to CDM_NextDocument (or tip_NextDocument) will return the Document that was created after the one returned by this function.

This function is equivelant to tip_GetByExternalId (Tcl API).

See Also:

CDM_Close, CDM_GetDocument, CDM_NextDocument, tip_GetByExternalId


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