Chapter 18 Jaguar ActiveX Overview

ActiveX datatype support

Table 18-1 the datatypes and argument modes supported by Jaguar Manager, and their corresponding CORBA IDL and ActiveX types. Each IDE script language uses a different syntax to represent these types. See your tool's documentation for more information.

For client development, most IDEs provide some way to view the interfaces exposed by registered automation servers. If your IDE provides an object browser, you can look up the interface for the proxy object and see it displayed in the IDE's specific syntax. For example, in Visual Basic, you can browse registered ActiveX interfaces using the Object Browser window.

For component development, you can code your component methods to use supported ActiveX datatypes, then import the DLL or type library into Jaguar Manager to define the component's IDL interface.

Argument modes specify how an argument is passed:

• in - read-only; arguments are passed by value
• inout - read/write; arguments are passed by reference
• out - write only
• return - the method returns a value of this datatype

Use in when the parameter is used to pass a value without changing the value. All parameters specified as in arguments are passed by value except for the string datatype (BSTR*). Use inout when the parameter is used to pass a value and change it. In the inout and out argument modes, the datatype of the parameter being passed must be identical to the datatype used for the same parameter in the server component method. Otherwise, no coercion is performed and an exception is thrown.

Table 18-1 the datatypes and argument modes supported by Jaguar Manager, and their corresponding CORBA IDL and ActiveX types. The ActiveX column contains ActiveX datatype specification as it is defined at runtime in the ActiveX VARIANTARG structure. The ActiveX datatypes are used by OLE automation to pass data. For information on how your IDE's datatypes correspond to these types, see your IDE's documentation.

IDL attributes are not supported by ActiveX clients.

Because the Timestamp datatype maps to the OLE date datatype, which does not represent thousandths of a second, you could lose precision when accessing a timestamp parameter from a Java component.

ResultSet or ResultSets datatypes can only be specified as a return type.

Only byte arrays are supported--no other type of array is supported. You can also use IDL sequences in lieu of arrays. The Jaguar JCollection interface is used by both clients and components to represent IDL sequences. See "Sequence support" for more information.

If you develop your component using Visual C++ and the parameter type is BSTR *, then the IDL signature for the parameter argument mode must be inout. In the IDL file, change the parameter mode to inout, regenerate and reregister the .tlb and .reg files, and modify the ActiveX client to pass the string argument by reference.

You can define get and set methods that control runtime properties for your component. However, using get and set methods to access properties over a network decreases performance.

Structure support

Jaguar component interfaces can use IDL structures as parameter types in method definitions. For example, in the home interface for an EJB entity Bean component, findByPrimaryKey method typically accepts a structure that represents the primary key for a database row.

ActiveX mapping for IDL structures

An IDL structure is mapped to an IDispatch interface, with every data member in the structure being mapped to a property in the corresponding IDispatch interface. All types supported by the ActiveX proxy are supported as members inside a structure, including structures and sequences.

If a Jaguar component interface uses IDL structures, Jaguar Manager generates IDispatch interfaces for each IDL structure when generating type libraries for the component interface definitions.

Example: using a structure in Visual Basic

bookStore::custCreditKey is an IDL structure defined in the IDL fragment below:

module bookStore
{
    struct custCreditKey
    {
        string custName;
        string creditType;
    };
};

To use this type in Visual Basic, you must first create a reference to the type library generated by Jaguar Manager to represent the bookStore IDL module. In Visual Basic code, you can create an instance of the structure and set the fields like this:

Set pKey = New bookStore.custCreditKey
pKey.creditType = "VISA"
pKey.custName = "Morry"

   Explicit version implicit field initialization Structure fields that use complex types such as struct, union, object, date, time, or timestamp must be initialized explicitly. If you do not initialize these fields before passing the union as a Jaguar method parameter or return value, the ActiveX dispatcher throws a marshalling exception. Fields of other types are implicitly set to a default value.

Union support

Jaguar maps IDL unions to an interface with properties to set and retrieve union member values.

About IDL unions

An IDL union is similar to an IDL structure, except that an instance of a union can contain a value for one field only. IDL union declarations look like this:

