Index

DKDatastoreDL

Purpose:

This class is a specific version of dkDatastore to implement the Content Manager datastore. It provides documents, parts and folders storage, a retrieval mechanism as well as query and search abilities, along with other document processing features supported by the Content Manager datastore.

The execute() and evaluate() functions of DKDatastoreDL take parametric query strings expressed in parametric query language type. The syntax of this query string is described below. DKParametricQuery object accepts queries in this syntax; the DKParametricQuery object delegates the low level query processing tasks to DKDatastoreDL.

By itself, Content Manager only supports parametric queries. Integration with other search engines, such as SearchManager/Text Search Engine or Image Search/QBIC, gives Content Manager the capability to index texts and images and collectively process combined queries. Combined query processing is performed by the DKCombinedQuery class, with the help of the associated datastore classes (DKDatastoreDL, TS, or QBIC, for example).

In addition to the functions described in dkDatastore, DKDatastoreDL provides some additional functions described below:

Class summary:

class DKEXPORT DKDatastoreDL : public dkDatastore
{
  public:
   DKDatastoreDL();
   DKDatastoreDL(const char* configuration);
 
   virtual ~DKDatastoreDL();
 
   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_PARAMETRIC_QL_TYPE,
                          const DKNVPair* parms = 0);
   virtual DKAny evaluate( dkQuery* query);
   virtual DKAny evaluate(DKCQExpr* qe);
   virtual dkResultSetCursor* execute( const char* command,
                                       const short commandLangType =
                                          DK_CM_PARAMETRIC_QL_TYPE,
                                       const DKNVPair* parms = 0);
   virtual dkResultSetCursor* execute( dkQuery* query);
   virtual dkResultSetCursor* execute( DKCQExpr* qe);
   virtual void executeWithCallback( const char* command,
                                     const short commandLangType,
                                     const DKNVPair* parms,
                                     dkCallback* callbackObj);
   virtual void executeWithCallback( dkQuery* query,
                                     dkCallback* callbackObj);
   virtual void executeWithCallback( DKCQExpr* qe,
                                     dkCallback* callbackObj);
   virtual dkQuery*  createQuery(const char* command,
                                 const short commandLangType =
                                    DK_CM_PARAMETRIC_QL_TYPE,
                                 const DKNVPair* parms=0);
   virtual dkQuery*  createQuery(DKCQExpr* qe);
 
   virtual void addObject(dkDataObject* dataObject);
   virtual void deleteObject(dkDataObject* dataObject);
   virtual void retrieveObject(dkDataObject* dataObject);
   virtual dkCollection* retrieveObjects(const char** itemIds, long& 
                                         arraySize, DKNVPair& errMsg);
   virtual void updateObject(dkDataObject* dataObject);
 
   virtual void startTransaction();
   virtual void commit ();
   virtual void rollback ();
   virtual DKBoolean isConnected();
   virtual DKHandle* connection();
   virtual DKHandle* transactionConnection();
   virtual DKHandle* handle(const char* type);
   virtual void wakeUpService(const char* searchEngine);
   virtual void invokeSearchEngine(const char* searchEngine,
                                   const char* searchIndex);
   virtual dkCollection* listDataSources();
   virtual DKString* listDataSourceNames(long& arrarySize);
   virtual DKAny listServers();
   virtual DKAny listSchema();
   virtual DKAny listSchemaAttributes(const char* schemaEntry);
   virtual dkCollection* listEntities();
   virtual DKString* listEntityNames(long& arraySize);
   virtual dkCollection* listEntityAttrs(const char* entityName);
   virtual DKString* listEntityAttrNames(const char* entityName,
                                         long& arraySize);
                                         
   // <1>
   virtual dkCollection* listAttrs();
   virtual DKString* listAttrNames(long& arraySize);
   // <1>
 
   virtual void addFolderItem(const char* folderId, const char* memberId);
   virtual void removeFolderItem(const char* folderId, const char* memberId); 
   virtual DKBoolean isCheckedOut(dkDataObject* dataObject);
   virtual DKString checkedOutUserid(dkDataObject* dataObject);
   virtual void unlockCheckedOut(dkDataObject* dataObject);
   virtual void checkOut(dkDataObject* dataObject);
   virtual void checkIn(dkDataObject* dataObject);
   virtual dkDatastoreDef* datastoreDef();
   virtual DKWorkFlowServiceDL*  createWorkFlowService();
   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 DKCQExpr* translate(DKCQExpr* cqe);
   virtual dkXDO*    retrieveFormOverlay(const char* objid);
   virtual void      moveObject(dkDataObject* dataObject, const char* entityName);
   virtual DKString* listRefFolders(dkDataObject* dataObject, long& arraySize);
};
 

