Index

DKDatastoreICM

Purpose:

The DKDatastoreICM class is the IBM Content Manager Version 8 and later implementation of the abstract class dkDatastore. Use this class to represent a Content Manager content server in your program. For earlier versions of Content Manager, use DKDatastoreDL.

This class provides facilities to query, retrieve, update, store, and manage content stored in a Content Manager datastore. Additional functions are provided by some associated classes, such as the following:

The methods add, retrieve, update, delete, and moveObject are persistent operations on a DDO representing an item or its components.

At this time, DKDatastoreICM is not thread-safe. You should not create more than one thread to call methods on the same instance of the datastore.

Since: Version 8

Class summary:

class DKEXPORT DKDatastoreICM : public dkDatastore
 {
   public:
   DKDatastoreICM();
   DKDatastoreICM(const char* configuration);
   virtual ~DKDatastoreICM();
   virtual void connect (const char* datastore_name,
                         const char* user_name = "",
                         const char* authentication = "",
                         const char* connect_string = "");
   virtual void disconnect();
   virtual void getOption(long option, DKAny& value);
   virtual void setOption(long option, DKAny& value);
 
   virtual DKAny evaluate (const char* command,
                           const short commandLangType =
                             DK_CM_XQPE_QL_TYPE,
                           const DKNVPair* parms = 0);
   virtual DKAny evaluate (DKCQExpr* cqe);
   virtual dkResultSetCursor* execute (const char* command,
                                       const short commandLangType =
                                         DK_CM_XQPE_QL_TYPE,
                                       const DKNVPair* parms = 0);
   virtual dkResultSetCursor* execute (DKCQExpr* cqe);
   virtual void executeWithCallback (const char* command,
                                     const short commandLangType,
                                     const DKNVPair* parms,
                                     dkCallback* callbackObj);
   virtual void executeWithCallback (DKCQExpr* cqe,
                                     dkCallback* callbackObj);
   virtual void validate (const char* xqpe_query);
 
   virtual void addObject(dkDataObject* dataobj);
   virtual void addObject(dkDataObject* dataobj, long option);
   virtual void addObjects(dkCollection * ddoCollection);
   virtual void addObjects(dkCollection * ddoCollection, long option);
 
   virtual void deleteObject(dkDataObject* dataobj, long option);
   virtual void deleteObject(dkDataObject* dataobj);
   virtual void deleteObjects(dkCollection *ddoColl, long option);
   virtual void deleteObjects(dkCollection *ddoColl);
 
   virtual void retrieveObject(dkDataObject* dataobj);
   virtual void retrieveObject(dkDataObject* dataobj,long option);
   virtual void retrieveObject(dkDataObject* dataobj, const DKNVPair* parms, long arraySize);
   virtual void retrieveObjects( dkCollection *ddoColl);
   virtual void retrieveObjects( dkCollection *ddoColl, int option);
   virtual void retrieveObjects( dkCollection *ddoColl, const DKNVPair* parms, long arraySize);
 
   virtual void updateObject(dkDataObject* dataobj);
   virtual void updateObject(dkDataObject* dataobj, long option);
 
   virtual void commit ();
   virtual void rollback ();
   virtual DKBoolean isConnected();
   virtual DKHandle* connection();
   virtual DKHandle* handle(const char* type);
   virtual dkCollection* listDataSources();
   virtual DKString* listDataSourceNames(long& arrarySize);
   virtual dkCollection* listEntities();
   virtual DKString* listEntityNames(long& arraySize);
   virtual dkCollection* listEntityAttrs(const char* entityName);
   virtual DKString* listEntityAttrNames(const char* entityName,
                                         long& arraySize);
   virtual dkDatastoreDef* datastoreDef();
   virtual DKString registerMapping(DKNVPair* sourceMap);
   virtual void unRegisterMapping(const char* mappingName);
   virtual DKString* listMappingNames(long& arraySize);
   virtual dkSchemaMapping* getMapping(const char* mappingName);
   virtual dkExtension* getExtension(const char* extensionName);
   virtual void addExtension(const char* extensionName,
                             dkExtension* extensionObj);
   virtual void removeExtension(const char* extensionName);
   virtual DKString* listExtensionNames(long& arraySize);
   virtual DKDDO* createDDO(const char* objectType, long Flags);
   virtual DKDDO* createDDO(DKString pidString);
   virtual DKDDO* createDDO(DKPidICM * pid);
   virtual DKDDO* createChildDDO(DKString objectType, DKString  componentName);
   virtual void checkIn(dkDataObject* item);
   virtual void checkOut(dkDataObject* item);
   virtual void unlockCheckedOut(dkDataObject* dataObject);
   virtual void startTransaction();
 
   virtual DKBoolean adminDomainEnabled();
   virtual DKBoolean informationMiningEnabled();
   virtual DKBoolean LDAPEnabled();
   virtual short platform();
   virtual DKBoolean textSearchEnabled();
   virtual DKBoolean workflowEnabled();
   virtual DKBoolean isCheckedOut(dkDataObject* dobj);
   virtual DKString checkedOutUserid(dkDataObject* dobj);
   DKString schemaName();
   dkCollection* listEvents(const char* itemId, short maxResults);
   dkCollection* listAdminEvents(short maxResults);
   dkCollection* retrieveEvent(long eventCode);
   void writeEvent(DKEventDefICM* aEvent);
   virtual void moveObject(dkDataObject* sourceDDO, dkDataObject* destinationDDO, long options=0);
   virtual void moveObject(dkDataObject* ddo, const char* destinationItemType);
   dkXDO* retrieveFormOverlay(DKString name);
virtual void changePassword(const char* userId,const char* oldPwd,const char* newPwd);
virtual DKBoolean setLocaleAndCodePage(char * locale, char * codePage);
virtual void getLocaleAndCodePage(DKString & locale, DKString & codePage);
       };
 

Members:

Constructors and destructor
DKDatastoreICM()

Constructs the datastore and initializes with the default configuration.

DKDatastoreICM(const char* configuration)

Constructs the datastore object and initializes it using the supplied configuration stringParameters: configuration - configuration string used for initialization. The configuration string is a sequence of name/value pairs separated by semi-colons. - DSNAME = datastore_name; Supplies the datastore name. Optional. -DBAUTH = SERVER|CLIENT; Indicates whether user authentication is done on the client or on the server. SERVER authentication is the default. Optional - LDAPORG = LDAP organization Specifies the LDAP organization providing the directory information. This can be used when the list of datasources is in IBM Secure Way. Optional - LANCACHE = YES|NO; Determines whether LANCACHE is enabled or disabled. Default value is NO (LANCACHE disabled)

virtual ~DKDatastoreICM()

Destructor for this object.

Member functions

connect
Establishes a connection to a Content Manager Version 8 datastore.

