In the hot spot example earlier in this section, the HelloWorld function used the internal Viewer variables hwndContext (a handle to the Viewer context window) and qchPath (a pointer to the title filename). In general, after you register a DLL function as a Viewer command, you can specify Viewer internal variables as parameters to that function when the function appears in hot spots or command footnotes.
In this section, you'll learn about other Viewer internal variables that you can pass to DLL functions registered as Viewer commands. This section also examines in detail one variable that controls how the DLL handles Viewer errors.
You can use any of the following Viewer internal variables in DLL functions:
| Variable | Format Spec | Description |
| hwndApp | “U” | Handle to the main Viewer window. This variable is guaranteed to be valid only while the function is executing. |
| hwndContext | “U” | Handle to the current active window (either the main Viewer window or a secondary window). |
| qchPath | “S” | Fully qualified path of the currently open title (.MVB) file. |
| qError | “U” | Long pointer to a structure containing information about the most recent Viewer error (described later in this section). |
| lTopicNo | “U” | Topic number. This number is relative to the order of topics in the RTF files used to build the title. |
| hfs | “U” | Handle to the file system for the currently open title (.MVB file). |
| coForeground | “U” | Current foreground color. |
| coBackground | “U” | Current background color. |
The internal variable qError points to a structure containing information about the most recent Viewer error. The error structure is defined as follows:
struct
{ WORD fwFlags;
WORD wError;
char rgchError[wMACRO_ERROR];
} QME;The fwFlags field contains flags indicating how Viewer responds to errors. The following are possible error flags and their values:
| Flag | Value | Description |
| fwMERR_ABORT | 0x0001 | Allows the “Abort” option. This flag is set by default. |
| fwMERR_CONTINUE | 0x0002 | Allows the “Continue” option. |
| fwMERR_RETRY | 0x0004 | Allows the “Retry” option. |
The wError field is a number indicating the type of error that occurred. The following are possible error numbers and their values:
| Error | Number | Description |
| wMERR_NONE | 0 | No error (initial value) |
| wMERR_MEMORY | 1 | Out of memory (local) |
| wMERR_PARAM | 2 | Invalid parameter passed |
| wMERR_FILE | 3 | Invalid file parameter |
| wMERR_ERROR | 4 | General Viewer command error |
| wMERR_MESSAGE | 5 | Viewer command error with message |
If the wError field is wMERR_MESSAGE, the rgchError field contains the error message that Viewer displays.