Microsoft KB Archive Search

Notice: This website is an unofficial Microsoft Knowledge Base (hereinafter KB) archive and is intended to provide a reliable access to deleted content from Microsoft KB. All KB articles are owned by Microsoft Corporation. Read full disclaimer for more details.

  1. Home
  2. MOD2000: How to Start a Custom Help File in a Run-Time Solution

MOD2000: How to Start a Custom Help File in a Run-Time Solution

View products that this article applies to.

This article was previously published under Q243568
Advanced: Requires expert coding, interoperability, and multiuser skills.

↑ Back to the top

Symptoms

To include a custom context-sensitive Help file in a Microsoft Access 2000 run-time solution, you cannot just add the .chm or .hlp file to the package. You must also take some other steps to make context-sensitive Help work correctly in the distributed application. This article demonstrates what steps are required.

↑ Back to the top

Resolution

Obtain and install Microsoft Access 2000 Runtime SR-1, which is included on the Microsoft Office 2000 Developer SR-1 Fulfillment CD. To obtain the MOD SR-1 Fulfillment CD, click the article number below to view the article in the Microsoft Knowledge Base:
253566� MOD2000: How to Obtain and Install Microsoft Office 2000 Developer Service Release 1 (SR-1)
NOTE: Because it does not include Access 2000 Runtime SR-1, you cannot correct this problem with the downloadable Microsoft Office 2000 Developer SR-1 Update that is available on the Web. You must obtain the Fulfillment CD. Also, follow the instructions in article Q253566 about how to update Access Runtime.

After updating Access Runtime on the developer computer, you can package a solution with a context-sensitive Help file, and have it work successfully on the target computers. Please remember the following important points when you do this:
  • The Help file (.chm) must be in the same folder as the database file (.mdb). If you accept the default location when you add the Help file in the wizard, this is assured.
  • In the properties of the form on which you want context-sensitive Help, make sure the property Help File on the Other tab contains the name of your Help file. This should be just the name of the file, not a path.

Demonstration

To demonstrate packaging an Access 2000 SR-1 run-time solution with context-sensitive Help, first update to Access 2000 SR-1 Runtime, and then follow parts I, III, and IV of the steps below. Note that having Access 2000 SR-1 Runtime eliminates the steps in part II. If you do not have Access 2000 SR-1 Runtime, you can implement a workaround by following the steps in Part II.

Part I: Creating a Test Help File

Create a context-sensitive compressed HTML Help file in the Help workshop. If you already have a context-sensitive Help file, you can skip to Part II.

The Microsoft HTML Help Workshop, included with Microsoft Office 2000 Developer, creates compressed HTML files (extension .chm). These Help files do not, by default, have context-IDs. They use titles for Help topics. Because Access only uses context-IDs to open specific Help topics, a few extra steps are involved to incorporate these IDs into a compressed HTML Help file. This first part involves creating such a Help file for the run-time demonstration.

Creating Test1.htm

  1. Click Start, point to Programs, point to HTML Help Workshop, and then click HTML Help Workshop.
  2. On the File menu, click New, and then click Project. Name the new project MyProject.
  3. On the File menu, click New.
  4. Click HTML File, and then click OK.
  5. In the HTML Title dialog box, type Form Help, and then click OK.
  6. Between the <BODY> tags, type This is the Help topic for the form.
  7. On the File menu, click Save File. The Save As dialog box appears.
  8. Save the file with the name Test1.htm. Make note of the folder that you save it to.
  9. Close Test1.htm.

Creating Test2.htm

  1. On the File menu, click New.
  2. Click HTML File, and then click OK.
  3. In the HTML Title dialog box, type Control Help, and then click OK.
  4. Between the <BODY> tags, type This is the Help topic for the control.
  5. On the File menu, click Save File. The Save As dialog box appears.
  6. Save the file with the name Test2.htm. Make note of the folder that you save it to.
  7. Close Test2.htm.