Members:

Constructors and destructor
DKDatastoreDL();
   DKDatastoreDL(const char* configuration);
   virtual ~DKDatastoreDL();

Member functions

connect
Connects a datastore. Datastore name is the name of the database or library server. connect_string describes some selected options, supported by the specific implementation of the datastore.

Exceptions

  • DKDatastoreError
  • DKDatastoreAccessError

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

disconnect
Disconnects a datastore.
virtual void disconnect(); 

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

DK_DL_OPT_RETRIEVAL_ACTION:
The global default retrieval action to retrieve the object content. Valid values are:

DK_DL_RETRIEVAL_GET_IT (default value):
retrieves the object if it is stored on a fixed storage device (such as DASD), or if it is stored on any online storage device. If the storage device is offline, the object server returns an error.

DK_DL_RETRIEVAL_GET_IT_PREFETCH:
similar to DK_DL_RETRIEVAL_GET_IT, except that the object server places the object in the staging area on DASD instead of sending it to the client for caching.

DK_DL_RETRIEVAL_NO_MOUNT:
retrieves the object if it is stored on a fixed storage device (such as DASD). If the object is located on a removable device, such as an optical disk, the object server returns an error.

DK_DL_RETRIEVAL_NO_MOUNT_PREFETCH:
similar to DK_DL_RETRIEVAL_NO_MOUNT, except that the object server places the object in the staging area on DASD instead of sending it to the client for caching.

DK_DL_RETRIEVAL_STAGE_IT:
retrieves the object, regardless of its location.

DK_DL_RETRIEVAL_STAGE_IT_PREFETCH:
similar to DK_DL_RETRIEVAL_STAGE_IT, except that the object server places the object in the staging area on DASD instead of sending it to the client for caching.

Restriction: for media objects, only the following values are valid:

DK_DL_RETRIEVAL_GET_IT

DK_DL_RETRIEVAL_STAGE_IT

DK_DL_RETRIEVAL_STAGE_IT_PREFETCH

DK_DL_OPT_DELETE_OPTION:
The delete option used to delete an object. The valid values for non-media objects are:

DK_DL_DELETE_ITEM
Delete the item if there are no more parts left in the item.

DK_DL_DELETE_OBJECT_ONLY (default value)
Do not delete the item even if the item contains no parts.

The valid values for media objects are:

DK_DL_DELETE_NO_DROPITEM_MEDIA_AVAIL
Do not delete the item even if the item contains no parts. You cannot delete media parts (media objects) when they are in use.

DK_DL_DELETE_NO_DROPITEM_MEDIA_INUSE
Do not delete the item even if the item contains no parts. You can delete media parts (media objects) when they are in use.

DK_DL_DELETE_DROPITEM_MEDIA_AVAIL
Delete the item if the item contains no parts. You cannot delete media parts (media objects) when they are in use.

DK_DL_DELETE_DROPITEM_MEDIA_INUSE
Delete the item if the item contains no parts. You can delete media parts (media objects) when they are in use.

DK_CM_OPT_CONTENT
The retrieval option used to retrieve an object. The valid values are:

