DumontEXE 0.0.1
Public Slots
cmcConversation Class Reference

DDE Conversation. More...

#include <cmcConversation.h>

Inheritance diagram for cmcConversation:

List of all members.

Public Slots

bool addItem (const QString &categoryName, const QString &itemName, const QString &itemClarify="")
 Add an Item
.
bool addSharedItem (const QString &categoryName, const QString &itemName)
 Add a Shared Item
.
bool appendText (const QString &categoryName, const QString &itemName, const QString &fieldName, const QString &appendText)
 Append Text to a field
.
bool assignConnection (const QString &fromCategory, const QString &fromItem, const QString &connectionName, const QString &toCategory, const QString &toItem)
 Assign a connection
.
bool checkInFormScript (const QString &categoryName, const QString &formName, const QString &fileName)
 Check a script into a form
.
bool checkOutFormScript (const QString &categoryName, const QString &formName, const QString &fileName)
 Check a script out of a form
.
void clarifyItemNames (const bool status)
 Set the Clarify Item Names status
.
bool clarifyItemNames ()
 Return Clarified Item Name Status
.
QString databases ()
 Return a database list
.
bool deleteItem (const QString &categoryName, const QString &itemName)
 Delete an Item
.
bool deleteView (const QString &viewName)
 Delete a View
.
bool editItem (const QString &categoryName, const QString &itemName, const QString &fieldName, const QString &fieldValue)
 Edit an Item
.
bool execute (const QString &cmd)
 Execute a DDE command
.
bool fireTrigger (const QString &trigger, const QString &arg2="", const QString &arg3="", const QString &arg4="", const QString &arg5="", const QString &arg6="", const QString &arg7="", const QString &arg8="", const QString &arg9="")
 Fire an Agent Trigger
.
QString formats ()
 Return Clipboard Formats
.
QString getActiveViewInfo (const QString &delimiter="\r\n")
 Return to Active View Info
.
QString getCallerID (const QString &categoryName, const QString &phoneNumber, const QString &delimiter="\r\n")
 Return Caller ID
.
long getCategoryCount ()
 Get Category Count
.
QString getCategoryDefinition (const QString &categoryName, const QString &delimiter="\r\n")
 Get Category Definition
.
QString getCategoryNames (const QString &delimiter="\r\n")
 Get Category Names
.
long getConnectedItemCount (const QString &fromCategory, const QString &fromItem, const QString &connectionName, const QString &toCategory, const QString &delimiter="\r\n")
 Get Connected Item Count
.
QString getConnectedItemField (const QString &fromCategory, const QString &fromItem, const QString &connectionName, const QString &toCategory, const QString &toFieldName, const QString &delimiter="\r\n")
 Get a Category List
.
QString getConnectedItemNames (const QString &fromCategory, const QString &fromItem, const QString &connectionName, const QString &toCategory, const QString &delimiter="\r\n")
 Get Connected Item Names
.
QString getConnectionNames (const QString &categoryName, const QString &delimiter="\r\n", const QString &conCatdelimiter=CONCAT_DELIMITER)
 Get Connection Names
.
QString getDatabase (const QString &delimiter="\r\n")
 Get Database
.
QString getDatabaseDefinition (const QString &delimiter="\r\n")
 Get Database Definition
.
long getDesktopCount ()
 Get Desktop Count
.
QString getDesktopNames (const QString &delimiter="\r\n")
 Get Desktop Names
.
QString getField (const QString &categoryName, const QString &itemName, const QString &fieldName)
 Get Field
.
long getFieldCount (const QString &categoryName)
 Get Field Count
.
QString getFieldDefinition (const QString &categoryName, const QString &fieldName)
 Get Field Definition
.
QString getFieldNames (const QString &categoryName)
 Get Field Names
.
bool getFieldToFile (const QString &categoryName, const QString &itemName, const QString &fieldName, const QString &fileName)
 Get Field to File
.
long getFormCount (const QString &categoryName)
 Get Form Count
.
QString getFormNames (const QString &categoryName)
 Get Form Names
.
QString getMeField (const QString &fieldName)
 Get Me Field value
.
QString getPreference (const QString &setting)
 Get Preference Setting
