Index

DXDatastoreDL

Purpose:

This class implements the Content Manager datastore. It provides document, part and folder storage, and 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() methods of DXDatastoreDL take parametric query strings expressed in parametric query language type. The syntax of this query string is described below. DXParametericQueryDL object accepts queries in this syntax; the DXParametricQuery object delegates the low level query processing tasks to DXDatastoreDL.

By itself, DXDatastoreDL only supports parametric queries. Integration with other search engines, such as SearchManager/Text Search Engine or Image Search/QBIC, gives DXDatastoreDL the ability to index texts and images, and collectively process combined queries. Combined query processing is done by the DXCombinedQuery class, with the help of the associated datastore classes (DXDatastoreDL, TS or QBIC, for some examples).

Methods:

connect
connect(LPCTSTR datastoreName, LPCTSTR userName,
        LPCTSTR authentication [, VARIANT connectString]);

This connects to the datastore. The datastore name is the name of the library server, all other parameters are optional. The connect string, if specified, is used to change the password.

To change the password of a user ID, you must set the DXDatastoreDL option DX_DL_OPT_ACCESS to DX_DL_SS_CONFIG, and enter in a connect string with the new password. Below is a sample of a connect string an end-user may supply:

Connect String:

    NPWD=NEWPASSWORD

disconnect
disconnect();

Disconnects from the datastore.

setOption
setOption(long option, VARIANT value);

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

DX_DL_OPT_ACCESS_MODE
Indicates the access mode for DatastoreDL and TS. The valid values are:

DX_DL_READONLY
Indicates that this connection supports read-only access to the datastore (default).

DX_DL_READWRITE
Indicates that this connection supports read and write access to the datastore (for DatastoreDL and TS).

DX_DL_OPT_TYPE_CONVERSION
Indicates the conversion type for DatastoreDL and TS. The valid values are:

DX_DL_TRUE
Indicates that base types from the datastore are to be returned in a retrieved DDO. (default)

DX_DL_FALSE
Indicates that base types from the datastore are converted to strings in a retrieved DDO.

DX_DL_OPT_CONTENT
Valid values are:

DX_DL_CONTENT_NO

DX_DL_CONTENT_ATTRONLY

DX_DL_CONTENT_YES

DX_DL_OPT_WAKEUPSRV
Valid values are:

DX_DL_TRUE
Notifies the search program that there is indexing work to be done for each XDO. (default)

DX_DL_FALSE
Notifies the search program that there is indexing work to be done.

DX_DL_OPT_FORCE_UPDATE
Valid values are:

DX_DL_TRUE
Performs an update if the XDO has not changed.

DX_DL_FALSE
Does not perform an update if the XDO has not changed.

DX_DL_OPT_ACCESS
Indicates the type of access to Content Manager that was requested. Valid values are:

DX_DL_SS_CONFIG
Indicates that the current access is an administrative session.

DX_DL_SS_NORMAL
Indicates that the current access is a non-configuration session and prohibits the same user ID from logging in to the datastore multiple times. (default)

DX_TS_OPT_CCSID

DX_CCSID_00850
(TS only) Indicates the type of coded character set indentifier. (default)

DX_TS_OPT_LANG

DX_LANG_ENU
(TS only) Indicates the type of language indentifier. (default)

DX_CM_OPT_TRANSACTION_STATE
(Content Manager only) Indicates the state of the transaction. Valid values are:

DX_CM_INACTIVE
Indicates that the end user is not in a current transaction. (default)

DX_CM_ACTIVE
Indicates that the end user is currently in a transaction.

DX_DL_OPT_SEARCHINDEX (DL only)
Options for the invokeSearchEngine method. Valid values are:

DX_DL_SRCHINDEX_QUEUE
Indicates that documents are to be placed in the queue.

DX_DL_SRCHINDEX_ONLINE
Indicates that documents are to be placed in the queue and then indexed. (default)

DX_DL_OPT_RETRIEVAL_ACTION
The global default retrieval action used to retrieve the object content (Content Manager only). The valid values are:

DX_DL_RETRIEVAL_GET_IT
Retrieves the object if the object is stored either on a fixed storage device (such as DASD), or on an online storage device. If the storage device is offline, the object server will return an error.

DX_DL_RETRIEVAL_GET_IT_PREFETCH
Instead of placing the object in the client's cache, this option tells the object server to place the object in the staging area on DASD.

DX_DL_RETRIEVAL_NO_MOUNT
Retrieves the object only if the object is located on a fixed storage device (such as DASD). If the object is located on a removable storage device (such as an optical drive), the object server will return an error.

DX_DL_RETRIEVAL_NO_MOUNT_PREFETCH
Instead of placing the object in the client's cache, this option tells the object server to place the object in the staging area on DASD.

DX_DL_RETRIEVAL_STAGE_IT
Retrieves the object, regardless of its location.

DX_DL_RETRIEVAL_STAGE_IT_PREFETCH
Instead of placing the object in the client's cache, this option tells the object server to place the object in the staging area on DASD.

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

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

DX_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:

DX_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.

DX_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.

DX_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.

DX_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.

getOption
getOption(long option, VARIANT* value);

Gets the datastore option. The valid options and values for getting options are the same as for setting options.

datastoreName
BSTR datastoreName();

Gets the datastore name.

datastoreType
BSTR datastoreType();

Gets the datastore type.

userName
BSTR userName();

