Quick Tip: Best Practice for Dexterity Version and Build Numbers
A common question that new Dexterity developers have is what should they use for the version and build numbers when creating a chunk dictionary for distribution. This post discusses how those numbers are used and what the best practice for setting their values is.
The following Knowledge Base (KB) article that I wrote discusses the steps to creating a chunk file for an integrating application (with or without alternate resources):
The last two stages into the chunking process using Dexterity Utilities are completing the Product Information window and the Auto Chunk window. For this post will have a look at these two windows and what to enter into each of the fields.
Product Information Window
The Dictionary field will have the currently opened Editable Dictionary which will be an extracted dictionary (with alternate resources transferred, if required). The Launch File field should contain DYNAMICS.SET, this is the default name for the Microsoft Dynamics GP launch file. The Launch ID for an integrating dictionary should be the Product ID for the main application dictionary, in our case this is DYNAMICS.DIC (Product ID: 0).
The Product Name is the name of your product that will appear in the launch file once the chunk file is installed. The Product ID is the unique dictionary number provided to you by Microsoft (this ensures that two developers do not use the same Product ID).
The Forms Dictionary and Reports Dictionary fields contain the filenames that will be used for the custom forms and reports dictionaries if the Modifier or Report Writer is used against this product. There are a number of naming conventions for these file names, one of the most popular is to include the Product ID in the name so that ensure it will not clash with any other product's dictionaries.
The Compatibility ID field should be a unique string that identifies the version of your application. It only needs to change when you have made a change to the dictionary that will require any custom forms or reports to be updated. I would suggest that the Compatibility ID is at least updated with each Microsoft Dynamics GP release. The Compatibility Message is the message to display when the Compatibility ID in the application dictionary is different from the string already stored in the custom forms and reports dictionary to tell you to upgrade the dictionary.
Auto Chunk Window
The Current Dictionary contains the path for the open Editable Dictionary. The Chunk Dictionary field is used to define what the chunk file to be created should be called. The Dictionary field has the name of the dictionary that will be created/updated when the chunk file is extracted during installation.
The Module field was used to define different products such as Payables Management, General Ledger, etc. but is now just a numbered list. Historically, I used Module 051 which was Dexterity, but just using Module 001 is fine.
Note: Whatever Module number you use when creating the chunk file needs to be the same as the one used in your code if you use the Runtime_GetModuleInfo() function library command to retrieve your version information.
So now to the Version Information fields, Major Version, Minor Version and Build Number. The best practice for this numbers is to match the Major Version and Minor Version numbers to match the version numbers for Microsoft Dynamics GP, such as 10.0 and 11.0 (GP 2010). The build number can then be incremented to signify your application's build number (starting back at 1 for each GP version). When displaying the product information in your product, format the version number to XX.XX.XXXX format. For example: 11.00.0015.
The code sample below shows how to format the version number to this layout:
local integer l_maj_ver, l_min_ver, l_build_number;
local string l_version;
l_maj_ver = Runtime_GetModuleInfo(Runtime_GetCurrentProductID(), 51, l_min_ver, l_build_number); { If using Module 051 }
l_version = str(l_maj_ver)+CH_PERIOD+pad(str(l_min_ver), LEADING, CH_0, 2)+CH_PERIOD+pad(str(l_build_number), LEADING, CH_0, 4);
One important point is mentioned in the Dexterity Utilities Help:
If the installation folder contains a dictionary for which the major and minor version numbers match those of the dictionary chunk, the build number will be examined. If the build number of the chunk is the same or greater than the build number of the dictionary, the chunk will be unchunked. If the build number of the chunk is lower, it will not be unchunked, and a message indicating the issue will be written to the InstallErrors.txt file in the installation folder.
In summary, to be able to install your chunk over the top of an existing dictionary, you must match the Major Version and Minor Version numbers and the Build Number must be equal or higher to the previously install dictionary. Otherwise you will have to delete the dictionary before your chunk will extract.
The Installation Scripts fields are used to define global procedures in your dictionary which can be run before or after the chunking process. Remember that with a SQL database, you cannot access data until after login, so these scripts should not access any tables. You can set a value in the Dex.ini, which can be checked after login to see if this is a new installation or update.
Finally, the Compression Settings. Usually, developers will use Total Compression which strips out the source code to leave only the executable compiled code. However, there are times when using Remove Unused Blocks to leave the source code in the dictionary is good option. Below are a couple of reasons to use Remove Unused Blocks:
- If working on cross dictionary code, or code that needs to be tested in a runtime environment, leaving the source allows the debugging tools to work with source (assumes Dexterity Option: Compile with Debug Information is selected). You can change to Total Compression when you are ready to release the code.
- If creating a customization specifically for a customer and the customer owns the code, leaving the source in the dictionary means that even if the source code dictionaries are lost, you can recreate a development dictionary from the chunk file or the installed dictionary.
That's all folks. Hope this is helpful.
David
18-Nov-2011: Change code example so that it was not looking for a 'Version' string field on the current window.