.
QString getViewNames (const QString &categoryName)
 Get View Names
.
QString request (const QString &req)
 DDE Request
.
bool showItem (const QString &categoryName="", const QString &itemName="", const QString &formName="")
 Show Item
.
bool showView (const QString &viewName, bool reopen=false)
 Show View
.
bool viewCategory (const QString &categoryName)
 View Category
.
bool viewFilter (const QString &filter)
 View Filter
.
long viewItemCount ()
 View Item Count
.
bool viewMarkItem (long index)
 View Mark Item
.

Detailed Description

DDE Conversation.

Definition at line 39 of file cmcConversation.h.


Member Function Documentation

bool addItem ( const QString &  categoryName,
const QString &  itemName,
const QString &  itemClarify = "" 
) [slot]

Add an Item
.

This function adds an item to a category.

Note:
Care should be taken to insure that the category can accept a new item. This is the responsibility of the programmer. No action is taken on the part of this function to determine if the category can be written to, or the potential pitfalls therein. For instance it may be possible to write to a category, but if that category has special permissions appied to it, and if the (-me-) connection is not properly assigned, you could potentially have an item in a category that you can neither write to nor delete.
Attention:
If the Category has mandatory fields, those fields must be filled in with subsequent editItem commands. Use the getFieldDefinition request to determine which fields are mandatory. Unpredictable results may follow if mandatory fields are left unfilled.
vbScript Example
 dim dexe: set dexe = createObject("Dumont.EXE") ' hook dumont
 dim dapp: set dapp = dexe.applications("DB1")   ' fetch an app by the its aliasName

 if( not dapp.cv.addItem("Person", "Smith, John (""sparky"")") ) then
   msgbox "Hmm, problem here"
   exit sub
 end if
See also:
addSharedItem
Returns:
bool ~ false on error
Parameters:
categoryNamesee: Category Name

itemNamesee: Item Name Field

itemClarifysee: Item Clarify Field. (optional)

Definition at line 135 of file cmcConversation.cpp.

bool addSharedItem ( const QString &  categoryName,
const QString &  itemName 
) [slot]

Add a Shared Item
.

Identical in function to addItem except that it creates a shared item, provided that the database is connected and the category is shared. Otherwise a local item is created.

Attention:
If the Category has mandatory fields, those fields must be filled in with subsequent editItem commands. Use the getFieldDefinition request to determine which fields are mandatory. Unpredictable results may follow if mandatory fields are left unfilled.
See also:
addItem
Returns:
bool ~ false on error
Parameters:
categoryNamesee: Category Name

itemNamesee: Item Name Field

Definition at line 151 of file cmcConversation.cpp.

bool appendText ( const QString &  categoryName,
const QString &  itemName,
const QString &  fieldName,
const QString &  appendText 
) [slot]

Append Text to a field
.

Appends Text to an existing text Field. Use this command to overcome the 256 character maximum string limitation of certain macro languages (such as WordBasic). Whenever possible, use a clarified item name.

Returns:
bool ~ false on error
Parameters:
categoryNamesee: Category Name

itemNamesee: Item Name Field

fieldNamesee: Field Name

appendTextText to append to the field

Definition at line 165 of file cmcConversation.cpp.

bool assignConnection ( const QString &  fromCategory,
const QString &  fromItem,
const QString &  connectionName,
const QString &  toCategory,
const QString &  toItem 
) [slot]

Assign a connection
.

Assign a connection between the two indicated Items via Connection. Whenever possible, use a Clarified Item Name.

Returns:
bool ~ false on error
Parameters:
fromCategorysee: Category Name

fromItemsee: Item Name Field

connectionNamesee: Connection Name

toCategorysee: Category Name

toItemsee: Item Name Field

Definition at line 183 of file cmcConversation.cpp.

bool checkInFormScript ( const QString &  categoryName,
const QString &  formName,
const QString &  fileName 
) [slot]

Check a script into a form
.

Updates the named detail form with the VBScript in the specified Filename. Only text (.txt) format files are currently supported. Filename must be a fully qualified path including the drive letter (e.g. c:\tmp\script.txt).

