California Team Decision Making Application
(TDM CA)
TDM CA Upgrade Tool Version 2.5
(TDM Upgrader v.2.5)
User and Technical Guide for Access 2000/XP
April 2005
Contacts:
Bill Dawson
Anne Abramson
CSSR, UCB
17
TDM CA User Guide: Contents
April 2005
TDM Upgrader v.2.5
User and Technical Guide for Access 2000/XP
Contents
Introduction
What is TDM Upgrader v.2.5? 2
What is TDM CA v.2.5? 2
Requirements for TDM Upgrader v.2.5 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
17
TDM Upgrader v.2.5 User and Technical Guide
TDM Upgrader v.2.5
User and Technical Guide for Access 2000/XP
Introduction
What is TDM Upgrader v.2.5?
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. It also allows you to upgrade your existing v.2.3 or v.2.4 database to v.2.5. (It allows you, therefore, to upgrade from v.2.2 to v.2.5 in a two-step process.)
This document focuses on the upgrade from v.2.3 and v.2.4 to v.2.5. Examples are based on an upgrade from v.2.4 to v.2.5; steps for upgrade from v.2.3 to v.2.5 are the same. For details, including screen captures of the upgrade from v.2.2 to v.2.3 please see “TDM Upgrader v.2.3: User and Technical Guide” available on the archived section of the TDM support website at:
http://cssr.berkeley.edu/tdm/archivedTDM.asp
What is TDM CA v.2.5?
TDM CA v.2.5 adds new reports (to v.2.3) or modifies existing reports (in v.2.4) in TDM CA. These reports provide all necessary information for completion of the TDM CA Quarterly Report and also allow you to produce reports for other time periods, meeting locations, etc. as needed. V.2.5 also modifies the v.2.3 ‘Reports’ form to allow you to print multiple reports in a single reporting session. Finally, v.2.5 corrects an error in the v.2.4 version of the Location Report, improves the validation code for the Export Form, and changes the defaults for the Custom Export.
For more information about the reporting features and v.2.5 of TDM CA in general, see the TDM CA v.2.5 User and Technical guides at:
http://cssr.berkeley.edu/tdm/
Requirements for TDM Upgrader v.2.5
The upgrade tool should work on customized versions of TDM CA v.2.3 or v.2.4 (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.3 or 2.4.
· 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.
You can use the tool to upgrade more than one copy of TDM CA for MS Access 2000/XP, although you can only upgrade one copy at a time.
If you are using an earlier version than v.2.2, you should download the full v.2.5 database and import data. TDM CA v.2.5 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_5.mdb’) to the folder that contains your TDM database. In this case the database to be upgraded is called ‘TDM_2_4.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_4’ has been entered by the user. You can enter the ‘.mdb’ extension (e.g., ‘TDM_2_4.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.5, there are three features:
1. Export
2. Reports and Fixes
3. Fixes.
Select the appropriate upgrade given the version number of your current database. For example, if you are upgrading from v.2.4, you would select ‘Fixes’.
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
[button] / Click the button to initiate the selected upgrade procedure.
After clicking the button ‘Upgrade’, 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_4.mdb', has been upgraded to v.2.5. 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_4_040705_backup24.mdb’:
As suggested by the confirmation message, the name of the target database should be changed from ‘TDM_2_4.mdb’ to ‘TDM_2_5.mdb’ to reflect the upgrade to v.2.5:
Confirming the Upgrade
To confirm the upgrade, open the renamed target database, in this example, ‘TDM_2_5.mdb’. The bottom left corner should indicate the version number as 2.5. To further confirm the upgrade, you may want to re-run the Location Report and compare numbers against a version produced on v.2.4.
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_4’).
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_4.mdb',
you should update the filename, e.g.,
'TDM_2_5.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_4.mdb’ to ‘TDM_2_5.mdb’ to reflect the upgrade to v.2.5.
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/2.3/2.4]. / (1) If you are attempting to upgrade from v.2.2 to v.2.3, the TDM database specified for upgrade is a version prior to v.2.2.
Install v.2.5, customize, and import data.
(2) If you are attempting to upgrade from v.2.3 to v.2.5, the TDM database specified is a version prior to v.2.3; if attempting v.2.4 to v.2.5, specified database is prior to v.2.4.
(a) If v.2.2 or later, upgrade to v.2.5 using appropriate upgrade(s).
(b) If prior to v.2.2, install v.2.5, customize, and import data.
602 / TDM database specified for upgrade is already version 2.5.
This Upgrader upgrades to version 2.5. / The TDM database has already been upgraded /No action required. However, if reporting features are not modified or not functioning correctly, 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).
NOTE: This example is based on an upgrade from v.2.2 to v.2.3. If you encounter an error while upgrading from v.2.3 or v.2.4 to v.2.5, follow these same steps.
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’.