DosLoadModule

Loads a dynamic link module (DLL), and returns a handle for the module.

Syntax
DosLoadModule (pszName, cbName, pszModname, phmod)

Parameters

 * pszName (PSZ) - output : The address of a buffer into which the name of an object that contributed to the failure of DosLoadModule is to be placed. (Address to a buffer into which in case of failure the name of the object that caused the failure is placed.)
 * The name of the object is usually the name of a dynamic link library that either could not be found or could not be loaded.


 * cbName (ULONG) - input : The length, in bytes, of the buffer described by pszName.
 * pszModname (PSZ) - input : The address of an ASCIIZ name string that contains the dynamic link module name.
 * The file-name extension used for dynamic link libraries is .DLL. (Name of the DLL to be loaded.)
 * When a request is made to load a module and a fully-qualified path is specified, the system loads that .DLL, if it exists. If a fully-qualified path is not specified, the system checks if the .DLL is already loaded. If it is loaded, that .DLL is the one that is used; otherwise, the system searches the paths in the LIBPATH string in the "CONFIG.SYS" file and uses the first instance of the specified .DLL it finds. If the current directory is not specified in the LIBPATH, the system does not check that directory to see if a different version exists. Consequently, if two processes started from different directories use the same DLL, but different versions of that DLL exist in both directories, the version of the DLL loaded by the first process is the one used by both processes.


 * phmod (PHMODULE) - output : Pointer to an HMODULE in which the handle for the dynamic link module is returned. (Pointer to the handle for the module)

Returns

 * APIRET rc:Indicates if any error occurred.

Include Info

 * 1) define INCL_DOSMODULEMGR
 * 2) include 

Usage Explanation
DosLoadModule tries to load a dynamic link module. If the module is an OS/2 dynamic link module then the module is loaded and a handle to the module is returned.

Gotchas
pszModuleName MUST NOT contain the .DLL extension if the DLL is to be loaded from the LIBPATH. On the other hand, if the DLL has to be loaded from a specific directory (i.e. not from the LIBPATH) then the .DLL extension is needed.

Remarks
DosLoadModule loads a dynamic link module, and returns a handle for the module.

If the file is an OS/2 dynamic link module, then the module is loaded, and a handle is returned. The returned handle is used for freeing the dynamic link module, getting procedure addresses, and getting the fully qualified file name.

DosLoadModule cannot be issued from ring 2 if the dynamic library routine has an initialization routine, or the process will be terminated.

If the module has an initialization routine that is in an object that has IOPL indicated, any process attempting to use the module will cause a general protection fault, and will be terminated.

Sample Code
HMODULE hmod; APIRET rc = 0; UCHAR szErrorName[CCHMAXPATH];  /* CCHMAXPATH defined in bsedos.h */ /* Load module. */ /* Try in same directory. */ rc=DosLoadModule(szErrorName, CCHMAXPATH-1, ".\\mydll.dll", &hmod); if (rc) { /* Failure? */   printf("Error in %s. Cannot load the DLL. DosLoadModule returned %d.\n",            szErrorName, rc); return(-1); } /* Query process addresses with DosQueryProcAddr */ /* Free module with DosFreeModule(hmod)           */ This example loads the dynamic link module "DISPLAY.DLL", queries its address and type, and finally frees it. 
 * 1) define INCL_DOSMODULEMGR    /* Module Manager values */
 * 2) define INCL_DOSERRORS       /* Error values */
 * 3) include 
 * 4) include 

int main(VOID) { PSZ     ModuleName     = "C:\\OS2\\DLL\\DISPLAY.DLL";  /* Name of module   */ UCHAR   LoadError[256] = "";          /* Area for Load failure information */ HMODULE ModuleHandle   = NULLHANDLE;  /* Module handle                     */ PFN     ModuleAddr     = 0;           /* Pointer to a system function      */ ULONG   ModuleType     = 0;           /* Module type                       */ APIRET  rc             = NO_ERROR;    /* Return code                       */ rc = DosLoadModule(LoadError,              /* Failure information buffer */                      sizeof(LoadError),       /* Size of buffer             */                      ModuleName,              /* Module to load             */                      &ModuleHandle);          /* Module handle returned     */ if (rc != NO_ERROR) { printf("DosLoadModule error: return code = %u\n", rc); return 1; } else { printf("Module %s loaded.\n", ModuleName); } /* endif */ rc = DosQueryProcAddr(ModuleHandle,        /* Handle to module           */                         1L,                   /* No ProcName specified      */                         NULL,                 /* ProcName (not specified)   */                         &ModuleAddr);         /* Address returned           */ if (rc != NO_ERROR) { printf("DosQueryProcAddr error: return code = %u\n", rc); return 1; } else printf("Address of module is 0x%x.\n", ModuleAddr); rc = DosQueryProcType(ModuleHandle,        /* Handle to module           */                         1L,                   /* Indicate no ProcName given */                         NULL,                 /* ProcName (not specified)   */                         &ModuleType);         /* Type 0=16-bit   1=32-bit   */ if (rc != NO_ERROR) { printf("DosQueryProcType error: return code = %u\n", rc); return 1; } else printf("This is a %s module.\n", ( ModuleType ? "32-bit" : "16-bit")); rc = DosFreeModule(ModuleHandle); if (rc != NO_ERROR) { printf("DosFreeModule error: return code = %u\n", rc); return 1; } else printf("Module %s freed.\n", ModuleName); return NO_ERROR; } 