See also:
cmcApplication::loadDefs
Returns:
bool ~ false on error
Parameters:
categoryNamesee: Category Name

formNamesee: Form Name

fileNamesee: Field Name

Definition at line 203 of file cmcConversation.cpp.

bool checkOutFormScript ( const QString &  categoryName,
const QString &  formName,
const QString &  fileName 
) [slot]

Check a script out of a form
.

Saves the VBScript associated with a particular detail form, FormName, to the named file, Filename. Only text (.txt) format files are currently supported. Filename must be a fully qualified path including the drive letter (e.g. c:\tmp\script.txt).

See also:
cmcApplication::loadDefs
Returns:
bool ~ false on error
Parameters:
categoryNamesee: Category Name

formNamesee: Form Name

fileNamesee: Field Name

Definition at line 219 of file cmcConversation.cpp.

void clarifyItemNames ( const bool  status) [slot]

Set the Clarify Item Names status
.

Tells Commence if clarified item names should be returned.

See also:
Clarified Item Names
Returns:
bool ~ false on error
Parameters:
statusStatus Flag true/false

If Status is "True", Commence will always return clarified item names (if the category has a clarify field defined). If Status is "False", non-clarified item names are returned. The default is "False".

Definition at line 235 of file cmcConversation.cpp.

bool clarifyItemNames ( ) [slot]

Return Clarified Item Name Status
.

See also:
Clarified Item Names
Returns:
bool ~ true if clarified item names is turned on

Definition at line 246 of file cmcConversation.cpp.

QString databases ( ) [slot]

Return a database list
.

Note:
Use the getDatabase request to determine the currently active database.
Returns:
List of Commence databases. The list is of the form: {Database Name 1}TAB{Database Path 1}CR/LF{Database Name 2}TAB{Database Path 2}CR/LF... CR/LF{Database Name n}TAB{Database Path n}

Definition at line 254 of file cmcConversation.cpp.

bool deleteItem ( const QString &  categoryName,
const QString &  itemName 
) [slot]

Delete an Item
.

Deletes the indicated Item from the Category. Once an item is deleted, it cannot be recovered. Whenever possible, use a clarified item name..

Returns:
bool ~ false if the item could not be deleted
Parameters:
categoryNamesee: Category Name

itemNamesee: Item Name Field

Definition at line 260 of file cmcConversation.cpp.

bool deleteView ( const QString &  viewName) [slot]

Delete a View
.

This command deletes the saved view.

Returns:
bool ~ false if the view could not be deleted
Parameters:
viewNamesee: View Name

Definition at line 274 of file cmcConversation.cpp.

bool editItem ( const QString &  categoryName,
const QString &  itemName,
const QString &  fieldName,
const QString &  fieldValue 
) [slot]

Edit an Item
.

Sets the value of Field to Value for the item identified by Item in Category. Field must not specify a Calculation field. Date fields may not specify a range, (e.g., "every day"). Whenever possible, use a clarified Item name.

If Field is an image field, Value must specify the filename containing the image. The filename must be a fully qualified path including the drive letter. The specified .bmp file is pasted into the image field. Only .BMP format image fields are currently supported. For example:

 if( not cv.editItem("Person", "Doe, John", "Snapshot", "c:\image\photo.bmp") ) then
   dexe.debug "problem editing photo into item"
 end if
Returns:
bool ~ false if the item could not be edited
Parameters:
categoryNamesee: Category Name

itemNamesee: Item Name Field

fieldNamesee: Field Name

fieldValueNew Field Value overwrites the existing field value

Definition at line 286 of file cmcConversation.cpp.

bool execute ( const QString &  cmd) [slot]

Execute a DDE command
.

Returns:
false if the execute call did not succeed
Parameters:
cmdDDE command string

Definition at line 73 of file cmcConversation.cpp.

bool fireTrigger ( const QString &  trigger,
const QString &  arg2 = "",
const QString &  arg3 = "",
const QString &  arg4 = "",
const QString &  arg5 = "",
const QString &  arg6 = "",
const QString &  arg7 = "",
const QString &  arg8 = "",
const QString &  arg9 = "" 
) [slot]

Fire an Agent Trigger
.