Parameters: datastore_name - the datastore name used for connection. user_name - the user name used for connection.authentication - the authentication used for connection. connect_string - the connect string used for connection. This is used to provide additional connection options. Valid connect_string name/value pairs separated by semi colons.

  • SQLUID=<database userid> database userid (optional)
  • SQLPWD=<database password> database password (optional)
  • DBAUTH=<SERVER | CLIENT> database authentication (optional)
  • SCHEMA=<database schema> database schema name (optional)
  • APPLNAME=<application name> library server application name (optional)
  • NPWD=<new federated password for federated userid> new federated password. Only valid if federated userid is not a system userid. (optional)
  • LANG=<federated database language> federated server language. (ie ENU which is the default) (optional)
  • TRACESERVERLEVEL=<trace level> trace level (optional)

    The default trace level for the server is 0 (ICMTRACE_OFF).

    ICM trace flags:

    0 ICMTRACE_OFF

    1 ICMTRACE_BASIC

    2 ICMTRACE_DETAILED

    4 ICMTRACE_DATA

    8 ICMTRACE_PERFORMANCE

    16 ICMTRACE_PARSEBUILD

    32 ICMTRACE_MEMDEBUG

    256 ICMTRACE_CACHE_TRACE

    512 ICMTRACE_CACHE_ALLOC

    1024 ICMTRACE_CACHE_MGT

    Trace level is constructed by adding the numbers above. For example, a common tracing level is 15 (calculated by adding ICMTRACE_BASIC, ICMTRACE_DETAILED, ICMTRACE_DATA, and ICMTRACE_PERFORMANCE).

  • DBAUTH=<SERVER | CLIENT> database authentication (optional)
  • LANCACHE=<YES | NO> LAN Cache (Default NO) (optional)

Throws:DKException - if a problem is encountered.

virtual void connect (const char* datastore_name,
const char* user_name = "",
const char* authentication = "",
const char* connect_string = "");

disconnect
Disconnects from a Content Manager datastore. Parameters: None Returns: None

Exceptions: DKException if a problem is encountered.

virtual void disconnect();

getOption
Gets a datastore option. The valid options and values are as follows:

Content Manager V8 Datastore Options: DK_ICM_OPT_LAN_CACHE option to indicate lan cache.The valid values are: DK_CM_TRUE lan cache true. DK_CM_FALSE lan cache false. DK_CM_OPT_CACHE To indicate if caching is enabled for schema information. ex: itemTypes, attributes, etc. DK_CM_TRUE cache true. DK_CM_FALSE cache false.

virtual void getOption(long option, DKAny& value);

setOption
Sets a datastore option. The valid options and values are as above.

Parameters: option - the option identifier. value - the option value.

Exceptions: DKException if a problem is encountered.

virtual void setOption(long option, DKAny& value);

evaluate
Evaluates query string command by executing it against this datastore and returning all results in a DKResults collection. The total number of returned results can be limited by specifying the DK_CM_PARM_MAX_RESULTS query option. For important details on result set cursor and transactions, refer to the execute method. For details on query syntax, refer to the Application Programming Guide. Example:
DKString query = "/Journal/Journal_Article[contains-text(@Title, \" 'Design' & 'Index' \")=1] SORTBY (@Title)";
DKNVPair options[3];
options[0].setName (DK_CM_PARM_MAX_RESULTS);
options[0].setValue (DKAny (DKString ("50")));
options[1].setName (DK_CM_PARM_RETRIEVE);
options[1].setValue (DKAny(DK_CM_CONTENT_ATTRONLY|
       DK_CM_CONTENT_LINKS_OUTBOUND));
options[2].setName (DK_CM_PARM_END);
           
DKAny queryResults = dsICM->evaluate(query, DK_CM_XQPE_QL_TYPE, options);
DKResults* results = (DKResults*)(dkCollection*) queryResults.value();
           
// Display results in the collection.
dkIterator* iter = results->createIterator();
cout << "  Number of Results: " << results->cardinality() << endl;
DKDDO* ddo = 0;
DKAny* element = 0;
DKString itemId = "";
while(iter->more()) {
   element = (DKAny*) iter->next();
   ddo = (DKDDO*) element->value();
   itemId = ((DKPidICM*)ddo->getPidObject())- >getItemId();
   cout << "     - Item ID:  " << itemId << "  ("
        << ddo->getPidObject()->getObjectType() << ")" << endl;
   delete ddo;
}

Parameters:command - a query string commandLangType - a type of query (must be DK_CM_XQPE_QL_TYPE) parms - additional query options in the form of name/value pairs (refer to the execute method for more details). Returns: a collection of results for this query

virtual DKAny evaluate(const char* command, const short commandLangType =
DK_CM_ICM_QL_TYPE,const DKNVPair* parms = 0);

evaluate
Evaluates a combined query expression cqe against this datastore and returns the results in a collection. This method is mostly used internally to run federated queries and is not advised for external use. Use the string version of the evaluate method to execute your queries.

Parameters: cqe - a combined query expression object

Returns: a collection of results for this query

virtual DKAny evaluate (DKCQExpr* cqe);

execute
Executes query string command against this datastore and returns a result set cursor object to provide access to the results. For details on query syntax, refer to the Application Programming Guide. A few notes about using the result set cursor. Important: make sure to close and destroy the result set cursor once you have finished using it. To close the result set cursor, call one of the following methods: dkResultSetCursor::close(), dkResultSetCursor::destroy(). To completely clean up the result set cursor, it is suggested that you use dkResultSetCursor::destroy(). All open result set cursors are closed when either dkDatastore::disconnect() ordkDatastore::destroy() method is called. Example:
DKString query = "/Journal[@NumPages > 50]";
DKNVPair options[3];
options[0].setName (DK_CM_PARM_MAX_RESULTS);
options[0].setValue (DKAny (DKString ("100")));
options[1].setName (DK_CM_PARM_RETRIEVE);
           options[1].setValue(DKAny(DK_CM_CONTENT_CHILDREN) );
options[2].setName (DK_CM_PARM_END);
           
dkResultSetCursor* cursor = dsICM->execute(query, DK_CM_XQPE_QL_TYPE, options);
           
DKDDO* ddo = 0;
DKString itemId = "";
           
// Display results using a result set cursor.
while((ddo = cursor->fetchNext()) != 0){
  itemId = ((DKPidICM*)ddo->getPidObject())->getItemId();
  cout << "     - Item ID:  " << itemId << "  ("
        << ddo->getPidObject()->getObjectType() << ")" << endl;
  delete ddo;
}
// VERY IMPORTANT STEP:
cursor->destroy(); // Close & destroy cursor, ending implicit transaction.

