Index

DXBlobDL

Purpose:

The DXBlobDL class defines the public interface for basic Binary Large Object (BLOB) data types in Content Manager. It supports persistency and may exist as a stand-alone object, without the associated DDO object. It provides a set of methods specifically used to communicate with DXDatastoreDL objects such as Add/Retrieve/Update/Delete functions. These functions enable an application to store and retrieve the object's data to and from a datastore, without the existence of an associated DDO object. A stand-alone DXBlobDL object must have its PID set in order to be able to locate the position in the datastore where it belongs. If the object is used in conjunction with a DDO object, the PID is set automatically.

Methods:

init
init(LPDISPATCH datastore);

If this method is used it must be called following the creation of a DXBlobDL object (except for methods returning a DXBlobDL object). Initialize XDO with the datastore from Content Manager. The input parameter LPDISPATCH pointer contains a DXDatastoreDL object.

getPidObject
LPDISPATCH getPidObject();

Gets the PID object. The returned LPDISPATCH pointer contains a DXPidXDODL object.

setPidObject
setPidObject(LPDISPATCH pidXDO);

Sets the PID object. The input parameter LPDISPATCH pointer contains a DXPidXDODL object.

add
add();

Adds the persistent data of this object to the datastore. If no file name is specified, then this object, identified by its PID, will be added to the persistent datastore. A new object with the given PID will be created in the datastore; note that an object having the same PID cannot exist there already, otherwise this method will throw an exception. The object itself is not changed.

If a file name is specified, then the content of the file will be added to the persistent datastore. The filename could be a full path name. With a very large file, this operation is more efficient than calling setContentFromClientFile, followed by add(); this will serve to help avoid out-of-memory problems. To allow the addition of very large files (>15 MB), set the environmental variable MAXPIECE. For example, setting MAXPIECE=4 will break the object content into 4 megabyte pieces, thus avoiding out-of-memory problems.

retrieve
retrieve();

Retrieves the persistent data of this object from the datastore. If no file name is specified, then this object, identified by its PID, will be retrieved from the persistent datastore.

If a file name is specified, then the content of the persistent datastore will be retrieved into the given filename, which can be an absolute pathname. For a very large object, this will serve to help avoid out-of-memory problems.

update
update();

Updates the persistent data of this object to the datastore. If no file name is specified, the persistent data of this object, identified by its PID, will be updated in the persistent datastore. The object itself is not changed.

If a file name is specified, then the object and the persistent datastore will be updated with the content of the given file.

del
del();

Deletes the persistent data of this object, identified by its PID, in the persistent datastore. The object itself is not changed. The next action depends on the value of flushFlag. If flushFlag is TRUE, it will clear the content, otherwise the current content will be preserved. The default is to clear the current content, that is, flushFlag is equal to TRUE.

getContent
BSTR getContent();

Gets the content data.

setContent
setContent(LPCTSTR content);

Sets the content data.

isContentChanged
BOOL isContentChanged();

Returns TRUE if the content has changed.

isSet
BOOL isSet();

Returns TRUE if the part content is set.

setAffiliatedType
setAffiliatedType(long affiliatedType);

Set the affiliated type of the object. The valid values are:

DX_DL_ANNOTATION
indicates that this object is an annotation for a document. It has a page number and XY coordinates of the position in the document.

DX_DL_BASE
indicates this object is a base object, such as a TIFF file, and is not an annotation, note, or event.

DX_DL_EVENT
indicates that this object is an event

DX_DL_MGDS
indicates this object is a machine generated data stream

DX_DL_NOTE
indicates this object is a note

If setAffiliatedType is not set, the default value is DX_DL_BASE.

getAffiliatedType
long getAffiliatedType();

Get the affiliated type of the object.

getMimeType
BSTR getMimeType();

Gets MIME type.

getContentType
BSTR getContentType();

Gets content type.

setContentType
setContentType(LPCTSTR contentType);

Sets content type.

datastore
LPDISPATCH datastore();

Gets the datastore. The returned LPDISPATCH pointer contains a DXDatastoreDL object.

changeStorage
void  changeStorage();

