DumontEXE 0.0.1
cmcRowSet.h
00001 /* ***************************************************************************
00002 **
00003 ** Copyright (C) 2007 Lorimark Solutions, LLC. All rights reserved.
00004 **
00005 ** This file is part of the DumontEXE Scripting Extension Kit
00006 **
00007 ** This file may be used under the terms of the GNU General Public
00008 ** License version 2.0 as published by the Free Software Foundation
00009 ** and appearing in the file LICENSE.GPL included in the packaging of
00010 ** this file.  Please review the following information to ensure GNU
00011 ** General Public Licensing requirements will be met:
00012 ** http://dumont.showoff-db.org/opensource.html
00013 **
00014 ** If you are unsure which license is appropriate for your use, please
00015 ** review the following information:
00016 ** http://dumont.showoff-db.org/licensing.html 
00017 ** or contact the sales department at sales@lorimarksolutions.com.
00018 **
00019 ** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
00020 ** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
00021 **
00022 ** author: Mark Petryk ~ Lorimark Solutions, LLC
00023 ** **************************************************************************/
00024 
00025 #ifndef CDA_ROWSET_H_422FD07F_0597_4cbb_A034_9AE85166472E
00026 #define CDA_ROWSET_H_422FD07F_0597_4cbb_A034_9AE85166472E
00027 
00028 #include <QPointer>
00029 #include <QStringList>
00030 #include <QVariant>
00031 
00032 #include "cmcApi.h"
00033 
00034 namespace cmcDatabaseApi {
00035 
00036 class cmcCategoryDef;
00037 class cmcCursor;
00038 
00039 /*!
00040 ** \brief Rowset Base Class
00041 **
00042 **
00043 **
00044 */
00045 class cmcRowSet:
00046   public cmcApi
00047 {
00048   Q_OBJECT
00049   public:
00050 
00051     enum ERROR_CODES
00052     {
00053       NoError,
00054       RowRange,
00055       ColRange
00056     };
00057 
00058     /*!
00059     ** \brief Rowset Types \n
00060     **
00061     ** A row set object is designated as being of a particular single type.
00062     **
00063     ** You can query for these row types by requesting type() on the rowset
00064     **  or if you prefer a string version of the rowset type, you can call
00065     **  typeName() with the type value requested.
00066     **
00067     ** There are four rowset Types:
00068     **
00069     */
00070     enum ROWSET_TYPES
00071     {
00072       /*! 1 == Read-Only */
00073       RowSetQuery  = 1,
00074 
00075       /*! 2 == Add-Only */
00076       RowSetAdd    = 2,
00077 
00078       /*! 3 == Read-Only plus Delete */
00079       RowSetDelete = 3,
00080 
00081       /*! 4 == Read and Write existing */
00082       RowSetEdit   = 4
00083     };
00084 
00085     cmcRowSet( const cmcRowSet & copy );
00086 
00087     /*!
00088     ** \brief Standard Constructor \n
00089     **
00090     */
00091     cmcRowSet
00092     (
00093       /*!
00094       ** This is a cached copy of the rowCount.  It is cached here because
00095       **  the rowCount doesn't change after the rowset has been instantiated
00096       **  and there's no point in making unnecessary calls to the 
00097       **  Commence API.
00098       ** \n\n
00099       **
00100       */
00101       long rowCount,
00102 
00103       /*!
00104       ** This is a copy of the flags passed along by the initial request.
00105       ** \n\n
00106       **
00107       */
00108       long flags,
00109 
00110       /*!
00111       ** This is an optional name.  Normally it's the same name as the
00112       **  cursor that created it, but it can be overridden by the application,
00113       **  allowing rowsets to be named.
00114       ** \n\n
00115       **
00116       */
00117       const QString & name,
00118 
00119       /*!
00120       ** This provides the rowset type from the constructor subclass.
00121       ** \n\n
00122       **
00123       */
00124       long type,
00125 
00126       /*!
00127       ** This is a reference to the originating cursor.  The cursor object
00128       **  can die (be destroyed) before the rowset is destroyed, but this should
00129       **  be avoided since the rowset object makes reference back to the cursor
00130       **  for various bits of information during its lifetime.
00131       ** \n\n
00132       **
00133       */
00134       cmcCursor * cursor,
00135 
00136       /*!
00137       ** This is the dispatch pointer provided by the Commence application server.
00138       ** \n\n
00139       **
00140       */
00141       IDispatch * dispatch,
00142 
00143       /*!
00144       ** This is the parent.  Normally it's NULL and vbScript takes ownership
00145       **  of the object.
00146       ** \n\n
00147       **
00148       */
00149       QObject * parent = NULL 
00150 
00151     ); // endcmcRowSet
00152 
00153     virtual ~cmcRowSet();
00154 
00155   public slots:
00156 
00157     /*!
00158     ** \brief \b extended: Originating Cursor \n
00159     **
00160     ** This returns a pointer to the cursor object that created this RowSet object.
00161     **
00162     ** \note It is possible for the cursor object to be destroyed before this
00163     **  RowSet object gets destroyed, in which case this reference will return a
00164     **  NULL pointer.  You should test for a NULL pointer or at least make sure your
00165     **  code doesn't destroy the cursor if you plan to use it.
00166     **
00167     ** \return Originating Cursor object
00168     */
00169     virtual cmcCursor * cursor();
00170 
00171     /*!
00172     ** \brief \b extended: Category Definition \n
00173     **
00174     ** \return Category Defintion object
00175     */
00176     virtual cmcCategoryDef * categoryDef();
00177 
00178     /*!
00179     ** \brief \b extended \b alias: Category Name \n
00180     **
00181     ** This is a convenience function.  I can never remember if the function
00182     **  I should be calling to get the category name should be name() or
00183     **  category() or categoryName().  This clarifies it for me.  Anytime I'm 
00184     **  referring to the name of a category, I can use categoryName()
00185     **
00186     ** \return String value of Category Name
00187     */
00188     virtual QString categoryName();
00189 
00190     /*!
00191     ** \brief \b extended: RowSet Type Name \n
00192     **
00193     ** This function is used to convert a rowset-type-code into a string value.
00194     **  It is used when building the request for Commence since Commence requires
00195     **  a string-type request for the API.
00196     **
00197     ** \par vbScript Example ~ Making a RowSet Type String Message
00198     ** \code
00199     ** dexe.debug "Get" & rs.typeName(2) & "RowSetByID"
00200     ** ' result: "GetAddRowSetByID"
00201     ** \endcode
00202     **
00203     ** \note This is mostly an internal function
00204     **
00205     ** \sa ROWSET_TYPES, type
00206     **
00207     ** \return String value of RowSet Type
00208     */
00209     static QString typeName
00210     (
00211       long type
00212     );
00213 
00214     /*!
00215     ** \brief \b extended: RowSet Type Name \n
00216     **
00217     ** \sa ROWSET_TYPES, type
00218     **
00219     ** \return String value of current RowSet Type
00220     */
00221     QString typeName();
00222 
00223     /*!
00224     ** \brief \b extended: RowSet Type ID \n
00225     **
00226     ** This returns a type number for the type of RowSet object implemented here.
00227     **  This single RowSet class handles the interface for any one of the four
00228     **  rowset types and different functions are available depending on the type
00229     **  of rowset created.  This type variable determines that functionality.
00230     **
00231     ** \par vbScript Example ~ Reading the RowSet Type
00232     ** \code
00233     ** if( rs.type = 2 ) then
00234     **   dexe.debug "this is an ADD rowset"
00235     ** end if
00236     ** \endcode
00237     **
00238     ** \note This is mostly an internal function
00239     **
00240     ** \sa ROWSET_TYPES, typeName
00241     **
00242     ** \return Integer value of RowSet type
00243     */
00244     virtual long type();
00245 
00246     /*!
00247     ** \brief Rowset Row Count \n
00248     **
00249     ** The Row Count value returns the number of rows requested for this rowset
00250     **  object when it was requested.  This may not necessarily be the same number
00251     **  of rows that the hosting cursor contains.
00252     **
00253     ** \sa columnCount, colCount
00254     **
00255     ** \return Integer value of RowSet item count
00256     */
00257     virtual long rowCount();
00258 
00259     /*!
00260     ** \brief \b extended: Quick Row Range Test \n
00261     **
00262     ** This is a handy function for determining quickly if an index variable is
00263     **  within the row range of the rowset.
00264     **
00265     ** \sa colInRange, rowCount, columnCount, colCount
00266     **
00267     ** \return bool True if index value is within range
00268     */
00269     virtual bool rowInRange
00270     (
00271       /*! index value to be checked */
00272       long row
00273     );
00274 
00275     /*!
00276     ** \brief \b extended: Quick Column Range Test \n
00277     **
00278     ** This is a handy function for determining quickly if an index variable is
00279     **  within the column range of the rowset.
00280     **
00281     ** \sa rowInRange, rowCount, columnCount, colCount
00282     **
00283     ** \return bool True if index value is within range
00284     */
00285     virtual bool colInRange
00286     (
00287       /*! index value to be checked */
00288       long col
00289     );
00290 
00291     /*!
00292     ** \brief Rowset Column Count \n
00293     **
00294     ** The Column Count value returns the number of columns assigned to the cursor
00295     **  for this rowset.  If no columns have been specifically assigned, then this
00296     **  value represents all the designed fields and connections.
00297     **
00298     ** \sa colCount, rowCount
00299     **
00300     ** \return Integer value of RowSet column count
00301     */
00302     virtual long columnCount();
00303 
00304     /*!
00305     ** \brief \b alias: Rowset Column Count \n
00306     **
00307     ** This is just an alias for columnCount() because I like it when my source
00308     **  files all line up properly, and
00309     **
00310     ** \code
00311     ** dim rowCount: rowCount = rs.rowCount()
00312     ** dim colCount: colCount = rs.colCount()
00313     ** \endcode
00314     **
00315     ** Looks better than
00316     **
00317     ** \code
00318     ** dim rowCount: rowCount = rs.rowCount()
00319     ** dim columnCount: columnCount = rs.columnCount()
00320     ** \endcode
00321     **
00322     ** but, that's just me!
00323     **
00324     ** \sa columnCount, rowCount
00325     **
00326     ** \return Integer value of RowSet column count
00327     */
00328     virtual long colCount();
00329 
00330     /*!
00331     ** \brief Get Column Index \n
00332     **
00333     ** This gets the index number of the requested column.  If no matching column
00334     **  exists, a -1 is returned.
00335     **
00336     ** This function first looks to the originating cursor for the column index.
00337     **  If a specific list of columns has been defined for the cursor, then this
00338     **  column index function operates very quickly because it does not need to
00339     **  make calls into the Commence API to retrieve it.  If columns have not been
00340     **  defined for the cursor, then this function will look to its own cache
00341     **  to determine the index number.  If it cannot be found here, then finally
00342     **  it makes a call into the Commence API to retrieve that information.
00343     ** 
00344     ** Therefore, by definition, it makes sense to define columns for the cursors
00345     **  before using them in rowset queries and updates.
00346     **
00347     ** \sa getColumnLabel
00348     **
00349     ** \return Integer value of column index for label.  -1 if label could not 
00350     **          be found.
00351     */
00352     virtual long getColumnIndex
00353     (
00354       /*! name ~ text label of column \n\n */
00355       const QString & col,
00356 
00357       /*! unused ~ defaults to zero \n\n */
00358       long flags = 0
00359     );
00360 
00361     /*!
00362     ** \brief Get Column Label \n
00363     **
00364     ** This gets the label for a specific column.  If the column specified is out
00365     **  of range, then this function returns an empty string.
00366     **
00367     ** \sa getColumnIndex
00368     **
00369     ** \return String value of column label for requested index
00370     */
00371     virtual QString getColumnLabel
00372     (
00373       /*! index ~ column number \n\n */
00374       long col,
00375 
00376       /*! unused ~ defaults to zero \n\n */
00377       long flags = 0
00378     );
00379 
00380     /*!
00381     ** \brief
00382     **
00383     **
00384     */
00385     virtual QString getRowValue
00386     (
00387       long col
00388     );
00389 
00390     /*!
00391     ** \brief Get a Row Value (String) by column number \n
00392     **
00393     **
00394     ** \return String value of row and column
00395     */
00396     virtual QString getRowValue
00397     (
00398       /*! index ~ (firstRow <= row <= lastRow) \n\n */
00399       long row,
00400 
00401       /*! index ~ (firstCol <= col <= lastCol) \n\n */
00402       long col,
00403 
00404       /*! unused ~ defaults to zero \n\n */
00405       long flags = 0
00406     );
00407 
00408     /*!
00409     ** \brief
00410     **
00411     **
00412     */
00413     virtual QString getRowValue
00414     (
00415       const QString & col
00416     );
00417 
00418     /*!
00419     ** \brief \b extended: Get a Row Value (String) by column name \n
00420     **
00421     **
00422     ** \return String value of row and column
00423     */
00424     virtual QString getRowValue
00425     (
00426       /*! index ~ (firstRow <= row <= lastRow) \n\n */
00427       long row,
00428 
00429       /*! name ~ text label of column \n\n */
00430       const QString & col
00431     );
00432 
00433     /*!
00434     ** \brief Get a Row ID \n
00435     **
00436     **
00437     */
00438     virtual QString getRowID();
00439 
00440     /*!
00441     ** \brief Get a Row ID \n
00442     **
00443     ** In order for this function to work properly, the rowset MUST be opened
00444     **  in USE_THIDS mode.  If not, the results of this function are unpredictable.
00445     ** Refer to the secion \ref thids for more information.
00446     **
00447     ** \sa getRowGUID
00448     **
00449     ** \return String THID of row
00450     */
00451     virtual QString getRowID
00452     (
00453       /*! index ~ (firstRow <= row <= lastRow) \n\n */
00454       long row,
00455 
00456       /*! unused ~ defaults to zero \n\n */
00457       long flags = 0
00458     );
00459 
00460     /*!
00461     ** \brief Get the Row THID \n
00462     **
00463     **
00464     */
00465     virtual QString getRowTHID();
00466 
00467     /*!
00468     ** \brief Get Row ID Alias \n
00469     **
00470     **
00471     */
00472     virtual QString getRowTHID
00473     (
00474       long row
00475     );
00476 
00477     /*!
00478     ** \brief Get the Row GUID \n
00479     **
00480     **
00481     */
00482     QString getRowGUID();
00483 
00484     /*!
00485     ** \brief \b extended: Read a GUID from a row \n
00486     **
00487     ** In order for this function to work properly, the category must be GUID
00488     **  ready.  
00489     ** Refer to the secion \ref thids for more information.
00490     **
00491     ** \sa getRowID
00492     **
00493     ** \return String GUID of row
00494     **
00495     ** \todo get GUID values working
00496     */
00497     virtual QString getRowGUID
00498     (
00499       /*! index ~ (firstRow <= row <= lastRow) \n\n */
00500       long row
00501     );
00502 
00503     /*!
00504     ** \brief Get a Row String \n
00505     **
00506     **
00507     */
00508     virtual QString getRowString
00509     (
00510       long col
00511     );
00512 
00513     /*!
00514     ** \brief \b extended: Get a Row String by column number \n
00515     **
00516     **
00517     ** \return String value of row and column
00518     */
00519     virtual QString getRowString
00520     (
00521       /*! index ~ (firstRow <= row <= lastRow) \n\n */
00522       long row,
00523 
00524       /*! index ~ (firstCol <= col <= lastCol) \n\n */
00525       long col
00526     );
00527 
00528     /*!
00529     ** \brief Get the Row String by column number \n
00530     **
00531     **
00532     */
00533     virtual QString getRowString
00534     (
00535       const QString & col
00536     );
00537 
00538     /*!
00539     ** \brief \b extended: Get a Row String by column name \n
00540     **
00541     **
00542     ** \return String value of row and column
00543     */
00544     virtual QString getRowString
00545     (
00546       /*! index ~ (firstRow <= row <= lastRow) \n\n */
00547       long row,
00548 
00549       /*! name ~ text label of column \n\n */
00550       const QString & col
00551     );
00552 
00553     /*!
00554     ** \brief Get Default Row Boolean \n
00555     **
00556     ** This is a short-hand function that provides the default row.
00557     **
00558     ** \return bool ~ True/False of row and column
00559     */
00560     virtual bool getRowBool
00561     (
00562       /*! long ~ column number */
00563       long col
00564     );
00565 
00566     /*!
00567     ** \brief \b extended: Get a Row Boolean by column number \n
00568     **
00569     ** This reads a row value and converts it to a Boolean true/false.  This is an
00570     **  important function since, in Commence, there are about three different
00571     **  versions of True and False, depending on the object type that you are 
00572     **  reading.  One is TRUE/FALSE for cursors and rowsets, another is Yes/No for
00573     **  connections, and yet another is... well... something else.  I can't remember.
00574     **  This function makes uniform that user interface.
00575     **
00576     ** \sa \ref getRowBool(long,const QString &) "getRowBool( by column name )"
00577     **
00578     ** \return bool ~ True/False of row and column
00579     */
00580     virtual bool getRowBool
00581     (
00582       /*! index ~ (firstRow <= row <= lastRow) \n\n */
00583       long row,
00584 
00585       /*! index ~ (firstCol <= col <= lastCol) \n\n */
00586       long col
00587     );
00588 
00589     /*!
00590     ** \brief Get a Row Boolean \n
00591     **
00592     **
00593     */
00594     virtual bool getRowBool
00595     (
00596       const QString & col
00597     );
00598 
00599     /*!
00600     ** \brief \b extended: Get a Row Boolean by column name \n
00601     **
00602     ** This reads a row value and converts it to a Boolean true/false.  This is an
00603     **  important function since, in Commence, there are about three different
00604     **  versions of True and False, depending on the object type that you are 
00605     **  reading.  One is TRUE/FALSE for cursors and rowsets, another is Yes/No for
00606     **  connections, and yet another is... well... something else.  I can't remember.
00607     **  This function makes uniform that user interface.
00608     **
00609     ** \sa \ref getRowBool(long,long) "getRowBool( by column number )"
00610     **
00611     ** \return bool ~ True/False or row and column
00612     */
00613     virtual bool getRowBool
00614     (
00615       /*! index ~ (firstRow <= row <= lastRow) \n\n */
00616       long row,
00617 
00618       /*! name ~ text label of column \n\n */
00619       const QString & col
00620     );
00621 
00622     /*!
00623     ** \brief Get a Row Long \n
00624     **
00625     **
00626     */
00627     virtual long getRowLong
00628     (
00629       long col
00630     );
00631 
00632     /*!
00633     ** \brief \b extended: Get a Row Long by column number \n
00634     **
00635     **
00636     ** \return Integer value of row and column
00637     */
00638     virtual long getRowLong
00639     (
00640       /*! index ~ (firstRow <= row <= lastRow) \n\n */
00641       long row,
00642 
00643       /*! index ~ (firstCol <= col <= lastCol) \n\n */
00644       long col
00645     );
00646 
00647     /*!
00648     ** \brief Get a Row Long \n
00649     **
00650     **
00651     */
00652     virtual long getRowLong
00653     (
00654       const QString & col
00655     );
00656 
00657     /*!
00658     ** \brief \b extended: Get a Row Long by column name \n
00659     **
00660     **
00661     ** \return Integer value of row and column
00662     */
00663     virtual long getRowLong
00664     (
00665       /*! index ~ (firstRow <= row <= lastRow) \n\n */
00666       long row,
00667 
00668       /*! name ~ text label of column \n\n */
00669       const QString & col
00670     );
00671 
00672     /*!
00673     ** \brief Get a Row Var \n
00674     **
00675     **
00676     */
00677     virtual QString getRowVar
00678     (
00679       long col,
00680       const QString & field
00681     );
00682 
00683     /*!
00684     ** \brief Get Row Var \n
00685     **
00686     ** This gets a var value from a column
00687     **
00688     */
00689     virtual QString getRowVar
00690     (
00691       long row,
00692       long col,
00693       const QString & field
00694     );
00695 
00696     /*!
00697     ** \brief Get a Row Var \n
00698     **
00699     **
00700     */
00701     virtual QString getRowVar
00702     (
00703       const QString & col,
00704       const QString & field
00705     );
00706 
00707     /*!
00708     ** \brief Get a Row Var \n
00709     **
00710     **
00711     */
00712     virtual QString getRowVar
00713     (
00714       long row,
00715       const QString & col,
00716       const QString & field
00717     );
00718 
00719     /*!
00720     ** \brief Get a Var Value \n
00721     **
00722     **
00723     */
00724     virtual QString varValue
00725     (
00726       const QString & col,
00727       const QString & field
00728     );
00729 
00730     /*!
00731     ** \brief Get a Var Value \n
00732     **
00733     **
00734     */
00735     virtual QString varValue
00736     (
00737       long row,
00738       const QString & col,
00739       const QString & field
00740     );
00741 
00742     /*!
00743     ** \brief Get a Var Value \n
00744     **
00745     **
00746     */
00747     virtual QString varValue
00748     (
00749       long col,
00750       const QString & field
00751     );
00752 
00753     /*!
00754     ** \brief Get a Var Value \n
00755     **
00756     **
00757     */
00758     virtual QString varValue
00759     (
00760       long row,
00761       long col,
00762       const QString & field
00763     );
00764 
00765     /*!
00766     ** \brief This sets a GUID on a Row \n
00767     **
00768     */
00769     virtual QString setRowGUID
00770     (
00771       long row
00772     );
00773 
00774 
00775 
00776     /*!
00777     ** \brief Modify a Row String by column number \n
00778     **
00779     ** \note Calling this function from a rowset other than \ref RowSetAdd "Add"
00780     **  or \ref RowSetAdd "Edit" row set will generate an error.
00781     **
00782     ** \attention There appears to be a bug within Commence regarding this function.
00783     **  While it has been demonstrated as being possible to make a connection setting
00784     **  using this function, internally Commence appears to be generating an error-code
00785     **  result.  Flag options have been provided with this wrapper to override the
00786     **  regular error reporting, but I am still uncertain if this is an error within
00787     **  Commence (that it's generating an error on call) or if Commence is not suppose
00788     **  to be allowing connections to be made from the cursor.rowset.modifyRow function.
00789     **
00790     ** \par vbScript Example ~ Setting Related Columns
00791     ** \code
00792     ** cursor.setRelatedColumn "Attendee", "Contacts", "Contact Name"
00793     ** dim rs: set rs = cursor.getEditRowSet
00794     **
00795     ** '
00796     ** ' This resets all the assigned staff persons on the docket
00797     ** '
00798     ** dim i: for i = rs.firstRow to rs.lastRow
00799     **   rs.modifyRow i, 0, "" ' clear the connection
00800     **   dim j: for j = 0 To UBound(staff) - 1
00801     **     rs.modifyRow i, 0, staff(j), 2 ' note: (2) cmcRowSet override (hide errors)
00802     **   next
00803     ** next
00804     ** rs.commit
00805     ** \endcode
00806     **
00807     ** \par
00808     ** The preceeding code actually works, and it does not generate any errors, and
00809     **  the connections are reassigned as expected.  However, if the (2) cmcRowSet 
00810     **  override had not been applied the user would be looking at a handful of error
00811     **  messages.
00812     **
00813     ** \par
00814     ** Here is an example of the output of error codes the user would see if he did
00815     **  \b not override the error handling:
00816     **
00817     ** \par Error Messages when setting related columns
00818     ** \code
00819     ** FAILED(8000001f): modifyRow(category='Calendar', row=0, col=0 'Attendee Contacts Contact Name', buf='Tom', flags=0)
00820     ** FAILED(8000001f): modifyRow(category='Calendar', row=0, col=0 'Attendee Contacts Contact Name', buf='Dick', flags=0)
00821     ** FAILED(8000001f): modifyRow(category='Calendar', row=0, col=0 'Attendee Contacts Contact Name', buf='Harry', flags=0)
00822     ** FAILED(8000001f): modifyRow(category='Calendar', row=1, col=0 'Attendee Contacts Contact Name', buf='Tom', flags=0)
00823     ** FAILED(8000001f): modifyRow(category='Calendar', row=1, col=0 'Attendee Contacts Contact Name', buf='Dick', flags=0)
00824     ** FAILED(8000001f): modifyRow(category='Calendar', row=1, col=0 'Attendee Contacts Contact Name', buf='Harry', flags=0)
00825     ** \endcode
00826     **
00827     ** \par
00828     ** As it turns out, the "bug" can be attributed to opening the cursor in 
00829     **  USE_THIDS mode.  When opened in this mode, setting connections must be 
00830     **  performed using THID values rather than categoryKey values.
00831     **
00832     **
00833     ** \return Integer ~ 0 on success, -1 on error
00834     */
00835     virtual long modifyRow
00836     (
00837       /*! index ~ (firstRow <= row <= lastRow) \n\n */
00838       long row,
00839  
00840       /*! index ~ (firstCol <= col <= lastCol) \n\n */
00841       long col,
00842  
00843       /*! string value \n\n */
00844       const QString & value,
00845  
00846       /*! optional ~ defaults to zero.  \n
00847       **  \li flags=1 causes this function to check the current value
00848       **      of the row before applying the modification. \n
00849       **  \li flags=2 causes this function to ignore return error codes
00850       **      from Commence
00851       ** \n\n 
00852       */
00853       long flags = 0
00854     );
00855  
00856     /*!
00857     ** \brief \b extended: Modify a Row String by column name \n
00858     **
00859     ** \note Calling this function from a rowset other than \ref RowSetAdd "Add"
00860     **  or \ref RowSetEdit "Edit" row set will generate an error.
00861     **
00862     ** \return Integer ~ 0 on success, -1 on error
00863     */
00864     virtual long modifyRow
00865     (
00866       /*! index ~ (firstRow <= row <= lastRow) \n\n */
00867       long row,
00868  
00869       /*! name ~ text label of column \n\n */
00870       const QString & col,
00871  
00872       /*! string value */
00873       const QString & value,
00874 
00875       /*! optional ~ defaults to zero. */
00876       long flags = 0
00877     );
00878  
00879     /*
00880     ** These are simple overloaded functions identical to the main functions, so
00881     **  no documentation is provided for them since it would just clutter up the
00882     **  doc file.
00883     **
00884     */
00885     virtual long modifyRow( long row, long col, const char * value );
00886     virtual long modifyRow(           long col, const char * value )
00887     { return( modifyRow( currentSelection(), col, value ) ); }
00888 
00889     virtual long modifyRow( long row, const QString & col, const char * value );
00890     virtual long modifyRow(           const QString & col, const char * value )
00891     { return( modifyRow( currentSelection(), col, value ) ); }
00892 
00893 
00894     virtual long modifyRow( long row, long col, bool value );
00895     virtual long modifyRow(           long col, bool value )
00896     { return( modifyRow( currentSelection(), col, value ) ); }
00897 
00898 
00899     virtual long modifyRow( long row, const QString & col, bool value );
00900     virtual long modifyRow(           const QString & col, bool value )
00901     { return( modifyRow( currentSelection(), col, value ) ); }
00902 
00903 
00904     virtual long modifyRow( long row, long col, long value );
00905     virtual long modifyRow(           long col, long value )
00906     { return( modifyRow( currentSelection(), col, value ) ); }
00907 
00908 
00909     virtual long modifyRow( long row, const QString & col, long value );
00910     virtual long modifyRow(           const QString & col, long value )
00911     { return( modifyRow( currentSelection(), col, value ) ); }
00912 
00913 
00914     virtual long modifyRow( long row, long col, double value );
00915     virtual long modifyRow(           long col, double value )
00916     { return( modifyRow( currentSelection(), col, value ) ); }
00917 
00918 
00919     virtual long modifyRow( long row, const QString & col, double value );
00920     virtual long modifyRow(           const QString & col, double value )
00921     { return( modifyRow( currentSelection(), col, value ) ); }
00922 
00923 
00924     virtual long modifyRow( long row, long col, const QDateTime & value );
00925     virtual long modifyRow(           long col, const QDateTime & value )
00926     { return( modifyRow( currentSelection(), col, value ) ); }
00927 
00928 
00929     virtual long modifyRow( long row, const QString & col, const QDateTime & value );
00930     virtual long modifyRow(           const QString & col, const QDateTime & value )
00931     { return( modifyRow( currentSelection(), col, value ) ); }
00932 
00933 
00934     virtual long modifyVar( long row, long col, const QString & varField, const QString & newVar );
00935     virtual long modifyVar(           long col, const QString & varField, const QString & newVar )
00936     { return( modifyVar( currentSelection(), col, varField, newVar ) ); }
00937 
00938 
00939     virtual long modifyVar( long row, const QString & col, const QString & varField, const QString & newVar );
00940     virtual long modifyVar(           const QString & col, const QString & varField, const QString & newVar )
00941     { return( modifyVar( currentSelection(), col, varField, newVar ) ); }
00942 
00943     /*!
00944     ** \brief Delete a Row \n
00945     **
00946     **
00947     */
00948     virtual long deleteRow();
00949 
00950     /*!
00951     ** \brief Mark a row for deletion \n
00952     **
00953     ** This function doesn't actually delete a row, but only marks it for
00954     **  deletion.  You must call commit() in order to save the deleted items
00955     **  to disk.  The procedure for deleting rows is as follows:
00956     **
00957     ** \par vbScript Example ~ Deleting Rows
00958     ** \code
00959     ** dim cursor: set cursor = dapp.db.getCursor("Person")
00960     ** cursor.setColumn "personKey"
00961     ** cursor.setFilter "[ViewFilter(1,F,,deleteMe,True)]"
00962     ** dim rs: set rs = cursor.getDeleteRowSet
00963     ** dim i: for i = rs.firstRow to rs.lastRow
00964     **   if( rs.deleteRow(i) = -1 ) then
00965     **     dexe.debug "Unable to delete: " & rs.getRowString(i,"personKey")
00966     **   end if
00967     ** next
00968     ** rs.commit
00969     ** \endcode
00970     **
00971     ** \note Calling this function from anything other than a "Delete"
00972     **  row set will generate an error.
00973     **
00974     ** \sa commit
00975     **
00976     ** \return Integer ~ 0 on success, -1 on error
00977     */
00978     virtual long deleteRow
00979     (
00980       /*! index ~ (firstRow <= row <= lastRow) \n\n */
00981       long row,
00982 
00983       /*! unused ~ defaults to zero \n\n */
00984       long flags = 0
00985     );
00986 
00987     /*!
00988     ** \brief Commit the changes to the database \n
00989     **
00990     ** \note Calling this function from a Query row set
00991     **  will generate an error.
00992     **
00993     ** \return Integer ~ 0 on success, -1 on error
00994     */
00995     virtual long commit
00996     (
00997       /*! unused ~ defaults to zero \n\n */
00998       long flags = 0
00999     );
01000 
01001     /*!
01002     ** \brief Return the first row index \n
01003     **
01004     ** In Commence, some object collections use zero based indexes, and 
01005     **  some use one based indexes.  Why try to remember?  Use these functions
01006     **  instead.
01007     **
01008     ** \sa firstColumn, firstCol, lastRow, lastColumn, lastCol
01009     **
01010     ** \return 0 (zero) ~ rowset rows are zero based
01011     */
01012     virtual long firstRow() { return 0; }
01013 
01014     /*!
01015     ** \brief Return the first row index \n
01016     **
01017     ** In Commence, some object collections use zero based indexes, and 
01018     **  some use one based indexes.  Why try to remember?  Use these functions
01019     **  instead.
01020     **
01021     ** \sa firstCol, lastColumn, lastCol, firstRow, lastRow
01022     **
01023     ** \return 0 (zero) ~ rowset columns are zero based
01024     */
01025     virtual long firstColumn() { return 0; }
01026 
01027     /*!
01028     ** \brief Return the first row index \n
01029     **
01030     ** In Commence, some object collections use zero based indexes, and 
01031     **  some use one based indexes.  Why try to remember?  Use these functions
01032     **  instead.
01033     **
01034     ** \sa firstColumn, firstRow, lastColumn, lastCol, lastRow
01035     **
01036     ** \return 0 (zero) ~ rowset columns are zero based
01037     */
01038     virtual long firstCol() { return 0; }
01039 
01040     /*!
01041     ** \brief Return the last row index \n
01042     **
01043     ** This function returns the rowCount() - 1 value.  It is used to
01044     **  make for/next loops look a little cleaner:
01045     **
01046     ** \par vbScript Example ~ Using lastRow
01047     ** \code
01048     ** dim i: for i = rs.firstRow to rs.lastRow
01049     **   dexe.debug rs.getRowValue(i,0)
01050     ** next
01051     ** \endcode
01052     **
01053     ** \sa lastColumn, lastCol, firstRow, firstColumn, firstCol
01054     **
01055     ** \return rowCount() - 1
01056     */
01057     virtual long lastRow();
01058 
01059     /*!
01060     ** \brief Return the last column index \n
01061     **
01062     ** This function returns the columnCount() - 1 value.  It is used to
01063     **  make for/next loops look a little cleaner:
01064     **
01065     ** \par vbScript Example ~ Using lastColumn
01066     ** \code
01067     ** dim i: for i = rs.firstColumn to rs.lastColumn
01068     **   dexe.debug rs.getRowValue(0,i)
01069     ** next
01070     ** \endcode
01071     **
01072     ** \sa lastRow, lastCol, firstRow, firstColumn, firstCol
01073     **
01074     ** \return columnCount - 1
01075     */
01076     virtual long lastColumn();
01077 
01078     /*!
01079     ** \brief Return the last column index \n
01080     **
01081     ** This is an alias for lastColumn().
01082     **
01083     ** \par vbScript Example ~ Using lastCol
01084     ** \code
01085     ** dim i: for i = rs.firstCol to rs.lastCol
01086     **   dexe.debug rs.getRowValue(0,i)
01087     ** next
01088     ** \endcode
01089     **
01090     ** \sa lastRow, lasColumn, firstColumn, firstCol, firstRow
01091     **
01092     ** \return \ref lastColumn()
01093     */
01094     virtual long lastCol();
01095 
01096     /*!
01097     ** \brief True when the rowset is dirty (needs a commit) \n
01098     **
01099     ** \sa commit
01100     */
01101     virtual bool isDirty();
01102 
01103     /*!
01104     ** \brief Current Row Selection \n
01105     **
01106     **
01107     **
01108     */
01109     virtual long currentSelection();
01110     
01111     /*!
01112     ** \brief Set the current Row \n
01113     **
01114     **
01115     */
01116     virtual void currentSelection( long value );
01117 
01118     /*!
01119     ** \brief Make a row Shared \n
01120     **
01121     **
01122     */
01123     virtual bool setShared( long row );
01124 
01125     /*!
01126     ** \brief Set Time Stamp \n
01127     **
01128     ** This will set the Time Stamp fields on the row.  In order for this
01129     **  function to operate properly, the category must have a Var
01130     **  field available.
01131     **
01132     ** The timestamp fields appear on the item as follows:
01133     **
01134     ** \code
01135     ** guid={d3c8e674-84b9-4ce9-b960-15fb442248b1}
01136     ** cmcID=nothing
01137     ** createdOn=20101011170217
01138     ** createdBy=MWP
01139     ** changedOn=20101011173130
01140     ** changedBy=CWG
01141     ** \endcode
01142     **
01143     ** \note In order for this function to work properly, you must
01144     **  expose the var field in your rowset.
01145     **
01146     **
01147     */
01148     virtual bool setTimeStamp( long row );
01149 
01150     /*!
01151     ** \brief Get the Shared status of a Row \n
01152     **
01153     **
01154     */
01155     virtual bool getShared( long row );
01156 
01157   signals:
01158 
01159   protected:
01160 
01161   private:
01162 
01163     /*!
01164     ** \brief Category Name Cache \n
01165     **
01166     ** We cache the category name here because it is possible that the cursor
01167     **  might disappear on us while we are still in existance.
01168     **
01169     */
01170     QString m_categoryName;
01171 
01172     /*!
01173     ** \brief Originating Cursor Pointer \n
01174     **
01175     ** Maintain a reference to the cursor that created this object.  Note that
01176     **  we are using a QPointer to make this reference, causing the pointer to
01177     **  automatically cleared if the cursor object is destroyed.
01178     **
01179     */
01180     QPointer<cmcCursor> m_cursor;
01181 
01182     /*!
01183     ** \brief RowSet Flags \n
01184     **
01185     ** These flags were passed in on the constructor.  Not sure what they're for.
01186     **
01187     */
01188     long m_flags;
01189 
01190     /*!
01191     ** \brief Rowset Type \n
01192     **
01193     ** This type is set by the subclass (add, query, edit, delete) rowset.  Note
01194     **  that this is very un-object-oriented-like, for a base class to know about
01195     **  its derived classes, but we're talking about Commence here.
01196     **
01197     ** \sa ROWSET_TYPES
01198     */
01199     long m_type;
01200 
01201     /*!
01202     ** \brief RowCount Cache \n
01203     **
01204     ** This is a row count cache - since the rowCount doesn't change after
01205     **  the object has been instantiated.
01206     **
01207     ** \sa rowCount, rowInRange
01208     */
01209     long m_rowCount;
01210 
01211     /*!
01212     ** \brief Column Count Cache \n
01213     **
01214     ** This is a column count cache - since the colCount doesn't change after
01215     **  the object has been instantiated.
01216     **
01217     ** \sa columnCount, colCount, colInRange
01218     */
01219     long m_colCount;
01220 
01221     /*!
01222     ** \brief RowSet Dirty Indicator \n
01223     **
01224     ** This is true when the rowset goes dirty.  It goes dirty when
01225     **  something is written to one of the columns
01226     **
01227     */
01228     bool m_dirty;
01229 
01230     /*!
01231     ** \brief Column Name Map Cache \n
01232     **
01233     ** This records the column mapping.  It's purpose is to expedite the lookup
01234     **  of the column numbers.
01235     **
01236     */
01237     QHash<QString,long> m_columns;
01238 
01239     /*!
01240     ** \brief Current Row Selection \n
01241     **
01242     ** This emulates the currentSelection() function like what's on the
01243     **  Connection object.
01244     **
01245     */
01246     long m_currentSelection;
01247 
01248 }; // endclass cmcRowSet:
01249 
01250 } // namespace cmcDatabaseApi
01251 
01252 #endif // #ifndef CDA_ROWSET_H
01253 
 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