Cursor Class Reference

Commence Cursor Object Wrapper. More...

#include <cursor.h>

List of all members.

Public Types

enum  Flag { NoFlags = 0, UseThids = 256 }
 Optional Cursor Flags. More...
enum  Mode {
  Category = 0, View = 1, Pilotab = 2, Pilotmemo = 3,
  Pilotodo = 5, Pilotappt = 6
}
 Type of Commence data to access with this cursor. More...

Public Member Functions

QString category () const
 (read-only) Name of the underlying Commence category
QString categoryName () const
 extended: (read-only) Name of the underlying Commence category
void clearFilter (int filterNumber=-1)
 Clear a Filter.
int colCount () const
 extended alias: Rowset Column Count
QString conCatFieldName (const QString &conName, const QString &catName, const QString &fieldName="") const
 Connection Category Field Name.
 Cursor (const Cursor &copy)
 Copy Constructor.
 Cursor (QObject *parent=0)
 Default Constructor.
 Cursor (Mode mode, const QString &catName, Flag flags, const Database &db)
 Constructor.
QStringList filterSet () const
 extended: Return Defined Filters
RowSet getAddRowSet (int rowCount=1, int flags=0) const
 Create a rowset of new items to add to the database.
int getColumnIndex (const QString name, int flags=0) const
 extended: Return Defined Column Index
QString getColumnLabel (int index, int flags=0) const
 extended: Return Defined Column Name
CommenceAPI::ICommenceCursor * getCommenceCursor () const
 Return the Internal Server Pointer.
RowSet getDeleteRowSet (int rowCount=-1, int flags=0) const
 Create a rowset of existing items for deletion.
RowSet getDeleteRowSetByID (const QString &rowID, int flags=0) const
 Create a rowset for deleting a particular row.
RowSet getDeleteRowSetByTHID (const QString &rowID, int flags=0) const
 Rowset By ID alias.
RowSet getEditRowSet (int rowCount=-1, int flags=0) const
 Create a rowset of existing items for editing.
RowSet getEditRowSetByID (const QString &rowID, int flags=0) const
 Create a rowset for editing a particular row.
RowSet getEditRowSetByTHID (const QString &rowID, int flags=0) const
 Rowset By ID alias.
RowSet getQueryRowSet (int rowCount=-1, int flags=0) const
 Create a rowset object with the results of a query.
RowSet getQueryRowSetByID (const QString &rowID, int flags=0) const
 Create a rowset object with a particular row loaded.
RowSet getQueryRowSetByTHID (const QString &rowID, int flags=0) const
 Rowset By ID alias.
Cursor getRelatedCursor (const QString &connectionName, const QString &parentKey="") const
 extended: Get a cursor from a related column
RowSet getRowSet (RowSet::Type type, const QString &id, const QString &name="", int flags=0) const
 extended: Get Row Set by ID
RowSet getRowSet (RowSet::Type type, int rowCount=-1, const QString &name="", int flags=0) const
 extended: Get Row Set
int maxFieldSize () const
 extended: Return the Max Field Size
int maxRows () const
 extended: Return the Max Rows
Cursor operator= (const Cursor &cursor)
 Assignment Operator.
int rowCount () const
 (read-only) Number of rows in this cursor (-1 on error)
int seekRow (int origin, int rows)
 Seek to a particular row in the cursor.
int seekRowApprox (int numerator, int denominator)
 Seek to an approximate position in the cursor.
bool setActiveDate (const QDate &date, int flags=0)
 Alias.
bool setActiveDate (const QString &sDate, int flags=0)
 passthrough: Set active date used for view cursors using a view linking filter
bool setActiveDateRange (const QDate &startDate, const QDate &endDate, int flags=0)
 Alias.
bool setActiveDateRange (const QString &startDate, const QString &endDate, int flags=0)
 passthrough: Set active date range used for view cursors using a view linking filter
bool setActiveItem (const QString &categoryName, const QString &rowID, int flags=0)
 Set active item used for view cursors using a view linking filter.
bool setColumn (int column, const QString &connectionName, const QString &targetCategoryName, const QString &fieldName, int flags=0)
 extended alias: Set Related Column
bool setColumn (int column, const QString &fieldName, int flags=0)
 Set Column.
int setColumn (const QString &connectionName, const QString &targetCategoryName, const QString &fieldName, int flags=0)
 extended preferred: Set Related Column
int setColumn (const QString &fieldName, int flags=0)
 extended preferred: Set Field Column
