Calling .NET/COM server components (.NET only)

Applies to

Appeon Server for .NET.

Supported server component types

  • .NET components: All valid .NET components, including executable files (.exe) and DLL files (.dll).

    Supported parameters: primitive type parameters, such as int, vlong char, and boolean. Non-primitive type parameters, such as class, are unsupported.

    Supports reference parameters.

  • COM components: COM/COM+ components

    Supported parameters: primitive type parameters, such as byte, int, long, and float.

    Supports reference parameters.

Description

To call .NET/COM components, Appeon provides a non-autoinstantiated NVO - AppeonDotNetComponent - as the proxy object to call the server-side components. The user can either create a local instance of AppeonDotNetComponent for each server component, or directly use an existing instance of AppeonDotNetComponent. The user must specify the properties of the instance, such as the component type, the library name and the class name, to bind the instance with the server component, or change the instance properties during runtime to dynamically bind with a different component.

It provides a universal single interface and a set of parameters which determines which component and methods will be called.

Note:

The script to call AppeonDotNetComponent takes effect only after the PowerBuilder application is deployed, and has no effect when the PowerBuilder application is run.

Register

The COM component must be registered using the regsvr32 tool.

Storage location

The components must reside in the %appeon%/AEM/components folder on the Appeon Server machine. You only need to place the .tlb library files and .dll files of the COM components to the folder. %appeon% indicates the installation directory of Appeon Server.

AppeonDotNetComponent object

Properties

Properties for AppeonDotNetComponent.

Properties

Type

Description

ComponentType

String

The type of the component to be called.

"1" indicates a .NET Assembly to be called.

"2" indicates an unmanaged-code COM component to be called.

"3" indicates a managed-code COM component to be called.

"4" indicates a built-in Appeon Workaround .NET Assembly to be called.

TypeLib

String

The name of the component library. Appeon Server uses this name to find the component.

ClassDescript

String

The class name.

ReturnValue

Any

Read-only. The return value of functions. The value and value type varies from function to function.

ErrorText

String

Read-only. The error message of functions. The message varies from function to function. Empty string if no error.

Functions
of_execinterface

Description

Calls the function in the binding component.

Syntax

of_execinterface ( string interfacename {, ref any paralist[]} )

Argument

Description

interfacename

The name of the component function.

paralist[]

Optional. Arrays of Any type. Specifies the parameter arrays for the component function.

Return value

Long.

0 – Call succeeded. Gets the value from the ReturnValue property of the proxy object.

-1 – Call failed. Gets the error message from the ErrorText property of the proxy object.

Usage

Before calling this function, use the proxy object properties to bind with the target component. If the component function contains no parameters, simply specify the function name. If the component function contains parameters, define an Any type array before the call, then place the argument to the array, finally pass the array as the second parameter of the function.

Examples

Example 1: the interface contains no parameters.

AppeonDotNetComponent lu_apf

lu_apf = create AppeonDotNetComponent lu_apf
lu_apf.ComponentType = "2"
lu_apf.TypeLib = "test.dll"
lu_apf.ClassDescript = "testclass"

ll_ret = lu_apf.of_ExecInterface("test")

Example 2: the interface contains four parameters, their types are: string, int, long, and string.

// Define the array variable
AppeonDotNetComponent lu_apf
any la_1[]

la_1[1] = "Appeon"
la_1[2] = 100
la_1[3] = 256
la_1[4] = "Sybase"

lu_apf = create AppeonDotNetComponent lu_apf
lu_apf.ComponentType = "1"
lu_apf.TypeLib = "testdotnet.dll"
lu_apf.ClassDescript = "interface1"

ll_ret = lu_apf.of_ExecInterface("test_dotnet", la_1)
Events
Constructor

Description

It will be triggered when you create an instance from a user-defined proxy object inherited from AppeonDotNetComponent.

Event ID

pbm_constructor

Argument

None

Return values

Long

Usage

Do not write scripts to this event directly, because the scripts will be abandoned when the application is deployed. Instead, define and inherit an object from AppeonDotNetComponent, and add the scripts to the Constructor event of the new object. The usage is the same as that of the PowerBuilder system object. For example, you can initialize the property value of this event, or define relevant information objects.

Destructor

Description

It will be triggered when you explicitly call Destroy to destroy the instance of a user-defined proxy object inherited from AppeonDotNetComponent.

Event ID

pbm_destructor

Argument

None

Return value

Long

Usage

Do not write scripts to this event directly, because the scripts will be abandoned when the application is deployed. Instead, define and inherit an object from AppeonDotNetComponent, and add the scripts to the Destructor event of the new object. The usage is the same as that of the PowerBuilder system object. For example, you can add scripts to release the instances related with the proxy object.

Code Examples

Example 1:

long lRet
int iResult
string strError
appeondotnetcomponent comcaller

// create appeondotnetcomponent instance and set properties

comcaller = create appeondotnetcomponent
comcaller.componenttype = '1'
comcaller.typelib = 'DotNetDll.dll'
comcaller.classdescript = 'DotNetClass'

// invoke component method

lRet = comcaller.of_execinterface("GetInt")
if lRet = 0 then
iResult = comcaller.ReturnValue
else
strError = comcaller.ErrorText
end if

// Bind with a component and call the component method

comcaller.componenttype = '2'
comcaller.typelib = 'comfordotnet.dll'
comcaller.classdescript = 'ifdotnet'
comcaller.of_execinterface("getint")

Example 2:

// Call a method with reference parameters

any paralist[]
long refparam1 = 32764
long refparam2 = 32763

paralist[1] = refparam1
paralist[2] = refparam2

comcaller.componenttype = '1'
comcaller.typelib = 'DotNetDll.dll'
comcaller.classdescript = 'DotNetClass'
comcaller.of_execinterface("GetIntAndRefInt",paralist)

refparam1 = paralist[1]
rafparam2 = paralist[2]