Display CHM Help Files Using Function HelpOnEx

We've recently upgraded an DOORS database to version 9.5.1 (server). Since this upgrade it is not possible anymore to display a compressed HTML help file using function helpOnEx(). The related line of code is as follows:

helpOnEx( myWindow, helpFile, mapID )

Parameter helpFile contains the full path to the chm file, mapID the index where to jump within the help file. myWindow is the parent window.

Calling help files in this way still works perfectly on a DOORS 9.4 server. When working on the 9.5.1 server the Windows help window does not open. There is no error notification. The code execution just continues. We can confirm this issue on 9.1, 9.3 and 9.4 DOORS clients, that connect to the 9.5.1 server.

I've seen that IBM changed the DOORS help from chm to Eclipse. Does this also affect function helpOnEx(), which is rarely documented?

Any ideas how to solve this issue?

Re: Display CHM Help Files Using Function HelpOnEx
Mathias Mamsch - Wed Feb 26 13:56:39 EST 2014

I find it highly curious, that the DOORS server version should affect the behaviour of this completely client based function at all. Are you saying that using a DOORS 9.4 client on a DOORS 9.4 server shows a different behaviour than a DOORS 9.4 client on a DOORS 9.5 server? Or are we talking about different client versions? 

If we are talking about different clients, how did you make sure your environment is exactly the same between both client installations? Could it be an environmental problem, that it works in one case and not in the other?

Regards, Mathias

Re: Display CHM Help Files Using Function HelpOnEx
rdratlos - Thu Feb 27 05:25:15 EST 2014

Dear Mathias,

as always: I appreciate your quick and competent feedback.

We're talking about one and the same client: DOORS 9.4. But your hint lead me in the correct direction. It's an environment issue. The DOORS client is started using a script which sets among others the addins path. And here is the root cause of the problem:

The function we use to display help information is as follows:

void dwx_showHelp( DB myWindow, string pHtmlHelpFile, int mapID )
{
    string helpFile = pHtmlHelpFile
    if (!canOpenFile( helpFile, false ))
    {
        // Try to find the help file in the lib's directory
        // Returns null string, if file can't be found
        helpFile = dwxint_canOpenHelpFile( helpFile )
    }
    if (!null helpFile)
    {
        helpOnEx( myWindow, helpFile, mapID )
        return
    }
    else
    {
        ack "HTML help file '" pHtmlHelpFile "' not found."
    }
}

The function can be called using the full path of the .chm help file or just the help file name, if it is located in the same directory as the library with the dwx_showHelp function. This works fine as long as the addins path (set with command-line switch '-a') does not point to a directory, in which a copy of the help file.is located. In this case, function call canOpenFile() returns true and function helpOnEx() is called with just the help file name as input and not the full path to the help file.

Therefore, the root cause of this issue is the wrong use of function canOpenFile() to check, if the user passed a correct chm help file name, that can be displayed by function helpOnEx(). The correct function to use for this purpose is fileExists(). Following code works:

void dwx_showHelp( DB myWindow, string pHtmlHelpFile, int mapID )
{
    string helpFile = pHtmlHelpFile
    if (!fileExists_(helpFile))
    {
        // Try to find the help file in the lib's directory
        // Returns null string, if file can't be found
        helpFile = dwxint_canOpenHelpFile( helpFile )
    }
    if (!null helpFile)
    {
        if (canOpenFile( helpFile, false ))
        {
            helpOnEx( myWindow, helpFile, mapID )
        }
        else
        {
            ack "Cannot open HTML help file '" helpFile "'."
        }
    }
    else
    {
        ack "HTML help file '" pHtmlHelpFile "' not found."
    }
}

More information on function dwxint_canOpenHelpFile() can be found here.

Best regards

Thomas