RegisterRoutine (or RR)

Registers a function within a dynamic-link library (DLL) as a Help macro. Registered functions can be used in macro hot spots or footnotes within topic files or in the [CONFIG] section of the Help project file, the same as standard Help macros.

Note:

The RegisterRoutine macro ignores all return values.

Syntax

RegisterRoutine("DLL-name", "function-name", "parameter-spec")

RR("DLL-name", "function-name", "parameter-spec")

Parameter Description

DLL-name String specifying the filename of the DLL being called. The filename must be enclosed in quotation marks. You can omit the .DLL filename extension.

Specify the directory only if necessary. Generally, DLLs are installed in the directory where Windows Help resides. For more information, see “How Help Locates .DLL and .EXE Files” in Chapter 14, “Help Macros.”

function-name String specifying the name of the function you want to use as a Help macro. The function name must be enclosed in quotation marks.
parameter-spec String specifying the formats of parameters passed to the function. Characters in the string represent C parameter types. Valid parameter types include the following:
  Character Data type Equivalent Windows data type

  u Unsigned short integer UINT, WORD, WPARAM
  U Unsigned long integer DWORD
  i Signed short integer BOOL (also C int or short)
  I Signed long integer LONG, LPARAM, LRESULT
  s Near pointer to a null-terminated text string PSTR, NPSTR
  S Far pointer to a null-terminated text string LPSTR, LPCSTR
  v Void (means no type; used only with return values) None. Equivalent to C void data type.

  The parameter-spec must be enclosed in quotation marks. Windows Help checks the format string to ensure that it matches the function prototype defined in the DLL.

To determine the data type of the function’s parameters, consult the application programming interface (API) documentation for the DLL, or ask the person who developed the DLL. When using Windows functions with Windows Help, be sure that you fully understand how the function will affect Help. For information on Windows functions, their parameters, and parameter types, see the Microsoft Windows version 3.1 Software Development Kit.

Example

The following DLL call registers a routine named PlayAudio in the DLL named HELPLIB.DLL:

RegisterRoutine("helplib", "PlayAudio", "SIU")

Comments

If Windows Help cannot find the DLL, it displays an error message and does not perform the call. When loading DLLs, Help looks for a routine first in the directory from which Help was started. Therefore, WINHELP.EXE can be located anywhere—even on a drive not on the user’s machine—and Help will look for DLLs in that directory first. Generally, it is not a good idea to place application-specific DLLs in the Windows directory or in the Windows SYSTEM directory.