Parameters:command - a query string commandLangType - a type of query (must be DK_CM_XQPE_QL_TYPE) params - additional query options in the form of name/value pairs Description of query options:

  • Name = DK_CM_PARM_MAX_RESULTS Value = A number contained in a DKString that specifies the maximum number of results that will be returned by the query. If this option is specified, the result set cursor stops processing results when this number of results has been processed. No indication is given to the application that there are additional results available. If max results is set to 0, there is no max, so all results will be returned. Example: DKString ("5")
  • Name = DK_CM_PREPARE_QUERY Value = none required If this option is specified, the query is only prepared, but the cursor is not opened, and the query is not actually executed. The result set cursor's open() method must be called to open the cursor and execute the query. If this option is not specified, the query will be prepared, the cursor opened, and the query will be executed.
  • Name = DK_CM_PARM_PREFETCH_SIZE Value = a DKAny containing a long If this option is specified, the value for this option indicates the block size in which results are retrieved from the datastore. A small value N will allow for faster display of the first N results, but will increase overall retrieval time for the whole result set. If this option is not specified, a default block size, which should be optimal for majority of applications, will be used.
  • Name = DK_CM_PARM_CONTENT Value = a DKAny containing a long This option specifies how much content is retrieved when results are returned from the query. This option is ignored if the DK_CM_PARM_RETRIEVE is specified. It is suggested to always use DK_CM_PARM_RETRIEVE option instead of the DK_CM_PARM_CONTENT option. Value = one of the following strings: "IDONLY", "NO", "ATTRONLY", and "YES". Here is how these option values are mapped to retrieve option values used with the DK_CM_PARM_RETRIEVE option: "IDONLY" = DK_CM_CONTENT_IDONLY "NO" = DK_CM_CONTENT_ATTRONLY "ATTRONLY" = DK_CM_CONTENT_ATTRONLY "YES" = (DK_CM_CONTENT_ATTRONLY | DK_CM_CONTENT_CHILDREN) If this option is not specified, default retrieval value is "ATTRONLY".
  • Name = DK_CM_PARM_RETRIEVE Value = described under DKDatastoreICM::retrieveObject(dkDataObject*, long) method. If this option is specified, it takes precedence over the DK_CM_PARM_CONTENT option above. This option specifies what to retrieve for the items that are returned. If this option is not specified, retrieval is DK_CM_CONTENT_ATTRONLY. If you do not want the results to be retrieved at all, set the value to DK_CM_CONTENT_IDONLY. For performance reasons, retrieve options related to content retrieval from the resource manager (e.g. DK_CM_CONTENT_YES and DK_CM_CONTENT_ONLY options) are ignored. This behavior is equivalent to content retrieve option DK_CM_CONTENT_NO. To retrieve content stored on the resource manager, use the DDO returned from query, set the content retrieve option, and call one of the retrieve methods that accept a single DDO. Example: DKAny((long) DK_CM_CONTENT_CHILDREN)
  • Name = DK_CM_PARM_PROJECTION_LIST Value = described under DKDatastoreICM::retrieveObject(dkDataObject*, const DKNVPair*, long) method. This option allows the user to apply a projection onto which attributes get retrieved in the hierarchical representation of the returned item. This way, the returned DDO is set with only the desired attributes. Returns: a datastore result set cursor to the results of the query virtual dkResultSetCursor* execute (const char* command, const short commandLangType DK_CM_ICM_QL_TYPE, const DKNVPair* parms = 0);

execute
Executes a combined query expression cqe against this datastore and returns a result set cursor object to provide access to the results. This method is mostly used internally to run federated queries and is not advised for external use. Use the string version of the execute method to execute your queries.

Parameters: cqe- a combined query expression object Returns: a datastore result set cursor to the results of the query

virtual dkResultSetCursor* execute (DKCQExpr* cqe);

executeWithCallback
Executes query string command against this datastore in asynchronous manner and sends the results to the specified callback object callbackObj in blocks. You can get the results from the callback object as soon as they are available. A callback object is any object that implements the dkCallback interface. This object is defined and created by the user program. IMPORTANT: NO datastore operations are allowed from the callback object. For example, it is not allowed to list item type definitions or call CRUD (Create, Retrieve, Update, Delete) methods inside of the callback object's dataCallback(dkCollection*, DKBoolean) method. You can display the results as long as this does not require datastore operations or you can wait until the query completes as indicated by the isDone() method returning true. If you want to stop receiving results, call the cancelQuery() method on your callbackObj object and wait until the isDone() method returns true. Example:
DKString query = "/Journal/Journal_Article[@VERSIONID = latest-version(.)]";
DKNVPair options[2];
options[0].setName (DK_CM_PARM_RETRIEVE);
options[0].setValue (DKAny(DK_CM_CONTENT_ITEMTREE));
options[1].setName (DK_CM_PARM_END);
           
// Create Callback Object (any object implementing dkCallback interface).
SSearchCallbackObjectICM callbackObject;
dsICM->executeWithCallback(query, DK_CM_XQPE_QL_TYPE, options,                                    (dkCallback*)&callbackObject);
 
// Wait for Callback Object to receive all results.
// This thread would normally do other work instead of simply waiting.
DKBoolean isDone = FALSE;
while(isDone == FALSE) {
  cout << "Waiting...";
  Sleep(100);
  isDone = callbackObject.isDone();
  if(callbackObject.error()) {
    cout << callbackObject.getFirstException();
  }
}
           
// Method in the callback object's class
// that is called for every block of results.
virtual DKBoolean dataCallback (dkCollection* ddoList, DKBoolean resultsComplete) 
{serverIsDone = resultsComplete; // Save the indication of whether or not the server is done.
 
   try {
     if (ddoList != NULL) {
       dkIterator* iter = ddoList  >createIterator();
       DKDDO* ddo = 0;
       DKAny* element = 0;
       DKString itemId = "";
       while (iter->more()) {
           element = (DKAny*) iter->next();
           ddo = (DKDDO*)(dkDataObjectBase*) element->value();
           results->addElement (ddo);  
// Save the result for later
           itemId = ((DKPidICM*)ddo->getPidObject())->getItemId();
            cout << "Callback Object:  - Item ID:  " << itemId << "  ("
  << ddo->getPidObject()->getObjectType() << ")" << endl;       }
               }
             } catch (DKException e) {
               printException (e);
               if (firstException == NULL)
                 firstException = new DKException (e);    // If it is the first failure, save it
             }
if (userRequestsCancel) { // If the user requests to cancel the query, 
// report to server.
    return(true);
} else {                  // Otherwise, 
return whether or not the server
// has indicated that it is done.
return (serverIsDone);
       }
}

Parameters: command - a query string commandLangType - a type of query (must be DKConstant.DK_CM_XQPE_QL_TYPE) parms - additional query options in the form of name/value pairs callbackObj - an object that will be called by this method for every block of results.

virtual void executeWithCallback( const char* command,
const short commandLangType,
const DKNVPair* parms,
dkCallback* callbackObj);

executeWithCallback
Executes a combined query expression cqe against this datastore in asynchronous manner and sends the results to the specified callback object callbackObj in blocks. This method is mostly used internally to run federated queries and is not advised for external use. Use the string version of the executeWithCallback method to execute your queries.

Parameters: cqe - a combined query expression object. callbackObj - an object that will be called by this method for every block of results.

virtual void executeWithCallback(DKCQExpr* cqe, dkCallback* callbackObj);

validate
Validates the syntax, but not the semantics, of the query string. For instance, it does not check that the correct types are used in comparisons (such as comparing a string attribute to an integer), or that text search is done on attributes that are text-searchable. This type of semantic error causes exceptions to be thrown by the evaluate/execute/executeWithCallback methods.

Parameters: xqpe_query - an XML-based query string that would also be passed to the evaluate, execute, and executeWithCallback methods.

virtual void validate(const char* xqpe_query);

addObject
Add this new item, including all child components, to the Content Manager persistent store. The tree of component DDOs with all supported attributes, properties, content, and child components are added through the root component DDO. Use the appropriate createDDO() methods to create the item in memory first. By default, the item will be checked in (unlocked).
// Given a connected DKDatastoreICM* object named 'dsICM' 
DKDDO* ddo = dsICM->createDDO("myItemType",DK_CM_DOCUMENT); 
short dataId= ddo->dataId("myAttr"); 
ddo->setData(dataId,DKString("My Attribute Value")); 
dsICM.addObject(ddo); 

