DumontEXE 0.0.1
Clarified Item Names

What is a clarified item name?

A Clarified Item Name refers to a method of identifying an item in a category that allows for duplicate items. Since categories have only one key field, and this key field is a text field of 50 characters, it is most common to set the value of this field to some value that represents the "key" of the item. This is fine for Company names or Class codes or Invoice numbers where duplications can be controlled, but what about things like peoples names, where "Smith, John" and "Smith, John" are likely to occur more than once in a large database?

Enter the: "Clarified Item Name"

If a category allows duplicates, that category can be assigned a clarify field. The clarify field is another field in that category that can act like a clarification of an item. For instance, say your "Person" category allows duplicates, and you have "Smith, John" and "Smith, John" occurring in your database. If you set another field as a clarify field and call this field "Nickname" then you would be able to distinguish one "Smith, John" from the other by setting one Nickname field value to "Smitty" and another to "Johnny". When searching for this item, then, you could use a "Clarified Item Name" as part of your search.

What is a Clarified Item Name?

A Clarified Item name is an assembly of the category Name field and Clarify field and Clarify Separator. The Clarify field is limited to 40 characters. This does not mean that you can only use a clarify field that is only 40 characters, rather Commence will only examine the first 40 characters of your clarify field. Let's say your category is laid out as follows:

 Category      ~ "Person"
 Name Field    ~ "Full Name"
 Clarify Field ~ "Nickname"
 Clarify Sep   ~ " - "

If you are then looking for "Smith, John" with a nickname of "Smitty" you would then assemble a "Clarified Item Name" value as follows:

 dim pd: pd = "                                                  " ' 50 spaces (not 50 paces)
 dim fn: fn  = "Smith, John" ' first name
 dim nn: nn  = "Smitty"      ' nick name
 dim sp: sp  = " - "         ' separator

 dim cn:  cn = Left( fn & pd, 50 ) & sp & Left( nn, 40 )

Note that in the code above you have to pad the 'Name' field to exactly 50 characters. This tiny little tidbit of valuable information is not located anywhere in the documentation that I have come across as of yet. If you're just now reading this document you're probably asking yourself why you just spent three days troubleshooting why using clarified item names doesn't work for you. Beats me, but finally you're here.

In the code above I have also trimmed the clarify field to 40 characters. This is probably not necessary but I do it anyway.

If so desired you can set your clarify field to Memo fields (really long fields) and Commence will still only use the first 40 characters. A good practice then is when you have a category that allows for duplicate items then create a special clarify field and fill it with a value that you are sure is not going to repeat. Then regardless of what the 'Name' field value is, you'll always be guaranteed to be able to find (and connect to) the correct item.

So... therefore... if you were formatting a DDE request, using the DDE [AssignConnection()] command, you might format a string that looks something like the following:

 dim pd:  pd   = "                                                  " ' 50 spaces (not 50 paces)
 dim fn:  fn   = "Smith, John" ' first name
 dim nn1: nn1  = "Smitty"      ' 1st nick name
 dim nn2: nn2  = "Johnny"      ' 2nd nick name
 dim sp: sp    = " - "         ' separator

 dim cn1:  cn1 = Left( fn & pd, 50 ) & sp & Left( nn1, 40 )
 dim cn2:  cn2 = Left( fn & pd, 50 ) & sp & Left( nn2, 40 )

 ' build a connection string.  Note that the 'dq' command is a sub-routine
 '  that will double-quote a string.
 dim conString
     conString = "[AssignConnection(Person," & dq(cn1) & ",Friends with,Person," & dq(cn2) & "]"

 ' Using Dumont, send the dde commands to assign the connection.  Make sure
 '  ClarifyItemNames is True before sending the assignment command.  Note
 '  that this call needs to only be made once per session (each time the
 '  .exe is run) so you might place the call is some seldom used chunk
 '  of code like in an application initialization routine, or at the top
 '  of your form or .vbs program so it doesn't get called repeatedly 
 '  unnecessarily.
 dapp.cv.execute "[ClarifyItemNames(True)]"
 dapp.cv.execute conString

Note, however, that none of this works if your category is not set up to use clarified items. In order to insure that it is you can change the category properties and specify the field that you indend to use as a clarify field, and at the same time, choose a clarify separator as well:

Something to remember about Dumont and the DDE channel... if you are using either the DumontDLL or the DumontEXE environment, note that Dumont will open a DDE channel back to Commence and keep it open throughout the life of the Commence.exe program (specifically the life of the dumont.dll or dumont.exe program, if you will). This is done mostly for speed, since opening and closing DDE channels takes time.
In this environment, therefore, you would only need to specify [ClarifyItemNames(True)] one time and it will, pretty much, stay enabled as long as the dumont.dll or dumont.exe stays loaded. If you are not using the Dumont extension libraries in your project, and accessing Commence the usual ways, through the regular Commence API, then if you are, say, performing DDE functions inside a detail form, you would be opening a new DDE channel to Commence everytime that form opened newly. In this environment you would have to execute [ClarifyItemNames(True)] each time your detail form opened, and a new DDE channel was opened.
If you are employing clarified item names, but you are forgetting to set [ClarifyItemNames(True)], or if you are not attempting to employ clarified item names, but you have also not set [ClarifyItemNames(False)] then you will be in for some confusing days.
Because of the strangeness of this "feature" of Commence, it would probably be a good idea for you to do some serious expirimenting to see what kinds of results are produced under what conditions, and then write your code accordingly.
'nuff said!
 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
~ ~ ~ ~ ~ ~
Author: Mark Petryk
Lorimark Solutions, LLC