Index

dkResultSetCursor

Purpose:

dkResultSetCursor is a datastore cursor which manages a virtual collection of DDO objects. The collection is a result set of a query submitted to the datastore.

Each elements of the collection do not materialize until a datastore fetch operation is executed .Each call to the fetch operation will create a new DKDDO object which will be returned to the caller. The caller is responsible for managing the memory for these objects.

dkResultSetCursor should be subclassed to provide a specific implementation on the target datastore. For example:

Class summary:

class dkResultSetCursor
     {
      public:
      virtual ~dkResultSetCursor();
      virtual DKBoolean isScrollable() const;
      virtual DKBoolean isUpdatable() const;
      virtual DKBoolean isValid() const;
      virtual DKBoolean isOpen() const;
      virtual DKBoolean isBegin() const;
      virtual DKBoolean isEnd() const;
      virtual DKBoolean isInBetween() const;
      virtual long getPosition() const;
      virtual void setPosition(long position, const DKAny& value);
      virtual void setToNext();
      virtual DKDDO* fetchObject();
      virtual DKDDO* fetchNext();
      virtual DKBoolean fetchNextN(long how_many, dkCollection& collection);
      virtual DKAny fetchObjectByName(const char* dataItemName);
      virtual DKAny fetchNextByName(const char* dataItemName);
      virtual DKBoolean fetchNextNByName(const char* dataItemName, 
                                         long how_many, DKAny* array);
      virtual DKDDO* findObject(long position, const char* predicate);
      virtual void deleteObject();
      virtual void updateObject(DKDDO* ddo);
      virtual DKDDO* newObject();
      virtual void addObject(DKDDO* ddo);
      virtual void open();
      virtual void close();
      virtual void destroy();
      virtual void open(const DKNVPair* parms);
      virtual DKString datastoreName() const;
      virtual DKString datastoreType() const;
      // DKHandle* handle(long type) is deprecated
      virtual DKHandle* handle(long type);
      virtual DKHandle* handle(const char* type);
      virtual unsigned long cardinality();
     protected:
      dkResultSetCursor();
 };

Members:

Constructor
ResultsetCursor is created by DataStore :: execute() method; there is no public constructor.

Member functions

isScrollable
Returns TRUE if this cursor can be scrolled forward and backward. The default is non-scrollable.
virtual DKBoolean isScrollable() const;

isUpdatable
Returns TRUE if this cursor is updatable.
virtual DKBoolean isUpdatable() const;

isValid
Returns TRUE if the cursor is valid.
virtual DKBoolean isValid() const;

isOpen
Returns TRUE if this cursor is at open state.
virtual DKBoolean isOpen() const;

isBegin
Returns TRUE if cursor is positioned at the beginning.

Exceptions

DKUsageError
Error messages:
  • Data access cursor invalid
virtual DKBoolean isBegin() const;

isEnd
Returns TRUE if cursor is positioned at the end.

Exceptions

DKUsageError
Error messages:
  • Data access cursor invalid
virtual DKBoolean isEnd() const;

isInBetween
Returns TRUE if cursor is positioned in between data objects in the result set. It is not at the beginning, at the end, or pointing to a data object in the result set.

Exceptions

DKUsageError
Error messages:
  • Data access cursor invalid
virtual DKBoolean isInBetween() const;

getPosition
Gets the current position of the cursor.

Exceptions

DKUsageError
Error messages:
  • Data access cursor invalid
virtual long getPosition() const;

setPosition
Sets cursor to the given position. The valid positions are:

DK_CM_ABSOLUTE:
the absolute position in the result set

DK_CM_BEGIN:
the beginning of the result set

DK_CM_END:
the end of the result set

DK_CM_FIRST:
the first data object in the result set

DK_CM_LAST:
the last data object in the result set

DK_CM_NEXT:
the next data object from the current position

DK_CM_PREVIOUS:
the previous data object from the current position

DK_CM_RELATIVE:
relative position in the result set from the current position.

In case the position is DK_CM_ABSOLUTE or DK_CM_RELATIVE, the value specifies the absolute or relative position value.

For the non-scrollable cursor, the valid positions are only DK_CM_NEXT and DK_CM_RELATIVE in a positive direction. Currently, the value parameter is an object of type Long.

Exceptions

DKUsageError
Error messages:
  • Data access cursor invalid
  • Data access position invalid
    virtual void setPosition (long position, const DKAny& value);

setToNext
Sets the cursor to point to the position of the next data object in the result set.

Exceptions

DKUsageError
Error messages:
  • Data access cursor invalid
  • Data access position invalid
virtual void setToNext();

fetchObject
Fetches the element of the result set at the current position and returns it as an DDO. If repeated, this operation will return the same value. The caller is responsible for destroying this DDO.

Exceptions

