To add an ActiveX control or OLE object to your ACUCOBOL-GT program

1. If it is not installed already, install and register the ActiveX control or OLE object of interest on your development system.

Complex controls may come with their own setup programs, licensing, and registration wizards. Look for a setup program or "readme" file in the directory containing the control. If there is a setup program, run it. This program will likely install and register the control for you. If there is a "readme" file, read it. This file will contain installation and registration instructions. If you cannot find any instructions on the control on your computer, you can also visit the control vendor's Web site.

For simple controls, you can usually accomplish installation and registration by copying the ActiveX control files (at least a ".ocx" or ".dll" file) to your hard disk and executing the following command:

regsvr32 <ocx or dll name>

"regsvr32.exe" is normally located in your \windows\system directory. Do not assume that it is in your search path. Even if the control is already installed on your machine--for instance, if it came with other software that you've purchased--you may still need to register the control with "regsvr32.exe".

2. Use Windows Explorer to locate "AXDEFGEN.EXE". You'll find it in the \AcuGT\bin directory wherever you installed ACUCOBOL-GT on your machine (\acucorp\acucbl500\AcuGT\bin by default).

3. Double-click the AXDEFGEN icon to start the utility. A list of all the controls and OLE objects currently in the local machine's Windows registry displays. (If desired, you can launch "AXDEFGEN" from the command line. Refer to section 3.7 of this book for applicable command line options.)

4. Select the ActiveX control or OLE object that you'd like to include in your COBOL program, then specify an output path and filename for the copybook file. Click "OK" when done. The utility automatically generates a copybook for the chosen control and appends the filename extension, ".def" to the file.

Note: Many ActiveX controls and OLE objects have documentation available. If they do, the "ActiveX Help" button on the right of this box is enabled. Click the button to read the help file for the selected ActiveX control or OLE object. If the "ActiveX Help" button is disabled, it means that AXDEFGEN could not locate a help file for the selected control.

5. In a code editor, open your ACUCOBOL-GT program and go to its ENVIRONMENT DIVISION/CONFIGURATION SECTION.

6. Copy the new copybook into the COBOL program's SPECIAL-NAMES paragraph. If you are adding several controls, copy several copybooks into this paragraph. Add a period at the end of the paragraph. For example:

SPECIAL-NAMES
copy "calendar.def"
copy "chart.def"
.

Note: ACUCOBOL-GT Version 5.0 includes an "ACUCLASS.DEF" file that contains stock class definitions for ActiveX. We recommend that you copy it into your program's SPECIAL-NAMES paragraph as well, as in:

copy "acuclass.def" .

7. Add the control to your program. You can do this in one of two ways:

a) Go the SCREEN SECTION of your program and add the new control to your screen. For example:

SCREEN SECTION

...

03 calendar-item Calendar column 5, line 5, size 60, lines 20

...

b) Go to your program's PROCEDURE DIVISION and create the control using the DISPLAY statement. For example:

* Declare the calendar control's handle.
   77 CALENDAR-1 USAGE IS HANDLE OF Calendar.
   ...
   * Create an instance of the calendar control
          DISPLAY Calendar LINE 4 COLUMN 6 LINES 10 SIZE 40
                 EVENT PROCEDURE IS CALENDAR-EVENT-HANDLER
                 HANDLE IN CALENDAR-1.

You can determine the name of the control by opening the copybook (".def" file) and looking at the section called "***Primary Interface***." You will find the name of the control after the word "CLASS" in the primary interface definition.

8. If desired, you can modify a control's properties or invoke methods using the MODIFY verb as in the following example.

MODIFY ActiveXcontrol Method ("parameters").

MODIFY ActiveXcontrol Property-name = property-value.

MODIFY ActiveXcontrol PROPERTY 37 = ("parameters").

Note that 37 is the ActiveX or OLE "property" number of property-name or Method. You can determine the property number by opening the copybook and searching for the name of the property or method. The "property" number, also known as the dispatch id or dispid, precedes the name in the copybook. The equal sign is optional.

To inquire about the value of one of a control's properties, use the INQUIRE verb, as in:

INQUIRE ActiveXcontrol Property-name IN value-item.

INQUIRE ActiveXcontrol PROPERTY 37 IN value-item.

9. If desired, modify your program to respond to one of the control's events, e.g., a mouse click. For example:

calendar-1-event.

   evaluate event-type

      when msg-ax-event

         evaluate event-data-2

            when CalendarClick

               Perform ...

         end-evaluate.
      ...
   end-evaluate.

You can view a list of control events by opening the copybook created by AXDEFGEN and looking at the section "Event Interface for the xxx Control."

10. Compile and run your modified program.

Note: In order for the control to work on your end user's machine, it must be installed and registered. If you are licensed to do so, you can distribute the control along with your application. Refer to section 10.9 for information distributing an application that contains an ActiveX object.