Changes the system-managed storage (SMS) criteria for an object. The collection name, management class name and storage class name will be all converted to upper case by the system. These names must be valid on the object server where you store the object. If you change the collection name and specify a null string as the management and storage class name, the function places the object in the default class for the specified collection.

You cannot move the object from one server to another using this function, therefore you cannot change the StoreSite. If the change causes any physical movement of the object, it might be deferred until the storage management cycle runs on the server.

Example code
    Dim dsDL As New DXDatastoreDL
    Dim xdo As New DXBlobDL
    ...
 
    //------- set DXStorageManageInfoDL -------
    Dim aSMS As New DXStorageManageInfoDL
    aSMS.setCollectionName "CBR.COLLECT3"
    aSMS.setRetention 888
    aSMS.setManagementClass "MGTCLASS"
    aSMS.setStorageClass "FIXED"
    xdo.setExtension aSMS
    axdo.changeStorage
 

setExtension
setExtension(LPDISPATCH extensionObj);

Sets the extension object for this object. Valid extension object names are: The input parameter LPDISPATCH pointer contains a DXAnnotationDL object or a DXSearchEngineInfoDL object or a DXMediaStreamInfoDL object or a DXStorageManageInfoDL object.

DXAnnotationDL
For an annotation object, you need to set this extension object to hold the affiliated informations.

DXSearchEngineInfoDL
For a search indexed object, you need to set this extension object to hold the search indexed informations.

DXMediaStreamInfoDL
For a media object, you need to set this extension object to hold the media user data.

DXStorageManageInfoDL
To associate with different storage collection , you need to set this extension object to hold the system-management storage information.

Example code
    Dim dsDL As New DXDatastoreDL
    Dim xdo As New DXBlobDL
    xdo.init dsDL
    xdo.setPartId 10
    xdo.setItemId "GAWCVGGVFUG428UJ"
 
    //------- set DXStorageManageInfoDL -------
    Dim aSMS As New DXStorageManageInfoDL
    aSMS.setCollectionName "CBR.COLLECT3"
    aSMS.setRetention 888
    aSMS.setManagementClass "MGTCLASS"
    aSMS.setStorageClass "FIXED"
    xdo.setExtension aSMS
    xdo.setContentClass DX_DL_CC_IBMVSS
    axdo.add

getExtension
LPDISPATCH  getExtension(LPCTSTR extensionName);

Gets the extension object for this object. Valid extension names are:

The returned LPDISPATCH pointer contains a DXAnnotationDL object or a DXSearchEngineInfoDL object or a DXMediaStreamInfoDL object or a DXStorageManageInfoDL object.

addExtension
addExtension(LPDISPATCH extensionObj);

Adds the extension object for this object. The valid extension object names are the same as for setting extension object The input parameter LPDISPATCH pointer contains a DXAnnotationDL object or a DXSearchEngineInfoDL object or a DXMediaStreamInfoDL object or a DXStorageManageInfoDL object.

removeExtension
removeExtension(LPDISPATCH extensionObj);

Removes the extension object from this object. The input parameter LPDISPATCH pointer contains a DXAnnotationDL object or a DXSearchEngineInfoDL object or a DXMediaStreamInfoDL object or a DXStorageManageInfoDL object.

isNull
    BOOL isNull(short data_id);

Returns TRUE if this object is null.

setNull
    setNull();

Set this object to null.

addWithFile
addWithFile(LPCTSTR filename);

Adds the persistent data of the file to the datastore.

retrieveToFile
retrieveToFile(LPCTSTR filename);

Retrieves the persistent data from the datastore and store in the file.

updateWithFile
updateWithFile(LPCTSTR filename);

Updates the persistent data of this file to the datastore.

delAndFlush
delAndFlush(BOOL flush);

Deletes the persistent data of this object from the datastore and clear the content of this object if flush is equal to TRUE. If flush is equal to FALSE the content of this object is not cleared.

getContentToClientFile
BSTR getContentToFile(LPCTSTR filename, long fileOption);

