Call-Out to COM

Using the COM connector, Uniface can call out to COM objects.

Note:  Call-out does not work if the COM component depends on old versions of common controls DLLs (version 5.8 and older). In this case, consider upgrading the COM component to a version that supports version 6.0 or higher.

To convert Uniface parameter types to and from the COM environment, see COM and Uniface Parameter Data Types .

Activating COM Components

COM components are activated from Uniface using the activate or newinstance ProcScript statements.

COM components are released by using the deleteinstance ProcScript statement.

For more information, see newinstance, activate and deleteinstance.

Using newinstance

The following code creates an instance of the MYOBJ component, sending the Uniface associative property list, ‘CLASS=Excel.Sheet’, to the constructor of the object. 

newinstance "MYOBJ", $2, "CLASS=Excel.Sheet"

To enable ProcScript to use the extended features of COM, the associative list can contain additional or overriding values for the new instance that is created by the COM connector.

The following are the keys for the property list:

  • CLASS—CLSID or ProgID of the desired COM class. This value overrides all other COM class specifications in the Repository and the assignment file.
  • CONTEXT—determines where the COM object is run. It can be set to one of the following values:
    • LOCAL—run the object in a separate process on the same computer
    • INPROC—run the object in the same process space as the COM client
    • REMOTE—run the object on a remote workstation
  • PASSWORD—password
  • SERVER—network workstation name at which the object should be created
  • USER—user name for the creation context. For a Microsoft Windows domain based login ID, you need to also specify the domain, for example, USER=lab\eddieg.

The class is set using the CLSID in the following way: 

newinstance "SVC4", $1,"CLASS={E7F86B89-6331-11D2-9825-006097FEA80D}"

The following example shows how to set the server, user name, and password in the property list of the newinstance statement: 

newinstance "SVC4",$1,"SERVER=CZ444; USER=lab\crew;PASSWORD=secret"

The COM class for the above example must be specified in the assignment file or the Signature Editor.

After obtaining the object instance, methods can be invoked on the object using the ->operator. For example:

ObjectName->methodname

COM Errors

If an error occurs when calling out to a COM component, Uniface generates error -150 and provides details in $procerrorcontext. Most of the information about the error is provided as a Uniface list under the ADDITIONAL ID. For example:

ERROR=-150
MNEM=<UACTERR_UNKNOWN>
 DESCRIPTION=Activation error occurred
 COMPONENT=COM_FRM
 PROCNAME=EXEC
 TRIGGER=EXEC
 LINE=3
 PROCLINE=activate VWINHTTPOBJECT."SEND"( "" ) 
 ADDITIONAL=
   INSTANCENAME=_ALIAS00000002  
   OPERATIONNAME=SEND  
   DRV=COM  
   CLASS=ICCDRV-COM-ERR Error with ICC system occurred  
   STATUS=(ICC system status: <-2147012889>)  
   MESSAGE=The COM method "Send" threw an OLE exception: HRESULT=0x80072ee7,
   description="The server name or address could not be resolved", 
   source="WinHttp.WinHttpRequest": COM error 0x80072ee7, 
   described as "Unknown error 0x80072EE7"

Stateless Components

A stateless COM component is activated by creating a single instance, calling the operation, then releasing the object. This allows stateless component functionality, even though the design of COM does not include the concept of ‘statelessness’.

Component-Object Parameters

When a COM method returns an object through a parameter, an entry is created in the Uniface instance table and a new Handle is created for the object. The ProcScript can then invoke the object via the activate statement. Because the ProcScript has ownership of the object, it must explicitly call deleteinstance on the returned Handle to free the object reference. For example: 

 $ComObj$->ReturnsAnObject($1) 
. . . 
deleteinstance $1

When a Uniface string Handle is passed to a COM method that expects an object reference for a parameter, the Uniface service is temporarily wrapped in a COM ‘shell’ and an object reference to the shell is sent.

Passing Optional Parameters

It is possible to mark a parameter of a COM Call-Out operation as optional by specifying a hyphen (-) or the string "UT_OPTIONAL". For example:

hHandle -> FIND (RESULT_, "WHAT", "UT_OPTIONAL", -, -, -, -, -, -, -)

Asynchronous Operations

Asynchronous operations are not supported. Instead, they are handled as synchronous operations.

Related Topics