DumontDSO::IDumontDataSet Interface Reference

Dumont DataSetObject Interface. More...

import "IDumontDSO.idl";

Inheritance diagram for DumontDSO::IDumontDataSet:

Inheritance graph

List of all members.

Public Member Functions

HRESULT _stdcall firstRow ([out, retval] long *Value)
 Move to the first row (index 0).
HRESULT _stdcall prevRow ([out, retval] long *Value)
 Back up one row.
HRESULT _stdcall nextRow ([out, retval] long *Value)
 Move forward one row.
HRESULT _stdcall lastRow ([out, retval] long *Value)
 Move to the last row (index = rowCount()-1).
HRESULT _stdcall deleteRow ([out, retval] long *ResultCode)
 Delete the current row.
HRESULT _stdcall post ([out, retval] long *ResultCode)
 Post changes to the database.
HRESULT _stdcall addFieldColumn ([in] BSTR Value)
 Add a field to the column definition list.
HRESULT _stdcall addConnectedColumn ([in]BSTR v_conName,[in]BSTR v_catName,[in]BSTR v_fieldName)
 Add a Connection Field to the column definition list.
HRESULT _stdcall delVar ([in] BSTR fldName,[in] BSTR varName)
 Delete a FieldVar.
HRESULT _stdcall dv ([in] BSTR vn)
 Delete a VarName from the catNameVar field.
HRESULT _stdcall filterClear (void)
 Clears the current filter definition.
HRESULT _stdcall sortClear (void)
HRESULT _stdcall test (void)
 Internal Test Function.

Properties

BSTR catName [get, set]
 Get and Set the category Name.
BSTR keyField [get, set]
long columnCount [get]
 Get the column count.
long rowCount [get]
 Return the rowCount for the dataset.
long addRows [get, set]
 Add rows to the DataSet.
long rowNumber [get, set]
 Get and Set the current Row Number.
VARIANT_BOOL bof [get]
 Returns true/false Beginning of File.
VARIANT_BOOL eof [get]
 Returns true/false End of File.
VARIANT_BOOL isDirtyRow [get]
 Returns true/false if the DataSet has been changed.
VARIANT_BOOL isDirtySet [get]
VARIANT_BOOL isAdd [get]
 True/False if the current RowNumber() is an AddRow().
BSTR fldVar ([in] BSTR fldName,[in] BSTR varName) [get, set]
 Get/Set a varField from a category field.
BSTR fv ([in] BSTR fn) [get, set]
 Get/Set a FieldValue based on its FieldName.
BSTR cv ([in] long cn) [get, set]
 Get/Set a FieldValue based on its ColumnNumber.
BSTR vt ([in] BSTR vn) [get, set]
 Get/Set a (Text) FieldValue based on its VarName.
long vi ([in] BSTR vn) [get, set]
 Get/Set a (Integer) FieldValue based on its VarName.
double vd ([in] BSTR vn) [get, set]
 Get/Set a (Double) FieldValue based on its VarName.
BSTR filter [get, set]
 Sets the first line in a filter definition.
BSTR andFilter [set]
 Add a And filter clause to the set.
BSTR orFilter [set]
 Add a Or filter clause to the set.
BSTR sort [get, set]
BSTR addSort [set]
IDumontDataSet openDataSet ([in] BSTR catName,[in] BSTR conName) [get]
 Get a connection as a DataSet.
IDumontDataSetChange openDataSetChange ([in] BSTR catName,[in] BSTR conName) [get]
 Get a connection as a DataSetChange.
IDumontDataSetCalendar openDataSetCalendar ([in] BSTR catName,[in] BSTR conName) [get]
 Get a connection as a DataSetCalendar.


Detailed Description

Dumont DataSetObject Interface.

This is the interface to the DumontDataSet object. This interface is designed to turn the Commence Cursor/Query/Edit/Add/Delete object into a single cohesive unit. The DataSet object has regular DataSet management methods and properties that programmers are normally used to having available.

The DumontDataSet object, therefore, acts as a wrapper class for the Commence CQEAD interfaces:

 +-[DumontDataSet]----+
 |                    |
 |  Cursor            |--O rowCount, rowNumber
 |    QueryRowSet     |--O firstRow, nextRow, prevRow, lastRow
 |    EditRowSet      |--O fv, cv, fldVar
 |    AddRowSet       |--0 filter, andFilter, orFilter
 |    DeleteRowSet    |--O sort
 |                    |
 +--------------------+

