DumontEXE 0.0.1
Public Types | Public Slots | Public Member Functions | Private Member Functions | Private Attributes
cmcCursor Class Reference

Cursor Object Wrapper. More...

#include <cmcCursor.h>

Inheritance diagram for cmcCursor:

List of all members.

Public Types

enum  CURSOR_MODES {
  CATEGORY = 0, VIEW = 1, PILOTAB = 2, PILOTMEMO = 3,
  PILOTTODO = 5, PILOTAPPT = 6
}
 Type of Commence data to access with this cursor
. More...

Public Slots

QString category ()
 (read-only) Name of the underlying Commence category

cmcCategoryDefcategoryDef ()
 extended: Category Definition object for this cursor

QString categoryName ()
 extended: (read-only) Name of the underlying Commence category

void clearFilter (long filterNumber=-1)
 Clear a Filter
.
long colCount ()
 extended alias: Rowset Column Count

long columnCount ()
 (read-only) Number of columns in this cursor (-1 on error)

virtual bool filter (const QString &filterString, long flags=0)
 Set Filter Alias
.
virtual QString filters (const QString &delimiter="\r\n")
 extended: Return Defined Filters

long flags ()
 Cursor Flags
.
virtual cmcRowSetgetAddRowSet (long rowCount=1, long flags=0)
 Create a rowset of new items to add to the database
.
virtual long getColumnIndex (const QString name, long flags=0)
 extended: Return Defined Column Index

virtual QString getColumnLabel (long index, long flags=0)
 extended: Return Defined Column Name

virtual cmcRowSetgetDeleteRowSet (long rowCount=-1, long flags=0)
 Create a rowset of existing items for deletion
.
virtual cmcRowSetgetDeleteRowSetByID (const QString &rowID, long flags=0)
 Create a rowset for deleting a particular row
.
virtual cmcRowSetgetDeleteRowSetByTHID (const QString &rowID, long flags=0)
 Rowset By ID alias
.
virtual cmcRowSetgetEditRowSet (long rowCount=-1, long flags=0)
 Create a rowset of existing items for editing
.
virtual cmcRowSetgetEditRowSetByID (const QString &rowID, long flags=0)
 Create a rowset for editing a particular row
.
virtual cmcRowSetgetEditRowSetByTHID (const QString &rowID, long flags=0)
 Rowset By ID alias
.
virtual cmcRowSetgetQueryRowSet (long rowCount=-1, long flags=0)
 Create a rowset object with the results of a query
.
virtual cmcRowSetgetQueryRowSetByID (const QString &rowID, long flags=0)
 Create a rowset object with a particular row loaded
.
virtual cmcRowSetgetQueryRowSetByTHID (const QString &rowID, long flags=0)
 Rowset By ID alias
.
virtual cmcCursorgetRelatedCursor (const QString &connectionName, const QString parentKey="")
 extended: Get a cursor from a related column

virtual cmcRowSetgetRowSet (long type, long rowCount=-1, const QString &name="", long flags=0)
 extended: Get Row Set

virtual cmcRowSetgetRowSet (long type, const QString &id, const QString &name="", long flags=0)
 extended: Get Row Set by ID

virtual long maxFieldSize ()
 extended: Return the Max Field Size

virtual long maxRows ()
 extended: Return the Max Rows

long mode ()
 Cursor Mode
.
long rowCount ()
 (read-only) Number of rows in this cursor (-1 on error)

virtual long seekRow (long origin, long rows)
 Seek to a particular row in the cursor
.
virtual long seekRowApprox (long numerator, long denominator)
 Seek to an approximate position in the cursor
.
virtual bool setActiveDate (const QDate &date, long flags=0)
 passthrough: Set active date used for view cursors using a view linking filter

virtual bool setActiveDateRange (const QDate &startDate, const QDate &endDate, long flags=0)
 passthrough: Set active date range used for view cursors using a view linking filter

virtual bool setActiveItem (const QString &categoryName, const QString &rowID, long flags=0)
 Set active item used for view cursors using a view linking filter