module TMod
  {
    union TUn switch (long)
    {
      case 5: long lVal;
      case 9, 7: short sVal;
      default: double dVal;
  };};

The declaration has a discriminator of the datatype specified by switch (typename) . Each field declaration must have a case specifier that describes the matching discriminator value. There can be one default field that applies when the discriminator matches no other value. At runtime, the union's discriminator tells which field contains the current value. In the example above, a discriminator value of seven indicates that the sVal field contains the current value.

Supported discriminator and field types

The following discriminator types are supported by the ActiveX proxy:

• signed or unsigned 2, 4 byte integers (including enumerations)
• boolean
• a typedef that aliases one of the above types
• An enumeration that switches on the IDL char type.

All IDL types presently supported by the ActiveX proxy can be used as union fields, including other unions.

IDL unions cannot have a field named discriminator, as it will conflict with the name of the discriminator variable in the generated ActiveX type.

ActiveX mapping for unions

An IDL union maps to an ActiveX interface named with the following properties and methods:

• One get/set property for each field, with the same name.
• A get/set discriminator property that represents the discriminator value. The discriminator has the ActiveX datatype that corresponds to the IDL discriminator type.

Setting and getting member values

To set a union member, simply set the property for that member. The discriminator value changes automatically to match the member you set.

To access the value of a member, first verify that the discriminator value is in the set of allowable cases for that member, then reference the matching property. The ActiveX proxy throws an exception if you attempt to access a member while the discriminator value is not in the set of case values for that member.

   Explicit version implicit field initialization Union fields that use complex types such as struct, union, object, date, time, or timestamp must be initialized explicitly. If you do not initialize these fields before passing the union as a Jaguar method parameter or return value, the ActiveX dispatcher throws a marshalling exception. Fields of other types are implicitly set to a default value.

Example

As an example, consider the following IDL union:

module TMod
  {
    union TUnion switch (long)
    {
      case 5: long lVal;
      case 9, 7: short sVal;
      default: double dVal;
  };};

The following Visual Basic code sets each member:

dim myUnion as TUnion
set myUnion = new TUnion
myUnion.lVal = 43000
myUnion.sVal = 43
myUnion.dVal = 43.43

The following code checks the discriminator and accesses the value if the lVal member is set:

if (myUnion.discriminator = 5) then
  print "Current value is " & myUnion.lVal
endif

Sequence support

Jaguar component interfaces can use IDL sequences as parameter or return types in method definitions. For example, in the home interface for an EJB entity Bean component, finder methods may return a sequence of remote interface proxies for the entity Bean.

In ActiveX clients and components, sequences are represented by the JCollection IDispatch interface. This interface is implemented by the Jaguar ActiveX proxy.

The JCollection interface is documented in Chapter 4, "ActiveX Client Interfaces", in the Jaguar CTS API Reference.

IDL typedef support

In IDL, the typedef construct defines an alias for an existing type. For example:

typedef short TShort;

short is the existing type and TShort is an alias for the same. Aliases to any type that is supported by the ActiveX proxy are supported. Nested IDL typedef declarations are supported, such as:

typedef short TShort;
typedef TShort MyKeyType;

Because ActiveX does not support type aliases, Jaguar translates each use of an IDL typedef with the equivalent ActiveX base type declaration. Alias names are not preserved in the ActiveX representation, but you can use IDL interfaces that use type aliasing.

IDL enumeration support

Enumerations represent a set of symbolic values. In IDL, an enumeration defines a set of constants that are represented by symbolic names, for example:

enum ShirtSize { xl, l, m, s }

The ActiveX proxy maps this IDL enumeration to an Microsoft IDL (MIDL) enumeration as:

typedef enum {
    xl = 0,
    1 = 1,
    m = 2,
    s = 3
} ShirtSize;

You can declare IDL enumerations globally, within a module, or within an interface. The ActiveX proxy supports only enumerations that are declared in a module or interface. Enumerations map to MIDL enumerations as follows:

