Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►  ◄Changes►               ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSMODULEMGR
 
USHORT DosGetModHandle(pszModName, phMod)
PSZ pszModName;    /* pointer to module name                      */
PHMODULE phMod;    /* pointer to variable receiving module handle */
 
The DosGetModHandle function retrieves the handle of a dynamic-link module.
The DosGetModHandle function is typically used to make sure that a module
has been loaded into memory. If the module has not been loaded, the function
returns ERROR_MOD_NOT_FOUND, and the DosLoadModule function must be used to
load the module.
 
Parameter   Description
────────────────────────────────────────────────────────────────────────────
 
pszModName  Points to the null-terminated string that specifies the module
            name. This string must be a valid MS OS/2 filename. If it does
            not specify a path and the filename extension, the function
            appends the default extension (.dll) and searches for the
            dynamic-link module in the directories specified by the libpath
            command in the config.sys file.
 
phMod       Points to the variable that receives the module handle.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:
 
     ERROR_INTERRUPT
     ERROR_MOD_NOT_FOUND
 
Example
 
This example calls DosGetModHandle to determine whether the dynamic-link
module mydll.dll is currently in memory. If mydll.dll is not in memory,
DosGetModHandle calls DosLoadModule to load it. It then calls DosGetModName
to get the full path of the module. (This example is accurate if mydll.dll
exists in a directory defined by the libpath command in the config.sys
file.)
 
USHORT usError;
HMODULE hmod;
UCHAR szFailName[CCHMAXPATH], szModName[CCHMAXPATH];
 
if (usError = DosGetModHandle("mydll", &hmod)) {
    if (usError == ERROR_MOD_NOT_FOUND)
        DosLoadModule(szFailName, sizeof(szFailName),
            "mydll", &hmod);
}
DosGetModName(hmod, sizeof(szModName), szModName);
 
See Also
 
DosFreeModule, DosGetModName, DosLoadModule
 
                                      ♦