.
virtual bool setColumn (long column, const QString &connectionName, const QString &targetCategoryName, const QString &fieldName, long flags=0)
 extended alias: Set Related Column

virtual long setColumn (const QString &name, long flags=0)
 extended preferred: Set Field Column

virtual bool setColumn (long column, const QString &name, long flags=0)
 Set Column
.
virtual long setColumn (const QString &connecionName, const QString &targetCategoryName, const QString &fieldName="", long flags=0)
 extended preferred: Set Related Column

virtual bool setFilter (const QString &filter, long flags=0)
 Defines a filter clause for the cursor
.
virtual bool setLogic (const QString &logic, long flags=0)
 Defines the filter logic for the cursor
.
virtual bool setRelatedColumn (long column, const QString &connectionName, const QString &targetCategoryName, const QString &fieldName, long flags=0)
 Set Related Column
.
virtual long setRelatedColumn (const QString &connectionName, const QString &targetCategoryName="", const QString &fieldName="", long flags=0)
 extended: Set Related Column

virtual bool setSort (const QString &sort, long flags=0)
 Defines the sort criteria for the cursor
.
bool shared ()
 (read-only) TRUE if category is shared in a workgroup

bool useThids ()
 Indicates if this cursor is using THIDS
.

Public Member Functions

 cmcCursor (const cmcCursor &copy)
 Copy Constructor
.
 cmcCursor (const long mode, const QString &name, const long flags, IDispatch *disp, cmcApplication *app, QObject *parent=NULL)
 Default Constructor
.

Private Member Functions

virtual IDispatch * getRowSet (const QString &rowSetType, long rowCount, long flags=0)
 (internal) Return a RowSet dispatch pointer

virtual IDispatch * getRowSet (const QString &rowSetType, const QString &id, long flags=0)
 (internal) Return a RowSet by ID dispatch pointer

Private Attributes

QStringList m_columnLabelCache
 Column Label Cache
.

Detailed Description

Cursor Object Wrapper.

This object wraps the regular Commence Cursor object, and adds a few functional enhancements without affecting existing programs that are written for the original (unwrapped) Cursor object.

Todo:
It is quite possible to have the cursor object "reissue" itself if a column is requested that was not initially defined in the cursor column set. This would be a convenience function. It would allow the developer to spend less attention to what columns he *might* be needing for a particular task, and just request them in the cmcRowSet functions. Since all the cmcObject wrappers are wrapping commence objects, and there is no state-data in those commence objects, then re-requesting a commence object should not cause any wrapper difficulty. It could cause some latency in the rowset if a new rowset had to be called up from a new cursor just to add a single column, but for small rowsets or properly filtered rowsets it might be quite handy to have a rowset automatically add columns to a cursor on demand.
Todo:
It is possible to create calculated columns as well. It would be possible to create simple calculated columns that operate on some simple concatination of fields, but if we can get the scripting module hooked in to this system, then we would be able to create a new cursor object call it a cursor model or something, and have that object have access to the scripting module whereby we can create truly calculated columns.

Definition at line 474 of file cmcCursor.h.


Member Enumeration Documentation

Type of Commence data to access with this cursor
.

A category is the most common method of accessing data. However, you can also access data from a filtered view. Using a filtered view you will get and already column-populated and filtered cursor to which you can acquire a rowset. A cursor object is also the API tool to use when accessing PALM type data.

Note:
If you are going to be working with cursors and THID values then there are some issues to be aware of. Refer to the section THID Bugs for more information.
Enumerator:
CATEGORY 

0 ~ Use the Commence category specified by pName.

VIEW 

1 ~ Use the Commence view specified by pName.

PILOTAB 

2 ~ Use the Commence category and fields defined from Preferences - Other Apps - 3Com Pilot Address Book

PILOTMEMO 

3 ~ Use the Commence category and fields defined from Preferences - Other Apps - 3Com Pilot Memo Pad

PILOTTODO 

5 ~ Use the Commence category and fields defined from Preferences - Other Apps - 3Com Pilot To Do List

PILOTAPPT 

