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

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.

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).

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).

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).