DKUsageError
Error messages:
  • Data access cursor invalid
  • Data access position invalid
virtual DKDDO* fetchObject();

fetchNext
Fetches the next element of the result set and returns it as a DDO. The caller is responsible for destroying this DDO.

Exceptions

DKUsageError
Error messages:
  • Data access cursor invalid
  • Data access position invalid
virtual DKDDO * fetchNext();

fetchNextN
Fetch the next N elements of the result set and insert them into the given collection. Returns TRUE if there is at least one data object returned. The number of elements in the returned collection maybe less than how_many if there is not enough memory. In order to process the whole result set, the user is expected to call fetchNextN() repeatedly until it returns FALSE. If how_many is set to zero a copy of all elements are inserted into the given collection. The caller is responsible for managing the objects inside the collection, depending on the collection type.

Exceptions

DKUsageError
Error messages:
  • Data access cursor invalid
  • Data access position invalid
virtual DKBoolean fetchNextN(long how_many, dkCollection& collection);

fetchObjectByName
Fetches a copy of the element of the result set at the current position by data item name and returns it. The caller is responsible for managing the object inside DKAny.
virtual DKAny fetchObjectByName(const char* dataItemName);

fetchNextByName
Fetches a copy of the next element of the result set by data item name and returns it. The caller is responsible for managing the object inside DKAny, subject to DKAny memory management rules.
virtual DKAny fetchNextByName(const char* dataItemName);

fetchNextNByName
Fetches a copy of the next N elements of the result set by data item name and inserts them into the given array. Returns TRUE if there is at least one data item value returned. The number of data item values in the returned array may be less than how_many if there is not enough memory. In order to process the whole result set, the user is expected to call fetchNextN() repeatedly until it returns FALSE. If how_many is set to zero a copy of all data item values are inserted into the given array. The caller is responsible for managing the object inside the array.
virtual DKBoolean fetchNextNByName(const char* dataItemName, long how_many, DKAny* array);

findObject
Find the data object which satisfies the given predicate, move the cursor to that position, fetch and return the data object. The valid positions for scrollable cursors are DK_CM_FIRST, DK_CM_LAST, DK_CM_NEXT, and DK_CM_PREVIOUS. These positions are described in the setPosition() method. For non-scrollable cursors, only DK_CM_NEXT is valid. The caller is responsible for managing the returned DDO.

The format of predicate string is AttrName RelOp Value where RelOp are relational operators such as = or ==, <=, >=, <, >, <>.

Exceptions

DKUsageError
Error messages:
  • Data access cursor invalid
  • Data access position invalid
  • Data access predicate invalid
    virtual DKDDO* findObject(long position, const char* predicate);

addObject
Adds a new element of the same type (represented by the given DDO) to the datastore.

Exceptions

DKDataObjectAlreadyExists

DKUsageError
Error messages:
  • Data access cursor invalid
  • Data object invalid
  • Data access cursor not updatable
    virtual void addObject(DKDDO* ddo );

deleteObject
Deletes an element at the current position from the datastore.

Exceptions

DKUsageError
Error messages:
  • Data access cursor invalid
  • Data access position invalid
  • Data access cursor not updatable
    virtual void deleteObject();

updateObject
Updates an element at the current position in the datastore, using the given DDO. The type of cursor element must match with the type of DDO.

Exceptions

DKUsageError
Error messages:
  • Data object invalid
  • Data access cursor invalid
  • Data access position invalid
  • Data access cursor not updatable
    virtual void updateObject(DKDDO* ddo);

newObject
Constructs a new element of the same type and returns it as an DDO.

Exceptions

DKUsageError
Error messages:
  • Data access cursor invalid
    virtual DKDDO* newObject();

open
Opens the cursor, and if necessary, executes the query to get the result set. Open reset the position to the beginning.

Exceptions

DKUsageError
Error messages:
  • Data access cursor invalid
       virtual void open();
       virtual void open(const DKNVPair* parms);

close
Closes the cursor, and invalidates the result set.

Exceptions

DKUsageError
Error messages:
  • Data access cursor invalid
    virtual void close();

isOpen
Returns TRUE if this cursor is at open state.
    virtual DKBoolean isOpen();

destroy
Destroys the resultSetCursor. This method allows for cleanup before the resultSetCursor is deleted.
    virtual void destroy();

datastoreName
Gets the name of the datastore associated with the datastore definition to which the resultset cursor belongs.
    virtual DKString datastoreName() const;

datastoreType
Gets the type of the datastore associated with the datastore definition to which the resultset cursor belongs.
    virtual DKString datastoreType() const;

handle
handle has been deprecated.
   virtual DKHandle* handle(long type);
   virtual DKHandle* handle(const char* type);

cardinality
Gets the number of results returned by the query.
virtual unsigned long cardinality();

Exceptions:

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