Copies the blob data of this object to the given file. FileOption DX_DL_WRITEFILE will create or overwrite an existing file; fileOption DX_DL_WRITEFILEIFEXIST will only create the file, but will also throw an exception if the file already exists; fileOption DX_DL_APPENDFILE appends to an existing file.

setContentFromClientFile
setContentFromFile(LPCTSTR filename);

Replaces the LOB data of this object with the contents of the file "filename." The file must be accessible by the client.

open
open();

The content of the object will be unloaded to a client file with a system generated name and then a default handler will be invoked against the file. If no file name is specified, the content of the object will be unloaded to a client file with a system generated name and then a default handler will be invoked against the file. Note that not all browsers work the same for this operation. For example, the Microsoft Internet Explorer needs a full path name and the correct file extension to function correctly here.

If a file name is specified, the content of the object will be unloaded to the file specified and a default handler invoked against the file.

openWithFile
openWithFile(LPCTSTR filename);

The content of the object will be unloaded to the specified client file and then a default handler will be invoked against the file.

length
long length();

Gets the size of the content data in this object.

setInstanceOpenHandler
setInstanceOpenHandler(LPCTSTR aHandler, BOOL newSynchronousFlag);

Sets the executable handler program name, and whether this handler should be invoked synchronously or asynchronously for this object instance. The handler name must be accessible from the client application.

setClassOpenHandler
setClassOpenHandler(LPCTSTR aHandler, BOOL newSynchronousFlag);

Sets the executable handler program name for the whole class instead of for this instance only.

getOpenHandler
BSTR getOpenHandler();

Returns the currently active handler program name for this object. It could be either class handler or instance handler.

isOpenSynchronous
BOOL isOpenSynchronous();

Returns the current synchronization property for this handler.

getRepType
BSTR getRepType();

Gets the representation type of the LOB data content as a string.

setRepType
setRepType(LPCTSTR repType);

Sets the representation type of the LOB data content. The default value is FRN$NULL. This default value is also used if the input aRType is a null string.

getItemId
BSTR getItemId();

Gets the item ID.

setItemId
setItemId(LPCTSTR itemId);

Sets the item ID.

getPartId
long getPartId();

Returns the part ID from the PID of the object.

setPartId
setPartId(long partId);

Sets the part ID field of the PID of the object.

setRank
setRank(long partId);

Sets the search result ranking value of the object; default is -1.

getRank
long getRank();

Gets the search result ranking value of the object; default is -1.

getCreatedTimestamp
BSTR getCreatedTimestamp();

Gets the timestamp for the creation of the object.

setCreatedTimestamp
setCreatedTimestamp(LPCTSTR createdTimestamp);

Sets the timestamp for the creation of the object.

getUpdatedTimestamp
BSTR getUpdatedTimestamp();

Gets the timestamp for the last update of the object.

setUpdatedTimestamp
setUpdatedTimestamp(LPCTSTR updatedTimestamp);

Sets the timestamp for the creation of the object.

setOption
setOption(long option, VARIANT value);

Sets the value for an option. The valid options and values are:

DX_DL_OPT_DELETE_OPTION
sets the delete option to delete the 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 there are no more parts left in the item

The valid values for media objects are:

DX_DL_DELETE_NO_DROPITEM_MEDIA_AVAIL
do not delete the item even if there are no parts left in the item. 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 there are no more parts left in the item. You can delete media parts (media objects) even when they are in use

DX_DL_DELETE_DROPITEM_MEDIA_AVAIL
delete the item if there are no parts left in the item. You cannot delete media parts (media objects) when they are in use

DX_DL_DELETE_DROPITEM_MEDIA_INUSE
delete the item if there are no more parts left in the item. You can delete media parts (media objects) even when they are in use

DX_DL_OPT_RETRIEVAL_ACTION
sets the retrieval action to retrieve the object content. The valid values are:

DX_DL_RETRIEVAL_GET_IT (default value)
retrieve the object if the object is stored on a fixed storage device (such as DASD) or on any other storage device that is online. If the object is stored offline, an error will return

DX_DL_RETRIEVAL_GET_IT_PREFETCH
similar to DX_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

