Compaq TP Desktop Connector

Getting Started

Order Number: AA-RCTWC-TE

August 1999

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
Houston, Texas

August 1999

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

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

Preface

This manual describes the Adapter Interface of the Compaq TP Desktop Connector product.1
Note 

1 Other manuals describe the Client Services Interface for ACMS applications. See "Associated Documents" in this Preface.

Intended Audience

This document is intended for:

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.

Structure

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 a Portable TP for Windows NT system. 
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. 

Associated Documents

Documents associated with the Desktop Client Services Interface are: Documents associated with the installation of this product and related options are:

Conventions

This document uses the following conventions:
Convention  Description 
italic 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 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. 

Chapter 1
Introduction

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.

The TP Desktop Connector product provides the following interfaces (see Section 1.6 for an overview):

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

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 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, 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 system supports.

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:

1.5 Adapter Behavior

For the TP Desktop Connector product, TPware adapters are of two general types: The following sections describe their behavior. 

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:

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 Applications

The Compaq 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 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.
Note 

1 Multithreading is not supported for clients that use DCE RPC communications with ACMSxp applications.

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