This section describes how to use ACUCOBOL-GT in conjunction with the Windows NT Software Development Kit (SDK). To use the SDK, you must have:
Microsoft Visual C++ version 6.0
Generally speaking, you make use of the SDK by writing various C subroutines that call the SDK. You then build a new runtime that contains these C subroutines, and you make calls to these routines from your COBOL application. You can also use this procedure to call code produced by code generators.
The remainder of this section assumes you are familiar with C and the 32-bit Windows SDK.
Building a new runtime
Appendix C in the ACUCOBOL-GT Reference Manual covers the details of writing C subroutines and passing parameters between those routines and COBOL. You may use any of the interface methods described there to call your C routines.
After you've written your routines, you'll need to link them into the runtime system. This process builds a new "wrun32.exe" that contains your routines.
In order to build a new runtime, you must have the ACUCOBOL-GT 32-bit development system and Visual C++ installed properly. The files that you need to rebuild the runtime can be found in the "library" subdirectory off the main ACUCOBOL-GT directory. Change to that directory and type:
NMAKE /-f WRUN32.MAK
If everything is installed correctly, you should see the steps occurring as a new runtime system is built, and you should end up with a new "wrun32.exe" file.
Important tips before you rebuild the runtime
You may add your C routines directly to the "sub.c" or "mswinsub.c" files provided with ACUCOBOL-GT. More likely, you'll want to create your own files that hold your routines. If you do this, add the names of your files to the line labeled "SUBS=" in the "makefile.nt" file. Note that you actually add the name of the corresponding ".obj" file, not the ".c" source file.
The file "mswinsub.c" contains useful declarations that you may want to use in your C subroutines. In particular, you will find variables for the "instance" and "main window" handles used by ACUCOBOL-GT. Also, you will find a start-up routine to which you can add your initialization code.
User interface approaches
You can use the SDK for many things that don't directly affect the user interface. For example, you can add dynamic data exchange with another application using the SDK. If you want to add user-interface code, however, then you must decide whether to build your user interface using a mix of COBOL and C, or whether to use C alone. This decision affects how your code will interact with the runtime system.
Using C only-no COBOL
If you build your interface entirely in C, then you have complete flexibility in how the interface will work. In this case, you will either want to run the runtime system with the "-b" command-line option, or set the configuration variable "NO-CONSOLE" to "1". When you do this, the runtime won't create its own application window. Instead, your C code must build its own window. When you take this approach, you may not use ACCEPT or DISPLAY verbs in your COBOL program (except for those that don't interact with the screen or keyboard). This approach also works well with a user interface created by a code-generating tool.
Using C and COBOL
If you want to use COBOL in conjunction with C, you must take care to cooperate with the runtime system in how the screen is displayed.
There are some cases in which you don't need to worry about the runtime system, because Windows NT will manage everything. Generally speaking, this occurs when your C code displays data in its own window. For example, you can display and accept data from a dialog box without interacting with the runtime system (all you need is the handle of the runtime's window, which you have in "mswinsub.c").
In other cases, you'll need to cooperate with the runtime's message handler. For example, if you want to display a graphical object in the main application window, you must monitor "paint" messages to the runtime system and draw your object when appropriate. The general technique for doing this is called "subclassing". When you subclass a window, you instruct Windows NT to pass all of its messages to your own message handler. Typically, your message handler acts on one or more messages and then passes all the messages to the original message handler. For detailed instructions on subclassing, see any Windows NT programming text. The following is an example of a typical case.
Suppose that you want to intercept messages to the runtime system and pass them to a routine called "MyMsgHandler". To do so, you would first declare "MyMsgHandler" as a function designed to be called from Windows NT:
LRESULT CALLBACK MyMsgHandler( HWND, UINT, WPARAM, LPARAM );
Next, in your start-up code, you would get the address of the ACUCOBOL-GT message handler and then direct Windows NT to send messages to your handler instead. The code reads like this:
FARPROC lpfnMyMsgHandler, lpfnAcuWndProc;
lpfnMyMsgHandler = MakeProcInstance((FARPROC) MyMsgHandler, hAcuInstance );
lpfnAcuWndProc = (FARPROC) GetWindowLong( hAcuWnd, GWL_WNDPROC );
SetWindowLong( hAcuWnd, GWL_WNDPROC, (long) lpfnMyMsgHandler );
At this point, all messages that Windows NT would normally direct to the ACUCOBOL-GT main window procedure will instead be received by "MyMsgHandler". Your message handler should intercept and act on the messages it cares about. At the end, it should then pass each message on to the original message handler and return the result. This is usually done with a line that reads like this:
return CallWindowProc( lpfnAcuWndProc, hWnd, iMsg, wParam, lParam );
For reference, ACUCOBOL-GT for Windows NT currently acts on the following messages:
WM_ACTIVATE
WM_ACTIVATEAPP
WM_CHAR
WM_CLOSE
WM_COMMAND
WM_CREATE
WM_CTLCOLOR
WM_CTLCOLORBTN
WM_CTLCOLOREDIT
WM_CTLCOLORLG
WM_CTLCOLORLISTBOX
WM_CTLCOLORMSGBOX
WM_CTLCOLORSCROLLBAR
WM_CTLCOLORSTATIC
WM_DESTROY
WM_DRAWITEM
WM_ENDSESSION
WM_ERASEBKGND
WM_GETMINMAXINFO
WM_HSCROLL
WM_INITMENU
WM_INITMENUPOPUP
WM_KEYDOWN
WM_KILLFOCUS
WM_LBUTTONDBLCLK
WM_LBUTTONDOWN
WM_LBUTTONUP
WM_MBUTTONDBLCLK
WM_MBUTTONDOWN
WM_MBUTTONUP
WM_MEASUREITEM
WM_MOUSEMOVE
WM_NCLBUTTONDBLCLK
WM_NCLBUTTONDOWN
WM_NCPAINT
WM_PAINT
WM_PALETTECHANGED
WM_QUERYDRAGICON
WM_QUERYENDSESSION
WM_QUERYNEWPALETTE
WM_RBUTTONDBLCLK
WM_RBUTTONDOWN
WM_RBUTTONUP
WM_SETCURSOR
WM_SETFOCUS
WM_SIZE
WM_SIZING
WM_SYSCHAR
WM_SYSCOLORCHANGED
WM_SYSCOMMAND
WM_TIMER
WM_VSCROLL
See the SDK documentation for details about these messages.