Parameters: ddoObject - data object for the root component of the item to be added.

Returns: None

Memory management: The input DDO object should be deleted by the caller.

virtual void addObject(dkDataObject* ddoObject);

addObject
Add this new item, including all child components, to the Content Manager persistent store. The tree of component DDOs with all supported attributes, properties, content, and child components are added through the root component DDO. Use the appropriate createDDO() methods to create the item in memory first. By default, the item will be checked in (unlocked).
// Given a connected DKDatastoreICM* object named 'dsICM' 
DKDDO* ddo = dsICM->createDDO("myItemType",DK_CM_DOCUMENT); 
short dataId= ddo->dataId("myAttr"); 
ddo->setData(dataId,DKString("My Attribute Value")); 
dsICM.addObject(ddo); 

Parameters: ddoObject - DDO to be added option - DK_CM_CHECKIN or 0 (default) Check in (unlock) the item and DK_CM_CHECKOUT Check out (lock) the item.

Returns: None

Memory management: The input DDO object should be deleted by the caller.

virtual void addObject(dkDataObject* dataobj, long option);

addObjects
Adds a collection of new items, including all child components, to the Content Manager persistent store. The tree of component DDOs, with all supported attributes, properties, content, and child components, are added through the root component DDO of each item. Use the appropriate createDDO() methods to create the item in memory first. By default, the item will be checked in (unlocked). A collection may be created using the DKSequentialCollection object.
// Given a connected DKDatastoreICM* object named 'dsICM' 
DKDDO* ddo1 = dsICM->createDDO("myItemType",DK_CM_DOCUMENT); 
DKDDO* ddo2 = dsICM->createDDO("myItemType",DK_CM_ITEM); 
DKDDO* ddo3 = dsICM->createDDO("myItemType",DK_CM_FOLDER); 
short dataId1= ddo1->dataId("myAttr"); 
short dataId2= ddo2->dataId("myAttr"); 
short dataId3= ddo3->dataId("myAttr"); 
ddo1->setData(dataId1,DKString("My Attribute Value")); 
ddo2->setData(dataId2,DKString("My Attribute Value")); 
ddo3->setData(dataId3,DKString("My Attribute Value")); 
dkCollection* coll = new DKSequentialCollection(); 
coll->addElement((dkDataObjectBase*)ddo1); 
coll->addElement((dkDataObjectBase*)ddo2); 
coll->addElement((dkDataObjectBase*)ddo3); 
dsICM->addObjects(coll); 

Parameters: ddoCollection - collection of root component DDOs for the items to be added. The dkCollection may be created using a DKSequentialCollection object.

Returns: None

Memory management: The input DDO collection and the DDO objects in the collection should be deleted by the caller.

virtual void addObjects(dkCollection * ddoCollection);

addObjects
Adds a collection of new items, including all child components, to the Content Manager persistent store. The tree of component DDOs, with all supported attributes, properties, content, and child components, are added through the root component DDO of each item. Use the appropriate createDDO() methods to create the item in memory first. By default, the item will be checked in (unlocked). A collection may be created using the DKSequentialCollection object.

Parameters: ddoCollection - collection of root component DDOs for the items to be added. The dkCollection may be created using a DKSequentialCollection object. option - DK_CM_CHECKIN or 0 (default) to check in (unlock) the item or DK_CM_CHECKOUT to check out (lock) the item

Returns: None

Memory management: The input DDO collection and the DDO objects in the collection should be deleted by the caller.

virtual void addObjects(dkCollection * ddoCollection, long option);

deleteObject
Deletes this item version from the persistent store.

Parameters: dataObj - the root component DDO for the item version to be deleted from this datastore.

Returns: None

Memory management: The input DDO object should be deleted by the caller.

virtual void deleteObject(dkDataObject* dataObject);

deleteObject
Deletes this item version from the persistent store.

Parameters: dataObj - the root component DDO for the item version to be deleted from this datastore.

Options: 0 (zero) default - Perform a regular delete, deleting the item version represented by this DDO. DKConstantICM.DK_ICM_DELETE_ALL_VERSIONS - Delete all versions of the item.

Returns: None

Memory management: The input DDO object should be deleted by the caller.

virtual void deleteObject(dkDataObject* dataObject,option);

deleteObjects
Deletes item versions contained in a collection from the persistent store. A group of root component DDOs for item versions to be deleted are provided in a dkCollection. You may create a dkCollection using the DKSequentialCollection object.

Parameters: ddoCollection - the collection of root component DKDDO objects representing items versions to be deleted from this persistent store.

Returns: None

Memory management: The input DDO collection and the DDO objects in the collection should be deleted by the caller.

virtual void deleteObjects(dkCollection *ddoColl);

deleteObjects
Deletes item versions contained in a collection from the persistent store. Parameters:

ddoCollection - - the collection of root component DKDDO objects representing items versions to be deleted from this persistent store. option - delete option: 0 (zero) default - Perform a regular delete, deleting the item version represented by this DDO. DKConstantICM.DK_ICM_DELETE_ALL_VERSIONS - Delete all versions of the item.

virtual void deleteObjects(ddoColl*option);

retrieveObject
Retrieves the specified DDO from the Content Manager persistent store. The DDO should contain a valid persistent identifier(PID). The DDO may represent a root item or child component of an item. By default, component attributes and up to one level of child components will be retrieved. Further information such as grandchildren, links, and folder table of contents will not be retrieved by this method. For more or less information or for greater control over the data retrieved, refer to the retrieveObject(dataObject,option) method.

Parameters:ddoObject - DDO to be retrieved Exceptions:DKDataObjectNotFound

Memory management: The DDO object retrieved should be deleted by the caller.

virtual void retrieveObject(dkDataObject* dataObject);

retrieveObject
Retrieve this DDO from the Content Manager persistent store with specified options. The DDO should contain a valid persistent identifier. Options can be combined using the bitswise OR boolean operator. For example: (DK_CM_CONTENT_ATTRONLY | DK_CM_CONTENT_YES)

Parameters: dataobj - DDO to be retrieved. options - retrieve options are described below:

  • level options:
    • DK_CM_CONTENT_ATTRONLY: retrieves current-level attributes
    • DK_CM_CONTENT_CHILDREN: retrieves the PID's of immediate children of the current DDO
    • DK_CM_CONTENT_ONELEVEL: equivalent to (DK_CM_CONTENT_CHILDREN | DK_CM_CONTENT_ATTRONLY)
    • DK_CM_CONTENT_ITEMTREE: retrieves the whole item tree hierarchy, including links as skeletons only; this option takes precedence over other level options. It also includes folder table of contents.
    • DK_CM_CONTENT_ITEMTREE_NO_LINKS: allows the full hierachy to be retrieved without retrieving links for folder contents.
  • miscellaneous options:
    • DK_CM_VERSION_LATEST: retrieves the latest version of this item
    • DK_CM_CHECKOUT: retrieves the item and checks it out from the datastore
    • DK_CM_CONTENT_LINKS_OUTBOUND: retrieves the links originating from this item and a folder's table of contents. Note that the folder contents retrieved are DKDDO objects with completed PIDs that must be retrieved in an additional call for retrieval on them individually or as a collection.
    • DK_CM_CONTENT_LINKS_INBOUND: retrieves the links pointing to this item
  • resource content options:
    • DK_CM_CONTENT_NO: contents of the Resource Object are not retrieved; this option is ignored for items that do not have content associated with them on the Resource Manager
    • DK_CM_CONTENT_YES: contents of the Resource Object are retrieved; this option is ignored for items that do not have content associated with them on the resource manager
    • DK_CM_CONTENT_ONLY: contents of the Resource Object are retrieved, but this option can only be used after retrieve with DK_CM_CONTENT_NO or DK_CM_CONTENT_YES has been done; this option is ignored for items that do not have content associated with them on the resource manager