bool setFilter (const QString &filter, int flags=0)
 Defines a filter clause for the cursor.
bool setFilters (const QStringList &filters)
 Set Filters.
bool setLogic (const QString &logic, int flags=0)
 Defines the filter logic for the cursor.
int setRelatedColumn (const QString &connectionName, const QString &targetCategoryName="", const QString &fieldName="", int flags=0)
 extended: Set Related Column
bool setRelatedColumn (int column, const QString &connectionName, const QString &targetCategoryName, const QString &fieldName, int flags=0)
 Set Related Column.
bool setSort (const QString &sort, int flags=0)
 Defines the sort criteria for the cursor.
bool shared () const
 (read-only) TRUE if category is shared in a workgroup
int unfilteredRowCount () const
 Total Category Rows.
bool usingThids () const
 Indicates if this cursor is using THIDS.


Detailed Description

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

Note:
Use care when pulling rowsets on a Cursor. You will run into difficulties if you try to pull two rowsets on the same cursor without repositioning the cursor using seekRow.

RowSets created with this cursor object maintain a reference to the originating Cursor object. Therefore, if your code destroys its own cursor reference, the orignial Cursor will still exist inside the RowSet, and the reference will not be lost. This is a good thing, and is the result of the the "pimpl idiom" http://en.wikipedia.org/wiki/Opaque_pointer employed in this API.

Definition at line 93 of file cursor.h.


Member Enumeration Documentation

enum Flag

Optional Cursor Flags.

Normally cursors are opened with no flags. Optionally, a cursor can be opened to cause it to return THID values for each row.

Enumerator:
NoFlags  0 ~ Open cursor with normal data
UseThids  256 ~ Open cursor to return THID values (0x100)

Definition at line 152 of file cursor.h.

enum Mode

Type of Commence data to access with this cursor.

A Cursor::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 name.
View  1 ~ Use the Commence view specified by name.
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
Pilotodo  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 115 of file cursor.h.


Constructor & Destructor Documentation

Cursor ( Cursor::Mode  mode,
const QString &  catName,
Cursor::Flag  flags,
const Database db 
)

Constructor.

This constructor is called from the Database object.

Parameters:
mode Mode ~ mode the cursor should be opened in
catName String ~ Category Name
flags Flags ~ Flags to be passed to the cursor
db Database ~ Reference to hosting database object

Definition at line 961 of file cursor.cpp.

Cursor ( QObject *  parent = 0  ) 

Default Constructor.

This constructs an empty (and invalid) cursor object.

Definition at line 988 of file cursor.cpp.

Cursor ( const Cursor copy  ) 

Copy Constructor.

This copies a cursor object from one to another. Note that the internal cursor object is not copied, just the reference object, making copy operations very efficient.

Definition at line 1003 of file cursor.cpp.


Member Function Documentation

QString category (  )  const

(read-only) Name of the underlying Commence category

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

See also:
categoryName

Definition at line 1118 of file cursor.cpp.

QString categoryName (  )  const [inline]

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

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

Definition at line 204 of file cursor.h.

void clearFilter ( int  filterNumber = -1  ) 

Clear a Filter.

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

Definition at line 1184 of file cursor.cpp.

int colCount (  )  const

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 1160 of file cursor.cpp.

QString conCatFieldName ( const QString &  conName,
const QString &  catName,
const QString &  fieldName = "" 
) const

Connection Category Field Name.

This returns a formatted composite of the conName->catName(fieldName) definition.

Returns:
String ~ "Relates to->Calendar(calendarKey)"
Parameters:
conName String ~ Connection Name such as "Relates to"
catName String ~ Category Name such as "Calendar"
fieldName String ~ Field Name such as "calendarKey"

Definition at line 1204 of file cursor.cpp.

QStringList filterSet (  )  const

extended: Return Defined Filters

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

See also:
setFilter

viewFilter

Definition at line 1828 of file cursor.cpp.

RowSet getAddRowSet ( int  rowCount = 1,
int  flags = 0 
) const

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

See also:
Of Cursors and RowSets
Parameters:
rowCount number of requested rows ~ default to ALL rows
flags optional ~ default zero

Definition at line 2104 of file cursor.cpp.

int getColumnIndex ( const QString  columnName,
int  flags = 0 
) const

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:
columnName column label
flags optional ~ default zero

Definition at line 1739 of file cursor.cpp.

