Compaq TP Desktop Connector
for ACMS

Client Application Programming Guide

Order Number: AA--PG9AH--TE


August 1999

This manual describes how to write, develop, and debug desktop client programs that access Compaq ACMS applications from the desktop, using the Compaq TP Desktop Connector client services.
Revision Update Information: This is a revised manual.
Operating System: Compaq OpenVMS VAX
Compaq OpenVMS Alpha
Software Version: Compaq 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.

© 1991, 1999 Digital Equipment Corporation. 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 CDROM.

This document was prepared using VAX DOCUMENT, Version V3.2-1n.
Contents  Index 


Preface

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

Intended Audience

This guide is intended for readers with diverse backgrounds:

For ACMS developers:

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 ACMS applications with TP Desktop Connector for ACMS, refer to the following manuals: If you are new to programming with ACMS software, Compaq recommends reading the following books before using the Compaq TP Desktop Connector for ACMS product: For additional information on ACMS software and on installing the TP Desktop Connector for ACMS product, refer to the following manuals: For information on OpenVMS programming tools and Compaq software engineering standards and practices, refer to these documents:

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 Compaq 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.1A contains these new features:

Part 1
Components and Design

Part 1 describes the components of the Compaq TP Desktop Connector for ACMS client services software and outlines basic design and development issues for Compaq ACMS solutions. It also discusses Compaq OpenVMS development procedures that are common across desktop platforms.


Chapter 1
Compaq TP Desktop Connector Components and Processing

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

The following sections discuss the TP Desktop Connector Gateway for ACMS. See Compaq 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 Compaq 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:  In the TP Desktop client/server model, you develop an application solution comprised of: 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:

Figure 1-2 TP Desktop Configuration 


 

1.1.1 Desktop Client Program Components

Desktop client programs interact with the user of the desktop system and access ACMS applications residing on the Compaq 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:

The programming interface for the Tru64 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 1 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 
Tru64 UNIX  DECnet, TCP/IP 


1OpenVMS VAX clients support NetWare for test purposes only.

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 
Tru64 UNIX  DECnet, TCP/IP 
Refer to Compaq 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: In TP 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 fulfills these roles:

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.

Note 

1 TP Desktop supports Novell NetWare as a transport over a local area network (LAN).


Next  Contents  Index