Index

DKDatastoreDES

Purpose:

DKDatastoreDES is the specific version of dkDatastore that is used to implement the Extended Search (DES) datastore. It provides Documents, Parts, and Folders' storage-and-retrieval mechanisms. It also searches and provides other document processing capabilities supported by DES.

Class summary:

class DKDatastoreDES : public dkDatastore
{
public:
    DKDatastoreDES();
    DKDatastoreDES(const char* configuration);	
    virtual ~DKDatastoreDES();
 
    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_DES_GQL_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_DES_GQL_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_DES_GQL_QL_TYPE,
                                  const DKNVPair* parms=0);
    virtual dkQuery*  createQuery(DKCQExpr* qe);
    virtual void addObject(dkDataObject* dataobj);
    virtual void deleteObject(dkDataObject* dataobj);
    virtual void retrieveObject(dkDataObject* dataobj);
    virtual void updateObject(dkDataObject* dataobj); 
    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 DKCQExpr* translate(DKCQExpr* cqe);
    virtual DKAny listServers();
    virtual DKAny listSchema();
    virtual DKAny listSchemaAttributes(const char* schemaEntry);
    void setSearchOptions(int iSourceMaxHits,
                          int iTotalMaxHits,
                          int iPageSize,
                          int iGetPage,
                          int iTimeOut,
                          bool bScheduled,
                          bool bResultsWhenAvail,
                          bool bSortAscending,
                          bool bFindAllWords,
                          const char*  sMailTo,
                          const char*  sSearchId,
                          const char*  sSortField,
                          void *vpConstraints = NULL)
    void printSearchOptions(void)
    void setLocaleForDES(char *locale)
};

Members:

Constructors and destructor
    DKDatastoreDES();
    virtual ~DKDatastoreDES();
 

Member functions

connect

Parameters

datastore_name
The DES server TCP/IP address.

userName
The user name used for connection.

authentication
The password used for connection.

connect_string
a string which supplies connection parameters to establish and maintain a connection to the DES server. Valid parameters are:

PORT=value
The port number for the DES server address. This MUST be specified.

DESAPPID=value
The Application ID for DES to control access to specific databases. This MUST be specified.

DESAPPPW=value
The Application ID password. This MUST be specified.
    virtual void connect(const char* datastore_name,
                         const char* user_name = "",
                         const char* authentication = "",
                         const char* connect_string = "");
 

disconnect
Disconnects from a datastore.
    virtual void disconnect();
 

getOption
Gets a datastore option.

Parameters
option -- The option ID.

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

setOption
Sets a datastore option.

Parameters
option -- The option ID
value -- The option value.

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

evaluate
Gets a list of attributes.

Parameters
command -- A query string.
commandLangType -- A query type.
parms -- Additional query option(s) in a name/value pair.

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

evaluate
Evaluates the query.

Parameters
query -- A query object.

    virtual DKAny evaluate(dkQuery* query);
 

evaluate
Evaluates the query.

Parameters
qe -- A common query expression object.

    virtual DKAny evaluate(DKCQExpr* qe);
 

execute
Adds the given attribute-definition object to this entity in the persistent store.

Parameters
command -- A query string.
commandLangType -- A query type.
parms -- Additional query option(s) in name/value pair.

    virtual dkResultSetCursor* execute(const char* command,
                                       const short commandLangType = 
                                       DK_DES_GQL_QL_TYPE,
                                       const DKNVPair* parms = 0);
 

execute
Executes the query.

Parameters
query -- A query object.

    virtual dkResultSetCursor* execute(dkQuery* query);
 

execute
Executes the query in the DKCQExpr and returns a resultSetCursor, which represents a datastore cursor.

Parameters
qe -- A common query expression object.

    virtual dkResultSetCursor* execute(DKCQExpr* qe);
 

executeWithCallback
Executes the query-with-callback function.

Parameters
command -- A query string.
commandLangType -- A query type.
parms -- Additional query option(s) in a name/value pair.
callbackObj -- A dkCallback object.

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

executeWithCallback
Executes the query-with-callback function.

Parameters
query -- A query object.
callbackObj -- A dkCallback object.

    virtual void executeWithCallback(dkQuery* query,
                                     dkCallback* callbackObj);
 