DK_CM_CONTENT_ATTRONLY
Retrieve an item with its attributes only. Do not retrieve the parts and/or the folder information. (Any existing DKPart or DKFolder value in the DKDDO will be set to NULL after retrieval.)

DK_CM_CONTENT_YES
Retrieve an item with its attributes, parts, and/or folder information. (This is the current default behaviour.)

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

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

DK_DL_OPT_RETRIEVAL_ACTION:
The global default retrieval action to retrieve the object content. Valid values are:

DK_DL_RETRIEVAL_GET_IT (default value):
retrieves the object if it is stored on a fixed storage device (such as DASD), or if it is stored on any online storage device. If the storage device is offline, the object server returns an error.

DK_DL_RETRIEVAL_GET_IT_PREFETCH:
similar to DK_DL_RETRIEVAL_GET_IT, except that the object server places the object in the staging area on DASD instead of sending it to the client for caching.

DK_DL_RETRIEVAL_NO_MOUNT:
retrieves the object if it is stored on a fixed storage device (such as DASD). If the object is located on a removable device, such as an optical disk, the object server returns an error.

DK_DL_RETRIEVAL_NO_MOUNT_PREFETCH:
similar to DK_DL_RETRIEVAL_NO_MOUNT, except that the object server places the object in the staging area on DASD instead of sending it to the client for caching.

DK_DL_RETRIEVAL_STAGE_IT:
retrieves the object, regardless of its location.

DK_DL_RETRIEVAL_STAGE_IT_PREFETCH:
similar to DK_DL_RETRIEVAL_STAGE_IT, except that the object server places the object in the staging area on DASD instead of sending it to the client for caching.

Restriction: for media objects, only the following values are valid:

DK_DL_RETRIEVAL_GET_IT

DK_DL_RETRIEVAL_STAGE_IT

DK_DL_RETRIEVAL_STAGE_IT_PREFETCH

DK_DL_OPT_DELETE_OPTION:
The delete option used to delete an object. The valid values for non-media objects are:

DK_DL_DELETE_ITEM
Delete the item if there are no more parts left in the item.

DK_DL_DELETE_OBJECT_ONLY (default value)
Do not delete the item even if the item contains no parts.

The valid values for media objects are:

DK_DL_DELETE_NO_DROPITEM_MEDIA_AVAIL
Do not delete the item even if the item contains no parts. You cannot delete media parts (media objects) when they are in use.

DK_DL_DELETE_NO_DROPITEM_MEDIA_INUSE
Do not delete the item even if the item contains no parts. You can delete media parts (media objects) when they are in use.

DK_DL_DELETE_DROPITEM_MEDIA_AVAIL
Delete the item if the item contains no parts. You cannot delete media parts (media objects) when they are in use.

DK_DL_DELETE_DROPITEM_MEDIA_INUSE
Delete the item if the item contains no parts. You can delete media parts (media objects) when they are in use.

DK_DL_OPT_CONTENT
The retrieval option used to retrieve an object. The valid values are:

DK_DL_CONTENT_ATTRONLY
Retrieve an item with its attributes only. Do not retrieve the parts and/or the folder information. (Any existing DKPart or DKFolder value in the DKDDO will be set to NULL after retrieval.)

DK_DL_CONTENT_YES
Retrieve an item with its attributes, parts, and/or folder information. (This is the current default behaviour.)

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

evaluate
Evaluates the query.
virtual DKAny evaluate(const char* command,
const short commandLangType =
DK_CM_PARAMETRIC_QL_TYPE,
const DKNVPair* parms = 0);
    virtual DKAny evaluate( dkQuery* query);
    virtual DKAny evaluate(DKCQExpr* qe); 

execute
Executes the query.
virtual dkResultSetCursor* execute( const char* command,
const short commandLangType =
DK_CM_PARAMETRIC_QL_TYPE,
const DKNVPair* parms = 0);
    virtual dkResultSetCursor execute( dkQuery* query);
    virtual dkResultSetCursor* execute( DKCQExpr* qe);