The default retrieve option is DK_CM_CONTENT_ONELEVEL. Exceptions:DKDataObjectNotFound

Returns: None

Memory management: The DDO object retrieved should be deleted by the caller.

virtual void retrieveObject(dkDataObject* dataobj,long option);

retrieveObject
Retrieves this DDO from the persistent store, with options. You can specify a retrieval with projection by providing a list of selected attributes in the option parameter. Attributes not in the list will not be retrieved.

Parameters:dataObj - DDO to be retrieved parms - name/value pair options. See getOption for valid values arraySize - number of name/value pair options in the array

Returns: None

Memory management: The DDO object retrieved should be deleted by the caller.

virtual void retrieveObject(dkDataObject* dataobj, const DKNVPair* parms, long arraySize);

retrieveObjects
Retrieves this collection of DDO's from the persistent store. If the retrieval of all the DDO's in the collection fails, then an DKDataObjectNotFoundException will be thrown. If the retrieval of at least one of the the DDO's in the collection succeeds no exception will be thrown. To find out which ones are successful or fail,we can use the DDO property DK_CM_PROPERTY_LAST_OPERATION, for each ddo. Each DDO property value is a DKNVPair which includes a name part and value part. The corresponding values for the name part are: DK_CM_LAST_OP_RETRIEVE DK_CM_LAST_OP_UPDATE DK_CM_LAST_OP_DELETE DK_CM_LAST_OP_ADD The corresponding values for the value part are: DK_CM_SUCCESS DK_CM_FAIL The default retrieve option is described under the retrieveObject(dkDataObject *, int) method. These defaults will be applied to all DDOs that comprise the collection. For performance reasons, retrieve options related to content retrieval are ignored in retrieve methods that accept collections of DDO's. This behavior is equivalent to having the content retrieve option DK_CM_CONTENT_NO specified. Use retrieve methods accepting a single DDO to retrieve content.

Parameters:ddoColl - collection of DDOs to be retrieved. The dkCollection object may be obtained from a search results (DKResults), from a child collection of a parent DDO (DKChildCollection), from the collection of folder contents (DKFolder), from a document parts collection (DKParts), or you may create a collection separately using the DKSequentialCollection object.

Returns: None

Memory management: The DDO object in the collection and the collection itself are to be deleted by the caller.

virtual void retrieveObjects( dkCollection *ddoColl);

retrieveObjects
Retrieves this collection of DDO's from this datastore. If the retrieval of all the DDO's in the collection fails, then a DKDataObjectNotFoundException will be thrown. If the retrieval of at least one of the the DDO's in the collection succeeds no exception will be thrown. To find out which ones are successful or fail,we can use the DDO property DK_CM_PROPERTY_LAST_OPERATION for each ddo. Each DDO property value is a DKNVPair which includes a name part and value part. The corresponding values for the name part are: DK_CM_LAST_OP_RETRIEVE DK_CM_LAST_OP_UPDATE DK_CM_LAST_OP_DELETE DK_CM_LAST_OP_ADD The corresponding values for the value part are: DK_CM_SUCCESS DK_CM_FAIL

Parameters: ddoCollection - Collection of DDOs to be retrieved. The dkCollection object my be obtained from a search results (DKResults), from a child collection of a parent DDO (DKChildCollection), from the collection of folder contents (DKFolder), from a document parts collection (DKParts), or you may create a collection separately using the DKSequentialCollection object. options - retrieve options are described below:

  • level options:
    • DK_CM_CONTENT_ATTRONLY: retrieves current-level attributes
    • DK_CM_CONTENT_CHILDREN: retrieves the PID's of immediate children of the current DDO
    • DK_CM_CONTENT_ONELEVEL: equivalent to (DK_CM_CONTENT_CHILDREN | DK_CM_CONTENT_ATTRONLY)
    • DK_CM_CONTENT_ITEMTREE: retrieves the whole item tree hierarchy, including links as skeletons only; this option takes precedence over other level options
  • miscellaneous options:
    • DK_CM_VERSION_LATEST: retrieves the latest version of this item
    • DK_CM_CHECKOUT: retrieves the item and checks it out from the datastore
    • DK_CM_CONTENT_LINKS_OUTBOUND: retrieves the links originating in this item
    • DK_CM_CONTENT_LINKS_INBOUND: retrieves the links pointing to this item
  • resource content options:
    • DK_CM_CONTENT_NO: contents of the Resource Object are not retrieved; this option is ignored for items that do not have content associated with them on the resource manager
    • DK_CM_CONTENT_YES: contents of the Resource Object are retrieved; this option is ignored for items that do not have content associated with them on the resource manager
    • DK_CM_CONTENT_ONLY: contents of the Resource Object are retrieved, but this option can only be used after retrieve with DK_CM_CONTENT_NO or DK_CM_CONTENT_YES has been done; this option is ignored for items that do not have content associated with them on the resource manager

The default retrieve option is DK_CM_CONTENT_ONELEVEL. Exceptions:DKDataObjectNotFound

Returns: None

Memory management: The DDO objects in the collection and the collection itself are to be deleted by the caller.

virtual void retrieveObjects( dkCollection *ddoColl, int option);

retrieveObjects
Retrieves a collection of DDOs from the persistent store. A retrieval with projections can be specified by providing a list of selected attributes in the name/value pairs parms parameter. Attributes not in the list will not be retrieved. If the retrieval of all the DDO's in the collection fails, then a DKDataObjectNotFoundException will be thrown. If the retrieval of at least one of the the DDO's in the collection succeeds no exception will be thrown. To find out which ones are successful or fail,we can use the DDO property DK_CM_PROPERTY_LAST_OPERATION, for each ddo. Each DDO property value is a DKNVPair which includes a name part and value part. The corresponding values for the name part are: DK_CM_LAST_OP_RETRIEVE DK_CM_LAST_OP_UPDATE DK_CM_LAST_OP_DELETE DK_CM_LAST_OP_ADD The corresponding values for the value part are: DK_CM_SUCCESS DK_CM_FAIL For performance reasons, retrieve options related to content retrieval are ignored in retrieve methods that accept collections of DDO's. This behavior is equivalent to content retrieve option DK_CM_CONTENT_NO. Use retrieve methods that accept a single DDO to retrieve content.