6 ~ Use the Commence category and fields defined from Preferences - Other Apps - 3Com Pilot Date Book

Definition at line 495 of file cmcCursor.h.


Constructor & Destructor Documentation

cmcCursor ( const cmcCursor copy)

Copy Constructor
.

Definition at line 33 of file cmcCursor.cpp.

cmcCursor ( const long  mode,
const QString &  name,
const long  flags,
IDispatch *  disp,
cmcApplication app,
QObject *  parent = NULL 
)

Default Constructor
.

This constructor builds the Cursor wrapper object.

Parameters:
modeCursor Mode

nameCursor Name

flagsCursor Flags

dispDispatch Pointer

appApplication reference

parentObject Parent

Definition at line 39 of file cmcCursor.cpp.


Member Function Documentation

QString category ( ) [slot]

(read-only) Name of the underlying Commence category

This returns the read/only name of the underlying category.

See also:
categoryName

Definition at line 555 of file cmcCursor.cpp.

cmcCategoryDef * categoryDef ( ) [slot]

extended: Category Definition object for this cursor

The categoryDef object is part of the dumont extension library. This object provides information about the category in question, it's available field and connection properties and such.

Definition at line 565 of file cmcCursor.cpp.

QString categoryName ( void  ) [slot]

extended: (read-only) Name of the underlying Commence category

This returns the read/only name of the underlying category.

Definition at line 560 of file cmcCursor.cpp.

void clearFilter ( long  filterNumber = -1) [slot]

Clear a Filter
.

Parameters:
filterNumberlong ~ filter index number (-1 default == ALL filters)

Definition at line 96 of file cmcCursor.cpp.

long colCount ( ) [slot]

extended alias: Rowset Column Count

This is just an alias for columnCount() because I like it when my source files all line up properly, and

 dim rowCount: rowCount = rs.rowCount()
 dim colCount: colCount = rs.colCount()

Looks better than

 dim rowCount: rowCount = rs.rowCount()
 dim columnCount: columnCount = rs.columnCount()

but, that's just me!

See also:
columnCount()

Definition at line 91 of file cmcCursor.cpp.

long columnCount ( ) [slot]

(read-only) Number of columns in this cursor (-1 on error)

This returns the API column count of the cursor. Note that the value returned by this call depends on the state of the column definitions. If no columns have been defined, then this call will return the total number of fields and connections defined for this category. As soon as a column is defined, then this call returns the number of 'presently defined' columns. Therefore, the results of this call could be misleading depending on if you have defined columns for this cursor yet or not.

Definition at line 86 of file cmcCursor.cpp.

bool filter ( const QString &  filterString,
long  flags = 0 
) [virtual, slot]

Set Filter Alias
.

This is a simplified filter command that does not require the "[ViewFilter()]" syntax expression. Filters can be expressed with just the essentials.

Parameters:
filterStringstring ~ simplified filter string

flagsoption ~ default to zero

Definition at line 145 of file cmcCursor.cpp.

QString filters ( const QString &  delimiter = "\r\n") [virtual, slot]

extended: Return Defined Filters

This returns a delimited list of filters that are presently applied to the cursor object.

See also:
setFilter
Filters Explained
Parameters:
delimiteroptional ~ defaults to CrLf

Definition at line 154 of file cmcCursor.cpp.

long flags ( ) [slot]

Cursor Flags
.

See also:
mode
Returns:
long 'flags' value the cursor was created with

Definition at line 66 of file cmcCursor.cpp.

cmcRowSet * getAddRowSet ( long  rowCount = 1,
long  flags = 0 
) [virtual, slot]

Create a rowset of new items to add to the database
.

See also:
Of Cursors and RowSets
Parameters:
rowCountnumber of requested rows ~ default to ALL rows

flagsoptional ~ default zero

Definition at line 880 of file cmcCursor.cpp.

long getColumnIndex ( const QString  name,
long  flags = 0 
) [virtual, slot]

extended: Return Defined Column Index

