DIGITAL TP Desktop Connector for ACMS ___________________________________________________ Installation Guide Order Number: AA-PG9DH-TE January 1999 This document provides information about installing the DIGITAL TP Desktop Connector for ACMS software on desktop systems, and about installing the DIGITAL TP Desktop Connector Gateway for ACMS software on systems running the DIGITAL OpenVMS operating system and DIGITAL ACMS software. It also describes activities associated with these installations, such as the verification procedure. Revision/Update Information: This is a revised manual. Software Version: DIGITAL TP Desktop Connector Version 3.1 for ACMS Compaq Computer Corporation Houston, Texas __________________________________________________________ January 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 FURNISHINGS, 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. © 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, ACMSxp, DEC DEC C, DECforms, DECnet, DECthreads, DECwindows, DIGITAL OpenVMS, PATHWORKS, VAX, VAX C, and VAXshare are trademarks of Compaq Computer Corporation. Apple, AppleShare, AppleTalk, HyperCard, Macintosh, MacTcl, and MacTerminal are registered trademarks of Apple Computer, Inc. HP and HP-UX are registered trademarks of Hewlett-Packard Company. IBM is a registered trademark of International Business Machines Corporation. Intel is a registered trademark of Intel Corporation. Microsoft, Microsoft Access, MS, MS-DOS, Visual Basic, Visual C++, Windows, Windows 95, and Windows NT are registered trademarks of Microsoft Corporation. Motif, UNIX, and X/open are registered trademarks and The Open Group is a trademark of The Open Group in the United States and other countries. NetWare and Novell are registered trademarks of Novell Corporation. ORACLE is a registered trademark and Oracle Rdb is a trademark of Oracle Corporation. PostScript is a registered trademark of Adobe Systems Incorporated. Other product names mentioned herein may be trademarks and /or registered trademarks of their respective companies. This document is available on CD-ROM. ________________________________________________________________ Contents Preface.................................................. xiii Part I Using the Software Products Library CD 1 Before Installing TP Desktop Connector from the Software Products Library CD 1.1 Overview of the Software Products Library Installation................................. 1-1 1.2 Software and Hardware Prerequisites.......... 1-2 1.3 Installation Procedure Requirements.......... 1-3 2 Installing TP Desktop Connector from the Software Products Library CD 2.1 Installing the TP Desktop Connector Gateway for ACMS..................................... 2-2 2.2 Installing the Client Kit.................... 2-2 3 After Installing from the Software Products Library CD 3.1 After Installing TP Desktop Connector Gateway Kit.......................................... 3-1 3.2 After Installing TP Desktop Connector Client Kit.......................................... 3-1 3.2.1 Editing Startup Files.................... 3-2 3.2.2 After Installing Non-VMS Clients......... 3-2 3.2.3 Installing the Client Services Interface on OpenVMS............................... 3-5 3.2.4 Installing the Motif Sample Client for OpenVMS.................................. 3-6 v 3.2.5 Verifying the Motif Sample Installation on OpenVMS............................... 3-7 3.3 Setting Up the Avertz ACMS Sample Application on an OpenVMS System......................... 3-8 3.3.1 Using the Avertz ACMS Sample with Rdb Version 6.0 with Multiversion............ 3-9 3.3.2 Building the Avertz ACMS Sample with DECforms V1.4............................ 3-9 3.3.3 User Name Quotas for the Avertz ACMS Sample................................... 3-10 3.3.4 Access Control List for the Avertz ACMS Sample................................... 3-10 3.3.5 Rebuilding the Avertz ACMS Sample........ 3-10 Part II Using the TPware Product Suite CD 4 Before Installing TP Desktop Connector for ACMS Software 4.1 Installation Overview........................ 4-1 4.2 Preparing to Install TP Desktop Connector Software..................................... 4-4 4.2.1 Product Licenses......................... 4-4 4.2.2 Disk Space............................... 4-4 4.2.3 Removing Previous Software Version....... 4-5 4.3 Removing the Installed Software.............. 4-5 5 Installing TP Desktop Connector Software on Win32 Systems 5.1 TP Desktop Connector Software Installation Procedure.................................... 5-1 5.2 After Installing TP Desktop Connector Software..................................... 5-2 5.2.1 Setting Up the TPware Environment........ 5-2 5.2.2 Accessing the ACMS System................ 5-3 5.2.3 Defining the Network Transport for the Client Services Interface................ 5-3 5.2.4 Verifying the TP Desktop Connector Installation............................. 5-3 5.2.5 Running the Win32 Sample Client Applications............................. 5-4 vi 5.2.6 Code Conversion Libraries for Kanji...... 5-6 6 Installing the TP Desktop Connector Client Services on Non-Win32 Systems 6.1 Overview of the Client Services Installation................................. 6-2 6.1.1 Software Prerequisites................... 6-2 6.1.2 Disk Space............................... 6-3 6.1.3 Resources................................ 6-5 6.2 Installing the Client Services for 16-Bit Microsoft Systems............................ 6-5 6.2.1 Setting Up the Client Services for DOS... 6-6 6.2.2 Installing the Sample Client Application for DOS.................................. 6-6 6.2.3 Verifying the Client Services Installation for DOS..................... 6-7 6.2.4 Setting Up the Client Services for Windows 3.11............................. 6-8 6.2.5 Code Conversion Libraries for Kanji...... 6-8 6.2.6 Installing the Sample Application for Windows 3.11............................. 6-9 6.2.7 Verifying the Client Services Installation on Windows 3.11............. 6-9 6.2.8 Installing the PowerBuilder Sample Application.............................. 6-12 6.2.9 Installing the Visual Basic Sample Applications............................. 6-12 6.2.9.1 Verifying the Visual Basic Avertz Sample Installation.................... 6-13 6.2.9.2 Verifying the Forced Nonblocking Tutorial............................... 6-13 6.3 Installing the Client Services for OpenVMS... 6-14 6.3.1 Installing the Motif Sample Client for OpenVMS.................................. 6-16 6.3.2 Verifying the Motif Sample Installation on OpenVMS............................... 6-17 vii 6.3.3 Setting Up the Avertz ACMS Sample Application on an OpenVMS System......... 6-18 6.3.3.1 Using the Avertz ACMS Sample with Rdb Version 6.0 with Multi-Version......... 6-19 6.3.3.2 Building the Avertz ACMS Sample with DECforms V1.4.......................... 6-20 6.3.3.3 User Name Quotas for the Avertz ACMS Sample................................. 6-20 6.3.3.4 Access Control List for the Avertz ACMS Sample................................. 6-20 6.3.3.5 Rebuilding the Avertz ACMS Sample...... 6-21 6.4 Installing the DIGITAL UNIX Client Software..................................... 6-22 6.4.1 Installing the Motif Sample Client on DIGITAL UNIX............................. 6-23 6.4.2 Verifying the Motif Sample Installation on DIGITAL UNIX.......................... 6-24 7 Installing the TP Desktop Connector Client Services for Macintosh Systems 7.1 Macintosh Installation Options............... 7-1 7.2 Preparing to Install the Macintosh Software..................................... 7-2 7.2.1 Prerequisite Software for Macintosh Systems.................................. 7-2 7.2.2 Disk Space............................... 7-3 7.3 Installing the Macintosh Software............ 7-4 7.3.1 Copying the TP Desktop Connector Installer to the Macintosh............... 7-4 7.3.2 Running the TP Desktop Connector Macintosh Installer...................... 7-5 Part III Using the Gateway CD viii 8 Preparing to Install TP Desktop Connector Gateway for ACMS Software 8.1 Required Operating System Components......... 8-1 8.2 Prerequisite Software........................ 8-2 8.3 Installation Procedure Requirements.......... 8-2 8.3.1 Disk Space............................... 8-2 8.3.2 Privileges and Authorization............. 8-3 8.3.3 OpenVMS License Management Facility...... 8-4 8.3.4 System Disk Backup....................... 8-5 8.3.5 Stopping ACMS and TP Desktop Connector Gateway.................................. 8-5 8.3.6 Locating the Saveset Directory........... 8-6 9 Installing TP Desktop Connector Gateway for ACMS Software 9.1 General Installation Information............. 9-1 9.1.1 Accessing the Online Release Notes....... 9-1 9.1.2 Files and Logical Names Installed on Your System................................... 9-1 9.1.3 Installation Verification Procedure...... 9-2 9.1.4 Aborting the Installation................ 9-3 9.2 Installation Procedure....................... 9-3 9.2.1 Invoking VMSINSTAL....................... 9-3 9.2.2 Installation Questions................... 9-4 9.2.3 Informational Messages................... 9-9 9.2.4 Running the Installation Verification Procedure................................ 9-10 9.2.5 Completing the Installation Procedure.... 9-10 9.3 Recovering from System and Installation Failures..................................... 9-10 9.3.1 System Failures.......................... 9-11 9.3.2 Installation Failures.................... 9-12 9.3.3 IVP Error Recovery....................... 9-13 ix 10 After Installing TP Desktop Connector Gateway for ACMS Software 10.1 Editing the OpenVMS System Files............. 10-1 10.1.1 Editing the System Startup File.......... 10-1 10.1.2 Editing the System Shutdown File......... 10-3 10.2 Performing Cluster Procedures................ 10-3 10.3 Matching Client and Server Versions.......... 10-4 11 Running the TP Desktop Connector Gateway for ACMS IVP 11.1 IVP Operations............................... 11-1 11.2 Running the IVP Independently................ 11-1 11.2.1 IVP Requirements......................... 11-2 11.2.2 IVP Steps................................ 11-2 11.2.3 IVP Error Recovery....................... 11-3 A Files Installed B Common Configuration Errors B.1 Errors Related to the Desktop System......... B-1 B.1.1 Errors on DOS or Windows 3.11 Desktops... B-1 B.1.2 Errors on OpenVMS Desktops............... B-2 B.1.3 Errors on DIGITAL UNIX Desktops.......... B-2 B.2 Errors Related to the ACMS System............ B-3 Index Examples 2-1 Sample Client Installation............... 2-2 B-1 Sample startup.bat File.................. B-1 B-2 Sample config.sys File................... B-2 x Tables 1-1 TP Desktop Connector Disk Space Requirements............................. 1-3 2-1 TP Desktop Connector Files on the Software Products Library CD............. 2-1 3-1 Contents of ACMSDI$NONVMS_CLIENTS........ 3-3 3-2 VR_DA_BLD_MMS.COM Parameters............. 3-11 4-1 Contents of the TPware Product Suite CD....................................... 4-3 4-2 TP Desktop Connector Disk Space Requirements............................. 4-4 6-1 Client Services Sample Applications Software Requirements.................... 6-3 6-2 TP Desktop Connector Client Services Disk Space Requirements on Non-Win32 Systems.................................. 6-3 6-3 VR_DA_BLD_MMS.COM Parameters............. 6-22 7-1 Macintosh Disk Space Requirements........ 7-4 8-1 Disk Space Requirements.................. 8-3 A-1 Files Installed for TP Desktop Connector Client Services for OpenVMS Systems...... A-1 A-2 Files Installed for the Motif Sample for OpenVMS Systems.......................... A-2 A-3 Files Installed for the PowerBuilder Win32 Sample............................. A-4 A-4 Files Installed for the Visual Basic Win32 Sample............................. A-5 A-5 Files Installed for the DOS Sample....... A-6 xi A-6 Files Installed for the Windows 3.11 Sample................................... A-7 A-7 Files Installed for the 16-Bit PowerBuilder Sample...................... A-10 A-8 Files Installed for the Visual Basic Avertz Sample............................ A-11 A-9 Files Installed for the Forced NonBlocking Tutorial..................... A-11 A-10 Files Installed for the Client Services for DIGITAL UNIX Systems................. A-12 A-11 Files Installed for the Motif Sample for DIGITAL UNIX Systems..................... A-13 xii ________________________________________________________________ Preface This guide presents information about installing the DIGITAL TP Desktop Connector for ACMS software on desktop platforms, and the TP Desktop Connector Gateway for ACMS software on OpenVMS platforms. Intended Audience This document is intended for: o Programmers developing client applications with TP Desktop Connector for ACMS software. o System managers responsible for DIGITAL ACMS transac- tion processing installations. To perform the installation and deinstallation procedures described in this guide, you must have administrator (for Windows NT), system (for OpenVMS), or superuser (for DIGITAL UNIX) privileges, and you should be familiar with your operating system's installation procedure. Related Software DIGITAL TP Desktop Connector for ACMS is part of a transaction processing software suite that also contains the following product variants: o DIGITAL TP Desktop Connector for ACMSxp o DIGITAL TP Desktop Connector for Portable TP o DIGITAL TP Web Connector o DIGITAL Portable TP for Windows NT o DIGITAL Application Optimizer for Windows NT xiii Complete information about the relationships of other software products with TP Desktop Connector software is available in the Software Product Description (SPD). The SPD also identifies which versions of your operating system are compatible with TP Desktop Connector software. A copy of the SPD is included in your product kit. You can also find it on the DIGITAL Web site at www.digital.com by searching for TP Desktop Connector in Software Product Descriptions. See the TP Desktop Connector release notes for the actual URL. Related Documents Installation instructions for the ACMSxp and Portable TP versions of TP Desktop Connector appear in the following manuals, respectively: o DIGITAL TP Desktop Connector for ACMSxp Installation Guide o DIGITAL TP Desktop Connector for Portable TP Installation Guide The following manuals contain information about building client applications with TP Desktop Connector products: o DIGITAL TP Desktop Connector Getting Started o DIGITAL TP Web Connector Getting Started o DIGITAL Portable TP for Windows NT Getting Started o DIGITAL Application Optimizer for Windows NT Getting Started The following documents contain information on the TP Desktop Connector Services Interface: o DIGITAL TP Desktop Connector for ACMS Client Application Programming Guide o DIGITAL TP Desktop Connector for ACMS Client Services Reference Manual o DIGITAL TP Desktop Connector for ACMS Gateway Management Guide xiv o DIGITAL ACMS Desktop 4D Externals User's Guide - online only (Look in the acmsdi-examples folder of your Macintosh after installation.) Other manuals contain information about installing and managing your ACMS system and TP Desktop Connector gateway software: o DIGITAL ACMS for OpenVMS Installation Guide Describes the installation of ACMS software on OpenVMS systems. o DIGITAL ACMS for OpenVMS Managing Applications Explains how to start and stop the ACMS system, monitor system performance, and perform some tuning operations. It also tells how to install applications and how to authorize users, devices, and applications. This guide does not provide details about the OpenVMS installation procedure. That information can be found in the Installation and Operations manual for the particular device you use. That manual describes the following procedures: o Handling and mounting the distribution media o Readying the current system and target system devices For information on recommended system management and operations policies and procedures, refer to your site management guide and the volumes in the OpenVMS documentation set that pertain to system management and operations. Finally, the TP Desktop Connector release notes contain information about new features and current restrictions for TP Desktop Connector software. Point your Web browser to the dskcon_release_notes.htm file on either the TPware Product Suite CD or the Software Products Library CD. Compaq recommends that you read the release notes before you install the software. xv Structure This manual is divided into three parts, according to how you received the TP Desktop Connector software. If you have the OpenVMS Software Products Library CD, you should start with Part I. If you have the TPware Product Suite CD or TP Desktop Connector Gateway for ACMS CD, you should start with Part II or III, respectively. The following table describes the contents of each part. __________________________________________________________ __________Using_the_Software_Products_Library_CD__________ Chapter 1 Explains how to prepare your OpenVMS system for installing TP Desktop Connector software from the Software Products Library CD. Chapter 2 Explains how to install TP Desktop Connector and TP Desktop Connector gateway software from the Software Products Library CD. Chapter 3 Describes tasks that might be needed on your OpenVMS system after installing TP Desktop Connector software from the Software Products Library CD. It also provides references to information on post-installation tasks for TP Desktop Connector client software on other platforms. xvi __________________________________________________________ ____________Using_the_TPware_Product_Suite_CD_____________ Chapter 4 Explains how to prepare your system for installing TP Desktop Connector software from the TPware CD. Chapter 5 Describes how to install the TP Desktop Connector software on a 32-bit Microsoft operating system: o Windows NT running on either an Intel or a DIGITAL Alpha processor o Windows 95 or 98 on an Intel processor Chapter 6 Describes how to install the TP Desktop Connector Services Interface client software and sample client applications on the following non-Windows 32-bit desktop platforms: Microsoft DOS Microsoft Windows 3.11 DIGITAL OpenVMS DIGITAL UNIX Chapter 7 Describes how to install the TP Desktop Connector Services Interface client software and sample client applications on Apple Macintosh systems. xvii __________________________________________________________ ____Using_the_TP_Desktop_Connector_Gateway_for_ACMS_CD____ Chapter 8 Explains how to prepare your OpenVMS system for installing TP Desktop Connector Gateway for ACMS software. Chapter 9 Describes how to install the TP Desktop Connector Gateway for ACMS software and sample server-side applications and run the Installation Verification Procedure (IVP). It also tells you how to recover from system and installation failures. Chapter 10 Describes postinstallation procedures that prepare the OpenVMS system for running TP Desktop Connector gateway software. Chapter 11 Describes how to run the installation verification procedure (IVP) separately from ____________the_installation_procedure.___________________ Appendix A lists the files that are installed on your system for the various sample programs. Appendix B contains helpful hints about errors that might occur when you run one of the sample applications. The information in the Appendixes applies no matter which CD you installed. Conventions The following icons appear in the margin to distinguish information that is specific to either OpenVMS VAX or OpenVMS Alpha: The Alpha icon denotes the beginning of information specific to OpenVMS Alpha systems. The VAX icon denotes the beginning of information specific to OpenVMS VAX systems. <> The diamond symbol denotes the end of a section of information specific to either operating system. xviii Additional typographic conventions used in this document are listed below: __________________________________________________________ Convention______Description_______________________________ TP Desktop Represents the DIGITAL TP Desktop Connector Connector for ACMS product software. TP Desktop Represents the DIGITAL TP Desktop Connector Connector Gateway for ACMS product gateway software. UPPERCASE In text, the names of OpenVMS directories, commands, logicals, and so on, are set in all capital letters. FTP Represents the file transfer program of your choice, not necessarily File Transfer Protocol. You can substitute any method that works on your installation and target platforms. italics In text, italics indicate emphasis or the title of a book. courier This font indicates a command, programming language, or an object on your screen. user input In examples, letters that you actually type are highlighted in boldface type. node In examples, italic type indicates variables, parameters, or arguments. You need to substitute the appropriate value. E:\ In examples, the CD-ROM device is assumed to be drive E:. Substitute the correct letter for your system, if needed. C:\TPware_ This is the default destination for the Products\ TPware Product Suite installation program. All the examples in this book use the default. If you choose a different folder during the installation, substitute that drive and folder name. xix __________________________________________________________ Convention______Description_______________________________ . In examples, a vertical ellipsis indicates . that information not directly related to ._______________the_example_has_been_omitted._____________ xx Part I ________________________________________________________________ Using the Software Products Library CD Part I describes how to install DIGITAL TP Desktop Connector for ACMS and DIGITAL TP Desktop Connector Gateway software from the OpenVMS Software Products Library compact disk, also known as the the consolidated distribution (CONDIST) CD. For installations using the TPware Product Suite CD or the TP Desktop Connector Gateway for ACMS CD, see Parts II and III, respectively. 1 ________________________________________________________________ Before Installing TP Desktop Connector from the Software Products Library CD This chapter discusses the preparations and requirements necessary for installing DIGITAL TP Desktop Connector for ACMS and DIGITAL TP Desktop Connector Gateway for ACMS software on an OpenVMS system from the Software Products Library CD. This chapter also provides a general overview of the installation process. If you have the TPware Product Suite or TP Desktop Connector Gateway for ACMS CD, see Part II or III, respectively. TP Desktop Connector software includes online release notes and gives you the option of printing or displaying them during the installation procedure. Compaq strongly recommends that you read the release notes before proceeding with the installation, in case they contain important information regarding the installation procedure. 1.1 Overview of the Software Products Library Installation The TP Desktop Connector for ACMS software is delivered in two distinct product savesets, one for the OpenVMS gateway and one for desktop clients: o The gateway saveset (ACMSDI031.*) Delivers the software required on an OpenVMS system to enable access to DIGITAL ACMS from the desktop systems. Also includes server-side sample applications. You install the gateway software with a regular VMSINSTAL command. o The client saveset (TPW031.A) Before Installing TP Desktop Connector from the Software Products Library CD 1-1 Delivers the software required for application development in a multiplatform, networked, desktop systems environment. Also includes sample client applications. You install the client software by starting with a VMSINSTAL command on an OpenVMS system. The next steps depend on your target desktop platform. The clients are provided as self-extracting archive files that expand upon execution. In general, the procedure for installing the client software and accompanying sample client application files consists of the following steps: 1. Transfer a client archive file to your target desktop platform, using a file transfer program such as FTP. 2. Expand the archive file by executing it. 3. If your target desktop is a Win32 system, run the resulting setup.exe file as explained in Section 5.1. If your target desktop is non-Win32: a. Set up your system for the TP Desktop Connector environment. b. Set up your network transport. These steps are explained in Section 5.2. If your target desktop is an Apple Macintosh, see Chapter 7 4. Run the sample application to verify that the installation functions properly. The following sections discuss the preparations and requirements necessary before installing the TP Desktop Connector for ACMS software. 1.2 Software and Hardware Prerequisites The DIGITAL TP Desktop Connector Version 3.1 Software Product Description (SPD), included on the Software Products Library CD, contains complete information on software products, networks, and systems required for installing and using TP Desktop Connector client and gateway software. 1-2 Before Installing TP Desktop Connector from the Software Products Library CD In addition, installing TP Desktop Connector software requires a certain amount of free storage space. Table 1-1 summarizes the storage requirements for TP Desktop Connector during and after installation. Table_1-1_TP_Desktop_Connector_Disk_Space_Requirements____ Blocks During Blocks After ________________________________Installation_Installation_ TP Desktop Connector Gateway 23 304 6 500 for ACMS software OpenVMS_client_files_____________34_383_______3_300_______ To determine the number of free disk blocks on the current system disk, enter the following command at the DCL prompt: $ SHOW DEVICE SYS$SYSDEVICE In the output column under the heading Free Blocks is the number of 512-byte blocks available on the device. 1.3 Installation Procedure Requirements Both the TP Desktop Connector gateway and client installations from the Software Products Library CD use the VMSINSTAL commannd. See Chapter 8 for instructions. Before Installing TP Desktop Connector from the Software Products Library CD 1-3 2 ________________________________________________________________ Installing TP Desktop Connector from the Software Products Library CD This chapter explains how to install DIGITAL TP Desktop Connector for ACMS and DIGITAL TP Desktop Connector Gateway for ACMS from the OpenVMS Software Products Library CD. Table 2-1 shows the contents of the TP Desktop Connector directory on the library CD. Table 2-1 TP Desktop Connector Files on the Software __________Products_Library_CD_____________________________ Name______________________Description_____________________ ACMSDI031.* TP Desktop Connector Gateway for ACMS savesets DSKCON_ACMS_INSTALL_ This book, formatted for GUIDE.PS PostScript or plain text DSKCON_ACMS_INSTALL_ GUIDE.TXT DSKCON_ACMS_RBI Read Before Installing letter DSKCON_ACMS_RELEASE_ New features and product NOTES.PS restrictions DSKCON_ACMS_RELEASE_ NOTES.TXT DSKCON_ACMS_SPD Software Product Description document TPW031.* TP Desktop Connector client __________________________savesets________________________ Installing TP Desktop Connector from the Software Products Library CD 2-1 2.1 Installing the TP Desktop Connector Gateway for ACMS Installing the gateway kit from the Software Products Library CD is the same as from the TP Desktop Connector Gateway for ACMS CD, except for the location of the product saveset. Refer to the Software Products Library Master Index for the directory name on the library CD. Instructions for VMSINSTAL are in Chapter 9. 2.2 Installing the Client Kit To install the client kit on the OpenVMS system, while logged in under the SYSTEM account at the DCL prompt, type a command in the following format: $ @SYS$UPDATE:VMSINSTAL TPW031 device-name:[directory-name] The value of device-name: is the specification of the drive on which the CD-ROM is mounted and directory-name is the location of the product saveset on the library CD (refer to the Software Products Library Master Index for the directory name). Example 2-1 shows the output from a sample installation. Example 2-1 Sample Client Installation OpenVMS VAX Software Product Installation Procedure V6.2 It is 8-DEC-1998 at 11:31. Enter a question mark (?) at any time for help. (continued on next page) 2-2 Installing TP Desktop Connector from the Software Products Library CD Example 2-1 (Cont.) Sample Client Installation %VMSINSTAL-W-NOTSYSTEM, You are not logged in to the SYSTEM account. %VMSINSTAL-W-ACTIVE, The following processes are still active: NOTES$0145_11* DECW$TE_0C4F KNEELAND FAL_14260004 DECW$TE_0688 _FTA57: _FTA58: ACMS01EXC001000 ACMS01EXC004000 ACMS004SP001000 ACMS01EXC00A000 ACMS00ASP001000 ACMS00ASP002001 * Do you want to continue anyway [NO]? y * Are you satisfied with the backup of your system disk [YES]? The following products will be processed: TPW V3.1 Beginning installation of TPW V3.1 at 11:31 %VMSINSTAL-I-RESTORE, Restoring product save set A ... Installation of TP Desktop Connector for ACMS V3.1 client software started. ************************************************************************** * Copyright (C) 1990, 1999 by * * COMPAQ Computer Corporation, Houston, Texas * * ALL RIGHTS RESERVED. UNPUBLISHED RIGHTS RESERVED UNDER THE * * COPYRIGHT LAWS OF THE UNITED STATES. * ************************************************************************** (continued on next page) Installing TP Desktop Connector from the Software Products Library CD 2-3 Example 2-1 (Cont.) Sample Client Installation %VMSINSTAL-I-SYSDIR, This product creates system disk directory SYS$COMMON:[ACMSDI.VMS_CLIENTS]. %VMSINSTAL-I-RESTORE, Restoring product save set B ... %VMSINSTAL-I-SYSDIR, This product creates system disk directory SYS$COMMON:[ACMSDI.NONVMS_CLIENTS]. %VMSINSTAL-I-RESTORE, Restoring product save set C ... %VMSINSTAL-I-SYSDIR, This product creates system disk directory SYS$COMMON:[SYSHLP.EXAMPLES.ACMSDI.AVERTZ.MOTIF]. %VMSINSTAL-I-RESTORE, Restoring product save set D ... %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... Installation of TP Desktop Connector for ACMS V3.1 client software has ended. Installation of TPW V3.1 completed at 11:33 VMSINSTAL procedure done at 11:33 See Chapter 3 to continue with postinstallation tasks. 2-4 Installing TP Desktop Connector from the Software Products Library CD 3 ________________________________________________________________ After Installing from the Software Products Library CD This chapter describes the procedures, on both the OpenVMS system where the gateway kit was installed and on your target desktop system, that are required for server-side and client-side applications to run and communicate. 3.1 After Installing TP Desktop Connector Gateway Kit Post-installation tasks for TP Desktop Connector Gateway for ACMS are the same whether you install from the Software Products Library CD or the TPware Product Suite CD. See Chapter 10 for information. For TP Desktop Connector Version 3.1 on the Software Products Library, the server-side sample application is part of the client kit, not the gateway kit. The client services files for OpenVMS are laid down when you use VMSINSTAL on the TPW031 saveset. See Section 3.3 for information on the server-side Avertz sample application. 3.2 After Installing TP Desktop Connector Client Kit After installing the client kit from the Software Products Library CD, all the files needed for OpenVMS client applications are in place. If you are developing an OpenVMS client application, you should edit a startup file as shown in Section 3.2.1. If you are developing a client application for a different desktop platform, you should follow Sections Section 3.2.1 and Section 3.2.2. After Installing from the Software Products Library CD 3-1 3.2.1 Editing Startup Files If TP Desktop Connector Gateway for ACMS is already installed on the same system, edit the gateway startup file, SYS$STARTUP:ACMSDI$STARTUP.COM. Remove the comment character (!) from the following logical name definitions for the client directories: $! The next three logical name definitions pertain to TP Desktop Connector $! client libraries and Motif samples and should be defined only after $! installing clients on the same system where the Gateway is installed. $! $! define/system acmsdi$vms sys$common:[acmsdi.vms_clients] $! define/system acmsdi$nonvms_clients sys$common:[acmsdi.nonvms_clients] $! define/system acmsdi$examples_avertz_motif sys$common:[syshlp.examples .acmsdi.avertz.motif] If the gateway is on a different system, add the following logical name definitions to your system startup file: $ define/system acmsdi$vms sys$common:[acmsdi.vms_clients] $ define/system acmsdi$nonvms_clients sys$common:[acmsdi.nonvms_clients] $ define/system acmsdi$examples_avertz_motif sys$common:[syshlp.examples .acmsdi.avertz.motif] 3.2.2 After Installing Non-VMS Clients In addition to OpenVMS client libraries, the client installation loads the self-extracting archive files shown in Table 3-1 on your OpenVMS system. (The logical name ACMSDI$NONVMS_CLIENTS is defined in Section 3.2.1.) 3-2 After Installing from the Software Products Library CD Table_3-1_Contents_of_ACMSDI$NONVMS_CLIENTS____________________ ALPHA32.EXE Runtime and development kit for the entire TPware product suite on DIGITAL Alpha platforms running Microsoft Windows NT DUNIX.EXE TP Desktop Connector client services[1] and samples for DIGITAL UNIX systems INTEL16.EXE TP Desktop Connector client services[1] and samples for 16-bit Microsoft operating systems (DOS, Windows 3.11, or Windows 95) on Intel platforms INTEL32.EXE Runtime and development kit for the entire TPware product suite on Intel platforms running 32-bit Microsoft operating systems (Windows NT or Windows 95) ACMS_DESKTOP.INSTALLER TP Desktop Connector client services[1] ________________________and_samples_for_Apple_Macintosh_systems [1]_Formerly_known_as_the_ACMS_Desktop_"portable API"_services. After installing the TP Desktop Connector client kit on an OpenVMS system, transfer the appropriate archive file to your desktop system and execute it. The archive expands, and the resulting files can then be used. For example, to transfer the client files to a Windows NT system on an Intel platform: 1. Copy from the OpenVMS system the INTEL32.EXE file. Use a network file transfer utility such as FTP. For example: a. On the client system, create a subdirectory to store the software: > mkdir c:\tpw031 b. Change directory to the newly created subdirectory: > cd c:\tpw031 After Installing from the Software Products Library CD 3-3 c. Connect to the OpenVMS system that contains the archive file: > ftp nodename . . . login to host . . . FTP> The value of nodename is the name of the OpenVMS system on which the archive is installed. At the FTP prompts, supply the OpenVMS user name and password. If you successfully log on to the OpenVMS system, type commands at the FTP prompt to copy the archive file from the OpenVMS directory to the client system and close the FTP utility. For example: FTP> binary FTP> cd sys$common:[acmsdi.nonvms_clients] FTP> get intel32.exe FTP> quit 2. On the client system, expand the archive file and delete it to recover disk space. For example: > intel32 > del intel32.exe 3. If you are developing an application for Win32 systems, see Chapter 5. For non-Win32 systems, see Chapters 6 and 7. Or, to transfer the client files to a DIGITAL UNIX system: 1. Copy from the OpenVMS system the dunix.exe file. Use a file transfer utility such as FTP. For example: a. On the client system, create a directory under your home directory: > mkdir tpw031dir 3-4 After Installing from the Software Products Library CD b. Change to the new directory: > cd tpw031dir c. Connect to the OpenVMS system that contains the archive file: > ftp nodename . . . login to host . . . ftp> The value of nodename is the name of the OpenVMS system on which the archive is installed. At the FTP prompts, supply the OpenVMS user name and password. If you successfully log on, type commands at the FTP prompt to copy the archive file and close the FTP utility. For example: ftp> binary ftp> cd sys$common:[acmsdi.nonvms_clients] ftp> get dunix.exe ftp> quit 2. On the client system, expand the archive file and delete it to recover disk space. For example: > chmod 755 dunix.exe > ./dunix.exe > rm dunix.exe 3. The archive expands into two tar files. See Section 6.4. 3.2.3 Installing the Client Services Interface on OpenVMS The client services library is preconfigured for DECnet network access. To build applications that use NetWare or TCP/IP as a transport, you must reconfigure the library before creating executable programs. After Installing from the Software Products Library CD 3-5 The following steps are necessary to set up the client services library for NetWare or TCP/IP access: 1. Remove the DECnet object from the library with the following command: $ library/delete = net_decnet acmsdi$client_objlib.olb 2. For NetWare, insert the NetWare transport access module into the library with the following command: $ library/insert acmsdi$client_objlib.olb net_netware.obj For TCP/IP, insert the TCP/IP transport access module into the library with the following command: $ library/insert acmsdi$client_objlib.olb net_tcpip.obj After these steps, you are ready to build TP Desktop Connector applications that use NetWare or TCP/IP as a transport. Table A-1 shows the files that are added to your desktop system during the installation of the TP Desktop Connector client services for OpenVMS. 3.2.4 Installing the Motif Sample Client for OpenVMS To install the Motif sample files on the OpenVMS desktop system, perform the following steps: 1. Create a directory on the desktop system to contain the sample files and move to that directory: $ create/dir [.motif_avertz] $ set def [.motif_avertz] 2. Copy the Motif sample file: For OpenVMS VAX systems: $ copy cd:[vmsvax.samples]vms_avertz.exe [] <> For OpenVMS Alpha systems: $ copy cd:[vmsalpha.samples]vms_avertz.exe [] <> 3-6 After Installing from the Software Products Library CD 3. Decompress the executable and restore the saveset: $ run vms_avertz.exe . . . accept the default output filename . . . $ backup/restore vms_avertz.sav/save *.*/log 4. Copy the Motif resource file to your home directory: $ copy m_avertz.dat sys$login:m_avertz.dat Table A-2 lists the files that are added to your desktop system. 3.2.5 Verifying the Motif Sample Installation on OpenVMS Compile, link, and run the source code for the sample client program to verify your capability to build applications. To build the sample application, follow these steps: 1. If you have MMS, use the MMS makefile provided to build the m_avertz sample application. In the sample directory, run MMS using the following command: $ MMS If you download TP Desktop Connector libraries to a different location, edit the makefile to indicate the new location of the libraries. ________________________Note_________________________ On OpenVMS Alpha systems, the makefile expects the logical ACMSDI$VMS_ALPHA to point to the directory that contains the TP Desktop Connector client library. In addition, on OpenVMS Alpha systems, the first time that the makefile tries to create the DECwindows library, the makefile fails. When this happens, rerun MMS to continue the build.<> _____________________________________________________ After Installing from the Software Products Library CD 3-7 If you do not have MMS, use the makefile as a guide to build the application yourself. 2. Run the application by entering the following command: > run m_avertz/nodebug The m_avertz application displays the menu bar of the AVERTZ Car Reservation System. If you want the sample desktop client program to communicate with the ACMS application, follow the procedures in Section 6.3.3 to set up the sample application on the ACMS system. After you set up the ACMS system, use the Session menu to sign in to the ACMS system. After you sign in, you can use the Rental menu to run the reserve task of the AVERTZ application. The installation procedure is now complete and verified. 3.3 Setting Up the Avertz ACMS Sample Application on an OpenVMS System The command procedure VR_DA_RUNTIME_SETUP.COM sets up the sample application. You need SYSPRV privilege to run the procedure. See the file ACMSDI$VR_APPLICATION_INFO.TXT in the ACMSDI$EXAMPLES_AVERTZ directory for more information on setting up the sample. To prepare the AVERTZ sample application on the DIGITAL OpenVMS system, do the following: 1. Run the command procedure to set up the application: $ @ACMSDI$EXAMPLES_AVERTZ:VR_DA_RUNTIME_SETUP . . . $ 2. Start the ACMS system (if necessary) and the applica- tion: $ ACMS/START SYSTEM $ ACMS/START APPLICATION VR_DA_APPL 3. Perform other management tasks related to your system, for example, authorizing user accounts. See the management information in DIGITAL TP Desktop Connector for ACMS Client Application Programming Guide. 3-8 After Installing from the Software Products Library CD The following sections provide additional information about using the Avertz sample application on the ACMS OpenVMS system. 3.3.1 Using the Avertz ACMS Sample with Rdb Version 6.0 with Multiversion When you execute the VR_DA_RUNTIME_SETUP.COM file to set up the sample application, this command file invokes two option files, VR_READ_SERVER.OPT and VR_UPDATE_SERVER.OPT, which refer to the SYS$LIBRARY:SQL$USER library. On a system with Rdb Version 6.0 with multiversion installed, the SYS$LIBRARY:SQL$USER file is not available. Instead, the version number is appended to the file name, for instance, SYS$LIBRARY:SQL$USER60. To work around this naming mismatch problem, you can define the logical name SQL$USER to reference the appropriate library file. For example: $ DEFINE SQL$USER SYS$LIBRARY:SQL$USER60 Modify the linker options files: ACMSDI$EXAMPLES_AVERTZ:VR_READ_SERVER.OPT ACMSDI$EXAMPLES_AVERTZ:VR_UPDATE_SERVER.OPT Replace the line SYS$LIBRARY:SQL$USERnn.OLB/LIBRARY with the following: SYS$USER/LIBRARY 3.3.2 Building the Avertz ACMS Sample with DECforms V1.4 The VR_FORM.IFDL file of the Avertz ACMS sample applica- tion cannot be compiled under DECforms Version 1.4. This is because the DECforms Version 1.4 IFDL parser no longer recognizes the colon symbol (:), which the VR_FORM.IFDL file uses. To get around this problem, put double quotation marks around the text containing the ":" symbol in the VR_ FORM.IFDL file. After Installing from the Software Products Library CD 3-9 For example, change the following: Copy AVERTZ_CDD_FIELD:CUSTOMER_ID from Dictionary End Copy To look like: Copy "AVERTZ_CDD_FIELD:CUSTOMER_ID" from Dictionary End Copy 3.3.3 User Name Quotas for the Avertz ACMS Sample The VR_DA_RUNTIME_SETUP.COM command file assigns quotas for the AVERTZ_EXC, AVERTZ_UPD, and AVERTZ_READ user names that are adequate for running the VR_DA_APPL sample application. If your system already has these user names defined, the quotas for these user names might be inadequate for VR_DA_APPL. If you are using the AVERTZ sample application, delete the AVERTZ_EXC, AVERTZ_UPD, and AVERTZ_READ user names before running VR_DA_RUNTIME_ SETUP.COM to ensure that you get appropriate quotas for these user names. To ensure the success of the operations in the VR_DA_ RUNTIME_SETUP.COM command procedure, run it from the system account. 3.3.4 Access Control List for the Avertz ACMS Sample The VR_DA_RUNTIME_SETUP.COM procedure adds the AVERTZ application name VR_DA_APPL to the ACMS database. The command line to do so includes the ACL qualifier and assigns the ID as /ID=SYSTEM. This might fail on your system. To ensure that the VR_DA_RUNTIME_SETUP.COM procedure works, change the ID=SYSTEM to ID=[UIC], where UIC is that of the account SYSTEM; for example, ID=[1,4]. 3.3.5 Rebuilding the Avertz ACMS Sample Executables are provided for the sample. You do not need to rebuild the sample to run it. However, a DEC/MMS description file is provided for rebuilding the sample to incorporate any changes you make to the sample. 3-10 After Installing from the Software Products Library CD To modify and rebuild the sample, follow these steps: 1. Copy the sample sources to another directory. 2. Use the command procedure VR_DA_BLD_MMS.COM to rebuild the sample under a different ADB name in that directory: a. Create the CDD directories for the AVERTZ compo- nents. b. Define logical names. If you are using a directory other than ACMSDI$EXAMPLES_AVERTZ for rebuilding the sample, edit the logical name definitions in the VR_DA_BLD_LOGICALS.COM command procedure to point to your file and CDD directories. Make these edits before running the BLD portion of the VR_DA_BLD_MMS.COM command procedure. c. Perform other setup and build activities. 3. Run the command procedure VR_DA_BLD_MMS.COM without parameters: $ @ACMSDI$EXAMPLES:VR_DA_BLD_MMS All the setup and build activities are performed. To perform a specific activity, specify one of the parameters in Table 6-3. Table_3-2_VR_DA_BLD_MMS.COM_Parameters____________________ Keyword__________Activity_________________________________ BLD Run MMS to build VR_DA_APPL CDD Set up the CDD dictionary and directories for VR_DA_APPL DB_______________Create_the_VEHICLE_RENTALS_database______ After Installing from the Software Products Library CD 3-11 Part II ________________________________________________________________ Using the TPware Product Suite CD Part II describes DIGITAL TP Desktop Connector for ACMS software installation from the TPware Product Suite CD on a Win32 system. This part covers the client-side software and samples, but not the server-side software and samples. See Part III for the server-side instructions. 4 ________________________________________________________________ Before Installing TP Desktop Connector for ACMS Software This chapter describes the preparations and requirements necessary for installing DIGITAL TP Desktop Connector for ACMS software. Your bill of materials (BOM) and indented bills report (BIL) specify the number and contents of your media. Be sure to verify the contents of your kit with this information. If your kit is damaged or incomplete, contact your Compaq representative. This chapter also contains information on removing TP Desktop Connector software from Win32 platforms. 4.1 Installation Overview The TPware Product Suite CD contains all the software required for development or deployment of TP Desktop Connector client applications, except for the gateway needed to connect to an ACMS system. The gateway is distributed separately. Table 4-1 lists the contents of the TPware CD-ROM. As shown in Table 4-1, all TP Desktop Connector files are provided on the TPware Product Suite CD. This compact disk is in ISO9660 standard format and contains executable programs that install the appropriate files. You must have a Windows NT or Windows 95/98 system with a CD drive on which to run the installation procedures that are described in Chapter 5. TP Desktop Connector supports the following platforms in addition to 32-bit Microsoft operating systems (Windows NT and Windows 95/98): o 16-bit Microsoft operating systems running on Intel platforms o DIGITAL OpenVMS running on VAX or Alpha systems Before Installing TP Desktop Connector for ACMS Software 4-1 o DIGITAL UNIX systems o Macintosh systems If you are developing TP Desktop Connector client applications for any of the above non-Win32 systems, you must install the client services files yourself. Refer to Chapters 6 and 7. 4-2 Before Installing TP Desktop Connector for ACMS Software Table_4-1_Contents_of_the_TPware_Product_Suite_CD______________ Name__________Contents_________________________________________ \alpha32 Runtime and development kit for the entire TPware product suite on DIGITAL Alpha platforms running Microsoft Windows NT \dunix TP Desktop Connector client services[1] and samples for DIGITAL UNIX systems \install_ Installation guides for all of the TPware guides products, formatted for Web browsing \intel16 TP Desktop Connector client services[1] and samples for 16-bit Microsoft operating systems (DOS, Windows 3.11, or Windows 95) on Intel platforms \intel32 Runtime and development kit for the entire TPware product suite on Intel platforms running 32-bit Microsoft operating systems (Windows NT or Windows 95/98) \mac TP Desktop Connector client services[1] and samples for Apple Macintosh systems \vmsalpha TP Desktop Connector client services[1] and samples for OpenVMS Alpha systems \vmsvax TP Desktop Connector client services[1] and samples for OpenVMS VAX systems dskcon_ Information on new features and known release_ restrictions for all three varieties of TP notes.htm Desktop Connector optimizer_ Information on new features and known release_ restrictions for Application Optimizer for notes.htm Windows NT portable_ Information on new features and known tp_release_ restrictions for Portable TP for Windows NT notes.htm webcon_ Information on new features and known release_ restrictions for TP Web Connector notes.htm______________________________________________________ [1] Formerly_known_as_the_ACMS_Desktop_"portable_API"_services. Before Installing TP Desktop Connector for ACMS Software 4-3 4.2 Preparing to Install TP Desktop Connector Software Ensure that your system meets the software requirements. Minimum software requirements needed to install the TP Desktop Connector software and build client applications that run with ACMS systems are shown in the Software Product Description (SPD). 4.2.1 Product Licenses To install TP Desktop Connector products, you must have a Product License Key. This is a paper certificate that contains information about the license you have to run a particular piece of software. You are asked to enter the license key during the installation procedure. 4.2.2 Disk Space Installing TP Desktop Connector software requires a certain amount of free storage space, which depends on the platform you use. Table 4-2 shows the storage requirements for TP Desktop Connector. Table_4-2_TP_Desktop_Connector_Disk_Space_Requirements____ __________________________Intel_______________Alpha_______ Kilobytes_(KB)____________6_063_______________6_517_______ ________________________Note_________________________ These are the minimum disk space requirements. These estimates, though conservative, are not always an accurate indicator of the disk space used on a particular machine. System disk configuration, including the size of the disk sector and the number of sectors per cluster, cannot be determined by the installation program. Therefore, some systems require more space. _____________________________________________________ See Table 6-2 for the disk space required for TP Desktop Connector client services software on non-Win32 systems. 4-4 Before Installing TP Desktop Connector for ACMS Software 4.2.3 Removing Previous Software Version Compaq recommends that you remove any previous versions of TP Desktop Connector before upgrading to Version 3.1. Removing TP Desktop Connector Version 3.1 is not necessary if you simply plan to select additional products or components. See Section 4.3 for details. 4.3 Removing the Installed Software You might decide to remove the installed TPware software in order to upgrade to a new TPware software version, or for other reasons. Note that when you remove the software, you lose the settings defined in the TPware Management Utility. See the release notes for instructions on saving your management settings prior to removing the software. You can remove the installed TP Desktop Connector software from your system using either the shortcut provided in the TPware products program group, or the system Add/Remove Programs utility. ________________________Note_________________________ The uninstall procedure removes all currently installed TPware products. _____________________________________________________ o To remove the software using the shortcut provided in the TPware program group: 1. Click the Start button. 2. Choose the Programs menu. 3. Choose the TPware Products program group. If you chose a different program group while installing TP Desktop Connector for ACMS, that group name is displayed on the Programs menu in place of TPware Products. 4. Choose the Uninstall TPware item. Before Installing TP Desktop Connector for ACMS Software 4-5 o To remove the software using the system Add/Remove Programs utility: 1. Double click the Add/Remove Programs icon in the Control Panel window. 2. Choose the DIGITAL TPware item. 3. Click the Add/Remove... button. 4-6 Before Installing TP Desktop Connector for ACMS Software 5 ________________________________________________________________ Installing TP Desktop Connector Software on Win32 Systems This chapter describes the procedures for installing or reinstalling the DIGITAL TP Desktop Connector for ACMS software from the TPware Product Suite CD on Microsoft Windows NT running on an Intel or a DIGITAL Alpha system, or Windows 95/98 on an Intel system. This chapter also contains information on postinstallation tasks on Windows NT or Windows 95/98 systems. For information on installing TP Desktop Connector software on non-Win32 platforms, see Chapters 6 and 7. For information on installing TP Desktop Connector gateway software, see Part III of this guide (Chapters 8 through 11). 5.1 TP Desktop Connector Software Installation Procedure To install TP Desktop Connector software, run one of the setup programs provided on the TPware Product Suite CD. Double-click (or choose Run from the Start menu and enter) one of the following: E:\alpha32\setup.exe E:\intel32\setup.exe Replace E: with the correct drive letter for your system. The setup program displays a splash screen and a progress indicator while it initializes its wizard. When setup starts, you see a series of dialog boxes. The following table lists the operations associated with the command buttons in the dialog boxes. Installing TP Desktop Connector Software on Win32 Systems 5-1 __________________________________________________________ To_do_this...___________________Click_this_button:________ Complete the choices in a Next dialog box and continue Return to a previous dialog Back box Exit without completing the Cancel installation______________________________________________ Follow the instructions in the dialog boxes to select installation of TP Desktop Connector for ACMS. The setup utility checks whether there is sufficient disk storage, copies the appropriate files, and performs registry operations. If setup finds that a requisite software product is not installed or that the minimum version of a requisite product is not on the system, it displays a Warning box showing the product name and version. The installation might continue after the warning or it might fail, depending on the prerequisite. If the installation continues, you must install the prerequisite software before you can actually use TP Desktop Connector software. 5.2 After Installing TP Desktop Connector Software This section describes some procedures you might want to perform after the setup program finishes. 5.2.1 Setting Up the TPware Environment Before developing TPware client applications, you must set up the environment variables that TPware software requires. To do this, run the command file installed by the setup program: C:\TPware\stdl\bin\stdl_set_version.bat ________________________Note_________________________ All examples show the default location. If you chose a different destination while running setup, substitute your own drive and folder for C:\TPware. _____________________________________________________ 5-2 Installing TP Desktop Connector Software on Win32 Systems 5.2.2 Accessing the ACMS System For access to a DIGITAL ACMS transaction processing system, the TP Desktop Connector Gateway for ACMS must be installed on the OpenVMS system. The gateway software is distributed on a separate CD; instructions for installing it are contained in Part III of this guide. 5.2.3 Defining the Network Transport for the Client Services Interface TP Desktop Connector Version 3.1 supports both DECnet and TCP/IP network transports for Windows NT or Windows 95 clients. The product files include two versions of the client application's dynamic link library (DLL); one for DECnet and one for TCP/IP. These files are installed, by default, in: C:\TPware\stdl_rt\bin\acmsdiDN.dll C:\TPware\stdl_rt\bin\acmsdiWS.dll To set up the TP Desktop Connector software for your network transport, copy the appropriate DLL from the installation folder to your working directory, and rename it acmsdi.dll. The acmsdiDN.dll provides DECnet support and works with PATHWORKS 32. The acmsdiWS.dll provides TCP/IP support and also works with PATHWORKS 32. 5.2.4 Verifying the TP Desktop Connector Installation To verify that your TP Desktop Connector software is installed correctly, you can run one of the sample applications provided. If you are developing an application that uses the Adapter Interface (described in DIGITAL TP Desktop Connector Getting Started), both the sample applications and the instructions for running them are online. To read the instructions, choose the ACMS Samples item from the TP Desktop Connector for ACMS menu in the TPware Products program group. Installing TP Desktop Connector Software on Win32 Systems 5-3 For a TP Desktop Connector for ACMS application that uses the Services Interface,[*] you must have platform-specific TP Desktop Connector client software on your development system. All the client services files are on the TPware Product Suite CD, but they are not all installed by the setup program. Setup handles Win32 operating systems only. If you are developing a TP Desktop Connector client application that uses the Services Interface, in a non-Win32 operating system, you must transfer the TP Desktop Connector client services files to your desktop development system yourself. How to do this varies according to platform: o For 16-bit Microsoft systems, DIGITAL OpenVMS, and DIGITAL UNIX, systems, see Chapter 6. o For Apple Macintosh systems, see Chapter 7. If you are developing a TP Desktop Connector client application that uses the Services Interface on a Win32 system, the client services files are installed on your desktop by the setup program with the rest of the development tools. The instructions for setting up the client services and running the sample programs are in the following sections of this chapter. You do not need to read Chapters 6 or 7. 5.2.5 Running the Win32 Sample Client Applications TP Desktop Connector for ACMS Version 3.1 client services include two sample applications for Win32 clients: o For Windows 95, in PowerBuilder, a simplified version of the original AVERTZ for Windows described in the ACMS manuals. This sample illustrates the execution of an ACMS task with no exchange I/O. Table A-3 describes the contents of the PowerBuilder sample folder TPware\STDL\Samples\acmsdi\PB. For directions on running the PowerBuilder sample, read the three .doc files in the sample folder. ___________________ [*]Formerly known as the ACMS Desktop "portable API", and as opposed to the new TPware automation interface. 5-4 Installing TP Desktop Connector Software on Win32 Systems o For Windows 95 or Windows NT, the same Visual Basic AVERTZ sample that was provided for ACMS Desktop V2.0; it is a blocking, no exchange I/O client. Table A-4 describes the contents of the Visual Basic sample folder TPware\STDL\Samples\acmsdi\VB. The following files provide memory copy procedures and can be used to help with interfacing Visual Basic Win32 programs with the TP Desktop Connector client services: C:\TPware\STDL\lib\divb.lib C:\TPware\STDL_RT\bin\divb.dll C:\TPware\STDL_RT\bin\msvcrt40.dll To verify the success of your TP Desktop Connector client services installation, you can run the Visual Basic sample application. Follow these steps: 1. Start up the Visual Basic development environment in Windows 95. 2. Open the VBAVERTZ project. 3. Verify that all the required files were loaded (see the VBAVERTZ project window): vbavertz.bas mainmenu.frm reserve.frm signin.frm Double click each item in the project window to verify that it loads properly. 4. Run the interpreted version of VBAVERTZ (choose the Start command from the Run menu). Installing TP Desktop Connector Software on Win32 Systems 5-5 5.2.6 Code Conversion Libraries for Kanji TP Desktop Connector client services provides code conversion libraries for Kanji users, which convert Shift JIS code to DEC Kanji code and DEC Kanji code to Shift JIS code. You can link these libraries with your client application, if it requires Kanji code conversion. The following files are installed for Kanji applications: C:\TPware\stdl\lib\jcnvwin.lib C:\TPware\stdl\include\jcnvwin.h C:\TPware\help\jcnvwin_guide.ps C:\TPware\help\jcnvwin_guide.txt For usage information, refer to either the PostScript or the text version of the Japanese conversion guide. 5-6 Installing TP Desktop Connector Software on Win32 Systems 6 ________________________________________________________________ Installing the TP Desktop Connector Client Services on Non-Win32 Systems The TP Desktop Connector client services software was previously released as the ACMS Desktop "portable API" services. It allows client applications running on a variety of desktop platforms to call ACMS tasks. For TP Desktop Connector Version 3.1, the client services software is distributed on the TPware Product Suite CD in folders (directories) according to the desktop platform. This chapter is also organized by platform: __________________________________________________________ For_this_platform_________________________See_._._._______ 16-bit[1] Microsoft operating systems, Section 6.2 that is, DOS or Windows 3.11 (also known as Windows for Workgroups (WfW)) DIGITAL OpenVMS systems Section 6.3 DIGITAL_UNIX_systems______________________Section_6.4_____ [1]For_Win32_Microsoft_operating_systems,_see_Section_5.2_ Section 6.1 presents a general overview of the installa- tion process and its prerequisites. For information on TP Desktop Connector client services for Apple Macintosh systems, see Chapter 7. For information on how to design and develop client applications using the TP Desktop Connector client services software, see the following ACMS books: o DIGITAL TP Desktop Connector for ACMS Client Application Programming Guide o DIGITAL TP Desktop Connector for ACMS Client Services Reference Manual Installing the TP Desktop Connector Client Services on Non-Win32 Systems 6-1 6.1 Overview of the Client Services Installation The TPware Product Suite CD is in ISO 9660 standard format. The instructions in this chapter assume that you can mount this CD directly on your desktop system. If you can not, you will have to use ftp or some other network file transport to get the files from a Windows 95 or Windows NT system that has the TPware CD mounted. The client services are provided as self-extracting archive files that expand upon execution. In general, the procedure for installing the client services and accompanying sample client application files consists of the following steps: 1. Transfer a client services archive to your desktop platform 2. Execute it 3. Set up your system for the TPware environment 4. Set up the client services for your network transport 5. Transfer and execute a sample client archive 6. Run the sample to verify that the installation functions properly. The following sections discuss the preparations and requirements necessary before installing the TP Desktop Connector client services and sample files. 6.1.1 Software Prerequisites The TP Desktop Connector SPD contains information on software prerequisites for installing TP Desktop Connector. Table 6-1 lists the products required to use the various client services sample applications. 6-2 Installing the TP Desktop Connector Client Services on Non-Win32 Systems Table 6-1 Client Services Sample Applications Software __________Requirements____________________________________ Platform___________Products_Required______________________ DOS Microsoft COBOL Version 5.0 or higher Microsoft Visual C++ Version 1.52 or higher Windows 3.11 SDK Microsoft Windows Version 3.11 or higher Microsoft Visual C++ Version 1.52 or higher Visual Basic Microsoft Windows Version 3.11 or higher Microsoft Visual Basic Version 4.0 or higher Motif on OpenVMS VAX C for OpenVMS Version 3.0 or higher DECwindows Motif for OpenVMS Alpha Version 1.0 Motif on DIGITAL DEC C, DECwindows Developers Kit on UNIX_______________DIGITAL_UNIX_for_OSF/Motif_Version_1.1_ 6.1.2 Disk Space Table 6-2 lists the disk space required for each of the desktop systems. Table 6-2 TP Desktop Connector Client Services Disk Space __________Requirements_on_Non-Win32_Systems_______________ OpenVMS_VAX_Client___________________Number_of_Blocks_____ Client services library and network 322 software Common headers 31 Motif sample files 305 (continued on next page) Installing the TP Desktop Connector Client Services on Non-Win32 Systems 6-3 Table 6-2 (Cont.) TP Desktop Connector Client Services Disk Space Requirements on Non-Win32 __________________Systems_________________________________ OpenVMS_Alpha_Client_________________Number_of_Blocks_____ Client services library and network 709 software Common headers 31 Motif sample files 489 __________________________________________________________ DOS_and_Windows_3.11_Client__________Number_of_Bytes______ Client services libraries and 2 187 264 network software Common files 70 222 Kanji conversion libraries 182 748 COBOL sample files 421 888 Windows sample files 437 248 __________________________________________________________ Macintosh_Client_____________________Number_of_Blocks_____ Client services library, network 2 538 software, and sample files Common headers 31 __________________________________________________________ DIGITAL_UNIX_Client__________________Number_of_Bytes______ Client services library and TCP/IP 261 748 module Motif sample files 291 826 Common_headers__________________________30_206____________ 6-4 Installing the TP Desktop Connector Client Services on Non-Win32 Systems 6.1.3 Resources Before you start the installation procedure, obtain the following: o DECnet node name (host name on TCP/IP) for the OpenVMS system on which the TP Desktop Connector Gateway for ACMS is installed o Valid account (user name and password) on the OpenVMS system on which the TP Desktop Connector Gateway for ACMS is installed o Directory of the network file transfer software in your directory search path or on your CD-ROM o Directory in which the TPware files reside on an OpenVMS system, or your CD-ROM device (usually E:\) o Directory in which to install the client services software o Sufficient disk space, as shown in Table 6-2 o Host name for TCP/IP 6.2 Installing the Client Services for 16-Bit Microsoft Systems TP Desktop Connector provides one self-extracting archive named i16_client.exe that contains all the client services files for both DOS and Windows 3.11 clients. The files contained within the archive include the static-link (LIB) and the dynamic-linked (DLL) libraries. Also included are individual object files and DLLs for the supported transports. To install the client services software, transfer the archive file to your desktop system and execute it. The archive expands, and the resulting files can then be used. For example: C:\> mkdir ACMSDI C:\> cd ACMSDI C:\ACMSDI> copy E:\intel16\i16_client.exe C:\ACMSDI> i16_client.exe Installing the TP Desktop Connector Client Services on Non-Win32 Systems 6-5 If this is to be your working directory, you need to set the environment variables that define the paths for the libraries, include files, and executables. You do this by adding commands to your autoexec.bat file. For example: set LIB=%LIB%;ACMSDI set INCLUDE=%INCLUDE%;ACMSDI set PATH=%PATH%;ACMSDI 6.2.1 Setting Up the Client Services for DOS The DOS client services use the static-link library ACMSDIL.LIB, which supports DECnet by default. Additional network transport object files are provided for the large- memory model, whose names reflects the transport they support. __________________________________________________________ Memory_Model__DECnet________TCP/IP________Netware_________ Large_________netdecl.obj___nettcpl.obj___netwarel.obj____ If you are not using DECnet, remove the DECnet module and insert the module that corresponds to the transport you are using. For example, to set up up the large model for TCP/IP: LIB ACMSDIL.LIB -NETDECL; LIB ACMSDIL.LIB +NETTCPL; 6.2.2 Installing the Sample Client Application for DOS The client services sample for DOS is written in Microsoft COBOL and is in a self-extracting archive file named i16_ cobol.exe. Transfer this file to your desktop platform, and execute it. For example: C:\ACMSDI\> mkdir cobol C:\ACMSDI\> cd cobol C:\ACMSDI\COBOL> copy e:\intel16\Samples\i16_cobol.exe C:\ACMSDI\COBOL> i16_cobol.exe Table A-5 shows the resulting files. The sample executable was built using the DECnet libraries. If you are not running DECnet, you need to relink the sample before you can run it. 6-6 Installing the TP Desktop Connector Client Services on Non-Win32 Systems 6.2.3 Verifying the Client Services Installation for DOS Compile, link, and run the source code for the sample client program to verify your capability to build applications. You need the following products on your desktop system to build the sample application: o Compiler (preferably Microsoft C) that can access objects compiled by Microsoft Visual C++ Version 1.5 or higher o C runtime library that is compatible with Microsoft Visual C++ Version 1.5 o COBOL compiler compatible with Microsoft COBOL software (required only to build the sample application) The client services samples include two batch files to build the COBOL client program. You can modify these files according to your own software development environment. After you modify the files, run them. For example: C:\ACMSDI\COBOL> bld-pps . . . C:\ACMSDI\COBOL> bld-cli . . . To run the sample client program, enter the following command: C:\ACMSDI\COBOL> client The client program displays the main menu of the AVERTZ Vehicle Rental System application. To connect the sample program to the AVERTZ sample application, follow the procedures in Section 6.3.3 to set up the sample application on the ACMS system. You can sign in to the ACMS system and use the reserve task of the application. The DOS installation procedure is now complete and verified. Installing the TP Desktop Connector Client Services on Non-Win32 Systems 6-7 6.2.4 Setting Up the Client Services for Windows 3.11 You would normally use a DLL when building applications under Windows. However, you can use the static-link libraries provided with TP Desktop Connector if you prefer, when the transport is DECnet. The client services sample for Windows 3.11 expects to find a DLL called acmsdi.dll To set up the client services for your network transport, copy one of the files below to your working directory and rename it acmsdi.dll. __________________________________________________________ DECnet___________TCP/IP___________Netware_________________ acmsdiDN.dll_____acmsdiWS.dll_____acmsdiNW.dll____________ For example, to use TCP/IP with the Winsock interface: C:\ACMSDI> mkdir sdk311 C:\ACMSDI> copy acmsdiWS.dll sdk311\acmsdi.dll There is an executable file, diTskLnk.exe, that supports multiple executables sharing a submitter session under Windows Version 3.1 using TCP/IP. See the DIGITAL TP Desktop Connector for ACMS Gateway Management Guide for information on this executable file. 6.2.5 Code Conversion Libraries for Kanji TP Desktop Connector provides code conversion libraries for Kanji users, which convert Shift JIS code to DEC Kanji code and DEC Kanji code to Shift JIS code. You can link these libraries with your client application, if it requires Kanji code conversion. These libraries are located in the following archive file: E:\intel16\win16\jcnvwin.exe For usage information, refer to JCNVWIN_GUIDE.PS or JCNVWIN_GUIDE.TXT, which are installed when you expand the archive. 6-8 Installing the TP Desktop Connector Client Services on Non-Win32 Systems 6.2.6 Installing the Sample Application for Windows 3.11 The client services sample for Windows 3.11 is written in C and is provided in two self-extracting archive files. The file sdk311lib.exe contains both the sample sources and the make file for using the DECnet medium model static-link library. The file sdk311dll.exe contains just the alternate files needed to rebuild the sample client against DLLs. The resulting executable file can work with any of the supported transports. Start by transferring the sources archive to your desktop platform and running it. For example: C:\ACMSDI> cd sdk311 C:\ACMSDI\SDK311> copy e:\intel16\Samples\sdk311lib.exe C:\ACMSDI\SDK311> sdk311lib.exe If you want the DLL version, first get the sources as above, then get the other archive and run it. This overrides the static-link makefiles. For example: C:\ACMSDI\SDK311> copy e:\intel16\Samples\sdk311dll.exe C:\ACMSDI\SDK311> sdk311dll.exe Table A-6 shows the resulting files. 6.2.7 Verifying the Client Services Installation on Windows 3.11 Compile, link, and run the source code for the sample client program to verify your capability to build applications. You need the following products on your desktop system to build the C language sample application: o Compiler (preferably Microsoft C) that can access objects compiled by Microsoft Visual C++ Version 1.52 or higher o C runtime library that is compatible with Microsoft Visual C++ Version 1.52 o Microsoft Windows for Workgroups Version 3.1.1. o If building against static link libraries, you need the PATHWORKS Version 5.1 Software Developer's Kit. Installing the TP Desktop Connector Client Services on Non-Win32 Systems 6-9 To verify the installation of the TP Desktop Connector client services for Windows 3.11, follow these steps: 1. Using the AVERTZ makefile, build the sample application by running nmake in the directory that contains the sample files. C:\ACMSDI\SDK311> nmake -f avertz 2. Run Windows by entering the following command: C:\ACMSDI\SDK311> win 3. Run the AVERTZ program by one of the following methods: o Use the Run command: a. In the Program Manager File menu, select the Run command. b. In the dialog box that appears, type the location: \ACMSDI\SDK311\avertz o Add the AVERTZ program icon to the screen and double click on it: a. In the Program Manager File menu, select the New command. This creates a group window to contain the icon. b. In the dialog box, select the new program group and click the OK button. c. At the description prompt, type a name for the group window. For example: ACMS Desktop Samples d. Give a file name for the group window. For example: C:\ACMSDI\SDK311\sample 6-10 Installing the TP Desktop Connector Client Services on Non-Win32 Systems After you enter the name, a window appears having the group window name. e. Click on the new group window to select it. f. In the Program Manager's File menu, select the New command to add the AVERTZ icon to the group window. g. In the dialog box, select new Program Item. h. In the description prompt, type the icon caption. For example: AVERTZ i. After the command-line prompt, type the location of the AVERTZ executable file. For example: C:\ACMSDI\SDK311 j. In the dialog box, click the OK button. The AVERTZ icon appears in the group window. k. Double click the AVERTZ icon to run the sample client program. The AVERTZ program displays the menu bar of the AVERTZ Vehicle Rental System application. If you want the sample desktop client program to communicate with the ACMS application, follow the procedures in Section 6.3.3 to set up the sample application on the ACMS system. After you set up the ACMS system, use the Session menu to sign in to the ACMS system. After you sign in, you can use the Rental menu to run the reserve task of the AVERTZ application. The Windows 3.11 installation procedure is now complete and verified. Installing the TP Desktop Connector Client Services on Non-Win32 Systems 6-11 6.2.8 Installing the PowerBuilder Sample Application There is a PowerBuilder Version 5.0 sample application provided on the TPware Product Suite CD as a self- extracting archive file named \intel16\i16_pb.exe. This sample is a simplified version of the original Avertz for Windows; it illustrates the execution of an ACMS task with no exchange I/O. The archive provides a PowerBuilder library, pbaverz.pbl, that contains the PowerBuilder objects for the Avertz client application, and a dynamic-link library, pb- pointr.dll that is required for memory management when building PowerBuilder applications that use TP Desktop Connector Gateway for ACMS services. To install the PowerBuilder sample, copy the archive file to your desktop and execute it. For example: C:\ACMSDI> mkdir pbsmp C:\ACMSDI> cd pbsmp C:\ACMSDI\PBSMP> copy e:\intel16\i16_pb.exe C:\ACMSDI\PBSMP> i16_pb.exe Table A-7 lists the files that are added to your system. For instructions on using the PowerBuilder sample, read the three .doc files shown in Table A-7. 6.2.9 Installing the Visual Basic Sample Applications There are two Visual Basic sample applications provided on the TPware Product Suite CD in the form of self-extracting archive files. The file \intel16\Samples\i16_avertz.exe contains the files for the same sample that was provided for ACMS Desktop V2.0; it is a blocking, no exchange I/O client. The file i16_fnb.exe (in the same folder) contains the files of a tutorial sample showing how to program to the new TP Desktop Connector Gateway for ACMS forced non- blocking interface. This interface allows languages like Visual Basic to issue non-blocking calls to TP Desktop Connector Gateway for ACMS and provides support for programming ACMS exchange I/O interface calls. 6-12 Installing the TP Desktop Connector Client Services on Non-Win32 Systems To install the selected sample, copy the corresponding archive to your desktop system and execute it. For example: C:\ACMSDI> mkdir vbavertz C:\ACMSDI> cd vbavertz C:\ACMSDI\VBAVERTZ> copy e:\Samples\i16_avertz.exe C:\ACMSDI\VBAVERTZ> i16_avertz.exe Table A-8 lists the files added to your system from the Avertz archive; Table A-9 lists the files from the Forced Nonblocking tutorial. 6.2.9.1 Verifying the Visual Basic Avertz Sample Installation To verify the success of the Visual Basic sample installation, bring up the Visual Basic development environment under Microsoft Windows: 1. Open the VBAVERTZ.MAK project using the Open command in the File menu. 2. Verify that all the required files were loaded. (See the VBAVERTZ.MAK project window): VBAVERTZ.BAS MAINMENU.FRM RESERVE.FRM SIGNIN.FRM Double click on each entry in the project window to verify that it loads properly. 3. Run the interpreted version of VBAVERTZ, by selecting the Start command in the Run menu. 6.2.9.2 Verifying the Forced Nonblocking Tutorial To verify the successful installation of the Forced Nonblocking tutorial (from file i16_fnb.exe), bring up the Visual Basic development environment in Microsoft Windows: 1. Open the FNBSAMPL.MAK project using the Open command in the File menu. 2. Add files ACMSDI.BAS and FORMS.BAS to the FNBSAMPL project by selecting Add File from the File menu. Installing the TP Desktop Connector Client Services on Non-Win32 Systems 6-13 ________________________Note_________________________ ACMSDI.BAS and FORMS.BAS were installed on your system as described in Section 6.2. _____________________________________________________ 3. Add file CONSTANT.TXT from the C:\VB directory. 4. Verify that all of the required files were loaded. (See the FMBSAMPL.MAK project window): FORM1.FRM FRMLOGIN.FRM FRMRECVC.FRM ACMSDI.BAS CONSTANT.TXT FORMS.BAS MTEXT.BAS NONBLK.BAS Double click each entry in the project window to verify that it loads properly. 5. Run the interpreted version of FNBSAMPL by selecting the Start command from the Run menu. 6.3 Installing the Client Services for OpenVMS For TP Desktop Connector Version 3.1, the client services kit is separate from the TP Desktop Connector Gateway for ACMS kit. The client services files for OpenVMS are provided as a compressed saveset that you can copy from the TPware CD mounted on your desktop platform. After copying the client services software, you decompress the file and restore the saveset. Follow these instructions to install the client services for OpenVMS: 1. Create the client services directory on the desktop system. Note that this directory must be created from a user account, not from the system account. $ create/dir [.acmsdi] 6-14 Installing the TP Desktop Connector Client Services on Non-Win32 Systems 2. Copy the file to that directory: For OpenVMS VAX systems: $ set def [.acmsdi] $ copy cd:[vmsvax]vms_client.exe [] $ run vms_client.exe . . . accept the default output filename . . . $ backup vms_client.sav/save *.*/log <> For OpenVMS Alpha systems: $ set def [.acmsdi] $ copy cd:[vmsalpha]vms_client.exe [] $ run vms_client.exe . . . accept the default output filename . . . $ backup vms_client.sav/save *.*/log <> 3. The TP Desktop Connector library is preconfigured for DECnet network access. To build applications that use NetWare or TCP/IP as a transport, you must reconfigure the library before creating executable programs. Installing the TP Desktop Connector Client Services on Non-Win32 Systems 6-15 The following steps are necessary to set up the TP Desktop Connector library for NetWare or TCP/IP access: a. Remove the DECnet object from the library with the following command: $ library/delete = net_decnet acmsdi$client_objlib.olb b. For NetWare, insert the NetWare transport access module into the library with the following command: $ library/insert acmsdi$client_objlib.olb net_netware.obj For TCP/IP, insert the TCP/IP transport access module into the library with the following command: $ library/insert acmsdi$client_objlib.olb net_tcpip.obj After these steps, you are ready to build TP Desktop Connector applications that use NetWare or TCP/IP as a transport. Table A-1 shows the files that are added to your desktop system during the installation of the TP Desktop Connector client services for OpenVMS. 6.3.1 Installing the Motif Sample Client for OpenVMS To install the Motif sample files on the OpenVMS desktop system, perform the following steps: 1. Create a directory on the desktop system to contain the sample files and move to that directory: $ create/dir [.motif_avertz] $ set def [.motif_avertz] 2. Copy the Motif sample file. For OpenVMS VAX systems: $ copy cd:[vmsvax.samples]vms_avertz.exe [] <> For OpenVMS Alpha systems: $ copy cd:[vmsalpha.samples]vms_avertz.exe [] <> 6-16 Installing the TP Desktop Connector Client Services on Non-Win32 Systems 3. Decompress the executable and restore the saveset: $ run vms_avertz.exe . . . accept the default output filename . . . $ backup/restore vms_avertz.sav/save *.*/log 4. Copy the Motif resource file to your home directory: $ copy m_avertz.dat sys$login:m_avertz.dat Table A-2 lists the files that are added to your desktop system. 6.3.2 Verifying the Motif Sample Installation on OpenVMS Compile, link, and run the source code for the sample client program to verify your capability to build applications. To build the sample application, follow these steps: 1. If you have MMS, use the MMS makefile provided to build the m_avertz sample application. In the sample directory, run MMS using the following command: $ MMS If you download TP Desktop Connector libraries to a different location, edit the makefile to indicate the new location of the libraries. Installing the TP Desktop Connector Client Services on Non-Win32 Systems 6-17 ________________________Note_________________________ On OpenVMS Alpha systems, the makefile expects the logical ACMSDI$VMS_ALPHA to point to the directory that contains the TP Desktop Connector client library. In addition, on OpenVMS Alpha systems, the first time that the makefile tries to create the DECwindows library, the makefile fails. When this happens, rerun MMS to continue the build.<> _____________________________________________________ If you do not have MMS, use the makefile as a guide to build the application yourself. 2. Run the application by entering the following command: > run m_avertz/nodebug The m_avertz application displays the menu bar of the AVERTZ Car Reservation System. If you want the sample desktop client program to communicate with the ACMS application, follow the procedures in Section 6.3.3 to set up the sample application on the ACMS system. After you set up the ACMS system, use the Session menu to sign in to the ACMS system. After you sign in, you can use the Rental menu to run the reserve task of the AVERTZ application. The installation procedure is now complete and verified. 6.3.3 Setting Up the Avertz ACMS Sample Application on an OpenVMS System The command procedure VR_DA_RUNTIME_SETUP.COM sets up the sample application. You need SYSPRV privilege to run the procedure. See the file ACMSDI$VR_APPLICATION_INFO.TXT in the ACMSDI$EXAMPLES_AVERTZ directory for more information on setting up the sample. To prepare the AVERTZ sample application on a DIGITAL OpenVMS system, do the following: 1. Run the command procedure to set up the application: $ @ACMSDI$EXAMPLES_AVERTZ:VR_DA_RUNTIME_SETUP . . . $ 6-18 Installing the TP Desktop Connector Client Services on Non-Win32 Systems 2. Start the ACMS system (if necessary) and the applica- tion: $ ACMS/START SYSTEM $ ACMS/START APPLICATION VR_DA_APPL 3. Perform other management tasks related to your system, for example, authorizing user accounts. See the management information in DIGITAL TP Desktop Connector for ACMS Client Application Programming Guide. The following sections provide additional information about using the Avertz sample application on the ACMS OpenVMS system. 6.3.3.1 Using the Avertz ACMS Sample with Rdb Version 6.0 with Multi-Version When you execute the VR_DA_RUNTIME_SETUP.COM file to set up the sample application, this command file invokes two option files, VR_READ_SERVER.OPT and VR_UPDATE_SERVER.OPT, which reference the SYS$LIBRARY:SQL$USER library. On a system with Rdb Version 6.0 with multi-version installed, the SYS$LIBRARY:SQL$USER file is not available. Instead, the version number is appended to the file name, for instance, SYS$LIBRARY:SQL$USER60. To work around this naming mismatch problem, you can define the logical name SQL$USER to reference the appropriate library file. For example: $ DEFINE SQL$USER SYS$LIBRARY:SQL$USER60 Modify the linker options files: ACMSDI$EXAMPLES_AVERTZ:VR_READ_SERVER.OPT ACMSDI$EXAMPLES_AVERTZ:VR_UPDATE_SERVER.OPT Replace the line SYS$LIBRARY:SQL$USERnn.OLB/LIBRARY with the following: SYS$USER/LIBRARY Installing the TP Desktop Connector Client Services on Non-Win32 Systems 6-19 6.3.3.2 Building the Avertz ACMS Sample with DECforms V1.4 The VR_FORM.IFDL file of the Avertz ACMS sample applica- tion can not be compiled under DECforms Version 1.4. This is because the DECforms Version 1.4 IFDL parser no longer recognizes the colon symbol (:), which the VR_FORM.IFDL file uses. To get around this problem, put double quotation marks around the text containing the ":" symbol in the VR_ FORM.IFDL file. For example, change the following: Copy AVERTZ_CDD_FIELD:CUSTOMER_ID from Dictionary End Copy To look like: Copy "AVERTZ_CDD_FIELD:CUSTOMER_ID" from Dictionary End Copy 6.3.3.3 User Name Quotas for the Avertz ACMS Sample The VR_DA_RUNTIME_SETUP.COM command file assigns quotas for the AVERTZ_EXC, AVERTZ_UPD, and AVERTZ_READ user names that are adequate for running the VR_DA_APPL sample application. If your system already has these user names defined, the quotas for these user names might be inadequate for VR_DA_APPL. If you are using the AVERTZ sample application, delete AVERTZ_EXC, AVERTZ_UPD, and AVERTZ_READ user names before running VR_DA_RUNTIME_ SETUP.COM to ensure that you get appropriate quotas for these user names. To ensure the success of the operations in the VR_DA_ RUNTIME_SETUP.COM command procedure, run it from the system account. 6.3.3.4 Access Control List for the Avertz ACMS Sample The VR_DA_RUNTIME_SETUP.COM procedure adds the AVERTZ application name VR_DA_APPL to the ACMS database. The command line to do so includes the ACL qualifier and assigns the ID as /ID=SYSTEM. This might fail on your system. 6-20 Installing the TP Desktop Connector Client Services on Non-Win32 Systems To ensure that the VR_DA_RUNTIME_SETUP.COM procedure works, change the ID=SYSTEM to ID=[UIC], where UIC is that of the account SYSTEM; for example, ID=[1,4]. 6.3.3.5 Rebuilding the Avertz ACMS Sample Executables are provided for the sample. You do not need to rebuild the sample to run it. However, a DEC/MMS description file is provided for rebuilding the sample to incorporate any changes you make to the sample. To modify and rebuild the sample, follow these steps: 1. Copy the sample sources to another directory. 2. Use the command procedure VR_DA_BLD_MMS.COM to rebuild the sample under a different ADB name in that directory: a. Create the CDD directories for the AVERTZ compo- nents. b. Define logical names. If you are using a directory other than ACMSDI$EXAMPLES_AVERTZ for rebuilding the sample, edit the logical name definitions in the VR_DA_BLD_LOGICALS.COM command procedure to point to your file and CDD directories. Make these edits before running the BLD portion of the VR_DA_BLD_MMS.COM command procedure. c. Perform other setup and build activities. 3. Run the command procedure VR_DA_BLD_MMS.COM without parameters: $ @ACMSDI$EXAMPLES:VR_DA_BLD_MMS All the setup and build activities are performed. To perform a specific activity, specify one of the parameters in Table 6-3. Installing the TP Desktop Connector Client Services on Non-Win32 Systems 6-21 Table_6-3_VR_DA_BLD_MMS.COM_Parameters____________________ Keyword__________Activity_________________________________ BLD Run MMS to build VR_DA_APPL CDD Set up the CDD dictionary and directories for VR_DA_APPL DB_______________Create_the_VEHICLE_RENTALS_database______ 6.4 Installing the DIGITAL UNIX Client Software The TP Desktop Connector client services and sample application files are distributed as archive (tar(1)) files on the TPware products CD. To install the client services on a DIGITAL UNIX desktop system, follow the instructions below. Note that the instructions recommend copying the client services library to /usr/lib/libacmsdi.a, so that you can refer to it in your link command as '-lacmsdi'. You need superuser privileges to copy into the /usr/lib directory. You can leave the TP Desktop Connector library in the client services directory. If you do, you need to use the full path to the library in your link command, instead of using the '-lacmsdi' option. 1. Create the client services directory on the desktop system, and change to that directory. For example: > mkdir acmsdi > cd acmsdi 2. Copy the archive file from the TPware CD to the client services directory. For example: > cp e:/dunix/du_client.tar . 3. Extract the files from the archive. For example: acmsdi> tar xvf du_client.tar . . . 6-22 Installing the TP Desktop Connector Client Services on Non-Win32 Systems The list of files printed because of the v flag should match the list of files in Table A-10. 4. If you want to use the DECnet transport, change the client library. For example: > su # ar d libacmsdi.a net_tcpip.o # ar r libacmsdi.a net_decnet.o # ar t libacmsdi.a . . . # ar qs libacmsdi.a Also edit the Makefile to add -ldnet to the link library list. 5. Copy the TP Desktop Connector client library to the system directory: # cp libacmsdi.a /usr/lib/libacmsdi.a . . . 6. Update the copied library file: # ar qs /usr/lib/libacmsdi.a 7. Exit superuser mode: # > 6.4.1 Installing the Motif Sample Client on DIGITAL UNIX To install the Motif sample files on the DIGITAL UNIX system, perform the following steps: 1. Create a directory on the desktop to contain the sample files and move to that directory: > mkdir avertz > cd avertz Installing the TP Desktop Connector Client Services on Non-Win32 Systems 6-23 2. Copy the sample archive from the TPware products CD: > cp e:\dunix\du_avertz.tar . 3. Extract the sample files: > tar xvf du_avertz.tar . . . The list of files printed should match the list in Table A-11. The sample makefile and executables for Motif on DIGITAL UNIX presume a TCP/IP transport. If you have changed the client services library to use DECnet, you must relink the sample application before you run it. 6.4.2 Verifying the Motif Sample Installation on DIGITAL UNIX Compile, link, and run the source code for the sample client program to verify your capability to build applications. To build the sample application, follow these steps: 1. Use the makefile provided to build the m_avertz sample application. In the sample directory, run make: > make 2. Run the application by entering the following command: > m_avertz The m_avertz application displays the menu bar of the AVERTZ Car Reservation System. If you want the sample desktop client program to communicate with the ACMS application, follow the procedures in Section 6.3.3 to set up the sample application on the ACMS system. After you set up the ACMS system, use the Session menu to sign in to the ACMS system. After you sign in, you can use the Rental menu to run the reserve task of the AVERTZ application. The installation procedure is now complete and verified. 6-24 Installing the TP Desktop Connector Client Services on Non-Win32 Systems 7 ________________________________________________________________ Installing the TP Desktop Connector Client Services for Macintosh Systems This chapter describes the installation of the TP Desktop Connector client services and samples for Apple Macintosh clients. After you install the TP Desktop Connector Gateway for ACMS software on the DIGITAL OpenVMS system, you can install the TP Desktop Connector client services software on individual desktop systems. 7.1 Macintosh Installation Options You can choose any of several installation options depending on the type of services you want to install on the target Macintosh: o Run-Time Services option Permits the execution of TP Desktop Connector client applications, but does not include files that are helpful for developing new applications. You can install Run-Time Services with or without the Calypso Tool, which provides support for dialin applications to the host ACMS Desktop server. Choose this option (with or without Calypso) if you do not intend to develop new TP Desktop Connector applications on the target Macintosh. o System Services option Includes the Run-Time Services plus a set of files that aids in the development of new TP Desktop Connector client applications on the target Macintosh. This option does not include the various examples that illustrate the use of the TP Desktop Connector client services. Choose the System Services option if you do not require the assistance of the examples, and want to conserve the disk space that the examples occupy. Installing the TP Desktop Connector Client Services for Macintosh Systems 7-1 o Examples option Includes the following: - Sample applications written in 4th Dimension, HyperCard, and C. - Two sets of 4th Dimension Externals that invoke the TP Desktop Connector client services, one of which includes C source code to illustrate how to write your own 4th Dimension Externals. - A set of HyperCard XFCNs that invoke the TP Desktop Connector client services, including C source code. - A set of utility files containing C source code for date and data conversion functions and programs useful in managing your development platform. You can install the Examples option separately, after installing the Run-Time Services. 7.2 Preparing to Install the Macintosh Software This section describes the preparations and requirements for installing the TP Desktop Connector client services software for Macintosh systems. 7.2.1 Prerequisite Software for Macintosh Systems Before you install the software, do the following: 1. Install TP Desktop Connector Gateway for ACMS software on the OpenVMS system running ACMS. 2. If you choose to use a VAXshare volume as the source from which to copy the client software to your Macintosh, identify a disk device on which to build a VAXshare volume. If you choose not to use a VAXshare volume as the source from which to copy the client software: a. Install a file transfer tool such as XMODEM or a DECnet file server on your host OpenVMS system. b. Install a corresponding file transfer tool such as MacTerminal or NetCopy on the Macintosh. 7-2 Installing the TP Desktop Connector Client Services for Macintosh Systems 3. Install the appropriate Communications Tools on your Macintosh for the transports you plan to use: - AppleTalk-DECnet Tool To use the AppleTalk-DECnet Gateway - DECnet Tool To manage your Macintosh as a DECnet node - MacTCP To use a TCP/IP communications transport - AppleTalk ADSP Tool To manage your host OpenVMS node as a socket in an AppleTalk Internet - A tool that implements serial communications protocols, such as the Serial Tool or the Apple Modem Tool. To use serial communications 4. If you plan to manage your OpenVMS node as a socket in an AppleTalk Internet, install the PATHWORKS AppleTalk for OpenVMS Transport on your OpenVMS system. 5. Log in to the OpenVMS system using an account with sufficient privileges. Using the SYSTEM account is recommended. 7.2.2 Disk Space The required disk space on your Macintosh depends on the installation option you choose, as listed in Table 7-1. Installing the TP Desktop Connector Client Services for Macintosh Systems 7-3 Table_7-1_Macintosh_Disk_Space_Requirements_______________ Option_____________________Disk_Space_____________________ Run-Time Services 138K bytes Run-Time Services and 263K bytes Calypso System Services 183K bytes System Services and 308K bytes Calypso Examples 2612K bytes System Services, Calypso, 2920K bytes and_Examples______________________________________________ 7.3 Installing the Macintosh Software This section describes how to install the TP Desktop Connector client services software for Macintosh on a Macintosh system. 7.3.1 Copying the TP Desktop Connector Installer to the Macintosh All the files that comprise the TP Desktop Connector Macintosh client software are compacted into a single installation file, ACMSDI_DESKTOP.INSTALLER. The installation procedure consists of the following steps: 1. Copy or FTP ACMSDI_DESKTOP.INSTALLER to the target Macintosh. 2. Double click the installer file. 3. Follow the instructions that are displayed. 7-4 Installing the TP Desktop Connector Client Services for Macintosh Systems The files on the TPware Product Suite and Software Products Library CDs are in MacBinary format. Many file transfer facilities such as NetCopy and MacTerminal automatically convert files from MacBinary to standard Macintosh format as part of the copy operation. If your file transfer utility does not automatically do so, use a tool such as MacBinary Converter (mBin) to convert the ACMSDI_DESKTOP.INSTALLER to standard Macintosh format after you copy it. After you have successfully copied the ACMSDI_DESKTOP.INSTALLER file to your Macintosh, proceed to Section 7.3.2. 7.3.2 Running the TP Desktop Connector Macintosh Installer The ACMSDI_DESKTOP.INSTALLER file is a self-extracting file containing all the TP Desktop Connector Macintosh client services files in compressed form. During installation, files are automatically moved to the appropriate folders. The installation process provides instructions with each step: 1. Begin the installation process by double clicking on the ACMSDI_DESKTOP.INSTALLER file. 2. A window appears that identifies the product as TP Desktop Connector Version 2.3. Click on the Continue button. 3. A second window appears containing a copyright notice. Read the copyright notice. Buttons are available to save or print the notice. You can cancel the installation at this point by clicking the Cancel button, in which case nothing is installed. Click the Continue button if you want to proceed with the installation. 4. The next window provides some information about the installer. It tells you where the files to be installed will be placed and tells how much disk space is required for the (standard) full installation. The Calypso Tool mentioned is the software that enables serial (dialin) communication between TP Desktop Connector client applications and the host ACMS Desktop server. Installing the TP Desktop Connector Client Services for Macintosh Systems 7-5 You have three buttons to choose from at this point: a. Custom button: Allows you to proceed to another window where you can choose which parts of the software you want to install. b. Quit button: Allows you to cancel the installation at this point; nothing is installed. c. Install button: Causes a full installation to occur; everything is installed. If you want a standard, full installation, click the Install button now, and skip to step 6. If you want to examine additional options, click the Custom button and proceed to step 5. 5. If you choose a custom installation, a window appears with six installation options. Text appears to describe each option and how much disk storage it requires. Section 7.1 presents a more complete description of the installation options. - System Services, Calypso, and Examples: This option installs everything. It is identical to the standard installation presented on the previous window. - System Services: This option installs everything except the examples and Calypso software. - System Services and Calypso: This option installs everything except the examples. - Examples: This option installs the examples only. Use it as a follow-up installation to a system services or run-time services option with or without Calypso. - Run-Time Services: This option installs only the basic software needed for run-time support. The development aids, the Examples and the Calypso software are not installed. 7-6 Installing the TP Desktop Connector Client Services for Macintosh Systems - Run-Time Services and Calypso: This option installs the basic software needed for run-time support and the Calypso software. The development aids and examples are not installed. You again have three buttons from which to choose: a. Standard button: Allows you to return to the standard installation window. b. Quit button: Allows you to cancel the installation at this point; nothing is installed. c. Install button: Cause an installation to occur. Before clicking on this button, select one of the installation options by clicking on it to highlight it. 6. Clicking on the Install button from either the standard or custom installation window causes a window to appear from which you can select the location to place the folder "TP Desktop Connector folder (2.3)". All files except the DDEV and Calypso Tool are installed in this folder. Clicking the Cancel button cancels the installation, in which case nothing is installed. Clicking the Save button causes the installation to occur, as indicated by a progress window. 7. If the installation is successful, a dialog box appears indicating success. From this window, you can quit or continue with additional installations. Installing the TP Desktop Connector Client Services for Macintosh Systems 7-7 Part III ________________________________________________________________ Using the Gateway CD Part III describes DIGITAL TP Desktop Connector Gateway for ACMS software installation from the Gateway CD on an OpenVMS system. This part covers the server-side software and samples, but not the client-side software and samples. See Part II for the client-side instructions. 8 ________________________________________________________________ Preparing to Install TP Desktop Connector Gateway for ACMS Software This chapter discusses the preparations and requirements necessary for installing DIGITAL TP Desktop Connector Gateway for ACMS software. Your bill of materials (BOM) and indented bills report (BIL) specify the number and contents of your media. Be sure to verify the contents of your kit with this information. If your kit is damaged or incomplete, contact your Compaq representative. TP Desktop Connector gateway software includes online release notes and gives you the option of printing or displaying them during the installation procedure. Compaq strongly recommends that you read the TP Desktop Connector release notes before proceeding with the installation, in case they contain important information regarding the installation procedure. 8.1 Required Operating System Components To install TP Desktop Connector gateway software, you must have one of the following operating systems installed: OpenVMS VAX operating system o Version 5.5-2 o Version 6.1 o Version 6.2 o Version 7.1 o Version 7.2 <> OpenVMS Alpha operating system o Version 6.1 Preparing to Install TP Desktop Connector Gateway for ACMS Software 8-1 o Version 6.2 o Version 7.1 o Version 7.2 <> 8.2 Prerequisite Software The Software Product Description (SPD) contains a list of the prerequisite software, as well as a complete list of the products that are compatible with this version of TP Desktop Connector gateway software. On OpenVMS Alpha systems, the SPD is on the media CD. <> 8.3 Installation Procedure Requirements The installation procedure, VMSINSTAL, checks for various conditions on your system. If VMSINSTAL detects any problems during the installation, it notifies you of the problem and asks whether you want to continue the installation. In some instances, you can answer YES to continue. To stop the installation process and correct the situation, answer NO or press . You can avoid having to stop and restart VMSINSTAL by following the directions in this section before you run VMSINSTAL. The time required for installing TP Desktop Connector gateway software is approximately five minutes. 8.3.1 Disk Space Installing TP Desktop Connector gateway software requires a certain amount of free storage space during the installation. Table 8-1 summarizes the storage requirements for TP Desktop Connector gateway during and after installation. 8-2 Preparing to Install TP Desktop Connector Gateway for ACMS Software Table_8-1_Disk_Space_Requirements_________________________ Blocks During Blocks After ______________________________Installation__Installation__ TP_Desktop_Connector_gateway__23_304_________6_500________ To determine the number of free disk blocks on the current system disk, enter the following command at the DCL prompt: $ SHOW DEVICE SYS$SYSDEVICE In the output column under the heading Free Blocks is the number of 512-byte blocks available on the device. 8.3.2 Privileges and Authorization To install TP Desktop Connector gateway software, you must be logged in to an account with the following privileges: NETMBX SETPRV TMPMBX The SYSTEM account has all the privileges you require for the installation. VMSINSTAL turns off the BYPASS privilege at the start of the installation and sets whatever privileges it needs during the installation. At the end of the installation procedure, if the TP Desktop Connector gateway system components were installed, the TP Desktop Connector gateway process on OpenVMS is started using the same user name that you use to install the product. Compaq recommends that you run the gateway under the user name SYSTEM or another user name with a [1,4] UIC. For the TP Desktop Connector for ACMS process to be properly started, the user name under which the installation is done must be an authorized ACMS agent. Preparing to Install TP Desktop Connector Gateway for ACMS Software 8-3 Use the ACMSUDU Utility to authorize the user name. For example: $ SET DEFAULT SYS$SYSTEM $ RUN ACMSUDU UDU> ADD SYSTEM/AGENT UDU> If the user name is not authorized as a ACMS agent, the IVP can fail and TP Desktop Connector client programs cannot sign in to the ACMS system. To allow client programs to successfully sign in to the ACMS system, stop the TP Desktop Connector gateway and restart it under a user name that is an authorized ACMS agent. 8.3.3 OpenVMS License Management Facility TP Desktop Connector gateway supports the OpenVMS License Management Facility (LMF). To install TP Desktop Connector gateway on an OpenVMS system, you must register your software license. LMF requires registration of a Product Authorization Key (PAK). The license registration information you need is contained in the PAK that is shipped with TP Desktop Connector gateway software. The PAK is a paper certificate that contains information about the license you have to run a particular piece of software. Register your TP Desktop Connector gateway license before you perform the installation. During the installation, you are asked whether you have registered the TP Desktop Connector gateway license and loaded the appropriate authorization key. You cannot run either the TP Desktop Connector gateway software or its IVP unless your license is loaded. After you perform the license registration and load an authorization key, you can run the IVP and use TP Desktop Connector gateway software. To register a license, first log in to the system manager account, SYSTEM. You then have a choice of two ways to register: o Run the SYS$UPDATE:VMSLICENSE.COM procedure. When it prompts you for information, respond with data from your PAK. 8-4 Preparing to Install TP Desktop Connector Gateway for ACMS Software o Issue the LICENSE REGISTER command with the appropriate qualifiers that correspond to information on the PAK. For complete information on using LMF, see VMS License Management Utility Manual. 8.3.4 System Disk Backup At the beginning of the installation, VMSINSTAL asks whether your system disk is backed up. Compaq recommends that you always do a system disk backup before installing new software on the operating system. Use the backup procedures that are established at your site to do this backup. For details on performing a system disk backup, see the section on the Backup Utility in the OpenVMS documentation set. 8.3.5 Stopping ACMS and TP Desktop Connector Gateway If you have TPware components already installed and running, shut them down. While logged in to the system under an account having the appropriate privileges as described in Section 8.3.2, execute the following commands. 1. Stop the TP Web Connector Gateway for ACMS process. For example: $ @SYS$STARTUP:ACMSDI$SHUTDOWN $ 2. If you have ACMS software already installed and running, shut it down. Execute the following commands. a. Stop the ACMS system. For example: $ ACMS/STOP SYSTEM . . . $ b. Stop the ACMS controller. For example: Preparing to Install TP Desktop Connector Gateway for ACMS Software 8-5 $ @SYS$STARTUP:ACMSTOP . . . $ 8.3.6 Locating the Saveset Directory If you have not already inserted the compact disk (CD) media in the CD drive, do so now. To obtain the directory location of the saveset for the TP Desktop Connector gateway software on the CD-ROM, refer to the OpenVMS Layered Products Compact Disc User's Guide, or, before starting the installation, complete these steps: 1. To determine whether the CD-ROM drive is already mounted (MOUNT command), enter a command in the following format: SHOW DEVICE device-name 2. If the device is not mounted, enter a command in the following format: MOUNT/OVERRIDE=ID device-name For example: $ MOUNT/OVERRIDE=ID DKA200: 3. Locate the distribution files. The directory-name depends on the OpenVMS platform, as follows: _______________________________________________________ OpenVMS_Platform______Directory_Name___________________ Alpha VMSALPHA VAX___________________VMSVAX___________________________ 4. To obtain the saveset name, use a DIRECTORY command in the following format and specify the saveset name from the previous command. DIRECTORY device-name:ACMSDI031 8-6 Preparing to Install TP Desktop Connector Gateway for ACMS Software 9 ________________________________________________________________ Installing TP Desktop Connector Gateway for ACMS Software This chapter describes how to install TP Desktop Connector Gateway for ACMS software. Section 9.1 provides helpful information about installing the software. Section 9.2 contains a step-by-step description of the installation procedure. 9.1 General Installation Information This section includes information about accessing Release Notes, determining the files and logical names added to your system, running the Installation Verification Procedure (IVP), and aborting the installation. 9.1.1 Accessing the Online Release Notes TP Desktop Connector gateway software provides online Release Notes. To activate the prompt about displaying or printing the Release Notes, invoke VMSINSTAL with the OPTIONS N parameter. After TP Desktop Connector gateway software has been installed, the Release Notes are located in a directory with public access. 9.1.2 Files and Logical Names Installed on Your System The following files contain a list of the files added to your system by the TP Desktop Connector gateway installation: Installing TP Desktop Connector Gateway for ACMS Software 9-1 SYS$COMMON:[SYSTEST.ACMSDI]ACMSDI$ADU_FILES.DAT SYS$COMMON:[SYSTEST.ACMSDI]ACMSDI$FIRST_FILES.DAT SYS$COMMON:[SYSTEST.ACMSDI]ACMSDI$SAMPLE_ADD_FILES.DAT SYS$COMMON:[SYSTEST.ACMSDI]ACMSDI$SAMPLE_AVERTZ_FILES.DAT SYS$COMMON:[SYSTEST.ACMSDI]ACMSDI$SAMPLE_COMMON_FILES.DAT SYS$COMMON:[SYSTEST.ACMSDI]ACMSDI$SAMPLE_EMPLOYEE_FILES.DAT SYS$COMMON:[SYSTEST.ACMSDI]ACMSDI$SAMPLE_MACINTOSH_FILES.DAT SYS$COMMON:[SYSTEST.ACMSDI]ACMSDI$SYSTEM_FILES.DAT You can display or print these files after you install TP Desktop Connector gateway software. After the installation, if the gateway is started (by ACMSDI$STARTUP.COM), the following logical names are added to your system: ACMSDI$EXAMPLES ACMSDI$EXAMPLES_ACMS ACMSDI$EXAMPLES_ADD ACMSDI$EXAMPLES_AVERTZ ACMSDI$EXAMPLES_EMPLOYEE ACMSDI_AVERTZ_DEFAULT AVERTZ_TDB These logical names are entered into the system logical name table. The names are used in various TP Desktop Connector gateway startup files. Thus, they are automati- cally entered into the system logical name table whenever the TP Desktop Connector gateway startup command file is executed. 9.1.3 Installation Verification Procedure The Installation Verification Procedure (IVP) for TP Desktop Connector gateway software verifies the installa- tion. During the installation, you are asked whether you want to run the IVP as part of the installation. If you answer YES, VMSINSTAL runs the IVP. It is recommended that you run the IVP to be sure that the software is installed correctly. After you install the TP Desktop Connector gateway software, you can run the IVP independently to verify that the software is available on your system. You might also want to run the IVP after a system failure to be sure that users can access TP Desktop Connector gateway 9-2 Installing TP Desktop Connector Gateway for ACMS Software software. See Chapter 11 for information about running the IVP separately from the installation procedure. 9.1.4 Aborting the Installation To abort the installation procedure at any time, press . When you press , the installation procedure deletes all files it has created up to that point and exits. You can then start the installation again. 9.2 Installation Procedure Perform the steps in the following sections to install the TP Desktop Connector gateway software. 9.2.1 Invoking VMSINSTAL Perform the following steps to start the installation process. 1. Log to a privileged account (see Section 8.3.2 for details) and set the default to the desired directory. For example: $ SET DEFAULT SYS$UPDATE $ SYS$UPDATE is used in this example. 2. Use the following syntax to invoke VMSINSTAL: @SYS$UPDATE:VMSINSTAL saveset-name device-name OPTIONS N The parameter saveset-name represents the installation name for the component. For the TP Desktop Connector gateway software, use the following installation name: ACMSDI If you do not supply the saveset name, VMSINSTAL prompts you for it later in the installation procedure. The parameter device-name represents the location of the saveset files (see Section 8.3.6). If you do not supply device-name, VMSINSTAL prompts you for this information later in the installation procedure. Installing TP Desktop Connector Gateway for ACMS Software 9-3 OPTIONS N is an optional parameter indicating that you want to be prompted to display or print the release notes. If you do not include the OPTIONS N parameter, VMSINSTAL does not prompt you to display or print the release notes. VMSINSTAL supports several other options. For information, refer to the OpenVMS documentation on software installation. 3. Execute the installation procedure. For example: $ @SYS$UPDATE:VMSINSTAL ACMSDI DKA200: OPTIONS N This command begins installing the ACMSDI saveset found on the CD device named DKA200. VMSINSTAL asks several installation questions as described in Section 9.2.2. 9.2.2 Installation Questions This section discusses the questions that appear during the installation. Each question in the installation is marked with an asterisk (*) at the beginning of the line. Some questions show the default response in brackets, for example, [YES]. To give the default response, press . 1. Confirming active processes VMSINSTAL displays a list of all active processes. It then asks whether you want to continue the installation. Install the TP Desktop Connector gateway software on a standalone system or cluster with DECnet shut down to minimize possible installation problems. %VMSINSTAL-W-ACTIVE, The following processes are still active: . . . * Do you want to continue anyway [NO]? YES 2. Confirm system backup 9-4 Installing TP Desktop Connector Gateway for ACMS Software VMSINSTAL asks whether you are satisfied with your system backup. Always back up your system disk before performing an installation. If you are satisfied with the backup of your system disk, press . Answer NO to discontinue the installation. After you back up your system disk, restart the installation. * Are you satisfied with the backup of your system disk [YES]? 3. Mounting the media VMSINSTAL now displays the CD device name and asks whether you are ready to continue with the installation. Answer YES to indicate that the CD is mounted. VMSINSTAL displays a message that the media containing TP Desktop Connector gateway software is mounted on the specified device and that the installation is beginning. For example: Please mount the first volume of the set on DKA200:. * Are you ready? YES %MOUNT-I-MOUNTED, ACMSDI mounted on DKA200: The following products will be processed: ACMSDI V3.1 Beginning installation of ACMSDI V3.1 at 13:14 %VMSINSTAL-I-RESTORE, Restoring product save set A... If you enter the wrong device name when you invoke VMSINSTAL and need to restart the installation, answer NO in response to the Are you ready? question. See Section 8.3.6 for instructions on mounting the CD. To abort the installation for other reasons, press . 4. Release Notes If you specified OPTIONS N when you invoked VMSINSTAL, you see several options for reviewing the Release Notes. The following options are displayed: Installing TP Desktop Connector Gateway for ACMS Software 9-5 Release Notes included with this kit are always copied to SYS$HELP. Additional Release Notes Options: 1. Display release notes 2. Print release notes 3. Both 1 and 2 4. None of the above * Select option [2]: 1 o Option 1 If you select option 1, VMSINSTAL displays the Release Notes immediately on the console terminal. You can terminate the display at any time by pressing . Because the Release Notes are several pages long, it is recommended that you choose option 2 to print the Release Notes rather than reviewing them on line. o Option 2 If you select option 2, VMSINSTAL prompts for the name of the print queue to use: * Queue name [SYS$PRINT]: Enter the name of an ANSI print queue on your system, or press to send the file to the default queue shown within the square brackets. o Option 3 If you select option 3, VMSINSTAL displays the Release Notes and prompts for a queue name for the printed version. o Option 4 If you select option 4, VMSINSTAL continues the installation. 9-6 Installing TP Desktop Connector Gateway for ACMS Software 5. Installing the ACMSADU extension The installation procedure asks whether you want to install the ACMSADU extension on the system on which the TP Desktop Connector Gateway for ACMS software is installed. To install the ACMSADU extension, press . Otherwise, answer NO. For example: * Do you want to install the ACMS ADU Extension software [YES]? YES If you answer YES, modified ACMS utility images are added to the system. 6. Continuing the installation The installation procedure asks whether you want to continue the installation. To continue, answer YES. Otherwise, press . In either case, the Release Notes are copied to a file in the SYS$HELP directory. For example: * Do you want to continue the installation [N]?: YES %VMSINSTAL-I-RELMOVED, Product's Release Notes have been moved to SYS$HELP. © Digital Equipment Corporation. 1998. All Rights Reserved. The name of the Release Notes file installed by VMSINSTAL consists of the current product name and version number. If you plan to compare previous versions of TP Desktop Connector gateway software, do not delete the Release Notes for previous versions of TP Desktop Connector gateway. 7. Choosing to purge files You can purge files from previous versions of TP Desktop Connector gateway that are superseded by this installation. Purging is recommended, however, if you need to keep files from a previous version, answer NO in response to this question: * Do you want to purge files replaced by this installation [YES]? Installing TP Desktop Connector Gateway for ACMS Software 9-7 8. Choosing to run the IVP If you are installing the TP Desktop Connector gateway system components, the installation procedure asks whether you want to run the IVP. The IVP checks that the software is installed correctly. It is recommended that you run the IVP. * Do you want to run the IVP after the installation [YES]? YES Press to run the IVP after installing TP Desktop Connector gateway software. Answer NO to omit the IVP. Run the IVP independently after the installation to check the consistency of the TP Desktop Connector gateway software. See Chapter 11 for information about how to run the TP Desktop Connector gateway IVP independently of the installation procedure. 9. Installing Macintosh sample code You have the option of installing the TP Desktop Connector gateway samples for the Macintosh platform. * Do you want to install the Macintosh sample [YES]? NO Press to load the server-side Macintosh sample application code in the [.MACINTOSH] subdirectory of the ACMSDI$EXAMPLES directory. Answer NO to omit the Macintosh sample code. Note that only the Macintosh samples are optional; the Add, Avertz, and Employee server-side sample files are installed automatically. 10.Confirming license registration VMSINSTAL asks whether you have a PAK installed. You can install TP Desktop Connector gateway software prior to registration; however, the software is unusable until you register the license. Looking up the Product Authorization Information. Product: TP-DESKTOP-ACMS Producer: DEC Version: 3.1 Release Date: 04-JAN-1999 * Does this product have an authorization key registered and loaded? YES 9-8 Installing TP Desktop Connector Gateway for ACMS Software If you answer NO, the installation completes but the IVP is not run. If you answer YES and the license is not registered, the IVP fails. 9.2.3 Informational Messages At this point, the installation procedure displays a number of informational messages that report on the progress of the installation and advise about different uses of the product. There are no further questions. %ACMSDI-I-PROCEED, There are no further questions and all checks have been completed. -ACMSDI-I-PROCEED, It will take approximately 15 minutes to complete the installation. %VMSINSTAL-I-ACCOUNT, This installation updates an identifier named ACMSDI$CLIENT. %UAF-I-RDBMDFYMSG, identifier ACMSDI$CLIENT modified . . . Read the instructions, because they might apply to your installation. If the installation procedure has been successful up to this point, VMSINSTAL moves the new or modified files to their target directories and updates help files. If you asked for files to be purged, that work is done. The following message is displayed: . . . %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... . . . If you are installing TP Desktop Connector gateway on a system disk that has limited free space, VMSINSTAL might not be operating in safety mode. In this case, VMSINSTAL processes all files immediately and does not display the %VMSINSTAL-I-MOVEFILES... message. If the disk has quotas enabled, a message is displayed. The account must have sufficient disk quotas to install. Refer to Table 8-1. Installing TP Desktop Connector Gateway for ACMS Software 9-9 9.2.4 Running the Installation Verification Procedure If you chose to run the IVP, VMSINSTAL runs it next. When the IVP runs successfully, you see the following messages displayed: %RUN-S-PROC_ID, identification of created process is 210031D5 Starting Server ACMSDI$SERVER The TP Desktop Connector V3.1-00 Gateway for ACMS IVP completed successfully Installation of ACMSDI V3.1 completed at 13:32 . . . The TP Desktop Connector V3.1-00 Gateway for ACMS IVP completed successfully 9.2.5 Completing the Installation Procedure The following messages indicate that the installation procedure is complete: Installation of ACMSDI V3.1 completed at 13:32 VMSINSTAL procedure done at 13:33 $ You can now log out of the privileged account: $ LOGOUT SYSTEM logged out at 04-JAN-1999 13:34:12.28 VMSINSTAL deletes or changes entries in the process symbol tables during the installation. Therefore, to continue using the system account and restore these symbols, log out and log in again. Proceed to Chapter 10 to follow postinstallation procedures. 9.3 Recovering from System and Installation Failures An unsuccessful installation can result from a system failure (see Section 9.3.1) or errors encountered during the installation procedure (see Section 9.3.2). 9-10 Installing TP Desktop Connector Gateway for ACMS Software 9.3.1 System Failures If you experience a system failure, such as a power loss during installation, VMSINSTAL attempts to continue the installation when you reboot the system. Depending on the point in the installation at which the system fails, one of three conditions exists: o The system disk did not undergo any changes before the system failure. VMSINSTAL instructs you to restart the installation. o The system disk used by the installation was corrupted. VMSINSTAL instructs you to restore the system disk from the backup copy and restart the installation. o VMSINSTAL continues the installation and can tell you to manually purge replaced files, even if you request that they be purged automatically. You can purge files, but remember that purging deletes all but the latest version of all files on your system disk. If you have multiple versions of system files to save, you can delete just the TP Desktop Connector gateway files you want to remove from system directories. To purge files, perform the following steps: 1. Reboot the system. 2. Log in to the SYSTEM account. 3. Purge all system files using the following command: $ PURGE/LOG SYS$SYSROOT:[*...]*.* . . . After you perform this task, the installation is complete. After you see the message that indicates the beginning of the IVP, the installation of the component software is complete. If the system fails subsequently, VMSINSTAL displays the following message when you reboot. Installing TP Desktop Connector Gateway for ACMS Software 9-11 %VMSINSTAL-I-RECOVER, TP Desktop Gateway for ACMS was being installed when the system crashed. The installation completed satisfactorily. This message indicates that VMSINSTAL finished success- fully, not that the installation of TP Desktop Connector gateway was successful. VMSINSTAL does not automatically restart the IVP. Run the IVP independently by following the steps described in Chapter 11. 9.3.2 Installation Failures If the installation of the TP Desktop Connector gateway software or a TP Desktop Connector sample application fails for some reason other than a system failure, the installation procedure displays a message describing the cause of the failure. To continue with the installation, correct the condition causing the error and restart the installation procedure from the beginning. Errors can occur during the installation if any of the following conditions exist: o The operating system version is incorrect. o A prerequisite software version is incorrect. o Quotas necessary for successful installation are insufficient. o System parameter values for successful installation are insufficient. o The OpenVMS help library is currently in use. For descriptions of the error messages generated by these conditions, see the OpenVMS documentation on system messages, recovery procedures, and OpenVMS software installations. If you are notified that any of these conditions exist, take the appropriate action as described in the message. (You might need to change a system parameter or increase a quota value.) For information on installation requirements, see Chapter 8. 9-12 Installing TP Desktop Connector Gateway for ACMS Software If the installation of the component software completes satisfactorily, but a test fails during the IVP, the IVP displays a message describing the failure and suggests a course of action. In most cases, the suggested course of action is to reinstall the TP Desktop Connector gateway software. If the IVP fails after you reinstall the TP Desktop Connector gateway software, contact your Compaq software specialist. 9.3.3 IVP Error Recovery As the IVP executes, it checks the success of each test and operation it performs. If any test or operation fails, the IVP displays a message describing the failure and suggests a course of action. Follow the suggested course of action and then restart the IVP as described in Chapter 11. If you reinstall TP Desktop Connector gateway software, the IVP runs automatically if you answer YES to the IVP question. If you still cannot successfully run the IVP, contact your Compaq software specialist. Installing TP Desktop Connector Gateway for ACMS Software 9-13 10 ________________________________________________________________ After Installing TP Desktop Connector Gateway for ACMS Software After installing TP Desktop Connector gateway software from the Gateway CD, perform the following tasks: o Edit OpenVMS system startup and shutdown files. o Perform any cluster operations. o Read the management chapters in the appropriate document: - DIGITAL TP Desktop Connector for ACMS Client Application Programming Guide - DIGITAL TP Desktop Connector Getting Started See Chapter 11 for information about how to run the Installation Verification Procedure (IVP) after the software has been installed. 10.1 Editing the OpenVMS System Files You must edit the OpenVMS system startup and shutdown files to provide for automatic startup and shutdown of TP Desktop software when your system is rebooted. (This step is usually not necessary for system upgrades.) 10.1.1 Editing the System Startup File The following files are located in the SYS$STARTUP directory. ACMSDI$SHUTDOWN.COM ACMSDI$STARTUP.COM Add the command line that starts TP Desktop to the OpenVMS system startup file. If you separate the startup procedures into modules, be sure that you add the lines to the correct file. After Installing TP Desktop Connector Gateway for ACMS Software 10-1 Position the TP Desktop startup command line after the line that invokes the ACMS startup command procedure. For example: $ @SYS$STARTUP:ACMSTART.COM . . . $ @SYS$STARTUP:ACMSDI$STARTUP.COM ________________________Note_________________________ Start ACMS software before you start TP Desktop software. _____________________________________________________ Starting TP Desktop software automatically enables the use of the DECnet communication transport. To use NetWare or TCP/IP protocols as well, or instead of DECnet, list the transports you want to use in a parameter file. Specify the parameter file as a qualifier on the TP Desktop startup command line. The parameter file is a simple ASCII text file that lists customer overrides to TP Desktop run-time quotas and defaults. These overrides can include the specification of the communication libraries that have been installed on the OpenVMS system. For example, to enable TP Desktop to use all transports, create the following file in the SYS$MANAGER directory: ACMS_DESKTOP_SERVER.DAT Include in the file the following line: transport=(tcpip,netware,decnet,appletalk) Modify the startup command line to specify the parameter file. For example: $ @SYS$STARTUP:ACMSDI$STARTUP.COM SYS$MANAGER:ACMS_DESKTOP_SERVER.DAT To perform this same function in batch from DCL-level, issue a SUBMIT command. For example: $ SUBMIT/USER=SYSTEM/NOLOG SYS$STARTUP:ACMSDI$STARTUP- _$ /PARAMETER=(SYS$MANAGER:ACMS_DESKTOP_SERVER.DAT) 10-2 After Installing TP Desktop Connector Gateway for ACMS Software This command starts a batch job that runs the startup command procedure using the input file specified in the parameter qualifier. When the batch job completes, the TP Desktop software is started. 10.1.2 Editing the System Shutdown File Find the following line, which stops the ACMS system, in the OpenVMS system shutdown file: $ @ACMSTOP.COM At some point before this line, add the following command line: $ @SYS$STARTUP:ACMSDI$SHUTDOWN.COM The command procedure cancels all active tasks and shuts down the TP Desktop process. This ensures that the TP Desktop system processes are run down properly. The command procedure also deinstalls TP Desktop images (using the Install Utility of OpenVMS) and deassigns the logical names. 10.2 Performing Cluster Procedures Because TP Desktop software treats a VAXcluster or VMScluster system as if it were a local area network (LAN), you must prepare system-specific roots on each node of the cluster. For example: $ CREATE/DIRECTORY SYS$SPECIFIC:[ACMSDI]/OWNER_UIC=SYSTEM- _$ /PROTECTION=(S:RWE,O:RWE,G:RE,W:RE) $ CREATE/DIRECTORY SYS$SPECIFIC:[SYSTEST.ACMSDI]- _$ /OWNER_UIC=SYSTEM/PROTECTION=(S:RWE,O:RWE,G:RE,W:RE) $ CREATE/DIRECTORY SYS$SPECIFIC:[SYSHLP.EXAMPLES.ACMSDI]- _$ /OWNER_UIC=SYSTEM/PROTECTION=(S:RWE,O:RWE,G:RE,W:RE) $ Executed on each node in the cluster, these commands create directory roots for the TP Desktop software. See Section 9.1.2 for the locations of files describing the directories added to your system. After Installing TP Desktop Connector Gateway for ACMS Software 10-3 10.3 Matching Client and Server Versions If you are upgrading from ACMS Desktop Version 2.n to TP Desktop Version 3.m, you can use your existing client programs with the new server. But, if you build a new client program under TP Desktop Version 3.m, you cannot use this new program with the old ACMS Desktop Version 2.n server. When the ACMS communication protocols do not match those of the desktop client, the TP Desktop Connector gateway rejects the attempted connection. The gateway writes a message to the software event log (SWL). The error code returned on the client side depends on the nature of the mismatch. The following error codes can indicate a mismatched condition: ACMSDI_SRVDEAD -3020 ACMSDI_INVPROTOCOL -3025 10-4 After Installing TP Desktop Connector Gateway for ACMS Software 11 ________________________________________________________________ Running the TP Desktop Connector Gateway for ACMS IVP This chapter describes how to run the TP Desktop Connector gateway installation verification procedure (IVP) separately from the installation procedure. The IVP can be run as a part of the normal installation when you answer YES to the IVP question. If the IVP fails for any reason, correct the error and rerun the IVP. See Chapter 9 for information on providing the IVP with information required for the installation procedure. Run separately from the installation procedure, the IVP can check the integrity of installed files on the system. 11.1 IVP Operations The IVP checks that: 1. The installation procedure successfully completed installing TP Desktop software. 2. The installed software can be used to set up and run TP Desktop software. 3. All the necessary files are on the system. The IVP does not check that the applications run correctly. 11.2 Running the IVP Independently This section describes the requirements and steps to run the IVP. Running the TP Desktop Connector Gateway for ACMS IVP 11-1 11.2.1 IVP Requirements If disk quotas are enabled, the IVP cannot run. The procedure checks to see whether disk quotas are enabled just after checking the process quotas. If disk quotas are enabled, the procedure provides an informational message to that effect and terminates. 11.2.2 IVP Steps To run the IVP independently of the installation procedure, follow these steps: 1. Log in to the SYSTEM account: Username: SYSTEM Password: 2. Set your default to the test directory: $ SET DEFAULT SYS$TEST $ 3. Run the IVP using the following file specification: ACMSDI$IVP.COM You can run the IVP only on your current booted system. You cannot run the IVP over a networked connection. To start the IVP, enter the following command: $ @ACMSDI$IVP The TP Desktop Connector V3.1-00 Gateway for ACMS IVP completed successfully . . . The TP Desktop Connector V3.1-00 Gateway for ACMS IVP completed successfully The IVP takes no more than 30 seconds to run, depending on the current system load. 11-2 Running the TP Desktop Connector Gateway for ACMS IVP 11.2.3 IVP Error Recovery As the IVP executes, it checks the success of each test and operation it performs. If any test or operation fails, the IVP does the following: 1. Stops processing. 2. Displays a message describing the failure. 3. Suggests a course of action to eliminate the cause of the failure. Follow the suggested course of action and then restart the IVP. Running the TP Desktop Connector Gateway for ACMS IVP 11-3 A ________________________________________________________________ Files Installed The following tables list the files that are installed on your systems for the various sample applications. Table A-1 Files Installed for TP Desktop Connector Client __________Services_for_OpenVMS_Systems____________________ Files_____________Description_____________________________ ACMSDI.H Include file for the TP Desktop Connector client services declarations ACMSDI$CLIENT_ Library for the TP Desktop Connector OBJLIB.OLB client services FORMS.H Include file for DECforms NET_APPLETALK.OBJ AppleTalk object file (for OpenVMS VAX systems only) NET_DECNET.OBJ DECnet object file NET_NETWARE.OBJ NetWare object file[1] NET_TCPIP.OBJ TCP/IP object file PPSTUBS.C Presentation procedure and action routine stubs TDMS.H____________Include_file_for_TDMS___________________ [1]For_testing_purposes_only,_not_officially_supported.___ Files Installed A-1 Table A-2 Files Installed for the Motif Sample for __________OpenVMS_Systems_________________________________ Name_____________Description______________________________ Makefile Makefile for building the sample acmsdi.h Include file for the TP Desktop Connector client services forms.h Sample include file with DECforms status values help.txt Overview of the AVERTZ user interface m_avertz.exe Motif sample executable file sys$login:m_ Motif sample resource file avertz.dat m_avertz.c Entry point for the sample; manages the main window of the sample m_avertz.h AVERTZ header file; defines global names m_avertz.opt Linker-purge options file for building the sample m_avertz.uid Runtime representation of the sample's UIL definition m_avertz.uil User interface template; defines the layout of the main window and the session dialog box m_avertzpp.c Reserve task presentation procedures; stubs for the checkin and the checkout tasks' presentation procedures m_avertzpp.h Header file for m_avertzpp.c m_disable.c Presentation procedure stub m_enable.c Presentation procedure stub m_icons.uil User interface template; defines the various session icons (continued on next page) A-2 Files Installed Table A-2 (Cont.) Files Installed for the Motif Sample __________________for_OpenVMS_Systems_____________________ Name_____________Description______________________________ m_list_pkg.c Provides linked list feature m_list_pkg.h Header file for list_pkg.c m_message.c Performs message box handling in the sample m_message.h Header file for m_message.c m_read_write.c Presentation procedure stub m_receive.c Presentation procedure stub m_request.c Presentation procedure stub m_resvform.c Management and convenience routines for handling the reservation form m_resvform.h Header file for m_resvform.c m_resvform.uil User interface template; defines the layout of the reservation form m_send.c Presentation procedure to dispatch to specific routines in m_avertzpp.c m_session.c Manages multiple sessions; switches context for using TP Desktop Connector Gateway for ACMS routines and updates the user interface m_session.h Header file for m_session.c m_sitelist.c Creates (using m_sites.dat) and manages the list box of AVERTZ sites m_sitelist.h Header file for m_sitelist.c m_sites.dat Contains data about AVERTZ sites; read in at run time (continued on next page) Files Installed A-3 Table A-2 (Cont.) Files Installed for the Motif Sample __________________for_OpenVMS_Systems_____________________ Name_____________Description______________________________ m_transceive.c Presentation procedure that dispatches to specific routines in avertzpp m_version.c Version-checking action routine stub m_wkspaces.c Support routines for AVERTZ workspace structures m_wkspaces.h Defines the AVERTZ workspace structures tdms.h Sample include file with TDMS status _________________values___________________________________ Table A-3 Files Installed for the PowerBuilder Win32 __________Sample__________________________________________ Name_____________Description______________________________ pbreadme.doc Contents of the folder in text format pbavertz.pbl PowerBuilder library containing PowerBuilder objects for the blocking sample that does not support exchange I/O pbavertz.exe Executable form of the PBAVERTZ sample pbavertz.doc Declarations and scripts used by PBAVERTZ in text format pbpointr.dll Dynamic link library required for memory management with PowerBuilder applications that use TP Desktop Connector Gateway for ACMS services. pbpointr.h Interface definition file for pb- pointr.dll acmsdipb.doc Microsoft Word document that explains how to use the pbpointr.dll services. cars.ico Icon used by PBAVERTZ (continued on next page) A-4 Files Installed Table A-3 (Cont.) Files Installed for the PowerBuilder __________________Win32_Sample____________________________ Name_____________Description______________________________ fnbsampl.pbl A PowerBuilder library containing a sample application that executes an ACMS task with exchange I/O using the forced nonblocking extension to the TP Desktop Connector client services. fnbsampl.exe Executable form of the forced nonblocking sample fnbsampl.doc Microsoft Word document that describes _________________forced_nonblocking_______________________ Table A-4 Files Installed for the Visual Basic Win32 __________Sample__________________________________________ Name_____________Description______________________________ mainmenu.frm GUI objects and code for the main window of Visual Basic AVERTZ reserve.frm GUI objects and code for the car rental reservations screen of Visual Basic AVERTZ signin.frm GUI objects and code for the session- login screen of Visual Basic AVERTZ readme.1st Contents of the folder in text format readme.txt Text document that explains how to use the helper DLL, divb.dll vbavertz.bas Global source code for Visual Basic AVERTZ vbavertz.exe Executable version of Visual Basic AVERTZ vbavertz.mak_____Project_makefile_for_Visual_Basic_AVERTZ_ Files Installed A-5 Table_A-5_Files_Installed_for_the_DOS_Sample______________ Name_____________Description______________________________ ACMSDI.H Include file for ACMS desktop interface programs BLD-CLI.BAT Batch file to compile and link the sample client program BLD-PPS.BAT Batch file to compile and link presenta- tion procedures used by the sample client program CHK-DATE.CBL COBOL program to validate dates CLASSES.CBL Sample workspace CLIENT.C Sample client C main program CLIENT.EXE Sample client program CONTROL.CBL Sample workspace CUSTOMER.CBL Sample workspace CUSTSHDW.CBL Sample workspace CU_TRANS.CBL Sample workspace DISABLE.C Sample presentation procedure ENABLE.C Sample presentation procedure FORMS.H Sample include file with DECforms status values GETSITE.CBL Sample presentation procedure LOGIN.CBL Sample client initialization procedure LOGOFF.CBL Sample client termination procedure MENU.CBL Sample client menu procedure RECV.C Sample presentation procedure (continued on next page) A-6 Files Installed Table_A-5_(Cont.)_Files_Installed_for_the_DOS_Sample______ Name_____________Description______________________________ REQUEST.C Sample presentation procedure RESERVTN.CBL Sample workspace SELCUST.CBL Sample presentation procedure SELSITE.CBL Sample presentation procedure SEND.C Sample presentation procedure SENDCTRL.CBL Sample workspace SHWCUST.CBL Sample presentation procedure SHWRESV.CBL Sample presentation procedure SITES.CBL Sample workspace SI_TRANS.CBL Sample workspace TDMS.H Sample include file with TDMS status values TRANS.C Sample presentation procedure TRANS.CBL Sample workspace TRANSHDW.CBL Sample workspace VERSION.C________Sample_version-checking_procedure________ Table_A-6_Files_Installed_for_the_Windows_3.11_Sample_____ Name_____________Description______________________________ ACMSDI.H Include file for the ACMS desktop interface AVERTZ Makefile for building the sample AVERTZ.C Entry point for the sample; manages the main window (continued on next page) Files Installed A-7 Table A-6 (Cont.) Files Installed for the Windows 3.11 __________________Sample__________________________________ Name_____________Description______________________________ AVERTZ.DEF Defines entry points and stack size for Microsoft Windows AVERTZ.EXE Microsoft Windows sample executable file AVERTZ.H AVERTZ header file; defines globals AVERTZ.RC User interface template; defines the main window, menus, and reservation form layout AVERTZMM.C Handles memory management for AVERTZ structures AVERTZMM.H Header file for AVERTZMM.C AVERTZPP.C Reserve task presentation procedures; stubs for checkin and checkout tasks and presentation procedures AVERTZPP.H Header file for AVERTZPP.C DISABLEW.C Presentation procedure stub DRIVING.ICO Icon for (an unselected) session that is currently processing a task ENABLEW.C Presentation procedure to define the session ID FORMS.H Sample include file with DECforms status values HELP.TXT Overview of the AVERTZ user interface LIST_PKG.C Provides linked list feature; preal- locates memory using arrays to reduce fragmentation of the local heap LIST_PKG.H Header file for LIST_PKG.C RECVW.C Presentation procedure stub (continued on next page) A-8 Files Installed Table A-6 (Cont.) Files Installed for the Windows 3.11 __________________Sample__________________________________ Name_____________Description______________________________ REDCAR.ICO Icon for (an unselected) session that is not currently processing a task REQUESTW.C Presentation procedure stub RESVFORM.C Management and convenience routines for handling the reservation form RESVFORM.H Header file for RESVFORM.C SDRIVING.ICO Icon for a selected session that is currently processing a task SENDW.C Presentation procedure to dispatch to specific routines in AVERTZPP.C SESSION.C Manages multiple sessions; switches context for using TP Desktop Connector Gateway for ACMS routines and updates the user interface SESSION.H Header file for to obtain the files for building against the static link libraries SESSION.C SITELIST.C Creates (using SITES.DAT) and manages list box of AVERTZ sites SITELIST.H Header file for SITELIST.C SITES.DAT Contains data about AVERTZ sites; read in at run time SREDCAR.ICO Icon for a selected session that is not currently processing a task TDMS.H Sample include file with TDMS status values TRANSW.C Presentation procedure that dispatches to specific routines in AVERTZPP.C (continued on next page) Files Installed A-9 Table A-6 (Cont.) Files Installed for the Windows 3.11 __________________Sample__________________________________ Name_____________Description______________________________ VERSIONW.C Version-checking procedure stub WKSPACES.C String conversion support for AVERTZ workspace structures WKSPACES.H_______Defines_the_AVERTZ_workspace_structures__ Table A-7 Files Installed for the 16-Bit PowerBuilder __________Sample__________________________________________ Name_____________Description______________________________ ACMSDIPB.DOC Document discussing TP Desktop Connector Gateway for ACMS support for PowerBuilder PBAVERTZ.PBL PowerBuilder library containing the blocking sample which does not support exchange I/O PBAVERTZ.EXE Executable form of the PBAVERTZ sample PBAVERTZ.DOC Declarations and scripts used by PBAVERTZ in text format CARS.ICO Icon used by PBAVERTZ PBPOINTR.DLL Dynamic link library containing the required memory management program PBPOINTR.H_______Interface_definition_file_for_PBPOINTR.DLL A-10 Files Installed Table A-8 Files Installed for the Visual Basic Avertz __________Sample__________________________________________ Name_____________Description______________________________ ACMSDI.BAS Include file of the ACMSDI declaration for Visual Basic applications HELP.TXT Online help file for the Visual Basic sample MAINMENU.FRM GUI objects and code for main window of Visual Basic AVERTZ RESERVE.FRM GUI objects and code for reservation form of Visual Basic AVERTZ SIGNIN.FRM GUI objects and code for session-login screen of Visual Basic AVERTZ VBAVERTZ.BAS Global module file for Visual Basic AVERTZ VBAVERTZ.EXE Visual Basic sample executable file VBAVERTZ.MAK_____Visual_Basic_makefile_for_AVERTZ_sample__ Table A-9 Files Installed for the Forced NonBlocking __________Tutorial________________________________________ Name_____________Description______________________________ ACMSDI.BAS ACMSDI declarations for Visual Basic applications FORM1.FRM GUI objects and code for the Forced Nonblocking Tutorial main window FORMS.BAS DECforms message code definitions for Visual Basic FNBSAMPL.MAK Visual Basic make file for the Forced Nonblocking Tutorial FRMLOGIN.FRM GUI objects and code for the Forced Nonblocking Tutorial session login window (continued on next page) Files Installed A-11 Table A-9 (Cont.) Files Installed for the Forced __________________NonBlocking_Tutorial____________________ Name_____________Description______________________________ FRMRECVC.FRM GUI objects and code for the Forced Nonblocking Tutorial receive control text window MTEXT.BAS Declarations and code to initialize ACMSDI message text for Visual Basic applications NONBLK.BAS Global declarations for the Visual Basic _________________Forced_Nonblocking_Tutorial______________ Table A-10 Files Installed for the Client Services for ___________DIGITAL_UNIX_Systems___________________________ Name_____________Description______________________________ acmsdi.h Include file for the TP Desktop Connector client services forms.h Include file for DECforms libacmsdi.a Library for TP Desktop Connector client services net_tcpip.o TCP/IP file for TP Desktop Connector client services net_decnet.o DECnet file for TP Desktop Connector client services ppstubs.c Presentation procedure and action routine stubs tdms.h___________Include_file_for_TDMS____________________ A-12 Files Installed Table A-11 Files Installed for the Motif Sample for ___________DIGITAL_UNIX_Systems___________________________ Name_____________Description______________________________ makefile Makefile for building the sample acmsdi.h Include file for the TP Desktop Connector client services forms.h Sample include file with DECforms status values help.txt Overview of AVERTZ user interface load_motif.sh Command shell to download the Motif sample from the OpenVMS system m_avertz Motif sample executable file m_avertz.c Entry point for the sample; manages the main window of the sample m_avertz.dat Font definitions for the sample screens m_avertz.h AVERTZ header file; defines globals m_avertz.uid Runtime representation of the sample UIL definition m_avertz.uil User interface template; defines the layout of the main window and the session dialog box m_avertzpp.c Reserve task presentation procedures; stubs for the checkin and the checkout tasks' presentation procedures m_avertzpp.h Header file for m_avertzpp.c m_disable.c Presentation procedure stub m_enable.c Presentation procedure stub m_icons.uil User interface template; defines the various session icons (continued on next page) Files Installed A-13 Table A-11 (Cont.) Files Installed for the Motif Sample ___________________for_DIGITAL_UNIX_Systems_______________ Name_____________Description______________________________ m_list_pkg.c Provides linked list feature m_list_pkg.h Header file for list_pkg.c m_message.c Performs message box handling in the sample m_message.h Header file for m_message.c m_read_write.c Presentation procedure stub m_receive.c Presentation procedure stub m_request.c Presentation procedure stub m_resvform.c Management and convenience routines for handling the reservation form m_resvform.h Header file for m_resvform.c m_resvform.uil User interface template; defines the layout of the reservation form m_send.c Presentation procedure to dispatch to specific routines in m_avertzpp m_session.c Manages multiple sessions; switches context for using TP Desktop Connector Gateway for ACMS routines and updates the user interface m_session.h Header file for m_session.c m_sitelist.c Creates (using m_sites.dat) and manages the list box of AVERTZ sites m_sitelist.h Header file for m_sitelist.c m_sites.dat Contains data about AVERTZ sites; read in at run time (continued on next page) A-14 Files Installed Table A-11 (Cont.) Files Installed for the Motif Sample ___________________for_DIGITAL_UNIX_Systems_______________ Name_____________Description______________________________ m_transceive.c Presentation procedure that dispatches to specific routines in m_avertzpp.c m_version.c Version-checking action routine stub m_wkspaces.c Support routines for AVERTZ workspace structures m_wkspaces.h Defines the AVERTZ workspace structures tdms.h Sample include file with TDMS status _________________values___________________________________ Files Installed A-15 B ________________________________________________________________ Common Configuration Errors The following sections discuss some of the errors that can occur while running the TP Desktop Connector client services sample applications. B.1 Errors Related to the Desktop System Errors can arise when any of the following conditions exits: o The TP Desktop Connector client program node does not have the network software functioning correctly. o The TP Desktop Connector client program node does not have the network in the directory search path. o The TP Desktop Connector client program node has insufficient disk space. B.1.1 Errors on DOS or Windows 3.11 Desktops Problems might be caused by a faulty startup or configura- tion file. Example B-1 shows a sample startup.bat file. Example B-1 Sample startup.bat File path=c:\;c:\PWV51;c:\dos;c:\MSVC\bin;c:\windows;c:\windev;c:\acmsdi mouse set lib=c:\MSVC\lib;c:\windev\lib;c:\acmsdi;c:\decnet\src set include=c:\MSVC\include;c:\windev\include;o:\acmsdi;c:\decnet\src set helpfiles=c:\MSVC\help\*.hlp set init=c:\MSVC\init Common Configuration Errors B-1 Example B-2 shows a sample config.sys file. Example B-2 Sample config.sys File files= 30 buffers=10 device=C:\himem.sys shell=\command.com /P /e:1024 device=C:\WINDOWS\smartdrv.sys 2048 1024 lastdrive=z Use the samples as guidelines to finding and fixing the problem. B.1.2 Errors on OpenVMS Desktops If errors occur in running the Motif Avertz program, verify the following: o The m_avertz.uid file is in the directory from which you run the m_avertz application. o The m_avertz.dat file (your resources file) is located in your home directory. If you encounter font-support problems running the program, you can modify the fonts used by editing the m_avertz resources file (m_avertz.dat in the user's home directory). B.1.3 Errors on DIGITAL UNIX Desktops If errors occur in running the Motif Avertz program, verify the following: o The m_avertz.uid file is in the directory from which you run the m_avertz application. o The m_avertz file (your resources file) is located in your home directory. If you are installing this application once for use by many users, make sure that the users copy m_avertz to their home directories. If you encounter font-support problems running the program, modify the fonts used by editing the m_avertz resources file (m_avertz in the user's home directory). B-2 Common Configuration Errors B.2 Errors Related to the ACMS System If you have used the client services sample to communicate with the ACMS system, errors will occur if any of the following conditions exists: o The TP Desktop Connector Gateway for ACMS system directory ACMSDI$EXAMPLES, ACMSDI$EXAMPLES_AVERTZ, or ACMSDI$EXAMPLES_ADD is protected against read access. o The TP Desktop Connector Gateway for ACMS system does not have the sample files installed. o The TP Desktop Connector Gateway for ACMS system does not have the network software functioning correctly. o The TP Desktop Connector Gateway for ACMS system is unavailable. o The TP Desktop Connector Gateway for ACMS system name is invalid. o The TP Desktop Connector Gateway for ACMS system is not running the ACMS software. o The TP Desktop Connector Gateway for ACMS system has not invoked ACMSDI$STARTUP.COM and ACMS/START SYSTEM. o The TP Desktop Connector Gateway for ACMS software is not installed or is improperly installed. o The TP Desktop Connector Gateway for ACMS system IVP failed. Common Configuration Errors B-3 ________________________________________________________________ Index A__________________________ B__________________________ ACMS Back button, 5-2 starting, 10-2 Blocking stopping system, 8-5 Visual Basic Sample Files ACMSADU, 8-4 , A-11 installing extension, 9-7 ACMSDI$CLIENT modification, C 9-9 ___________________________ ACMSDI$SYSTEM_FILES.DAT, C++, 6-3 9-2 Cancel button, 5-2 ACMS_DESKTOP_SERVER.DAT, Cluster procedures, 10-3 10-2 COBOL, 6-3 Administrator privileges, Components xiii TP Desktop Connector, 4-1 API CONDIST see TP Desktop Connector see Software Products client services Library Appletalk enabling, 10-2 Configuration errors, B-1 Authorization, 8-3 D Authorizing TP Desktop ___________________________ Connector gateway user DEC C, 6-3 name, 8-4 DECforms, 3-9, 6-20 AVERTZ DECnet, 5-3 access control list, DECnet enabling, 10-2 3-10, 6-20 DECwindows Motif, 6-3 application notes, 3-9, Disk space, 4-4, 7-3, 8-2 6-19 determining free, 1-3, rebuilding, 3-10, 6-21 8-3 user name quota values, requirements 3-10, 6-20 desktops, 6-3 gateway, 1-3 Index-1 Disk space requirements, 4-4 H__________________________ Hardware E__________________________ for installation, 4-1 Editing system shutdown file, I__________________________ 10-3 Installation system startup file, 10-1 aborting, 9-3 Environment variables, 5-2 dialog box usage, 5-1 Error recovery, 9-13 procedure, 5-1 to 5-2 Errors, B-1 procedures for, 9-1 Examples questions, 9-4 logical name, 9-2 tasks following, 3-1, Macintosh question, 9-8 10-1 system-specific root, Installing 10-3 DIGITAL UNIX client Examples option, 7-2 services, 6-22 DIGITAL UNIX Motif sample F__________________________ , 6-23 Failure recovery, 9-10 DOS client services, 6-5 Files DOS link library options, client services 6-6 added to OpenVMS DOS memory options, 6-6 Desktop system, DOS sample, 6-5 A-1 DOS Sample Application, installed on system, 9-1 6-6 purge, 9-7 DOS transport options, sample 6-6 added to OpenVMS OpenVMS client services, desktop system, 6-14 A-1 OpenVMS gateway, 2-2 added to Windows OpenVMS Motif sample, system, 6-9 3-6, 6-16 sample applications, A-1 Visual Basic Samples, Forced Nonblocking 6-12 Visual Basic Sample Files Windows client services, , A-11 6-5 FTP, xix Windows link library options, 6-8 Windows sample, 6-5 Windows Sample Application, 6-9 Index-2 Installing (cont'd) Motif, 6-3 Windows transport options , 6-8 N__________________________ Installing PowerBuilder Netware enabling, 10-2 sample, 6-12 Network transports, 5-3 ISO format, 6-2 Next button, 5-2 IVP error recovery, 11-3 O__________________________ operations performed by, Operating system components 11-1 , 8-1 requirements to run, 11-2 OSF/Motif, 6-3 running independently, 11-1 P steps to run, 11-2 ___________________________ PAK, 8-4 K__________________________ Parameter file, 10-2 Kanji, 5-6, 6-8 specifying, 10-2 PATHWORKS, 5-3 L Portable API ___________________________ see TP Desktop Connector License client services checking, 8-4 PowerBuilder, 6-12 installation question, PowerBuilder sample client, 9-8 A-4 registration, 8-4 Preparing to install License, product, 4-4 Macintosh software, 7-3 LMF requirement, 8-4 Prerequisite Logical name hardware, 1-2 added to system, 9-2 software, 1-2 Logical names Prerequisite software defining, 3-2 sample application, 6-2 M Prerequisite software for ___________________________ Macintosh systems, 7-2 Macintosh installation Prerequisites options, 7-1 gateway kit, 8-1 Macintosh sample code Privileges, ix, 8-3 installation, 9-8 BYPASS use, 8-3 Microsoft COBOL, 6-3 Program group Microsoft Visual Basic, creating, 5-2 6-3 Protocol mismatch, 10-4 Microsoft Visual C++, 6-3 Purge files, 9-7 Index-3 R__________________________ T__________________________ Rdb with multi-version, TCP/IP, 5-3 6-19 TCP/IP enabling, 10-2 Rdb with multiversion, 3-9 Time for installation, 8-2 Release notes TP Desktop Connector accessing, 9-1 client services, 6-1 to Removing installed software 6-24 , 4-5 components, 4-1 Resources, 6-5 installation Run-Time Services option, Win32 systems, 5-1 7-1 Transport Running the Installer, 7-5 automatic enabling, 10-2 parameter file enabling, S__________________________ 10-2 Sample U DIGITAL UNIX, 6-23 ___________________________ OpenVMS, 3-6, 6-16 User name requirement, 8-3 Sample application setup on OpenVMS, 3-8, 6-18 V__________________________ Saveset name, 9-3 VAX C, 6-3 Self-extracting archives, Verifying 1-2, 6-2 DIGITAL UNIX sample, 6-24 Services interface, 5-4 DOS sample, 6-7 Shutdown, 10-3 OpenVMS Motif sample, Software Products Library 3-7, 6-17 installing, 2-1 to 2-4 Windows sample, 6-9 SQL$USER library file, Version 3-9, 6-19 matching client and STDL version, 5-2 server, 10-4 Storage requirements, 4-4 operating system, 8-1 Superuser privileges, ix Visual Basic, 6-3 System privileges, ix Visual Basic Avertz Sample System Services option, Verifying installation, 7-1 6-13 System startup file Visual Basic AVERTZ Sample editing, 3-2 Verifying installation, System-specific roots, 5-5 10-3 Visual C++, 6-3 VMSINSTAL invoking, 9-3 requirements, 8-2 to 8-6 syntax, 9-3 Index-4 VMSLICENSE.COM, 8-4 VR_DA_APPL sample application, 3-9, 6-19 VR_DA_BLD_MMS.COM parameters, 3-11, 6-22 W__________________________ Windows Sockets, 5-3 Index-5