DX_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

DX_DL_RETRIEVAL_NO_MOUNT_PREFETCH
similar to DX_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

DX_DL_RETRIEVAL_STAGE_IT
retrieves the object, regardless of its location

DX_DL_RETRIEVAL_STAGE_IT_PREFETCH
similar to DX_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:

  • DX_DL_RETRIEVAL_GET_IT
  • DX_DL_RETRIEVAL_STAGE_IT
  • DX_DL_RETRIEVAL_STAGE_IT_PREFETCH

Example code
         Dim dsDL As New DXDatastoreDL
         Dim xdo As New DXBlobDL
         xdo.init dsDL
         xdo.setPartId 1
         xdo.setPidObject "GAWCVGGVFUG428UJ"
         xdo.setOption DX_DL_OPT_RETRIEVAL_ACTION, 
         DX_DL_RETRIEVAL_STAGE_IT_PREFETCH
         xdo.retrieve

getOption
getOption(long option, VARIANT* value);

Get the value of an option. See the setOption method for a list of the valid options and values.

Example code
         Dim dsDL As New DXDatastoreDL
         Dim xdo As New DXBlobDL
         xdo.init dsDL
         xdo.setPartId 10
         xdo.setPidObject "GAWCVGGVFUG428UJ"
         Dim opt As Long
         xdo.getOption DX_DL_OPT_DELETE_OPTION, opt
         cout "getOption of deleteOption=" & opt

isCategoryOf
BOOL isCategoryOf(long category);

Returns the value TRUE if the object is a specified category object. The valid category names are:

DX_DL_INDEXED_OBJECT
checks if this object is a search indexed object. If TRUE is returned, this method also retrieves the search indexed attribute values. You can use the getExtension method to obtain the DXSearchEngineInfoDL instance that contains all the search indexed informations

DX_DL_MEDIA_OBJECT
checks if this object is a media object. If TRUE is returned, this method also retrieves the media user data (media object attributes). You can use the getExtension method to obtain the DXMediaStreamInfoDL instance that contains all the media user data

Example code
         Dim dsDL As New DXDatastoreDL
         Dim xdo As New DXBlobDL
         xdo.init dsDL
         xdo.setPartId 10
         xdo.setPidObject "GAWCVGGVFUG428UJ"
         Dim catflag As Boolean
         catflag = xdo.isCategoryOf(DX_DL_MEDIA_OBJECT)

retrieveObjectState
long retrieveObjectState(long objectCategory);

Retrieves the state of a specified category object. This method performs dynamic retrieval. The valid category names are:

DX_DL_INDEXED_OBJECT
before you invoke this method to retrieve the search indexed state, you should invoke the isCategoryOf(DX_DL_INDEXED_OBJECT) method to make sure this object is a search indexed object. For a non-search indexed object, this method will return the value 0. The valid status values are:

256
to be updated; a call to the invokeSearchEngine(searchEngine, searchIndex) datastore method will change this value

512
to be deleted; a call to the invokeSearchEngine(searchEngine, searchIndex) datastore method will change this value

769
queued to be updated; the object is in the queue and is ready to be indexed by the search machine

770
queued to be deleted; the object is in the queue and is ready to be deleted by the search machine's indexing action

1024
indexed; the search machine has indexed the object

DX_DL_MEDIA_OBJECT
before you invoke this method to retrieve the state of the media object, you should invoke the isCategoryOf(DX_DL_MEDIA_OBJECT) method to make sure this object is a media object. For a non-media object, this method will return the value 0. The valid status values are:

1
pending, load in progress

2
load completed successfully

3
load failed

Example code
         Dim dsDL As New DXDatastoreDL
         Dim xdo As New DXBlobDL
         xdo.init dsDL
         xdo.setPartId 10
         xdo.setPidObject "GAWCVGGVFUG428UJ"
         Dim indexState As Long
         Dim mediaState As Long
         indexState = xdo.retrieveObjectState(DX_DL_INDEXED_OBJECT)
         mediaState = xdo.retrieveObjectState(DX_DL_MEDIA_OBJECT)
           

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