Order Number: AA--PG9AG--TE

This manual describes how to write, develop, and debug desktop client programs that access DIGITAL ACMS applications from the desktop, using the DIGITAL TP Desktop Connector client services.

Revision Update Information: This is a revised manual.

Operating System: DIGITAL OpenVMS VAX
DIGITAL OpenVMS Alpha

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.

Copyright © Digital Equipment Corporation 1991,1999. All rights reserved.

Compaq and the Compaq logo are registered in the United States Patent and Trademark Office.

ACMS, ACMS Desktop, DEC, DECforms, DECnet, :DECnet--DOS, DECtp, DECtrace, DECwindows, OpenVMS, PATHWORKS, VAX, VAX DOCUMENT, VAXcluster, VAXset, VMS, VT, and the :DIGITAL logo are trademarks of Compaq Computer Corporation.

Apple, AppleTalk, HyperCard, HyperTalk, Macintosh, and MacTCP are registered trademarks of Apple Computer, Inc.

4D, 4D External Kit, and 4th Dimension are registered trademarks or trademarks of ACI and ACIUS, Inc.

Hayes is a registered trademark of Hayes Microcomputer Products, Inc.

InterConnections, Inc., Terminal Emulation Services, TES, Network Print Services, NPS, and DECnet/IPX Portal are trademarks of InterConnections, Inc.

Microsoft, Microsoft C, Microsoft COBOL, MS, :MS--DOS, Visual Basic, Windows, Windows 95, Windows 98, and Windows NT are registered trademarks of Microsoft Corporation.

Motif and OSF/Motif are registered trademarks of The Open Group in the United States and other countries.

Novell and NetWare are registered trademarks of Novell, Inc.

Open Desktop and SCO are trademarks of Santa Cruz Operation, Inc.

OPEN LOOK is a registered trademark of UNIX System Laboratories, Inc., a wholly owned subsidiary of Novell, Inc.

Oracle CDD and Oracle Rdb are registered trademarks of Oracle Corporation.

PowerBuilder is a registered trademark of PowerSoft Corporation.

X Window System is a registered trademark of Massachusetts Institute of Technology.

Other product names mentioned herein may be trademarks and/or registered trademarks of their respective companies.

This document is available on :CD-ROM.

This document was prepared using VAX DOCUMENT, Version V3.2-1h.

Contents

Index

This guide describes how to use the DIGITAL TP Desktop Connector software to:

• Incorporate DIGITAL TP Desktop Connector client services in a customer-written desktop client program based on sample code supplied in the kit. The desktop client program signs the user in to the DIGITAL ACMS system, selects DIGITAL ACMS tasks, and signs the user out of the DIGITAL ACMS system.
• Design, code, build, and debug a desktop client program that uses forms processing products and interacts with the end user on the desktop system and a DIGITAL ACMS system.
• Manage the desktop system running the desktop client program and the system running the DIGITAL TP Desktop Connector gateway.

Intended Audience

This guide is intended for readers with diverse backgrounds:

For ACMS developers:

• Part 1 is for users who are knowledgeable about desktop presentation tools and DIGITAL ACMS programming.
• Part 2 describes development procedures for TP Desktop Connector applications.

Manual Structure

This manual has the following structure:

Part 1	Components and Design
Chapter 1	Describes the components of the software and the basic processing that is performed.
Chapter 2	Explains the design essentials.
Chapter 3	Describes the development to be done on the OpenVMS system.
Part 2	Portable API and Macintosh Client Development
Chapter 4	Describes the steps to code, debug, and build a desktop client program that uses TP Desktop Connector client services in a DOS blocking environment.
Chapter 5	Describes the steps to code, debug, and build a desktop client program that uses TP Desktop Connector client services in a Windows, Windows 95, Windows 98, or Windows NT event-driven nonblocking environment.
Chapter 6	Describes the stages to code, debug, and build a desktop client program that uses TP Desktop Connector client services in a Motif, event-driven, nonblocking environment on OpenVMS
Chapter 7	Discusses guidelines for building TP Desktop Connector for ACMS client programs using the forced nonblocking client services.
Chapter 8	Describes the steps to code, debug, and build a desktop client program in a Macintosh environment.
Appendixes
Appendix A	Lists the locations of code that accompanies the TP Desktop Connector software.
Appendix B	Lists the general purpose tools, include files, and sample programs in the ACMSDI$EXAMPLES directory.

