Function CDM_NextDocument


Definition:#include <CDM.h>
Prototype:CDM_Document CDM_NextDocument(CDM_Collection Collection);
Arguments:

Collection: A Collection object. (CDM_Collection)

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

Description:

This function will return the next available Document object. "Next" means the Document that follows the one previously returned by calls to the following functions: CDM_FirstDocument, CDM_NextDocument, CDM_GetDocument, CDM_GetByExternalId.

If previous calls to this function have returned all available Documents, then NULL will be returned and the current active Tcl interpreter (CDM_Interp) will be reseted. If an error occurs, then NULL will also be return and an error message will be left at the current active Tcl interpreter. As a result, the caller must check the information stored at this Tcl interpreter in order to distinguish between the normal termination of the Document chain or an error condition.

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). NULL will also be returned if the last Document of the specified Collection has already been returned by any of the following functions: CDM_FirstDocument, CDM_NextDocument, CDM_GetDocument, CDM_GetByExternalId.

Also 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 if this function is called with a Collection object that has just be created or opened, an undefined behaviour will occur.

This function is equivelant to tip_NextDocument (Tcl API).

See Also:

CDM_Close, CDM_FirstDocument, CDM_NextDocument, CDM_GetDocument, CDM_GetByExternalId, tip_NextDocument


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