executeWithCallback
Executes the query-with-callback function.

Parameters
qe -- A common query expression object.
callbackObj --A dkCallback object.

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

createQuery
Creates a query object

Parameters
command -- A query string.
commandLangType -- A query type.
parms -- Additional query option(s) in a name/value pair.

    virtual dkQuery*  createQuery(const char* command,
                                  const short commandLangType = 
                                  DK_DES_GQL_QL_TYPE,
                                  const DKNVPair* parms=0);
 

createQuery
Creates a query object.

Parameters
qe -- A common query expression object.

    virtual dkQuery*  createQuery(DKCQExpr* qe);
 

addObject
Adds a data object to the persistent datastore.
    virtual void addObject(dkDataObject* dataobj);
 

deleteObject
Deletes the data object from the persistent datastore. The in-memory copy of the data object is not affected.
    virtual void deleteObject(dkDataObject* dataobj);
 

retrieveObject
Retrieves the data object from this datastore.

Parameters
dataobj -- The data-object to be retrieved from this datastore.

    virtual void retrieveObject(dkDataObject* dataobj);
 

updateObject
Updates the persistent datastore with the new value of this data object.
    virtual void updateObject(dkDataObject* dataobj); 
 

commit
Commits the current transaction.
    virtual void commit ();
 

rollback
Executes the query-with-callback function.
    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();
 

handle
Gets either the DES session handle or the broker handle (based on the type).

Parameters
type -- The type of handle (either session or broker).

    virtual DKHandle* handle(const char* type);
 

listDataSources
Lists the available datastore sources that can be connected to.
    virtual dkCollection* listDataSources();
 

listDataSourceNames
Gets a list of datasource names.
    virtual DKString* listDataSourceNames(long& arrarySize);
 

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

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

listEntityAttrs
Gets a list of attributes for a given entity name.

Parameters
entityName -- The name of the entity to retrieve attributes for.

    virtual dkCollection* listEntityAttrs(const char* entityName);
 

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

Parameters
entityName -- Name of the entity to retrieve attribute names for.

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

datastoreDef
Get the datastore definition.
    virtual dkDatastoreDef* datastoreDef();
 

registerMapping
Registers a mapping definition to this datastore. Mapping is done by entities.

Parameters

sourceMap
the source name and mapping, that is: a DKNVPair class with the following possible values (only the "SCHEMA" option is supported):

("SCHEMA", )
A reference to a dkSchemaMapping object defining the mapping.
    virtual DKString registerMapping(DKNVPair* sourceMap);
 

unRegisterMapping
Unregisters mapping information from this datastore.

Parameters
mappingName -- The name of the mapping information.

    virtual void unRegisterMapping(const char* mappingName);
 

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

getMapping
Gets mapping information from this datastore.

Parameters
mappingName -- The name of the mapping information.

    virtual dkSchemaMapping* getMapping(const char* mappingName);
 

getExtension
Gets the extension object from a given extension name.

Parameters
extensionName -- The name of the extension object.

    virtual dkExtension* getExtension(const char* extensionName);
 

addExtension
Adds a new extension object.

Parameters
extensionName -- The name of a new extension object.
extensionObj -- The extension object to be set.

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

removeExtension
Remove an existing extension object.

Parameters
extensionName -- Name of the extension object to be removed.

    virtual void removeExtension(const char* extensionName);
 

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

createDDO
Creates a dynamic data object (DDO).
    virtual DKDDO* createDDO(const char* objectType, long Flags);
 

translate
Translates a query expression into a native query expression that is able to be processed by this datastore.

Parameters
cqe -- The input compound query expression.

    virtual DKCQExpr* translate(DKCQExpr* cqe);
 

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 listEntityAttrs.
    virtual DKAny listSchemaAttributes(const char* schemaEntry);
 

setSearchOptions
Instantiates the search options (private) variable in the DKDatastoreDES class. The SearchOptions variable can be used to set the appropriate variables for the esBroker (DES). The MAX_RESULTS and TIME_LIMIT variables passed in the search query can also be overwritten by instantiating this variable. This function should be invoked before calling the execute() member function in the DKDatastoreDES class. If this function is not invoked, a default set of values will be set for the searchOptions variable preserving all the values passed in the actual search query.