This function accesses the cursor Column Label Cache. Normally this function has no meaning unless some columns have been designated for this cursor using one of the setColumn() or setRelatedColumn() function calls. If a column index is requested but has not yet been defined in the cursor then a -1 index value is returned.

Note:
Define a column before calling this function
See also:
setColumn( Field Name ) ' preferred
Accessing Cursor Data using Column Labels
Parameters:
namecolumn label

flagsoptional ~ default zero

Definition at line 545 of file cmcCursor.cpp.

QString getColumnLabel ( long  index,
long  flags = 0 
) [virtual, slot]

extended: Return Defined Column Name

This function accesses the cursor column index cache. Normally this function has no meaning unless some columns have been designated for this cursor. If a column label is requested but has not yet been defined in the cursor then an empty string is returned.

Note:
Define a column before calling this function.
See also:
setColumn( Field Name ) ' preferred
Accessing Cursor Data using Column Labels
Parameters:
indexcolumn index

flagsoptional ~ default zero

Definition at line 550 of file cmcCursor.cpp.

cmcRowSet * getDeleteRowSet ( long  rowCount = -1,
long  flags = 0 
) [virtual, slot]

Create a rowset of existing items for deletion
.

See also:
Of Cursors and RowSets
Parameters:
rowCountnumber of requested rows ~ default to ALL rows

flagsoptional ~ default zero

Definition at line 895 of file cmcCursor.cpp.

cmcRowSet * getDeleteRowSetByID ( const QString &  rowID,
long  flags = 0 
) [virtual, slot]

Create a rowset for deleting a particular row
.

See also:
Of Cursors and RowSets
Parameters:
rowIDsee THID's and GUID's and why we need them

flagsoptional ~ default zero

Definition at line 900 of file cmcCursor.cpp.

virtual cmcRowSet* getDeleteRowSetByTHID ( const QString &  rowID,
long  flags = 0 
) [inline, virtual, slot]

Rowset By ID alias
.

Definition at line 1355 of file cmcCursor.h.

cmcRowSet * getEditRowSet ( long  rowCount = -1,
long  flags = 0 
) [virtual, slot]

Create a rowset of existing items for editing
.

See also:
Of Cursors and RowSets
Parameters:
rowCountnumber of requested rows ~ default to ALL rows

flagsoptional ~ default zero

Definition at line 885 of file cmcCursor.cpp.

cmcRowSet * getEditRowSetByID ( const QString &  rowID,
long  flags = 0 
) [virtual, slot]

Create a rowset for editing a particular row
.

See also:
Of Cursors and RowSets
Parameters:
rowIDsee THID's and GUID's and why we need them

flagsoptional ~ default zero

Definition at line 890 of file cmcCursor.cpp.

virtual cmcRowSet* getEditRowSetByTHID ( const QString &  rowID,
long  flags = 0 
) [inline, virtual, slot]

Rowset By ID alias
.

Definition at line 1296 of file cmcCursor.h.

cmcRowSet * getQueryRowSet ( long  rowCount = -1,
long  flags = 0 
) [virtual, slot]

Create a rowset object with the results of a query
.

See also:
Of Cursors and RowSets
Parameters:
rowCountnumber of requested rows ~ default to ALL rows

flagsoptional ~ default zero

Definition at line 870 of file cmcCursor.cpp.

cmcRowSet * getQueryRowSetByID ( const QString &  rowID,
long  flags = 0 
) [virtual, slot]

Create a rowset object with a particular row loaded
.

See also:
Of Cursors and RowSets
Parameters:
rowIDsee THID's and GUID's and why we need them

flagsoptional ~ default zero

Definition at line 875 of file cmcCursor.cpp.

virtual cmcRowSet* getQueryRowSetByTHID ( const QString &  rowID,
long  flags = 0 
) [inline, virtual, slot]

Rowset By ID alias
.

Definition at line 1252 of file cmcCursor.h.

cmcCursor * getRelatedCursor ( const QString &  connectionName,
const QString  parentKey = "" 
) [virtual, slot]

extended: Get a cursor from a related column

