DumontEXE 0.0.1
Classes | Functions | Variables
cmcDatabaseApi Namespace Reference

Commence Database API Namespace. More...

Classes

class  cmcActiveViewInfo
 Active View Information. More...
class  cmcApi
 Commence COM Interface. More...
class  cmcApplication
 Commence Application object. More...
class  cmcApplications
 This is the Commence Running Applications Table. More...
class  cmcApplicationsModel
 Applications Model. More...
class  cmcCategoryDef
 Category Definition. More...
class  cmcCategoryDefs
 Category Definitions. More...
class  cmcCategoryModel
 Category Model. More...
class  cmcCategoryModelItem
 Category Model Item. More...
class  cmcCda
 Commence Database API. More...
class  cmcCdaItem
 Commence CDA Item. More...
class  cmcConnection
 Connection. More...
class  cmcConnectionDef
 Connection Definition. More...
class  cmcConnectionDefs
 Commence Connection Collection. More...
class  cmcConversation
 DDE Conversation. More...
class  cmcCursor
 Cursor Object Wrapper. More...
class  cmcCursors
 Category Definitions. More...
class  cmcDatabase
 Commence Database Object. More...
class  cmcError
 Cmc Error Object. More...
class  cmcField
 Field. More...
class  cmcFieldDef
 Field Definition. More...
class  cmcFieldDefs
 Field Def Collection. More...
class  cmcForm
 Form
. More...
class  cmcFormDef
 Form Definition. More...
class  cmcFormDefs
 Form Definition Collection. More...
class  cmcFormField
 Form Field. More...
class  cmcForms
 Form Collection. More...
class  cmcFormScript
 Form Script
. More...
class  cmcItem
 Commence Item. More...
class  cmcItemField
 Form Field. More...
class  cmcItems
 Commence Items. More...
class  cmcMeInfo
 (-Me-) Information More...
class  cmcObject
 Commence Base Object. More...
class  cmcObjectNode
 Make Reference to a Commence object. More...
class  cmcObjects
 Collection Manager. More...
class  cmcPersist
 Cmc Persistence Object. More...
class  cmcQueue
 Process Queue. More...
class  cmcRowSet
 Rowset Base Class. More...
class  cmcStringList
 Cmc StringList Object. More...
class  cmcSubField
 Extended Field. More...
class  cmcSyncProxy
 Synchronization Proxy. More...
class  cmcTreeModel
 Tree Model. More...
class  cmcViewDef
 View Definition. More...
class  cmcViewDefs
 Form Definition Collection. More...

Functions

QString className (QObject *object)
 Class Name without the namespace.
QString dateTimeStamp (const QDateTime &dateTime, long length)

Variables

int m_tracDepth = 0
 Run-time trace depth.
int m_tracLevel = 0
 Requested Trace Level (higher value == more messages)

Detailed Description

Commence Database API Namespace.

This namespace contains all the objects that are used to interface to and manage the application through the COM interface API.

cmc Database Api Parent/Child Relationships
dot_inline_dotgraph_3.png

As you are perusing through these files, you will come across objects that look remarkably like regular Commence objects. This was an intentional part of the Dumont design - to create a bunch of objects that look just like regular Commence objects, but that also have additional (aka; extended) features. The regular Commence look-alike functions have no special notation on them. However, the extended functions do. And, while there are several extended functions, some of them are preferred. The alias functions simply replicate the same functionality as another function, but with a slightly different syntax. See the following for more explanation:

extended:
Some functions are marked as "extended" functions. Extended functions are new functions that do not exist in the current Commence cursor object, but are provide by the Dumont program. These functions extend the normal capabilities of the Commence API, usually resulting in an improvement.
preferred:
Some functions are marked as "preferred" functions. Preferred functions are functions that have many similar versions, but one or two of them are the preferred-use functions, and should be used when trying to decide which function to call. Take, for instance, the setColumn functions. There is a handful of various versions of these functions. Some are provided as aliases of existing functions, and others are truly new implementations that greatly simplify the application script. These preferred functions should be considered first when choosing a design implementation.
alias:
Some functions are marked as "alias" functions. Alias functions are functions that are completely identical to some other function, but are provided for program API consistency. A good example is the colCount() alias function. This function is identical in every way to its columnCount() counterpart, and is only provided to help with script readability because colCount() has a tendancy to line up nicely with rowCount() when they're used together. Other alias functions are simply easier to look at since they are less wordy.
General Improvements
Let me just give a brief example of what some of the improvements to the Commence API that we're talking about here. Below is a chunk of code that was implemented to assemble a formatted address for a client. The format for the address depended on the "Address Type" selected by the user, and the address type came from a client->Address list, meaning that a single client could have many addresses associated with his profile. The trick is to decide what addresses are available, and format something that looks like an address lable properly. Dumont made this procedure really really simple:
 ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' 
 '
 ' This function takes a client name and formats an address for him.
 '  It employs an AddressType specifier that can determine which address
 '  to choose from by priority.  The 'AddressType' is based upon the 
 '  category 'Address Type'.
 '
 ' If just the client name is given, then the address is taken from
 '  the primary address fields on the 'Contacts' item.  If an AddressType
 '  is included, then this procedure will parse through the address list
 '  of extended addresses from the 'Address' category.
 ' 
 ' The Flags field determines what content is returned by the query.
 '  .T. ~ turns on the AddressType designation.  This is prepended to
 '         the top of the address field to aid in address identification
 '
 '  .F. ~ turns on the field names.  Each field name is prepended to each
 '         address line (not working yet).
 '
 Function FormatContactAddress( ByVal ContactName, ByVal AddressType, ByVal Flags )
 
   '
   ' Default to a blank address
   '
   FormatContactAddress = "~no address on file~"
 
   '
   ' Get a contact item that matches the name
   '
   dim ContactItem
   set ContactItem = dapp.db.getItem( "Contacts", ContactName )
 
   '
   ' Check the result of the query.  We should never call this routine
   '  with a bad contact name, but just in case...
   '
   if( not ContactItem.Cursor.RowCount = 1 ) then _
     MsgBox "Bad Row Count " & ContactItem.Cursor.RowCount & " for " & ContactName
 
   '
   ' Get a string list for formatting the resulting
   '  address field.
   '
   dim addressInfo
   set addressInfo = dapp.getStringList
 
   '
   ' If the address type was specified then assume he's referring to
   '  one of the sub-addresses and try to find a match for that.  You can
   '  find a list of address sub-types in the "Address Type" category.
   '
   if( AddressType <> "" ) then
 
     '
     ' Get the address items for this contact
     '
     dim addressItems
     set addressItems = ContactItem.con("has","Address","for")
 
     '
     ' Filter for the particular address type we're looking for
     '
     addressItems.cursor.filter "2,CTI,,is an,Address Type," & AddressType
 
     '
     ' If we found one address item, then we can pull all the
     '  field data from it.
     '
     if( addressItems.count = 1 ) then
 
       dim addressItem
       set addressItem = addressItems.item(0)
 
       if( instr(Flags,"T") ) then _
         addressInfo.append "(" & AddressType & ")"
 
       if( ContactItem.extField("FileAs").value = "Person" ) then
         addressInfo.append ContactItem.field("Employed by Contacts").value
       end if
 
       addressInfo.append addressItem.field("Street").value
       addressInfo.append addressItem.field("City").value  & ", " & _
                          addressItem.field("State").value & "  " & _
                          addressItem.field("ZipPostal").value
 
       if( addressItem.field("Note").value <> "" ) then
         addressInfo.append "Note: " & _
         addressItem.field("Note").value
       end if
 
     end if
 
   end if
 
   '
   ' If the address info has no lines in it, then we were not able to
   '  find a match in the sub-address.  Assume then we are going to the
   '  primary address.
   '
   if( addressInfo.count = 0 ) then
 
     if( instr(Flags,"T") ) then _
       addressInfo.append "(Primary)"
 
     if( ContactItem.extField("FileAs").value = "Person" ) then
       addressInfo.append ContactItem.field("Employed by Contacts").value
     end if
 
     addressInfo.append ContactItem.field("Street Address").value
     addressInfo.append ContactItem.field("City").value  & ", " & _
                        ContactItem.field("State").value & "  " & _
                        ContactItem.field("Zip").value
 
   end if
 
   '
   ' Add the other fields to the address format
   '
   addressInfo.append ContactItem.field("Phone List").value
   addressInfo.append ContactItem.field("Business Email").value
   addressInfo.append ContactItem.field("License").value
 
   '
   ' If this address is being designated as a "bill-to" address,
   '  then make some extra effort to highlight that.
   '
   if( dfrm.field("Bill to").value = "1" ) then
     addressInfo.prepend "<< Bill to Address >>"
   end if
 
   '
   ' Format the whole address field into a single, crlf
   '  delimited string.
   '
   if( addressInfo.count > 0 ) then _
     FormatContactAddress = addressInfo.join
 
 End Function
 '
 ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' 

It may seem bulky at first glance, but this code worked out really well, and when in the middle of writing it, all I had to do was focus on the goal of what I was after, and not on the API interface to Commence, which can be somewhat distracting. This documentation makes working with and learning the Dumont API a breeze.

Give it a try!


Function Documentation

QString className ( QObject *  object)

Class Name without the namespace.

This is a global support function that strips off the namespace identifier from the class name. For instance, all of the CDA objects exist in the cmcDatabaseApi name space. This means that the class name for any of these objects in this system is going to be:

namespace examples
 cmcDatabaseApi::cmcObject      becomes cmcObject
 cmcDatabaseApi::cmcApplication becomes cmcApplication
 cmcDatabaseApi::cmcField       becomes cmcField

The purpose for this function is to extract the actual class name of the object for storage in the database definition extension xml file.

xml file example
 <cmcApplication name="KES.mwp" >
   <objectName type="static" >KES.mwp</objectName>
   <comment type="static" >KES Main Database</comment>
   <description type="static" ></description>
   <cmcCategoryDefs name="Categories" >
     <objectName type="static" >Categories</objectName>
     <comment type="static" ></comment>
     <description type="static" ></description>
     <documentation type="static" ></documentation>
     <cmcCategoryDef name="Activity" >

Definition at line 657 of file cmcObject.cpp.

QString dateTimeStamp ( const QDateTime &  dateTime,
long  length 
)

Note:
The Length parameter is automatically limited to 0 - 17.

Definition at line 669 of file cmcObject.cpp.


Variable Documentation

int m_tracDepth = 0

Run-time trace depth.

The TraceDepth represents the run-time module depth as the application is running. Various modules can increment the m_traceDepth at their discretion, and then should decrement the m_traceDepth at the end of their process path. The Trace Depth is compared against the requested TraceLevel (m_traceLevel), and if the requested trace level is greater than the current depth, a message is displayed.

Definition at line 450 of file cmcObject.cpp.

int m_tracLevel = 0

Requested Trace Level (higher value == more messages)

The TraceLevel is the requested trace level. This is initialized to zero, indicating no trace is requested. As the application runs, the m_traceDepth is incremented. If the m_traceLevel is higher then the current depth, then debug messages are sent to the appropriate console terminal.

Definition at line 462 of file cmcObject.cpp.

 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