executeWithCallback
Executes the query with a callback function.
virtual void executeWithCallback( const char* command,
const short commandLangType,
const DKNVPair* parms,
dkCallback* callbackObj);
virtual void executeWithCallback( dkQuery* query,
dkCallback* callbackObj);
virtual void executeWithCallback( DKCQExpr* qe,
dkCallback* callbackObj);

createQuery
Creates a query object.
virtual dkQuery* createQuery(const char* command,
const short commandLangType =
DK_CM_PARAMETRIC_QL_TYPE,
const DKNVPair* parms=0);
virtual dkQuery*  createQuery(DKCQExpr* qe); 

addObject
Adds a DDO to this datastore.
virtual void addObject(dkDataObject* dataObject);

deleteObject
Deletes the DDO from this datastore.
virtual void deleteObject(dkDataObject* dataObject);

retrieveObject
Retrieves the DDO from this datastore.
virtual void retrieveObject(dkDataObject* dataObject);

retrieveObjects
Retrieves a set of items (given their itemIds).
virtual dkCollection* retrieveObjects(const char** itemIds, long& 
arraySize, DKNVPair& errMsg); 

updateObject
Updates the DDO in this datastore.
virtual void updateObject(dkDataObject* dataObject);

startTransaction
Start a transaction; you can user commit or rollback to end the transaction.

Exceptions

  • DKDatastoreAccessError

virtual void startTransaction(); 

commit
Commits a datastore transaction.
virtual void commit (); 

rollback
Rollbacks a datastore transaction.
virtual void rollback (); 

isConnected
Checks to see if the datastore is connected.
virtual DKBoolean isConnected(); 

connection
Gets the connection handle for a datastore.
virtual DKHandle* connection(); 

transactionConnection
Gets the transaction handle for a datastore.
virtual DKHandle* transactionConnection(); 

handle
Gets a datastore handle.
virtual DKHandle* handle(const char* type);

wakeUpService
wakeUpService has been deprecated and replaced by invokeSearchEngine.
virtual void wakeUpService(const char* searchEngine);

invokeSearchEngine
Notify the search service program that there's indexing work to be done.

The searchEngine is the search engine name (for example, QBIC) and the searchIndex is the search index ID (for example, QBICDB-QBICCAT-QBICSRV, where QBICDB = an image search database name, QBICCAT = an image search catalog name, and QBICSRV = an image search alias for an image search server). For Text Search, the search engine name is SM. The searchIndex can be TM-TMINDEX, where TM is the text search service name and TMINDEX is a text search index. You can specify an empty string ("") for the searchIndex if you want all items for that search engine to be processed.

Exceptions

  • DKDatastoreAccessError
  • DKDatastoreError

virtual void invokeSearchEngine(const char* searchEngine,
const char* searchIndex);

listDataSources
List the available datastore sources that can be used to connect with.
virtual dkCollection* listDataSources(); 

listDataSourceNames
List the available datastore source names that can be used to connect with.
virtual DKString* listDataSourceNames(long& arrarySize); 

listServers
listServers has been deprecated and replaced by listDataSources .
virtual DKAny listServers(); 

listSchema
listSchema has been deprecated and replaced by listEntities.
virtual DKAny listSchema(); 

listSchemaAttributes
listSchemaAttributes has been deprecated and replaced by listEntityAttributes.
virtual DKAny listSchemaAttributes(const char* schemaEntry);

listEntities
Gets a list of entities from persistent datastore.
virtual dkCollection* listEntities(); 

listEntityNames
Gets a list of entity names from persistent datastore.
virtual DKString* listEntityNames(long& arraySize);

listEntityAttrs
Gets a list of attributes for a given entity name.
virtual dkCollection* listEntityAttrs(const char* entityName); 