This returns a cursor like a sub-query. It can include a filter (and should) but will default to no filter if one isn't specified. If the filter can be derived by a simple parent key (meaning the parent category has a key field (name field) and 'no-duplicates-allowed' is turned on, then this function will apply that (simple) filter directly.

/note If a parent key is specified but this call was unable to apply that filter properly then a NULL cursor will be returned to prevent the caller from attempting to operate on a cursor with too many rows.

Definition at line 616 of file cmcCursor.cpp.

IDispatch * getRowSet ( const QString &  rowSetType,
long  rowCount,
long  flags = 0 
) [private, virtual]

(internal) Return a RowSet dispatch pointer

This formats the API call to acquire a rowset handle. The dispatch pointer returned must be freed by the caller.

Parameters:
rowSetTypeRowSet Types

rowCountnumber of requested rows

flagsoptional ~ default zero

Definition at line 622 of file cmcCursor.cpp.

IDispatch * getRowSet ( const QString &  rowSetType,
const QString &  id,
long  flags = 0 
) [private, virtual]

(internal) Return a RowSet by ID dispatch pointer

Parameters:
rowSetTypesee RowSet Types

idsee THID's and GUID's and why we need them

flagsoptional ~ default zero

Definition at line 677 of file cmcCursor.cpp.

cmcRowSet * getRowSet ( long  type,
long  rowCount = -1,
const QString &  name = "",
long  flags = 0 
) [virtual, slot]

extended: Get Row Set

This function gets a generic row set. This is really a low-level function. You should consider using one of the higher-level rowset get functions.

See also:
Of Cursors and RowSets
Parameters:
typesee RowSet Types

rowCountoptional ~ number of rows to fetch. If omitted, the rowset will return all the rows in the cursor.

nameoptional ~ Normally, rowsets receive the same name as the categoryName, but they can be individually named. Naming a rowset has no functional impact over the rowset operation.

flagsoptional ~ default zero

Definition at line 735 of file cmcCursor.cpp.

cmcRowSet * getRowSet ( long  type,
const QString &  id,
const QString &  name = "",
long  flags = 0 
) [virtual, slot]

extended: Get Row Set by ID

This function gets a generic row set. This is really a low-level function. You should consider using one of the higher-level rowset get functions.

See also:
Of Cursors and RowSets
Parameters:
typesee RowSet Types

idsee THID's and GUID's and why we need them

nameoptional ~ Normally, rowsets receive the same name as the categoryName, but they can be individually named. Naming a rowset has no functional impact over the rowset operation.

flagsoptional ~ default zero

Definition at line 811 of file cmcCursor.cpp.

long maxFieldSize ( ) [virtual, slot]

extended: Return the Max Field Size

Definition at line 606 of file cmcCursor.cpp.

long maxRows ( ) [virtual, slot]

extended: Return the Max Rows

Definition at line 611 of file cmcCursor.cpp.

long mode ( ) [slot]

Cursor Mode
.

Type of Commence data to access with this cursor.

  0 - CMC_CURSOR_CATEGORY
      Use the Commence category specified by pName.

  1 - CMC_CURSOR_VIEW
      Use the Commence view specified by pName.

  2 - CMC_CURSOR_PILOTAB
      Use the Commence category and fields defined from
      Preferences - Other Apps - 3Com Pilot Address Book

  3 - CMC_CURSOR_PILOTMEMO
      Use the Commence category and fields defined from
      Preferences - Other Apps - 3Com Pilot Memo Pad

  5 - CMC_CURSOR_PILOTTODO
      Use the Commence category and fields defined from
      Preferences - Other Apps - 3Com Pilot To Do List

  6 - CMC_CURSOR_PILOTAPPT
      Use the Commence category and fields defined from
      Preferences - Other Apps - 3Com Pilot Date Book
See also:
flags
Returns:
long 'mode' value the cursor was created with

Definition at line 71 of file cmcCursor.cpp.

long rowCount ( ) [slot]

(read-only) Number of rows in this cursor (-1 on error)

This returns the current row count.

Definition at line 81 of file cmcCursor.cpp.

long seekRow ( long  origin,
long  rows 
) [virtual, slot]