QString getColumnLabel ( int  index,
int  flags = 0 
) const

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:
index column index
flags optional ~ default zero

Definition at line 1920 of file cursor.cpp.

CommenceAPI::ICommenceCursor * getCommenceCursor (  )  const

Return the Internal Server Pointer.

The internal server is the actual Commence cursor object that we are wrapping. If the root object is needed for some purpose, then it can be retrieved here. Note that any calls made through this object completely bypass the DumontAPI interface and wrapper functions.

Definition at line 1069 of file cursor.cpp.

RowSet getDeleteRowSet ( int  rowCount = -1,
int  flags = 0 
) const

Create a rowset of existing items for deletion.

See also:
Of Cursors and RowSets
Parameters:
rowCount number of requested rows ~ default to ALL rows
flags optional ~ default zero

Definition at line 2125 of file cursor.cpp.

RowSet getDeleteRowSetByID ( const QString &  rowID,
int  flags = 0 
) const

Create a rowset for deleting a particular row.

See also:
Of Cursors and RowSets
Parameters:
rowID see thids
flags optional ~ default zero

Definition at line 2146 of file cursor.cpp.

RowSet getDeleteRowSetByTHID ( const QString &  rowID,
int  flags = 0 
) const

Rowset By ID alias.

Definition at line 2185 of file cursor.cpp.

RowSet getEditRowSet ( int  rowCount = -1,
int  flags = 0 
) const

Create a rowset of existing items for editing.

See also:
Of Cursors and RowSets
Parameters:
rowCount number of requested rows ~ default to ALL rows
flags optional ~ default zero

Definition at line 2062 of file cursor.cpp.

RowSet getEditRowSetByID ( const QString &  rowID,
int  flags = 0 
) const

Create a rowset for editing a particular row.

See also:
Of Cursors and RowSets
Parameters:
rowID see thids
flags optional ~ default zero

Definition at line 2083 of file cursor.cpp.

RowSet getEditRowSetByTHID ( const QString &  rowID,
int  flags = 0 
) const

Rowset By ID alias.

Definition at line 2175 of file cursor.cpp.

RowSet getQueryRowSet ( int  rowCount = -1,
int  flags = 0 
) const

Create a rowset object with the results of a query.

See also:
Of Cursors and RowSets
Parameters:
rowCount number of requested rows ~ default to ALL rows
flags optional ~ default zero

Definition at line 2018 of file cursor.cpp.

RowSet getQueryRowSetByID ( const QString &  rowID,
int  flags = 0 
) const

Create a rowset object with a particular row loaded.

See also:
Of Cursors and RowSets
Parameters:
rowID see thids
flags optional ~ default zero

Definition at line 2040 of file cursor.cpp.

RowSet getQueryRowSetByTHID ( const QString &  rowID,
int  flags = 0 
) const

Rowset By ID alias.

Definition at line 2165 of file cursor.cpp.

Cursor getRelatedCursor ( const QString &  connectionName,
const QString &  parentKey = "" 
) const

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 2205 of file cursor.cpp.

RowSet getRowSet ( RowSet::Type  type,
const QString &  id,
const QString &  name = "",
int  flags = 0 
) const

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:
type see RowSet Types
id see thids
name optional ~ 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.
flags optional ~ default zero

Definition at line 1984 of file cursor.cpp.

RowSet getRowSet ( RowSet::Type  type,
int  rowCount = -1,
const QString &  name = "",
int  flags = 0 
) const

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:
type see RowSet Types
rowCount optional ~ number of rows to fetch. If omitted, the rowset will return all the rows in the cursor.
name optional ~ 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.
flags optional ~ default zero

Definition at line 1943 of file cursor.cpp.

int maxFieldSize (  )  const

extended: Return the Max Field Size

Definition at line 1225 of file cursor.cpp.

int maxRows (  )  const

extended: Return the Max Rows

Definition at line 1250 of file cursor.cpp.

Cursor operator= ( const Cursor cursor  ) 

Assignment Operator.

Definition at line 1014 of file cursor.cpp.

int rowCount (  )  const

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

This returns the current row count.

Definition at line 1290 of file cursor.cpp.

int seekRow ( int  origin,
int  rows 
)

Seek to a particular row in the cursor.

Definition at line 1303 of file cursor.cpp.

int seekRowApprox ( int  numerator,
int  denominator 
)

Seek to an approximate position in the cursor.

Definition at line 1315 of file cursor.cpp.