Creating Map.h

  1. Click the Add/Remove topic files button. It is the second button down on the Project tab.
  2. Add the two files that you created earlier: Test1.htm and Test2.htm.
  3. On the Windows taskbar, click Start, and then click Run.
  4. Type Notepad, and then click OK.
  5. Type in the following:
       #define Test1 1001
   #define Test2 2001
  6. On the File menu, click Save as.
  7. In the Save as type: box, change the file type to All Files.
  8. Select the folder where you saved Test1.htm and Test2.htm. In the File name box, type MyMap.h. Click Save, and then close the file.

Aliasing Your Topics

  1. Return to the HTML Help Workshop.
  2. Click the HtmlHelp API information button. It is the fourth button down on the Project tab
  3. On the Alias tab, click Add.
  4. Type 1001 as the constant or number passed to the Help API, and then select the Test1.htm file from the selection of HTML files. Click OK.
  5. On the Alias tab, click Add.
  6. Type 2001 as the constant or number passed to the Help API, and then select the Test2.htm file from the selection of HTML files. Click OK.

Including Your Files, Setting Project Properties, and Compiling the Project

  1. On the Map tab, click Header File.
  2. Click Browse and browse to the MyMap.h file that you created earlier in Notepad.
  3. Click MyMap.h, click Open, and then click OK. Note that #include MyMap.h is in the list. Click OK
  4. Click the Change project options button. It is the first button down on the Project tab
  5. On the General tab, type My Custom Help File as the title of the Help project.
  6. Select Test1.htm as the default file from the dropdown list. Click OK.
  7. On the File menu, click Compile.
  8. Compile the Help file as MyProject.
  9. You should now have a compressed HTML Help file called MyProject.chm. Verify that it has been created, and make note of its location.

Creating a Test Database to Use with Your Help File

  1. In Access, create a new database called Database1.mdb. Create it in the same folder where you created the Help file.
  2. In Database1.mdb, create the following form named MyTestForm: 
       Form: MyTestForm
   ----------------

   Text Box
   ------------
   Name: Field1

   Text Box
   ------------
   Name: Field2
  3. If the Properties window is not already visible, click the form, and then on the View menu, click Properties.
  4. Make sure the form is selected, and then click the Other tab.
  5. In the Help File property, type MyProject.chm.
  6. In Help Context Id property, type 1001.
  7. Select the Field2 control, and then on the View menu, click Properties.
  8. Click the Other tab.
  9. In Form property Help Context Id, type 2001.
  10. On the View menu, click Form View.
  11. Click Field1, and then press F1. Note that you see the topic for the form appear. This is because Field1 does not have an associated topic and therefore defaults to the general form topic.
  12. Click Field2 and press F1. Note that you see the topic for the control appear.

Part II. Getting the Database Ready for Run-Time Use

This part is only necessary if you have not upgraded the computer that you are creating the run-time application to Access 2000 SR-1 Runtime on. If you have Access 2000 SR-1 Runtime, skip part II.

You should modify the database that uses the Help file. This involves creating custom code that ensures that your Help file is run appropriately and without error in a run-time application.

To start your custom Help File in a Microsoft Access 2000 run-time application, the Help file must be installed in the same folder as the database, and the full path to the Help file must be included in the properties of any forms or reports that use it. Because it is unpredictable what the exact path, including drive letter, may be for the Help file, some coding is required to ensure that each form is modified the first time, and only the first time that you open the database.

After the Help File property has been set on all forms, the code sets a custom database property specifying the name of the custom Help file. This property can then be checked on subsequent times that you open the database. If the database property exists, the code does not need to run again.

Also, to ensure that the Help file is run for any form or report, regardless of whether a Help file is specified for them, a macro is present that responds to the F1 key. This macro calls a function that runs the Help file.

To demonstrate adding the compressed HTML file with context-sensitive Help to an Access run-time solution, follow these steps.

