Problem:
This example illustrates how to use the Windows MessageBox API function to display information for an application user. Four different techniques are described. Eight significant features are demonstrated:
- call-convention,
- COBOL Call Prototypes,
- Constant Compiler directive,
- Conditional Compilation,
- Level 78 items,
- z'literal',
- procedure-pointer items,
- set ... to entry ... statements.
Resolution:
INTRODUCTION
==========
This example illustrates how to use the Windows MessageBox Api to display information for an application user. Four different techniques are described. Eight significant features are demonstrated, call-convention, COBOL Call Prototypes, Constant Compiler directive, Conditional
Compilation, Level 78 items, z'literal', procedure-pointer items, and set ... to entry ... statements.
There are five projects in these four directories:
- cc66\\Cob32api\\MessageBox66Cob32api.app
- cc66\\SetToEntry\\MessageBox66SetToEntry.app
- cc74\\MessageBox.app
- Prototype\\Prototype.app
- Prototype\\LINKED.app
The Prototype directory contains two projects. The Prototype.app project uses intermediate code (.Int) and the LINKED.app project uses object code (.Obj).
An annotated version of the Win32 SDK documentation describing the MessageBox Api is included and named MessageBox.doc (COBOL source code additions). It is a Wordpad document in Word 6.0 format.
Project cc66\\Cob32api\\MessageBox66Cob32api.app:
----------------------------------------------------------------
This example uses call-convention 66 and the Micro Focus Cob32api.dll. This technique will support Win32 Api functions in Shell32.dll, Comdlg32.dll, Comctl32.dll, Advapi32.dll, Gdi32.dll, User32.dll and Kernel32.dll. This technique works with .Int, .Gnt and .Obj file formats.
cc66\\SetToEntry\\MessageBox66SetToEntry.app
----------------------------------------------------------
This example uses call-convention 66, a procedure-pointer item and a set ... to entry ... statement to gain access to user32.dll (the Win32 Dll containing the MessageBox function). This technique will support any Windows Api function and any mixed language Dll that conforms to Windows standard call specifications. This technique will work with .Int, .Gnt and .Obj file formats.
cc74\\MessageBox.app
---------------------------
This example uses call-convention 74 and import libraries distributed with NetExpress or the Microsoft Win32 SDK to static link your COBOL program with the Win32 MessageBox function. This technique will only work with object (.Obj) format files.
Prototype\\Prototype.app
-------------------------------
This example uses a COBOL prototype for the MessageBox, Win32 function. Both call-convention 66 and 74 are specified, as well as a procedure-pointer item and a set ... to entry ... statement. Conditional compiler directing statements determine the code actually compiled.
Using a prototype simplifies your call statement coding and supports the compiler's verification of your coding. Spell the function name incorrectly, code too many or too few parameters, code the picture or usage for a parameter incorrectly and the compiler will produce an error.
This example also shows you how to accommodate Unicode alternatives as well as static linking by using conditional compilation directives. The source code for this project is shared with the LINKED project.
Prototype\\LINKED.app
----------------------------
This project uses the compiler constant LINKED in order to produce an executable static linked to the MessageBox Win32 function. This constant must be added to the Compiler directives in Project Properties. To use the LINKED compiler constant without disrupting the Prototype project,
you need a separate project file. A given project has only one set of Project Properties that can be adjusted. Examine the Project Properties, Compiler directives and you'll see that this constant has been added:
constant LINKED (1)
to the end of the default compiler directive settings. This is what permits the LINKED project to produce an executable that is static linked with the MessageBox Win32 function in user32.dll.
SOURCE FILES:
=========
Program Files Description
---------------- -----------------------------------------------------------
Msgbox.cbl A COBOL program that calls the Windows MessageBox function. The cc66
projects and the cc74 project use source code that is nearly identical. The
Prototype and LINKED projects use the same source program.
Copy Files:
------------------- -----------------------------------------------------------
Prototypes.cpy This copy book is a COBOL Call Prototype definition for the Win32 MessageBox
function. It is only used in the Prototype and LINKED projects.
Win32 SDK Supplement
--------------------- -----------------------------------------------------------
MessageBox.doc A Wordpad document in Word 6.0 format that is an annotated copy of the
Win32 SDK documentation on the MessageBox Api. Refer to this document
for a description of the MessageBox Api and the corresponding COBOL
used to implement the Api in the examples.
REQUIREMENTS:
==========
NetExpress 3.1 and Microsoft Win32 SDK.Read MessageBox.doc for the details on how to use the
MessageBox Api. Review the example programs for the details on each type of implementation.
OPERATION:
========
The programs are compiled and can be Animated as is. This applies to all Debug Builds. The LINKED project is a Release Build and not intended for Animation.
cc66\\Cob32api
------------------
You only need to call the Micro Focus Cob32api Dll at the beginning of your application.
call 'cob32api'
The file will remain in memory until your application terminates. Multiple calls to this program are not necessary, but they are also not harmful.
cc66\\SetToEntry
--------------------
The following code represents the essentials of using a procedure-pointer to load your Dll programs.
working-storage section.
77 User32Ptr procedure-pointer.
procedure division.
set User32Ptr to entry 'user32'
Once the procedure-pointer has been set you can test it for a zero (null) value to determine if the Dll has been located and loaded into memory by the operating system. This is most useful when you are loading other COBOL Dlls or implementing a mixed language application. Most of the Windows Dlls will already be loaded into memory when your application starts execution.
cc74
------
You should Rebuild All this example and examine the Output Window. Note the Link step and the import libraries listed. These Windows import libraries are included in the Link step by default: msvcrt.lib; kernel32.lib; user32.lib; gdi32.lib; advapi32.lib; and are also present in the NetExpress\\Base\\Lib directory.
If you are working with a Win32 Api that requires an import library other than those listed above, you will need to install the Win32 SDK and specify the library by name in your Build settings, Link tab, Advanced Category, under Link with these LIBS.
Prototype
------------
Although this directory contains two projects it is just one program that is being worked. The Prototype project is a Debug Build. This project waw used to perfect the example. Once this project was working correctly it was closed, NetExpress was shut down and the LINKED project was opened to perform the Release Build. I encountered difficulties switching between these two projects without shutting NetExpress down.
REFERENCES:
========
call-convention
-------------------
Net Express Bookshelf: Language Reference, Part 2:
Compilation Group Definition,
Chapter 6: Environment Division,
Section 6.1.2.3
The Special-names Paragraph
Netxpress Help: Click Find tab, type "call-convention" in
window 1, click "call-convention" in window
2, click "Call conventions for interfacing
with mixed language applications",
click Display button.
COBOL Call Prototypes
----------------------------
Net Express Bookshelf: Language Reference, Part 1 COBOL
Concepts, Chapter 3 Language
Fundamentals, Section 3.4 Call
Prototypes.
NetExpress Bookshelf: Language Reference - Additional
Topics, Chapter 6: Examples, 6.1 Call
Prototypes.
Compiler Constant Directive
----------------------------------
Net Express Help: Click Index tab, type "constant" in window
1, click "CONSTANT Compiler directive" in
window 2 and click the Display button.
Conditional Compilation
----------------------------
NetExpress Bookshelf: Language Reference, Part 2:
Compilation Group Definition, Chapter
18: Compiler-directing Statements,
Section 18.5 Conditional Compilation,
18.5.2 $ELSE Statement, 18.5.3 $END
Statement, 18.5.4 $IF Statement.
level 78 and z'literal'
------------------------
NetExpress Bookshelf: Language Reference, Part 2:
Compilation Group Definition,
Chapter 8: Data Division - File and
Data Description, Section 8.2 Data
Description Entry, Format 4 (syntax),
Generals Rules, Rule 3 Format4.
NetExpress Help: Click Find tab, type "constant-name" in
window 1, click "Constant-names" in window
2, click "Constant-names" in window 3 and
click the Display button.
NetExpress Help: Click Index tab, type "literal" in window
1, click "Literal" in window 2, click
Display button, select "Literals" in
Topics Found dialog and click Display
button in Topics Found dialog. In
"Nonnumeric Literals" section read
paragraph beginning "A null-terminated
string" through the end of the section.
MessageBox
----------------
Win32 SDK Help: Open Win32 Programmer's Reference, open
Reference, open MapVirtualKeyEx to
NetFileEnum, double click MessageBox, click
and read Quick Info button information
noting import library name (Dll name is
usually the same), Unicode specification
and Header file name, read document.
MSDN Web Site: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/winui/winui/windowsuserinterface/windowing/dialogboxes/dialogboxreference/dialogboxfunctions/messagebox.asp
procedure-pointer item
----------------------------
NetExpress Bookshelf: Language Reference, Part 2:
Compilation Group Definition,
Chapter 8: Data Division - File and
Data Description, Section 8.2 Data
Description Entry, Format 1 (syntax),
Generals Rules, Rule 3 (no picture).
NetExpress Help: Click Index tab, type "procedure-pointer"
in window 1, select 1st "Procedure-
pointer" in window 2, click Display
button, read "Calling and Setting
Procedure-pointer - Example".
set ... to entry ... statement
------------------------------
NetExpress Help: Click Index tab, type "procedure-pointer"
in window 1, click 2nd "Procedure-
pointer" in window 2, click Display
button, click "SET statement format 7
(procedure-pointer)" topic and click
Display button in Topics Found dialog.
Click Syntax Rules button and read.
Click General Rules button and read.
NetExpress Help: Click Find tab, type
"procedure-pointer-name" in window 1,
click "procedure-pointer-name" in window
2, click "Loading a dynamic link library"
in window 3 and click the Display button.
NOTE:
=====
A few words about the Microsoft Win32 SDK documentation. Don't expect 100% consistency in the code examples. The MessageBox function, for example, has been around since 16-bit Windows and the illustration in the SDK remains pretty much as it was originally.
int MessageBox(
HWND hWnd, // handle of owner window
LPCTSTR lpText, // address of text in message box
LPCTSTR lpCaption, // address of title of message box
UINT uType
// style of message box
);
Use the item names (hWnd, lpText, lpCaption, uType) in your COBOL program. When something goes wrong you may need to return to the SDK documentation to re-read the details on a
specific item. Using an identical or very similar COBOL name can speed up your search for information. The lower case prefix (h, lp, u) is significant. "h" is a handle. "lp" is a long pointer. "u" is an unsigned integer. In this example I've adjusted the long pointer prefix to "lpsz". This means long pointer, string zero (NULL) terminated. I've retained the "sz" as a prefix for the item that needs to be initialized to a null terminated string. Thus I end up with names for two items that clearly show they are closely related.
77 lpszText pointer.*> pointer to MessageBox Text
77 szText pic x(256). *> MessageBox Text, must be null terminated
Enjoy Programming Windows in COBOL!
==========================================================
Keywords: demonstration, sample, example, demo, win32 api, MessageBox.zip
demo.ex
demo.ne