bool setActiveDate ( const QDate &  date,
int  flags = 0 
)

Alias.

Accepts QDate instead of string.

Definition at line 1350 of file cursor.cpp.

bool setActiveDate ( const QString &  date,
int  flags = 0 
)

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

Parameters:
date Date value used with view linking filter; supports AI date values such as 'today'
flags optional ~ default zero

Definition at line 1329 of file cursor.cpp.

bool setActiveDateRange ( const QDate &  startDate,
const QDate &  endDate,
int  flags = 0 
)

Alias.

Definition at line 1386 of file cursor.cpp.

bool setActiveDateRange ( const QString &  startDate,
const QString &  endDate,
int  flags = 0 
)

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

Parameters:
startDate Date value of start date used with view linking filter; supports AI date values such as 'today'
endDate Date value of end date used with view linking filter; supports AI date values such as 'next monday'
flags optional ~ default zero

Definition at line 1364 of file cursor.cpp.

bool setActiveItem ( const QString &  pCategoryName,
const QString &  pRowID,
int  flags = 0 
)

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

Parameters:
pCategoryName Category name of the active item used with view linking filter
pRowID see thids
flags optional ~ default zero

Definition at line 1402 of file cursor.cpp.

bool setColumn ( int  column,
const QString &  connectionName,
const QString &  targetCategoryName,
const QString &  fieldName,
int  flags = 0 
)

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:
column The Column Number to be assigned... this should be sequential
connectionName The Connection Name as defined in the database
targetCategoryName The Target Category name

fieldName The Target Field name (from the target category)
flags optional ~ default zero

Definition at line 1585 of file cursor.cpp.

bool setColumn ( int  column,
const QString &  fieldName,
int  flags = 0 
)

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 bet 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:
column The column number to be assigned... this should be sequential
fieldName The column name to be assigned... this cannot be duplicated
flags optional ~ default zero

Definition at line 1456 of file cursor.cpp.

int setColumn ( const QString &  connectionName,
const QString &  targetCategoryName,
const QString &  fieldName = "",
int  flags = 0 
)

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:
connectionName The Connection Name (often 'Relates to' or 'Employed by')
targetCategoryName The Target Category Name
fieldName The Target Category Target Field Name
flags optional ~ default zero

Definition at line 1550 of file cursor.cpp.

int setColumn ( const QString &  fieldName,
int  flags = 0 
)

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:
fieldName The 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.
flags optional ~ default zero

Definition at line 1494 of file cursor.cpp.

bool setFilter ( const QString &  filter,
int  flags = 0 
)

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

viewFilter

Parameters:
filter string expression ~ see viewFilter
flags optional ~ default zero

Definition at line 1788 of file cursor.cpp.

bool setFilters ( const QStringList &  filters  ) 

Set Filters.

This will set all the filters at one time.

Definition at line 1808 of file cursor.cpp.

bool setLogic ( const QString &  logic,
int  flags = 0 
)

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:
logic Logic String
flags optional ~ default zero

Definition at line 1868 of file cursor.cpp.

int setRelatedColumn ( const QString &  connectionName,
const QString &  targetCategoryName = "",
const QString &  fieldName = "",
int  flags = 0 
)

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:
connectionName The Connection Name as defined in the database
targetCategoryName The Target Category name
fieldName The Target Field name (from the target category)
flags optional ~ default zero

Definition at line 1694 of file cursor.cpp.

bool setRelatedColumn ( int  column,
const QString &  connectionName,
const QString &  targetCategoryName,
const QString &  fieldName,
int  flags = 0 
)

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:
column The Column Number to be assigned... this should be sequential
connectionName The Connection Name as defined in the database
targetCategoryName The Target Category name
fieldName The Target Field name (from the target category)
flags optional ~ default zero

Definition at line 1648 of file cursor.cpp.

bool setSort ( const QString &  sort,
int  flags = 0 
)

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:
sort sort ~ string
flags optional ~ default zero

Definition at line 1892 of file cursor.cpp.

bool shared (  )  const

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

Definition at line 1170 of file cursor.cpp.

int unfilteredRowCount (  )  const

Total Category Rows.

This returns the total number of rows available before any filter is applied.

Definition at line 1277 of file cursor.cpp.

bool usingThids (  )  const [inline]

Indicates if this cursor is using THIDS.

Returns:
True if USE_THIDS was provided at cursor open

Definition at line 196 of file cursor.h.


The documentation for this class was generated from the following files:




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