PxPlus COM Support 

Referencing a COM Object

 

The DEF OBJECT directive is used to create a new instance of a specified object.

DEF OBJECTobj_id ,[@( col,ln,wth,ht )]{, | = } obj_name $ [; LICENSE =key ] [; FINALIZE =method ] [, ERR= stmtref ]

Where:

@(col,ln,wth,ht)

Numeric expressions. Column and line coordinates for top left corner, width in number of columns and height in number of lines.

FINALIZE=method

Optional method name of the object instance to be run upon release of the object. See Finalize Method below.

LICENSE=key

Optional license key that should be applied when attempting to bind to an object. See Using Licensed Objects below.

obj_id

Numeric variable that will be used to save the object reference.

obj_name$

String expression identifying the object to be referenced, as well as any object-specific parameters. See Object Name Contents below.

ERR=stmtref

Optional program line number or statement label to which to transfer control in case of error. If an error occurs during the DEF OBJECT statement, the error code will always equal 12. Use the MSG(-1) function to obtain further details on the failure.

Upon successful execution of DEF OBJECT, a reference to the object obj_name$ will be placed into the supplied numeric variable obj_id. Leave out the column and line coordinates for non-visible objects. Use "*" to list all registered COM controls.

Object Name Contents

The options below may be used in the DEF OBJECT obj_name$ string. Square brackets are part of the statement's syntax (see Example Statements below).

*

Use an * asterisk to display a pop-up window listing all 32-bit COM controls installed on the system.

CLSID

Class identifier (GUID) for the object in the format {hhhhhhhh-hhhh-hhhh-hhhhhhhhhhhh}, where the h indicates a hexadecimal character.

progID

Programmatic identifier name for the object (i.e. Word.Document).

[DESIGN] filename.XML

Indicates that a previously saved OLE/ActiveX control definition should be loaded from the specified .XML file. See PVXSAVE.

[DCOM] server;name

Indicates that the object is located on a remote system.

server parameter is optional and can be specified either by name or by IP address. If not supplied, then the object is considered local.
name parameter is the CLSID or progID for the object.

[FILE] x:\filename

Indicates that the object should be created using the specified file name. An example of this would be a Microsoft Word document file.

[GETOBJECT] name

Indicates that PxPlus should bind to a running instance of the named object.

name parameter is the CLSID or progID for the object or a file-based moniker. File monikers are commonly used when dealing with WMI, LDAP and related services in Windows.

[GLOBAL] name

Indicates that a reference to an object exposed by the use of PvxMakeGlobal should be obtained.

name parameter is the name used to expose the object.

[REGISTER] x:\filename;name

Ensures that the object information is properly registered before attempting to create an instance of the object.

x:\filename parameter is the name of the executable file or library that exposes the automation object.
name parameter is the CLSID or progID for the object.

[RUNNING] name

Indicates that PxPlus should bind to a running instance of the named object, where name is given as CLSID or progID. An error occurs if the object is not currently running.

[RUNNING OR NEW] name

Indicates the same functionality as [RUNNING] syntax; however, if the object is not currently running, PxPlus attempts to create a new instance of the named object.

[PICTURE] *

Indicates creation of an empty IPicture object.

[PICTURE] filename

Indicates that an IPicture object should be created and the specified image file should be loaded by the object.

[PICTURE] * [#] name ;{ BMP | CUR | ICO }

Indicates that an IPicture object should be created and specified resource contents loaded by the object.

For numeric resources, name should be prefixed with a #; e.g. #101.
The image type is specified as the second parameter and indicates the resource group that contains the desired resource.

Using Licensed Objects

Redistribution of a third-party COM control may sometimes require the use of a license file (usually identified by a .lic extension). The license file usually permits developer-level access to the control and is not for redistribution. In some cases, a license key must be extracted from the license file in order for the control to function in run-time mode.

The following steps outline how to extract the license key from the license file and how to make it available in a run-time environment:

Once the new DEF OBJECT statement has been generated, the object reference can then be obtained on systems that do not have the license file installed.

Finalize Method

A method of the object instance can be specified to run when the object is released. This method should not require any parameters to be passed to it. This is intended to simplify the handling of automation "servers" (such as Word or Excel) that require the Quit( ) method to be executed in order to shut down the server. By specifying a finalize method, the Quit( ) method (or similar) of an object does not need to be called in order to free resources.

See Releasing an Object Reference.

Example Statements

The following are examples of DEF OBJECT statements:

DEF OBJECT X, "*"
DEF OBJECT X, "Word.Application;Finalize=Quit", ERR=*NEXT
DEF OBJECT X, @(1,1, 70, 20)="Word.Document"
DEF OBJECT X, "[DCOM]MyServer;Shell.Explorer"
DEF OBJECT X, @(10, 2, 20, 10)="[File]c:\my documents\test.doc"
DEF OBJECT X, "VCF1.VCF1Ctrl.1;License=1234567890ABCDEF..."
DEF OBJECT X, "[Running or New]Excel.Application"
DEF OBJECT X, "[Picture]*PVXHAPPY;cur"
DEF OBJECT X, @(40, 1, 40, 15) = "[Design]chartfx.xml"
DEF OBJECT X, "[GetObject]winmgmts:\\.\servername\root\cimv2" 

The DEF OBJECT statement can also be used to bind child objects, which are returned as the result of either a property access or method call. The syntax is as follows: DEF OBJECT X.