# 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:

- One Automation object for each task group
- A method for each task
- A property named `einfo` that points to an `STDL.stdl_einfo` object that contains exception information for an STDL call (see Section 7.2.1)
- A property named `call_attributes` that Automation clients can access to specify values to pass to communications adapters on each call (see Section 7.4)
- Automation objects for STDL records

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 STDL data type is used as an argument to a task in the task group.
  The value record-name is derived from the STDL data type identifier that specifies the record layout.
- The STDL data type identifier is used as a data type for a field within another record object being generated for the task group (X/Open syntax only).
  The value record-name is derived from the STDL data type identifier that specifies the record layout.
- An embedded record is used as a data type for a field within another record object being generated for the task group.
  The compiler gives the object a name in the following format:

  `group.field-name_record`

  The value field-name is derived from the STDL field name.

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:
   - In a `CreateObject` service
     You can use the `Server.CreateObject` method to create objects with session, page, or application scope. Objects with page scope are created each time the user accesses the page and are destroyed when the server finishes processing the current page. After session objects are created, they remain in existence until the current session either is abandoned or times out.
   - By using object references in Visual Basic
   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:
   - By referring to the group object in a `CreateObject` service with a name in the following format:

         group.Group

     The value group is the converted name of the task group.
   - By using object references in Visual Basic
     For example, the group object name for `add_task_group` is:

         add_task_group.Group

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.
   - If the client calls ACMS tasks, set up parameters (see Section 10.2.4).
   - If the client calls ACMSxp tasks, set up parameters (see Section 10.2.3).
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:

- STDL task groups executing under an ACMSxp system
- TDL task groups executing under an ACMS system
- STDL task groups running under a Portable TP for Windows NT system

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:

- Clients developed using Microsoft Visual J++.
- Clients developed using JDK 1.1 (Java Development Kit).

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.

- Java Native Interface (JNI) code
  Contained within the DLL that also contains the output adapter, the JNI code is the interface between the Java components of the stub and the TPware runtime.
- Java code
  Created as a collection of classes representing the task group specification and its records, this code is the interface between the client application and the JNI 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.)

   - PATH
     Define in the PATH environment variable the JDK bin directory and the directory containing the JNI DLL that is generated by the build. Place the standard JDK directory in the path before any other JDK environments installed on the machine. For example:

         set path=c:\jdk1.1.6\bin;c:\work;%path%

   - INCLUDE
     Define in the INCLUDE environment variable the standard JDK and win32-specific directories. For example:

         set include=c:\jdk1.1.6\include;c:\jdk1.1.6\include\win32;%include%

   - CLASSPATH
     Define in the CLASSPATH environment variable your working directory and the directory for the standard JDK classes. Place these directories before those for any alternative JDK classes. For example:

         set classpath=.;..;c:\jdk1.1.6\lib\classes.zip;%classpath%

     Before actually running the adapter code, specify in the CLASSPATH environment variable the path for the JAR file that is generated by the build (see Section 8.8.1).
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:+
   - A Java archive with a name in the following format:+

     `group_out_adapter.jar`

   - A Java adapter stub with a name in the following format:+

     `group_java_out_adapter.obj`

   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:+
   - The TPware runtime library:

         stdl_rtm.lib

   - Objects and libraries that depend on the type of task that the client calls and the output adapter that the client uses, as shown in Table 8-3.

     Table 8-3 Java Client Adapter-Dependent Link Input
     If Client Calls... | Input File Name | Comment
     --- | --- | ---
     ACMS tasks (uses `acmsda` adapter) | group_java_acmsda.obj | The adapter stub for the ACMS application (the STDL task group)
     | stdl_acmsda.lib | ACMS Gateway adapter runtime link library
     ACMSxp tasks and uses `dce` adapter | group_java_dce.obj | Adapter stub for the task group
     | group_dce_cstub.obj | DCE client stub
     | libdce.lib pthreads.lib stdl_dce.lib | DCE libraries
     ACMSxp tasks and uses the `msrpc` adapter | group_java_msrpc.obj | Adapter stub for the task group
     | group_msrpc_c.obj | Microsoft RPC client stub
     | stdl_msrpc.lib | Microsoft RPC adapter runtime link library
     | rpcndr.lib rpcns4.lib rpcrt4.lib | Windows NT libraries
     Tasks running under Portable TP for Windows NT (uses the `mts` adapter) | group_java_mts.obj | Adapter stub for the task group
     | stdl_mts.lib | MTS adapter runtime link library

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