# DIGITAL TP Web Connector
DIGITAL Database Web Connector

# Getting Started

Order Number: AA-R6WWA-TE

# October 1997

This document introduces you to the DIGITAL TP Web Connector and DIGITAL Database Web Connector software and provides information to enable you to install the products on a Windows NT and an OpenVMS system. This document also contains reference information for building applications that call ACMS tasks, ACMSxp tasks, and local STDL processing procedures from various web and C-language interfaces and for managing the environment in which the applications run.

Revision/Update Information: This is a new manual.

Software Version: DIGITAL TP Web Connector Version 1.0

DIGITAL Database Web Connector Version 1.0

Digital Equipment Corporation, Maynard, Massachusetts

October 1997

Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from DIGITAL or an authorized sublicensor.

#### © Digital Equipment Corporation 1997. All Rights Reserved.

The following are trademarks of Digital Equipment Corporation: ACMS, ACMS Desktop, ACMSxp, ACMSxp Desktop, DEC, DECnet, DECthreads, DIGITAL, OpenVMS, VAX, VAX DOCUMENT, VMS, VT, and the :DIGITAL logo.

The following are third-party trademarks:

Gradient is a registered trademark and PC-DCE is a trademark of Gradient Technologies, Inc.

IBM and NetWare are registered trademarks of International Business Machines Corporation.

Intel is a trademark of Intel Corporation.

Micro Focus and Animator are registered trademarks and Micro Focus COBOL, Micro Focus COBOL Toolbox, Micro Focus COBOL/2, LEVEL II COBOL/ET, and VS COBOL are trademarks of Micro Focus Limited.

Microsoft, Microsoft Access, MS, :MS--DOS, Visual Basic, Visual C++, Windows, and Windows 95 are registered trademarks and Windows NT is a trademark of Microsoft Corporation.

Oracle Rdb is a registered trademark of the Oracle Corporation.

OSF is a registered trademark of the Open Software Foundation, Inc.

X/Open is a trademark of X/Open Company Limited.

All other trademarks and registered trademarks are the property of their respective holders.

Contents | Index

# Preface

This manual provides information that enables you to install and use the DIGITAL TP Web Connector and DIGITAL Database Web Connector software.

# Intended Audience

This document is intended for:

- Anyone who is responsible for installing, maintaining, or deinstalling software for DIGITAL TP Web Connector and DIGITAL Database Web Connector installations.
- Application programmers who need reference information about developing applications with DIGITAL TP Web Connector to access either ACMSxp tasks or ACMS tasks, or DIGITAL Database Web Connector to access local processing procedures.

# Operating System Information

For information about the versions of the operating system and other software that are compatible with this version of DIGITAL TP Web Connector and DIGITAL Database Web 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 DIGITAL TP Web Connector and DIGITAL Database Web 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 Web Connector and Database Web Connector products allow World Wide Web users and servers to carry out transactions with DIGITAL ACMS tasks, DIGITAL ACMSxp tasks, and local STDL processing procedures.
Chapter 2 | Describes the installation of the TP Web Connector and Database Web Connector components on a Windows NT system, including requirements and preparations associated with the installation.
Chapter 3 | Describes the installation of the TP Web Connector components on an OpenVMS system, including requirements and preparations associated with the installation.
Chapter 4 | Explains the procedures for building interfaces for web servers to access ACMS tasks, ACMSxp tasks, or local STDL processing procedures.
Chapter 5 | Describes the STDL compiler option flags used in generating TP Web Connector and Database Web Connector applications.
Chapter 6 | Describes TP Web Connector components used for development on the ACMS system and for run-time support and management on the Windows NT system. Explains the use of the development components to translate ACMS applications so that you can build web servers that access those ACMS applications.
Chapter 7 | Explains how to use the TPware management utility on a Windows NT system to customize runtime settings for connecting web servers and TP applications.
Chapter 8 | Describes procedures for managing the ACMS Desktop adapter gateway on an OpenVMS system.

# Conventions

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.

# Chapter 1
Introduction to Adapters

This chapter provides an overview of the technology used by TPware software.

# 1.1 TPware Products

TPware is a transaction processing software suite that includes the TP Web Connector and Database Web Connector products. The TPware suite is made up of components derived from ACMSxp and ACMS software. The TPware products described in this manual consist of the following:

