Chapter 12 Calling Jaguar Component Methods from PowerDynamo

Calling Jaguar components from a PowerDynamo script

You can call Jaguar components from within a PowerDynamo script by using:

• The Dynamo SQL tag (must return a result set)
• The Dynamo COMPONENT tag (may return a result set)
• The connection.CreateQuery method (must return a result set)
• The connection.CreateComponent method (must return a result set)
• The java.CreateComponent method (no restriction on the return)
• The java.GetUserTransaction method (allows access to the UserTransaction object of Jaguar components participating in a transaction)
• The java.GetHomeInterface method (allows access to EJB home interface of Jaguar components)
• An ActiveX object through the PowerDynamo CreateObject method (no restriction on the return)

The SQL tag, COMPONENT tag, connection.CreateQuery method and the connection.CreateComponent methods allow Dynamo to call Jaguar components as though they were Methods As Stored Procedures (MASP). Each MASP invocation creates an instance of the component, invokes the method and then destroys the component instance.

Jaguar client software
If you will be calling Jaguar components from PowerDynamo, ensure that you have installed the client software (select Runtime), when installing Jaguar.

For more information on MASP, see the Jaguar Programmer's Guide.

The Dynamo SQL tag (MASP)

Description

You can use the PowerDynamo SQL tag to make Methods As Stored Procedures (MASP) calls. You can use the normal SQL tag attributes when calling a MASP with the SQL tag. For a list of these attributes, see "The SQL tag" in PowerDynamo Reference.

Syntax

<!--SQL

    exec packageName.componentName.methodName [parameters]

-->

Example

The following example makes a MASP method call to the SVUEnrollment component, which resides in the SVU package. The method being called is getMajors . No parameters are being passed in.

<!--SQL
    exec SVU.SVUEnrollment.getMajors
-->
<!--FORMATTING-->
<!--/FORMATTING-->

The SVUEnrollment component contains several methods, one of which is getMajors . These methods can all be called as MASP methods by the SQL tag. The only restriction on calling a MASP with the SQL tag is that the return must be a result set. If the component method contains inout or output parameters, the output of these parameters will not be available.

The MASP being called in the following example requires that parameters be passed in order for the method to execute. In this case, a first and last name are required as well as a phone number.

<!--SQL 
     exec Demo_Components.PhoneList.addPhoneList Tammy, Black, (519)873-2243
-->

These examples assume that the connection for the script has been set to the Jaguar server.

For more information on the SQL tag, see "The SQL tag" in PowerDynamo Reference.

The Dynamo COMPONENT tag

Description

Using the Dynamo COMPONENT tag is similar to the way in which the SQL tag is used to call Jaguar components except that the package, component, and method are clearly labeled. The attributes normally associated with the SQL tag can also be used with the COMPONENT tag. For a list of these attributes, see "The COMPONENT tag" in PowerDynamo Reference.

Although you can use the COMPONENT tag for ActiveX and Java access, the instance of that component exists only until the end of the COMPONENT tag.

COMPONENT name for the returned value
The default name of the returned value when using the COMPONENT tag is COMPONENT, in the same way that the default name of the query object is SQL when using the SQL tag.

Syntax

For SQL access (MASP):

<!--COMPONENT ACCESS_METHOD= SQL PKG=packagename COMPONENT_NAME=componentname METHOD=methodname 

parameter(s)

-->

For ActiveX access (no restriction on the return):

<!--COMPONENT ACCESS_METHOD= ACTIVEX PKG=packagename COMPONENT_NAME=componentname METHOD=methodname HOST=hostname

parameter(s)

-->

For Java access (no restriction on the return):

<!--COMPONENT ACCESS_METHOD= JAVA PKG=packagename COMPONENT_NAME=componentname METHOD=methodname MANAGER_URL=url USERID=id PASSWORD=password NARROW_INTERFACE=narrowinterface

parameter(s)

-->

Example

Here is an example of a MASP being called from within a Dynamo script using the Dynamo COMPONENT tag. You can use the FORMATTING tags to move through the result set:

<!--COMPONENT PKG=SVU COMPONENT_NAME=SVUEnrollment METHOD=getMajors
-->
<!--FORMATTING NAME=COMPONENT-->
<!--/FORMATTING-->

For more information on the COMPONENT tag, see "The COMPONENT tag" in PowerDynamo Reference.

The connection.CreateQuery method (MASP)

Description

The connection.CreateQuery method executes a MASP and returns a query object that you can use to move through the result set. This is a method of the DynaScript scripting language.

