Order Number: AA--QPVED--TE

This manual contains the information needed to manage the TP Desktop Connector gateway for ACMS on the system where the Compaq ACMS monitor resides. It also contains information on the network transports that can be used.

Revision Update Information: This is a revised manual.

Operating System: Compaq OpenVMS VAX
Compaq OpenVMS Alpha

TP Monitor: Compaq ACMS for OpenVMS

Software Version: Compaq TP Desktop Connector
Version 3.1A

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 MERCHANTIBILITY, 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.

© 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, ACMS Desktop, DEC, DECdesign, DECforms, DECnet, :DECnet--DOS, DECtp, DECwindows, DIGITAL, OpenVMS, PATHWORKS, PATHWORKS for DOS, PATHWORKS for Macintosh, VAX, VAXcluster, VAXset, VMS, and VT are trademarks of Compaq Computer Corporation.

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

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

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

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

Motif, UNIX, and OSF/Motif are registered trademarks and The Open Group is a trademark of The Open Group in the United States and other countries.

MultiNet is a registered trademark of TGV, Inc.

NetWare and Novell are registered trademarks of Novell, Inc.

Open Desktop is a trademark of Santa Cruz Operations, 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 trademarks of the Oracle Corporation.

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

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

Contents

Index

This manual provides reference information for administration of the TP Desktop Connector gateway for ACMS.

Intended Audience

This guide is intended for application programmers, application designers, and system managers.

Manual Structure

Table 1 describes the structure of this manual:

Table 1 Manual Structure

Chapter	Description
Chapter 1	Provides an introduction to gateway management tasks.
Chapter 2	Outlines the essentials of managing a desktop client program and a TP system for desktop purposes.
Chapter 3	Describes how to prepare the server and the client for use with the various transports that TP Desktop Connector supports.
Chapter 4	Describes how to prepare the server and the client for use with the serial transport.

Related Documents

For information on developing Compaq ACMS applications, refer to the following manuals:

• Compaq TP Desktop Connector for ACMS Client Application Programming Guide
  Provides information for designing, coding, and implementing a TP Desktop Connector solution that uses the client services interface.

• Compaq TP Desktop Connector for ACMS Client Services Reference Manual
  Contains the services and commands needed to create and maintain desktop client programs that use the client services interface.
• Compaq TP Desktop Connector for ACMS Installation Guide
  Provides the steps needed to install a gateway on the OpenVMS system and a TP Desktop Connector API and sample software on the desktop client system.
• Compaq TP Desktop Connector Getting Started
  Introduces you to the Compaq TP Desktop Connector software and provides information for building client applications that use the adapter interface. It also describes how to manage the client interface environment in which the applications run.
• Compaq ACMS for OpenVMS Getting Started
  Provides a high-level discussion and examples of the activities to develop, install, and run a complete Compaq ACMS application.
• Compaq TP Desktop Connector for ACMS 4D Externals User's Guide---online only
  Describes a set of 4D external functions that you can use to create a TP Desktop Connector client program using 4th Dimension as a development platform. Look for this book on your Macintosh in the acmsdi-examples folder.

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

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

For additional information on ACMS software, refer to the following manuals:

• Compaq ACMS for OpenVMS Introduction
  Describes basic concepts and terms concerning the ACMS environment.
• Compaq 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 run-time components.
• DECtp Implementation Toolkit
  Provides valuable extensions to DECset tools to tailor them for developing a Compaq ACMS solution. Available through Compaq Services.
• DECtp Design Toolkit
  Provides valuable extensions to DECdesign software 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 Compaq ACMS documentation also describes how you can use the DECset tools to create an effective development environment.
• The Digital Guide to Software Development
  Describes an incremental approach to software development and outlines standards applicable to software development. Written for managers, programmers, and documentation writers.

Conventions

This guide uses the following conventions and symbols:

user input	In examples, user input is highlighted with bold type.
$	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; or HyperCard data types.
word	In format descriptions, lowercase words indicate parameters, variables, services, or procedures.
italics	Italics are used for emphasis and for parameters in text. Titles of manuals and product names 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 Connector	Refers to the Compaq TP Desktop Connector software.
gateway	Refers to the TP Desktop Connector gateway for ACMS.
Rdb	Refers to the Oracle Rdb product.
Windows	Refers to Microsoft Windows, Microsoft Windows 95 or 98, or Microsoft Windows NT when not specified otherwise.

This manual discusses the system management and administration of the TP Desktop Connector gateway for ACMS, called the gateway in this manual.

1.1 Overview

The gateway is a Compaq ACMS agent that communicates with other ACMS components for the desktop client program and sends the results of requests back to the desktop client. The Gateway client services call the gateway to execute requests. Access to a ACMS system through TP Desktop Connector software requires a software configuration such as the one shown in Figure 1-1.

Figure 1-1 TP Desktop Connector Configuration

As the manager of the system on which the gateway runs, you want to provide users with access to services. Also you want to operate the system for efficient performance.

1.2 System Management with TP Desktop Connector Software

This book describes how to perform system management with TP Desktop Connector software to authorize users, set up networks, and tune the gateway. It describes how to:

