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 DosLoadModule(pszFailName, cbFileName, pszModName, phmod)
PSZ pszFailName;      /* pointer to buffer for name if failure */
USHORT cbFileName;    /* length of buffer for name if failure  */
PSZ pszModName;       /* pointer to module name                */
PHMODULE phmod;       /* pointer to variable for module handle */
 
The DosLoadModule function loads a dynamic-link module and returns a handle
for the module. You can use the module handle to retrieve the entry
addresses of procedures in the module and to retrieve information about the
module.
 
Parameter    Description
────────────────────────────────────────────────────────────────────────────
 
pszFailName  Points to the buffer that receives a null-terminated string.
             The DosLoadModule function copies a string to the buffer only
             if the function fails to load the module. The string identifies
             the dynamic-link module responsible for the failure. This
             module may be other than the one specified in the pszModName
             parameter if the specified module links to other dynamic-link
             modules.
 
cbFileName   Specifies the length (in bytes) of the buffer pointed to by the
             pszFailName parameter.
 
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 handle of the
             dynamic-link module.
 
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_BAD_FORMAT
     ERROR_FILE_NOT_FOUND
     ERROR_INTERRUPT
     ERROR_INVALID_MINALLOCSIZE
     ERROR_INVALID_NAME
     ERROR_NOT_ENOUGH_MEMORY
 
Comments
 
The DosLoadModule function loads only MS OS/2 dynamic-link modules. Attempts
to load other executable files (such as MS-DOS executable files) result in
an error.
 
Example
 
This example calls the DosLoadModule function to load the dynamic-link
module qhdll.dll. This example then calls the DosGetProcAddr function to
retrieve the address of the BOXMESSAGE function that is defined in the
module. After calling the BOXMESSAGE function, the example calls
DosFreeModule to free the dynamic-link module. (This example is accurate if
qhdll.dll exists in a directory defined by the libpath command of the
config.sys file, and if qhdll.dll contains the BOXMESSAGE function that uses
the Pascal calling convention.)
 
UCHAR szFailName[CCHMAXPATH];
HMODULE hmod;
VOID (PASCAL FAR *pfnBoxMsg)(PSZ, BYTE, BYTE, SHANDLE, SHANDLE, BOOL);
 
DosLoadModule(szFailName,        /* failure name buffer         */
    sizeof(szFailName),          /* size of failure name buffer */
    "qhdll",                     /* module name                 */
    &hmod);                      /* address of handle           */
DosGetProcAddr(hmod, "BOXMESSAGE", &pfnBoxMsg);
pfnBoxMsg("Hello World", 0x30, 1, 0, 0, FALSE);
DosFreeModule(hmod);
 
See Also
 
DosExecPgm, DosFreeModule, DosGetModName, DosGetProcAddr
 
                                      ♦