Related Documents

For information on developing DIGITAL ACMS applications with TP Desktop Connector for ACMS, refer to the following manuals:

• DIGITAL TP Desktop Connector Getting Started
  Introduces you to the DIGITAL TP Desktop Connector software and provides information for building client applications that call ACMS tasks, ACMSxp tasks, and STDL tasks executing under Portable TP for Windows NT.
• DIGITAL TP Desktop Connector for ACMS Client Services Reference Manual
  Provides a list of client services with their format, parameters, and qualifiers.
• DIGITAL TP Desktop Connector Gateway Management for ACMS
  Describes system management tasks for the gateway.
• DIGITAL TP Desktop Connector 4D Externals User's Guide --- online only
  Describes a set of 4D external functions that you can use to create a TP Desktop Connector Macintosh client program, using 4th Dimension as a development platform. Look for this book in the acmsdi-examples folder on your Macintosh system.
• DIGITAL ACMS for OpenVMS Getting Started
  Provides a high-level discussion and examples of the activities to develop, install, and run a complete application.

If you are new to programming with DIGITAL ACMS software, Compaq recommends reading the following books before using the DIGITAL TP Desktop Connector for ACMS product:

• DIGITAL ACMS for OpenVMS Writing Applications
  Describes procedures to follow using the Application Development Utility (ADU).
• DIGITAL ACMS for OpenVMS Writing Server Procedures
  Describes how to write and debug procedures for DIGITAL ACMS applications. Also supplies reference information for application and system programming services.

For additional information on DIGITAL ACMS software and on installing the TP Desktop Connector for ACMS product, refer to the following manuals:

• DIGITAL ACMS for OpenVMS Introduction
  Describes basic concepts and terms concerning the DIGITAL ACMS environment.
• DIGITAL ACMS for OpenVMS ADU Reference Manual
  Describes the details of the syntax for the definitions you create and the commands you use to build the runtime components.
• DIGITAL TP Desktop Connector for ACMS Installation Guide
  Provides installation requirements and steps to install TP Desktop Connector for ACMS software and verify the installation.
• DECtp Implementation Toolkit
  Provides valuable extensions to VAXset tools to tailor them for developing an DIGITAL ACMS solution. Available through Compaq Services.
• DECtp Design Toolkit
  Provides valuable extensions to DECdesign to help design effective ACMS solutions. Available through Compaq Services.

For information on OpenVMS programming tools and Compaq software engineering standards and practices, refer to these documents:

• Using DECset
  Describes the OpenVMS programming environment, provides helpful hints about conducting a software project, and shows a case study of DECset tools. Provided with the DECset documentation set.
  The DIGITAL ACMS documentation also describes how you can use the VAXset tools to create an effective development environment.
• The Digital Guide to Software Development
  Describes the DIGITAL incremental approach to software development and outlines standards applied in software development. Published by DIGITAL Press and written for managers, programmers, and documentation writers.

Conventions

This guide uses the following conventions and symbols:

User Input	In examples, user input is differentiated in boldface type from system output.
$	The dollar sign indicates a generic command line prompt. This prompt may be different on your system.
[Return]	A key name in a box indicates that you press that key on the keyboard.
[Ctrl]/x	Press the Ctrl (control) key and hold it down while pressing the specified key (indicated here by x).
WORD	Uppercase text indicates OpenVMS data types, commands, keywords, logical names, and routines or services; C files and data structures; Microsoft Windows data structures; and HyperCard data types.
word	In format descriptions, a lowercase word indicates parameters, variables, and services or procedures.
italics	Italic type is used for emphasis and for parameters in text. Titles of manuals are also italicized.
[]	In format descriptions, square brackets surround a choice of options; select none, one, several, or all of the choices.
. . .	A vertical ellipsis in an example means that information not directly related to the example has been omitted.
TP Desktop	Refers to DIGITAL TP Desktop Connector for ACMS software.
CDD	Refers to the Oracle CDD product.
Rdb	Refers to the Oracle Rdb product.
Windows	Refers to Microsoft Windows, Microsoft Windows 95, Microsoft Windows 98, or Microsoft Windows NT.