This command fires the indicated Agent Trigger.

You can pass arguments to be used by the agent actions. The arguments passed via a DDE trigger are accessible using the following keyword strings: (-0-), (-1-), (-2-), (-3-), (-4-), (-5-), (-6-), (-7-), (-8-), and (-9-). These keyword strings may be used to display the passed arguments using a message box or status bar action, to set values in an Add or Edit Item action or any other place that keyword replacement is allowed in agents. The following example illustrates how the DDE trigger arguments are mapped to keywords.

  [FireTrigger(TrigStr, Arg2, Arg3, Arg4, Arg5, Arg6, Arg7, Arg8, Arg9)]
    (-0-) = Always FireTrigger
    (-1-) = Trigger String, e.g., TrigStr
    (-2-) through (-9-) = The string passed in that position, e.g., Arg2
    through Arg9 respectively.
Returns:
bool ~ false on error
Parameters:
triggerTrigger Name

arg2Argument values arg2..arg9

arg3optional argument ~ string
arg4optional argument ~ string
arg5optional argument ~ string
arg6optional argument ~ string
arg7optional argument ~ string
arg8optional argument ~ string
arg9optional argument ~ string

Definition at line 304 of file cmcConversation.cpp.

QString formats ( ) [slot]

Return Clipboard Formats
.

Returns:
A tab-delimited list of clipboard formats supported by Commence for DDE.

Definition at line 330 of file cmcConversation.cpp.

QString getActiveViewInfo ( const QString &  delimiter = "\r\n") [slot]

Return to Active View Info
.

Returns:
Information about the currently active view. The return string is of the form: {ViewName}Delim {ViewType}Delim {CategoryName}Delim {ItemName}Delim {FieldName} {ViewType} can be any one of the following:

Book Calendar Gantt Chart Report Item Detail

{FieldName} is only valid if the active child window is an item detail. Note that a getField on an active item detail will only retrieve the previous field value (before the edit). Until an item is saved, there is no way to retrieve updated field values.

Note:
If the optional Delim parameter is not specified, the returned list is delimited with CR/LF (ASCII codes 13 and 10). The Delim parameter can be any string (up to 8 characters).
Parameters:
delimiterdelimiter (optional)

Definition at line 335 of file cmcConversation.cpp.

QString getCallerID ( const QString &  categoryName,
const QString &  phoneNumber,
const QString &  delimiter = "\r\n" 
) [slot]

Return Caller ID
.

Returns:
list of all items in the Category having the given phone number in a phone field.

If Category is blank, this function searches all categories in the currently active database. The phone number may be given in a variety of formats. Some examples of valid phone values are:

 1(800)CALLNOW
 415-555-1212
 123
Note:
If the optional Delim parameter is not specified, the returned list is delimited with CR/LF (ASCII codes 13 and 10). The Delim parameter can be any string (up to 8 characters).
Parameters:
categoryNamesee: Category Name

phoneNumberformatted phone number

delimiterdelimiter (optional)

Definition at line 345 of file cmcConversation.cpp.

long getCategoryCount ( ) [slot]

Get Category Count
.

Returns:
long ~ number of categories in the system

Definition at line 360 of file cmcConversation.cpp.

QString getCategoryDefinition ( const QString &  categoryName,
const QString &  delimiter = "\r\n" 
) [slot]

Get Category Definition
.

Returns:
String ~ delimited text of Category Definition
Parameters:
categoryNamesee: Category Name

delimiterdelimiter (optional)

Definition at line 366 of file cmcConversation.cpp.

QString getCategoryNames ( const QString &  delimiter = "\r\n") [slot]

Get Category Names
.

Returns:
String ~ Delimited string of category names
Parameters:
delimiteroptional ~ defaults to vbCrLf

Definition at line 380 of file cmcConversation.cpp.

long getConnectedItemCount ( const QString &  fromCategory,
const QString &  fromItem,
const QString &  connectionName,
const QString &  toCategory,
const QString &  delimiter = "\r\n" 
) [slot]

Get Connected Item Count
.

Returns:
long ~ Number of Connected items
Parameters:
fromCategorysee: Category Name

fromItemsee: Item Name Field

connectionNamesee: Connection Name