Memory management: The DDO objects in the collection and the collection itself are to be deleted by the caller. The DDNVPair objects are to be deleted by the caller.

virtual void retrieveObjects( dkCollection *ddoColl, const DKNVPair* parms, long arraySize);

updateObject
Update this item version in the persistent store. A new version of the items is created if the item type definition has versioning set to Always.

The default behavior of updateObject is not to check in the item after update. Parameters:dataObject - root component DDO for the item version to be updated.

Returns: None

Memory management: The input DDO object should be deleted by the caller.

virtual void updateObject(dkDataObject* dataObject);

updateObject
Updates this DDO in the persistent datastore. A new version of this item is created if the item type definition has versioning set to Always.

The default behavior of updateObject is not to check in the item after the update. Parameters:dataObj - the item DDO to be updated option - update options Valid values are: DK_CM_CHECKIN: check in the item after the update. Default is not to check in the item DK_CM_VERSION_LATEST: update the latest version DK_CM_VERSION_NEW: create a new version of this item. This is only applicable if the version control on the item type is set to version the item or to application controlled. If that is not the case, the item is updated and no error is returned, but a new version is not created.

Returns: None

Memory management: The input DDO object should be deleted by the caller.

virtual void updateObject(dkDataObject* dataobj, long option);

startTransaction
Starts an explicit transaction. The user needs to call either commit() or rollback() to end the transaction and to release the resources associated with the transaction. startTransaction cannot be called twice without calling commit() or rollback in between. If an error is detected by the APIs after this call and before commit() or rollback() are called(), the API may rollback all persistent changes after this point when an error occurs.

Parameters: None

Returns: None

virtual void startTransaction();

commit
Commits all persistent changes performed by API calls after an explicit transaction was started with the startTransaction() method. If an explicit transaction has not been started, this call will have no persistent effect.

Parameters: None

Returns: None

virtual void commit ();

rollback
Rollback all persistent changes performed by API calls after an explicit transaction was started with the startTransaction() method. If an explicit transaction has not been started or if the transaction was automatically rolled back, this call will have no persistent effect.

Parameters: None

Returns: None

virtual void rollback (); 

isConnected
Determines if this datastore object has been connected. Please note that this does not validate the status of the current connection. It returns true if DKDatastoreICM::connect() has been called and completed successfully, regardless of the actual state of the current communication.

Returns: TRUE if the datastore object has been connected, FALSE otherwise.

Parameters: None

virtual DKBoolean isConnected();

connection
Retrieves the connection handle for the connection to this datastore.

Parameters: None

Returns: Connection handle as an instance of DKHandle

virtual DKHandle* connection();

listDataSources
Returns a list of data sources as collection of dkServerDef instances.

Returns: Collection of data sources as instances of dkServerDef.

Parameters: None

Memory management: The server def objects in the collection and the collectino itself are to be deleted by the caller.

virtual dkCollection* listDataSources();

listDataSourceNames
Retrieves a list of data source names.

Parameters: arraySize - size of the returned array Returns: List of data source names as an array of DKString variables.

Memory management: The DKString array returned is to be deleted by the caller.

virtual DKString* listDataSourceNames(long& arrarySize);

handle
Retrieves the datastore handle.

Parameters: type - type of datastore handle wanted. Various Types - DK_ICM_CONNECT_HANDLE Returns:Aa datastore handle

virtual DKHandle* handle(const char* type);

listEntities
Retrieves a list of entities from the persistent store.

Parameters: None

Returns: Collection of entity definitions as instances of dkEntityDef.

Memory management: The entity objects in the collection and the collection itself are to be deleted by the caller.

virtual dkCollection* listEntities();

listEntityNames
Retrieves a list of entity names from the persistent store.

Parameters: arraySize - size of the retrieved array. Returns: array of entity names as instances of DKString.

Memory management: The DKString array returned is to be deleted by the caller.

virtual DKString* listEntityNames(long& arraySize);

listEntityAttrs
Retrieve a list of attributes for the specified entity.

Parameters: entityName - name of the entity for which attributes have to be retrieved. Returns: list of attribute definitions as instances of DKAttrDefICM.

Memory management: The attribute objects in the collectin and the collectiion itself are to be deleted by the caller.

virtual dkCollection* listEntityAttrs(const char* entityName);

listEntityAttrNames
Gets a list of attribute names for a given entity name.

Parameters: entityName - name of the entity that owns the attributes. arraySize - size of the retrieved array. Returns: an array of attribute names.

Memory management: The DKString array is to be deleted by the caller.

virtual DKString* listEntityAttrNames(const char* entityName,long& arraySize);

listAttrs
Retrieves the list of attributes defined in the current datastore.

Returns: Collection of attribute as instances of DKAttrDefICM.

Memory management: The attribute objects and the collection itself are to be deleted by the caller.

virtual dkCollection* listAttrs();

listAttrNames
Retrieves a list of names for attributes defined in the current datastore.

Parameters: arraySize - size of attribute name arrays Returns: array of attribute names as DKString variables

Memory management: The DKString array returned is to be deleted by the caller.

virtual DKString* listAttrNames(long& arraySize);

isCheckedOut
Checks whether an item is checked out from the datastore.

Parameters: dataObject - root component DDO for the item to check if the item is checked. out.Returns: TRUE if the specified DDO is checked out; FALSE otherwise.

Memory management: The input DDO object should be deleted by the caller.

virtual DKBoolean isCheckedOut(dkDataObject* dataObject);

checkedOutUserid
Returns the user ID of the user who checked out the item.

Parameters: dataObject - root component DDO of the item to to check. Returns: User ID who has checked out the specified DDO as a DKString variable

Memory management: The input DDO object should be deleted by the caller.

virtual DKString checkedOutUserid(dkDataObject* dataObject);

checkOut
Checks out an item from the datastore. The current user will have exclusive update privileges to the item. All other users are allowed read access only, until the item is checked back in. An item as a whole is checked out, including all versions and all child components of that item.

Parameters: dataObject - root component DDO for the item to be checked out (locked). Throws: DKException if a problem is encountered

Memory management: The input DDO object should be deleted by the caller.

virtual void checkOut(dkDataObject* dataObject);

checkIn
Checks in an item previously checked out from the datastore. Check-in releases exclusive updating privileges to this item.

Parameters: dataObject - root component DDO fo the item to be checked in (unlocked).

Memory management: The input DDO object should be deleted by the caller.

virtual void checkIn(dkDataObject* dataObject);

datastoreDef
Retrieves the datastore definition object. Each call to this method will return the same object during the lifecycle of the datastore.

Returns: datastore definition object as instance of DKDatastoreDefICM.Each call to this method will return the same object. See also: DKDatastoreDefICM

virtual dkDatastoreDef* datastoreDef();

registerMapping
Registers mapping information to this datastore.

Parameters: sourceMap - source name and mapping information. The name part of the NVPair specifies the source of mapping information. A string literal "SCHEMA" indicates that the mapping information is provided in the value part in the form of the schema mapping object. Returns: mapping name for the mapping information as an instance of DKString.

virtual DKString registerMapping(DKNVPair* sourceMap);

unRegisterMapping
Unregisters the mapping information for from this datastore.

Parameters: mappingName - name of the mapping information to be unregistered.