Seek to a particular row in the cursor
.

Definition at line 582 of file cmcCursor.cpp.

long seekRowApprox ( long  numerator,
long  denominator 
) [virtual, slot]

Seek to an approximate position in the cursor
.

Definition at line 587 of file cmcCursor.cpp.

bool setActiveDate ( const QDate &  date,
long  flags = 0 
) [virtual, slot]

passthrough: Set active date used for view cursors using a view linking filter

Parameters:
dateDate value used with view linking filter; supports AI date values such as 'today'

flagsoptional ~ default zero

Definition at line 596 of file cmcCursor.cpp.

bool setActiveDateRange ( const QDate &  startDate,
const QDate &  endDate,
long  flags = 0 
) [virtual, slot]

passthrough: Set active date range used for view cursors using a view linking filter

Parameters:
startDateDate value of start date used with view linking filter; supports AI date values such as 'today'.

endDateDate value of end date used with view linking filter; supports AI date values such as 'next monday'.

flagsoptional ~ default zero

Definition at line 601 of file cmcCursor.cpp.

bool setActiveItem ( const QString &  categoryName,
const QString &  rowID,
long  flags = 0 
) [virtual, slot]

Set active item used for view cursors using a view linking filter
.

Parameters:
categoryNameCategory name of the active item used with view linking filter

rowIDsee THID's and GUID's and why we need them

flagsoptional ~ default zero

Definition at line 591 of file cmcCursor.cpp.

long setColumn ( const QString &  connecionName,
const QString &  targetCategoryName,
const QString &  fieldName = "",
long  flags = 0 
) [virtual, slot]

extended preferred: Set Related Column

This function sets a related column. It uses the same basic syntax as its setColumn(FieldName) counterpart, but is easier to remember than the actual setRelatedColumn(ConName,CatName,FieldName,flags) Commence API Call. It also makes the vbScript code look a little cleaner, since all the calls to set column are virtually the same. Behold:

vbScript Example of setting mixed column types
 dim cursor: set cursor = cmdb.getCursor("Inventory")
 cursor.setColumn "inventoryKey"
 cursor.setColumn "Quantity on Hand"
 cursor.setColumn "Relates to", "Inventory Location", "inventoryLocationKey"
 cursor.setColumn "Minimum Order Qty"
Note:
In the code above, both static-fields and connection-fields are referenced using the same basic code syntax, keeping the vbScript code lined up cleanly. This makes programs more readable and therefore more maintainable (I like it when things line up). Furthermore, the syntax of the procedure for setting columns is the same for regular static fields as it is for connection field, and this makes remembering the function calls easier.
See also:
setColumn( Field Name ) ' preferred
Accessing Cursor Data using Column Labels
Returns:
Index number of referenced column. -1 indicates the column reference could not be made.
Parameters:
connecionNameThe Connection Name (often 'Relates to' or 'Employed by')

targetCategoryNameThe Target Category Name

fieldNameThe Target Category Target Field Name

flagsoptional ~ default zero

Definition at line 532 of file cmcCursor.cpp.

bool setColumn ( long  column,
const QString &  name,
long  flags = 0 
) [virtual, slot]

Set Column
.

This wraps the existing Commence setColumn API function call. It requires a column parameter, and a field name parameter. However, the flags parameter is optional and may be excluded.

Like the Commence implementation, this function requires each column to be assigned in sequence. Column numbers cannot be skipped, duplicated, folded, bent or mutilated. If you reference a column out of sequence, or if you duplicate a reference to a column then you will receive a pop-up warning message, and this function will return false.

vbScript Example
 dim cursor: set cursor = cmdb.getCursor( "Person" )
 if( not cursor.setColumn(0,"First Name")  ) then exit sub
 if( not cursor.setColumn(1,"Last Name")   ) then exit sub
 if( not cursor.setColumn(2,"Middle Name") ) then exit sub
Note:
Your best best is to use one of the preferred functions instead.
See also:
setColumn( Field Name ) ' preferred
Accessing Cursor Data using Column Labels
Returns:
True/False if the column could be set
Parameters:
columnThe column number to be assigned... this should be sequential

