3.8.2 Loading Bitmaps

In your program, you must load bitmap images (BMP or JPG) from disk into memory before they can be displayed as buttons. To load a bitmap, you must use the WBITMAP-LOAD operation. The call looks like this:

CALL "W$BITMAP" USING WBITMAP-LOAD, filename
 GIVING bitmap-handle

where filename is a literal or data item that holds the name of the bitmap file to load, and bitmap-handle is a PIC 9(9) COMP-4 data item. This call opens the filename file, loads the bitmap into memory and closes the file. If the operation is successful, bitmap-handle will contain a positive value. If bitmap-handle is zero or negative, an error occurred. For a complete description of W$BITMAP and all error values returned by it, see Appendix I, Book 4, "Appendices."

Note that in order to use JPG files, you must have the file "VIC32.DLL" installed in the same directory as the runtime.

If you have multiple bitmap files, you need to load each before you can use the images they contain. Make certain to store the returned handles in different data items.

W$BITMAP searches for resources before it searches for disk files. For example, the "tour.cbl" sample program contains the following lines:

COPY RESOURCE "gtanima.bmp".

CALL "W$BITMAP" USING WBITMAP-LOAD,
"gtanima.bmp" GIVING GT-BITMAP

The bitmap loaded will be the resource specified in the COPY RESOURCE statement, because the referenced file name is the same as the resource name. Note that replacing the COPY RESOURCE statement with

COPY RESOURCE "mybmps/gtanima.bmp"

would have the same effect (assuming "mybmps/gtanima.bmp" existed at compile time), because resource names do not include directory information. Also note that

CALL "W$BITMAP" USING WBITMAP-LOAD,
"mybmps/gtanima.bmp"  . . .

would not use a resource, because there would never be any matching resource name.

You can include JPG files as a resource in your COBOL programs with the COPY RESOURCE statement or by using "cblutil", in exactly the same manner as BMP files. cblutil "-info" will identify JPG resources contained within an object library.

Note: A resource name with a hyphen ("MY-FILE") is considered equivalent to the same resource name given with an underscore ("MY_FILE").

When you are done with an image and have destroyed all the buttons that reference that image, you can remove it from memory with the WBITMAP-DESTROY operation. Do not destroy an image that is referenced by an existing button; the results are unpredictable.