virtual void unRegisterMapping(const char* mappingName);

listMappingNames
Retrieves the list of registered mapping information from this datastore.

Parameters: arraySize - size of returned mapping names array. Returns: array of names of the registered mapping information.

Memory management: The DKString array returned is to be deleted by the caller.

virtual DKString* listMappingNames(long& arraySize);

getMapping
Retrieves the specified schema mapping information registered in this datastore.

Parameters: mappingName - name of the schema mapping information. Returns: schema mapping as an instance of dkSchemaMapping.

virtual dkSchemaMapping* getMapping(const char* mappingName);

getExtension
Retrieves the specified extension object from this datastore. For example, the option 'DK_CM_DATASTORE_EXT' will retrieve the DKDatastoreExtICM* object.
DKDatastoreExtICM* dsExtICM = (DKDatastoreExtICM*) dsICM->getExtension(DK_CM_DATASTORE_EXT);

Parameters: extensionName - name of the extension object to be retrieved. For the DKDatastoreExtICM object, use DK_CM_DATASTORE_EXT. Returns: extension object as an instance of dkExtension.

virtual dkExtension* getExtension(const char* extensionName);

addExtension
Adds a new extension object to this datastore. The extension object is implemented based on the Extension Object pattern described in "Pattern Languages for Program Design, vol. 3, R. Martin, et al (eds), Addison Wesley, 1998".

Parameters: extensionName - name of the new extension object. extensionObj - extension object to be added.

virtual void addExtension(const char* extensionName,dkExtension* extensionObj);

removeExtension
Removes an existing extension object from this datastore.

Parameters: extensionName - name of extension object ot be removed.

virtual void removeExtension(const char* extensionName);

listExtensionNames
Retrieves the list of extension objects' names available in this datastore.

Parameters: arraySize - size of extension object name array. Returns: array of extension object names as DKString variables.

Memory management: The DKString array returned is to be deleted by the caller.

virtual DKString* listExtensionNames(long& arraySize);

createDDO
This method is used to recreate a DDO object given the string representation of a PID for an existing component DDO in the persistent store.

Parameters: pidString - string returned from DKPidICM.pidString() method Returns: created DDO as instance of DKDDO object

Memory management: The returned DDO should be deleted by the caller.

virtual DKDDO* createDDO(DKString pidString);

createDDO
This method is used to recreate a DDO object given the PID object for an existing component DDO in the persistent store.

Parameters: pid - valid PID as instance of DKPidICM. Returns: created DDO as instance of DKDDO object.

Memory management: The returned DDO and the input DKPidICM object should be deleted by the caller.

virtual DKDDO* createDDO(DKPidICM * pid);

createDDO

Creates a new DDO with object type, properties and attributes set according to the definition of the corresponding item type in this datastore. The flag indicates additional properties that need to be set. This is the recommended way to create items. This method will create a new root item of the specified item type. This method will allow the system to automatically setup important information in the DKDDO structure, which allows for easier and greater functionality, such as resources, Content Manager document model, and folders. The DDO returned will have the appropriate properties and attributes setup to fit the corresponding item type definition.

Resource items: The item type definition determines what type of DDO is created. If it is a resource, the correct XDO is returned, depending on the XDO Class specified in the item type definition. The returned DDO may be cast to the correct structure, since it is setup correctly according to the item type definition. For more information, please refer to the "Returns" documentation.

Item property types: An item or DDO must have a generic "type" property associated with it. This generic type of the DDO is document, folder, or item. When creating items, the item property must be specified as the second parameter of the datastore's createDDO function.

The value is stored in the DDO's property named, "DK_CM_PROPERTY_ITEM_TYPE", which should not be confused with the overall item type definition that describes the the structure of this item. "PROPERTY_ITEM_TYPE" refers to the "item property", not the item type definition, something specific to the ICM connector.

Available item property types:

Table 1. Item type property definitions

Property type Constant Definition
Document DK_CM_DOCUMENT Item represents a document or stored data. The information contained in this item might form a document. This item can be considered a common document since it does not rigidly mean an implementation of a specific document model.
Folder DK_CM_FOLDER Item represents an object containing or referencing contents or objects. This item can be considered a common folder since it does not rigidly mean an implementation of a specific document model.
Item (default) DK_CM_ITEM Generic item. This item does not fit system defined or user defined semantic types.

Semantic type: When creating Items, a semantic type can be specified as the second parameter of the Datastore's createDDO function. A semantic type in general is a metaphor for an item. It gives it an enforceable characteristic for basic operations. Where applicable, semantic types are enforced within EIP OOAPI and can be enforced externally as you see fit.

The value is stored in the DDO's property DKConstantICM.DK_ICM_PROPERTY_SEMANTIC_TYPE, which in many cases may contain the same value as the Item Property Type.

Available semantic types:

Table 2. Pre-defined semantic types

Semantic type Constant Definition
Document DK_ICM_SEMANTIC_TYPE _Document Indicates that this item is a document
Folder DK_ICM_SEMANTIC_TYPE _Folder Indicates that this item is a folder
Annotation DK_ICM_SEMANTIC_TYPE _Annotation Indicates that this item or part is an annotation to the base part
Container DK_ICM_SEMANTIC_TYPE _Container Indicates that this item is a container, which can contains other items. The container-containee relationship is represented using links.
History DK_ICM_SEMANTIC_TYPE _History Indicates that this item or part is a history of the base part.
Note DK_ICM_SEMANTIC_TYPE _Note Indicates that this item or part is a note to the base part.
Base DK_ICM_SEMANTIC_TYPE _Base Indicates that this item or part is the base part that may have an annotation, note, or history associated with it.
User defined User defined A user defined semantic type interpreted by the application.
Notes:
  • The constants are defined in DKConstantICM.java.
  • In Content Manager Version 7, semantic type is called affiliated type.

Parameters: objectType - - the name of the Item Type defined in this datastore. The first parameter takes the name of the Item Type that defines the entire Item. This may also be considered the Root Item Type, since the DDO returned is the Root Component DDO. The Item Type definition should be defined at design-time in this datastore through the System Administration Client or API. flags - - indicates additional properties of the DDO. This is the Item Property/Semantic Type. The second parameter determines the Item Property and Semantic Type of the DDO, such as Document, Folder, Item, or User-Defined.

Returns: The DDO returned is a new DKDDO of the Root Component. If the Item Type defines extended functionality such as XDO Resource functionality, the returned DKDDO is the correct derived descendent from DKDDO, such as DKLobICM, DKTextICM, DKImageICM, DKStreamICM, and DKVideoStreamICM and may be cast to those types.

Throws: DKException - If errors are detected such as the following:

The Item Type name given does not exist in this datastore.

The Semantic Type specified is incompatible with the Item Type specified.

Child Component Type name specified instead of a Root Item Type name.

Other Usage Errors

Memory Management: The returned DDO should be deleted by the caller.

virtual DKDDO* createDDO(const char* objectType, long Flags);