These steps use the Help file and database that was created in Part I. For your specific situation, you can modify the code to use your database and Help file instead. Make sure to change any reference to MyProject.chm to the name of your Help file.
  1. In Access, open Database1.mdb.
  2. In the Database window, click Modules, and then click New.
  3. On the Tools menu, click References. Note that the References dialog box lists the various libraries referenced.NOTE: NOTE: The sample code in this article uses Microsoft Data Access Objects. For this code to run properly, you must reference the Microsoft DAO 3.6 Object Library. To do so, click References on the Tools menu in the Visual Basic Editor, and make sure that the Microsoft DAO 3.6 Object Library check box is selected.

  4. Type or paste the following code into the new module.
    Sub SpecifyHelpFile()
    Dim db As DAO.Database
    Dim frm As Document
    Dim cnt As Container
    Dim frmName As Form

    Set db = CurrentDb
    Set cnt = db.Containers!Forms

    For Each frm In cnt.Documents    'Loop through the forms
        If frm.Name <> "frmStartup" Then    'Avoid setting the property for 
                                            'the hidden start-up form.

            'Open the form in Design view, but hidden.
            DoCmd.OpenForm frm.Name, acDesign, , , , acHidden

            'Assign the name of the current form to the variable.
            Set frmName = Forms(frm.Name)

            'Enter the path and Help file name in the Help File property.
            frmName.HelpFile = appPath & "MyProject.chm"

            'Close and save form.
            DoCmd.Close acForm, frmName.Name, acSaveYes
        End If
    Next frm    'Go to the next form.
End Sub
  5. Save the module as modSetFormHelpProperty.
  6. Create a second new module, and then type or paste the following code:
    Function SetAccessProperty(obj As Object, strName As String, _
         intType As Integer, varSetting As Variant) As Boolean
    Dim prp As Object

    Const conPropNotFound As Integer = 3270

    On Error GoTo ErrorSetAccessProperty

    'Explicitly refer to Properties collection.
    obj.Properties(strName) = varSetting
    obj.Properties.Refresh

    SetAccessProperty = True
    
ExitSetAccessProperty:
    Exit Function
    
ErrorSetAccessProperty:
    If Err = conPropNotFound Then
        'Create property, denote type, and set initial value.
        Set prp = obj.CreateProperty(strName, intType, varSetting)

        'Append Property object to Properties collection.
        obj.Properties.Append prp
        obj.Properties.Refresh

        SetAccessProperty = True
        Resume ExitSetAccessProperty
    Else
        MsgBox Err.Number & " - " & Err.Description
        SetAccessProperty = False
        Resume ExitSetAccessProperty
    End If
End Function

Sub CallPropertySet()
    Dim dbs As DAO.Database
    Dim ctr As Container
    Dim doc As Document
    Dim blnReturn As Boolean
    
    'Return reference to current database.
    Set dbs = CurrentDb

    'Return reference to Databases container.
    Set ctr = dbs.Containers!Databases

    'Return reference to SummaryInfo document.
    Set doc = ctr.Documents!summaryinfo

    'The last argument specifies the name of the Help File, MyProject.chm.
    blnReturn = SetAccessProperty(doc, "Subject", dbText, "MyProject.chm") 

    'Evaluate return value.
    If blnReturn = True Then 
        MsgBox "Property set successfully."
    Else
        MsgBox "Property not set successfully."
    End If