Gets the user name.

evaluate/evaluateQuery
VARIANT evaluate(LPCTSTR command,
                 short commandLangType
                 [,VARIANT paramList]);
VARIANT evaluateQuery(LPDISPATCH query);

Evaluates a query using a command. The parameter list is in the form of an array of DXNVPairDL objects. The value of the returned VARIANT is a DXResultsDL object. The second form takes a query object. The value of the returned VARIANT is a DXResultsDL object. The input parameter LPDISPATCH pointer contains a DXParametricQueryDL object.

execute/executeQuery
LPDISPATCH execute(LPCTSTR command,
                   short commandLangType
                   [,VARIANT paramList]);
LPDISPATCH executeQuery(LPDISPATCH query);

Executes a query using a command. The parameter list is in the form of an array of DXNVPairDL objects. The returned LPDISPATCH pointer contains a DXResultSetCursorDL object. The second form takes a query object. The input parameter LPDISPATCH pointer contains a DXParametricQueryDL object. The returned LPDISPATCH pointer contains a DXResultSetCursorDL object.

createQuery
LPDISPATCH createQuery(LPCTSTR command,
                       short commandLangType
                       [,VARIANT paramList]);

Creates a query object using a command. The parameter list is in the form of an array of DXNVPairDL objects. The returned LPDISPATCH pointer contains a DXParametricQueryDL object.

addObject
addObject(LPDISPATCH ddobase);

Adds the data object to the datastore. The input parameter LPDISPATCH pointer contains a DXDDODL object.

deleteObject
deleteObject(LPDISPATCH ddobase);

Deletes the data object from the datastore. The input parameter LPDISPATCH pointer contains a DXDDODL object.

retrieveObject
retrieveObject(LPDISPATCH ddobase);

Retrieves the data object from the datastore. The input parameter LPDISPATCH pointer contains a DXDDODL object.

updateObject
updateObject(LPDISPATCH ddobase);

Updates the datastore with this data object. The input parameter LPDISPATCH pointer contains a DXDDODL object.

commit
commit();

Commits the current transaction.

rollback
rollback();

Rolls back the current transaction.

isConnected
BOOL isConnected();

Returns TRUE if it is connected to the datastore.

listDataSources
LPDISPATCH listDataSources();

Gets a list of servers. The returned LPDISPATCH pointer contains a DXSequentialCollectionDL object.

listDataSourceNames
VARIANT listDataSourceNames(long* arraySize);

Gets a list of server names. The output parameter arraySize is the size of the array.

listEntities
LPDISPATCH listEntities();

Gets a list of entities. The returned LPDISPATCH pointer contains a DXSequentialCollectionDL object.

listEntityNames
VARIANT listEntityNames(long* arraySize);

Gets a list of entity names. The output parameter arraySize is the size of the array.

listEntityAttrs
LPDISPATCH listEntityAttrs(LPCTSTR entityName);

Gets a list of entity attributes. The returned LPDISPATCH pointer contains a DXSequentialCollectionDL object.

listEntityAttrNames
VARIANT listEntityAttrNames(LPCTSTR entityName, long* arraySize);

Gets a list of entity attribute names. The output parameter arraySize is the size of the array.

datastoreDef
LPDISPATCH datastoreDef();

Gets the datastore definition. The returned LPDISPATCH pointer contains a DXDatastoreDefDL object.

startTransaction
startTransaction();

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

invokeSearchEngine
invokeSearchEngine(LPCTSTR searchEngine,
                   LPCTSTR searchIndex);

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 identifier (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).

checkOut
checkOut(LPDISPATCH dataObject);

This 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. The input parameter LPDISPATCH pointer contains a DXDDDODL object.

checkIn
checkIn(LPDISPATCH dataObject);

This checks in a document or folder item previously checked out from the datastore. You release all write privileges with this method. The input parameter LPDISPATCH pointer contains a DXDDDODL object.

createWorkFlowService
LPDISPATCH createWorkFlowService();

Creates a workflow service object. The returned LPDISPATCH pointer contains a DXWorkFlowServiceDL object.

Content Manager parametric query string

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

Content Manager parametric query syntax

       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 zero or not specified, all items that match the search criteria will be returned.

conditional_expression
is an expression composed of attribute_name and attribute_value pairs joined with relational operators, and two subsequent pairs are connected with logical operators. Each pair is enclosed in parentheses. Attribute names with a blank character must be enclosed within single quotes only.

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. 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 apostrophe (') in a string, the apostrophe is specified as follows:

If the user wishes to search for a quotation marks (") in a string, the quotation marks 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 DXParts attribute to be set to a collection of parts with no content. Similarly, the DXFolder 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:

CANCELLED_WF_ITEMS
searches for items removed from a workflow

COMPLETED_WF_ITEMS
searches for completed items in a workflow

CURRENT_WF_ITEMS
searches for items in a workflow

ITEMS_NOT_IN_WF
searches for items not in a workflow

ALL (default value)
searches for items regardless of their work-in-process status. Using this value is equivalent to using all the other values simultaneously. If you specify this value, you cannot specify any other values

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

ITEMS_SUSPENDED
searches for suspended items

ITEMS_NOT_SUSPENDED
searches for items that are not suspended

ALL (default value)
searches for items regardless of their work-in-process status. Using this value is equivalent to using all the other values simultaneously. If you specify this value, you cannot specify any other values

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