- DIGITAL TP Web Connector
  Allows web servers to call ACMS tasks or ACMSxp tasks.
- DIGITAL Database Web Connector
  Allows web servers to call local STDL processing procedures.

# 1.2 Transaction Processing Through TPware

Typically, transaction processing (TP) applications connect diverse modules for handling the user interface, the business logic, and the database access functions of a business solution. For applications that need to be connected to the World Wide Web, the user interface is usually a web browser. If a TP application is to accommodate a web browser as a user interface, business logic and database access modules need to be connected to the web server for that web browser.

## 1.2.1 Connecting Browsers and TP Applications

TPware software connects a browser's web server and an ACMS or ACMSxp TP application. TPware provides both a C language option and an Automation option for connecting your application to a web server. The TPware options can also be used to connect any other PC-based client to an ACMS or ACMSxp application.

On a server platform, TPware extracts information from the business logic (that is, the task) portion of the ACMS or ACMSxp application. You download the extracted information to the client platform. TPware translates the extracted information into a format that you can easily use to connect to a web server or other PC-based client program.

For example, in the Microsoft environment, TPware translates the extracted information from the server system into an Automation object. The Automation object can be linked with any Microsoft-compatible software that supports Automation; for example, the Internet Information Server (IIS), Microsoft Office, and Visual Basic. In the Microsoft environment, the interfaces are compatible with the Microsoft components architecture, or Common Object Model (COM). The Microsoft-compatible interface connects any Microsoft COM object to an ACMS or ACMSxp application with minimal programming effort.

## 1.2.2 TPware and the World Wide Web

TPware expands the capabilities of World Wide Web browsers and servers by enabling them to access ACMS tasks, ACMSxp tasks, or local STDL processing procedures with code executing in the web server. The basic model for TPware is illustrated in Figure 1-1.

Figure 1-1 The TPware Model

TPware accomplishes this access by enabling the creation of code called a TP stub that translates calls between web browsers and TP applications.

## 1.2.3 TPware Operation

Using a web browser, the user accesses a page on a web server. The page is an HTML page containing server-side scripts with either references to Automation objects or references to a shared library (DLL on Windows NT systems) loaded on the web server. The script or shared library processes the incoming request and extracts information needed for the transaction.

With the extracted transaction information, the server then performs the following operations:

- Calls a TP application through a stub.
- Interprets the results from the TP application.
- Displays those results to the end user.

For DIGITAL TP Web Connector, the TP application is either a TDL task executing under ACMS on an OpenVMS platform or an STDL task executing under an ACMSxp system. For DIGITAL Database Web Connector, the TP application is a local STDL processing procedure executing on the same system as the web server. The script or shared library that connects the TP application and the web server uses the same interface whether the TP application is implemented using ACMS, ACMSxp, or a local STDL processing procedure.

# 1.3 Stub Generation and Adapters

TPware uses TP stub technology to support the generation of interfaces that allow PC-based clients (including web browsers) to call tasks or processing procedures using a variety of language interfaces and communications mechanisms.

ACMSxp software uses stubs to allow clients to call servers without having to deal directly with a communications mechanism. ACMSxp generates stubs using DCE RPC as the communication mechanism. These stubs allow user-written clients to call ACMSxp task servers, and ACMSxp task servers to call processing servers and other ACMSxp task servers.

Figure 1-2 shows how a TP stub composed of TPware interfaces allows C procedures and ACMSxp tasks (using DCE RPC) to call each other.

Figure 1-2 ACMSxp Adapter Technology

To accomplish this stub-based calling mechanism, TPware divides the functionality of the TP stub into halves called adapters. These program interfaces generated by the TPware STDL compiler are called adapters because they are used to adapt web servers and other PC clients to ACMS and ACMSxp applications. 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.

TPware software extends the capabilities of stubs. By supporting stubs with various types of adapters in addition to C and DCE RPC adapters, TPware software can support different language interfaces and communications mechanisms. Figure 1-3 illustrates the types of adapters that TPware supports.

Figure 1-3 Adapters Supported by TPware

TP Web Connector generates and uses the following types of adapters:

- Automation input
- C input
- DCE RPC output (for calls to ACMSxp tasks)
- ACMS Desktop output (for calls to ACMS tasks)

