Compaq TP Desktop Connector
Order Number: AA-RCTWC-TE
This document introduces you to the Adapter Interface of the Compaq
TP Desktop Connector product and provides information for building
client applications that call ACMS tasks, ACMSxp tasks, or
STDL tasks executing under Portable TP for Windows NT from various
Automation, Java, and C-language interfaces. This guide also describes
managing the environment in which the client applications run.
Revision/Update Information: This is a revised manual.
Software Version: TP Desktop Connector Version 3.1A
Compaq Computer Corporation
The information in this publication is subject to change without notice.
COMPAQ COMPUTER CORPORATION SHALL NOT BE LIABLE FOR TECHNICAL OR EDITORIAL
ERRORS OR OMISSIONS CONTAINED HEREIN, NOR FOR INCIDENTAL OR CONSEQUENTIAL
DAMAGES RESULTING FROM THE FURNISHING, PERFORMANCE, OR USE OF THIS MATERIAL.
THIS INFORMATION IS PROVIDED "AS IS" AND COMPAQ COMPUTER CORPORATION DISCLAIMS
ANY WARRANTIES, EXPRESS, IMPLIED, OR STATUTORY, AND EXPRESSLY DISCLAIMS
THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR PARTICULAR PURPOSE,
GOOD TITLE, AND AGAINST INFRINGEMENT.
This publication contains information protected by copyright. No part
of this publication may be photocopied or reproduced in any form without
prior written consent from Compaq Computer Corporation.
© 1997, 1998, 1999 Digital Equipment Corporation. All Rights
The software described in this guide is furnished under a license agreement
or nondisclosure agreement. The software may be used or copied only in
accordance with the terms of the agreement.
Compaq and the Compaq logo are registered in the United States Patent
and Trademark Office.
ACMS, ACMSxp, DEC, DECnet, DIGITAL, OpenVMS, VAX, VAX DOCUMENT, and
VMS are trademarks of Compaq Computer Corporation.
The following are third-party trademarks:
Macintosh is a registered trademark of Apple Computer, Inc.
Intel is a registered trademark of Intel Corporation.
Microsoft, Microsoft Access, MS, :MS--DOS, Visual Basic, Visual C++,
Windows, Windows 95, and Windows NT are registered trademarks of Microsoft
Oracle Rdb is a registered trademark of the Oracle Corporation.
X/Open is a registered trademark of The Open Group, and The Open Group
is a trademark in the United States and other countries.
Java and JavaBeans are registered trademarks of Sun Microsystems, Inc.
Other product names mentioned herein may be trademarks and/or registered
trademarks of their respective companies.
This manual describes the Adapter Interface of the Compaq TP Desktop
manuals describe the Client Services Interface for ACMS applications.
See "Associated Documents" in this Preface.
This document is intended for:
Application programmers who need reference information about how to develop
client programs that call ACMS tasks, ACMSxp tasks, or STDL
tasks executing under a Portable TP for Windows NT system from various
Automation, Java, and C language interfaces.
Anyone who is responsible for configuring and managing a client interface
developed with the TP Desktop Connector product.
Operating System Information
For information about the versions of the operating system and other software
that are compatible with this version of TP Desktop Connector software,
refer to the Software Product Description (SPD). Use the SPD to verify
which versions of your operating system are compatible with this version
of TP Desktop Connector software.
This document has the following components, as shown in the following table:
||Provides an overview of how the TP Desktop Connector product
allows client systems to call TP applications.
||Describes the STDL compiler option flags used in generating TP Desktop
Connector client programs.
||Introduces the general procedures for building TPware adapter interfaces
for client systems to access ACMS tasks, ACMSxp tasks, or
STDL tasks executing under a Portable TP for Windows NT system.
||Describes TP Desktop Connector components used for development
on the ACMS system and for runtime support and management on the
Windows platform. Explains the use of the development components to translate
ACMS applications so that you can build a client interface that
access those ACMS applications.
||Introduces the TPware client build utility and describes how to use
its graphical user interface to build Automation and C clients.
||Describes writing and building C and asynchronous clients.
||Describes writing Automation servers and clients.
||Describes writing and building Java clients.
||Describes application setup operations.
||Explains how to use the TPware management utility on a Windows platform
to customize runtime settings for connecting clients and TP applications.
||Describes how the software records run-time errors that cannot be returned
to the client process.
||Describes Kanji text data code conversion functions.
Documents associated with the Desktop Client Services Interface are:
Documents associated with the installation of this product and related
Compaq TP Desktop Connector for ACMS Client Application
Compaq TP Desktop Connector for ACMS Client Services Reference
Compaq TP Desktop Connector for ACMS Gateway Management
Compaq TP Desktop Connector for ACMS Installation Guide
Compaq TP Desktop Connector for ACMSxp Installation Guide
Compaq TP Desktop Connector for Portable TP Installation
This document uses the following conventions:
||Italic type indicates important information, a Compaq product name,
or the complete title of a manual. In command syntax, it indicates variable
parts of input that you must supply.
||New terms are highlighted in boldface type where they are defined in
||In examples, user input is differentiated in boldface font from system
||Words in monospaced font in text indicate names of files, commands
and options, user interface elements such as menu names, objects stored
on the system, or system output used in examples.
||Commands that you enter (except where the command line includes an
environment variable) are in lowercase.
||Uppercase text indicates STDL syntax. Environment variables are in
uppercase. Key words on the OpenVMS system are also indicated by
||In command syntax, square brackets enclose an optional choice or choices.
|In examples, a vertical ellipsis indicates that information not directly
related to the example has been omitted.
This chapter provides an overview of the adapter technology used by TPware
software and, in particular, the capabilities of the Compaq TP Desktop
Connector product's Adapter Interface.
1.1 TPware Products
TPware is a set of components from which
several TP-related products are created. Different components are used
to create different products. These products are as follows:
This manual describes the TP Desktop Connector product, which allowssingle-user
client systems to call TP applications.
Compaq TP Desktop Connector
Compaq TP Web Connector
Compaq Portable TP for Windows NT
Compaq Application Optimizer for Windows NT
The TP Desktop Connector product provides the following interfaces
(see Section 1.6 for an overview):
TPware Adapter Interface (described in this manual)
Client Services Interface for ACMS applications (described in other
manuals; see "Associated Documents" in the Preface)
1.2 Transaction Processing Through TPware
Typically, transaction processing (TP) applications connect different systems
that handle the user interface, the business logic, and the database access
functions of a business solution. For applications that need to be connected
to clients over a network, the interface is usually a PC client. Through
its adapter technology, TPware provides an interface between clients running
on a PC and the business application.
TPware can connect dissimilar clients and servers using a variety of
communications mechanisms. You can use TPware to write client applications
that call ACMS tasks, ACMSxp tasks, or MTS servers written
using STDL. You can write these client applications either in C or Java,
or by using Microsoft Automation.
1.3 Connecting a Client Application to TP Applications
The TP Desktop Connector product allows you to connect a client
application to a TP server application.The
basic model that the TP Desktop Connector product uses to connect
single-user client systems to TP applications is illustrated in Figure
Figure 1-1 Connecting a Client Application to a TP Application
TPware accomplishes client access to TP applications by enabling the
creation of code called aTP stub that translates
calls between client programs and TP applications.
Using a client program, the user enters a request
by entering information in a programmer-designed window. The client program
processes the incoming request and extracts information needed to call
the TP application.
The client program then performs the following operations:
The TP application is either a TDL task executing under ACMS on
an OpenVMS platform, an STDL task executing under an ACMSxp
system, or an STDL task executing under a Portable TP for Windows NT
Calls a TP application through the TP stub.
Interprets the results from the TP application.
Displays those results to the end user.
1.4 Stub Generation and Adapters
TPware uses TP stub technology to support the generation of interfaces
that allow PC-based clients to call tasks using a variety of language interfaces
and communications mechanisms. For example,Figure
1-2 shows how a TP stub allows two types of interfaces to call each
Figure 1-2 TP Stub and Adapter Technology
To accomplish this stub-based calling mechanism,
TPware divides the functionality of the TP stub into halves called adapters.
One half of the TP stub, theinput adapter,
takes an incoming call and transforms it into a standard form called theTPware
standard call. The other half, theoutput
adapter, takes the TPware standard call and transforms it into the
appropriate form for the TP application.
In this way, TPware software extends the capabilities of stubs. By supporting
stubs with various types of adapters, TPware software can support different
language interfaces and communications mechanisms. Figure
1-3 illustrates the types of adapters that a TP Desktop Connector
Figure 1-3 Adapters Supported by TP Desktop Connector
The TP Desktop Connector software generates and uses the following
types of input adapters:
The TP Desktop Connector software generates and uses the following
types of output adapters:
Java input (Java/JavaBeans)
Asynchronous C input
ACMS Gateway output (for calls to ACMS tasks)
DCE RPC output (for calls to ACMSxp tasks)
Microsoft RPC output (for calls to ACMSxp tasks)
MTS output (for calls to STDL tasks executing under a Portable TP for
Windows NT system)
1.5 Adapter Behavior
For the TP Desktop Connector product, TPware adapters are of two
The following sections describe their behavior.
Input language adapters
Output communications adapters
1.5.1 Input Language Adapters
Input adapters present the components of an interface to clients that are
written in a particular language such as C or that use a particular calling
mechanism such as Automation. The TPware input adapters present to a client
the following aspects of the TPware interface:
A way to call each procedure within the interface
TPware interfaces such as STDL task groups consist of one or more procedures
that each take one or more arguments. These arguments may be input, output,
A way to retrieve the exception information that may be returned on a TPware
The TPware or adapter runtime software can generate exceptions. The
called procedure can return exception information that is made accessible
to the client through the STDL einfo structure (see Section
A way to specify the TPware call attributes for a call
Clients must have a way to pass information such as destination and
authentication information to communications adapters on each call. TPware
does this through the use of the call attributes string (see Section
1.5.2 Output Communications Adapters
Each output adapter handles specific call attributes and accepts a default
for each attribute (see Section 3.3).
These output adapters perform the appropriate transformation of the call
into the communications messages required to invoke the remote task.
1.6 TP Desktop Connector Interfaces to TP
The Compaq TP Desktop Connector product provides the following interfaces
for client access to TP applications (illustrated in Figure
Figure 1-4 TP Desktop Connector
Client Services Interface (described in other manuals; see "Associated
Documents" in the Preface)
TPware Adapter Interface (described in this manual)
The client services interface provides single-threaded client
access to ACMS applications. The client makes a series of service
calls to Client Services to invoke tasks and handle exchange I/O from the
Figure 1-4 shows how a single-threaded
C client calls Client Services, which uses ACMS RPC to call the
TP Desktop Connector gateway. This ACMS gateway executes
on OpenVMS platforms.
The client services interface for Macintosh clients differs from the
services interface described here and is covered in other manuals.
The TPware adapter interface provides client access to ACMS,
ACMSxp, and a Portable TP for Windows NT system, using adapters
generated by the TPware STDL compiler. To call ACMS tasks, use the
ACMSADU compiler to generate an STDL task group definition for an ACMS
application (see Section 1.7), and
then use the STDL compiler to generate the adapter.
The type of client determines the type of input adapter:
The type of output adapter depends on the TP application being accessed
and the communications mechanism being used. For example, the ACMS
Gateway Adapter uses the ACMS RPC to send the call information to
the gateway. The gateway process in turn calls the ACMS task.
C input language adapter
Provides both single-threaded and multithreaded C client program access
to ACMS, ACMSxp, and Portable TP for Windows NT applications.1
Asynchronous C input language adapter
Provides an asynchronous interface for C clients to call ACMS,
ACMSxp, and Portable TP for Windows NT applications. When
the task call completes, the adapter invokes the call-back routine provided
by the client.
Automation input language adapter
Provides an Automation interface to ACMS, ACMSxp, and
Portable TP for Windows NT applications. Use the Automation input
adapter with any client that can use an Automation interface (currently
limited to 32-bit Microsoft Windows platforms). For example, you can use
tools such as Visual Basic and Office 95/97.
Java/JavaBeans input language adapter
Provides a Java interface to ACMS, ACMSxp, and Portable
TP for Windows NT applications. To the application Java client, the
Java input adapter presents Java classes that represent application objects.
It provides to those Java classes a Java Native Interface (JNI) that represents
equivalent application objects. The Java classes call into the native methods,
which in turn call the standard C interface.
is not supported for clients that use DCE RPC communications with ACMSxp
1.7 The ACMSADU Extension
To invoke an ACMS task using a TPware adapter, you need to generate
an STDL definition for the ACMS application. You do this by using
an extension to the ACMSADU compiler, as shown in Figure
Figure 1-5 Using the ACMSADU Extension
The ACMS application translator (the ACMSADU compiler extension)
generates an STDL task group specification but applies the ACMS
application name as the task group name. The STDL task name is mapped to
an ACMS task name within the ACMS application.
After using the ACMSADU compiler extension on an OpenVMS system
to generate the STDL task group, you copy the task group specification
to a Windows system and use the STDL compiler there to generate the stub
containing the ACMS Gateway adapter. For more detail on using the
ACMSADU Extension, see Chapter