4.5 Methods

The following section pertains only to ActiveX controls.

All ACUCOBOL-GT controls have properties and styles. In addition to properties and styles, ActiveX controls have a concept known as "methods." In ActiveX, methods (also known as object methods) specify the functions that the control provides. To invoke (call) a method, you use the MODIFY verb in much the same way as you set a property or style.

Note: Unlike common properties and styles, you cannot use the DISPLAY statement to set a special property or invoke a method of an ActiveX control defined in the Screen Section. You must use the MODIFY verb.

ActiveX methods can take any number of parameters or no parameters. They can also take optional parameters (i.e., parameters that can be omitted). You specify the parameters in COBOL by enclosing them in parentheses. The optional parameters are always last. If a method takes only one parameter, the parentheses may be omitted. If a method takes no parameters, you must use parentheses (i.e. "( )").

For example consider the ActiveX control, "Microsoft Rich Textbox Control 6.0". Here is an excerpt from its copy book, created using the AXDEFGEN utility. (See section 6.10 of Book 1, "User's Guide" for more information on using AXDEFGEN):

...
      * LoadSave constants.
      * LoadSaveConstants
           CLASS @LoadSaveConstants
               CLSID, 9FAEAB20-894B-11CE-9576-0020AF039CA3
               NAME, "LoadSaveConstants"
      * long rtfRTF
               ENUMERATOR, @rtfRtf, 0
      * long rtfText
               ENUMERATOR, @rtfText, 1
...
      * Microsoft Rich Textbox Control 6.0
      *** Primary Interface ***
      * RichTextBox
           CLASS @RichTextBox
               CLSID, 3B7C8860-D78F-101B-B9B5-04021C009402
               NAME, "RichTextBox"
...
      * LoadFile
      * Loads an .RTF file or text file into a RichTextBox control.
               METHOD, 37, @LoadFile,
                   "BSTR bstrFilename",
                   "VARIANT vFileType"
                       OPTIONAL 1
...

The LoadFile method takes two parameters: "bstrFilename" and "vFileType". "vFileType" is an OPTIONAL parameter. "bstrFileName" is a BSTR type and "vFileType" is a VARIANT type. To invoke this method from COBOL, you use the MODIFY verb:

MODIFY RICH-TEXT-BOX-1 LoadFile ("myfile.rtf", rtfRtf).

The ACUCOBOL-GT runtime automatically converts the parameters to the appropriate type and invokes the method. The LoadFile method does not have a return value. If the method had a return value that was not "void", it would be converted and moved to the item specified in the GIVING clause of the MODIFY statement. Note that the syntax is as if LoadFile is a property whose value is its parameter list. For example, the following is also valid:

MODIFY RICH-TEXT-BOX-1 PROPERTY 37 = ("myfile.rtf", rtfRtf).

Note that 37 is the "property" number of LoadFile. The equals sign is optional. Commas in the parameter list are optional. The parameters may be arithmetic expressions.