• The IDL enumeration e declared in module m translates to MIDL enumeration e in type library m.
• Enumeration e declared in interface i in module m translates to MIDL enumeration i_e in type library m. MIDL does not allow enumerations to be declared inside an interface, so the interface is declared at the type-library level, and the interface and enumerations names are concatenated to avoid name collisions between like-named IDL enumerations declared in different interfaces.

In Visual Basic, you can refer to an enumeration's members as:

enum.member

Where enum is the enumeration name and member is the member name.

If your ActiveX development tool supports MIDL enumerations, you should use the symbolic member names rather than the hard coded constants. Doing so isolates your code from changes to the IDL enumeration definition.

In tools that do not support enumerations, you must use the enumeration's integer constants rather than the symbolic names. However, the constants associated with an enumeration are subject to change if the IDL definition changes. To minimize the effect of changes to your source code, declare variables and assign the constant value to them. For example:

dim shirtsize_xl as integer

shirtsize_l = 0

Result set support

A ResultSet or ResultSets datatype can be specified only as a return type or a parameter type with an out argument mode. You cannot define a method as having both a ResultSet or ResultSets return type and a ResultSet or ResultSets parameter type.

A result set is returned as a RecordSet object. After retrieving the result set, you can process it using the methods in the interfaces below. These interfaces are documented in Chapter 4, "ActiveX Client Interfaces" in the Jaguar CTS API Reference:

• RecordSet Interface - Provides methods to iterate through the rows in each result set.
• Fields Collection - Contains the Field objects that represent the columns in a row.
• Field Interface - Represents one column in a row.

     For compatibility with previous releases, you can still use GetRecordSet method to retrieve an ActiveX RecordSet interface pointer that can be used to retrieve the row results.

Algorithm to retrieve result sets

The pseudocode below illustrates a typical algorithm for retrieving result sets using a RecordSet object. getEmployeeDetails() is a method in the component that returns a single result set as a RecordSet object. The algorithm executes three nested loops, as follows:

• The outermost loop iterates through RecordSet objects. Each object contains rows from one result set. After rows have been retrieved, the example calls the RecordSet.NextRecordSet method. This method returns the next RecordSet object. The outermost loop terminates when RecordSet.NextRecordSet has set the RecordSet.EOF property to true.
• The middle loop iterates through the rows in a result set, calling the RecordSet.MoveNext method until the RecordSet.EOF property tests as true. Inside the loop, the RecordSet.Fields property provides a Fields object that allows access to the row's columns.
• The innermost loop iterates through the columns in a row, using the Fields.Item property to retrieve the Field object that represents each column.

Here is the algorithm:

Integer employee_id
RecordSet = proxycomponent.getEmployeeDetails(employee_id)

DO
    // Position the row pointer before the first row.
    RecordSet.MoveFirst()

    // Iterate through all the rows.
    WHILE RecordSet.EOF = FALSE
       
       // Fields object represents the current row.
       Fields = RecordSet.Fields

       // Iterate through columns.
       FOR i = 0 TO i = (Fields.Count - 1)

           Field = Fields.Item(i)

           ... retrieve Field  properties to process column 
               data as desired ...

       END FOR

       // Move to the next row.
       RecordSet.MoveNext()

    END WHILE

    // Move to the next result set, if any.
    RecordSet = RecordSet.NextRecordSet()

WHILE RecordSet.EOF = FALSE

The logic in this example executes correctly if a method has not returned result sets. In this case, the RecordSet.EOF property is always false.

Some scripting languages may allow or require variations on this algorithm, for example:

• You can replace the WHILE loop logic that iterates through rows with a FOR loop that indexes from 1 to RecordSet.Count.
• Some scripting languages provide a FOR EACH loop syntax that allows iterations over an ActiveX collection. You can use this construct to iterate through the Field objects in a Fields collection. For example, in Microsoft Visual Basic, you can use code similar to this:
  

  'Get the collection of fields from record set           

  
  
  

  Set flds = recset.Fields
  For Each fld in flds 
      'Process each Field as desired 
  Next fld

  
  

Copyright © 2000 Sybase, Inc. All rights reserved.