Using Custom Database Properties in Application Development

Microsoft Corporation

July 1996

Overview

There are many acceptable ways to capture data in the information-gathering process of the various dialog boxes in a wizard and in custom applications that interact with the user. Many developers will use public variables to hold the selection, and then reference the variables in code as needed. Other techniques involve saving the data to tables or writing the output to an external file. One of the more powerful methods is to use custom database properties.

The benefits of this approach include:

• A visual dialog to create and manipulate entries.
  
  
• Static values that can be retrieved from any form.
  
  
• Easy implementation.
  
  
• Less memory usage.

This technique makes debugging and testing your custom wizards much easier because you can test any wizard dialog box as though you had stepped through the previous dialog boxes.

How to Create Custom Database Properties

Custom database properties are created using the Database Properties dialog box in Microsoft® Access:

1. Press F11 to bring focus to the Database window.
   
   
2. On the File menu, click Database Properties.
   
   
3. In the Database Properties dialog box, click the Custom tab.
   
   
4. Add your custom property.

Note   This article uses DBName as an example.

How to Return Custom Database Properties

The following function will return values from the custom database properties:

Function GetCustomProps(PropName As String) As Variant
   
  ' **********************************************
  ' Function: GetCustomProps
  '
  ' Purpose:
  ' Based upon the passed value, a variant
  ' is returned containing the requested
  ' custom property value.
  '
  '
  ' Returns: Boolean
  ' **********************************************
   
   On Local Error GoTo GetCustomProps_Err
   
   Dim db As DATABASE, prp As Property
   
   Set db = CodeDb
   Set prp = db.Containers(0).Documents("UserDefined").Properties(PropName)
   
   If IsNull(prp) Then
      
      ' A null value may break certain
      ' aspects of formulas used in the
      ' wizard and default values.
      GetCustomProps = False
   
   Else
   
      GetCustomProps = prp
   
   End If
GetCustomProps_End:
   
   Exit Function
GetCustomProps_Err:
   
   GetCustomProps = Err.Number
   Resume GetCustomProps_End
End Function

How to Modify Existing Values of Custom Properties

The following code will enable you to manipulate existing entries:

Function SetCustomProps(PropName As String, PropValue As Variant) As Boolean
   
  ' **********************************************
  ' Function: SetCustomProps
  '
  ' Purpose:
  ' Save the specified custom property and its
  ' associated value in the custom database
  ' property values.
  '
  '
  ' Returns: Boolean
  ' **********************************************
   
   On Local Error GoTo SetCustomProps_Err
   
   Dim db As DATABASE, prp As Property
   
   Set db = CodeDb
   Set prp = db.Containers(0).Documents("UserDefined").Properties(PropName)
   prp = PropValue
   
   SetCustomProps = True
SetCustomProps_End:
   
   Exit Function
SetCustomProps_Err:
   
   SetCustomProps = Err.Number
   Resume SetCustomProps_End
End Function

Setting Defaults Before Releasing Your Application

You should have a function dedicated to resetting your custom properties to default values before shipping your application or wizard. You never want an end user to see testing information or erroneous information the first time that the end user starts your application.

Note   The following example assumes that you have added a custom string property named DBName.

Sub SetDefaults()
   
   On Error Resume Next
   
   Dim Result As Integer
      
   ' Reset all custom wizard properties.
   Result = SetCustomProps("DBName", "N/A")
      
   MsgBox "All Properties Set to Defaults!", vbInformation, "YourAppName"
   
End Sub

Putting the Functions Together

The following piece of code saves the name of the database the user selected:

Note   The following example assumes that you have added a custom string property named DBName.

' Save the selected database name.
      Result = SetCustomProps("DBName", CStr(Me!MRU))
      If Not (Result = True) Then
         Msg = "There was an internal error in the wizards ability to save"
         Msg = Msg & " the 'DBName' option to the custom properties..." & vbCrLf & vbCrLf
         Msg = Msg & "Error# = " & Format$(Result)
         MsgBox Msg, vbInformation, "YourAppName"
      End If

Once the values are saved, they can be retrieved at any time. In the case of a wizard, the user may click the Back button to return to the previous dialog box. By adding the following code to the form's OnOpen event, you can retrieve the previous values easily:

If Len(OpenArgs) Then
      
      ' Existence of OpenArgs indicates that the wizard
      ' page is being accessed by the user returning
      ' to the page from a previous page.
      Me!txtDBName = GetCustomProps("DBName")
   
End If

The above code uses the existence of the OpenArgs value to act as a flag that another dialog box is returning to the page and that the values should be retrieved to reflect the user's previous selections.