For example, what used to require this:

    dim cmcDB: set cmcDB = CreateObject("Commence.DB")
    dim cursr: set cursr = cmcDB.GetCursor( 0, "Calendar", 0 )
    cursr.setFilter "[ViewFilter(1,F,,calendarKey,Contains,Lunch)]", 0
    cursr.setSort   "[SetSort(Date,Ascending)]", 0
    dim ers: set ers = cursr.GetEditRowSet( cursr.RowCount, 0 )
    dim i: for i = 0 to ers.RowCount - 1
      dim calKey:  calKey  = ers.GetRowValue( i, ers.GetColumnIndex( "calendarKey", 0 ), 0 )
      dim calDate: calDate = ers.GetRowValue( i, ers.GetColumnIndex( "Date", 0 ), 0 )
      msgBox calKey & " " & calDate
      if( calDate = "12/12/2007" ) then
        ers.modifyRow i, ers.GetColumnIndex( "Note" ), "Eat Salad!", 0
      end if
    next
    ers.commit 0

can now be expressed like this:

    dim dumSDK: set dumSDK = CreateObject("DumontSDK.DSO")
    dim calDSO: set calDSO = dumSDK.DataSet("Calendar")
    calDSO.filter = "F,,calendarKey,Contains,Lunch"
    calDSO.sort   = "Date,Ascending"
    while not calDSO.eof
      msgbox calDSO.fv("calendarKey") & " " & calDSO.fv("Date")
      if( calDSO.fv("Date") = "12/12/2007" ) then
        calDSO.fv("Note") = "Eat Salad!"
      end if
    wend
    calDSO.post

One issue when using Commence Cursors and RowSets is dealing with the longevity and validity of the cursor object. For instance, when pulling an EditRowSet from a Cursor, the Cursor effectively becomes invalid without care taken on the (poorly documented) 'cursor row pointer'. An attempt to use the cursor again for some operation without presummably resetting the cursor 'current row pointer' will result in an error. The cursor must be reset and filters and sorts reapplied before it can be used to get another RowSet object. The DumontSDK takes care of these obscure details and effectively wraps the Commence database API into a cohesive, easy to use DataSet type of object.

There are unexpected limitations in the Commence API that the programmer will quickly experience when trying to perform some serious automation on any category. One of these entails interfacing to the Connection type fields from within a RowSet. These connections are limited to a CrLf delimited list of connected items. No editing of these items is possible without opening yet another dataset on the target category. To further complicate the issue, special filtering tactics must be applied on the target connection category to arrive at the correct connected item before any editing can be safely performed. The DumontSDK takes care of these obscure details and effectively wraps the Commence database into a cohesive, easy to use DataSet type of object.

Commence categories are limited to 100 fields. In some cases this represents a serious limitation in the practical application of Commence in various real-world applications. Take Realestate Management for instance. This is an industry that usually requires a great number of fields for managing all of the details of a realestate contract. The DumontSDK DataSet interface provides the ability to easily extend the field limit in Commence above the 100 field high. Adding additional fields to a Commence beyond the 100 field limit is a natural part of the DataSet object.

See also:
QCosDumontDataSet

Definition at line 156 of file IDumontDSO.idl.


Member Function Documentation

HRESULT _stdcall DumontDSO::IDumontDataSet::addConnectedColumn ( [in] BSTR  v_conName,
[in] BSTR  v_catName,
[in] BSTR  v_fieldName 
)

Add a Connection Field to the column definition list.

Parameters:
v_conName The "Name" of the connection
v_catName The "Category the connection connects to
v_fieldName The "Field" in the category the connection connects to
This function appends a Connection name to the list of field names defined in the dataset Column defs. Before a connection is added the list is first checked to see if the connection column has already been defined since defining the connection column twice would cause a problem with Commence.

HRESULT _stdcall DumontDSO::IDumontDataSet::addFieldColumn ( [in] BSTR  Value  ) 

Add a field to the column definition list.

Parameters:
Value String of the field name to add
This function appends a field name to the list of field names defined in the dataset Column defs. Before a column is added the list is first checked to see if the column has already been defined since defining the column twice would cause a problem with Commence.

HRESULT _stdcall DumontDSO::IDumontDataSet::deleteRow ( [out, retval] long *  ResultCode  ) 

Delete the current row.

HRESULT _stdcall DumontDSO::IDumontDataSet::delVar ( [in] BSTR  fldName,
[in] BSTR  varName 
)

Delete a FieldVar.

HRESULT _stdcall DumontDSO::IDumontDataSet::dv ( [in] BSTR  vn  ) 

Delete a VarName from the catNameVar field.

HRESULT _stdcall DumontDSO::IDumontDataSet::filterClear ( void   ) 

Clears the current filter definition.

See also:
filter, andFilter, orFilter

HRESULT _stdcall DumontDSO::IDumontDataSet::firstRow ( [out, retval] long *  Value  ) 

Move to the first row (index 0).

See also:
rowNumber, prevRow, nextRow, lastRow, bof, eof