createDDO
Creates a new DDO with object type, properties and attributes set based on the supplied PID and attribute list. Parameters: pid - A valid instance of DKPidICM object fedAttributeList - An array of attribute strings numOfFedAttrs - Size of fedAttributeList Returns: A new DDO of give object type with all the properties and attributes set, so that the user only needs to set the attribute values. The attribute values are initialized to NULL. Memory management: The returned DDO, the DKString array and the DKPidICM object should be deleted by the caller.
virtual DKDDO* createDDO(DKPidICM *pid, DKString *fedAttrList, long numOfFedAttrs);

createChildDDO
Creates a child DDO based on the given component name under the specified root component. The child component can be located anywhereh under the root component (it does not have to be a direct child of the root). The created child DDO will have all the properties and attibutes from the child component already set up, so that the user only needs to set up the attribute values. The attribute values are initialized to NULL by default.

Parameters: objectType - name of the root item type componentName - name of the child component based oon which this DDO is to be created Returns: DDO object representing the child component

Memory management: If returned DDO is not a child collection, it should be deleted by the caller.

virtual DKDDO* createChildDDO(DKString objectType, DKString componentName);

adminDomainEnabled
Determines whether the adminstration domain is enabled for this datastore or not.

Returns: Returns TRUE if the adminstration domain is enabled for this datastore; FALSE otherwise

virtual DKBoolean adminDomainEnabled();

informationMiningEnabled
Determines whether information mining is enabled for this datastore or not.

Returns: Returns TRUE if the information mining is enabled for this datastore; FALSE otherwise

virtual DKBoolean informationMiningEnabled();

LDAPEnabled
Determines whether LDAP is enabled for this datastore or not.

Returns: TRUE if LDAP is enabled for this datastore; FALSE otherwise

virtual DKBoolean LDAPEnabled();

platform
Retrieves the platform code for the platfomr on which this specific Content Manager datastore is running.

Returns: platform code. Valid return values are: DK_CM_PLATFORM_WINDOWS DK_CM_PLATFORM_AIX DK_CM_PLATFORM_SUN DK_CM_PLATFORM_390

virtual short platform();

textSearchEnabled
Returns whether text search is enabled for this datastore.

Returns: TRUE if text search is enabled, FALSE otherwise

virtual DKBoolean textSearchEnabled();

workflowEnabled
Determines whether the workflow service is enabled on the datastore or not.

Returns: TRUE if the workflow service is enabled; FALSE otherwise

virtual DKBoolean workflowEnabled();

getLocaleAndCodePage
Currently not implemented. Retrieves the locale and code page being used by this datastore instance. Parameters: locale - Returned value for the locale in use codePage - Returned value for the code page in use Returns: None
virtual void getLocaleAndCodePae(DKString & locale, DKString & codePage);

setLocaleAndCodePage
Currently not implemented. Sets the value of the locale and code page to be sued by this datastore instance. Calling this method is optional. You can pass in a string of zero length for either one of the two values that you do not want to specify. Parameters: locale - New locale value to be used codePage - New code page to be used Returns: TRUE if the call succeeded; FALSE otherwise.
virtual DKBoolean setLocaleAndCodePage(char * locale, char * codePage);

schemaName
Returns the schema name for this Content Manager datastore

Returns: schema name as instance of DKString

DKString schemaName();

listEvents
Lists all events related to the given item id.

Parameters: itemId - an item id . maxResults - the maxium number of DKEventDefICM objects to be returned in the collection. Returns: Returns a collection of DKEventDefICM objects. Throws: DKException if a problem is encountered.

Memory management: The DKEventDefICM objects in the collection and the collection itself are to be deleted by the caller.

dkCollection* listEvents(const char* itemId, short maxResults);

listAdminEvents
Lists all events related to System Administration functions.

Parameters: maxResults - the maxium number of events to retrieve. 0 means no limits. Returns: Returns a collection of DKEventDefICM objects. Throws: DKException if a problem is encountered.

Memory management: The DKEventDefICM objects in the collection and the collection itself are to be deleted by the caller.

dkCollection* listAdminEvents(short maxResults);

retrieveEvent
Retrieves event information for the given event code from the persistent event log. Returns a collection of event objects with the information.

Parameters: eventCode - event code to retrieve event information for Returns: collection of event objects as instances of DKEventDefICM

Returns: Collection of even objects as instnces of DKEventDefICM

Memory management: The DKEventDefICM objects in the collection and the collection itself are to be deleted by the caller.

dkCollection* retrieveEvent(long eventCode);

writeEvent
Writes this event information into the persistent event log

Parameters: aEvent - event to be written

void writeEvent(DKEventDefICM* aEvent);

retrieveFormOverlay
Retrievs the form overlay object and returns it as an XDO object. Note: An example of a form overlay object is an image used as a background print of an invoice. This image is shared across all invoices.

Parameters: name - name of form overlay object Returns: form overlay as an XDO object

dkXDO* retrieveFormOverlay(DKString name);

moveObject
Moves the data-object from the current item type to another in this datastore. After the move, the data object will be relocated into the destination item type but will retain the same itemId. The default is not to check-in the item. You can only move a root component. Caution:
  • In the current implementation, the source data object and all of its versions will be deleted after a successful move.
  • Since child component names are unique under a given schema instance, this method can not move the child components associated with this root, if any. Therefore, when the source item is deleted at the end of a successful move, all its child components will be deleted too.

Parameters: ddo - the data-object to be moved destinationItemType - the destination item type to move this data-object to. Throws: DKException - if a problem is encountered.

virtual moveObject(dkDataObject* ddo, const char* destinationItemType);

moveObject
Moves the data-object from the current item type to another in this datastore. The destination data-object has the format of the destination item type. It contains some additional attributes which do not exist in the source item type that you want to set in the destination item. The destination data-object is necessary when such attributes are not nullable, thus requiring values to be set. The relevant values from source data object will be copied over into the destination data-object. This process would filter out attributes and other data not relevant to the destination item type. You should create the destination DDO using dkDatastore.createDDO() method and populate it as necessary. After the move, the destination item will be created in the destination item type having the same itemId as the source item. You can only move a root component. Caution:
  • In the current implementation, the source data object and all of its versions will be deleted after a successful move.
  • Since child component names are unique under a given schema instance, this method can not move the child components associated with this root, if any. Therefore, when the source item is deleted at the end of a successful move, all its child components will be deleted too.

Parameters: sourceDDO - the data-object to be moved destinationDDO - the template of destination data-objectoptions - valid options are

  • DK_CM_CHECKIN : the default is not to checkin the item.
  • DK_CM_VERSION_NEW : the default is not to create a new version. This option has some limitations.
  • DK_CM_KEEP_IN_AUTOFOLDER : the default is to remove from the current auto folder.

Throws: DKException - if a problem is encountered.

virtual void moveObject(dkDataObject* sourceDDO, dkDataObject* destinationDDO, long options=0);

Data type Conversion:

Class library type Content Manager server data type
DKString VARCHAR
DKString CHAR
short SHORT
long INTEGER
DKDecimal DECIMAL
DKDate DATE
DKTime TIME
DKTimestamp TIMESTAMP
DKByteArray BLOB,DBCLOB
DKString CLOB

Note that each piece of data is transfered into and out of the Content Manager server as a character string representation of its value. The only exception to this rule is the BLOB data type; this data type is transfered in its native binary mode.

(c) Copyright International Business Machines Corporation 1996, 2003. IBM Corp. All rights reserved.