Parameters

int iSourceMaxHits
The maximum number of hits that can be returned to a Broker by an individual source. Default: 50

int iTotalMaxHits
The maximum number of hits that comprise a complete search-results set for the client. Hits are accumulated by the Broker as they are received by the individual agents (data sources) participating in the search. Note how SourceMaxHits can effect how many data sources can contribute to a given TotalMaxHits results set. Default: 50

int iPageSize
The number of hits to be returned to the client for display. Default: 10

int iGetPage
The page number to be retrieved (starts at one). PageSize should be less than or equal to TotalMaxHits. Requesting a page that does not exist (is outside the bounds of the results set) causes a 337 return code. Default: 1

int iTimeOut
The maximum amount of time in seconds that the client is willing to wait for a search to complete. Default: 30 seconds

bool bScheduled
Boolean Flag to indicate that the query is to run at a later data/time as dictated by the scheduled query agent. Note that this option requires the instantiation of a Notes Client Search Application database into which the query/results will be stored and the scheduled query agent is associated with. Default: not to schedule the query.

bool bResultsWhenAvail
Boolean flag to indicate that the results are to be returned as soon as enough results are received by the Broker to fill up the requested GetPage (or when TimeOut is exceeded). Note that results are only sorted by relevance rank within a given data source when returning results when available. If this flag is set to false then the results are returned sorted requiring the Broker to wait for all participating data sources to return their results before the sort can begin (or when iTimeOut is exceeded). Default: True (return results when available)

bool bSortAscending
Boolean flag to indicate that the sort is to be in ascending order.Default: descending order

bool bFindAllWords
Boolean Flag to indicate that all words in the query string are required to be present inorder to satisfy the query. This is normally used when the query string is a simple list of keywords and is not in the formal Generalized Query Language (GQL) format. Default:Not to find all words (OR condition)

const char*sMailTo
The results (hitlist) of the scheduled query are to be mailed to this address. The query must be scheduled.Default: null;

const char* sSearchId
The searchId of a previous search request/result. A unique searchId is returned with each search request. This Id is used in conjunction with iGetPage to get subsequent pages in the total results set. Note that the SearchId can also be passed as a parameter for the constructor. Default: NULL

const char* sSortField
Name of the field on which the sort is to be performed. Field must be present in the hitlist result set.Default: DocRank

void* vpConstraints
vpConstraints is an esArray<Constraint>* type casted as void*. The user should define an esArrayes<Constraint>* and typecast it to void* when passing it as an argument and the user is also responsible to free the memory allocated for that pointer. A Constraint Object further filters the results of the query. They are expressed in Name/Operator/Value triplets. Any number of constraints can be specified and will subsequently be passed back to the receiving ES Link Managers for processing. For this release, ES Link Managers can support only the DesMaxHits constraint. A greater set of constraints (e.g. DocDate, DocAuthor, etc..) will be supported in the next release. Defining your n constraints is useful if you have written you own ES Link (using the toolkit) and need to pass additional information to you custom link. Default: No constraints.
    void setSearchOptions(int iSourceMaxHits,
                          int iTotalMaxHits,
                          int iPageSize,
                          int iGetPage,
                          int iTimeOut,
                          bool bScheduled,
                          bool bResultsWhenAvail,
                          bool bSortAscending,
                          bool bFindAllWords,
                          const char*  sMailTo,
                          const char*  sSearchId,
                          const char*  sSortField,
                          void *vpConstraints = NULL)

printSearchOptions
Prints the values stored in the searhOptions variable. (This can be used for debugging purposes.)
    void printSearchOptions(void)

setLocaleForDES
Sets the locale variable for the esBroker. If not specified, the locale from NT workstation would be extracted as default. This function has to be called after instantiating a DKDatastoreDES object.

Parameters
char* locale -- the locale string for the esBroker.

The following are the syntax for the locale for English(USA):

  • en
  • enUS
  • enUS1252
  • enUS850
  • enUS437
  • enuUSA
  • enuUSA1252

Please follow these rules for other languages supported by DES3.0.

    void setLocaleForDES(char *locale)

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