To Add an ActiveX Control or COM Object to Your ACUCOBOL-GT Program

If it is not installed already, install and register the ActiveX control or COM 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. Run the setup program if you find one. This program will likely install and register the control for you. Read the "readme" file, if one exists, for any installation and registration instructions. If you cannot find any instructions on the control, 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>
```
The “regsvr32.exe” file 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”
Use Windows Explorer to locate "axdefgen.exe". You'll find it in the \AcuGT\bin directory wherever you installed ACUCOBOL-GT on your machine (c:\Program Files\Micro Focus\extend xxx\ by default).
Double-click the AXDEFGEN icon to start the utility. A list of all the controls and COM objects currently in the local machine's Windows registry appears.
Note: You can launch "AXDEFGEN" from the command line. See AXDEFGEN Utility Reference for applicable command-line options.
Select the ActiveX control or COM object that you'd like to include in your COBOL program, then specify an output path and filename for the COPY file. Click OK when done. The utility automatically generates a COPY file for the chosen control and appends the .def filename extension to the file.
If the control or object requires a runtime license (in addition to a development license), it is automatically embedded in the .def file, and no further licensing action is required in order to use it: the .def file contains the additional LICENSE-KEY property in the *** Primary interface *** section. If you have also specified a LICENSE-KEY property within your source code, although it will not cause any problems, we recommend that you remove it and rely on AXDEFGEN to deal with the runtime licensing requirements. If you have specified a LICENSE-KEY property in your source code, it will take precedence at runtime over the one created by AXDEFGEN.

Many ActiveX controls and COM objects have documentation available. If they do, the ActiveX Help push button on the right side of this box is enabled. Click the button to read the help file for the selected ActiveX control or COM object. If the ActiveX Help push button is disabled, then AXDEFGEN could not locate a help file for the selected control.
In a code editor, open your ACUCOBOL-GT program and go to its Environment Division/Configuration Section.
Copy the new COPY file into the COBOL program's Special-Names paragraph. If you are adding several controls, copy several COPY files into this paragraph. Add a period at the end of the paragraph. For example:
```
SPECIAL-NAMES.
COPY "calendar.def".
COPY "chart.def".
```
ACUCOBOL-GT includes an acuclass.def file, which contains stock class definitions for ActiveX. We recommend that you also copy it into your program's Special-Names paragraph, as in: COPY "acuclass.def".
Add the control to your program. If you are adding a COM object, you add the object using the CREATE statement in your program's Procedure Division. For example:
```
*Create an instance of the Outlook application 
CREATE Application OF Outlook 
     HANDLE IN myOutlook 
     EVENT PROCEDURE OUTLOOK-EVENTS.
```
If you are adding an ActiveX control, however, you can do one of two things:
1. Add the new control to your screen in your program's Screen Section. For example:
```
SCREEN SECTION.
...
03 calendar-item Calendar column 5, 
   line 5, size 60, lines 20
...
```
  or
2. Create the control using the DISPLAY statement in your program's Procedure Division. 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 COPY file (".def" file) and looking at the section called "***Primary Interface***." Look for the name of the control after the word "CLASS" in the primary interface definition. If you set a property of the ActiveX control in the control property panel (thus storing it in the resource file) and that property has a corresponding ACUCOBOLGT property (e.g., ENABLED), then the COBOL program must explicitly set the corresponding ACUCOBOL-GT property in the Screen section or Procedure Division. For example, if the ActiveX ENABLED property is set to "false" in the ActiveX control property panel, then a line must be included in the initialization code of the COBOL program to set the ACUCOBOL-GT ENABLED property to "false", as in:
```
MODIFY ActiveXcontrol ENABLED FALSE
```
  Note:
  The runtime ignores events from all controls while it is creating an ActiveX control. If you are using a control that delivers significant information using events and you don't want to miss those events while you are creating a new control, set the CONTROL_CREATION_EVENTS runtime configuration variable to "1" (on, true, yes). Alternatively, you could avoid creating an ActiveX control when you are expecting an event.
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.
```
or
```
MODIFY ActiveXcontrol PROPERTY 37 = ("parameters").
```
Note that 37 is the ActiveX or COM "property" number of Property-name or Method. You can determine the property number by opening the COPY file 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 COPY file. The equal sign is optional.

To disable an ActiveX control, you use the MODIFY statement:
```
MODIFY ActiveXcontrol ENABLED FALSE.
```
If the ActiveX control has its own property named ENABLED, the MODIFY statement must explicitly set both the ACUCOBOLGT ENABLED property and the ActiveX property (@ENABLED; the "@" symbol signifies that the property is a property of the ActiveX control). For example:
```
MODIFY ActiveXcontrol ENABLED FALSE @ENABLED FALSE.
```
To enable the control:
```
MODIFY ActiveXcontrol ENABLED TRUE @ENABLED TRUE.
```
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.
```
or
```
INQUIRE ActiveXcontrol PROPERTY 37 IN value-item.
```
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 COPY file created by AXDEFGEN and looking at the section "Event Interface for the xxx Control."
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. See Distributing Applications Containing ActiveX Controls, for information about distributing an application that contains an ActiveX object.