California Team Decision Making Application
(TDM CA)
TDM CA Upgrade Tool Version 2.3
(TDM Upgrader v.2.3)
User and Technical Guide for Access 2000/XP
August 2004
Contact:
Bill Dawson
CSSR, UCB
9
TDM CA User Guide: Contents
August 2004
TDM Upgrader v.2.3
User and Technical Guide for Access 2000/XP
Contents
Introduction
What is TDM Upgrader v.2.3? 2
What is TDM CA v.2.3? 2
Requirements for TDM Upgrader v.2.3 2
Upgrading Your Database
Set Up 3
Upgrade Procedure 4
Confirming the Upgrade 8
Messages, Errors, and Troubleshooting
Overview of Visual Basic for Applications (VBA) Code 9
Standard Messages 10
Error Messages 11
Error Numbers and Descriptions 12
Resetting For Another Attempt 12
Supplemental Topics
Determining Folder Permissions 16
Affected Objects and the 'Backup Objects?' Checkbox 16
9
TDM Upgrader v.2.3 User and Technical Guide
TDM Upgrader v.2.3
User and Technical Guide for Access 2000/XP
Introduction
What is TDM Upgrader v.2.3?
TDM Upgrader is a tool (a small MS Access database) that allows you to upgrade your existing TDM CA v.2.2 MS Access 2000/XP database or databases to v.2.3.
What is TDM CA v.2.3?
TDM CA v.2.3 adds an export feature to TDM CA. This feature allows you to send data you specify to MS Excel or text files. It also allows you to export data to a pre-specified MS Excel file for data exchange with UC Berkeley (UCB). This will allow UCB to assist in linking data in your TDM database with data in the CWS/CMS archive at UCB.
For more information about the export feature and v.2.3 of TDM CA in general, see the v.2.3 User and Technical guides at:
http://cssr.berkeley.edu/tdm/
Details of the data exchange process and outcome reporting will follow by mid-October, 2004.
Requirements for TDM Upgrader v.2.3
The upgrade tool should work on customized versions of TDM CA v.2.2 (i.e., versions of the database that have been modified by your county) as long as the following conditions exist in your target database:
· The table ‘tblVersionInfo’ exists, has not been structurally altered, and the maximum version is 2.2
· The table ‘tblLUPAttendee’ exists and contains the field ‘AttendeeLabel’.
· The query ‘qryVersionInfo_max’ exists and has not had fields deleted or renamed.
It is unlikely that these objects will have been altered unless your county has made extensive modifications to the database.
The export tool, installed by the Upgrader, requires certain additional conditions to function properly. Please see the Technical Guide for details.
You can use the tool to upgrade more than one copy of TDM CA for MS Access 2000/XP.
If you are using an earlier version than v.2.2, you should download the full v.2.3 database and import data. TDM CA v.2.3 is available for download in a zipped or unzipped format on the TDM support website at:
http://cssr.berkeley.edu/tdm/
The TDM CA User Guide provides information about importing data from a prior version of TDM.
Upgrading Your Database
Set Up
Have all users close out of the TDM database. Confirm that the folder permissions allow you to ‘Modify’ or have ‘Full Control’ of the folder in which the TDM database resides (see ‘Supplemental Topics: Determining Folder Permissions’ for details). Copy the TDM Upgrader (‘TDM_Upgrader_2_3.mdb’) to the folder that contains your TDM database. In this case the database to be upgraded is called ‘TDM_2.2.mdb’. As in this example, there can be additional files in the folder.
Upgrade Procedure
Begin the procedure by double-clicking (or otherwise opening) the TDM Upgrader. The database will open and display the Upgrade form as follows:
It provides the following options:
1. Enter TDM Database Name:
…
Name:
[textbox] / Enter the name of the TDM database you want to upgrade. In this example, the name ‘TDM_2.2’ has been entered by the user. You can enter the ‘.mdb’ extension (e.g., ‘TDM_2.2.mdb’), but it is not required.
2. Feature(s) to install:
[listbox] / Select the feature or features you wish to install as part of the upgrade. With TDM Upgrader 2.3, there is only one feature, ‘Export’, which should be pre-selected. If it is not, select the ‘Export’ item.
3. Indicate backup preferences:
Backup objects?
[check box] / If you check the box, objects that will be replaced by the Upgrader are first backed up as [Object Name]_[mmddyy] in your database. If you have customized the particular objects that will be affected by the upgrade, you may wish to check the box. For details, see “Supplemental Topics: Affected Objects and the ‘Backup Objects?’ Checkbox” below.
4. Upgrade:
Upgrade to v.2.3
[button] / Click the button to initiate the upgrade procedure.
After clicking the button ‘Upgrade v.2.3’, the mouse pointer will switch to an hour glass.
If you are upgrading a version of the database that has not been initialized for data entry, you may briefly see the 'Welcome to TDM Application' form. Do not click on this form; it will close on its own.
If the upgrade completes without error, a confirmation message will appear:
Click ‘OK’.
Then, click the ‘Close’ button. A message box will confirm that you want to exit the TDM Upgrader.
Click ‘Yes’.
[If an error occurs during the upgrade procedure, you will see an error message. See “Messages, Errors, and Troubleshooting” below.]
Your target database, in this case 'TDM_2.2.mdb', has been upgraded to v.2.3. The folder containing your database will also have a new object, a backup of your database as it was before the upgrade, in this example, ‘TDM_2.2_072704_backup.mdb’:
As suggested by the confirmation message, the name of the target database should be changed from ‘TDM_2.2.mdb’ to ‘TDM_2_3.mdb’ to reflect the upgrade to v.2.3:
Confirming the Upgrade
To confirm the upgrade, open the renamed target database, in this example, ‘TDM_2_3.mdb’. The bottom left corner should indicate the version number as 2.3. In addition, you should observe a new button at the bottom right position on the main part of the form, ‘Export Data’. To further confirm the upgrade, you may want to consult the User Guide and test the new export functions.
Messages, Errors, and Troubleshooting
Overview of Visual Basic for Applications (VBA) Code
The main component of the TDM Upgrader is Visual Basic for Applications (VBA) code, which performs the upgrade procedure. This code is stored in the module ‘mdlUpgrade’, which is organized as follows:
Sub Procedure / Phase / FunctionsubUpgradeCtl / 1 / Call other sub procedures
Handle errors
subParam / 2 / Confirm user parameters
subExist / 3 / Confirm existence of TDM database specified for upgrade (target database)
subVersion / 4 / Confirm target database is correct version
subBackupDB / 5 / a) Backup target database
b) Create copy of TDM Upgrader for use in upgrade procedure
subBackupInstall / 6 / In target database:
a) Backup objects (if indicated by user)
b) Delete existing objects
c) Install new and replacement objects
subUpdateVer / 7 / Update the version number of the target database
subDeleteSrc / 8 / Delete copy of TDM Upgrader
subConfirm / 9 / Generate confirmation message
Standard Messages
Phase / Function / Specific Message / ExplanationRecommended Action(s)
1 / Call sub procedures
Handle errors / TDM Upgrader
The field ‘tblUpgrade.Destination’ cannot contain a Null value because the required property for this field is set to True. Enter a value in this field. / The TDM Upgrader has not found anything in the ‘Name’ textbox.
Enter the name of the target database you wish to upgrade (e.g., ‘TDM_2.2’).
3 / Confirm existence of TDM database specified for upgrade (target database) / Cannot locate TDM database
The TDM Upgrader is unable to locate the specified TDM database for upgrade.
Please confirm database name: [Database Name]
Also confirm that TDM database is located
in the same folder as this TDM Upgrader:
[Directory Path] / The TDM Upgrader cannot locate a MS Access database with the name you’ve entered.
1. Check that the database name entered in the ‘Name’
textbox is exactly the same as the name of the database you wish to upgrade. If not, modify the database name and try again.
2. Confirm that the TDM Upgrader and the database you wish to upgrade are in the same folder.
9 / Generate confirmation message / Upgrade Complete
Congratulations! Upgrade complete.
IMPORTANT: If your filename includes the version number, e.g.,
'TDM_2.2.mdb',
you should update the filename, e.g.,
'TDM_2_3.mdb'. / All upgrade operations have been completed without error.
As suggested by the message, if applicable, the name of the target database should be changed from (for example) ‘TDM_2.2.mdb’ to ‘TDM_2_3.mdb’ to reflect the upgrade to v.2.3.
N/A / [Click ‘Close’ button] / Exit TDM Upgrader?
Do you want to exit the TDM Upgrader & MS Access?
Click 'Yes' to exit.
Click 'No' to return to the Upgrader. / You have clicked the ‘Close’ button on the TDM Upgrader form. If you wish to exit, click ‘Yes’. If you inadvertently clicked ‘Close’, click ‘No’ to return to the TDM Upgrader form.
Error Messages
Errors will generate messages of the general form:
"Sorry, unable to complete upgrade
Error number [#] [TDM Upgrader Message]:
[Description]
Upgrade has terminated.
Please make a note of this message and refer to documentation
for possible sources of error and/or next steps
or contact technical support.
Click 'OK' to return to form."
[#] will be a MS Access or TDM Upgrader generated error number.
[Description] will be a MS Access or TDM Upgrader generated error description.
[TDM Upgrader Message] will indicate the phase and function of the upgrade in which the error occurred as follows:
Phase / Function / TDM Upgrader Message1 / Call sub procedures
Handle errors / …while initializing upgrade procedures…
2 / Confirm user parameters / …while getting upgrade parameters…
3 / Confirm existence of TDM database specified for upgrade (target database) / …while checking for existence of specified database…
4 / Confirm target database is correct version / …while determining version number of specified database…
5 / a) Backup target database
b) Create copy of TDM Upgrader for use in upgrade procedure / a)…while backing up specified database…
b)…while creating temporary copy of Upgrader…
6 / In target database:
a) Backup objects (if indicated by user)
b) Delete existing objects
c) Install new and replacement objects / a)…while backing up objects in specified database…
b)…while deleting objects in specified database…
c)…while installing objects in specified database…
7 / Update the version number of the target database / …while updating version information in specified database…
8 / Delete copy of TDM Upgrader / …while deleting temporary copy of Upgrader…
9 / Generate confirmation message / …while confirming completion of upgrade procedure…
Error Numbers and Descriptions
Recommended Action
600 / TDM Upgrader application error: Minimum DB version >= Release DB version / Error in TDM Upgrader. Data in ‘tblLUPUpgrade’ is incorrect. /
Record error message and contact UCB for technical support.
601 / TDM database specified for upgrade is version [version #]
Minimum version required for upgrade is version 2.2. / The TDM database specified for upgrade is a version prior to v.2.2. /
Install v.2.3, customize, and import data.
602 / TDM database specified for upgrade is already version 2.3.
This Upgrader upgrades to version 2.3. / The TDM database has already been upgraded /
No action required. However, if export feature is not available, contact UCB for technical support
Resetting For Another Attempt
If you receive an error number and description other than those listed above, it is a MS Access generated error. This may be the result of you or another user having the database open, insufficient folder permissions, modifications to the target database, or other causes. The MS Access error description may give you adequate information to determine the source of the problem.
In some cases, you will want to correct the problem—for example (if the problem was that another user had the database open) by closing all instances of the target database—and try again.
If so, make note of the phase in which the error occurred.
In this example, the error occurred “while deleting objects in specified database”.
According to the table in ‘Error Messages’ above, this indicates that the error occurred in phase 6 (part b: delete existing objects).
In cases where an error occurred during or after phase 5, you should take the following steps before trying to upgrade again. (These steps return your files to the state they were in before you initiated the first upgrade.)
Once you have corrected the suspected source of the error:
(1) Close all instances of MS Access (i.e. all open windows).
(2) In Windows Explorer, confirm the presence of the backup database: ‘[Your Database Name]_[mmddyy]_backup.mdb’.
In this example, the backup database, ‘TDM_2.2_081804_backup.mdb’ is present and the correct approximate size (i.e., same size as original target database).
(3) If the backup is present, delete the target database. It may have been altered by the partial upgrade.
If you receive an error message, indicating a sharing violation, when you attempt to delete the database (see below), open and close the database, then delete.
(4) Rename the backup database with the name of the original target database.