New Features

TP Desktop Connector for ACMS Version 3.1 contains these new features:

• Enhanced Data Compression Monitor
• Support for TDMS Read and TDMS Write exchange steps
• Dynamic specification of TCP/IP port number
• Simpler installation process

This chapter introduces the DIGITAL TP Desktop Connector Gateway for ACMS components and processing phases.

The following sections discuss the TP Desktop Connector Gateway for ACMS. See DIGITAL TP Desktop Connector for ACMS Gateway Management Guide for a description of system management tasks and transports.

1.1 TP Desktop Connector Gateway for ACMS Components

The TP Desktop Connector software provides access to DIGITAL ACMS systems from desktop systems running their native operating system, such as Microsoft Windows or Macintosh. TP Desktop software implements a client/server computing model in which the following operations are typical:

• The desktop client program makes a request to the TP Desktop Connector software through an application programming interface (API).
• The TP Desktop Connector Gateway for ACMS (server) responds after processing the desktop client program request.

In the TP Desktop client/server model, you develop an application solution comprised of:

• One or more ACMS tasks
• Task group
• Application definitions
• Desktop client program

Figure 1-1 shows a simplified view of the TP Desktop components.

Figure 1-1 TP Desktop Components

You write desktop client programs to run on desktop systems using the TP Desktop Connector client services. Through the TP Desktop client services, these desktop client programs send requests to and receive responses from the ACMS system. The TP Desktop client services and the embedded network software on the desktop system allow the desktop system to transmit and receive TP Desktop Connector messages over a communications medium.

The desktop client program communicates with an ACMS system through the TP Desktop Connector Gateway for ACMS shown in Figure 1-1. The TP Desktop client services call the TP Desktop Connector Gateway for ACMS to execute requests. As an ACMS agent, the TP Desktop Connector Gateway communicates with other ACMS components for the desktop client program and sends the results of requests back through the mutually understood interface.

Access through TP Desktop software to an ACMS system requires a software configuration similar to that shown in Figure 1-2. Although your system need not be exactly the same as the one shown, your system must have at least:

• Desktop client program
• Network link
• TP Desktop Connector Gateway system components
• ACMS TP System

Figure 1-2 TP Desktop Configuration

Desktop client programs interact with the user of the desktop system and access ACMS applications residing on the DIGITAL OpenVMS system. The TP Desktop components support access to ACMS software through the TP Desktop portable client services and the TP Desktop client services for Macintosh.

The TP Desktop portable client services support the following operating systems:

• DIGITAL UNIX
• DOS command line
• Microsoft Windows
• Microsoft Windows 95
• Microsoft Windows NT
• OpenVMS Alpha
• OpenVMS VAX

The programming interface for the DIGITAL UNIX, OpenVMS, Microsoft Windows, Microsoft Windows 95, and Microsoft Windows NT operating systems is the same as the interface for DOS; both blocking and nonblocking client programs are supported. In addition, all seven operating systems can perform I/O tasks.

The TP Desktop client services for Macintosh support a Data Access Manager interface. Macintosh clients can also perform I/O tasks.

1.1.2 Network Components

The network software transmits messages between the desktop client program and the TP Desktop Connector Gateway over the network link shown in Figure 1-2.

Although network software is required for TP Desktop software to work, the programmer does not need to understand networking to develop desktop client programs. The network software is largely transparent to the desktop client program. The TP Desktop client services shield the desktop client program from both the message protocol used by TP Desktop software and the networking services used to implement that protocol.

To communicate, both the TP Desktop Connector Gateway and the desktop systems using TP Desktop software must have the appropriate network software installed. For example, DOS can use either a DECnet or a Novell NetWare ¹ transport. The user or system manager must install this software and ensure that a network connection links the desktop client program to the TP Desktop Connector Gateway.

TP Desktop transparently handles all the network communications necessary to call ACMS tasks running on an OpenVMS system.

Table 1-1 lists the transports TP Desktop supports on OpenVMS VAX Version 5.5-2, Version 6.1, Version 6.2, and Version 7.1.

