DIGITAL_ACMS_Desktop_for_OpenVMS____________________ Installation Guide Order Number: AA-PG9DF-TE April 1997 This guide provides information about installing the DIGITAL ACMS Desktop software on systems running the DIGITAL OpenVMS operating system. It also explains how to load the various interfaces and sample client programs on their native desktop systems. Revision Update Information: This is a revised manual. Operating System: DIGITAL OpenVMS VAX DIGITAL OpenVMS Alpha Software Version: DIGITAL ACMS Desktop for OpenVMS Version 2.3 Digital Equipment Corporation Maynard, Massachusetts ________________________________________________________________ First Printing, May 1991 Second Printing, March 1992 Third Printing, April 1993 Fourth Printing, April 1994 Fifth Printing, November 1995 Sixth Printing, April 1997 Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description. Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from DIGITAL or an authorized sublicensor. © Digital Equipment Corporation 1991,1997. All Rights Reserved. Printed in U.S.A. The following are trademarks of Digital Equipment Corporation: ACMS, ACMS Desktop, Alpha, DEC, DECforms, DECnet, DECnet-DOS, DECtp, DECwindows, OpenVMS, PATHWORKS, PATHWORKS for DOS, PATHWORKS for Macintosh, VAX, VAXcluster, VAXset, VMS, VT, and the DIGITAL logo. The following are third-party trademarks: Apple, AppleTalk, HyperCard, HyperTalk, Macintosh, and MacTCP are registered trademarks of Apple Computer, Inc. InterConnections, Inc., Terminal Emulation Services, TES, Network Print Services, NPS, and DECnet/IPX Portal are trademarks of InterConnections, Inc. 4D, 4D External Kit, and 4th Dimension are registered trademarks or trademarks of ACI and ACIUS, Inc. Microsoft, Microsoft C, Microsoft COBOL, Microsoft Windows, Microsoft Windows 95 Microsoft Windows NT, MS, MS-DOS, and Visual Basic, are registered trademarks of Microsoft Corporation. Windows NT is a trademark of Microsoft Corporation. Motif and OSF/Motif are trademarks of Open Software Foundation, Inc. Novell and NetWare are registered trademarks of Novell, Inc. Open Desktop and SCO are trademarks of Santa Cruz Operations, Inc. Open Look is a registered trademark of UNIX System Laboratories, Inc., a wholly owned subsidiary of Novell, Inc. Oracle CDD and Oracle Rdb are trademarks of Oracle Corporation. PowerBuilder is a trademark of Powersoft Corporation. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company, Ltd. X Window System is a registered trademark of Massachusetts Institute of Technology. All other trademarks and registered trademarks are the property of their respective holders. This document is available on CDROM. This document was prepared using VAX DOCUMENT Version 2.1. _________________________________________________________________ Contents Preface................................................... ix Part I ACMS Desktop Software 1 Preparing to Install DIGITAL ACMS Desktop Software 1.1 Required Operating System Components.......... 1-1 1.2 Prerequisite Software......................... 1-2 1.3 Installation Procedure Requirements........... 1-2 1.3.1 OpenVMS License Management Facility....... 1-2 1.3.2 Time...................................... 1-3 1.3.3 Privileges and Authorization.............. 1-3 1.3.4 Disk Space................................ 1-4 1.3.5 VMSINSTAL Requirements.................... 1-5 1.3.6 System Disk Backup........................ 1-5 1.3.7 Print Queue for Release Notes............. 1-5 2 Installing ACMS Desktop Software 2.1 General Installation Information.............. 2-1 2.1.1 Accessing the Online Release Notes........ 2-1 2.1.2 Files and Logical Names Installed on Your System.................................... 2-1 2.1.3 Installation Verification Procedure....... 2-3 2.2 Aborting the Installation..................... 2-3 2.3 Installation Procedure........................ 2-3 2.3.1 Stopping DIGITAL ACMS and Digital ACMS Desktop................................... 2-3 2.3.2 Invoking VMSINSTAL........................ 2-5 2.3.3 Installation Questions.................... 2-7 2.3.4 Informational Messages.................... 2-15 iii 2.3.5 Running the Installation Verification Procedure................................. 2-16 2.3.6 Completing the Installation Procedure..... 2-16 2.4 Recovering from System and Installation Failures...................................... 2-17 2.4.1 System Failures........................... 2-17 2.4.2 DIGITAL ACMS Desktop Installation Failures.................................. 2-18 2.4.3 Error Recovery............................ 2-19 3 After Installing DIGITAL ACMS Desktop Software 3.1 Editing the OpenVMS System Files.............. 3-1 3.1.1 Editing the System Startup File........... 3-1 3.1.2 Editing the System Shutdown File.......... 3-3 3.2 Performing Cluster Procedures................. 3-3 3.3 Client and Sample Software Installation....... 3-3 3.3.1 Client Software on Desktop Systems........ 3-4 3.3.2 Matching Client and Server Versions....... 3-4 3.3.3 Sample Software........................... 3-4 3.4 Determining and Reporting Problems............ 3-5 4 Running the DIGITAL ACMS Desktop IVP 4.1 IVP Operations................................ 4-1 4.2 Running the IVP Independently................. 4-1 4.2.1 IVP Requirements.......................... 4-1 4.2.2 IVP Steps................................. 4-2 4.2.3 IVP Error Recovery........................ 4-2 Part II ACMS Desktop Client Services 5 Installing ACMS Desktop Portable API Services and Samples 5.1 Preparing to Install the API and Sample Software...................................... 5-2 5.1.1 Prerequisite Software..................... 5-2 5.1.2 API Installation Procedure Requirements... 5-6 5.1.2.1 Time.................................... 5-6 5.1.2.2 Resources............................... 5-6 5.1.2.3 Use of Self-Extracting Archives......... 5-7 5.2 Installing the DOS and Windows APIs........... 5-7 iv 5.2.1 Setting Up the DOS Client Services........ 5-8 5.2.2 Installing the DOS Sample Application..... 5-8 5.2.3 Verifying the DOS Sample Installation..... 5-9 5.2.3.1 NonWindows Sample Files Added to the System.................................. 5-10 5.2.4 Setting up the Windows Client Services.... 5-11 5.2.5 Code Conversion Libraries for Kanji....... 5-12 5.2.6 Installing the Windows Sample Application............................... 5-12 5.2.7 Verifying the Windows Sample Installation.............................. 5-13 5.2.7.1 Using AVERTZ Sample Application on a System with Rdb Version 6.0 with Multi-Version........................... 5-16 5.2.7.2 Building the Avertz ACMS Sample Application with DECforms V1.4.......... 5-16 5.2.7.3 AVERTZ User Name Quota Values........... 5-17 5.2.7.4 Access Control List for AVERTZ.......... 5-17 5.2.7.5 Setting Up the AVERTZ Sample Application............................. 5-17 5.2.7.6 Rebuilding the DIGITAL ACMS Desktop Sample.................................. 5-18 5.2.7.7 Windows Sample Files Added to the System.................................. 5-19 5.2.8 Installing the PowerBuilder Version 5.0 Sample Applications....................... 5-21 5.2.9 Installing the Visual Basic Sample Applications.............................. 5-22 5.2.9.1 Verifying the Visual Basic AVERTZ Sample Installation............................ 5-23 5.2.9.2 Visual Basic Sample Files Added to the System.................................. 5-23 5.2.9.3 Verifying the Visual Basic Forced Nonblocking Tutorial.................... 5-24 5.2.9.4 Visual Basic Sample Files Added to the System for FNBSAMPL..................... 5-25 5.3 Installing the Windows 95 API................. 5-25 5.3.1 Installing the Windows 95 Client Software.................................. 5-26 5.3.2 Installing a Sample for Windows 95........ 5-27 5.4 Installing the Windows NT API................. 5-27 5.4.1 Installing the Windows NT Client Software.................................. 5-27 v 5.4.2 Installing a Sample for Windows NT........ 5-29 5.5 Installing the OpenVMS API and Sample Client Software...................................... 5-29 5.5.1 Installing the OpenVMS API................ 5-29 5.5.1.1 API Files Added to the OpenVMS Desktop System.................................. 5-31 5.5.2 Installing the Motif Sample Client for OpenVMS................................... 5-31 5.5.2.1 Copying the Motif Sample Files on OpenVMS................................. 5-31 5.5.2.2 Verifying the Motif Sample Installation on OpenVMS.............................. 5-32 5.5.2.3 Sample Files Added to the OpenVMS Desktop System.......................... 5-33 5.6 Installing the DIGITAL UNIX API and Sample Client Software............................... 5-35 5.6.1 Installing the DIGITAL UNIX API........... 5-36 5.6.1.1 API Files Added to the DIGITAL UNIX Desktop System.......................... 5-38 5.6.2 Installing the Motif Sample Client on DIGITAL UNIX.............................. 5-38 5.6.2.1 Verifying the Motif Sample Installation on DIGITAL UNIX......................... 5-39 5.6.2.2 Sample Files Added to the DIGITAL UNIX Desktop System.......................... 5-40 5.7 Installing the SCO UNIX API and Sample Client Software...................................... 5-42 5.7.1 Installing the SCO UNIX API............... 5-42 5.7.1.1 API Files Added to the SCO UNIX Desktop System.................................. 5-46 5.7.2 Installing the Motif Sample Client on SCO UNIX...................................... 5-46 5.7.2.1 Verifying the Motif Sample Installation on SCO UNIX............................. 5-47 5.7.2.2 Sample Files Added to the SCO UNIX Desktop System.......................... 5-48 5.8 Installing the RISC ULTRIX API and Sample Client Software............................... 5-50 5.8.1 Installing the RISC ULTRIX API............ 5-50 5.8.1.1 API Files Added to the RISC ULTRIX Desktop System.......................... 5-54 vi 5.8.2 Installing the Motif Sample Client on RISC ULTRIX.................................... 5-54 5.8.2.1 Verifying the Motif Sample Installation on RISC ULTRIX.......................... 5-55 5.8.2.2 Sample Files Added to the RISC ULTRIX Desktop System.......................... 5-56 5.9 Installation Errors........................... 5-58 6 Installing the DIGITAL ACMS Desktop Macintosh System and Sample Software 6.1 Macintosh Installation Options................ 6-1 6.2 Preparing to Install the Macintosh Software... 6-2 6.2.1 Prerequisite Software for Macintosh Systems................................... 6-2 6.2.2 Installation Procedure Requirements....... 6-3 6.2.2.1 Time.................................... 6-3 6.2.2.2 Disk Space.............................. 6-4 6.2.2.3 Installation Procedure Resources........ 6-4 6.3 Installing the Macintosh Software............. 6-5 6.3.1 Copying the ACMS Desktop Installer to the Macintosh................................. 6-5 6.3.1.1 Copying the Installer Using a VAXshare Volume.................................. 6-5 6.3.1.2 Copying the Installer Without Using a VAXshare Volume......................... 6-8 6.3.2 Running the ACMS Desktop Macintosh Installer................................. 6-9 A Sample Installations A.1 OpenVMS VAX Sample Software Installation...... A-1 A.2 OpenVMS Alpha Sample Software Installation.... A-5 Index vii Examples 5-1 Sample Startup.bat File................... 5-15 5-2 Sample config.sys File.................... 5-15 Tables 1-1 Timetable for Installing DIGITAL ACMS Desktop Software.......................... 1-3 1-2 Disk Space Requirements................... 1-4 5-1 Network Access............................ 5-2 5-2 Software Requirements for API............. 5-3 5-3 Sample Application Product Dependencies... 5-5 5-4 API Installation Timetable................ 5-6 5-5 NonWindows Sample Files................... 5-10 5-6 VR_DA_BLD_MMS.COM Parameters.............. 5-19 5-7 Windows Sample Files...................... 5-19 5-8 Files Added for PowerBuilder Samples...... 5-22 5-9 Visual Basic Sample Files................. 5-23 5-10 Visual Basic Sample Files for FNBSAMPL Sample.................................... 5-25 5-11 OpenVMS Files............................. 5-31 5-12 Motif Sample Files for the OpenVMS System.................................... 5-33 5-13 DIGITAL UNIX Files........................ 5-38 5-14 Motif Sample Files for the DIGITAL UNIX System.................................... 5-40 5-15 SCO UNIX Files............................ 5-46 5-16 Motif Sample Files for the SCO UNIX System.................................... 5-48 5-17 RISC ULTRIX Files......................... 5-54 5-18 Motif Sample Files for the RISC ULTRIX System.................................... 5-56 6-1 Macintosh Disk Space Requirements......... 6-4 viii _________________________________________________________________ Preface This installation guide describes how to install the DIGITAL ACMS Desktop software kit. Intended Audience Read this manual if you are responsible for installing and maintaining software for an DIGITAL ACMS Desktop system. To perform the installation procedures described in this manual, you must have access to a privileged DIGITAL OpenVMS system manager's account and be familiar with the OpenVMS installation procedure, VMSINSTAL. Operating System Information For DIGITAL ACMS Desktop software, you must be running ACMS Version 4.1 or higher. For information on the compatibility of other software products with this version of DIGITAL ACMS Desktop software, refer to the Software Product Description (SPD). Use the SPD to verify which versions of your operating system are compatible with this version of DIGITAL ACMS Desktop software. Manual Structure This manual has the following chapters and appendixes: ix ___________________________________________________________ Part_I______ACMS_Desktop_Software__________________________ Chapter 1 Explains how to prepare yourself and your system for installing DIGITAL ACMS Desktop software. Chapter 2 Describes how to install the DIGITAL ACMS Desktop software and sample applications and run the Installation Verification Procedure (IVP). It also tells you how to recover from system and installation failures. Chapter 3 Describes postinstallation procedures that prepare your OpenVMS system for running DIGITAL ACMS Desktop software. Chapter 4 Describes how to run the DIGITAL ACMS Desktop ____________IVP_separately_from_the_installation_procedure. Part_II_____ACMS_Desktop_Client_Services___________________ Chapter 5 Describes the installation of the API client services and sample applications for DOS, Windows, Windows NT, OpenVMS, DIGITAL UNIX, and SCO UNIX desktop systems. Chapter 6 Describes the installation of DIGITAL ACMS Desktop client services and sample desktop client programs that run under Macintosh software. Related Documents This manual does not provide details about the OpenVMS installation procedure. This information can be found in the VMS Installation and Operations manual for the particular device you use. That guide 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. x Other manuals contain information about managing your DIGITAL ACMS system and DIGITAL ACMS Desktop software: o DIGITAL ACMS for OpenVMS Managing Applications Explains how to start and stop the DIGITAL 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. o DIGITAL ACMS Desktop for OpenVMS Client Application Programming Guide Contains information about designing, developing, and managing client software on desktop systems. xi o DIGITAL ACMS Desktop for OpenVMS Client Services Reference Manual Contains the syntax for the ACMS Desktop client services. o DIGITAL ACMS Desktop for OpenVMS Gateway Management for ACMS Contains information about the system management and administration of the ACMS Desktop gateway. It also includes information on the methodology of the use of network transports. o DIGITAL ACMS Desktop for OpenVMS Release Notes Contains information about new features and current restrictions for DIGITAL ACMS Desktop software. When the installation procedure starts, you can print the Release Notes. Read the Release Notes before installing the software. o DIGITAL ACMS Desktop 4D Externals User's Guide - online only Describes a set of 4D external functions that you can use to create an ACMS Desktop Macintosh client program, using 4th Dimension as a development platform. Look for this book in the acmsdi-examples folder on your Macintosh system. Conventions The following icons appear in the margin to distinguish information that is specific to either OpenVMS VAX or OpenVMS Alpha: ___________________________________________________________ Convention____Description__________________________________ ACMS Desktop Refers to DIGITAL ACMS Desktop for OpenVMS. User input In examples, user input is highlighted with DIGITAL burgundy type in hardcopy documentation and with bold type in online documentation. xii ___________________________________________________________ Convention____Description__________________________________ Press the Ctrl (control) key and hold it down while pressing the specified key (indicated here by X). italics Use of italics emphasizes a word or phrase. Titles of manuals are also italicized. WORD Uppercase text indicates the name of a routine, the name of a file, the name of a file protection code, or the abbreviation for a system privilege. This symbol indicates that you press the Return key. . A vertical ellipsis in an example indicates . that information not directly related to the . example has been omitted. nn nnn.nnn A space character separates groups of 3 nn digits in numerals of 5 or more digits. For example, 10 000 equals ten thousand. n.nn A period in numerals signals the decimal point indicator. For example, 1.75 equals one ______________and_three-fourths.___________________________ xiii Part I _________________________________________________________________ ACMS Desktop Software Part I describes how to install the DIGITAL ACMS Desktop software on your DIGITAL OpenVMS system. 1 _________________________________________________________________ Preparing to Install DIGITAL ACMS Desktop Software This chapter discusses the preparations and requirements necessary for installing DIGITAL ACMS Desktop 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 Digital representative. DIGITAL ACMS Desktop software includes online Release Notes and gives you the option of printing or displaying the Release Notes during the installation procedure. Digital 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 Required Operating System Components To install DIGITAL ACMS Desktop software, you must have one of the following operating systems installed: o DIGITAL OpenVMS VAX operating system - Version 5.5-2 - Version 6.1 - Version 6.2 - Version 7.1 o DIGITAL OpenVMS Alpha operating system - Version 6.1 - Version 6.2 - Version 7.1 Preparing to Install DIGITAL ACMS Desktop Software 1-1 1.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 DIGITAL ACMS Desktop software. On OpenVMS Alpha systems, the SPD is on the media CD.<> 1.3 Installation Procedure Requirements The following sections discuss various requirements for installing DIGITAL ACMS Desktop software. 1.3.1 OpenVMS License Management Facility ACMS Desktop supports the OpenVMS License Management Facility (LMF). To install DIGITAL ACMS Desktop on an OpenVMS VAX 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 DIGITAL ACMS Desktop software. The PAK is a paper certificate that contains information about the license you have to run a particular piece of software. Register your DIGITAL ACMS Desktop license before you perform the installation. During the installation, you are asked whether you have registered the DIGITAL ACMS Desktop license and loaded the appropriate authorization key. You cannot run either the DIGITAL ACMS Desktop 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 DIGITAL ACMS Desktop 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. o Issue the LICENSE REGISTER command with the appropriate qualifiers that correspond to information on the PAK. 1-2 Preparing to Install DIGITAL ACMS Desktop Software For complete information on using LMF, see OpenVMS License Management Facility Manual. 1.3.2 Time Table 1-1 lists the approximate time required for installing DIGITAL ACMS Desktop software. Table 1-1 Timetable for Installing DIGITAL ACMS Desktop __________Software_________________________________________ Software_____________________________Time_Required-Minutes_ ACMSDI product on OpenVMS system 10 ACMSDI product and sample on 20 OpenVMS_system_____________________________________________ See Table 5-4 for the time it takes to install the ACMSDI client software on the desktop system. 1.3.3 Privileges and Authorization To install DIGITAL ACMS Desktop software, you must be logged in to an account with the following privileges: SETPRV, TMPMBX, NETMBX 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 DIGITAL ACMS Desktop system components were installed, the DIGITAL ACMS Desktop server process on OpenVMS is started using the same user name that you use to install the product. Digital recommends that you run the server under the user name SYSTEM or another user name with a [1,4] UIC. For the DIGITAL ACMS Desktop server to be properly started, the user name under which the installation is done must be an authorized DIGITAL ACMS agent. Use the ACMSUDU Utility to authorize the user name. For example: Preparing to Install DIGITAL ACMS Desktop Software 1-3 $ SET DEFAULT SYS$SYSTEM $ RUN ACMSUDU UDU> ADD SYSTEM/AGENT UDU> If the user name is not authorized as a DIGITAL ACMS agent, the IVP can fail and desktop client programs cannot sign in to the DIGITAL ACMS system. To allow desktop client programs to successfully sign in to the DIGITAL ACMS system, stop the DIGITAL ACMS Desktop server and restart it under a user name that is an authorized DIGITAL ACMS agent. 1.3.4 Disk Space Installing DIGITAL ACMS Desktop software requires a certain amount of free storage space during the installation. Table 1-2 summarizes the storage requirements for DIGITAL ACMS Desktop during and after installation. Table_1-2_Disk_Space_Requirements__________________________ Blocks During Blocks After Components____________________Installation__Installation___ DIGITAL ACMS Desktop server 18 000 3 500 and client services Sample common [1] 650 150 AVERTZ sample application 5500 4 700 DOS sample 700 650 Windows sample 500 1 300 Macintosh sample 100 40 Motif sample 6 000 5 250 [1]If_you_install_any_part_of_the_sample,_this_software_is_ present. ___________________________________________________________ If you are installing the sample application, add the number of blocks required for the sample application to the number of blocks required for server and client services. 1-4 Preparing to Install DIGITAL ACMS Desktop Software 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 1.3.5 VMSINSTAL Requirements When you invoke VMSINSTAL, it checks for the following conditions: o You are logged in to a privileged account. o You have adequate quotas for installation. o DECnet/VMS software is up and running. o No users are logged in to the 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 . 1.3.6 System Disk Backup At the beginning of the installation, VMSINSTAL asks whether your system disk is backed up. Digital 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. 1.3.7 Print Queue for Release Notes If you select an option to print the Release Notes during the installation, VMSINSTAL asks for a print queue name. The default name is SYS$PRINT. Enter the name of an ANSI queue on your system to change the default queue. Preparing to Install DIGITAL ACMS Desktop Software 1-5 2 _________________________________________________________________ Installing ACMS Desktop Software This chapter describes how to install ACMS Desktop software. Section 2.3 contains a step-by-step description of the installation procedure. 2.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. 2.1.1 Accessing the Online Release Notes DIGITAL ACMS Desktop software provides online Release Notes. To activate the prompt about displaying or printing the Release Notes, invoke VMSINSTAL with the OPTIONS N parameter. After DIGITAL ACMS Desktop has been installed, the Release Notes are located in a directory with public access. 2.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 DIGITAL ACMS Desktop installation: SYS$COMMON:[SYSTEST.ACMSDI]ACMSDI$SYSTEM_FILES.DAT SYS$COMMON:[SYSTEST.ACMSDI]ACMSDI$SAMPLE_COMMON_FILES.DAT SYS$COMMON:[SYSTEST.ACMSDI]ACMSDI$SAMPLE_AVERTZ_FILES.DAT SYS$COMMON:[SYSTEST.ACMSDI]ACMSDI$SAMPLE_MSDOS_FILES.DAT SYS$COMMON:[SYSTEST.ACMSDI]ACMSDI$SAMPLE_MSWINDOWS_FILES.DAT SYS$COMMON:[SYSTEST.ACMSDI]ACMSDI$SAMPLE_MACINTOSH_FILES.DAT SYS$COMMON:[SYSTEST.ACMSDI]ACMSDI$SAMPLE_MOTIF_FILES.DAT You can display or print these files after you install DIGITAL ACMS Desktop software. Installing ACMS Desktop Software 2-1 The following logical names are added to your system after the installation: ACMSDI$COMMON ACMSDI$EXAMPLES ACMSDI$EXAMPLES_ACMS ACMSDI$EXAMPLES_MACINTOSH ACMSDI$EXAMPLES_MSDOS ACMSDI$EXAMPLES_MSW31 ACMSDI$EXAMPLES_NT_ALPHA ACMSDI$EXAMPLES_NT_I86 ACMSDI$EXAMPLES_WIN95 ACMSDI$EXAMPLES_VB ACMSDI$EXAMPLES_PB ACMSDI$EXAMPLES_MOTIF ACMSDI$EXAMPLES_MOTIF_VMS ACMSDI$EXAMPLES_MOTIF_VMS_ALPHA ACMSDI$EXAMPLES_MOTIF_SCO ACMSDI$EXAMPLES_MOTIF_UNIX ACMSDI$EXAMPLES_MOTIF_MIPS_ULTRIX ACMSDI$MACINTOSH ACMSDI$MSDOS ACMSDI$WIN95 ACMSDI$NT_ALPHA ACMSDI$NT_I86 ACMSDI$UNIX ACMSDI$VMS ACMSDI$VMS_ALPHA ACMSDI$SCO ACMSDI$MIPS_ULTRIX ACMSDI_AVERTZ_DEFAULT AVERTZ_TDB These logical names are entered into the system logical name table. The names are used in various DIGITAL ACMS Desktop startup files. Thus, they are automatically entered into the system logical name table whenever the DIGITAL ACMS Desktop startup command file is executed. 2-2 Installing ACMS Desktop Software 2.1.3 Installation Verification Procedure The Installation Verification Procedure (IVP) for DIGITAL ACMS Desktop software verifies the installation. 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 DIGITAL ACMS Desktop is installed correctly. After you install the DIGITAL ACMS Desktop 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 DIGITAL ACMS Desktop software. See Chapter 4 for information about running the IVP separately from the installation procedure. 2.2 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. 2.3 Installation Procedure Perform the steps in the following sections to install the DIGITAL ACMS Desktop software. On DIGITAL OpenVMS Alpha systems, if you have not already inserted the compact disk (CD) media in the CD drive, do so now before starting the installation. <> 2.3.1 Stopping DIGITAL ACMS and Digital ACMS Desktop Log in to the system under an account having the appropriate privileges (see Section 1.3.3). Username: SYSTEM Password: $ o If you have DIGITAL ACMS Desktop software already installed and running, shut it down: $ @SYS$STARTUP:ACMSDI$SHUTDOWN $ Installing ACMS Desktop Software 2-3 o If you have the ACMS Desktop Serial Gateway running, shut it down: $ MCR ACMSDI$SERIAL_GATE_MANAGER ACMSDIGW$MANAGER> SHUTDOWN ACMSDIGW$MANAGER> EXIT 2-4 Installing ACMS Desktop Software o Then, stop ACMS with the following commands: $ ACMS/STOP SYSTEM . . . $ @SYS$STARTUP:ACMSTOP . . . $ 2.3.2 Invoking VMSINSTAL While logged in to the privileged account, set default to the SYS$UPDATE directory: $ SET DEFAULT SYS$UPDATE $ Use the following syntax to invoke VMSINSTAL: @SYS$UPDATE:VMSINSTAL saveset-name device-name OPTIONS N saveset-name The installation name for the component. For DIGITAL ACMS Desktop software, use the following installation name: ACMSDI If you do not supply the saveset name, VMSINSTAL prompts you for this information later in the installation procedure. On OpenVMS Alpha systems, to obtain the directory location of the ACMS Desktop saveset on the CD, refer to OpenVMS Alpha Layered Products Compact Disc User's Guide that accompanies the CD distribution kit, or before starting the installation, complete these steps: 1. To determine whether the CD drive is already mounted (MOUNT command), enter the following: $ SHOW DEVICE device-name 2. IF the CD is not mounted, enter the appropriate MOUNT command to mount the CD (omit the /FOREIGN qualifier). Installing ACMS Desktop Software 2-5 3. To obtain the saveset name, use a DIRECTORY command specifying the directory file from the previous command: $ DIRECTORY device-name [acmsdi023]*.A <> device-name The name of the device on which you mount the distribution media. For example, MUA0: is the device name for a tape drive. You do not have to use the console drive for this installation. However, if you do use the console drive, after the installation is completed replace any media you removed. If you do not supply the device name, VMSINSTAL prompts you for this information later on in the installation procedure. OPTIONS N 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 has several other options; for information, see the OpenVMS documentation on software installation. The following command invokes VMSINSTAL and installs DIGITAL ACMS Desktop software from the MUA0: tape drive. This example uses the OPTIONS N parameter for printing or displaying Release Notes: On OpenVMS VAX systems: $ @SYS$UPDATE:VMSINSTAL ACMSDI MUA0: OPTIONS N OpenVMS VAX Software Product Installation Procedure V5.5-2 It is 29-MAR-1997 at 13:12. Enter a question mark (?) at any time for help.<> 2-6 Installing ACMS Desktop Software On OpenVMS Alpha systems: $ @SYS$UPDATE:VMSINSTAL ACMSDI USER3$:[DESKTOP] OpenVMS ALPHA Software Product Installation Procedure V6.1 It is 29-MAR-1997 at 13:12. Enter a question mark (?) at any time for help.<> VMSINSTAL does not prompt for any options. To access the Release Notes during the installation, include OPTIONS N on the VMSINSTAL command line. 2.3.3 Installation Questions This section discusses the questions that appear during the installation. See Appendix A for a sample 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 DIGITAL ACMS Desktop 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 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 Installing ACMS Desktop Software 2-7 Now mount the distribution volume on the device you specified when you invoked VMSINSTAL. The device name appears in the line preceding the question. VMSINSTAL then asks whether you are ready to continue with the installation. Answer YES to indicate that you are ready. VMSINSTAL displays a message that the media containing DIGITAL ACMS Desktop software is mounted on the specified device and that the installation is beginning. For example: Please mount the first volume of the set on MUA0:. * Are you ready? YES %MOUNT-I-MOUNTED, ACMSDI mounted on MUA0: The following products will be processed: ACMSDI V2.3 Beginning installation of ACMSDI V2.3 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. 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: 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 2-8 Installing ACMS Desktop Software 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 a queue name or press to send the file to the default output print device 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. Installing ACMS Desktop Software 2-9 5. 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. 1997. 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 DIGITAL ACMS Desktop software, do not delete the Release Notes for previous versions of DIGITAL ACMS Desktop. 6. Choosing to purge files You can purge files from previous versions of DIGITAL ACMS Desktop 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]? 7. Choosing to run the IVP If you are installing the DIGITAL ACMS Desktop 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 if you want to run the IVP after installing DIGITAL ACMS Desktop software. Answer NO to omit the IVP. Run the IVP independently after the installation to check the consistency of the DIGITAL ACMS Desktop software. See Chapter 4 for information about how to run the DIGITAL ACMS Desktop IVP independently of the installation procedure. 2-10 Installing ACMS Desktop Software 8. Choosing the sample application If the product is already installed, you can install the AVERTZ sample application. To install the sample application source files without installing the product, answer NO to the product installation question. * Do you wish to install any of the ACMS Desktop samples at this time [YES]? YES The AVERTZ sample application forms the basis of most of the programming samples in the DIGITAL ACMS Desktop user documentation. The sample contains both source code you can borrow and modify, and executable code you can run to gain experience with the software. The DIGITAL ACMS Desktop sample is divided into several parts. If you answer NO, no part of the sample is installed. If you answer YES to this question, you are asked the following questions to specify what parts of the sample you want to install. a. Choosing the AVERTZ sample These files for the back-end application include the DIGITAL ACMS task, task group, and application definitions and command procedures to set them up. The procedures to set them up are given in Section 5.2.7.5. The installation of the ACMS Desktop AVERTZ Application requires 4700 blocks. * Do you wish to install the AVERTZ application [YES]? YES To run any of the DIGITAL ACMS Desktop samples, install the AVERTZ application. If you do not intend to run any of the samples, answer NO to this question. If you answer YES, the AVERTZ sample application DIGITAL ACMS source files are stored in the [.ACMSDI] and [.ACMSDI.ACMS} subdirectories of SYS$EXAMPLES. b. Choosing the DOS sample Installing ACMS Desktop Software 2-11 These files for the sample blocking client program are the C and COBOL source and build files. The installation of the ACMS Desktop MS-DOS sample requires 650 blocks. * Do you wish to install the MS-DOS sample [YES]? YES If you are implementing a client on the DOS platform that uses the blocking forms of the DIGITAL ACMS Desktop services, answer YES. If you answer YES, the files are stored in the [.ACMSDI.MSDOS] subdirectory of SYS$EXAMPLES. To install the sample source files on a desktop system, follow the procedures in Chapter 5. 2-12 Installing ACMS Desktop Software c. Choosing the Windows, Visual Basic, PowerBuilder, Windows NT, and Windows 95 samples These files for the sample client programs are Visual Basic, PowerBuilder, C, Windows, Windows 95, and the Windows NT source and build files. The installation of the ACMS Desktop Windows samples requires 1300 blocks. * Do you wish to install the Windows samples [YES]? YES If you are implementing a client on the Microsoft Windows that uses the DIGITAL ACMS Desktop services, answer YES. If you answer YES, the files are stored in the [.ACMSDI.WINDOWS] subdirectory tree of SYS$EXAMPLES. To install the sample source files on a desktop system, follow the procedures in Chapter 5. d. Choosing the Macintosh sample These are the files needed to build and support the ACMSDI$EXAMPLES_MACINTOSH sample ACMS application. The installation of the ACMS Desktop Macintosh sample requires 40 blocks. * Do you wish to install the Macintosh sample [YES]? YES If you are implementing a client on the Macintosh platform, answer YES. If you answer YES, the files are stored in the [.ACMSDI.MACINTOSH] subdirectory of SYS$EXAMPLES. To install the sample source files on a desktop system, follow the procedures in Chapter 6. e. Choosing the Motif sample The installation of the ACMS Desktop Motif sample requires 5250 blocks. * Do you wish to install the Motif sample [YES]? YES If you are implementing a client on the OpenVMS, DIGITAL UNIX, RISC ULTRIX, or SCO UNIX platforms under Motif X Windows, you have a choice of samples. If you answer YES, the files are stored in the appropriate subdirectory of SYS$EXAMPLES. Installing ACMS Desktop Software 2-13 f. Verifying your selection of samples The procedure prints a summary of your choices for the samples and the approximate sizes and total size in blocks occupied on the OpenVMS system. You can verify your selections. You have made the following sample installation choices: COMMON FILES 150 BLOCKS AVERTZ APPLICATION 4700 BLOCKS MS-DOS SAMPLE 650 BLOCKS MICROSOFT WINDOWS SAMPLE 1200 BLOCKS MACINTOSH SAMPLE 40 BLOCKS MOTIF SAMPLE 5250 BLOCKS ==================================== TOTAL SIZE: 11990 BLOCKS * Are you satisfied with your selections [YES]? YES If you answer YES, the parts of the sample listed are installed. If you answer NO, you are asked to reenter the sample selections. 9. Confirming license registration VMSINSTAL asks whether you have a PAK installed. You can install DIGITAL ACMS Desktop software prior to registration; however, the software is unusable until you register the license. Looking up the Product Authorization Information. Product: DESKTOP-ACMS Producer: DEC Version: 2.3 Release Date: 07-MAY-1997 * Does this product have an authorization key registered and loaded? YES 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. 2-14 Installing ACMS Desktop Software 2.3.4 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 DIGITAL ACMS Desktop 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 1-2. Installing ACMS Desktop Software 2-15 2.3.5 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: On OpenVMS VAX systems: %RUN-S-PROC_ID, identification of created process is 210031D5 Starting Server ACMSDI$SERVER The ACMS Desktop V2.3 IVP completed successfully Installation of ACMSDI V2.3 completed at 13.32 . . . The ACMS Desktop V2.3-00 IVP completed successfully <> On OpenVMS Alpha systems: %RUN-S-PROC_ID, identification of created process is 00000176 Starting Server ACMSDI$SERVER . . . The ACMS Desktop V2.3 IVP completed successfully Installation of ACMSDI V2.3 completed at 13.32 Adding history entry in VMI$ROOT:[SYSUPD]VMSINSTAL.HISTORY Creating installation data file: VMS$ROOT:[SYSUPD]ACMSDI023.VMI_DATA <> 2.3.6 Completing the Installation Procedure The following messages indicate that the entire installation procedure is complete: Installation of ACMSDI V2.3 completed at 13:32 VMSINSTAL procedure done at 13:33 $ You can now log out of the privileged account: $ LOGOUT SYSTEM logged out at 29-MAR-1997 14:40:12.28 2-16 Installing ACMS Desktop Software VMSINSTAL deletes or changes entries in the process symbol tables during the installation. Therefore, if you are going to continue using the system account and you want to restore these symbols, log out and log in again. Proceed to Chapter 3 to follow postinstallation procedures. 2.4 Recovering from System and Installation Failures An unsuccessful installation can result from a system failure or errors encountered during the installation procedure. 2.4.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 DIGITAL ACMS Desktop 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. Installing ACMS Desktop Software 2-17 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. %VMSINSTAL-I-RECOVER, ACMS Desktop was being installed when the system crashed. The installation completed satisfactorily. This message indicates that VMSINSTAL finished successfully, not that the installation of DIGITAL ACMS Desktop was successful. VMSINSTAL does not automatically restart the IVP. Run the IVP independently by following the steps described in Chapter 4. 2.4.2 DIGITAL ACMS Desktop Installation Failures If the installation of the DIGITAL ACMS Desktop software or an DIGITAL ACMS Desktop 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 1. 2-18 Installing ACMS Desktop 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 DIGITAL ACMS Desktop software. If the IVP fails after you reinstall the DIGITAL ACMS Desktop software, contact your DIGITAL specialist. 2.4.3 Error Recovery You can run the IVP separately after you install DIGITAL ACMS Desktop software by following the instructions in Chapter 4. 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 4. If you reinstall DIGITAL ACMS Desktop software, the IVP runs automatically if you answer YES to the IVP question. If you still cannot successfully run the IVP, contact your DIGITAL specialist. Installing ACMS Desktop Software 2-19 3 _________________________________________________________________ After Installing DIGITAL ACMS Desktop Software After installing DIGITAL ACMS Desktop software, perform the following tasks: o Edit DIGITAL OpenVMS system startup and shutdown files. o Perform any cluster operations. o Read the management chapters in DIGITAL ACMS Desktop for OpenVMS Client Application Programming Guide. See Chapter 4 for information about how to run the Installation Verification Procedure (IVP) after the software has been installed. 3.1 Editing the OpenVMS System Files You must edit the OpenVMS system startup and shutdown files to provide for automatic startup and shutdown of DIGITAL ACMS Desktop software when your system is rebooted. (This step is usually not necessary for system upgrades.) 3.1.1 Editing the System Startup File The ACMSDI$STARTUP.COM and ACMSDI$SHUTDOWN.COM files are located in the SYS$STARTUP directory. Add the command line that starts DIGITAL ACMS 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. Position the DIGITAL ACMS Desktop startup command line after the line that invokes the DIGITAL ACMS startup command procedure. For example: After Installing DIGITAL ACMS Desktop Software 3-1 $ @SYS$STARTUP:ACMSTART.COM . . . $ @SYS$STARTUP:ACMSDI$STARTUP.COM $ ________________________ Note ________________________ Start DIGITAL ACMS before you start DIGITAL ACMS Desktop. ______________________________________________________ Starting ACMS 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 ACMS Desktop startup command line. The parameter file is a simple ASCII text file that lists customer overrides to ACMS 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 ACMS Desktop to use all transports, create a file in SYS$MANAGER: called ACMS_DESKTOP_SERVER.DAT, which contains the following line: transport=(tcpip,netware,decnet,serial,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 the following command: $ SUBMIT/USER=SYSTEM/NOLOG SYS$STARTUP:ACMSDI$STARTUP- _$ /PARAMETER=(SYS$MANAGER:ACMS_DESKTOP_SERVER.DAT) 3-2 After Installing DIGITAL ACMS Desktop Software 3.1.2 Editing the System Shutdown File The ACMSDI$SHUTDOWN.COM file is located in the SYS$STARTUP directory. Find the following line in the file: $ @ACMSTOP.COM At some point before the line that stops the DIGITAL ACMS system, add the following command line to the system shutdown file: $ @SYS$STARTUP:ACMSDI$SHUTDOWN.COM The command procedure cancels all active tasks and shuts down the DIGITAL ACMS Desktop server. This ensures that the DIGITAL ACMS Desktop system processes are run down properly. The command procedure also deinstalls DIGITAL ACMS Desktop images (using the Install Utility of OpenVMS) and deassigns the logical names. 3.2 Performing Cluster Procedures Because DIGITAL ACMS 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) $ 3.3 Client and Sample Software Installation To develop DIGITAL ACMS Desktop client programs on their desktop platforms, you must install specific DIGITAL ACMS Desktop client software on the desktop development system. Included in the product is sample software that is helpful in aiding developers in following the design and development procedures described in the documentation. After Installing DIGITAL ACMS Desktop Software 3-3 3.3.1 Client Software on Desktop Systems During the installation, client software is stored on the OpenVMS system. After the installation, you must transfer this software to the desktop development systems. The information to transfer the software appears as follows: o For DOS, Windows 3.n, Windows NT, Windows 95, DIGITAL UNIX, OpenVMS, UNIX, MIPS ULTRIX, and SCO UNIX desktop systems, see Chapter 5. o For Macintosh systems, see Chapter 6. 3.3.2 Matching Client and Server Versions If you are upgrading from ACMS Desktop Version 2.n to ACMS Desktop Version 2.3, you can use your existing client programs. But, if you build a new client program under ACMS Desktop Version 2.3, you cannot use this new program with ACMS Desktop Version 2.n. When the ACMSDI desktop server communication protocols do not match those of the ACMSDI desktop client, the ACMS Desktop server rejects the attempted connection. The server outputs 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 3.3.3 Sample Software If you request sample software during the installation, directories on the OpenVMS system are created to store the samples. If you want to set up and run the sample software under DIGITAL ACMS and DIGITAL ACMS Desktop software, follow the steps described in the documentation as follows: o For DOS and Windows systems, you can use both a blocking and nonblocking sample client program. For installing the blocking and nonblocking sample clients, see Chapter 5. o For Macintosh systems, you can use a Version 7 sample client program. 3-4 After Installing DIGITAL ACMS Desktop Software See Section 6.1 in Chapter 6. o To set up the sample application on the OpenVMS system, follow the procedures in Section 5.2.7.5. 3.4 Determining and Reporting Problems Installing DIGITAL ACMS Desktop software changes the state of your system. Record any changes to the system in your system management log. If an error occurs while DIGITAL ACMS Desktop software is being used and you believe that the error is caused by a problem with DIGITAL ACMS Desktop, take one of the following actions: o If you have a Basic or DECsupport Software Agreement, call your Customer Support Center. (With these services, you receive telephone support that provides high-level advisory and remedial assistance.) o If you have a Self-Maintenance Software Agreement, submit a Software Performance Report (SPR). See DIGITAL ACMS Desktop for OpenVMS Release Notes for information regarding submission of SPRs. o If you purchased DIGITAL ACMS Desktop software within the past 90 days and think the problem is caused by a software error, submit a Software Performance Report (SPR). See DIGITAL ACMS Desktop for OpenVMS Release Notes for information regarding submission of SPRs. After Installing DIGITAL ACMS Desktop Software 3-5 4 _________________________________________________________________ Running the DIGITAL ACMS Desktop IVP This chapter describes how to run the DIGITAL ACMS Desktop IVP separately from the installation procedure. The installation verification procedure (IVP) can be run as a part of the normal installation. The IVP automatically runs when you install the DIGITAL ACMS Desktop software and answer YES to the IVP question. If the IVP fails for any reason, correct the error and rerun the IVP. See Chapter 2 for information on providing the IVP with information required for the installation procedure. 4.1 IVP Operations The IVP checks that the installation procedure successfully completed installing DIGITAL ACMS Desktop software and that the software can be used to set up and run DIGITAL ACMS Desktop applications. The IVP checks that all the necessary files are on the system. 4.2 Running the IVP Independently This section describes the requirements and steps to run the IVP. 4.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. Running the DIGITAL ACMS Desktop IVP 4-1 4.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 ACMS Installation Verification Procedure, 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 ACMS Desktop V2.3-0 IVP completed successfully $ The IVP takes no more than 30 seconds to run, depending on the current system load. 4.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 displays a message describing the failure and suggests a course of action. Follow the suggested course of action and then restart the IVP. 4-2 Running the DIGITAL ACMS Desktop IVP Part II _________________________________________________________________ ACMS Desktop Client Services Part II describes how to install the DIGITAL ACMS Desktop client services and the DIGITAL ACMS Desktop dynamic-link library on your desktop system. 5 _________________________________________________________________ Installing ACMS Desktop Portable API Services and Samples After you install the ACMS Desktop product and sample software on the host DIGITAL OpenVMS system, you can install the API and the sample on individual desktop systems that have the appropriate network software. This chapter discusses the installation of the ACMS Desktop services as follows: o Section 5.1.1 Discusses the prerequisites for installing the desktop software. o Section 5.2 Presents the API and sample installation procedures for DOS and Microsoft Windows operating systems. o Section 5.3 presents the API installation procedures for the Microsoft Windows 95 operating system. o Section 5.4 presents the API installation procedures for the Microsoft Windows NT operating system. o Section 5.5 Presents the API and sample installation procedures for OpenVMS operating systems. o Section 5.6 Presents the API installation procedures for the DIGITAL UNIX operating system. o Section 5.7 Presents the API and sample installation procedures for the SCO UNIX operating system. Installing ACMS Desktop Portable API Services and Samples 5-1 o Section 5.8 Presents the API and sample application procedures for the RISC ULTRIX operating system. o The last section, Section 5.9 Discusses the typical errors that can occur during installation. 5.1 Preparing to Install the API and Sample Software The following sections discuss the preparations and requirements necessary for installing ACMS Desktop services. 5.1.1 Prerequisite Software Before installing the ACMS Desktop services on the various desktop systems, you need the network access listed in Table 5-1 to an OpenVMS system running the appropriate version of ACMS software. Table_5-1_Network_Access___________________________________ Desktop_System___Network___________________________________ DOS DECnet, TCP/IP, NetWare, or Serial Windows DECnet, TCP/IP, NetWare, or Serial Windows 95 DECnet, TCP/IP Windows NT DECnet, TCP/IP[1] OpenVMS VAX DECnet, TCP/IP, NetWare[2] OpenVMS Alpha DECnet, TCP/IP, NetWare[2] DIGITAL UNIX DECnet, TCP/IP Alpha Macintosh DECnet, TCP/IP, Apple-Talk/DECnet SCO UNIX DECnet, TCP/IP RISC ULTRIX DECnet, TCP/IP [1]TCP/IP_is_supported_on_Windows_NT_Version_4.0.__________ [2]NetWare support for testing purposes only. ___________________________________________________________ Table 5-2 lists the products required to use the various APIs. The table is divided according to network transport. 5-2 Installing ACMS Desktop Portable API Services and Samples Table_5-2_Software_Requirements_for_API____________________ API_Using_DECnet_______Products_Required___________________ DOS client PATHWORKS for DOS and Windows Version 5.0 or higher, Microsoft Visual C++ Version 1.5 or compatible compiler Microsoft Windows PATHWORKS for DOS and Windows client Version 5.0 or higher, Microsoft Visual C++ Version 1.5 or compatible compiler Windows 95 client PATHWORKS for Windows 95 Version 1.0 or higher Microsoft Visual C++ Version 4.0 or compatible compiler Windows NT client PATHWORKS for Windows NT Version 4.1b Microsoft Visual C++ Version 4.0 or compatible compiler Visual Basic client PATHWORKS for DOS and Windows Version 5.0 or higher Visual Basic Version 3.0 or higher OpenVMS VAX client VAX C or compatible compiler DECnet-VAX OpenVMS Alpha client DEC C or compatible compiler DECnet-Alpha RISC ULTRIX client DEC C or compatible compiler[1] DECnet-ULTRIX SCO UNIX client SCO UNIX System V/386 or SCO ODT DECnet for SCO UNIX OpenVMS Alpha server DECnet-Alpha ACMS Remote or Run-Time OpenVMS VAX server DECnet-VAX ACMS Remote or Run-Time [1]If_you_are_running_UWS,_you_already_have_the_DEC_C______ compiler. (continued on next page) Installing ACMS Desktop Portable API Services and Samples 5-3 Table_5-2_(Cont.)_Software_Requirements_for_API____________ API_Using_TCP/IP_______Products_Required___________________ DOS client PATHWORKS for DOS and Windows Version 5.0 or higher Microsoft Windows PATHWORKS for DOS and Windows client Version 5.0 or higher[2] Windows top 95 client Microsoft Visual C++ Version 4.0 or compatible compiler Windows NT client Microsoft Visual C++ Version 4.0 or compatible compiler Macintosh client PATHWORKS for Macintosh DIGITAL UNIX Alpha DEC C or compatible compiler RISC ULTRIX client DEC C or compatible compiler[1] SCO UNIX client SCO UNIX SYSTEM V/386 or SCO ODT SCO TCP/IP Run-Time OpenVMS server TCP/IP Services for OpenVMS Version 3.2 or Multinet Version 3.3, ACMS Remote or Run-Time ___________________________________________________________ API_Using_NetWare______Products_Required___________________ DOS client Novell NetWare Version 3.2, or PATHWORKS Version 5.0 Microsoft Windows Novell NetWare Version 3.2, client or PATHWORKS Version 5.0 Microsoft Windows Version 3.1 Microsoft Visual C++ Version 1.5 Visual Basic client Novell NetWare Version 3.2, or PATHWORKS Version 5.0 [1]If_you_are_running_UWS,_you_already_have_the_DEC_C______ compiler. [2]Windows clients can use any TCP/IP for Windows that follows the Windows Sockets Version 1.1 standard. (continued on next page) 5-4 Installing ACMS Desktop Portable API Services and Samples Table_5-2_(Cont.)_Software_Requirements_for_API____________ API_Using_NetWare______Products_Required___________________ OpenVMS server Interconnections Leverage Host Server Version 3.1 ___________________________________________________________ API Using Serial Communications_________Products_Required___________________ DOS client None Microsoft Windows None client_____________________________________________________ Table 5-3 lists the products required to use the sample application. Table_5-3_Sample_Application_Product_Dependencies________________ Sample______________Products_Required____________________________ DOS Microsoft COBOL Version 5.0 Microsoft Visual C++ Version 1.5 or higher Microsoft Windows Microsoft Windows Version 3.1 or higher Microsoft Visual C++ Version 1.5 or higher Visual Basic Microsoft Windows Version 3.1 or higher client Microsoft Visual Basic Version 3.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 DIGITAL UNIX Alpha UNIX for OSF/Motif Version 1.1 Motif on RISC DEC C for RISC, DECwindows Developer Kit on ULTRIX RISC ULTRIX for OSF/Motif Version 1.1 Motif on SCO/ODT Open Desktop Development System Version ____________________1.1.ob_or_higher_____________________________ Installing ACMS Desktop Portable API Services and Samples 5-5 5.1.2 API Installation Procedure Requirements The following sections discuss the requirements for installing the software. 5.1.2.1 Time Table 5-4 lists the approximate time needed to install the Desktop ACMS services on a standalone desktop system. The time to install varies depending on the hardware configuration and network connection. Table_5-4_API_Installation_Timetable_______________________ Desktop_System___Time_to_Install___________________________ DOS (hard disk) 10 minutes OpenVMS 5 minutes DIGITAL UNIX 10 minutes SCO UNIX 10 minutes ULTRIX___________10_minutes________________________________ 5.1.2.2 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 ACMS Desktop server is installed o Valid account (user name and password) on the OpenVMS system on which the ACMS Desktop server is installed o Directory for the ACMS Desktop API and network software in your directory search path o Directory in which to install the sample software o Sufficient disk space to install the API, network software, and sample code o Host name on TCP/IP or NetWare 5-6 Installing ACMS Desktop Portable API Services and Samples 5.1.2.3 Use of Self-Extracting Archives The following self-extracting archives are provided: o Client API for DOS, Windows, Windows 95, and Windows NT o Samples for DOS and Windows These archives expand upon execution. The self-extracting archives were made using Info-ZIP's compression utility. The Info-ZIP software (Zip, UnZip, UnZipSfx and related utilities) is free and can be obtained as source or executables from various bulletin board or Internet web browser services. 5.2 Installing the DOS and Windows APIs ACMS Desktop provides one self extracting archive named MSDOS.EXE that contains all the files that are associated with both the DOS and Windows 3.n APIs for ACMS Desktop. The files contained within the archive include the static- link libraries and the DLLs for use with Windows. There are individual object files and DLLs for the supported transports and files that deal with telephone dialing for the serial transport. To expand the archive, copy it in image mode to a clean directory on the PC, and execute it. The archive expands, and the resulting files can then be used. For example, on the PC: C:\ > CD ACMSDI C:\ > NFT COPY/block nodename"username password"::ACMSDI$MSDOS:MSDOS.EXE C:\ > MSDOS.EXE In addition to the DOS specific files, there are some common files that are needed to build an application. These files are on the OpenVMS system in the directory ACMSDI$COMMON: ACMSDI.H FORMS.H PPSTUBS.C TDMS.H Copy those files to the current directory, for example, using DECnet: C:\ > NFT COPY nodename"username password"::ACMSDI$COMMON:*.* Installing ACMS Desktop Portable API Services and Samples 5-7 If this is to be your working directory, add it in your autoexec.bat startup file to the environment variables that define the paths for the libraries, include files and execution path, for example: set LIB=%LIB%;dir set INCLUDE=%INCLUDE%;dir set PATH=%PATH%;dir 5.2.1 Setting Up the DOS Client Services The DOS API uses the static-link library is ACMSDIL.LIB. There are transport object files provided for the large- memory model, whose name reflects the transport they support. Select the object file that corresponds to the transport you are going to use when building the application. ___________________________________________________________ Memory Model_____DECnet________TCP/IP________Netware_______Serial_ Large_____netdecl.obj___nettcpl.obj___netwarel.obj__netstl.obj The static-link library come with the DECnet object inserted, if you are not building for DECnet, remove the DECnet module and insert the module you are using. For example, to setup up the large model for TCP/IP: LIB ACMSDIL.LIB -NETDECL; LIB ACMSDIL.LIB +NETTCPL; 5.2.2 Installing the DOS Sample Application The DOS COBOL sample is provided on the OpenVMS system as a self-extracting archive file. To expand the archive, copy it in image mode to a clean directory on the PC, and execute it. For example, on the PC: C:\ > CD ACMSDI\CLIENT C:\ > NFT COPY/block nodename"user passw"::ACMSDI$EXAMPLES_MSDOS:EGCOBOL.EXE C:\ > EGCOBOL.EXE The sample executable was built using the DECnet libraries, if you are not running DECnet, the sample needs relinking before it can be used. 5-8 Installing ACMS Desktop Portable API Services and Samples 5.2.3 Verifying the DOS Sample Installation 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 run-time 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 software includes a batch file to build the sample client program. You can modify this file according to your own software development environment. After you modify the file, enter the following commands: \CLIENT> BLD-PPS . . . \CLIENT> BLD-CLI . . . To run the sample client program, enter the following command: \CLIENT> 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 5.2.7.5 to set up the sample application on the DIGITAL ACMS system. You can sign in to the DIGITAL ACMS system and use the reserve task of the application. The installation procedure is now complete and verified. Installing ACMS Desktop Portable API Services and Samples 5-9 5.2.3.1 NonWindows Sample Files Added to the System All C and COBOL language files (.c, .h, .cbl) listed in Table 5-5 are copied to the desktop system during the installation of the nonWindows sample. Table_5-5_NonWindows_Sample_Files__________________________ Name_______________Description_____________________________ ACMSDI.H Include file for ACMSDI BLD-CLI.BAT Batch file to compile and link the sample client program BLD-PPS.BAT Batch file to compile and link presentation 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 LOADER.BAT Batch file to download the sample from the OpenVMS VAX system LOGIN.CBL Sample client initialization procedure LOGOFF.CBL Sample client termination procedure MENU.CBL Sample client menu procedure RECV.C Sample presentation procedure REQUEST.C Sample presentation procedure (continued on next page) 5-10 Installing ACMS Desktop Portable API Services and Samples Table_5-5_(Cont.)_NonWindows_Sample_Files__________________ Name_______________Description_____________________________ 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_______ 5.2.4 Setting up the Windows Client Services Normally when building applications under Windows, the the DLLs provided with ACMS Desktop are used, rather than the static-link libraries. However, you can use the static-link libraries if you prefer, when the transport is DECnet. To use the DLLs, identify which one, by selecting the transport that is to be supported. ___________________________________________________________ DECnet________TCP/IP________Netware_______Serial___________ ACMSDIDN.DLL__ACMSDIWS.DLL__ACMSDINW.DLL__ACMSDIST.DLL_____ The name of the DLL that will be used by ACMS Desktop for Windows is ACMSDI.DLL. Copy the selected DLL that contains the support for the needed transport, to create the ACMSDI.DLL. For example, to use TCP/IP through use of the Winsock interface: C:\ > copy ACMSDIWS.DLL ACMSDI.DLL Installing ACMS Desktop Portable API Services and Samples 5-11 If the resulting DLL is to be used in place, then the containing directory must be included in the path, or be the default working directory for Windows. There is an executable file, diTskLnk.exe, that supports multiple executables sharing a submitter session under Windows Version 3.1 using TCP/IP. See DIGITAL ACMS Desktop for OpenVMS Gateway Management Guide for information on this executable file. 5.2.5 Code Conversion Libraries for Kanji ACMS Desktop 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 client user applications, if the application requires Kanji code conversion. These libraries are located in the following directories: SYS$COMMON:[ACMSD.JCNVWIN.WIN31] (for Windows 3.1) SYS$COMMON:[ACMSD.JCNVWIN.WIN95] (for Windows 95) For further information, refer to JCNVWIN_GUIDE.PS or JCBVWIN_GUIDE.TXT, located in either directory. 5.2.6 Installing the Windows Sample Application The Windows Avertz sample is provided in two forms on the VMS system as self extracting archive files in the ACMSDI$EXAMPLES_MSW31: directory. The file SDK31LIB.EXE contains both the sample sources and the make file for using the DECnet medium model static-link library. The file SDK31DLL.EXE contains just the alternate files in order to build against DLLs. The resulting executable file can work with any of the supported transports. To expand the selected archive, copy it in image mode to a clean directory on the PC and execute it. For example, on the PC to obtain the files for building against the static link libraries: C:\ > CD ACMSDI\SDK31 C:\ > NFT COPY nodename"username password"::ACMSDI$COMMON:*.h C:\ > NFT COPY/block nodename"user passw"::ACMSDI$EXAMPLES_MSW31:SDK31LIB.EXE C:\ > SDK31LIB.EXE 5-12 Installing ACMS Desktop Portable API Services and Samples To obtain the files for DLL builds, perform the above to get the sources, then override the static link make files by expanding those to build the DLL version. C:\ > NFT COPY/block nodename"user passw"::ACMSDI$EXAMPLES_MSW31:SDK31DLL.EXE C:\ > SDK31DLL.EXE 5.2.7 Verifying the Windows Sample Installation 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 run-time library that is compatible with Microsoft Visual C++ Version 1.5 o Microsoft Windows Version 3.1 or 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. To build the sample application, follow these steps: 1. Using the AVERTZ makefile, build the sample application by running NMAKE in the directory containing the sample files. o To use NMAKE, enter the following command: nmake -f AVERTZ 2. Run Windows by entering the following command: 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\SDK31\avertz Installing ACMS Desktop Portable API Services and Samples 5-13 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 on 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\SDK31\sample 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\SDK31 j. In the dialog box, select the OK button. The AVERTZ icon appears in the group window. k. Double click on the AVERTZ icon to run the sample client program. The AVERTZ program displays the menu bar of the AVERTZ Vehicle Rental System application. 5-14 Installing ACMS Desktop Portable API Services and Samples If you want the sample desktop client program to communicate with the DIGITAL ACMS application, follow the procedures in Section 5.2.7.5 to set up the sample application on the DIGITAL ACMS system. After you set up the DIGITAL ACMS system, use the Session menu to sign in to the DIGITAL 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. If errors occur in running the program, the problem might be caused by a faulty startup or configuration file. Example 5-1 shows a sample startup.bat file. Example 5-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 Example 5-2 shows a sample config.sys file. Example 5-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. Installing ACMS Desktop Portable API Services and Samples 5-15 5.2.7.1 Using AVERTZ Sample Application on a System 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_ACMS:VR_READ_SERVER.OPT ACMSDI$EXAMPLES_ACMS:VR_UPDATE_SERVER.OPT Replace the line SYS$LIBRARY:SQL$USERnn.OLB/LIBRARY with the following: SYS$USER/LIBRARY 5.2.7.2 Building the Avertz ACMS Sample Application with DECforms V1.4 The VR_FORM.IFDL file of the Avertz ACMS sample application 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 5-16 Installing ACMS Desktop Portable API Services and Samples To look like: Copy "AVERTZ_CDD_FIELD:CUSTOMER_ID" from Dictionary End Copy 5.2.7.3 AVERTZ User Name Quota Values 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 may 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. 5.2.7.4 Access Control List for AVERTZ 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 may 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]. 5.2.7.5 Setting Up the AVERTZ Sample Application 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_ACMS 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: Installing ACMS Desktop Portable API Services and Samples 5-17 $ @ACMSDI$EXAMPLES_ACMS:VR_DA_RUNTIME_SETUP . . . $ 2. Start the DIGITAL ACMS system (if necessary) and the application: $ 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 ACMS Desktop for OpenVMS Client Application Programming Guide. You can then run the DOS, Windows, Windows 95, and Macintosh AVERTZ clients to call the reserve task in VR_ DA_APPL. 5.2.7.6 Rebuilding the DIGITAL ACMS Desktop 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 Oracle CDD directories for the AVERTZ components. b. Define logical names. If you are using a directory other than ACMSDI$EXAMPLES_ACMS for rebuilding the sample, edit the logical name definitions in the VR_DA_BLD_ LOGICALS.COM command procedure to point to your file and Oracle 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. 5-18 Installing ACMS Desktop Portable API Services and Samples 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 5-6. Table_5-6_VR_DA_BLD_MMS.COM_Parameters_____________________ Keyword__________Activity__________________________________ BLD Run MMS to build VR_DA_APPL CDD Set up the Oracle CDD dictionary and directories for VR_DA_APPL DB_______________Create_the_VEHICLE_RENTALS_database_______ 5.2.7.7 Windows Sample Files Added to the System All C language and header files (.c and .h), Windows (.def), icons (.ico), executable files (.exe), and data files (.dat) listed in Table 5-7 are copied to the desktop system during the installation of the API and sample client software. Table_5-7_Windows_Sample_Files_____________________________ Name_______________Description_____________________________ ACMSDI.H Include file for the DIGITAL ACMS Desktop API AVERTZ Makefile for building the sample AVERTZ.C Entry point for the sample; manages the main window of the sample AVERTZ.DEF Windows definition file; defines entry points and stack size for Windows AVERTZ.EXE Windows sample executable file AVERTZ.H AVERTZ header file; defines globals (continued on next page) Installing ACMS Desktop Portable API Services and Samples 5-19 Table_5-7_(Cont.)_Windows_Sample_Files_____________________ Name_______________Description_____________________________ 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; preallocates memory using arrays to reduce fragmentation of the local heap LIST_PKG.H Header file for list_pkg.c LOADWIN.BAT Batch file to download the Windows sample from the OpenVMS VAX system RECVW.C Presentation procedure stub 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 (continued on next page) 5-20 Installing ACMS Desktop Portable API Services and Samples Table_5-7_(Cont.)_Windows_Sample_Files_____________________ Name_______________Description_____________________________ SDRIVING.ICO Icon for a selected session that is currently processing a task SENDW.C Presentation procedure to dispatch to specific routines in avertzpp SESSION.C Manages multiple sessions; switches context for using ACMS Desktop routines and updates the user interface SESSION.H Header file for 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 VERSIONW.C Version-checking procedure stub WKSPACES.C String conversion support for AVERTZ workspace structures WKSPACES.H_________Defines_the_AVERTZ_workspace_structures_ 5.2.8 Installing the PowerBuilder Version 5.0 Sample Applications There is a PowerBuilder sample application provided in the OpenVMS installation directory, ACMSDI$EXAMPLES_PB. There are two self-extracting archive files: 32PB5KIT.EXE and 16PB5kit.exe. Each archive file contains the 32-bit or 16-bit sample application, PBAVERZ.PBL, which is a PowerBuilder library containing PowerBuilder objects for a simplified version of the original AVERTZ client sample for Windows. This sample illustrates the execution of an ACMS task with no exchange I/O. Installing ACMS Desktop Portable API Services and Samples 5-21 Each self-extracting archive also contains a DLL (PBPOINTR.DLL) required for memory management when building PowerBuilder applications that use ACMS Desktop services. The use of PBPOINTR.DLL services is discussed in an MSW Word document (ACMSDIPB.DOC). To expand the self-extracting archive, copy it in image mode to a clean directory on the PC and execute it. For example, on the PC: C:\> CD ACMSDI\PBSMP C:\PBSMP> NFT COPY/BLOCK nodename"user passw"::ACMSDI$EXAMPLES_PB:PB5KIT.EXE C:\PBSMP> PB5KIT.EXE Table 5-8 lists files that are added to the system. Table_5-8_Files_Added_for_PowerBuilder_Samples_____________ Name_____________Description_______________________________ ACMSDIPB.DOC Document discussing ACMS Desktop 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 5.2.9 Installing the Visual Basic Sample Applications There are two Visual Basic sample applications provided in the OpenVMS installation directory ACMSDI$EXAMPLES_VB: in the form of self extracting archive files. The AVERTZVB.EXE contains the files for the same sample that was provided for ACMS Desktop V2.0, it is a blocking, no exchange I/O AVERTZ samples. The file FNONBLK.EXE contains the files of a tutorial sample showing how to program to the new ACMS Desktop forced non-blocking interface. This interface allows languages like Visual Basic to issue non-blocking 5-22 Installing ACMS Desktop Portable API Services and Samples calls to ACMS Desktop and provides support for programming ACMS exchange I/O interface calls. To expand the selected archive, copy it in image mode to a clean directory on the PC and execute it. For example on the PC: C:\ > CD ACMSDI\VBAVERTZ C:\ > NFT COPY/block nodename"user passw"::ACMSDI$EXAMPLES_VB:AVERTZVB.EXE C:\ > AVERTZVB.EXE 5.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. 5.2.9.2 Visual Basic Sample Files Added to the System Table 5-9 lists the Visual Basic files added to the system. Table_5-9_Visual_Basic_Sample_Files________________________ Name_______________Description_____________________________ ACMSDI.BAS Include file of the ACMSDI declaration for Visual Basic applications (continued on next page) Installing ACMS Desktop Portable API Services and Samples 5-23 Table_5-9_(Cont.)_Visual_Basic_Sample_Files________________ Name_______________Description_____________________________ HELP.TXT Online help file for the Visual Basic sample LOADVB.BAT Batch file to download Visual Basic sample from OpenVMS system 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_ 5.2.9.3 Verifying the Visual Basic Forced Nonblocking Tutorial To verify the successful installation of the Visual Basic Forced Nonblocking Tutorial, bring up the Visual Basic development environment under 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. NOTE: ACMSDI.BAS and FORMS.BAS were installed on your system as described in section 5.2. 3. Add file CONSTANT.TXT from the C:\VB directory by selecting Add File from the File menu. 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 5-24 Installing ACMS Desktop Portable API Services and Samples MTEXT.BAS NONBLK.BAS Double click on 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. 5.2.9.4 Visual Basic Sample Files Added to the System for FNBSAMPL Table 5-10 lists the Visual Basic files added to the system for the Visual Basic Forced Nonblocking Tutorial: Table_5-10_Visual_Basic_Sample_Files_for_FNBSAMPL_Sample___ 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 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___________________ 5.3 Installing the Windows 95 API ACMS Desktop Version 2.3 supports Windows 95 using DECnet and TCP/IP. The following sections describe how to install the ACMS Desktop interface for Windows 95. Installing ACMS Desktop Portable API Services and Samples 5-25 5.3.1 Installing the Windows 95 Client Software The client services for Windows 95 are contained in a self- extracting archive in the OpenVMS installation directory ACMSDI$WIN95. ACMSDI$WIN95: WIN95.EXE To expand the archive, copy it in image mode to a clean directory on the PC and execute it. For example, to copy into a directory called ACMSDI, using DECnet, type the following: C:\ACMSDI> NFT COPY/block nodename"username password"::ACMSDI$WIN95:WIN95.EXE C:\ACMSDI> WIN95.EXE This makes available the DLLs and reference libraries for both DECnet and TCP/IP versions of the client services for Windows 95. Common Files for Windows 95 In addition to the Windows 95 specific files, there are some common files that are needed to build an application. These files are on the OpenVMS system in the directory ACMSDI$COMMON: acmsdi.h forms.h ppstubs.c tdms.h Copy these files to the current directory, using DECnet: C:\ACMSDI> NFT COPY nodename"username password"::ACMSDI$COMMON:*.* If this is to be your working directory, add to a setup.bat file or modify through the control panel, setting environment variables that define the paths for the libraries, include files and execution path. For example: set LIB=%LIB%;C:\ACMSDI set INCLUDE=%INCLUDE%;C:\ACMSDI set PATH=%PATH%;C:\ACMSDI The client application program is linked against the acmsdi.lib reference library to resolve the ACMS Desktop API procedure references. At run time, programs linked against this library expect to locate two DLLs, acmsdi.dll and di_cnv.dll. Make sure that the di_cnv.dll is in the 5-26 Installing ACMS Desktop Portable API Services and Samples working directory. Depending on whether DECnet or TCP/IP is to be used for the transport, copy acmsdiDN.dll or acmsdiWS.dll to a file called acmsdi.dll. The acmsdiDN.dll provides DECnet support and works with PATHWORKS for Windows 95 V1.0. The acmsdiWS.dll provides TCP/IP support and works with the Windows 95 Winsock DLL called Wsock32.dll. Make sure that the acmsdi.dll file is also in the working directory. 5.3.2 Installing a Sample for Windows 95 There is no sample application for Windows 95. 5.4 Installing the Windows NT API ACMS Desktop Version 2.3 supports the following Windows NT configuration for ACMS Desktop clients: Platform: Intel, Alpha Network Transport: TCP/IP, DECnet Windows NT Version: Version 3.51 final release The following sections describe how to install the ACMS Desktop interface for Windows NT clients. 5.4.1 Installing the Windows NT Client Software The client services for NT 3.51 are contained in a self- extracting archive for Windows NT Intel systems and in a Zip file with an unzip utility program for Windows NT Alpha systems. These files are located in the OpenVMS installation directories. ACMSDI$NT_ALPHA: NT_ALPHA.ZIP ACMSDI$NT_ALPHA: UNZIP_ALPHA.EXE ACMSDI$NT_I86: NT_I86.EXE To expand the NT Intel archive, copy it in image mode to a clean directory on the PC and execute it. For example, to install the ACMS Desktop client services for Windows NT to work with an Intel-based PC: C:\ > CD ACMSDI C:\ > NFT COPY/block nodename"username password"::ACMSDI$NT_I86:NT_I86.EXE C:\ > NT_I86.EXE Installing ACMS Desktop Portable API Services and Samples 5-27 To expand the NT Alpha zip file, copy both the zip and the unzip files into a clean directory and execute the following command: C:\ > UNZIP_ALPHA NT_ALPHA.ZIP This makes available the DLLs and reference libraries for both DECnet and TCP/IP versions of the client services for NT. Common Files for Windows NT The archive expands, and the resulting files and directories are created in the working directory. These files provide the client services: c:\acmsdi\acmsdi.lib - The reference library to link against c:\acmsdi\acmsdiws.dll - The client services for TCP/IP operation c:\acmsdi\acmsdidn.dll - The client services for DECnet operation The following files provide memory copy procedures and can be used to assist with interfacing Visual Basic 32-bit programs with the client services: c:\acmsdi\divb.lib c:\acmsdi\divb.dll c:\acmsdi\readme.txt c:\acmsdi\readme.1st In addition to the NT Intel specific files, there are some common files that are needed to build an application. These files are on the OpenVMS system in the directory ACMSDI$COMMON: ACMSDI.H FORMS.H PPSTUBS.C TDMS.H Copy those files to the current directory, for example, using DECnet: C:\ > NFT COPY nodename"username password"::ACMSDI$COMMON:*.* 5-28 Installing ACMS Desktop Portable API Services and Samples If this is to be your working directory, add to a setup.bat file or modify through the control panel, setting environment variables that define the paths for the libraries, include files and execution path, for example: set LIB=%LIB%;dir set INCLUDE=%INCLUDE%;dir set PATH=%PATH%;dir 5.4.2 Installing a Sample for Windows NT There is no sample application for Windows NT. 5.5 Installing the OpenVMS API and Sample Client Software The following sections describe how to install the ACMS Desktop API and sample client software on an OpenVMS desktop system. 5.5.1 Installing the OpenVMS API The OpenVMS desktop system may, or may not be the same OpenVMS system on which you have already installed the ACMS Desktop kit. If it is the same system, then the API and the sample software have already been installed for you. If it is not the same system, follow these instructions to install the OpenVMS API: 1. Create the API directory on the desktop system: $ create/dir [.acmsdi] 2. Copy the appropriate files from the ACMS Desktop server system to your workstation. The following example copies the ACMS Desktop API library and header files to the acmsdi directory. In the following instructions, words in italics represent user-specific input: server_ The node name of the OpenVMS system where node ACMS Desktop has been installed and from which files are copied username A valid user account on server_node password The password of the user account username a. Copy the ACMS Desktop Header and Presentation Procedure Stubs File: Installing ACMS Desktop Portable API Services and Samples 5-29 $ set def [.acmsdi] $ copy server_node"username password" ::acmsdi$common:*.* *.* b. Copy the ACMS Desktop client library: For OpenVMS VAX systems: $ copy server_node"username password"::acmsdi$vms:acmsdi$client_objlib.olb - _$ acmsdi$client_objlib.olb <> For OpenVMS Alpha systems: $ copy server_node"username password"::acmsdi$vms_alpha:acmsdi$client_objlib.olb - _$ acmsdi$client_objlib.olb <> 3. If installing the OpenVMS API for NetWare or TCP/IP, configure the Desktop ACMS library for the appropriate transport. The ACMS Desktop 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. The following steps are necessary to reconfigure the ACMS Desktop library for NetWare or TCP/IP access: a. For NetWare, copy the NetWare object file (only available for OpenVMS VAX): $ copy server_node"username password"::acmsdi$vms:net_netware.obj *.* <> For TCP/IP, on OpenVMS VAX, copy the TCP/IP object file: $ copy server_node" username password"::acmsdi$vms:net_tcpip.obj *.* <> For TCP/IP, on OpenVMS Alpha, copy the TCP/IP object file: $ copy server_node" username password"::acmsdi$vms_alpha:net_tcpip.obj *.* <> b. Remove the DECnet object from the library with the following command: $ library/delete = net_decnet acmsdi$client_objlib.olb c. For NetWare, insert the NetWare transport access module into the library with the following command: $ library/insert acmsdi$client_objlib.olb net_netware.obj 5-30 Installing ACMS Desktop Portable API Services and Samples 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 ACMS Desktop applications that use NetWare or TCP/IP as a transport. 5.5.1.1 API Files Added to the OpenVMS Desktop System Files in Table 5-11 are copied to the OpenVMS system during the installation of the ACMS Desktop client services for OpenVMS software. Table_5-11_OpenVMS_Files___________________________________ Files____________Description_______________________________ ACMSDI.H Include file for the ACMS Desktop API ACMSDI$CLIENT_ Library for the ACMS Desktop API OBJLIB.OLB FORMS.H Include file for DECforms NET_TCPIP.OBJ TCP/IP object file NET_NETWARE.OBJ NetWare object file[1] PPSTUBS.C Presentation procedure and action routine stubs TDMS.H Include file for TDMS [1]For_testing_purposes_only_______________________________ ___________________________________________________________ 5.5.2 Installing the Motif Sample Client for OpenVMS Installing the Motif sample client involves copying the appropriate files to the user's account, and verifying that the sample can be rebuilt there. 5.5.2.1 Copying the Motif Sample Files on 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] Installing ACMS Desktop Portable API Services and Samples 5-31 2. Copy the general Motif sample files: $ copy server_node "username password"::acmsdi$examples_motif:*.* *.* - _$/exclude=(*.dir,*.sh) $ copy server_node "username password"::acmsdi$common:*.h *.* 3. Copy the OpenVMS-specific Motif sample files: For OpenVMS VAX systems: $ copy server_node "username password"::acmsdi$examples_motif_vms:*.* *.* <> For OpenVMS Alpha systems: $ copy server_node " username password"::acmsdi$examples_motif_vms_alpha:*.* *.* <> 4. Copy the Motif resource file to your home directory: $ copy m_avertz.dat sys$login:m_avertz.dat 5.5.2.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 If you download ACMS Desktop 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 ACMS Desktop 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. ______________________________________________________ 5-32 Installing ACMS Desktop Portable API Services and Samples 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 5.2.7.5 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. If errors occur in running the program, verify the following: o The m_avertz.uid file must be present 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). 5.5.2.3 Sample Files Added to the OpenVMS Desktop System All C language and header files (.c and .h), UIL files (.uil), UIL database files (.uid), executable files (.exe), and data files (.dat) listed in Table 5-12 are copied to the desktop system. Table_5-12_Motif_Sample_Files_for_the_OpenVMS_System_______ Name_____________Description_______________________________ Makefile Makefile for building the sample acmsdi.h Include file for the ACMS Desktop API forms.h Sample include file with DECforms status values (continued on next page) Installing ACMS Desktop Portable API Services and Samples 5-33 Table 5-12 (Cont.) Motif Sample Files for the OpenVMS ___________________System__________________________________ Name_____________Description_______________________________ help.txt Overview of the AVERTZ user interface load_motif Command shell to download the Motif sample from the OpenVMS system m_avertz 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 Run-time 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 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_receive.c Presentation procedure stub m_request.c Presentation procedure stub (continued on next page) 5-34 Installing ACMS Desktop Portable API Services and Samples Table 5-12 (Cont.) Motif Sample Files for the OpenVMS ___________________System__________________________________ Name_____________Description_______________________________ 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 ACMS Desktop 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 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____________________________________ 5.6 Installing the DIGITAL UNIX API and Sample Client Software The following sections describe how to install the DIGITAL UNIX API and sample client software on a DIGITAL UNIX desktop system. Installing ACMS Desktop Portable API Services and Samples 5-35 5.6.1 Installing the DIGITAL UNIX API To install the DIGITAL UNIX API, follow these instructions: 1. Create the API directory on the desktop system: > mkdir acmsdi The default network support in the DIGITAL UNIX ACMS Desktop API library is for TCP/IP. 2. Copy the appropriate files from the ACMS Desktop server system to your workstation. The following example copies the ACMS Desktop API library to /usr/lib/libacmsdi.a, so that you can refer to this library in your link command as '-lacmsdi'. You need superuser privileges to copy into the /usr/lib directory. You can alternatively copy the ACMS Desktop API library to the acmsdi (API) directory. If you do, you need to use the full path to the library in your link command, instead of using the '-lacmsdi' option. In the following instructions, words in italics represent user-specific input: server_ The node name of the OpenVMS system where node ACMS Desktop has been installed and from which files are copied username A valid user account on server_node password The password of the user account username 3. Use ftp to copy the following files: a. Copy the ACMS Desktop Header Presentation Procedure Stubs File and client library: 5-36 Installing ACMS Desktop Portable API Services and Samples > cd acmsdi > ftp server_node . . . ftp> cd "acmsdi$common" ftp> get acmsdi.h ftp> get ppstubs.c ftp> get forms.h ftp> get tdms.h ftp> binary ftp> get acmsdi$unix:libacmsdi.a libacmsdi.a ftp> get acmsdi$unix:net_tcpip.o net_tcpip.o ftp> get acmsdi$unix:net_decnet.o net_decnet.o ftp> bye b. Change the client library to use the DECnet transport (optional): > su # ar d libacmsdi.a net_tcpip.o # ar r libacmsdi.a net_decnet.o # ar t libacmsdi.a # ranlib libacmsdi.a Also edit the Makefile to add -ldnet to the link library list. c. Copy the ACMS Desktop client library to the syste_ directory: > su # cp libacmsdi.a /usr/lib/libacmsdi.a . . . 4. Update the archive file libacmsdi.a by entering the following command: # ranlib /usr/lib/libacmsdi.a 5. Exit superuser mode: # > Installing ACMS Desktop Portable API Services and Samples 5-37 5.6.1.1 API Files Added to the DIGITAL UNIX Desktop System Files listed in Table 5-13 are copied to the DIGITAL UNIX system during the installation of the ACMS Desktop services for DIGITAL UNIX software. Table_5-13_DIGITAL_UNIX_Files______________________________ Name_____________Description_______________________________ ACMSDI.H Include file for the ACMS Desktop API FORMS.H Include file for DECforms LIBACMSDI.A Library for ACMS Desktop API NET_TCPIP.O TCP/IP file for ACMS Desktop API NET_DECNET.O DECnet file for ACMS Desktop API PPSTUBS.C Presentation procedure and action routine stubs TDMS.H___________Include_file_for_TDMS_____________________ 5.6.2 Installing the Motif Sample Client on DIGITAL UNIX The DIGITAL UNIX Motif sample makefile and executables presume a TCP/IP transport. To install the Motif sample files on the DIGITAL UNIX system, perform the following steps: 1. Create a directory on the DIGITAL UNIX system to contain the sample files and move to that directory: > mkdir motif_avertz > cd motif_avertz 2. Use ftp to copy the load_motif shell to your client system: > ftp server_node . . . ftp> get acmsdi$examples_motif:load_motif.sh load_motif.sh ftp> bye 5-38 Installing ACMS Desktop Portable API Services and Samples 3. Run load_motif: > sh load_motif.sh Enter operating system ID (digital_unix, mips_ultrix, sco_unix):digital_unix Enter location of sample files on OpenVMS [acmsdi$examples_motif]: Use ftp or DECnet (f, d): f Enter Desktop Server Node: server_node Enter Username: username Enter Password: password 5.6.2.1 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 5.2.7.5 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. If errors occur in running the program, verify the following: o The m_avertz.uid file must be present 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. Installing ACMS Desktop Portable API Services and Samples 5-39 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). 5.6.2.2 Sample Files Added to the DIGITAL UNIX Desktop System All C language and header files (.c and .h), UIL files (.uil), UIL database files (.uid), executable files (.exe), and data files (.dat) listed in Table 5-14 are copied to the desktop system by the load_motif shell. Table_5-14_Motif_Sample_Files_for_the_DIGITAL_UNIX_System__ Name_____________Description_______________________________ Makefile Makefile for building the sample acmsdi.h Include file for the ACMS Desktop API forms.h Sample include file with DECforms status values help.txt Overview of AVERTZ user interface load_motif Command shell to download the Motif sample from the OpenVMS system m_avertz Motif sample executable file ~/m_avertz[1] Motif sample resource file m_avertz.c Entry point for the sample; manages the main window of the sample m_avertz.h AVERTZ header file; defines globals m_avertz.uid Run-time 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 [1]The_tilde_(~)_indicates_that_the_file_is_in_the_home____ directory. (continued on next page) 5-40 Installing ACMS Desktop Portable API Services and Samples Table 5-14 (Cont.) Motif Sample Files for the DIGITAL UNIX ___________________System__________________________________ Name_____________Description_______________________________ 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 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_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 ACMS Desktop 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 m_transceive.c Presentation procedure that dispatches to specific routines in m_avertzpp.c m_version.c Version-checking action routine stub (continued on next page) Installing ACMS Desktop Portable API Services and Samples 5-41 Table 5-14 (Cont.) Motif Sample Files for the DIGITAL UNIX ___________________System__________________________________ Name_____________Description_______________________________ 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____________________________________ 5.7 Installing the SCO UNIX API and Sample Client Software The following sections describe how to install the ACMS Desktop API and sample client software on a SCO UNIX desktop system. 5.7.1 Installing the SCO UNIX API To install the SCO UNIX API, follow these instructions: 1. Create the API directory on the desktop system: > mkdir acmsdi 5-42 Installing ACMS Desktop Portable API Services and Samples 2. Select the appropriate network object modules. To enable the desktop client program to communicate with the ACMS system, you must link your application programs with the proper network software. The choices for network software with ACMS Desktop for SCO UNIX are: o DECnet o TCP/IP The default network support in the ACMS Desktop API library is for DECnet. You can, however, configure the ACMS Desktop API library to use either DECnet or TCP/IP, by using one of the following object modules: o net_decnet.o (for DECnet support) o net_tcpip.o (for TCP/IP support) You can incorporate either of these object modules into the ACMS Desktop API library. 3. Copy the appropriate files from the ACMS Desktop server system to your workstation. The following example copies the ACMS Desktop API library to /usr/lib/libacmsdi.a, so that you can refer to this library in your link command as '-lacmsdi'. Superuser privileges are needed to copy into the /usr /lib directory. You can alternatively copy the ACMS Desktop API library to the acmsdi (API) directory. If you do, you must use the full path to the library in your link command, instead of using the '-lacmsdi' option. In the following instructions, words in italics represent user-specific input: server_ The node name of the OpenVMS system where node ACMS Desktop has been installed and from which files are copied username A valid user account on server_node password The password of the user account username Installing ACMS Desktop Portable API Services and Samples 5-43 Using DECnet to copy the API files: a. Copy the ACMS Desktop Header and Presentation Procedure Stubs Files: > cd acmsdi > dcp server_node/username/password::'acmsdi$common:*.*' . b. Copy the ACMS Desktop client library: > su # cd /usr/lib # dcp -i server_node/username/password::'acmsdi$sco:libacmsdi.a' libacmsdi.a ________________________ Note ________________________ Make sure that libacmsdi.a has full read privileges: # chmod +r libacmsdi.a ______________________________________________________ c. If you are configuring the ACMS Desktop library for TCP/IP, copy this file: # dcp -i server_node/username/password::'acmsdi$sco:net_tcpip.o' net_tcpip.o d. Exit superuser mode: # > Using ftp to copy the files: a. Copy the ACMS Desktop Header and Presentation Procedure Stubs File: > cd acmsdi > ftp server_node . . . ftp> get acmsdi$common:acmsdi.h ftp> get acmsdi$common:ppstubs.c ftp> get acmsdi$common:forms.h ftp> get acmsdi$common:tdms.h ftp> bye 5-44 Installing ACMS Desktop Portable API Services and Samples b. Copy the ACMS Desktop client library: > su # cd /usr/lib # ftp server_node . . . ftp> binary ftp> get acmsdi$sco:libacmsdi.a libacmsdi.a c. If you are configuring the ACMS Desktop library for TCP/IP, copy this file: ftp> binary ftp> get acmsdi$sco:net_tcpip.o net_tcpip.o d. Exit ftp: ftp> bye e. Exit superuser mode: # > 4. Configure the ACMS Desktop library for TCP/IP: The ACMS Desktop library is preconfigured for DECnet network access. To build applications that use TCP/IP as a transport, the library must be reconfigured before creating executable programs. Follow these steps to reconfigure the ACMS Desktop library for TCP/IP access: a. Enter superuser mode and move to the library directory: > su # cd /usr/lib b. Delete the DECnet transport access module: # ar d libacmsdi.a net_decnet.o c. Insert the TCP/IP transport access module into the library: # ar r libacmsdi.a net_tcpip.o # Installing ACMS Desktop Portable API Services and Samples 5-45 After these steps, you are ready to build ACMS Desktop applications that use TCP/IP as a transport. 5.7.1.1 API Files Added to the SCO UNIX Desktop System Files listed in Table 5-15 are copied to the SCO UNIX system during the installation of the ACMS Desktop services for SCO UNIX software. Table_5-15_SCO_UNIX_Files__________________________________ Name_____________Description_______________________________ ACMSDI.H Include file for the ACMS Desktop API FORMS.H Include file for DECforms LIBACMSDI.A Library for ACMS Desktop API NET_TCPIP.O Network support for TCP/IP PPSTUBS.C Presentation procedure and action routine stubs TDMS.H___________Include_file_for_TDMS_____________________ 5.7.2 Installing the Motif Sample Client on SCO UNIX The SCO UNIX sample makefile and executable files presume a TCP/IP transport. To install the Motif sample files on the SCO UNIX system, perform the following steps: 1. Create a directory on the SCO UNIX system to contain the sample files and move to that directory: > mkdir motif_avertz > cd motif_avertz 2. Use ftp or dcp to copy the load_motif shell to your client system. a. Using DECnet: > dcp server_node/username/password::'acmsdi$examples_motif::load_motif.sh' load_motif 5-46 Installing ACMS Desktop Portable API Services and Samples b. Using ftp: > ftp server_node . . . ftp> get acmsdi$examples_motif::load_motif.sh load_motif ftp> bye 3. Run load_motif: > sh load_motif.sh Enter operating system ID (digital_unix, mips_ultrix, sco_unix): sco_unix Enter location of sample files on OpenVMS [acmsdi$examples_motif]: Use ftp or DECnet (f, d): transport Enter Desktop Server Node: server_node Enter Username: username Enter Password: password Copying m_avertz resource file... Copying m_avertz.c... Copying m_avertz.h... . . . 5.7.2.1 Verifying the Motif Sample Installation on SCO UNIX Compile, link, and run the source code for the sample client program to verify your capability to build applications. You must configure the acmsdi library for TCP/IP. 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 5.2.7.5 to set up the sample application on the ACMS system. After you Installing ACMS Desktop Portable API Services and Samples 5-47 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. If errors occur in running the program, verify the following: o The m_avertz.uid file must be present 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). 5.7.2.2 Sample Files Added to the SCO UNIX Desktop System All C language and header files (.c and .h), UIL files (.uil), UIL database files (.uid), executable files (.exe), and data files (.dat) listed in Table 5-16 are copied to the desktop system by the load_motif shell. Table_5-16_Motif_Sample_Files_for_the_SCO_UNIX_System______ Name_____________Description_______________________________ Makefile Makefile for building the sample acmsdi.h Include file for the ACMS Desktop API forms.h Sample include file with DECforms status values load_motif Command shell to download the Motif sample from the OpenVMS system m_avertz Motif sample executable file ~/m_avertz[1] Motif sample resource file m_avertz.c Entry point for sample; manages the main window of the sample [1]The_tilde_(~)_indicates_that_the_file_is_in_the_home____ directory. (continued on next page) 5-48 Installing ACMS Desktop Portable API Services and Samples Table 5-16 (Cont.) Motif Sample Files for the SCO UNIX ___________________System__________________________________ Name_____________Description_______________________________ m_avertz.h AVERTZ header file; defines global names m_avertz.uid Run-time 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 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_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 Desktop routines and updates the user interface (continued on next page) Installing ACMS Desktop Portable API Services and Samples 5-49 Table 5-16 (Cont.) Motif Sample Files for the SCO UNIX ___________________System__________________________________ Name_____________Description_______________________________ m_session.h Header file for m_session.c m_sitelist.c Creates (using m_sites.dat) and manages 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 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____________________________________ 5.8 Installing the RISC ULTRIX API and Sample Client Software The following sections describe how to install the RISC ULTRIX API and sample client software on a RISC ULTRIX desktop system. 5.8.1 Installing the RISC ULTRIX API To install the RISC ULTRIX API, follow these instructions: 1. Create the API directory on the desktop system: > mkdir acmsdi 5-50 Installing ACMS Desktop Portable API Services and Samples 2. Select the appropriate network object modules. To enable the desktop client program to communicate with the ACMS system, you must link your application programs with the proper network software. The choices for network software with ACMS Desktop for RISC ULTRIX are: o DECnet o TCP/IP The default network support in the ACMS Desktop API library is for DECnet. You can, however, configure the ACMS Desktop API library to use either DECnet or TCP/IP, by using one of the following object modules: o net_decnet.o (for DECnet support) o net_tcpip.o (for TCP/IP support) You can incorporate either of these object modules into the ACMS Desktop API library. 3. Copy the appropriate files from the ACMS Desktop server system to your workstation. The following example copies the ACMS Desktop API library to /usr/lib/libacmsdi.a, so that you can refer to this library in your link command as '-lacmsdi'. You need superuser privileges to copy into the /usr/lib directory. ________________________ Note ________________________ If you are installing on an ULTRIX client system in a diskless client/server environment, /usr/lib is located in a special client area on the ULTRIX server system. This special client area is usually located in /dlenv0/root0.vax/usr/lib. Access this area by logging in to the ULTRIX server system directly. ______________________________________________________ You can alternatively copy the ACMS Desktop API library to the acmsdi (API) directory. If you do, you must use the full path to the library in your link command, instead of using the '-lacmsdi' option. Installing ACMS Desktop Portable API Services and Samples 5-51 The following instructions use italics to represent user-specific input: server_ The node name of the OpenVMS system where node ACMS Desktop has been installed and from which files are copied username A valid user account on server_node password The password of the user account username Using DECnet to copy the API files: a. Copy the ACMS Desktop Header and Presentation Procedure Stubs Files: > cd acmsdi > dcp server_node/username/password::'acmsdi$common:*.*' . b. Copy the ACMS Desktop client library: > su # cd /usr/lib # dcp -i server_node/username/password::'acmsdi$mips_ultrix:libacmsdi.a' libacmsdi.a c. If you are configuring the ACMS Desktop library for TCP/IP, copy this file: # dcp -i server_node/username/password::'acmsdi$mips_ultrix:net_tcpip.o' net_tcpip.o d. Exit superuser mode: # > Using ftp to copy the files: a. Copy the ACMS Desktop Header and Presentation Procedure Stubs File: > cd acmsdi > ftp server_node . . . ftp> get acmsdi$common:acmsdi.h ftp> get acmsdi$common:ppstubs.c ftp> get acmsdi$common:forms.h ftp> get acmsdi$common:tdms.h ftp> bye 5-52 Installing ACMS Desktop Portable API Services and Samples b. Copy the ACMS Desktop client library: > su # cd /usr/lib # ftp server_node . . . ftp> binary ftp> get acmsdi$mips_ultrix:libacmsdi.a libacmsdi.a c. If you are configuring the ACMS Desktop library for TCP/IP, copy this file: ftp> binary ftp> get acmsdi$mips_ultrix:net_tcpip.o net_tcpip.o d. Exit ftp: ftp> bye e. Exit superuser mode: # > 4. Configure the ACMS Desktop library for TCP/IP. The ACMS Desktop library is preconfigured for DECnet network access. To build applications that use TCP/IP as a transport, the library must be reconfigured before creating executable programs. The following steps are necessary to reconfigure the ACMS Desktop library for TCP/IP access: a. Enter superuser mode and move to the library directory: > su # cd /usr/lib b. Delete the DECnet transport access module: # ar d libacmsdi.a net_decnet.o Installing ACMS Desktop Portable API Services and Samples 5-53 c. Insert the TCP/IP transport access module into the library: # ar r libacmsdi.a net_tcpip.o # ar t libacmsdi.a # ranlib libacmsdi.a # After these steps, you are ready to build ACMS Desktop applications that use TCP/IP as a transport. 5.8.1.1 API Files Added to the RISC ULTRIX Desktop System Files listed in Table 5-17 are copied to the RISC ULTRIX system during the installation of the ACMS Desktop services for RISC ULTRIX software. Table_5-17_RISC_ULTRIX_Files_______________________________ Name_____________Description_______________________________ ACMSDI.H Include file for the ACMS Desktop API FORMS.H Include file for DECforms LIBACMSDI.A Library for ACMS Desktop API NET_TCPIP.O Network support for TCP/IP PPSTUBS.C Presentation procedure and action routine stubs TDMS.H___________Include_file_for_TDMS_____________________ 5.8.2 Installing the Motif Sample Client on RISC ULTRIX The RISC ULTRIX Motif sample makefile and executable files presume a DECnet transport. To install the Motif sample files on the RISC ULTRIX system, perform the following steps: 1. Create a directory on the RISC ULTRIX system to contain the sample files and move to that directory: > mkdir motif_avertz > cd motif_avertz 5-54 Installing ACMS Desktop Portable API Services and Samples 2. Use ftp or dcp to copy the load_motif shell to your client system. a. Using DECnet: > dcp server_node/username/password::'acmsdi$examples_motif::load_motif.sh' load_motif b. Using ftp: > ftp server_node . . . ftp> get acmsdi$examples_motif::load_motif.sh load_motif ftp> bye 3. Run load_motif: > sh load_motif.sh Enter operating system ID (mips_ultrix, sco_unix, vax_ultrix): mips_ultrix Enter location of sample files on OpenVMS [acmsdi$examples_motif]: Use ftp or DECnet (f, d): transport Enter Desktop Server Node: server_node Enter Username: username Enter Password: password Copying m_avertz resource file... Copying m_avertz.c... Copying m_avertz.h... . . . 5.8.2.1 Verifying the Motif Sample Installation on RISC ULTRIX 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 Installing ACMS Desktop Portable API Services and Samples 5-55 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 5.2.7.5 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. If errors occur in running the program, verify the following: o The m_avertz.uid file must be present 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). 5.8.2.2 Sample Files Added to the RISC ULTRIX Desktop System All C language and header files (.c and .h), UIL files (.uil), UIL database files (.uid), executable files (.exe), and data files (.dat) listed in Table 5-18 are copied to the desktop system by the load_motif shell. Table_5-18_Motif_Sample_Files_for_the_RISC_ULTRIX_System___ Name_____________Description_______________________________ Makefile Makefile for building the sample acmsdi.h Include file for the ACMS Desktop API forms.h Sample include file with DECforms status values help.txt Overview of the AVERTZ user interface load_motif Command shell to download the Motif sample from the OpenVMS system (continued on next page) 5-56 Installing ACMS Desktop Portable API Services and Samples Table 5-18 (Cont.) Motif Sample Files for the RISC ULTRIX ___________________System__________________________________ Name_____________Description_______________________________ m_avertz Motif sample executable file ~/m_avertz[1] Motif sample resource file 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.uid Run-time 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 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_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 [1]The_tilde_(~)_indicates_that_the_file_is_in_the_home____ directory. (continued on next page) Installing ACMS Desktop Portable API Services and Samples 5-57 Table 5-18 (Cont.) Motif Sample Files for the RISC ULTRIX ___________________System__________________________________ Name_____________Description_______________________________ 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 ACMS Desktop 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 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____________________________________ 5.9 Installation Errors Errors can occur during the installation, if any of the following conditions exists when installing: o For the DOS API-DIGITAL ACMS Desktop server system ACMSDI$MSDOS, ACMSDI$EXAMPLES ACMSDI$EXAMPLES_MSDOS, or ACMSDI$EXAMPLES_MSWINDOWS directory is protected against read access. o For the OpenVMS API-DIGITAL ACMS Desktop server system ACMSDI$COMMON, the ACMSDI$EXAMPLES_ACMS directory, the ACMSDI$EXAMPLES_MOTIF directory, or the ACMSDI$EXAMPLES_ MOTIF_VMS directory is protected against read access. 5-58 Installing ACMS Desktop Portable API Services and Samples o For the RISC ULTRIX API-ACMS Desktop server system ACMSDI$COMMON, ACMSDI$MIPS_ULTRIX, ACMSDI$EXAMPLES_ACMS, ACMSDI$EXAMPLES_MOTIF, or ACMSDI$EXAMPLES_MOTIF_MIPS_ULTRIX directory is protected against read access. o For the SCO UNIX API-DIGITAL ACMS Desktop server system ACMSDI$COMMON, ACMSDI$SCO, ACMSDI$EXAMPLES, ACMSDI$EXAMPLES_MOTIF, or ACMSDI$EXAMPLES_MOTIF_SCO directory is protected against read access. o DIGITAL ACMS Desktop server system does not have the DOS or the MS-Windows sample software installed. o DIGITAL ACMS Desktop server node does not have the network software functioning correctly. o DIGITAL ACMS Desktop server node is unavailable. o DIGITAL ACMS Desktop server node name is invalid. o DIGITAL ACMS Desktop server node is not running the DIGITAL ACMS system. o DIGITAL ACMS Desktop server node has not invoked ACMSDI$STARTUP.COM and ACMS/START SYSTEM. o DIGITAL ACMS Desktop server software is not installed or is improperly installed. o DIGITAL ACMS Desktop server IVP failed. o ACMS Desktop client program node does not have the network software functioning correctly. o ACMS Desktop client program node does not have the network in the directory search path. o ACMS Desktop client program node has insufficient disk space. Installing ACMS Desktop Portable API Services and Samples 5-59 6 _________________________________________________________________ Installing the DIGITAL ACMS Desktop Macintosh System and Sample Software This chapter discusses the installation of the ACMS Desktop services for Macintosh software. After you install the DIGITAL ACMS Desktop software on the DIGITAL OpenVMS system, you can install the Macintosh software on individual desktop systems. 6.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 ACMS Desktop 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 ACMS Desktop 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 ACMS Desktop client applications on the target Macintosh. This option does not include the various examples that illustrate the use of the ACMS Desktop API. 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. the DIGITAL ACMS Desktop Macintosh System and Sample Software 6-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 ACMS Desktop API, 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 ACMS Desktop API, 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 either the Run-Time Services or the System Services. You must install the Run-Time Services in order to install the Examples. 6.2 Preparing to Install the Macintosh Software This section discusses the preparations and requirements for installing the ACMS Desktop services for Macintosh software. 6.2.1 Prerequisite Software for Macintosh Systems Before you install the software, do the following: 1. Install DIGITAL ACMS Desktop software on the OpenVMS system running the DIGITAL ACMS Desktop server. 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. 6-2 Installing the DIGITAL ACMS Desktop Macintosh System and Sample Software 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. 6.2.2 Installation Procedure Requirements The following sections discuss the requirements for installing the Macintosh client services software. 6.2.2.1 Time Installing the ACMS Desktop services for Macintosh software on a Macintosh computer with a hard disk takes approximately 10 minutes, depending on the hardware configuration, the network connection, and the installation options chosen. the DIGITAL ACMS Desktop Macintosh System and Sample Software 6-3 6.2.2.2 Disk Space Installing the ACMS Desktop services for Macintosh software requires approximately 3000 blocks on your OpenVMS system plus an additional 1700 blocks if you choose to use a VAXshare volume as the source from which the client software can be copied to your Macintosh. The required disk space on your Macintosh depends on the installation option you choose, as listed in Table 6-1. Table_6-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_______________________________________________ 6.2.2.3 Installation Procedure Resources Before you start the installation procedure, obtain the following: o Valid account (user name and password) with privileges on the OpenVMS system on which the DIGITAL ACMS Desktop server is installed. The SYSTEM account is recommended. o If you choose to use a VAXshare volume as the source from which the client software can be copied to your Macintosh, the name of the disk device on the OpenVMS system on which the VAXshare volume is to be created. o Sufficient disk space to load the software. 6-4 Installing the DIGITAL ACMS Desktop Macintosh System and Sample Software 6.3 Installing the Macintosh Software This section describes how to install the ACMS Desktop services for Macintosh software on a Macintosh system. The procedures involve activities on both the OpenVMS system and the Macintosh system. 6.3.1 Copying the ACMS Desktop Installer to the Macintosh All the files that comprise the ACMS Desktop Macintosh client software are compacted into a single installation file, ACMS_DESKTOP.INSTALLER. The installation procedure includes the following steps: 1. Copy ACMS_DESKTOP.INSTALLER to the target Macintosh. 2. Double click on the installer file. 3. Following the instructions that are displayed. There are two methods for copying the installer to your Macintosh, one of which requires the use of a VAXshare volume. The other method does not require the use of a VAXshare volume, and may not require the use of any PATHWORKS services. Choose the method that is most convenient for you. If you choose to use a VAXshare volume, see Section 6.3.1.1, otherwise, go to Section 6.3.1.2. 6.3.1.1 Copying the Installer Using a VAXshare Volume To load the Macintosh files on the VAXshare volume on the OpenVMS system, use the SYSTEM account, or some other account with the appropriate privileges to execute a command procedure as follows. 1. Enter the following command: $ @ACMSDI$MACINTOSH:CREATE_MACINTOSH_SYSTEM_VOLUME The command file displays several prompts. 2. Supply the name of the disk device for the VAXshare volume: Are you prepared to supply the device name? [Y/N]: the DIGITAL ACMS Desktop Macintosh System and Sample Software 6-5 Answer NO to exit the procedure. Answer YES to display the following prompt: VAXshare volume device name: Type the name of the disk on which the VAXshare volume is to be created. Proceed to the next step. a. If you enter an invalid device name, the following message is displayed: %SYSTEM-W-NOSUCHDEV, no such device available The procedure terminates. b. If the procedure finds a volume named ACMSDI- Macintosh V2.3, the following is displayed: %MSA-E-VOLEXISTS, volume already exists Do you wish to continue? [Y/N]: To preserve the current volume, answer NO. The procedure exits. Save the files and restart the procedure. To delete the existing volume and its contents, answer YES. In PATHWORKS for Macintosh Version 1.0, the procedure shuts down all file servers on the node and displays a message or messages indicating that this is happening: WARNING: About to delete old version of VAXshare Volume ACMSDI-Macintosh V2.3. To do so it will be necessary to temporarily stop all file servers on this node. OK to proceed? [Y/N]: Answer NO to terminate the procedure. Answer YES to shut down the file server or servers active on the current node (if any, and if PATHWORKS for Macintosh Version 1.0 is running) and delete files in the VAXshare volume: 6-6 Installing the DIGITAL ACMS Desktop Macintosh System and Sample Software . . . Deleting old files... . . . Old files deleted... %MSA-I-STARTING . . . The procedure restarts all file servers on the node, if you are running PATHWORKS for Macintosh Version 1.0. ________________________ Note ________________________ If you are using PATHWORKS for Macintosh Version 1.1 or later, the file servers are not shut down. ______________________________________________________ 3. The procedure creates the new VAXshare volume and copies the files: Creating VAXshare Volume ACMSDI-Macintosh V2.3... . . . Loading ACMS Desktop system files... . . . System files loaded... VAXshare volume installation successfully completed The VAXshare volume has the appropriate files. 4. From the Macintosh, open the Chooser. When the Chooser window appears, follow these steps: a. Click on the AppleShare icon. the DIGITAL ACMS Desktop Macintosh System and Sample Software 6-7 b. Select the file server to use. If UAM is installed, a dialog box appears to let you select a log-in method. Select a log-in method. c. Enter a user name and password and click on the OK button. d. Select the "ACMSDI-Macintosh V2.3" VAXshare volume, click on the OK button, and close the Chooser. 5. Open the "ACMSDI-Macintosh V2.3" VAXshare volume by double clicking on its icon. 6. Open folders contained in the VAXshare volume until you see a READ ME file and the ACMS_DESKTOP.INSTALLER file. The READ ME file contains information about using the ACMS_DESKTOP.INSTALLER file. Take time to read that file now. 7. Drag the ACMS_DESKTOP.INSTALLER file to the hard disk on your Macintosh. 8. Proceed to Section 6.3.2. 6.3.1.2 Copying the Installer Without Using a VAXshare Volume This section describes how to copy the ACMS_ DESKTOP.INSTALLER file to your Macintosh without using a VAXshare volume. If you prefer to use a VAXshare volume, follow the steps in Section 6.3.1.1. There are several tools available for copying files from your OpenVMS system to your Macintosh, for example: o XMODEM file transfer utility running on your OpenVMS system in conjunction with MacTerminal running on your Macintosh o NetCopy utility provided by PATHWORKS After you install ACMS Desktop on the host OpenVMS system, the ACMS_DESKTOP.INSTALLER file is located in the ACMSDI$MACINTOSH directory. Using a file transfer facility, copy the ACMS_DESKTOP.INSTALLER file from the ACMSDI$MACINTOSH directory to your Macintosh. 6-8 Installing the DIGITAL ACMS Desktop Macintosh System and Sample Software The file on the OpenVMS system is 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 ACMS_DESKTOP.INSTALLER to standard Macintosh format after you copy it. After you have successfully copied the ACMS_ DESKTOP.INSTALLER file to your Macintosh, proceed to Section 6.3.2. 6.3.2 Running the ACMS Desktop Macintosh Installer This section assumes that you have successfully moved the ACMS_DESKTOP.INSTALLER file to the hard disk on your Macintosh using one of the two methods described in Section 6.3.1.1 and Section 6.3.1.2. The ACMS_DESKTOP.INSTALLER file is a self-extracting file containing all the ACMS Desktop Macintosh client 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 ACMS_DESKTOP.INSTALLER file. 2. A window appears that identifies the product as ACMS Desktop 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 ACMS Desktop client applications and the host ACMS Desktop server. the DIGITAL ACMS Desktop Macintosh System and Sample Software 6-9 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 on the Install button now. If you want to examine additional options, click on the Custom button and proceed to step 5. 5. After clicking on the Custom button, a window appears with six installation options. Text appears to describe each option and how much disk storage it requires. Section 6.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. 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. 6-10 Installing the DIGITAL ACMS Desktop Macintosh System and Sample Software - Run-Time Services and Calypso: This option installs the basic software needed for run-time support and the Calypso software. Development aids and Examples are not installed. This window provides three choices. - Standard button: Allows you to return to the standard installation window. - Quit button: Allows you to cancel the installation at this point; nothing is installed. - 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 the Standard or Custom installation window causes a window to appear from which you can select the location to place the folder "ACMS Desktop 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. the DIGITAL ACMS Desktop Macintosh System and Sample Software 6-11 A _________________________________________________________________ Sample Installations This appendix contains two examples of installing the DIGITAL ACMS Desktop software. Section A.1 is an example of installing ACMS Desktop on an DIGITAL OpenVMS VAX system. Section A.2 is an example of installing ACMS Desktop on an DIGITAL OpenVMS Alpha system. A.1 OpenVMS VAX Sample Software Installation This section contains an example of installing the DIGITAL ACMS Desktop software on an OpenVMS VAX Version 5.5-2 system. Welcome to OpenVMS VAX V5.5-2 Username: SYSTEM Password: Welcome to OpenVMS VAX V5.5-2 Last interactive login on February, 29-MAR-1997 10:19 Last non-interactive login on Wednesday, 09-FEB-1997 14:27 $ @SYS$STARTUP:ACMSDI$SHUTDOWN $ set default sys$update $ @SYS$UPDATE:VMSINSTAL ACMSDI MUA0: OPTIONS N OpenVMS VAX Software Product Installation Procedure V5.5-2 It is 29-MAR-1997 at 09:32. Enter a question mark (?) at any time for help. Sample Installations A-1 %VMSINSTAL-W-NOTSYSTEM, You are not logged in to the SYSTEM account. %VMSINSTAL-W-ACTIVE, The following processes are still active: NETBIOS NBNS PCFS_SERVER NOTES$00A4_1* _RTA2: * Do you want to continue anyway [NO]? y * Are you satisfied with the backup of your system disk [YES]? y The following products will be processed: ACMSDI V2.3 Beginning installation of ACMSDI V2.3 at 09:32 %VMSINSTAL-I-RESTORE, Restoring product save set A ... %VMSINSTAL-I-RELMOVED, Product's release notes have been moved to SYS$HELP. © Digital Equipment Corporation. 1997. All Rights Reserved. The installation of the ACMS Desktop system software requires 18000 blocks peak and 3500 blocks net. * Do you want to install the ACMS Desktop system software [YES]? y The Installation Verification Procedure (IVP) may be run at a later time by invoking the .COM file: @sys$test:acmsdi$ivp * Do you want to run the IVP after the installation [YES]? y * Do you want to purge files replaced by this installation [YES]? y * Do you want to install any of the ACMS Desktop samples [YES]? y The installation of the ACMS Desktop AVERTZ Application requires 4700 blocks. * Do you want to install the AVERTZ application [YES]? y The installation of the ACMS Desktop MS-DOS sample requires 650 blocks. * Do you want to install the MS-DOS sample [YES]? y The installation of the ACMS Desktop Windows samples requires 1300 blocks. * Do you want to install the Windows samples [YES]? y The installation of the ACMS Desktop Macintosh sample requires 40 blocks. A-2 Sample Installations * Do you want to install the Macintosh sample [YES]? y The installation of the ACMS Desktop Motif sample requires 5250 blocks. * Do you want to install the Motif sample [YES]? y You have made the following SAMPLE installation choices: COMMON FILES 150 BLOCKS AVERTZ APPLICATION 4700 BLOCKS MS-DOS SAMPLE 650 BLOCKS WINDOWS SAMPLES 1300 BLOCKS MACINTOSH SAMPLE 40 BLOCKS MOTIF SAMPLE 5250 BLOCKS ========================================== TOTAL SIZE: 12090 BLOCKS * Are you satisfied with your selections [YES]? y Looking up the Product Authorization Information. Product: DESKTOP-ACMS Producer: DEC Version: 2.3 Release Date: 07-MAY-1997 Sample Installations A-3 * Does this product have an authorization key registered and loaded? y %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 %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.COMMON]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.JCNVWIN.WIN95]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.JCNVWIN.WIN31]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.MSDOS]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.WIN95]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.NT_I86]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.NT_ALPHA]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.MACINTOSH]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.VMS]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.VMS_ALPHA]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.SCO]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.MIPS_ULTRIX]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.UNIX]. %VMSINSTAL-I-RESTORE, Restoring product save set B ... %VMSINSTAL-I-RESTORE, Restoring product save set C ... %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MSDOS]. %VMSINSTAL-I-RESTORE, Restoring product save set D ... %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MSWINDOWS]. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MSWINDOWS.MSW31]. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MSWINDOWS.NT_I86]. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MSWINDOWS.NT_ALPHA]. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MSWINDOWS.WIN95]. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MSWINDOWS.VB]. %VMSINSTAL-I-RESTORE, Restoring product save set E ... %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MACINTOSH]. %VMSINSTAL-I-RESTORE, Restoring product save set F ... %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MOTIF]. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MOTIF.VMS]. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MOTIF.VMS_ALPHA]. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MOTIF.SCO]. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MOTIF.MIPS_ULTRIX]. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MOTIF.UNIX]. %VMSINSTAL-I-RESTORE, Restoring product save set G ... %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... %RUN-S-PROC_ID, identification of created process is 23000CB4 Starting Server ACMSDI$SERVER The ACMS Desktop T2.3-00 IVP completed successfully A-4 Sample Installations Installation of ACMSDI V2.3 completed at 09:47 VMSINSTAL procedure done at 09:47 $ LOGOUT SYSTEM logged out at 29-MAR-1997 9:47:12.28 A.2 OpenVMS Alpha Sample Software Installation This section contains an example of installing the DIGITAL ACMS Desktop software on an OpenVMS Alpha Version 6.1 system. $ @SYS$UPDATE:VMSINSTAL ACMSDI USER3$:[DESKTOP] OpenVMS ALPHA Software Product Installation Procedure V6.1 It is 29-MAR-1997 at 09:32. Enter a question mark (?) at any time for help. %VMSINSTAL-W-ACTIVE, The following processes are still active: DECW$MWM _FTA5: * Do you want to continue anyway [NO]? YES * Are you satisfied with the backup of your system disk [YES]? YES The following products will be processed: ACMSDI V2.3 Beginning installation of ACMSDI V2.3 at 20:19 %VMSINSTAL-I-RESTORE, Restoring product save set A ... %VMSINSTAL-I-RELMOVED, Product's release notes have been moved to SYS$HELP. © Digital Equipment Corporation. 1997. All Rights Reserved. * Do you want to purge files replaced by this installation [YES]? YES The installation of the ACMS Desktop system software requires 18000 blocks peak and 3500 blocks net. * Do you wish to install the ACMS Desktop system software [YES]?) YES The Installation Verification Procedure (IVP) may be run at a later time by invoking the .COM file: @sys$test:acmsdi$ivp * Do you want to run the IVP after the installation [YES]? YES Sample Installations A-5 * Do you wish to install any of the ACMS Desktop samples at this time [YES]? YES The installation of the ACMS Desktop AVERTZ Application requires 4700 blocks. * Do you wish to install the AVERTZ application [YES]? YES The installation of the ACMS Desktop MS-DOS sample requires 650 blocks. * Do you wish to install the MS-DOS sample [YES]? ) YES The installation of the ACMS Desktop Windows samples requires 1300 blocks. * Do you wish to install the Windows samples [YES]? YES The installation of the ACMS Desktop Macintosh sample requires 40 blocks. * Do you wish to install the Macintosh sample [YES]? YES The installation of the ACMS Desktop Motif sample requires 5250 blocks. * Do you wish to install the Motif sample [YES]? YES You have made the following sample installation choices: COMMON FILES 150 BLOCKS AVERTZ APPLICATION 4700 BLOCKS MS-DOS SAMPLE 650 BLOCKS MICROSOFT WINDOWS & NT SAMPLE 1300 BLOCKS MACINTOSH SAMPLE 40 BLOCKS MOTIF SAMPLE 5250 BLOCKS ========================================== TOTAL SIZE: 12090 BLOCKS * Are you satisfied with your selections [YES]? YES Looking up the Product Authorization Information. A-6 Sample Installations Product: DESKTOP-ACMS Producer: DEC Version: 2.3 Release Date: 07-MAY-1997 * Does this product have an authorization key registered and loaded? YES %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 %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.COMMON]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.JCNVWIN.WIN95]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.JCNVWIN.WIN31]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.MSDOS]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.WIN95]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.NT_I86]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.NT_ALPHA]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.MACINTOSH]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.VMS]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.VMS_ALPHA]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.SCO]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.MIPS_ULTRIX]. %VMSINSTAL-I-SYSDIR, This product creates system directory [ACMSDI.UNIX]. %VMSINSTAL-I-RESTORE, Restoring product save set B ... %VMSINSTAL-I-RESTORE, Restoring product save set C ... %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MSDOS]. %VMSINSTAL-I-RESTORE, Restoring product save set D ... %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MSWINDOWS]. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MSWINDOWS.MSW31]. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MSWINDOWS.NT_I86]. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MSWINDOWS.NT_ALPHA]. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MSWINDOWS.WIN95]. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MSWINDOWS.VB]. %VMSINSTAL-I-RESTORE, Restoring product save set E ... %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MACINTOSH]. %VMSINSTAL-I-RESTORE, Restoring product save set F ... %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MOTIF]. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MOTIF.VMS]. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MOTIF.VMS_ALPHA]. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MOTIF.SCO]. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MOTIF.MIPS_ULTRIX]. %VMSINSTAL-I-SYSDIR, This product creates system directory [SYSHLP.EXAMPLES.ACMSDI.MOTIF.UNIX]. %VMSINSTAL-I-RESTORE, Restoring product save set G ... %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... %RUN-S-PROC_ID, identification of created process is 00000176 Starting Server ACMSDI$SERVER Sample Installations A-7 The ACMS Desktop V2.3-00 IVP completed successfully Installation of ACMSDI V2.3 completed at 09:47 Adding history entry in VMI$ROOT:[SYSUPD]VMSINSTAL.HISTORY Creating installation data file: VMI$ROOT:[SYSUPD]ACMSDI020.VMI_DATA VMSINSTAL procedure done at 09:47 $ LOGOUT SYSTEM logged out at 29-MAR-1997 09:47:43.56 A-8 Sample Installations _________________________________________________________________ Index A______________________________ F______________________________ API installation requirements, Files 5-6 API AVERTZ added to DIGITAL UNIX access control list, 5-17 system, 5-38 application notes, 5-16 added to OpenVMS Desktop rebuilding, 5-18 system, 5-31 user name quota values, 5-17 added to RISC ULTRIX C system, 5-54 _______________________________ added to SCO UNIX system, Copying the Installer 5-46 with VAXshare volume, 6-5 installed on system, 2-1 without a VAXshare volume, sample 6-8 added to DIGITAL UNIX system, 5-40 D______________________________ added to nonWindows system Device name , 5-10 installation, 2-6 added to OpenVMS desktop Disk space, 1-4, 6-4 system, 5-33 added to RISC ULTRIX E______________________________ system, 5-56 Editing added to SCO UNIX system, system shutdown file, 3-3 5-48 system startup file, 3-1 added to Windows system, Examples option, 6-2 5-19 Forced Nonblocking Visual Basic Sample Files, 5-23, 5-25 Index-1 Installing PowerBuilder sample I______________________________ , 5-21 Installation Installing Windows 95 sample, aborting, 2-3 5-27 device name for, 2-6 Installing Windows NT sample, invoking, 2-5 5-29 option parameter, 2-6 IVP procedures for, 2-1 error recovery, 4-2 questions, 2-7 operations performed by, 4-1 tasks following, 3-1 requirements to run, 4-1 Installation errors, 5-58 running independently, 4-1 Installing steps to run, 4-2 DIGITAL UNIX API, 5-36 DIGITAL UNIX Motif sample, L______________________________ 5-38 Logical name DOS API, 5-7 added to system, 2-2 DOS link library options, 5-8 M______________________________ DOS memory options, 5-8 Macintosh client installation DOS sample, 5-7 DOS Sample Application, 5-8 requirements, 6-3 DOS transport options, 5-8 Macintosh installation options OpenVMS API, 5-29 , 6-1 OpenVMS Motif sample, 5-31 RISC ULTRIX API, 5-50 O______________________________ RISC ULTRIX Motif sample, Operating system components, 5-54 1-1 SCO UNIX API, 5-42 OPTIONS N SCO UNIX Motif sample, 5-46 installation parameter, 2-6 Visual Basic Samples, 5-22 Windows 95 API, 5-25 P Windows API, 5-7 _______________________________ Windows link library options, Performing cluster procedures, 5-11 3-3 Windows NT API, 5-27 PowerBuilder, 5-21 Windows NT client software, Preparing to install Macintosh 5-27 software, 6-2 Windows sample, 5-7 Prerequisite software Windows Sample Application, API, 5-2 5-12 sample application, 5-5 Windows transport options, Prerequisite software for 5-11 Macintosh systems, 6-2 Privileges, 1-3 Index-2 Product name of, 2-5 T______________________________ Time to install, 5-6, 6-3 R______________________________ Release Notes, 1-5 V______________________________ accessing, 2-1 Verifying Reporting problems, 3-5 DIGITAL UNIX sample, 5-39 Resources, 5-6 nonWindows sample, 5-9 Run-Time Services option, 6-1 OpenVMS Motif sample, 5-32 Running the Installer, 6-9 RISC ULTRIX sample, 5-55 SCO UNIX sample, 5-47 S______________________________ Windows sample, 5-13 Sample Visual Basic AVERTZ Sample DIGITAL UNIX, 5-38 Verifying installation, 5-23 OpenVMS, 5-31 VMSINSTAL RISC ULTRIX, 5-54 requirements, 1-5 SCO UNIX, 5-46 syntax, 2-5 Sample application setup, 5-17 VR_DA_APPL Self Extracting Archives, 5-7 sample application, 5-16 System Services option, 6-1 VR_DA_BLD_MMS.COM parameters, 5-19 Index-3