End Sub
  7. Save the module as modSetDatabaseProperty.

    NOTE: The form that you create below always opens hidden. It also opens the first form the users will see, which in this example is MyTestForm. Therefore, you do not need to define a startup form on the Tools menu with the Startup command. Doing so may interfere with the code that runs upon opening the database.
  8. Create a blank unbound form called frmStartup.
  9. Add the following code to the OnLoad event of the form:
    Private Sub Form_Load()
    On Error GoTo Err_Form_Load

    appPath = Left(CurrentDb.Name, InStrRev(CurrentDb.Name, "\"))

    'Check to see if the subject is null.
    'If so, specify Help file. If not, do nothing.
    If IsNull(CurrentDb.Containers("databases"). _
       Documents("SummaryInfo").Properties("Subject")) Then
        SpecifyHelpFile
        CallPropertySet
    End If
    
Exit_Form_Load:
    DoCmd.OpenForm "MyTestForm", acNormal
    DoCmd.Close acForm, Me.Name
    Exit Sub
        
Err_Form_Load:
    If Err.Number = 3270 Then    'If the property was Null, a trappable 
                                 '"Property Not Found" error occurs.
        SpecifyHelpFile
        CallPropertySet
    Else
        MsgBox Err.Number & " - " & Err.Description
    End If
        Resume Exit_Form_Load
End Sub
  10. Close and save the frmStartup form.
  11. Create a new macro, and save it as AutoExec.
  12. In the new macro, define the following Action and Action Arguments:
        Macro Name  Action
    -------------------------
    AutoExec    OpenForm

    AutoExec Action Arguments
    -------------------------
      Form Name: frmStartup
           View: Form
    Window Mode: Hidden
  13. Close and save the macro.
  14. Disable the Office Assistant. To do so, on the Help menu, click Hide the Office Assistant. If Show the Office Assistant command appears on the menu, do nothing because this means that the Office Assistant is already hidden.
  15. In the Database window, click Macros, and then click New.
  16. Save the new macro with the name AutoKeys.
  17. On the View menu, click Macro Names.
  18. Type the following in the first line under Macro Name: {F1}.
  19. Set the action for {F1} to RunCode.
  20. For the Function Name, type the following:
    =MyHelpEntryRoutine()
  21. Close and save the macro.
  22. Create a new module. This holds the function that is run by the Autokeys macro that you created earlier. Add the following code to the new module:
    Declare Function HtmlHelp Lib "hhctrl.ocx" Alias "HtmlHelpA" _
        (ByVal hwndCaller As Long, ByVal pszFile As String, _
         ByVal uCommand As Long, ByVal dwData As Long) As Long

Const HH_DISPLAY_TOPIC = &H0
Const HH_SET_WIN_TYPE = &H4
Const HH_GET_WIN_TYPE = &H5
Const HH_GET_WIN_HANDLE = &H6
Const HH_DISPLAY_TEXT_POPUP = &HE
Const HH_HELP_CONTEXT = &HF
Const HH_TP_HELP_CONTEXTMENU = &H10
Const HH_TP_HELP_WM_HELP = &H11

Public appPath As String    'This is found on the OnLoad property of the                                'startup form: frmStartup

Public Function HH_DISPLAY_Click(Myhandle As Long)
    'hWnd is a Long defined elsewhere to be the window handle that 
    'will be the parent to the Help window.
    Dim hwndHelp As Long

    'The return value is the window handle of the created Help window.
    hwndHelp = HtmlHelp(Myhandle, appPath & "MyProject.chm", _ 
               HH_DISPLAY_TOPIC, 0)
End Function

Public Sub HH_HELP_Click(HelpFileName As String, MycontextID As Long)   
    'A specific topic identified by the variable context-ID is launched in 
    'response to this button click:
    Dim hwndHelp As Long

    'The return value is the window handle of the created Help window.
    Select Case MycontextID
        Case Is = 0
            hwndHelp = HtmlHelp(Application.hWndAccessApp, HelpFileName, _
                       HH_DISPLAY_TOPIC, MycontextID)
        Case Else
            hwndHelp = HtmlHelp(Application.hWndAccessApp, HelpFileName, _
                       HH_HELP_context, MycontextID)
    End Select
End Sub

Public Function MyHelpEntryRoutine()
    On Error GoTo Err_MyHelpEntryRoutine

    'Identify the name of the Help file and a possible context-id
    Dim MyHelpID As Long
    Dim MyHelpFile As String
    Dim MyForm As Form
    Dim MyReport As Report

    'Specify a path to the Help file and concatenate a generic Help file
    MyHelpFile = appPath & "MyProject.chm"

    'Set the initial Help context-id to zero
    MyHelpID = 0
    Set MyForm = Screen.ActiveForm
    
    'Check the Help file property of the form. If a Help file exists, 
    'assign the name and context-id to the respective variables
    If MyForm.HelpFile <> "" Then
        MyHelpFile = MyForm.HelpFile
        MyHelpID = MyForm.HelpcontextId
    End If

    'If the Help context-id is not null for a control, assign the 
    'value to the variable.
    If Not IsNull(MyForm.ActiveControl.Properties("HelpcontextId")) Then
        'If MyForm.ActiveControl.Properties("HelpcontextId") > 0 Then
        MyHelpID = MyForm.ActiveControl.Properties("HelpcontextId")
    End If

    'Call the function to launch the Help file passing it the name 
    'of the Help file and the context-id.
    HH_HELP_Click MyHelpFile, MyHelpID
    Exit Function

Err_MyHelpEntryRoutine:
    'If a report was loaded instead of a form, a trappable error occurs.
    If Err.Number = 2475 Then
        Set MyReport = Screen.ActiveReport
        If MyReport.HelpFile <> "" Then
            MyHelpFile = MyReport.HelpFile
            MyHelpID = MyReport.HelpcontextId
        End If
        HH_HELP_Click MyHelpFile, MyHelpID
    Else
        MsgBox Err.Number & " - " & Err.Description
        Exit Function
    End If
End Function
  23. Save the module with the name modLaunchHelpFile.
  24. Close Database1.mdb.

Part III: Packaging It Up

Now that you have your database and Help file ready, you can follow these steps to package the files up into a working run-time solution.
  1. Open Database1.mdb, and then on the File menu, click Database Properties.
  2. On the Summary tab, make sure the Subject box is blank, and then click OK. From previous demonstrations, the Subject box may contain the name of your Help file. It must be empty to specify the Help file on user's computers.
  3. If you skipped Part II, be sure to click Startup on the Tools menu, and select MyTestForm from the Display Form/Page dropdown list, and then click OK.
  4. Open the Visual Basic Editor (press ALT+F11) and on the Add-ins menu, click Package and Deployment Wizard. If the Package and Deployment Wizard is not available, please see the following article in the Microsoft Knowledge Base to load the wizard.
    236143� MOD2000: How to Start the Package and Deployment Wizard
  5. In the Package and Deployment Wizard, click Package.
  6. Click Next on each page, taking the defaults until you see the page titled Package and Deployment Wizard - Included Files.
  7. Add your Help file, MyProject.chm, here.

    NOTE: If you receive a message that the MyProject.chi file is missing, click OK to proceed without the file.
  8. Click to select the Include Access Runtime check box. Click Next.Note: If you are asked for the location of Access Runtime, insert the Microsoft Office 2000 Developer CD, and browse to the following file:
    <CD drive>\ODETools\v9\AccessRT\DATA1.MSI
  9. On the Package and Deployment Wizard - Installation Options page, note that the Installation Title is "Database1". Delete that and change the title to MyTest.
  10. Continue clicking Next in the wizard, taking the defaults, until the wizard is finished.

Part IV: Trying It in a Run-Time Solution

Install the run-time solution on another computer, run it, and verify that the custom Help is working. To do so, follow these steps:
  1. On a clean computer, install the run-time solution that you created in Part III.
  2. After the installation is complete, click Start, point to Programs, point to MyTest, and then click MyTest. Note that the database opens, and you are notified that the property was set successfully. The Test Form form opens.
  3. Click the first control, and then press F1. Note that Help for the form appears.
  4. Click the second control, and then press F1. Note that Help for that control appears.
  5. Close the application and reopen it. Note that you are not notified about setting the property because the Help settings are incorporated in the database for that computer.

↑ Back to the top

Status

Microsoft has confirmed that this is a problem in the Microsoft products that are listed at the beginning of this article. This problem was corrected in Microsoft Office 2000 SR-1/SR-1a.

↑ Back to the top

More information

Steps to Reproduce the Behavior

  1. Prepare a computer with the original version of Microsoft Office 2000 Developer and Access 2000 Runtime, not SR-1.
  2. Complete the steps in the "Resolution" section of this article labeled "Part I: Creating a Test Help File".
  3. Complete the steps in the "Resolution" section of this article labeled "Part III: Packaging it Up."
  4. Complete the steps in the "Resolution" section of this article labeled "Part IV: Trying it in a run-time solution."
  5. Install the run-time application on to a target computer that does not have Access.
  6. Start the run-time application, set focus to the text box, and press F1.

↑ Back to the top

Keywords: KB243568, kbpending, kbbug

↑ Back to the top

Article Info
Article ID : 243568
Revision : 3
Created on : 6/29/2004
Published on : 6/29/2004
Exists online : False
Views : 468