Table 1-1 Transports for OpenVMS VAX Systems

Clients	Transports
DOS/Windows	DECnet, NetWare, TCP/IP
Windows 95	DECnet, TCP/IP
Windows NT	DECnet, TCP/IP
Macintosh	AppleTalk, DECnet, Serial, TCP/IP
OpenVMS	DECnet, NetWare 1, TCP/IP
DIGITAL UNIX	DECnet, TCP/IP

Table 1-2 lists the transports TP Desktop supports on OpenVMS Alpha Version 6.1, Version 6.2, and Version 7.1.

Table 1-2 Transports for OpenVMS Alpha Systems

Clients	Transports
DOS/Windows	DECnet, NetWare, TCP/IP
Windows 95	DECnet, TCP/IP
Windows NT	DECnet, TCP/IP
Macintosh	AppleTalk, DECnet, Serial, TCP/IP
OpenVMS	DECnet, TCP/IP
DIGITAL UNIX	DECnet, TCP/IP

Refer to DIGITAL TP Desktop Connector for ACMS Gateway Management Guide for detailed information on specifying a transport for communications.

1.1.3 TP Desktop Connector Gateway for ACMS System Components

The TP Desktop Connector Gateway for ACMS typically starts during system initialization. While ACMS software is running, the TP Desktop Connector Gateway accepts TP Desktop sign-in, task start, and sign-out requests from the desktop client program. After the TP Desktop Connector Gateway for ACMS ensures that the desktop client program passes the authentication checks on that OpenVMS system, it processes requests from the program by dispatching them to the ACMS software. The OpenVMS system on which the TP Desktop Connector Gateway runs consists of these major parts:

• ACMS system and customer-written ACMS applications
• TP Desktop Connector Gateway for ACMS
• Network software

In TO Desktop Connector systems, shown in Figure 1-3, the TP Desktop Connector Gateway performs authentication and task invocation for desktop systems.

The TP Desktop Connector Gateway handles user sign-in and is responsible for invoking tasks. The EXC calls the TP Desktop Connector Gateway to handle exchange steps, passing the same type of workspaces and other data to the TP Desktop Connector Gateway that it passes to the Command Process (CP).

The TP Desktop Connector Gateway for ACMS fulfills these roles:

• As a gatekeeper, the TP Desktop Connector Gateway ensures that users of desktop client programs are authorized to access the ACMS system. The users of desktop client programs must pass through the full range of checks that are applied to a user on a VT terminal logging in to the OpenVMS system, and signing in to the ACMS system.
• As a dispatcher, the TP Desktop Connector Gateway routes requests between the desktop system and the ACMS system.

Figure 1-3 TP Desktop-Oriented Components

For efficiency, the TP Desktop Connector Gateway runs as a multithreaded process. It can handle multiple desktops and multiple requests simultaneously. The capacity is controlled by factors such as the maximum network links available on the OpenVMS system, and the licensing scheme. Like all ACMS processes, the TP Desktop Connector Gateway is started before any user activity is requested. This prestarting takes care of all overhead activities before a user request is received. The TP Desktop Connector Gateway design ensures effective use of resources, with optimal throughput and response time.

Because the TP Desktop Connector Gateway complements the Command Process (ACMS CP), using TP Desktop software has no impact on the rest of the ACMS system. As shown in Figure 1-3, the TP Desktop Connector Gateway and the CP can run on the same system. The ACMS application, task group, and task definitions, and the server procedures that support a VT terminal can be used unchanged from a desktop system having TP Desktop software.

VT terminals and desktop systems can use a single runtime instance of an ACMS application simultaneously. The desktop systems use their own presentation procedures, while the VT terminals use DECforms form I/O or TDMS request I/O. The DECforms and TDMS runtime libraries are not used on the desktop system.

The implementation of the TP Desktop Connector Gateway as a complement to the CP ensures that the benefits of the ACMS runtime system are retained. This includes the efficient processing provided by the ACMS runtime system and the capabilities that ACMS software supplies in application control, availability, resource management, event-tracking, and task-level security. TP Desktop Connector software allows you to take full advantage of the unique benefits of both the desktop system and the ACMS software environment.