nameThe column name to be assigned... this cannot be duplicated

flagsoptional ~ default zero

Definition at line 219 of file cmcCursor.cpp.

bool setColumn ( long  column,
const QString &  connectionName,
const QString &  targetCategoryName,
const QString &  fieldName,
long  flags = 0 
) [virtual, slot]

extended alias: Set Related Column

See original setRelatedColumn() for documentation notes.

Note:
Your best best is to use one of the preferred functions instead.
See also:
setColumn( Connection Name ) ' preferred
setRelatedColumn( Connection Name ) ' original
Accessing Cursor Data using Column Labels
Returns:
True/False if column could be set
Parameters:
columnThe Column Number to be assigned... this should be sequential

connectionNameThe Connection Name as defined in the database.

targetCategoryNameThe Target Category name

fieldNameThe Target Field name (from the target category)

flagsoptional ~ default zero

Definition at line 491 of file cmcCursor.cpp.

long setColumn ( const QString &  name,
long  flags = 0 
) [virtual, slot]

extended preferred: Set Field Column

This function is preferred over the standard Commence API setColumn function call onaccounta it is easier to use.

This function is provided as a matter of convenience for setting columns. It is intended to allow the programmer to be able to set columns and not have to worry about the actual numbers (indexes) of the columns that are being defined for a cursor. Furthermore, this function detects duplicate column references and returns the existing column reference number rather than generating an error.

See also:
setColumn( Connection Name ) ' preferred
Accessing Cursor Data using Column Labels
Returns:
Index number of referenced column. -1 indicates the column reference could not be made.
Parameters:
nameThe string-value of the column name. Note that this must match an existing field value within the category. If not, a -1 index value is returned.

flagsoptional ~ default zero

Definition at line 336 of file cmcCursor.cpp.

bool setFilter ( const QString &  filter,
long  flags = 0 
) [virtual, slot]

Defines a filter clause for the cursor
.

This function applys a filter to the cursor.

Note:
If the the filter could not be set this function will return false. In this condition, the program can query the err object to read the error message as follows:
vbScript Example ~ checking a filter set for errors (Equal is misspelled)
 if( not cursor.setFilter("[ViewFilter(1,F,,First Name,Equal to,""Jim"")]") ) then
   Quit cursor.error.description
 end if

This function has an added bonus in that if you do not include the regular "[ViewFilter()]" parameterization formatting, it will be included for you. This means that you can specify your filter strings as easily as:

vbScript Example ~ really simple strings
 if( not cursor.filter("1,F,,First Name,Equal to,Jim") ) then
   Quit cursor.error.description
 end if
Returns:
True if filter set successfully
See also:
filters
Filters Explained
Parameters:
filterstring expression ~ see Filters Explained

flagsoptional ~ default zero

Definition at line 112 of file cmcCursor.cpp.

bool setLogic ( const QString &  logic,
long  flags = 0 
) [virtual, slot]

Defines the filter logic for the cursor
.

The logic string that this function requires is identical to the DDE [ViewConjunction(AndOr12, AndOr13, AndOr34)] command. You'll have to refer to the Commence help file for syntax until I get this help file finished.

vbScript Example ~ Setting the Cursor Filter Logic
 if( not cursor.setLogic("[ViewConjunction(And,Or,And,Or,Or,Or)]") ) then
   msgBox "Error: " & cursor.error.description
   exit function
 end if
Returns:
True if logic could be set
Parameters:
logicLogic String

flagsoptional ~ default zero

Definition at line 577 of file cmcCursor.cpp.

bool setRelatedColumn ( long  column,
const QString &  connectionName,
const QString &  targetCategoryName,
const QString &  fieldName,
long  flags = 0 
) [virtual, slot]

Set Related Column
.

This wraps the existing Commence setRelatedColumn API function call. It requires a column number, a Connection name, Target Category name, a Target Field name, and a flag. However, the flag parameter is optional and may be excluded.