Syntax

<!--SCRIPT

    queryObjectName = connection.CreateQuery( "exec packageName.ComponentName.methodName"  );

-->

Example

The following example uses the connection.CreateQuery method to call a Jaguar MASP:

<!--SCRIPT 
    queryObject = connection.CreateQuery( "exec SVU.SVUEnrollment.getMajors"  );
-->
<!--FORMATTING NAME=queryObject-->
<!--/FORMATTING-->

This example uses connection.CreateQuery to call a MASP that adds new users to a phone list:

<!--SCRIPT 
connection.CreateQuery("exec Demo_Components.PhoneList.addPhoneList Nicole LaChance (519)873-2243");
-->

For more information, see "CreateQuery method" in PowerDynamo Reference.

The connection.CreateComponent method (MASP)

Description

The connection.CreateComponent method executes a MASP and returns a component object. You can then call methods of the component object that will return a query object.

Syntax

<!--SCRIPT

    componentObject = connection.CreateComponent( "packageName", "componentName" );

    componentObject.methodName (parameters);

-->

Example

This example uses the connection.CreateComponent method to create an instance of the SVUEnrollment Jaguar component and to then call the getMajors method of that component:

<!--SCRIPT 
    myJagComponent = connection.CreateComponent( "SVU", "SVUEnrollment" );
    queryObject = myJagComponent.getMajors();
-->
<!--FORMATTING NAME=queryObject-->
<!--/FORMATTING-->

The following example uses connection.CreateComponent to call a MASP that adds a new user to the phone list:

<!--SCRIPT 
    myComp = connection.CreateComponent( "Demo_Components", "PhoneList" );
    myComp.addPhoneList ( "Zachary", "Graham", "(519)873-2763" );
-->

For more information, see "CreateComponent method" in PowerDynamo Reference.

The java.CreateComponent method

Description

You can use the PowerDynamo java.CreateComponent method to create an instance of a Java object. Once you have created a Java object, you can call its methods in the same manner as a normal DynaScript object.

Syntax

<!--SCRIPT

javaObj = java.CreateComponent( component_name [, manager_url, id, password, narrowing_component] )

-->

Example

The following example creates an instance of the SVU/SVUEnrollment component called comp . Once the object is created, its method getMajors is called and the Record Set is displayed:

<!--SCRIPT 
    comp = java.CreateComponent( "SVU/SVUEnrollment" ); 
    RecordSet = comp.getMajors();
    query = java.CallStaticMethod( "com.sybase.CORBA.jdbc11.SQL", "getResultSet", RecordSet );
    received = query.next();
    i = 0;
    while( received ) {
        metadata = query.getMetaData();
        document.writeln( "*****" );
        columns = metadata.getColumnCount();
        for( j = 1; j <= columns; j++ ) {
           value = query.getString( j );
           document.writeln( value );
        }
        received = query.next();
        i++;
    }
-->
</HTML>

For more information, see "CreateComponent method" in PowerDynamo Reference.

This example creates an instance of the SVU/SVUEnrollment component called comp from a machine called testMachine. Once the object is created, its method getMajors is called and the Record Set is displayed:

<!--SCRIPT 
    comp = java.CreateComponent( "SVU/SVUEnrollment", "iiop://testMachine:9000", "guest", "" ); 
    
    RecordSet = comp.getMajors();
    query = java.CallStaticMethod( "com.sybase.CORBA.jdbc11.SQL", "getResultSet", RecordSet );
    received = query.next();
    i = 0;
    while( received ) {
        metadata = query.getMetaData();
        document.writeln( "*****" );
        columns = metadata.getColumnCount();
        for( j = 1; j <= columns; j++ ) {
           value = query.getString( j );
           document.writeln( value );
        }
        received = query.next();
        i++;
    }
-->

For information on tabular results see, "Working with Tabular Results".

GetHomeInterface method

Description

Allows access to the EJBHome interface for a Jaguar component.

Syntax

java.GetHomeInterface(component_name [, provider_url, user_id, password] )

The parameters are:

• component_name The name of the component to instantiate. Component names are composed as follows:
  [<server-context>]<package>/<comp>
  
  • server-context - The root naming context for the server where the component is installed. server-context is optional and necessary only if a root naming context has been set for the server. The root naming context can also be given as the initial context in the provider_url.
  • package - The Jaguar package to which the component belongs, as displayed in Jaguar Manager.
  • component - The component name, as displayed in Jaguar Manager.
  
  
