Order Number: AA-RCTWB-TE
This document introduces you to the Adapter Interface of the DIGITAL TP Desktop Connector product and provides information for building client applications that call ACMS tasks, ACMSxp tasks, and 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: DIGITAL TP Desktop Connector Version 3.1
Compaq Computer Corporation
Houston, Texas
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.
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 Corporation.
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.
| Contents | Index |
This manual describes the Adapter Interface of the DIGITAL TP Desktop Connector product.1
|
Note 1 Other manuals describe the Client Services Interface for ACMS applications. See "Associated Documents" in this Preface. |
This document is intended for:
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.
This document has the following components, as shown in the following table:
| Component | Description |
|---|---|
| Chapter 1 | Provides an overview of how the TP Desktop Connector product allows client systems to call TP applications. |
| Chapter 2 | Describes the STDL compiler option flags used in generating TP Desktop Connector client programs. |
| Chapter 3 | Introduces the general procedures for building TPware adapter interfaces for client systems to access ACMS tasks, ACMSxp tasks, or STDL tasks executing under Portable TP for Windows NT. |
| Chapter 4 | 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. |
| Chapter 5 | Introduces the TPware client build utility and describes how to use its graphical user interface to build Automation and C clients. |
| Chapter 6 | Describes writing and building C and asynchronous clients. |
| Chapter 7 | Describes writing Automation servers and clients. |
| Chapter 8 | Describes writing and building Java clients. |
| Chapter 9 | Describes application setup operations. |
| Chapter 10 | Explains how to use the TPware management utility on a Windows platform to customize runtime settings for connecting clients and TP applications. |
| Appendix A | Describes how the software records run-time errors that cannot be returned to the client process. |
| Appendix B | 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 options are:
This document uses the following conventions:
| Convention | Description |
|---|---|
| italic | Italic type emphasizes important information and indicates complete titles of manuals. In format descriptions, it indicates variable parts of input that you must supply. |
| new term | New terms are highlighted in boldface type where they are defined in the text. |
| user input | In examples, user input is differentiated in boldface font from system output. |
| monospace text | 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. |
| lowercase | Commands that you enter (except where the command line includes an environment variable) are in lowercase. |
| UPPERCASE | Uppercase text indicates STDL syntax. Environment variables are in uppercase. Key words on the OpenVMS system are also indicated by uppercase text. |
| [] | 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 DIGITAL TP Desktop Connector product's Adapter Interface.
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 allows single-user client systems to call TP applications.
The TP Desktop Connector product provides the following interfaces (see Section 1.6 for an overview):
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.
The TP Desktop Connector product allows you to connect a client application to a TP server application. The basic model that TP Desktop Connector uses to connect single-user client systems to TP applications is illustrated in Figure 1-1.
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 a TP 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 Portable TP for Windows NT.
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 other.
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, the input adapter, takes an incoming call and transforms it into a standard form called the TPware standard call. The other half, the output 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 TP Desktop Connector supports.
Figure 1-3 Adapters Supported by TP Desktop Connector
TP Desktop Connector generates and uses the following types of input adapters:
TP Desktop Connector generates and uses the following types of output adapters:
For TP Desktop Connector, TPware adapters are of two general types:
The following sections describe their behavior.
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:
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.
The DIGITAL TP Desktop Connector product provides the following interfaces for client access to TP applications (illustrated in Figure 1-4):
Figure 1-4 TP Desktop Connector Interfaces
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 tasks.
Figure 1-4 shows a single-threaded C client calling Client Services, which uses ACMS RPC to call the TP Desktop Connector Gateway for ACMS. The 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 Portable TP for Windows NT, 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.
|
Note 1 Multithreading is not supported for clients that use DCE RPC communications with ACMSxp applications. |
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 1-5.
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 4.
| Next | Contents | Index |