Like the Commence implementation, this function requires each column to be assigned in sequence. Column numbers cannot be skipped, duplicated, folded, bent or mutilated.

This function checks the requested column against the columnLabelCache of previously defined columns. During this check it is able to determine if the column is being applied is out of sequence and if the column itself has been applied previously. Both of these conditions are failure conditions.

If the column is being added out of sequence, then this call will quit with an error message. If the column has been defined previously then this function will again quit with an error message indicating so. In either case the column will not be applied to the Commence API call and the function will return false.

vbScript Example
 dim cursor: set cursor = cmdb.getCursor( "Person" )
 if( not cursor.setRelatedColumn(0,"Relates to","Calendar","calendarKey")   ) then exit sub
 if( not cursor.setRelatedColumn(1,"Family Member", "Person", "First Name") ) then exit sub
 if( not cursor.setRelatedColumn(2,"has", "Notes", "notesKey")              ) then exit sub
Note:
Your best best is to use one of the preferred functions instead.
See also:
setColumn( Connection Name ) ' preferred
setRelatedColumn( Connection Name ) ' original
Accessing Cursor Data using Column Labels
Returns:
True/False if column could be set
Parameters:
columnThe Column Number to be assigned... this should be sequential

connectionNameThe Connection Name as defined in the database.

targetCategoryNameThe Target Category name

fieldNameThe Target Field name (from the target category)

flagsoptional ~ default zero

Definition at line 374 of file cmcCursor.cpp.

long setRelatedColumn ( const QString &  connectionName,
const QString &  targetCategoryName = "",
const QString &  fieldName = "",
long  flags = 0 
) [virtual, slot]

extended: Set Related Column

This function is the same as its original setRelatedColumn() counterpart, except that the column specification is not provided. Like the other new setColumn function calls, it returns the index number of the newly added column.

vbScript Example
 dim cursor: set cursor = cmdb.getCursor( "Person" )
 if( not cursor.setRelatedColumn("Relates to","Calendar","calendarKey")   ) then exit sub
 if( not cursor.setRelatedColumn("Family Member", "Person", "First Name") ) then exit sub
 if( not cursor.setRelatedColumn("has", "Notes", "notesKey")              ) then exit sub
See also:
setColumn( Connection Name ) ' preferred
Accessing Cursor Data using Column Labels
Returns:
Index number of referenced column. -1 indicates the column reference could not be made.
Parameters:
connectionNameThe Connection Name as defined in the database.

targetCategoryNameThe Target Category name

fieldNameThe Target Field name (from the target category)

flagsoptional ~ default zero

Definition at line 507 of file cmcCursor.cpp.

bool setSort ( const QString &  sort,
long  flags = 0 
) [virtual, slot]

Defines the sort criteria for the cursor
.

Note:
This function will automatically add the string '[ViewSort()' formatting to the sort string if you do not provide it.
Parameters:
sortsort ~ string
flagsoptional ~ default zero

Definition at line 159 of file cmcCursor.cpp.

bool shared ( ) [slot]

(read-only) TRUE if category is shared in a workgroup

Definition at line 572 of file cmcCursor.cpp.

bool useThids ( ) [slot]

Indicates if this cursor is using THIDS
.

Returns:
True if USE_THIDS was provided at cursor open

Definition at line 76 of file cmcCursor.cpp.


Member Data Documentation

QStringList m_columnLabelCache [private]

Column Label Cache
.

This holds a list of all the column names that have been specifically assigned to this cursor object. If no column names have been assigned, then this list will be empty and the related function calls for reading the column label list will do nothing (ie; return empty lists or whatever)

Definition at line 1517 of file cmcCursor.h.


The documentation for this class was generated from the following files:
 All Classes Namespaces Functions Variables Enumerations Enumerator Properties




~ ~ ~ ~ ~ ~
Source Code without Comments is like a Cranberry Garland
without the berries. Comment your Code!
 
Commence Database User Support Group Forum
http://newsgroup.showoff-db.org/
~ ~ ~ ~ ~ ~
Author: Mark Petryk
Lorimark Solutions, LLC
mark@lorimarksolutions.com