Developing 32-bit Windows programs

Developing with Stony Brook Modula-2 allows you to take advantage of all of Win32capabilities, including:

• Win32 API
• Resources
• DLLs

Win32 Development Information

Building DLLs

The Win32 API

Although using the runtime library to program for Win32 is possible, you willnot be writing true Win32 applications.  In order to develop applications thatprovide your users with the menus, dialogs, windows and other features they willbe expecting you will have to use the Win32 Application Programming Interface(API).The Win32 API is provided in definition modules in the runtime library.  Youcan call Win32 API functions in the same way you call run time library functions.

Many of the API calls have been altered from their original C style to a stylethat is more natural for the Modula-2 programming language. The parameters that havebeen converted are pointer parameters. The Modula-2 language in many ways does notneed such parameters and Stony Brook Modula-2 takes this a bit further. The parametersare either value or VAR parameters depending on the function usage of the parameter.

String Parameters. LPSTR, LPCSTR, LPTSTR, LPCTSTR, LPWSTR, LPCWSTR are pointersto characters. In the Modula-2 API definitions these where converted to ARRAY OFCHAR parameters without the implicit high bound. However, the Win32 API restrictionthat strings be NULL terminated still applies, so take care that strings you passare indeed NULL terminated.

RECORD type parameters. Pointers to RECORD types have been converted to valueor VAR parameters. This can be done because our compiler always passes RECORD typesby reference, even for value parameters.

ARRAY type parameters. Pointers to ARRAY types have been converted to value orVAR parameters. This can be done because our compiler always passes ARRAY types byreference, even for value parameters.

Pointers to scalar types. In these cases the API call is doing exactly what theModula-2 VAR parameter accomplishes. The VAR parameter is a cleaner and type safemechanism.

Here is a list of the Win32 API files provided and what they contain :

WINX also contains some strongly typed constants, and some NIL variables for Modula-2modified parameters such as RECORD and ARRAY OF parameters.  These NIL variablesexist because Windows often provides optional behaviors on API functions when a NILpointer is passed.  In Modula-2, since these have been mapped to structuresand arrays, a clean way was needed to access these optional behaviors.  Forexample, if you wanted to  call an API that required a NIL string be passedyou would call the function as:

Api name(WINX.NIL_STR);

OpenGL

The OpenGL interface is compiled is a separate project, OpenGL. Add this project to any project that need to use the OpenGL interface. The project exists in the installation directroy.

Exception Handlers on Exports

Procedures which are marked with the EXPORT attribute will automatically generatean exception handler if you do not supply one.  The exception handler will terminatethe program if it is activated.  This is to avoid the situation of an exceptionpropagating to other programs.  We strongly recommend that you provide an explicitexception handler on all exported procedures and handle any exceptions in a way thatbest suits your program (Returning an error code for example).

A compiler directive is supplied to allow a procedure with the EXPORT attributeto propagate and exception. This should only be used when Modula-2 is calling Modula-2code and all of the code is using the same instance of the runtime system. If yourexported procedure is in a DLL then you should be linking to the DLL version of theModula-2 runtime library for all DLLs and programs.

Important Variables

The information that Win32 provides when an application is run or attached/detachedis made available by the following six variables which exist in WINX.  For informationon their usage please consult your Win32 reference manuals.

Instance : HINSTANCE;

PrevInstance : HINSTANCE;

CmdShow : UINT;

CmdLine : LPSTR;

The following variables are imported from the SYSTEM module.

IsInit : BOOLEAN; (* Initialization or termination of a DLL *)

IsThread : BOOLEAN; (* Process or Thread DLL *)

The meanings of the last two variables for DLLs are:

WIN32.DLL_PROCESS_ATTACH = IsInit AND (NOT IsThread);

WIN32.DLL_PROCESS_DETACH = (NOT IsInit) AND (NOT IsThread);

WIN32.DLL_THREAD_ATTACH = IsInit AND IsThread;

WIN32.DLL_THREAD_DETACH = (NOT IsInit) AND IsThread;

For programs IsInit is always TRUE and IsThread is always FALSE.

Name Clashes

Win32 contains symbols that collide with Modula-2 pervasive symbols. The symbolsin the API files have been renamed as follows.

• SIZE goes to WSIZE
• FLOAT goes to WFLOAT
• INT goes to WINT
• PROC goes to WPROC

ASCII and UNICODE

The Stony Brook development system provides comprehensive support in developingASCII and Unicode applications.  The default mode is ASCII application development. To develop Unicode applications, the RunTime library may be built with thechar implementation set to Unicode. If this is done all string parameters in theRTL will be Unicode strings.

Mixed ASCII/Unicode development can be accomplished by calling the "W"and "A" versions of the API functions directly.

Note: The Windows 95/98/Me operating systems do not support Unicode applications.

Startup Code

The main program entry point for normal Modula-2 programs is called _start@0.The entry point is the module BEGIN block of your program.

If CMAIN is used the C entry point procedure is the entry point. The C entry pointwill then call your main program BEGIN block which has the public symbol name _WinMain@16.

For DLLs the entry point is called _startDLL@12.  The entry point is theBEGIN block of the program module.

All of the programs initialization code is called automatically.

Using Resources

To include a resource in a program,  put the compiler resourcedirective into your program. You can have more than one resource file per programwhen using the Stony Brook linker. If you use other linkers this may not be the case.The environment uses this directive to track a dependency between the source filewith the directive and the resource file. The resource file will be linked when thesource file with the directive is a part of the program.

Creating Help files

Standard Input and Output

A normal Win32 program does not have any standard input of output handles unless explicitly given these handles by the program that starts the program. For standard input and output Win32 programs you must make sure that the Console Application Linker Option is set. Windows will automatically create a console window for a console program if the console program is not started from a console window. Windows will automatically delete the console window on program termination.