LoadModule

3.0

HINSTANCE LoadModule(lpszModuleName, lpvParameterBlock)
LPCSTR lpszModuleName;	/* address of filename to load	*/
LPVOID lpvParameterBlock;	/* address of parameter block for new module	*/

The LoadModule function loads and executes a Windows application or creates a new instance of an existing Windows application.

Parameters

lpszModuleName

Points to a null-terminated string that contains the complete filename (including the file extension) of the application to be run. If the string does not contain a path, Windows searches for the executable file in this order:

1.The current directory.

2.The Windows directory (the directory containing WIN.COM), whose path the GetWindowsDirectory function retrieves.

3.The Windows system directory (the directory containing such system files as GDI.EXE), whose path the GetSystemDirectory function retrieves.

4.The directory containing the executable file for the current task; the GetModuleFileName function obtains the path of this directory.

5.The directories listed in the PATH environment variable.

6.The list of directories mapped in a network.

lpvParameterBlock

Points to an application-defined LOADPARMS structure that defines the new application's parameter block. The LOADPARMS structure has the following form:

struct _LOADPARMS {
    WORD      segEnv;         /* child environment  */
    LPSTR     lpszCmdLine;    /* child command tail */
    UINT FAR* lpShow;         /* how to show child  */
    UINT FAR* lpReserved;     /* must be NULL       */
} LOADPARMS;

Member

Description

segEnv	Specifies whether the child application receives a copy of the parent application's environment or a new environment created by the parent application. If this member is zero, the child application receives an exact duplicate of the parent application's environment block. If the member is nonzero, the value entered must be the segment address of a memory object containing a copy of the new environment for the child application.
lpszCommandLine	Points to a null-terminated string that specifies the command line (excluding the child application name). This string must not exceed 120 characters. If there is no command line, this member must point to a zero-length string (it cannot be set to NULL).
lpShow	Points to an array containing two 16-bit values. The first value must always be set to two. The second value specifies how the application window is to be shown. For a list of the acceptable values, see the description of the nCmdShow parameter of the ShowWindow function.
lpReserved	Reserved; must be NULL.

Return Value

The return value is the instance handle of the loaded module if the function is successful. If the function fails, it returns an error value less than HINSTANCE_ERROR.

Errors

If the function fails, it returns one of the following error values:

Value

Meaning

0	System was out of memory, executable file was corrupt, or relocations were invalid.
2	File was not found.
3	Path was not found.
5	Attempt was made to dynamically link to a task, or there was a sharing or network-protection error.
6	Library required separate data segments for each task.
8	There was insufficient memory to start the application.
10	Windows version was incorrect.
11	Executable file was invalid. Either it was not a Windows application or there was an error in the .EXE image.
12	Application was designed for a different operating system.
13	Application was designed for MS-DOS 4.0.
14	Type of executable file was unknown.
15	Attempt was made to load a real-mode application (developed for an earlier version of Windows).
16	Attempt was made to load a second instance of an executable file containing multiple data segments that were not marked read-only.
19	Attempt was made to load a compressed executable file. The file must be decompressed before it can be loaded.
20	Dynamic-link library (DLL) file was invalid. One of the DLLs required to run this application was corrupt.
21	Application requires Microsoft Windows 32-bit extensions.

Comments

The WinExec function provides an alternative method for executing an application.

Example

The following example uses the LoadModule function to run an executable file named DRAW.EXE:

struct LOADPARMS {
    WORD   segEnv;                  /* child environment  */
    LPSTR  lpszCmdLine;             /* child command tail */
    LPWORD lpwShow;                 /* how to show child  */
    LPWORD lpwReserved;             /* must be NULL       */
};

char szMsg[80];
HINSTANCE hinstMod;
struct LOADPARMS parms;
WORD awShow[2] = { 2, SW_SHOWMINIMIZED };

parms.segEnv = 0;               /* child inherits environment */
parms.lpszCmdLine = (LPSTR) "";     /* no command line        */
parms.lpwShow = (LPWORD) awShow;    /* shows child as an icon */
parms.lpwReserved = (LPWORD) NULL;  /* must be NULL           */

hinstMod = LoadModule("draw.exe", &parms);

if ((UINT) hinstMod < 32) {
    sprintf(szMsg, "LoadModule failed; error code = %d",
        hinstMod);
    MessageBox(hwnd, szMsg, "Error", MB_ICONSTOP);
}
else {
    sprintf(szMsg, "LoadModule returned %d", hinstMod);
    MessageBox(hwnd, szMsg, "", MB_OK);
}