Compaq TP Desktop Connector
Getting Started


Previous Contents Index

7.2 Automation Objects and STDL Support

The TP Desktop Connector software provides Automation objects and the STDL compiler generates Automation objects for the client interface. Sections 7.2.1 to 7.2.3 describe the objects and their properties.

7.2.1 Standard Objects

The following standard Automation objects are supplied with TP Desktop Connector software:


STDL.stdl_einfo 
STDL.stdl_uuid 

These objects are installed when you install the TP Desktop Connector software.

The STDL.stdl_einfo object is used to store STDL status information in a Microsoft Automation environment. This object has the following Automation properties described using Visual Basic data types:


eclass  AS LONG 
ecode   AS LONG 
eproc   AS STRING 
epgroup AS STRING 
esource AS STRING 
ecgroup AS STDL.stdl_uuid 

The STDL.stdl_uuid object is used to store the STDL universal unique identifier (UUID). This object has the following Automation properties described using a Visual Basic data type:


uuid_string AS STRING 

7.2.2 STDL-Generated Automation Objects

The STDL compiler generates Automation objects based on the contents of the task group specification. The Automation client maps a task group to an Automation object as follows:

The Automation object generated for a group has a name in the following format:

group.Group

The compiler derives the value for group by converting the STDL name to lowercase and replacing any hyphen characters (-) with underscore characters (_).

Within the group Automation object, the STDL compiler creates a method for each task in the task group specification.

TP Desktop Connector software uses Automation objects to model STDL records. Because Automation does not directly support records, the STDL compiler generates an Automation object for each record used as an argument by a task in the task group being called.

The Automation object for each record has a name in the following format:

group.record-name

The compiler creates one of these objects in each of the following cases:

The compiler creates an object for each argument to be passed to a task. If an STDL record is used for more than one argument or is included in more than one other STDL record, the compiler generates only one STDL record object.

For each field within the record, the object has one Automation property. The property name is derived from the STDL field name and the type of the property depends on the STDL field type (see Section 7.2.3).

You can use an object browser (for example, the Visual Basic object viewer) to examine objects defined by the generated Automation server.

7.2.3 Automation Data Type Support

When the STDL compiler generates an Automation object for each STDL record (see Section 7.2.2), each field from an STDL record is represented by a property within the generated record object. The type of the property is determined by the STDL data type of the field as shown in Table 7-3.

Table 7-3 Automation Data Type Mapping
  Automation Data Type
STDL Data Type C Visual Basic
ARRAY 1 1
DATE DATE DATE
DECIMAL STRING BSTR STRING
FLOAT SIZE 4 float SINGLE
FLOAT SIZE 8 double DOUBLE
INTEGER SIZE 1 short INTEGER
INTEGER SIZE 2 short INTEGER
INTEGER SIZE 4 long LONG
OCTET unsigned char BYTE
RECORD Record object 2 Record object 2
TEXT CHARACTER SET ISO-LATIN-1 BSTR STRING
TEXT CHARACTER SET ISO-LATIN-2 3 3
TEXT CHARACTER SET ISO-UCS-2 3 3
TEXT CHARACTER SET KANJI BSTR STRING
TEXT CHARACTER SET KATAKANA 3 3
UNSIGNED INTEGER SIZE 1 unsigned char BYTE
UNSIGNED INTEGER SIZE 2 short INTEGER
UNSIGNED INTEGER SIZE 4 long LONG
UUID BSTR STRING


1Array references are to the base data type starting with an index of zero.
2An Automation object for the record is created (see Section 7.2.2).
3This data type support is not implemented.

7.3 Calling Tasks from Automation Clients

To call tasks within a task group, write the Automation client so that it performs the following actions:

  1. If the client is written in Visual Basic, it imports the task group type library having a name in the following format:


    group Type Library for ActiveX Access 
    

  2. Creates an object for each record to be passed to the task.
    This is done by referencing the record object name (group.record-name) in one of the following ways:
    For example, for the add_number record in the add_task_group, the object name is add_task_group.add_number.
  3. Fills in data in the record objects as necessary.
    The fields within the record objects are referenced as attributes of the created record object.
  4. Creates an object for the task group in one of the following ways:
  5. Optionally sets the call attributes string.
  6. Within the task group object, calls the task as a method.
  7. Checks the exception information contained in the group object for the status of the call to the task.

7.4 Specifying the Call Attributes String

Automation clients specify call attributes by referencing an Automation property on the group object. This property has the name call_attributes.

When a new group object is created, the call_attributes property is null. The Automation client can set the call_attributes property for use on subsequent method calls using that group object. If the Automation client provides a new call attributes string, the new string overwrites the old string. If the Automation client sets the call attributes string to null, then subsequent method calls on that object will have no call attributes string.

The Automation input adapter does not interpret the contents of the call attributes string. Any error in the contents of the call attributes string is not returned until the next call using that group object.

If an error occurs in the group_set procedure, the error is returned in the einfo structure.