listEntityAttrNames
Gets a list of attribute names for a given entity name.
virtual DKString* listEntityAttrNames(const char* entityName,
long& arraySize);

listAttrs
Gets a list of attributes defined in the current server.
virtual dkCollection* listAttrs(); 

listAttrNames
Gets a list of attribute names defined in the current server.
virtual DKString* listAttrNames(long& arraySize);

addFolderItem
Adds a folder item.
virtual void addFolderItem(const char* folderId, const char* memberId); 

removeFolderItem
Removes a folder item.
virtual void removeFolderItem(const char* folderId, const char* memberId); 

isCheckedOut
Checks whether a document or folder item is checked out from the datastore.
virtual DKBoolean isCheckedOut(dkDataObject* dataObject); 

checkedOutUserid
Lists the user ID of the user who checked out the document or folder.
virtual DKString checkedOutUserid(dkDataObject* dataObject); 

unlockCheckedOut
Unlocks the checked-out document or folder item.
virtual void unlockCheckedOut(dkDataObject* dataObject); 

checkOut
Checks out a document or folder item from the datastore. You will have exclusive updating privileges to the item, while other users are allowed read access only, until you check it back in.

Exceptions

DKUsageError
Error messages:
  • Connection not established.

DKDatastoreAccessError

virtual void checkOut(dkDataObject* dataObject);

checkIn
Checks in a document or folder item previously checked out from the datastore; you release all write privileges with this function.

Exceptions

DKUsageError
Error messages:
  • Connection not established.

DKDatastoreAccessError
Item is not checked out.

virtual void checkIn(dkDataObject* dataObject);

datstoredef
Gets datastore definition.
virtual dkDatastoreDef* datastoreDef(); 

createWorkFlowService
Creates a workflow service object.
virtual DKWorkFlowServiceDL*  createWorkFlowService();

registerMapping
Registers mapping information to this datastore.
virtual DKString registerMapping(DKNVPair* sourceMap);

unRegisterMapping
Unregisters mapping information for this datastore.
virtual void unRegisterMapping(const char* mappingName);

listMappingNames
Gets the list of the register mappings for this datastore.
virtual DKString* listMappingNames(long& arraySize);

getMapping
Get mapping information for this datastore.
virtual dkSchemaMapping* getMapping(const char* mappingName);

getExtension
Gets the extension object from a given extenstion name.
virtual dkExtension* getExtension(const char* extensionName);

addExtension
Adds a new extension object.
virtual void addExtension(const char* extensionName, dkExtension* extensionObj); 

removeExtension
Removes an existing extension object.
virtual void removeExtension(const char* extensionName);

listExtensionNames
Gets the list of extension objects' names.
virtual DKString* listExtensionNames(long& arraySize);

createDDO
Creates a new DDO with object type, properties and attributes set for a given content server.
virtual DKDDO* createDDO(const char* objectType, long Flags);

translate
Translates a query expression into a native query expression that can be processed by this datastore.
virtual DKCQExpr* translate(DKCQExpr* cqe);

retrieveFormOverlay
virtual dkXDO* retrieveFormOverlay(const char* objid); 

moveObject
virtual void moveObject(dkDataObject* dataObject, 
const char* entityName);

listRefFolders
Gets an array of itemids for a given document or folder.
virtual DKString* listRefFolders(dkDataObject* dataObject, 
long& arraySize); 

Content Manager parametric query string

The syntax of Content Manager parametric query string is as follows:

 
      SEARCH=([INDEX_CLASS=index_class_name,]
              [MAX_RESULTS=maximum_results,]
               COND=(conditional_expression)
               [; ...]
             );
     [OPTION=([CONTENT=yes_no_attronly,]
               [TYPE_QUERY=type_of_query,]
               [TYPE_FILTER=doc_and_or_folder]
               [WIPSTATUS=work_in_process_filter,]
               [SUSPEND=suspension_status_filter]
              )]