Database Web Connector generates and uses the following types of adapters:

- Asynchronous input
- Automation input
- C input
- C output (for calls to local processing procedures)

# 1.4 TPware Components

Both the DIGITAL TP Web Connector and DIGITAL Database Web Connector products include the following components:

- Base STDL compiler
- Base STDL runtime
- TPware management utility
- Automation adapter generator and runtime
- C adapter generator and runtime

In addition, the DIGITAL TP Web Connector product includes the following components:

- DCE RPC adapter generator and runtime
- ACMS Desktop adapter generator and runtime
- ACMSADU extensions
- ACMS Desktop adapter gateway

# 1.5 Control Points

TPware allows application programmers to insert control points within a process on a local server. Control points serve as a virtual TP monitor, increasing performance for the application in the following ways:

- Control points can optimize database access by allowing calls to processing procedures to be executed on a dedicated set of worker threads.
- Control points can reduce I/O contention within the database by allowing application programmers to limit the number of threads that are concurrently executing processing procedures in a processing group. Additional client threads queue, waiting for a free worker thread.
- Control points solve problems with insufficient stack space to execute calls.

For applications with many client threads, such as a web application, control points can increase performance.

# Chapter 2
Installing TPware Components on a Windows NT System

This chapter describes the installation of the TPware components on a Windows NT system, including requirements and activities associated with the installation.

# 2.1 Installation Overview

The software is distributed on :CD--ROM with the following components:

- Both TP Web Connector and Database Web Connector components

- STDL compiler
- TPware management utility
- TPware runtime library
- Samples

- TP Web Connector only

- Run-time libraries for supported input adapters (Automation and C) and output adapters (ACMS Desktop and DCE RPC)
- Samples

- Database Web Connector only

- Run-time libraries for supported input adapters (asynchronous, Automation, and C) and output adapter (C)
- Samples

## 2.1.1 Hardware Support

TPware runs on the following Windows NT hardware platforms:

- DIGITAL Alpha systems
- Intel systems

## 2.1.2 Disk Space Requirements

The TPware components require an amount of free storage space depending on the platform on which the software is installed and on the options installed for each product, as shown in Table 2-1.

Table 2-1 TPware Disk Space Requirements

|  | Megabytes (MB)
--- | --- | ---
Product | Option Installed | Intel | Alpha
Database Web Connector | Base system 1 | .7 | .7
| Development system | 2.0 | 2.1
| Samples | .05 | .05
| All options | 2.75 | 2.85
TP Web Connector | Base system 1 | .7 | .7
| Development system | 2.2 | 2.5
| Samples | .15 | .15
| All options | 3.15 | 3.35

1This option is always installed for Database Web Connector and TP Web Connector.

# 2.2 Preparing to Install TPware Components

Ensure that the Windows NT system meets software requirements. Minimum software requirements needed to install TPware components and build clients that run with TP Web Connector or Database Web Connector are shown in Table 2-2.

Table 2-2 Required Software for Windows NT Systems

TPware Component | Title of Required Product | Version
--- | --- | ---
Both TP Web Connector and Database Web Connector | One of: | Windows NT Workstation | 4.0 with Service Pack 2
|  | Windows NT Server | 4.0 with Service Pack 2
| One of: | Visual C++ and Microsoft Platform Software Developer's Kit (SDK) March 1997 or later | 4.2 or higher
|  | Visual C++ | 5.0
| One of: 1 | Internet Information Server (IIS) on Windows NT Server 4.0 | 3.0
|  | Peer Web Services on Windows NT Workstation 4.0 | 3.0
| One of: 2 | Active Server Pages (ASP) for IIS 3.0 | 1.0
|  | Active Server Pages (ASP) for Peer Web Services 3.0 | 1.0
TP Web Connector only | DIGITAL DCE Application Developer's Kit for Windows NT 3 | 2.0
| DIGITAL DCE Runtime Services for Windows NT 3 | 2.0
| Access to an ACMSxp TPsystem 3 | 3.0 or higher

1Required only if the interface you are developing works with web clients.
2Required only if you are using server-side scripts.
3Required only if the interface you are developing calls ACMSxp tasks. Also, DIGITAL DCE Version 2.0 for Windows NT requires Windows NT Service Pack 3.

Next | Contents | Index