Index

DKDatastoreIP

Purpose:

The ImagePlus for OS/390 implementation of datastore. This class is a specific implementation of the abstract class dkDatastore. The ImagePlus datastore provides facilities to query, retrieve, and manage documents stored on an ImagePlus for OS/390 server. The ability to add, update and delete documents and folders is not supported in this release. Also, the ability to check out and check in documents and folders is not supported in this release.

Class summary:

class DKDatastoreIP : public dkDatastore
{
  public:
   DKDatastoreIP();
   DKDatastoreIP(const char* configuration);
 
   virtual ~DKDatastoreIP();
 
   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 void updateObject(dkDataObject* dataObject);
   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 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 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 dkXDO* retrieveFormOverlay(const char* objid);
};

Members:

Constructors and destructor
Constructs and initializes an ImagePlus for OS/390 datastore. A connection will not be established by the constructors. The second constructor takes a configuration string which supplies the specific initialization parameters. Valid parameters include:

CC2MIMEURL=value
The url for the file containing the content-class-to-mime-type mapping.

CC2MIMEFILE=value
The name of the file containing the content-class-to-mime-type mapping. This parameter is ignored if the CC2MIMEURL parameter is specified.

DSNAME=value
The name to be given to this datastore.

   DKDatastoreIP();
   DKDatastoreIP(const char* configuration);
 
   virtual ~DKDatastoreIP();
 

Member functions

connect
Connects to a datastore.

Parameters

datastore_name
The name of this datastore.

user_name
The user name being used to connect to the content server.

authentication
The authentication or password being used to connect.

connect_string
A string which supplies all of the specific connection parameters to establish and maintain a connection to the content server. Valid parameters include:

APPL=value
The Application ID of the FAF Host application to connect. This must be specified.

FAFIP=value
The TCPIP address of the FAF Host to connect. This must be specified.

IODMIP=value
The TCPIP address of the IODM Host to connect. This must be specified.

FAFPORT=value
The TCPIP port number of the FAF Host. This must be specified.

IODMPORT=value
The TCPIP port number of the IODM Host. This must be specified.

FAFPROT=value
The communication protocol of the FAF Host. Valid values are (4000 for TCPIP on CICS, and 4500 for TCPIP on IMS). This must be specified.

IODMPROT=value
The communication protocol of the IODM Host. Valid values are (4000 for TCPIP on CICS, and 4500 for TCPIP on IMS). This must be specified.

TERMID=value
This is the IODM Terminal ID for this workstation. If not specified, the user ID will be used as the Terminal ID.

FAFSITE=value
The four character symbolic ID of the folder application that owns and catalogs the documents associated with this datastore. This parameter is optional.

NPWD=value
This is the new password to be used to change the user's password at connect time. This value must have a length of eight characters or less.

IODMCNTL=value
This is the IODM document storage location control. If the document is not located at the specified location, the document will not be retrieved. The default value is DASD. The valid values are:

DASD
Retrieve documents from DASD only.

OPTICAL
Retrieve documents from DASD or Optical only.

SHELF
Retrieve documents from DASD, Optical or Shelf.

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

disconnect
Disconnects from the content server.
   virtual void disconnect();
 

getOption
Gets the value associated with the specified option. Valid options for the ImagePlus for OS/390 datastore are:

DK_CM_OPT_ACCESS _MODE
This option controls the updateability of the datastore. The default is DK_CM_READONLY.

DK_CM_OPT_CONTENT
This option controls the amount of information returned in the DKDDO objects. The default is DK_CM_CONTENT_YES

DK_IP_OPT_INCLUDE_PENDING_DOCS
This option controls whether or not documents which are in pending state (the document contains no content) are included when searching for documents or listing the contents of folders. The default is DK_IP_PENDING_NO.

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

setOption
Sets the given option with a specific value. Options for ImagePlus for OS/390 datastore are:

DK_CM_OPT_ACCESS _MODE
This option controls the updateability of the datastore. The default is DK_CM_READONLY.

DK_CM_OPT_CONTENT
This option controls the amount of information returned in the DKDDO objects. The default is DK_CM_CONTENT_YES

DK_IP_OPT_INCLUDE_PENDING_DOCS
This option controls whether or not documents which are in pending state (the document contains no content) are included when searching for documents or listing the contents of folders. The default is DK_IP_PENDING_NO.

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

evaluate
The first form evaluates the query from a query string. The query string must follow the ImagePlus for OS/390 parametric query string syntax. The second form evaluates the query from a query object. The third form evaluates the query from a common query expression object. This method returns the result as a DKAny containing a reference to a DKResults collection.
   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
The first form executes the query from a query string. The query string must follow the ImagePlus for OS/390 parametric query string syntax. The second form executes the query from a query object. The third form executes the query from a query expression object. This method returns a reference to the result set cursor. If the reference to the result set cursor is not deleted by the caller of this method, the result set cursor will be deleted when this datastore is deleted or disconnected.
   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 using the 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
The first form creates a query object using the specified parameters. The command string must follow the ImagePlus for OS/390 parametric query string syntax. The second form creates a query object using the specified common query expression. Both forms of the query can be used as input to the evaluate or execute methods. The query object must be deleted by the caller of this method.
   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 data object (DDO) from the persistent datastore into memory.
   virtual void retrieveObject(dkDataObject* dataObject);
 

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

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

rollback
Rolls back the current transaction.
   virtual void rollback ();

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

connection
Gets a reference to the connection handle for the datastore. The DKHandle reference should not be deleted by the caller of this method.
   virtual DKHandle* connection();
 