• You can view and edit this setting using the Naming Service tab of the Server Properties window from Jaguar Manager. The default for a new server is "/". If you specified an initial name context in GetHomeInterface()'s provider_url parameter, then the server context is assumed to be relative to this initial name context. For example, if the provider_url parameter is set to iiop://localhost:9000/USA/Sybase, and your server's root context is USA/Sybase/Engineering, then you can resolve component names as Engineering/package/component.
• provider_url The provider_url is optional and defaults to "iiop://localhost:9000". If used, it identifies the URL of the JNDI name server. This parameter should be of the form iiop://<hostname>[:<iiop-port>][/<initial-context>] where:
  
  • hostname Is the host machine name for the Jaguar server that serves as the name server for your application.
  • iiop-port Is the IIOP port number for the server.
  • initial-context Is the optional initial naming context, which can be used to set a default prefix for name resolution. For example, if you specify USA/Sybase/, then the component_name parameter is assumed to be relative to this location in the name hierarchy. When specifying the initial context, the trailing slash is optional; it is added automatically if you do not specify an initial context that ends with a slash.
  
  
• user_id The user name for the Jaguar session. If authorization is enabled for your Jaguar server, this parameter is used to authorize access to Jaguar components.
  The user_id parameter is optional and defaults to "guest".
  
• password The password for the Jaguar session. If authorization is enabled for your Jaguar server, the password is used to authorize access to Jaguar components.
  The password parameter is optional and default is no password.
  

   The Dynamo methods GetHomeInterface and GetUserTransaction enable access to EJB interfaces of Jaguar components.

Example

Use java.GetHomeInterface to create an instance of the EJBHome interface for the component Test/Cart . Then use the Home interface to create an actual instance of Test/Cart .

carthomeObj = java.GetHomeInterface("CartPackage/Cart")    cartObj = carthomeObj.create("John", "7506");    cartObj.addItem(66)    cartObj.addItem(22)    cartObj.purchase()    carthomeObj.remove(...)

See also

The PowerDynamo Reference Manual.

GetUserTransaction method

Description

Allows access to the EJB UserTransaction object.

Syntax

java.GetUserTransaction(  [ <provider_url>, <user_id>, <password>] )

The parameters are:

• provider_url The provider_url is optional and defaults to "iiop://localhost:9000". It identifies the URL of the JNDI name server. This parameter should be of the form iiop://<hostname>[:<iiop-port>][/<initial-context>] where:
  
  • hostname Is the host machine name for the Jaguar server that serves as the name server for your application.
  • iiop-port Is the IIOP port number for the server.
  • initial-context Is the optional initial naming context, which can be used to set a default prefix for name resolution. For example, if you specify USA/Sybase/, all names that you resolve with the context are assumed to be relative to this location in the name hierarchy. When specifying the initial context, the trailing slash is optional; it is added automatically if you do not specify an initial context that ends with a slash.
  
  
• user_id The user name for the Jaguar session. If authorization is enabled for your Jaguar server this optional parameter, which defaults to "guest", is used to authorize access to Jaguar components.
• password The password for the Jaguar session. If authorization is enabled for your Jaguar server, this optional parameter, which defaults to no password, is used to authorize access to Jaguar components.

   The Dynamo methods GetHomeInterface and GetUserTransaction enable access to EJB interfaces of Jaguar components.

Comments

The components that participate in the transaction managed with the UserTransaction object must be in the same server as the UserTransaction object, which cannot be assumed if a Jaguar cluster is used to ensure that this requirement is met:

1. Use the same name server to create the UserTransaction object that was used when creating the component instances. That is, supply the same provider_url to GetUserTransaction() and GetHomeInterface() , CreateComponent() . The initial-context values of the URLs can differ.
2. Get the UserTransaction object and begin the transaction before creating any component instances.
3. In addition, follow the same restrictions as other Java clients when using the UserTransaction object. Refer to the Jaguar CTS Programmer's Guide and Jaguar CTS Reference Manual for details.

The UserTransaction interface defines exceptions that are thrown when errors occur. For example, TransactionRolledbackException is thrown when commit() is called after setRollbackOnly() has already been called for a transaction.

As many of the methods in the UserTransaction interface for example, return void, begin() , commit() , rollback() , these exceptions are the only way to detect errors.