HRESULT _stdcall DumontDSO::IDumontDataSet::lastRow ( [out, retval] long *  Value  ) 

Move to the last row (index = rowCount()-1).

See also:
rowNumber, firstRow, prevRow, nextRow, bof, eof

HRESULT _stdcall DumontDSO::IDumontDataSet::nextRow ( [out, retval] long *  Value  ) 

Move forward one row.

See also:
rowNumber, firstRow, prevRow, lastRow, bof, eof

HRESULT _stdcall DumontDSO::IDumontDataSet::post ( [out, retval] long *  ResultCode  ) 

Post changes to the database.

HRESULT _stdcall DumontDSO::IDumontDataSet::prevRow ( [out, retval] long *  Value  ) 

Back up one row.

See also:
rowNumber, firstRow, nextRow, lastRow, bof, eof

HRESULT _stdcall DumontDSO::IDumontDataSet::sortClear ( void   ) 

HRESULT _stdcall DumontDSO::IDumontDataSet::test ( void   ) 

Internal Test Function.

This is a test function for internal testing purposes only. It should NOT be used.

Implemented in DumontDSO::IDumontDataSetChange, and DumontDSO::IDumontDataSetCalendar.


Property Documentation

long DumontDSO::IDumontDataSet::addRows [get, set]

Add rows to the DataSet.

This property will add additional rows to the DataSet object. Note that the rows won't actully exist in the database until a call to post() is made. Adding rows to the dataset has the effect of increasing the rowCount().

Note:
Once set, the value should not be changed until the dataset post() command is called.
vbScript example:
 msgbox calDSO.rowCount ' could indicate 10
 calDSO.addRows = 5
 msgbox calDSO.rowCount ' should now indicate 15

BSTR DumontDSO::IDumontDataSet::addSort [set]

BSTR DumontDSO::IDumontDataSet::andFilter [set]

Add a And filter clause to the set.

See also:
filter, orFilter, filterClear

VARIANT_BOOL DumontDSO::IDumontDataSet::bof [get]

Returns true/false Beginning of File.

See also:
rowNumber, firstRow, prevRow, nextRow, lastRow, eof

BSTR DumontDSO::IDumontDataSet::catName [get, set]

Get and Set the category Name.

This "Gets" and "Sets" the Category Name assigned to the DataSet object. This can be used to retrieve the current category name but normally should not be used to set the category name. Instead the category name should be set when the dataset is first instantiated.

vbScript example:
 dim dumSDK: set dumSDK = createObject("DumontSDK.DSO")
 dim calDSO: set calDSO = dumSDK.DataSet("Calendar")
 msgbox calDSO.catName

long DumontDSO::IDumontDataSet::columnCount [get]

Get the column count.

This value will normally be 100 when the dataset is first instantiated until a column is defined.

BSTR DumontDSO::IDumontDataSet::cv [get, set]

Get/Set a FieldValue based on its ColumnNumber.

VARIANT_BOOL DumontDSO::IDumontDataSet::eof [get]

Returns true/false End of File.

vbScript example:
 ds.firstRow
 while not ds.eof
   msgbox fv("calendarKey")
   ds.nextRow
 wend
See also:
rowNumber, firstRow, prevRow, nextRow, lastRow, bof

BSTR DumontDSO::IDumontDataSet::filter [get, set]

Sets the first line in a filter definition.

In (Get), this function returns ALL the lines currently defined in the filter.

Note:
This has the same effect as clearing the filter settings and then reappying this one filter line.
vbScript example:
 dim dumSDK: set dumSDK = createObject("DumontSDK.DSO")
 dim calDS:  set calDS  = dumSDK.DataSet("Calendar")
 calDS.filter    "F,,calendarKey,Contains,Lunch"
 calDS.andFilter "F,,Date Start,Between,1/1/07,3/1/07"
 calDS.orFilter  "F,,calendarKey,Contains,Dinner"
 calDS.andFilter "F,,Date Start,Between,1/1/07,3/1/07"
 msgbox calDS.rowCount ' better be only a few!
See also:
andFilter, orFilter, filterClear

BSTR DumontDSO::IDumontDataSet::fldVar [get, set]

Get/Set a varField from a category field.

This property get/set is part of the Category Field Extension Module (CFEM). This property will manipulate any field in the category and apply an .ini type of file data structure to it. This allows additional field values to be quickly stored and retrieved on an item-by-item basis.

