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 occured.

0	NO_ERROR
2	ERROR_FILE_NOT_FOUND
3	ERROR_PATH_NOT_FOUND
4	ERROR_TOO_MANY_OPEN_FILES
5	ERROR_ACCESS_DENIED
8	ERROR_NOT_ENOUGH_MEMORY
11	ERROR_BAD_FORMAT
26	ERROR_NOT_DOS_DISK
32	ERROR_SHARING_VIOLATION
33	ERROR_LOCK_VIOLATION
36	ERROR_SHARING_BUFFER_EXCEEDED
95	ERROR_INTERRUPT
108	ERROR_DRIVE_LOCKED
123	ERROR_INVALID_NAME
127	ERROR_PROC_NOT_FOUND
180	ERROR_INVALID_SEGMENT_NUMBER
182	ERROR_INVALID_ORDINAL
190	ERROR_INVALID_MODULETYPE
191	ERROR_INVALID_EXE_SIGNATURE
192	ERROR_EXE_MARKED_INVALID
194	ERROR_ITERATED_DATA_EXCEEDS_64K
195	ERROR_INVALID_MINALLOCSIZE
196	ERROR_DYNLINK_FROM_INVALID_RING
198	ERROR_INVALID_SEGDPL
199	ERROR_AUTODATASEG_EXCEEDS_64K
201	ERROR_RELOCSRC_CHAIN_EXCEEDS_SEGLIMIT
206	ERROR_FILENAME_EXCED_RANGE
295	ERROR_INIT_ROUTINE_FAILED

Include Info

#define INCL_DOSMODULEMGR
#include <os2.h>

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.DDL," queries its address and type, and finally frees it.

 #define INCL_DOSMODULEMGR     /* Module Manager values */
 #define INCL_DOSERRORS        /* Error values */
 #include <os2.h>
 #include <stdio.h>

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;
}

See Also

• DosFreeModule
• DosQueryProcAddr