handle
Gets a reference to the connection handle for type=DK_IP_DSTYPE. The DKHandle reference should not be deleted by the caller of this method. For types other than DK_IP_DSTYPE, a value of 0 is returned.
   virtual DKHandle* handle(const char* type);
 

listDataSources
A collection of data sources is constructed and returned. The collection itself must be deleted by the caller of this method. For ImagePlus for OS/390, this list is empty.
   virtual dkCollection* listDataSources();
 

listDataSourceNames
A list of data source names is constructed and returned. The collection itself must be deleted by the caller of this method. Upon return, arraySize contains the number of elements in the list, which is always 0 in the case of ImagePlus for OS/390.
   virtual DKString* listDataSourceNames(long& arrarySize);

listEntities
A collection of entity definitions is constructed and returned. The entity definitions in the collection and the collection itself must be deleted by the caller of this method.
   virtual dkCollection* listEntities();
 

listEntityNames
A list of entity names is constructed and returned. The list itself must be deleted by the caller of this method. Upon return, arraySize contains the number of array elements in the list.
   virtual DKString* listEntityNames(long& arraySize);
 

listEntityAttrs
A collection of attribute definitions is constructed and returned. The attribute definitions and the collection itself must be deleted by the caller of this method.
   virtual dkCollection* listEntityAttrs(const char* entityName);
 

listEntityAttrNames
A list of attribute names is constructed and returned. The list itself must be deleted by the caller of this method. Upon return, arraySize contains the number of array elements in the list.
   virtual DKString* listEntityAttrNames(const char* entityName,
                                         long& arraySize);
 

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 (and locks) a document or folder item from the datastore.
   virtual void checkOut(dkDataObject* dataObject);

checkIn
Checks in ( and unlocks) a document or folder item to the datastore.
   virtual void checkIn(dkDataObject* dataObject);

datastoreDef
Returns the datastore definition for this datastore. The returned datastore definition should not be deleted by the caller of this method.
   virtual dkDatastoreDef* datastoreDef();
 

registerMapping
Registers the 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:

SCHEMA
A reference to a dkSchemaMapping object defining the mapping.

   virtual DKString registerMapping(DKNVPair* sourceMap);
 

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

listMappingNames
A list of mapping names is constructed and returned. The list itself must be deleted by the caller of this method. Upon return, arraySize contains the number of array elements in the list.
   virtual DKString* listMappingNames(long& arraySize);
 

getMapping
Gets the schema mapping (a reference to the specified schema mapping). It should not be deleted by the caller of this method.
   virtual dkSchemaMapping* getMapping(const char* mappingName);
 

getExtension
Gets the extension object of the given extension name. The returned extension is a reference to the specified extension and should not be deleted by the caller of this method.
   virtual dkExtension* getExtension(const char* extensionName);
 

addExtension
Adds a new extension object, which provides a set of new methods.
   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 object names. The list itself must be deleted by the caller of this method. Upon return, arraySize contains the number of array elements in the list.
   virtual DKString* listExtensionNames(long& arraySize);
 

createDDO
Creates a new DDO with object type, properties and attributes set for a given content server. The returned DDO must be deleted by the caller of this method.
   virtual DKDDO* createDDO(const char* objectType, long Flags);
 

retrieveFormOverlay
Retrieves the form overlay.
   virtual dkXDO* retrieveFormOverlay(const char* objid);

ImagePlus for OS/390 qyery syntax

The following example shows the query syntax for ImagePlus for OS/390.

SEARCH=(COND=(ip_search_expression),ENTITY={entity_name | mapped_entity_name}
       [,MAX_RESULTS=maximum_results]);
       [OPTION=([CONTENT={YES | ATTRONLY | NO};][PENDING={YES | NO};])]

The valid parameters are:

ip_search_expression
	ip_search_criteria
	    [[binary_operator ip_search_criteria] ... ]

Note: only the binary operator AND is supported

ip_search_criteria
{attr_name | mapped_attr_name} operator literal

attr_name
the name of the entity attribute on which to base the search

mapped_attr_name
the mapped attribute name associated with the attribute on which to base the search

operator
for attributes of type DATE, the following operators are supported:

==
equality

>
greater than

<
less than

>=
greater than or equal to

<=
less than or equal to

Note: for all other attributes, only equality (==) is supported

literal

for numeric attributes, no quotes should be used, for example:

FolderType == 9

for date, time and timestamp attributes, no quotes are necessary, although double and single quotes are tolerated, for example:

ReceiveDate == 1999-03-08
ReceiveDate == '1999-03-08'

for string attributes, no quotes are necessary, although double and single quotes are tolerated. If the string contains a single quote, the string must be specified using 2 single quotes, for example for a value of Folder'1:

FolderId == 'Folder''1'

entity_name
the name of the entity to be searched

mapped_entity_name
the mapped entity name associated with the entity to be searched

maximum_results
he desired maximum number of results to be returned

The option keywords are:

CONTENT
Controls the amount of information returned in the results

YES
the default value. The Pids, attributes and their values for a document or folder are set. If there are parts in a document, the XDO Pids are set. If there are documents in a folder, the document Pids are set.

NO
Only the document or folder Pids are set.

ATTRONLY
Only the Pids, attributes and their values for a document or folder are set.

PENDING
Controls whether or not pending documents (documents which do not have any parts) are included in the results. This option only applies when ENTITY is set to DOCUMENT or an entity mapped to DOCUMENT.

YES
Includes pending documents in the results

NO
The default value. Does not include pending documents in the results

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