Every Windows application needs a module-definition file. This file defines the name, segments, memory requirements, and exported functions of the application. If you do not create a module-definition file for your program, a default version will be created when you build it. You may edit this file once it is created. For a simple application, like Generic, you need at least the NAME, STACKSIZE, HEAPSIZE, EXETYPE, and EXPORTS statements. However, most applications include a complete definition of the module, as shown in the following example:
;module-definition file for Generic
1 NAME Generic WINDOWAPI ; Application's module name
2 DESCRIPTION 'Sample Microsoft Windows Application'
3 EXETYPE WINDOWS 3.0 ; Required for all Windows applications
4 STUB 'WINSTUB.EXE' ; Generates error message if application
;is run without Windows
5 CODE MOVABLE DISCARDABLE ; code can be moved in memory and
;discarded/reloaded
6 DATA MOVABLE MULTIPLE ; DATA must be MULTIPLE if
; program can be invoked more than once
7 HEAPSIZE 1024
8 STACKSIZE 5120 ; Recommended minimum for Windows applications
; All functions that will be called by any Windows routine
; MUST be exported.
9 EXPORTS
MainWndProc @1 ; Name of window-processing function
About @2 ; Name of About processing function
The semicolon is the delimiter for comments in the module-definition file.
In this example:
| 1 | The NAME statement defines the name and type of the application. The name (in the example, Generic) is used by Windows to identify the application. The NAME statement is not required, but is needed by Windows applications to override the defaults. The default application name is the base name of the executable file. The default application type is NOTWINDOWCOMPAT. |
| 2 | The DESCRIPTION statement is an optional statement that places the message Sample Microsoft Windows Application in the application's executable file. This statement is typically used to add version control or copyright information to the file. |
| 3 | The EXETYPE statement marks the executable file as either a Windows or an OS/2 executable file. Windows applications must contain the statement EXETYPE WINDOWS, since, by default, the linker creates executable files for the MS OS/2 environment. The optional version specifier marks the minimum version of Windows required for the program. |
| 4 | The STUB statement specifies a DOS program to be placed at the beginning of the file. When a user tries to run the application without Windows, the stub is executed instead. Most Windows applications use the default WINSTUB.EXE executable file supplied with QuickC for Windows. WINSTUB displays a warning message and terminates the application if the user attempts to run the application without Windows. You can also supply your own executable stub. If this statement is omitted, the linker provides a standard stub program. |
| 5 | The CODE statement defines the memory attributes of the application's code segment. Code segments contain the executable code that is generated when the GENERIC.C file is compiled. Generic is a small-model application with only one code segment, which is defined as MOVABLE and DISCARDABLE. If the application is not active and Windows needs additional space in memory, Windows can move the code segment to make room for other segments and, if necessary, discard it. A discarded code segment is automatically reloaded on demand by the Windows operating system. |
| 6 | The DATA statement defines the memory requirements of the application's data segment. Data segments contain storage space for all the static variables declared in the program, and space for the program stack and local heap. Generic has only one data segment, which, like the code segment, is MOVABLE. The MULTIPLE keyword directs Windows to create a new data segment for the application each time the user starts a new instance of the application. Although all instances share the same code segment, each has its own data segment. An application must have the MULTIPLE keyword if the user can run more than one copy of it at a time. |
| 7 | The HEAPSIZE statement defines the size, in bytes, of the application's local heap. Generic uses its heap to allocate the temporary structure used to register the window class, so it specifies 1024 bytes of storage. Applications that use the local heap frequently should specify larger amounts of memory. |
| 8 | The STACKSIZE statement defines the size, in bytes, of the application's stack. The stack is used for temporary storage of function arguments. Any application, like Generic, that calls its own local function must have a stack. Generic specifies 5120 bytes of stack storage, the recommended minimum for a Windows application. This statement overrides a stack size specified as a linker option. |
| 9 | The EXPORTS statement defines the names and ordinal values of the functions to be exported by the application. Generic exports its window function, MainWndProc, which has ordinal value 1 (this is an identifier; it could be any integer, but usually such values are assigned sequentially as the exports are listed). You must export all functions that Windows will call (except the WinMain function). These functions are referred to as “callback” functions. Callback functions include the following: |
| All window functions | |
| All dialog functions | |
| Special callback functions, such as enumeration functions, that certain Windows API functions require | |
| Any other function that will be called from outside your application |
For more information about the syntax and use of module-definition statements, see the Appendix, “Module-Definition Files,” in the Toolkit.