Words in uppercase are keywords. Lowercase words are parameters supplied by users, they are described below. Note that DBCS (double-byte character set) attribute names are in SBCS (single-byte character set) single quotes; DBCS (double-byte character set) attribute values can also be specified in SBCS double quotes. All other characters are SBCS.

index_class_name:
the name of the index class to be searched. If it is not specified, all available index classes will be searched.

maximum_results:
the maximum number of results to be returned. If MAX_RESULTS is 0 or not specified, all items that match the search criteria will be returned.

conditional_expression:
an expression composed of attribute_name and attribute_value pairs joined with relational operators, and two subsequent pairs that are connected with logical operators. Each pair is enclosed in paretheses.

Logical operators are NOT (or ^), AND (or &), and OR (or |). Relational operators are EQ (or ==), LEQ (or <=), GEQ (or >=), LT (or <), GT (or >), NEQ (or <>), IN, NOTIN, LIKE, NOTLIKE, BETWEEN, and NOTBETWEEN. These last two operators take a pair of attribute values as a range.

An example of a conditional expression is:

        (DLSEARCH_Date >= "1990") AND (DLSEARCH_Date <= "1993")  AND
        (DLSEARCH_Volume BETWEEN 1 3)

Attribute names with spaces must be enclosed within single quotes; this also includes DBCS characters. For example:

        ('last name' == "Smith") AND 
        ('first name' <> "Joe")          

Attribute values with DBCS characters must be enclosed within double quotes.

The sequence of INDEX_CLASS, MAX_RESULTS, and COND can be repeated for other index classes to formulate a parametric query using multiple criteria. Each sequence should be separated by a semicolon.

If the user wishes to search for a single quote in a string, the single quote character is specified as follows:

If the user wishes to search for a double quote in a string, the double quote character can be specified in two ways.

  1. Title: 'Jonathan"s book'
  2. Title: "Jonathan""s book"

yes_no_attronly
YES or NO or ATTRONLY. If content is YES, the resulting documents and folders will have their contents retrieved. If the value is NO, only the document or folder ids are set. If the value is ATTRONLY, the document or folder ids are set as the attributes and their values. The default is YES if not specified.

For example, content value YES would cause the resulting document or folder DDOs to have their PID, object type, properties and all attributes set. This option also causes the DKParts attribute to be set to a collection of parts with no content. Similarly, the DKFolder attribute is also set to a collection of DDOs with NO content. If the CONTENT value is ATTRONLY, the resulting document or folder DDOs PID, object type, properties, and all attributes are set. If the CONTENT value is NO, the resulting document or folder DDOs PID, object type, and properties are set. The part or DDO content can be retrieved explicitly when needed.

type_of_query
the valid values are:

STATIC (default value)
process the request using static SQL query. If no static query is available the function uses a dynamic query.

DYNAMIC
process request using a dynamic SQL query.

BUILDONLY
generates a static SQL query based on the input search expressions and saves it for future searches.

doc_and_or_folder (FOLDERDOC is the default value)
takes the value of FOLDERDOC, to search for folders and documents, DOC to search for documents only, and FOLDER to search for folders only.

work_in_process_filter
The work-in-process status of the items to be searched. These values can be used by themselves or in conjunction with other values. If you use two or more of the values together, the values must be specified in parenthesis separated by commas (for example, WIPSTATUS = (CANCELLED_WF_ITEMS,CURRENT_WF_ITEMS)). The valid values are:

suspension_status_filter
The suspension status of the items to be searched. The valid values are:

Data type conversion

The following table displays the default data type conversions when you transfer data between a Content Manager server and the class library.

Class library type Content Manager server data type
DKString VSTRING
DKString FSTRING
short SHORT
long LONG
DKString DECIMAL
DKDate DATE
DKTime TIME
DKTimestamp TIMESTAMP
DKBlob BLOB (parts)

Notes

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