For more information on passing call attributes, see Section 3.3.

7.5 Automation Runtime Errors

Automation runtime error values are returned using a 32-bit number known as a result handle (HRESULT). Microsoft defines the structure of the HRESULT value. Automation errors returned by TP Desktop Connector begin at the HRESULT value 0x80041001. To determine an STDL error code from the HRESULT format, subtract 0x80041000 from the Automation error code value:

STDL-error-code = <Automation-error-code-value> - 0x80041000

STDL error codes and their corresponding messages are described in the stdlrt_msg.h message file, located in a directory with a name in the following format:

install-directory\stdl\include

For example, if you installed the product in the C:\tpware directory, then the STDL message file is located at:


c:\tpware\stdl\include\stdlrt_msg.h 

7.6 Next Steps

After you build and debug the client, set up the management environment for the client:

  1. Use the management utility to establish runtime parameters.
  2. Set up error logging for the client (see Appendix A).
  3. If the client calls ACMS tasks, set up the ACMS Gateway adapter environment (see Section 10.3.2).


Chapter 8
Writing Java Clients

A client program developed with the Java language can call tasks in one of the following environments:

See Chapter 3 for introductory information.

8.1 Overview of Java Client Development

Support is provided for the following kinds of programs developed with the Java language:

For Java clients developed using Visual J++, the interface is provided through an Automation input adapter and COM objects (see Section 7.1).

For Java clients developed using the JDK, the interface is provided through the generated Java input adapter as described in this chapter. The Java client comprises the application code that you write and STDL-generated Java input adapter code.

Use the STDL compiler to generate an adapter stub containing a Java input adapter and an output adapter designated by the type of task calls that the client makes. The adapter stub is used to build a Java client.

The Java input adapter created as part of the generated adapter stub contains the following code.

Thus, your client does not invoke the JNI code directly. You use the Java classes in the client to call tasks. The Java code in the input adapter calls the JNI code to convert the task calls to the type designated by the type of output adapter you specify for the adapter stub.

To write a Java client, follow these general steps:

  1. Generate the adapter stub and related code for the Java client (see Section 8.2).
  2. Code the client application including calls to tasks, following the appropriate guidelines (see Section 8.3).
  3. Build the Java client and related runtime code (see Section 8.2).

8.2 Steps for Building a Java Client

The Java client can call a task on an ACMSxp system, an ACMS system, or a Portable TP for Windows NT system. To build a Java client with an adapter stub, perform the following steps:

  1. Set up Java-specific environment variables.
    In addition to using stdl_set_version.bat (see Section 2.1) and setting up your C/C++ programming environment, define the environment variables specific to your Java environment. (The .bat-style examples assume that your working directory is C:\work, and that the JDK was installed in the C:\jdk1.1.6 directory.)

  2. Optionally, define build environment variables for Java tools that are used (see Table 8-1).

    Table 8-1 Optional Build Environment Variables for Java Tools
    Name Purpose
    STDL_JAVA_JAR_OPTIONS Overrides default JAR command line options
    STDL_JAVA_JAVAC_OPTIONS Overrides default JAVAC command line options
    STDL_JAVA_JDK_HOME Specifies the location of the JDK installation root

    Use these environment variables only to change default operations for the Java tools that the STDL compiler calls.

  3. Copy to the client development system a task group specification and any related files from an ACMSxp system, an ACMS system, or a Portable TP for Windows NT system (see Section 3.1).
  4. Compile the STDL task group specification.
    On the STDL compile command line, specify input and output adapters with the -a flag. See Section 2.2 for the complete stdl command syntax. Use for the input adapter either java (if you want the Java classes that represent the application objects to present their data record fields as public members) or javabeans (if you want the Java classes that represent the application objects to present their data record fields through accessor methods). Supply the appropriate output adapter type from those shown in Table 8-2.

    Table 8-2 Output Adapter Specifications for Java Clients
    Specification Purpose
    acmsda Calls ACMS tasks using a gateway
    dce Calls ACMSxp tasks using DCE RPC
    msrpc Calls ACMSxp tasks using Microsoft RPC
    mts Calls tasks running under Portable TP for Windows NT using COM

    For example:


      stdl -a java:acmsda add_acms_appl  
    

    The command creates a Java input adapter and an ACMS Gateway output adapter in the generated adapter stub. The compilation produces the following files:+


    The format conventions are:
    group Converted name of the compiled STDL task group specification (see Section 8.3.2.1).
    out_adapter Name of one of the output adapter types from Table 8-2.

    See Compilation Output in Section 2.2.
  5. Write the Java client, using STDL-generated Java classes for the task group being accessed (see Section 8.3).
  6. Produce the DLL for the Java client. Specifying the /DLL qualifier to the linker, link the following items:+
  7. If the client calls tasks running under Portable TP for Windows NT, you may need to register the proxy stub DLL and perform other setup operations (see Section 9.1.1).

Note

+ The value group is a converted name (see Section 8.3.2.1).


Previous Next Contents Index