Order Number: AA--QPVEC--TE

This manual contains the information needed to manage the TP Desktop Connector Gateway for ACMS on the system where the DIGITAL 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: DIGITAL OpenVMS VAX
DIGITAL OpenVMS Alpha

TP Monitor: DIGITAL ACMS for OpenVMS

Software Version: TP Desktop Connector for ACMS 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 FURNISHINGS, PERFORMANCE, OR USE OF THIS MATERIAL. THIS INFORMATION IS PROVIDED "AS IS" AND COMPAQ COMPUTER CORPORATION DISCLAIMS THE 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.

Copyright ©Digital Equipment Corporation 1995, 1999. 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.

This document is available on :CD-ROM.

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 DIGITAL ACMS applications, refer to the following manuals:

• DIGITAL TP Desktop Connector for ACMS Client Application Programming Guide
  Provides information for designing, coding, and implementing a TP Desktop Connector solution.

• DIGITAL TP Desktop Connector for ACMS Client Services Reference Manual
  Contains the services and commands needed to create and maintain desktop client programs.
• DIGITAL 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.
• DIGITAL TP Desktop Connector Getting Started
  Introduces you to the DIGITAL TP Desktop Connector for ACMS software and provides information for building client applications. It also describes how to manage the environment in which the applications run.
• DIGITAL ACMS for OpenVMS Getting Started
  Provides a high-level discussion and examples of the activities to develop, install, and run a complete application.
• 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 DIGITAL ACMS software, DIGITAL recommends reading the following books before using the 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, 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 run-time components.
• DECtp Implementation Toolkit
  Provides valuable extensions to DECset tools to tailor them for developing a DIGITAL ACMS solution. Available through DIGITAL Services.
• DECtp Design Toolkit
  Provides valuable extensions to DECdesign software to help design effective ACMS solutions. Available through DIGITAL Services.

For information on OpenVMS programming tools and DIGITAL 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 DECset 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 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 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 TP Desktop Connector for ACMS 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 Microsoft Windows NT when not specified otherwise.

This manual discusses the system management and administration of the TP Desktop Connector Gateway for ACMS.

1.1 Overview

The gateway is a DIGITAL ACMS agent that communicates with other DIGITAL 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 DIGITAL 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 TP Desktop Connector Gateway for ACMS. 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.

1.3 Network Software

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 transparently handles all the network communications necessary to call ACMS tasks running on an OpenVMS system.

Table 1-1 lists the transports 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
DIGITAL UNIX	DECnet, TCP/IP

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

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

• Downloading application information from an OpenVMS system to the desktop system.
• Authorizing OpenVMS users of desktop client programs to be DIGITAL ACMS task submitters.
• Controlling the TP Desktop Connector system
• Starting and stopping the TP Desktop Connector Gateway for ACMS.
• Tuning the DIGITAL ACMS system and gateway parameters to optimize performance.
• Troubleshooting on both the OpenVMS system and the desktop client system

The following sections describe downloading information from the host to the desktop system.

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 DIGITAL ACMS application node. Refer to the recommended development procedures for version checking for DOS and for Macintosh in the DIGITAL 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. See 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 DIGITAL ACMS submitter node.
2. DIGITAL ACMS user authorization on the DIGITAL ACMS submitter node.
3. DIGITAL ACMS device authorization on the DIGITAL ACMS submitter node.
4. DIGITAL ACMS task authorization in the DIGITAL ACMS application definition.

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

2.2.2 Authorizing DIGITAL ACMS Users

The user of the application must be an authorized DIGITAL ACMS user on the submitter node. Run the DIGITAL ACMS User Definition Utility on the submitter node and add the user account names. For example:

$ SET DEFAULT SYS$SYSTEM $ RUN ACMSUDU UDU> ADD RODRIGUEZ UDU>

DIGITAL ACMS menus and other user attributes (except for forms-print-file and forms-language) defined in ACMSUDU are not applicable to desktop users.

Authorize as an agent the account under which the gateway runs:

UDU> ADD SYSTEM/AGENT UDU>

If you use the system startup procedure to start the gateway, the OpenVMS account SYSTEM runs the gateway.