In DynaScript, exceptions are passed to the user through the site.GetErrorInfo() method. That is, the exception is converted to an error string. For example:

    ut.begin()
    ...
    ut.commit()
    errMsg = site.GetErrorInfo();
    if ((errMsg != null) && (errMsg != ""))
    {
        /* the transaction was not committed */
    }

The UserTransaction.getStatus() method returns an integer value indicating the status of the current transaction. Dynamo users can include the script ~/system/utils/usertran.ssc to get the definitions of variables that map to the integer values returned by getStatus() .

    import "~/system/utils/usertran.ssc"

    ...

    ut = java.GetUserTransaction(...);
    ut.begin()
    status = ut.getStatus();
    if (status != UserTran.STATUS_ACTIVE)
    {        /* the transaction was not started */    }
    ...

Example

Use java.GetUserTransaction to get the UserTransaction object, instantiate the components that will participate in the transaction, begin the transaction, perform the operations required in the transaction, and commit the transaction.

    ut = java.GetUserTransaction("iiop://my-host:9000")
    acctHome = java.GetHomeInterface("Bank/Account", "iiop://my-host:9000")
    acct1 = acctHome.create("John", "Doe", "111-11-1111")
    acct2 = acctHome.create("Jane", "Doe", "222-22-2222")
    acct3 = = java.CreateComponent("Bank/Account", "iiop://my-host:9000")
    ut.begin();
    errMsg = site.GetErrorInfo();
    if ((errMsg != null) && (errMsg != ""))
    {
        /* handle error, the transaction did not begin return
    }
    acct1.withdraw(100);
    acct2.deposit(50);
    acct3.deposit(50);
    ut.commit();
    errMsg = site.GetErrorInfo();
    if ((errMsg != null) && (errMsg != ""))
    {
        /* handle error, the transaction did not commit return
    }

See also

The PowerDynamo Reference Manual.

The PowerDynamo CreateObject method

Description

You can use the PowerDynamo CreateObject method to create an instance of an ActiveX object. Once an ActiveX object has been created, its methods may be called in the same manner as a normal DynaScript object. An ActiveX object exists until it goes out of scope or until the ActiveX variable is assigned a new value.

Syntax

<!--SCRIPT

objectName=CreateObject("packageName.componentName");

[objectName.Host("machineName:portNumber");

objectName.UserName="jagadmin";

objectName.Password="";

objectName.Name="packageName_1/componentName_1"]

objectName.Initialize();

output=objectName.methodName(parameter);

-->

The Host, UserName, and Password are all optional properties, depending on the scenario in which you are creating your instance of an ActiveX object.

• Host By default, host is set to localhost:9000. If the Jaguar server is running on a different machine or the port number is a value other than 9000, you must set this property accordingly.
• UserName and Password The user name and password are optional properties unless you are working with components that have had component level security specified using Roles.
• Name The name property is optional if the package name is the same as the module name and the component name is the same as the interface name.

For more information on working with ActiveX and Jaguar, see the Jaguar Programmer's Guide.

Example

This example creates an instance of an ActiveX object called comp . Once the object is created, its method getMajors is called and the Record Set is displayed:

<!--SCRIPT 
    comp = CreateObject( "SVU.SVUEnrollment" );    
    comp.Initialize();
    RecordSet = comp.getMajors();
    RecordSet.MoveFirst();
    while( !RecordSet.EOF ) {
        document.writeln( "*****" );
        fields = RecordSet.Fields;
        columns = fields.Count;
        for( j = 0; j < columns; j++ ) {
            field = fields.Item(j);
            document.writeln( field.Value );
        }
        RecordSet.MoveNext();
    }
-->

This example creates an instance of an ActiveX object called comp that resides on a machine called testMachine. Once the Object is created, its method getMajors is called and the Record Set is displayed:

<!--SCRIPT 
    comp = CreateObject( "SVU.SVUEnrollment" );    
    comp.Host = "testMachine:9000";
    comp.Initialize();
    RecordSet = comp.getMajors();
    RecordSet.MoveFirst();
    while( !RecordSet.EOF ) {
        document.writeln( "*****" );
        fields = RecordSet.Fields;
        columns = fields.Count;
        for( j = 0; j < columns; j++ ) {
            field = fields.Item( j );
            document.writeln( field.Value );
        }
        RecordSet.MoveNext();
    }
-->

For more information about the CreateObject method, see "Built-in functions" in PowerDynamo Reference.

For information on ADO record sets see "Working with ADO record sets as PowerDynamo query objects".

Copyright © 1999 Sybase, Inc. All rights reserved.