vbScript example:
Assuming you have a MEMO field in your calendar category called calendarVar, you can use the following code to set and retrieve value from that field using the CFEM.
 dim dumSDK: set dumSDK = createObject("DumontSDK.DSO")
 dim calDS:  set calDS  = dumSDK.DataSet("Calendar")
 calDS.filter "F,,calendarKey,Contains,Lunch"
 while not calDS.eof
  if( calDS.fv("Date Start") > "12/31/06" )
    calDS.fldVar("calendarVar","nextYear")   = "True"
    calDS.fldVar("calendarVar","Reschedule") = "False"
    calDS.fldVar("calendarVar","sysMsg")     = "These values were set automatically"
  end if
 wend
 calDS.post
The preceeding code will have the effect of placing the following values in the calendarVar memo field:
 calendarVar:
   nextYear=True
   Reschedule=False
   sysMsg=These values were set automatically
Warning:
Commence MEMO fields are limited to 32K bytes. This can impose a limitation depending on the type of data being stored in it using the CFEM. For practical purposes only short fields should be stored using the CFEM.

The CFEM is designed to manipulate Text-only data. Attempting to store binary data is likely to cause a fault.

See also:
delVar

BSTR DumontDSO::IDumontDataSet::fv [get, set]

Get/Set a FieldValue based on its FieldName.

VARIANT_BOOL DumontDSO::IDumontDataSet::isAdd [get]

True/False if the current RowNumber() is an AddRow().

VARIANT_BOOL DumontDSO::IDumontDataSet::isDirtyRow [get]

Returns true/false if the DataSet has been changed.

VARIANT_BOOL DumontDSO::IDumontDataSet::isDirtySet [get]

BSTR DumontDSO::IDumontDataSet::keyField [get, set]

IDumontDataSet DumontDSO::IDumontDataSet::openDataSet([in] BSTR catName, [in] BSTR conName) [get]

Get a connection as a DataSet.

Parameters:
catName Connected Category name
conName Category Reverse Connection
This command is very powerful to vbScript programs. This will fetch a new DataSet object that is automatically connected to this DataSet. The fetched DataSet is automatically filtered to only include rows that satisfy the connection.

The parameters to this command really act like a "reverse" connection, specifying the "target" category, and the connection field from that target category back to the existing category. To say it another way, if we have a Company category open, and we want the employees for that company, we simply fetch the "Person Employed by" connection, and we receive an already-filtered dataset of People who are employed by this company.

The resulting DataSet has all of the DataSet editing properties available just like any other DataSet interface. Consider the following example:

vbScript example:
 '    Using the following layout between a Person
 '    and a company category:
 '
 '   +-----------+                    +-----------+
 '   |           |---[Employed By]--->|           |
 '   |  Person   |                    |  Company  |
 '   |           |<----[Employs]------|           |
 '   +-----------+                    +-----------+
 '
 ' Open the company category
 '
 dim dumDSO:     set dumDSO     = createObject("DumontSDK.DSO")
 dim employerDS: set employerDS = dumDSO.OpenDataSet("Company")
 employerDS.keyField = "companyKey"
 employerDS:filter   = "F,,companyKey,Contains,Widget Makers, Inc."
 
 '
 ' Open the Employees on this company
 '
 dim employeeDS: set employeeDS = employerDS.OpenDataSet( "Person", "Employed by" )
 while not employeeDS.eof
  msgbox employeeDS.fv("personKey")
  employeeDS.nextRow
 wend

IDumontDataSetCalendar DumontDSO::IDumontDataSet::openDataSetCalendar([in] BSTR catName, [in] BSTR conName) [get]

Get a connection as a DataSetCalendar.

IDumontDataSetChange DumontDSO::IDumontDataSet::openDataSetChange([in] BSTR catName, [in] BSTR conName) [get]

Get a connection as a DataSetChange.

BSTR DumontDSO::IDumontDataSet::orFilter [set]

Add a Or filter clause to the set.

See also:
filter, andFilter, filterClear

long DumontDSO::IDumontDataSet::rowCount [get]

Return the rowCount for the dataset.

This value will include addRows when addRows have been requested.

long DumontDSO::IDumontDataSet::rowNumber [get, set]

Get and Set the current Row Number.

The RowNumber range is from zero to the RowCount()-1. Note that the rowCount() is a composite of the editRows() and addRows() values.

Warning:
If the RowNumber is assigned a value beyond the range of the rowCount then the change request is completely ignored.
See also:
firstRow, prevRow, nextRow, lastRow, bof, eof

BSTR DumontDSO::IDumontDataSet::sort [get, set]

double DumontDSO::IDumontDataSet::vd [get, set]

Get/Set a (Double) FieldValue based on its VarName.

long DumontDSO::IDumontDataSet::vi [get, set]

Get/Set a (Integer) FieldValue based on its VarName.

BSTR DumontDSO::IDumontDataSet::vt [get, set]

Get/Set a (Text) FieldValue based on its VarName.


The documentation for this interface was generated from the following file:




~ ~ ~ ~ ~ ~
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