DIGITAL TP Desktop Connector
Getting Started
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:
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:
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:
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:
- 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
|
- 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.
- Fills in data in the record objects as necessary.
The fields
within the record objects are referenced as attributes of the created
record object.
- 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:
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:
- Optionally sets the call attributes string.
- Within the task group object, calls the task as a method.
- 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:
- 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).
- Set up error logging for the client (see Appendix A).
- 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 ACMSxp
- TDL task groups executing under ACMS
- STDL task groups running under Portable TP for Windows NT
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:
- Generate the adapter stub and related code for the Java client (see
Section 8.2).
- Code the client application including calls to tasks, following the
appropriate guidelines (see Section 8.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:
- 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).
- 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.
- 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).
- 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:+
- 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.
- Write the Java client, using STDL-generated Java classes for the
task group being accessed (see Section 8.3).
- Produce the DLL for the Java client. Specifying the /DLL qualifier
to the linker, link the following items:+
- The TPware runtime library:
- 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
|
- 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).