toCategorysee: Category Name

delimiterdelimiter (optional)

Definition at line 388 of file cmcConversation.cpp.

QString getConnectedItemField ( const QString &  fromCategory,
const QString &  fromItem,
const QString &  connectionName,
const QString &  toCategory,
const QString &  toFieldName,
const QString &  delimiter = "\r\n" 
) [slot]

Get a Category List
.

Returns:
String ~ Delimited string of category names
Parameters:
fromCategorysee: Category Name

fromItemsee: Item Name Field

connectionNamesee: Connection Name

toCategorysee: Category Name

toFieldNamesee: Field Name

delimiterdelimiter (optional)

Definition at line 409 of file cmcConversation.cpp.

QString getConnectedItemNames ( const QString &  fromCategory,
const QString &  fromItem,
const QString &  connectionName,
const QString &  toCategory,
const QString &  delimiter = "\r\n" 
) [slot]

Get Connected Item Names
.

Returns:
Parameters:
fromCategorysee: Category Name

fromItemsee: Item Name Field

connectionNamesee: Connection Name

toCategorysee: Category Name

delimiterdelimiter (optional)

Definition at line 431 of file cmcConversation.cpp.

QString getConnectionNames ( const QString &  categoryName,
const QString &  delimiter = "\r\n",
const QString &  conCatdelimiter = CONCAT_DELIMITER 
) [slot]

Get Connection Names
.

Returns:
A list of all connections where the named Commence category is the From category.

The list is of the form:

  • {Connection 1}ConnCatDelim {ToCategory 1}Delim
  • {Connection 2}ConnCatDelim {ToCategory 2}Delim...Delim
  • {Connection n}ConnCatDelim
  • {ToCategory n}

where {Connection n} is the name of the nth connection and {ToCategory n} is the name of the To category for the nth connection.

Note:
If the optional delimiter parameters are not specified, the returned list is delimited with CR/LF (ASCII codes 13 and 10). The Delim parameter can be any string (up to 8 characters). If the optional connCatDelim parameter is not specified, the connection names and their To categories are delimited with " -> ". The ConnCatDelim parameter can be any string (up to 8 characters).
 vbScript Example
 dim dexe: set dexe = createObject("Dumont.EXE") ' open dumont
 dim dapp: set dapp = dexe.applications("KES")   ' fetch a database by its alias name

 '
 ' Pull the connection names out.  You should have an array of 
 '  connection names, each of the "conName -> toCatName" format.
 '
 dim conDefs: set conDefs = Array( dapp.cv.getConnectionNames("Calendar"), vbCrLf )
Parameters:
categoryNamesee: Category Name

delimiterItem delimiter. This is usually vbCrLf.

conCatdelimiterConnection Category Delimiter. This delimiter defaults to " -> " in the cmcDatabaseApi package. You can override this when making your queries, however, this delimiter was chosen because it was assumed that this string would be fairly reliably unique... in otherwords, some developers encode special attributes in their connection/cat names so as to be able to quickly distinguish a field name from a connection name. The cmcDatabaseApi doesn't do that, but it may turn out that on some databases, the cmcDatabaseApi approach may conflict with some existing connection name encoding methods (such as if that developer already included a "->" in their connection name directly... that would be a big problem, probably).

Definition at line 451 of file cmcConversation.cpp.

QString getDatabase ( const QString &  delimiter = "\r\n") [slot]

Get Database
.

Returns:
Parameters:
delimiterdelimiter (optional)

Definition at line 467 of file cmcConversation.cpp.

QString getDatabaseDefinition ( const QString &  delimiter = "\r\n") [slot]

Get Database Definition
.

Returns:
Parameters:
delimiterdelimiter (optional)

Definition at line 479 of file cmcConversation.cpp.

long getDesktopCount ( ) [slot]

Get Desktop Count
.

Returns:

Definition at line 490 of file cmcConversation.cpp.

QString getDesktopNames ( const QString &  delimiter = "\r\n") [slot]

Get Desktop Names
.

Returns:
Parameters:
delimiterdelimiter (optional)

Definition at line 496 of file cmcConversation.cpp.

