Special Properties

CLSID (alphanumeric)

This special property is provided for advanced programming tasks that require a generic interface to ActiveX controls. You may create, modify, inquire and destroy an ActiveX control using the ACTIVE-X control type, but with certain restrictions. The compiler will not recognize symbolic property, method, or event names provided by the ActiveX control. You must specify properties and methods by their dispatch identifier (dispid) using the PROPERTY phrase, and you must identify events by their dispatch identifier in your event procedure. ACTIVE-X controls are identified by a globally unique identifier called a class id (CLSID). In order to create an instance of an ACTIVE-X control, you must provide this class id. Set CLSID to the class id of the control when you create the control (either in the screen section definition or in the DISPLAY statement).

LICENSE-KEY (alphanumeric)

Some ActiveX controls are licensed for run time via a license key that is provided to you by the distributor of the control. This license key is a text string provided by the control vendor. When you set the LICENSE-KEY property to the value of the license key, you cause the license key to be embedded in your COBOL program. Then, when the COBOL program is run, the license key is passed to the ActiveX control for verification.

Note: It is not necessary to specify a LICENSE-KEY for any of the Microsoft controls included on the ACUCOBOL-GT installation CD. If you use one of these controls in your program, the runtime system applies the license key for you automatically. For a discussion of these controls, see Using ActiveX Controls and COM Objects in A Guide to Interoperating with ACUCOBOL-GT.

Getting the license key value and setting the LICENSE-KEY property is simple using AcuBench. We recommend that you use AcuBench to get the license key value even if you don't use AcuBench to create your screens. In AcuBench, when you place an ActiveX control on a screen form in the Screen Designer, the LICENSE-KEY property is automatically set to the license key value (if the vendor provided a value when the control was acquired and installed). If you use the AcuBench Screen Designer to create your screens and generate code, there is nothing more to do.

If you do not use AcuBench to create your screens, simply locate the entry for the LICENSE-KEY property in the control's Property window, and copy and assign that value to LICENSE-KEY in the Screen Section definition or DISPLAY statement of your program. For example, you might include a LICENSE-KEY property like this one: 

LICENSE-KEY "C1P0009-XPJ439-01MQ7-2223".

Note that if the license key is WideChar (WCHAR) (Doublebyte), such as 0x0067 0x01a2 0x00dd 0x0134 0x0167, you must use the STRING verb to put the license into a pic x variable; otherwise, the embedded NULLs may cause the key to be truncated or even empty. To use a key such as this, you should declare a variable like this: 

77 mLicenseKey PIC X(128).

(Note that any size will do as long as it is wide enough to hold all the characters as specified in the license plus two final NULLs.)

You should then set the variable's value. For example: 

INITIALIZE mLicenseKey REPLACING ALPHANUMERIC BY LOW-VALUES.
STRING x"00" x"67" x"01" x"a2" x"00" x"dd" x"01" x"34" x"01"
   x"67" delimited by size into mLicenseKey.

You can then invoke the ActiveX component through SCREEN SECTION or PROCEDURE DIVISION using the DISPLAY verb providing the following property: 

LICENSE-KEY mLicenseKey.

The default value of LICENSE-KEY is " ".

INITIAL-STATE (multiple parameters)

Use INITIAL-STATE in conjunction with the C$RESOURCE library routine to establish the ActiveX control's initial state. 

{ INITIAL-STATE } { Is  } ( resource-handle, resource-name )
                  { Are }
                  { =   }

where:

resource-handle     is a HANDLE OF RESOURCE
resource-name is a literal or data-item

General Rules

  • resource-handle must be the handle of an open resource file. It is obtained by calling the C$RESOURCE library routine
  • resource-name must be the name of a resource item in the resource file whose handle is specified in resource-handle
  • INITIAL-STATE is set only once per control instance. After a program creates an ActiveX control, only the first DISPLAY or MODIFY that specifies INITIAL-STATE will set it
  • INITIAL-STATE failure raises one of the following exceptions:
    ACU-E-INITIALSTATE Error reading resource item from resource file
    ACU-E-INVALIDHANDLE     Invalid control handle
    ACU-E-UNEXPECTED Unexpected error

Example

77 RES-HANDLE USAGE HANDLE OF RESOURCE

CALL "C$RESOURCE" USING CRESOURCE-LOAD, "PROGRAM1.RES"
   GIVING RES-HANDLE.

To set the ActiveX control's initial state: 

DISPLAY Calendar LINE 4 COLUMN 6 LINES 10 SIZE 40
   INITIAL-STATE (RES-HANDLE, "CALENDAR-1-INITIAL-STATE")
   HANDLE IN CALENDAR-1.

or in the screen section: 

03 CALENDAR-1 Calendar LINE 4 COLUMN 6 LINES 10 SIZE 40 
   INITIAL-STATE (RES-HANDLE, "CALENDAR-1-INITIAL-STATE").

CALENDAR-1-INITIAL-STATE is the name of a resource in PROGRAM1.RES. Its binary value is the initial state of the CALENDAR-1 ActiveX control. Note that each program that contains ActiveX controls generally has its own resource file.

Parent topic: ActiveX