• Provide users with the access and authorization necessary for the applications, systems, and networks involved
• Cancel users and tasks
• Manage the gateway to ensure that the network is available
• Customize the gateway and system by setting parameters, user quotas, and specifying the transports to be initialized
• Set up the transports for the gateway and clients
• Determine password expiration information
• Apply cyclic redundancy checking when network or client application errors are a concern.
• Tune the ACMS system using the command procedure ACMSPARAM.COM to automatically calculate and specify system parameters suitable for use with TP Desktop Connector. Provide the accounts under which the TP Desktop Connector Process executes.

The network software transmits messages between the desktop client program and the gateway over the network link as shown in Figure 1-1.

Although network software is required for TP Desktop Connector 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 Connector client services shield the desktop client program from both the message protocol used by TP Desktop Connector software and the networking services used to implement that protocol.

To communicate, both the gateway and the desktop systems using TP Desktop Connector 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 gateway.

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

Table 1-1 lists the transports that TP Desktop Connector 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

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

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

This chapter explains the tasks involved in managing a TP Desktop Connector system:

• Downloading application information from an OpenVMS system to the desktop system (see Section 2.1).
• Authorizing OpenVMS users of desktop client programs to be Compaq ACMS task submitters (see Section 2.2).
• Controlling the TP Desktop Connector system (see Section 2.3).
• Starting and stopping the TP Desktop Connector gateway for ACMS software (see Section 2.4).
• Tuning the ACMS system and gateway parameters to optimize performance (see Section 2.5).
• Troubleshooting on both the OpenVMS system and the desktop client system (see Section 2.6).

This section provides information about synchronizing software versions on the host and desktop systems (see Section 2.1.1) and about downloading software from the host to the desktop system (see Section 2.1.2).

2.1.1 Software Version Synchronization

TP Desktop Connector software does not automatically download task information and forms code to the desktop. You must ensure that the version of the desktop client program running on the desktop system is consistent with the software on the ACMS application node. Refer to the recommended development procedures for version checking for DOS and for Macintosh in the Compaq TP Desktop Connector for ACMS Client Application Programming Guide.

2.1.2 File Server Access for Applications

PATHWORKS software can store DOS or Macintosh applications on the OpenVMS system. This software can automatically download the desktop client programs when a file server on the OpenVMS system is accessed. Refer to the PATHWORKS documentation set for your client.

2.2 Authorizing Users

Authorizing users for TP Desktop Connector applications requires you to perform the following:

1. OpenVMS system authorization on the ACMS submitter node (see Section 2.2.1).
2. ACMS user authorization on the ACMS submitter node (see Section 2.2.2).
3. ACMS device authorization on the ACMS submitter node (see Section 2.2.3).
4. ACMS task authorization in the ACMS application definition (see Section 2.2.4).

The user of the application must be an authenticated OpenVMS user on the ACMS submitter node, that is, the node on which the gateway is running. You can authorize one account for all users or a different account for each user.

The account is not associated with a specific desktop system. A desktop user can have multiple OpenVMS accounts on a ACMS submitter node, or can have accounts on multiple systems, each system running a gateway. Authorization involves validating the user name and password sent from the desktop system to the submitter node.

When a desktop client program calls a TP Desktop Connector client service to sign a user in to the ACMS system, the gateway checks the user name and password. It ensures that all of the following are true, in the order listed:

1. The user name appears in SYSUAF.
2. The user name has not been disabled using the AUTHORIZE command MODIFY user/FLAGS=DISUSER.
3. The account has not expired.

4. The account has no secondary password set.
   If the account has a secondary password set, the gateway rejects the sign-in.
5. At least one of the following conditions is met:
   • The user is permitted network access for the current time of the current type of day (primary or secondary).
   • The user name has been granted the ACMSDI$CLIENT right.
6. The password passed on the call to the sign-in service matches the password stored in the SYSUAF file.
7. The password has not expired.

TP Desktop Connector software ignores the presence of an OpenVMS system password. Authorization can succeed even if a system password is set. TP Desktop Connector imposes no further OpenVMS requirements on the SYSUAF entries for user names specified in calls to the sign-in service.

The following command adds a new user name to SYSUAF allowing the new user access to TP Desktop Connector and the network:

$ SET DEFAULT SYS$SYSTEM $ RUN AUTHORIZE UAF> ADD RODRIGUEZ /NETWORK UAF>

AUTHORIZE copies the settings for the user name DEFAULT to use for RODRIGUEZ, except as specified differently on the ADD command. When adding accounts, follow adequate security and password controls not shown in this example. For information on adding security and password controls, refer to the OpenVMS system management documentation.

To disallow network access for the user name, but still permit the user to sign in to the ACMS system from desktop client programs, enter the following commands:

UAF> ADD RODRIGUEZ /NONETWORK . . . UAF> GRANT /ID ACMSDI$CLIENT RODRIGUEZ

Use the TP Desktop Connector rights identifier ACMSDI$CLIENT. The installation procedure creates the ACMSDI$CLIENT rights identifier.

For security reasons, all types of invalid logins are reported to the desktop client program as ACMSDI_INVLOGIN. However, the protected SWL contains detailed information describing the OpenVMS authorization failure.