QString getField ( const QString &  categoryName,
const QString &  itemName,
const QString &  fieldName 
) [slot]

Get Field
.

Returns:
Parameters:
categoryNamesee: Category Name

itemNamesee: Item Name Field

fieldNamesee: Field Name

Definition at line 508 of file cmcConversation.cpp.

long getFieldCount ( const QString &  categoryName) [slot]

Get Field Count
.

Returns:
Parameters:
categoryNamesee: Category Name

Definition at line 524 of file cmcConversation.cpp.

QString getFieldDefinition ( const QString &  categoryName,
const QString &  fieldName 
) [slot]

Get Field Definition
.

Returns:
Parameters:
categoryNamesee Category Name

fieldNamesee: Field Name

Definition at line 532 of file cmcConversation.cpp.

QString getFieldNames ( const QString &  categoryName) [slot]

Get Field Names
.

Returns:
Parameters:
categoryNamesee Category Name

Definition at line 546 of file cmcConversation.cpp.

bool getFieldToFile ( const QString &  categoryName,
const QString &  itemName,
const QString &  fieldName,
const QString &  fileName 
) [slot]

Get Field to File
.

Returns:
Parameters:
categoryNamesee: Category Name

itemNamesee: Item Name Field

fieldNamesee: Field Name

fileNamefilename ~ string

Definition at line 558 of file cmcConversation.cpp.

long getFormCount ( const QString &  categoryName) [slot]

Get Form Count
.

Returns:
Parameters:
categoryNamesee: Category Name

Definition at line 575 of file cmcConversation.cpp.

QString getFormNames ( const QString &  categoryName) [slot]

Get Form Names
.

Returns:
Parameters:
categoryNamesee Category Name

Definition at line 588 of file cmcConversation.cpp.

QString getMeField ( const QString &  fieldName) [slot]

Get Me Field value
.

Returns:

Definition at line 615 of file cmcConversation.cpp.

QString getPreference ( const QString &  setting) [slot]

Get Preference Setting
.

Returns some Commence preferences setting (from Customize-Preferences). Valid Settings are:

  • "Me" Returns the Category and Item Name of the selected Me item (delimited by CR/LF). For example, "Person{Delim}Doe,John"
  • "ExternalDir" Returns the full path of the Commence external data file directory. For example, "c:\commence\data\files".
  • "LetterLogDir" Returns the full path of the Commence letter Log directory. For example, "c:\commence\letters".
Parameters:
settingPreference setting to retrieve

Definition at line 627 of file cmcConversation.cpp.

QString getViewNames ( const QString &  categoryName) [slot]

Get View Names
.

Parameters:
categoryNamestring ~ view name

Definition at line 639 of file cmcConversation.cpp.

QString request ( const QString &  req) [slot]

DDE Request
.

Send a dde request string

Returns:
String list of Response
Parameters:
reqRequest String

Definition at line 56 of file cmcConversation.cpp.

bool showItem ( const QString &  categoryName = "",
const QString &  itemName = "",
const QString &  formName = "" 
) [slot]

Show Item
.

[ShowItem(Category, Item, Form)]

Parameters:
categoryNamestring ~ Category Name

itemNamestring ~ Item Name

formNamestring ~ (optional) Form Name

Definition at line 651 of file cmcConversation.cpp.

bool showView ( const QString &  viewName,
bool  reopen = false 
) [slot]

Show View
.

[ShowView(View Name, 1)]

Definition at line 672 of file cmcConversation.cpp.

bool viewCategory ( const QString &  categoryName) [slot]

View Category
.

[ViewCategory(Category)]

Definition at line 688 of file cmcConversation.cpp.

bool viewFilter ( const QString &  filter) [slot]

View Filter
.

[ViewFilter(ClauseNumber, FilterType, NotFlag, FieldTypeParameters...)]

Definition at line 702 of file cmcConversation.cpp.

long viewItemCount ( ) [slot]

View Item Count
.

[ViewItemCount()]

Definition at line 715 of file cmcConversation.cpp.

bool viewMarkItem ( long  index) [slot]

View Mark Item
.

[ViewMarkItem(Index)]

Definition at line 722 of file cmcConversation.cpp.


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




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