CreateInstance

Creates an instance of a remote object running on a middle-tier server.

To create a remote object instance

Use

From a PowerBuilder client

Syntax 1 For creating an object instance on a remote server

From within an EAServer or COM+ component

Syntax 2 For creating a component instance on the current server


Syntax 1 For creating an object instance on a remote server

Description

Creates an instance of a component running on EAServer. This function can be used to instantiate a remote object from a PowerBuilder client. In addition, it can be used within a component running on EAServer to instantiate another component running on a different server.

Applies to

Connection objects

Syntax

connection.CreateInstance (objectvariable {, classname } )

Argument

Description

connection

The name of the Connection object used to establish the connection.

objectvariable

A global, instance, or local variable whose datatype is the same class as the object being created or an ancestor of that class.

classname (optional)

A string whose value is the name of the class datatype to be created. You can optionally prepend a package name followed by a slash to the class name (for example, "mypkg/mycomponent").

Returns

Long. Returns 0 if it succeeds and one of the following values if an error occurs:

Usage

Before calling CreateInstance, you need to connect to a server. To do this, you need to call the ConnectToServer function.

CreateInstance allows you to create an object on a remote server. If you want to create an object locally, you need to use the CREATE statement.

When you deploy a remote object’s class definition in a client application, the definition on the client has the same name as the remote object definition deployed in the server application. Variables declared with this type are able to hold a reference to a local object or a remote object. Therefore, at execution time you can instantiate the object locally (with the CREATE statement) or remotely (with the CreateInstance function) depending on your application requirements. In either case, once you have created the object, its physical location is transparent to client-side scripts that use the object.

Examples

Example 1

The following statements create an object locally or remotely depending on the outcome of a test. The statements use the CreateInstance function to create a remote object and the CREATE statement to create a local object:

boolean bWantRemote

connection myconnect

uo_customer iuo_customer


//Determine whether you want a remote

//object or a local object.

...

//Then create the object.

IF bWantRemote THEN

    //Create a remote object

    IF myconnect.CreateInstance(iuo_customer) <> 0 THEN

      //deal with the error

      ...

    END IF

ELSE

    //Create a local object

    iuo_customer = CREATE uo_customer

END IF


//Call a function of the object.

//The function call is the same whether the object was

//created on the server or the client.

IF isValid(iou_customer) THEN

    iuo_customer.GetCustomerData()

END IF

See also

ConnectToServer


Syntax 2 For creating a component instance on the current server

Description

Creates an instance of a component running on the current EAServer or COM+ server. This function is called from within a component instance running on EAServer or COM+.

Applies to

TransactionServer objects

Syntax

transactionserver.CreateInstance (objectvariable {, classname } )

Argument

Description

transactionserver

Reference to the TransactionServer service instance.

objectvariable

A global, instance, or local variable whose datatype is the same class as the object being created or an ancestor of that class.

classname (optional)

A string whose value is the name of the class datatype to be created.

For EAServer components, you can optionally prepend a package name followed by a slash to the class name (for example, "mypackage/mycomponent").

For COM+ components, you can optionally prepend a ProgID followed by a period to the class name (for example, "PowerBuilder.HTMLDataWindow".

Returns

Long. Returns 0 if it succeeds and one of the following values if an error occurs:

Usage

The CreateInstance function on the TransactionServer context object allows you to access other EAServer or COM+ components running on the current server. The created instance inherits all the transaction and security attributes of the current object.

On EAServer, the TransactionServer CreateInstance method invokes the EAServer name service to create proxies. Proxies for remote components might be returned by the name service rather than an instance that is running locally. To guarantee that a locally installed instance is used, specify the component name as “local:package/component”, where package is the package name and component is the component name. The call fails if the component is not installed in the same server.

The CreateInstance function on the TransactionServer context object uses the same user and password information that applies to the component from which it is called.

Before you can use the transaction context service, you need to declare a variable of type TransactionServer and call the GetContextService function to create an instance of the service.

Examples

Example 2

The following statements show how an EAServer component might instantiate another component in the same server and call one of its methods:

Integer rc

rc = this.GetContextService("TransactionServer", &

    ts)

IF rc <> 1 THEN

    // handle the error

END IF

rc = this.CreateInstance(mycomp2, &

    "mypackage/nvo_comp2")


IF IsValid(mycomp2) = FALSE THEN

    // handle the error

END IF

mycomp2.method1()

Example 3

This example shows the syntax for creating an instance of a COM component:

Integer rc
OleObject lole
TransactionServer lts

lole = create OleObject
rc = this.GetContextService("TransactionServer", lts)
IF rc <> 1 THEN
   return "Error from GetContextService " + String (rc)
END IF

// PBCOM is the ProgID, n_genapp is the class name
rc = lts.CreateInstance(lole, "PBCOM.n_genapp")

IF rc <> 0 THEN
   return "Error from CreateInstance " + String (rc)
END IF
iole.my_func ()

See also