ACMS_Desktop_for_OSF/1________________________ Installation Guide Order Number: AA-Q19ZB-TE December 1994 This guide describes how to install ACMS Desktop on an AXP (Alpha AXP architecture) system running the DEC OSF/1 AXP operating system. Revision/Update Information: This is a revised manual. Operating System & Version: DEC OSF/1 Version 3.0 or higher. Future maintenance releases may require higher versions. Software Version: ACMS Desktop for OSF /1 Version 2.1 Digital Equipment Corporation Maynard, Massachusetts __________________________________________________________ First Printing, December 1993 Second Printing, December 1994 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 1993, 1994. All Rights Reserved. The postpaid Reader's Comments forms at the end of this document request your critical evaluation to assist in preparing future documentation. The following are trademarks of Digital Equipment Corporation: ACMS Desktop, ACMSxp, AXP, Bookreader, DEC, DEC C, DECwindows, Digital, PATHWORKS, and the DIGITAL logo. The following are third-party trademarks: 4D, 4D Externals, and 4th Dimension are registered trademarks or trademarks of ACI and ACIUS, Inc. Macintosh is a registered trademark of Apple Computer, Inc. Microsoft, Microsoft C, Microsoft COBOL, Microsoft Windows, MS, MS-DOS, and Visual Basic are registerd trademarks of Microsoft Corporation. Motif, OSF and OSF/1 are registered trademarks of the Open Software Foundation, Inc. All other trademarks and registered trademarks are the property of their respective holders. This document is available on CD-ROM. This document was prepared using VAX DOCUMENT Version 2.1. ________________________________________________________________ Contents Preface.................................................. vii Part I ACMS Desktop Software 1 Preparing for ACMS Desktop Installation 1.1 Reading the Online Release Notes............. 1-1 1.2 Registering Your Software License............ 1-1 1.3 Checking the Software Distribution Kit....... 1-2 1.4 Checking Installation Procedure Requirements................................. 1-2 1.4.1 Checking Login Privileges................ 1-2 1.4.2 Checking Hardware Requirements........... 1-3 1.4.3 Checking Software Requirements........... 1-3 1.4.4 Determining Which Subsets to Load........ 1-4 1.4.5 Determining Disk Space Requirements...... 1-4 1.4.5.1 Checking Current Disk Space............ 1-5 1.4.5.2 Increasing Disk Space by Using Alternative Disks ..................... 1-6 1.5 Installing from Media or Using RIS........... 1-7 1.6 Backing Up Your System Disk.................. 1-7 1.7 Stopping the Installation.................... 1-7 2 Installing ACMS Desktop 2.1 Pre-Installation Work........................ 2-1 2.2 Using CD-ROM Consolidated Distribution Media........................................ 2-1 2.3 Using an RIS Distribution Area .............. 2-2 2.4 Responding to Installation Procedure Prompts...................................... 2-3 iii 2.4.1 Selecting Subsets........................ 2-3 2.4.2 Monitoring Displays During the Subset Loading Process.......................... 2-4 3 After Installation 3.1 Running the Installation Verification Procedure ................................... 3-1 3.2 Deleting ACMS Desktop from Your System....... 3-1 3.3 Displaying Documentation from CD-ROM......... 3-2 4 Running the ACMS Desktop for OSF/1 IVP 4.1 IVP Operations............................... 4-1 4.2 Running the IVP Independently................ 4-1 4.2.1 IVP Steps................................ 4-1 4.2.2 IVP Error Recovery....................... 4-3 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-3 5.1.2.1 Time................................... 5-3 5.1.2.2 Disk Space............................. 5-3 5.1.2.3 Resources.............................. 5-4 5.2 Installing the DOS and Windows APIs.......... 5-5 5.2.1 Installing the DOS or Windows API and Sample Client Software................... 5-5 5.2.1.1 Troubleshooting the DOS and Windows Postinstallation Procedure............. 5-7 5.2.2 Verifying the NonWindows Sample Installation............................. 5-7 5.2.2.1 NonWindows Sample Files Added to the System................................. 5-8 iv 5.2.3 Verifying the Windows Sample Installation............................. 5-9 5.2.3.1 Windows Sample Files Added to the System................................. 5-13 5.2.4 Installing the Visual Basic Sample Client................................... 5-15 5.2.4.1 Copying the Visual Basic Sample Files.................................. 5-16 5.2.4.2 Verifying the Visual Basic Sample Installation........................... 5-17 5.2.4.3 Visual Basic Sample Files Added to the System................................. 5-17 5.3 Installing the OSF/1 API and Sample Client Software..................................... 5-18 5.3.1 Installing the OSF/1 API................. 5-18 5.3.1.1 API Files Added to the OSF/1 Desktop System................................. 5-20 5.3.2 Installing the Motif Sample Client on OSF/1.................................... 5-20 5.3.2.1 Verifying the Motif Sample Installation on OSF/1............................... 5-21 5.3.2.2 Sample Files Added to the OSF/1 Desktop System................................. 5-22 5.4 Installation Errors.......................... 5-24 6 Installing the 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-2 6.2.2.1 Time................................... 6-2 6.2.2.2 Disk Space............................. 6-3 6.2.2.3 Installation Procedure Resources....... 6-3 6.3 Installing the Macintosh Software............ 6-3 6.3.1 Copying the ACMS Desktop Installer to the Macintosh................................ 6-3 6.3.1.1 Copying the Installer.................. 6-4 6.3.2 Running the ACMS Desktop Macintosh Installer................................ 6-4 v A Sample Listings A.1 Sample ACMS Desktop Installation ............ A-1 A.2 Sample Installation Verification Procedure ............................................. A-2 B Setting Up the Sample Application C Recovering from Errors C.1 Failures During Product Installation ........ C-1 C.2 Failures During Product Use.................. C-2 Index Examples 5-1 Sample startup.bat File.................. 5-13 5-2 Sample config.sys File................... 5-13 Tables 1 Conventions Used in this Guide .......... ix 5-1 Installing ACMS Desktop Services......... 5-1 5-2 Products Required for APIs............... 5-2 5-3 Sample Application Product Dependencies............................. 5-3 5-4 API Installation Timetable............... 5-3 5-5 API and Library Disk Space Requirements............................. 5-4 5-6 NonWindows Sample Files.................. 5-8 5-7 Windows Sample Files..................... 5-13 5-8 Visual Basic Sample Files................ 5-17 5-9 OSF/1 Files.............................. 5-20 5-10 Motif Sample Files for the OSF/1 System................................... 5-23 6-1 Macintosh Disk Space Requirements........ 6-3 vi ________________________________________________________________ Preface This installation procedure creates ACMS Desktop file systems subordinate to the /usr/opt and /var/opt directories. It creates links to those file systems under the following: o /usr/bin o /usr/etc o /usr/examples o /usr/man o /usr/nls o /var Keep this guide with your distribution kit. You will need it to install maintenance updates or to reinstall ACMS Desktop for any other reason. Intended Audience This guide is intended for system managers who install ACMS Desktop. Manual Structure This manual has the following chapters and appendixes: __________________________________________________________ Part_I______ACMS_Desktop_Software_________________________ Chapter 1 Explains how to prepare yourself and your system for installing ACMS Desktop software. vii __________________________________________________________ Part_I______ACMS_Desktop_Software_________________________ Chapter 2 Describes how to install the ACMS Desktop software and sample applications and how to recover from system and installation failures. Chapter 3 Describes postinstallation procedures that prepare your OSF/1 system for running ACMS Desktop software. Chapter 4 Describes how to run the 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, and DEC OSF/1 desktop systems. Chapter 6 Describes the installation of ACMS Desktop client services and sample desktop client programs that run under Macintosh software. Appendix A Contains a log of a sample installation for the kit. Appendix B Describes the steps to prepare the sample ACMS application on the OSF/1 system. Appendix C Provides information to help deal with failures or errors that might occur. Related Documents In addition to this guide, use the following documentation for reference: o ACMS Desktop for OSF/1 Application Developer's Guide Conventions Table 1 describes the conventions used in this guide. viii Table_1_Conventions_Used_in_this_Guide____________________ Convention_____Meaning____________________________________ User Input In examples, user input is highlighted with bold type. # A pound sign (#) is the default superuser prompt. % A percent sign (%) is the default user prompt. In examples, a boxed symbol indicates that you must press the named key on the keyboard. Ctrl/C This symbol indicates that you must press the Ctrl key while you simultaneously press another key (in this case, C). user input In interactive examples, this typeface indicates input entered by the user. filesystem In text, this typeface indicates the exact name of a command, routine, partition, pathname, directory, or file. This typeface is also used in interactive examples and other screen displays. UPPERCASE The DEC OSF/1 AXP operating system lowercase differentiates between lowercase and uppercase characters. Examples, syntax descriptions, function definitions, and literal strings that appear in text must be typed exactly as shown. [y] In a prompt, square brackets indicate that the enclosed item is the default response. For example, [y] means that the default _______________response_is_Yes.___________________________ ix Part I ________________________________________________________________ ACMS Desktop Software Part I describes how to install the ACMS Desktop software on your DEC OSF/1 system. 1 ________________________________________________________________ Preparing for ACMS Desktop Installation Your distribution kit includes a letter titled Read Before Installing ACMS Desktop. This letter discusses important information that might not be included in this guide. Read this letter now. 1.1 Reading the Online Release Notes ACMS Desktop provides online release notes. Digital strongly recommends that you read the release notes before using the product. The release notes may contain information about changes to the application. The release notes for ACMS Desktop are in the following files: /usr/etc/acmsdi/install/acms_desktop_v21_release_notes.txt /usr/etc/acmsdi/install/acms_desktop_v21_release_notes.ps 1.2 Registering Your Software License ACMS Desktop includes support for the License Management Facility (LMF). You must register your License Product Authorization Key (License PAK) in the License Database (LDB) in order to use ACMS Desktop on a newly licensed node. The License PAK may be shipped along with the kit if you ordered the license and media together; otherwise, it is shipped separately to a location based on your license order. If you are installing prerequisite or optional software along with ACMS Desktop, review the PAK status and install the PAKs for any prerequisite or optional software before you install ACMS Desktop. To register a license under the DEC OSF/1 AXP operating system, first log in as superuser. Preparing for ACMS Desktop Installation 1-1 At the superuser prompt, edit an empty PAK template with the lmf register command as follows, and include all the information on your License PAK: # lmf register After you register your license, use the following lmf reset command to copy the license details from the License Database (LDB) to the kernel cache: # lmf reset For complete information on using the License Management Facility, see the Guide to Software License Management and the lmf(8) reference page. 1.3 Checking the Software Distribution Kit Use the Bill of Materials (BOM) to check the contents of your ACMS Desktop software distribution kit. In addition to this guide, the software distribution kit includes the following: o CD-ROM optical disk for systems with optical disk drives o CD-ROM booklet and CD-ROM read first letter If your software distribution kit is damaged or incom- plete, contact your Digital representative. 1.4 Checking Installation Procedure Requirements This section discusses various requirements for installing ACMS Desktop. Installing ACMS Desktop, including running the Installation Verification Procedure (IVP), takes approximately two to ten minutes, depending on your type of media and system configuration. 1.4.1 Checking Login Privileges You must have superuser privileges to install the ACMS Desktop software and to register the license PAK. 1-2 Preparing for ACMS Desktop Installation 1.4.2 Checking Hardware Requirements To install ACMS Desktop, you need the following hardware: o Software distribution device (if installing from media) Locate the CD-ROM drive for the CD-ROM software distribution media. The CD booklet or the documentation for the CD-ROM drive you are using explains how to load the CD-ROM media. o Terminal You can use either a hardcopy or video terminal to communicate with the operating system and respond to prompts from the installation procedure. See the ACMS Desktop Software Product Description (SPD) for additional hardware requirements. 1.4.3 Checking Software Requirements ACMS Desktop for OSF/1 Version 2.1 requires the DEC OSF/1 AXP operating system Version 3.0 or higher. Future ACMS Desktop releases may require higher versions. See the Read Before Installing letter (included on the CD-ROM) or the online release notes for information about the minimum version of the operating system required. ACMS Desktop also requires that the following DEC OSF/1 AXP software subsets be loaded on the system where you install ACMS Desktop: o OSFBASE300-the "Base System" subset o DCECDS130-DCE CDS Server Version 1.2 o DCEMAN130-DEC Administration Manual Pages Version 1.2 o DCERTS130-DCE Run-Time Services Version 1.2 o DCESEC130-DCE Security Server Version 1.2 o ACMSXPVBASE200-ACMSxp for OSF/1 Version 2.0 - Server Kit To check whether these subsets are loaded, follow these steps: 1. Log in to the system where you will install ACMS Desktop. Preparing for ACMS Desktop Installation 1-3 2. Enter the following command: # setld -i | egrep 'OSFBASE' If you do not log in as superuser (login name root), you must enter the full path of the command. For example: % /usr/sbin/setld -i | grep OSFBASE Check the displayed rows for the name of the relevant subset and any related patches. The word "installed" appears in a row after the subset identifier when a subset is loaded. If the word "installed" does not appear (the second column in a row is blank), the subset or patch is not loaded. In this case, you must load the missing DEC OSF/1 AXP software before installing ACMS Desktop. If the ACMSxp subset is not loaded on the system where you are installing ACMS Desktop, create the following directories and copy the indicated files from your ACMSxp system: /usr/opt/ACMSXPV200/bin/* /usr/opt/ACMSXPV200/shlib/* - The ACMSxp shared libraries /usr/opt/ACMSXPV200/msg/en_US.ISO8859-1.cat - An ACMSxp message catalog For information on how to load the operating system software, see the Guide to Installing DEC OSF/1. 1.4.4 Determining Which Subsets to Load You must choose the ACMS Desktop subsets you want to load. The ACMS Desktop subset has the following title: ACMS Desktop for OSF/1 1.4.5 Determining Disk Space Requirements This section lists the disk space requirements for loading the ACMS Desktop software subset. These requirements apply to the disks where you load the ACMS Desktop subset. The following requirements are listed by directory for convenience if you are doing installations on systems where these directories are mount points for different disk partitions: 1-4 Preparing for ACMS Desktop Installation o /usr/opt - 4 000 Kbytes o /var/opt - 5 Kbytes Using these disk space requirements, total the values for the subsets you will load in each directory. Compare the space required for subsets with the free space currently on the disks where ACMS Desktop files will reside. 1.4.5.1 Checking Current Disk Space To check the current amount of free space for a directory path, log in to the system where you will install ACMS Desktop. You can check which directories are mounted and where they are by viewing the /etc/fstab file. For example: # more /etc/fstab /dev/rd0a:/:rw:1:1:ufs:: /dev/rd0g:/usr:rw:1:2:ufs:: /usr/staff/r1/leslie@bigsys:/usr/staff/r1/leslie:rw:0:0:nfs:bg: /usr/man@bigsys:/usr/man:ro:0:0:nfs:bg: The display indicates that /usr (mounted to /dev/rd0g) is the only mount point that affects where ACMS Desktop files will reside; the system has only one local disk drive, and the /usr/lib and file system resides in the g partition of the disk on that drive. To check the total space and the free space for the directories where ACMS Desktop will reside, enter the df command. Given the previous display of the /etc/fstab file, which shows that only /usr is a mount point, you need to check free space only in the /usr file system. For example: # df /usr Filesystem Total kbytes kbytes % node kbytes used free used Mounted on /dev/rd0g 122598 54447 55892 49% /usr This display shows that there are 55,892 Kbytes free. This free space must accommodate the subset requirements listed in Section 1.4.5. Preparing for ACMS Desktop Installation 1-5 On systems where /usr/lib and /usr/man are mounted to different devices from /usr, enter the following command: # df /usr/lib /usr/man In this case, you compare space required for ACMS Desktop files in /usr/lib to the free space displayed in the first line of the df output list, and compare the space required for ACMS Desktop files in /usr/man to the free space displayed in the second line of that list. 1.4.5.2 Increasing Disk Space by Using Alternative Disks The ACMS Desktop installation procedure creates the following directories and loads files into subordinate directories: /usr/opt/ACMSDI210 /var/opt/ACMSDI210 If the ACMSDI210 directory node in the previous paths does not exist, the installation procedure creates it. If the ACMSDI210 node does exist, the installation procedure uses it. If you find that there is insufficient disk space for the ACMS Desktop subsets and you know that you have additional space on alternative disks or disk partitions for your system, perform the following steps before installing ACMS Desktop: 1. Log in as superuser. 2. Create the directories /usr/opt/ACMSDI210 and /var/opt /ACMSDI210. 3. Specify in the /etc/fstab file that one or more of the newly created directories are mount points to new disk partitions where there is additional space. 4. Enter the mount -a command so that the new mount points take effect. 1-6 Preparing for ACMS Desktop Installation 1.5 Installing from Media or Using RIS Someone from your site must perform at least one ACMS Desktop installation from the distribution medium. Your site system manager can then decide whether or not to make an ACMS Desktop distribution kit available online so that subsequent installations of ACMS Desktop can use the Remote Installation Service (RIS). For information on extracting ACMS Desktop subsets to an RIS distribution area, see the Guide to Sharing Software on a Local Area Network. If you expect to use ACMS Desktop subsets from the RIS area of a remote system for installation on your local system, first check with your site system manager to ensure that: o An ACMS Desktop network kit is available for use. o Your system is registered as an RIS client. If ACMS Desktop subsets are available to you on an RIS server system, you must know the name of that system. For more information on installing ACMS Desktop from an RIS distribution area, see Section 2.3. 1.6 Backing Up Your System Disk Digital recommends that you back up your system disk before installing any software. For information about backing up your system disk, see the DEC OSF/1 AXP system documentation. 1.7 Stopping the Installation To stop the installation procedure at any time, press Ctrl /C. You must then delete files created up to this point interactively. Preparing for ACMS Desktop Installation 1-7 2 ________________________________________________________________ Installing ACMS Desktop This chapter describes how to install ACMS Desktop. Before you start the installation, read Chapter 1. You can install ACMS Desktop locally (using CD-ROM media) or from a server area. If you encounter any failures during installation, see Appendix C. 2.1 Pre-Installation Work Before installing ACMS Desktop Version 2.1, do the following: o Create the group acmsdi in the /etc/group file. Users who are members of this group can act as administrators of ACMS Desktop. o Remove any earlier installations of this product, for example: % setld -d ADIBASE140 2.2 Using CD-ROM Consolidated Distribution Media The following procedure loads ACMS Desktop files onto a disk belonging to the system where you perform the installation. When ACMS Desktop is run, its executable images are mapped into memory on your system. Follow these steps to install ACMS Desktop from CD-ROM media: 1. Mount the media on the appropriate disk drive. 2. Log in as superuser (login name root) to the system where you are installing ACMS Desktop. Installing ACMS Desktop 2-1 3. Make sure that you are at the root (/) directory by entering the following command: # cd / 4. Check for the name of the CD-ROM device by looking for RRD42 in the device list: % file /dev/rrz*c 5. Specify a name for the /cdrom directory to be the mount point for the distribution file system on the drive. For example, if your CD-ROM device is /dev/rrz4c, enter the following command: # mount -dr /dev/rz4c /cdrom ________________________Note ________________________ Be sure to specify /rz4c, not /rrz4c. _____________________________________________________ 6. Enter a setld command that requests the load function (-l) and identifies the directory in the mounted file system where ACMS Desktop subsets are located. For example, if the directory location for these subsets is /cdrom/ADI210/kit, enter the following command: # setld -l /cdrom/ADI210/kit The installation procedure now displays the names of ACMS Desktop subsets and asks you to specify the subsets you want to load. See Section 2.4 to continue the installation. 2.3 Using an RIS Distribution Area If you are installing ACMS Desktop subsets that reside in an /etc/ris RIS distribution area on a remote system, follow these steps: 1. Log in as superuser (login name root) to the system where you are installing ACMS Desktop. 2-2 Installing ACMS Desktop 2. Make sure that you are at the root directory (/) by entering the following command: # cd / 3. Enter a setld command that requests the load function (-l option) and identifies the system where the ACMS Desktop subsets are located. For example, if you are loading ACMS Desktop subsets from an RIS distribution area on node orion, enter the following: # setld -l orion: Remote Installation Services now displays a menu that lists all the software subsets available to you and asks you to specify the subsets you want to load. See Section 2.4 to continue the installation. 2.4 Responding to Installation Procedure Prompts This section explains the installation procedure prompts and displays. 2.4.1 Selecting Subsets You must specify which ACMS Desktop subsets you want to load. ________________________Note ________________________ If you are installing from an RIS distribution area, the number of subsets can vary depending on what products are available in the RIS area and how many subsets they have. _____________________________________________________ *** Enter Subset Selections *** The subsets listed below are optional: There may be more optional subsets than can be presented on a single screen. If this is the case, you can choose subsets screen by screen or all at once on the last screen. All of the choices you make will be collected for your confirmation before any subsets are installed. 1) ACMS Desktop for OSF/1 Of you may choose one of the following options: Installing ACMS Desktop 2-3 2) All of the Above 3) CANCEL selections and redisplay menus 4) Exit without installing any subsets Enter your choices or press RETURN to redisplay menus. Choices (for example, 1 2 4-6): 1 If you specify more than one number at the prompt, separate each number with a space, not a comma. Next, the script lets you verify your choice. For example, if you enter 1 in response to the previous prompt, you see the following display: You are installing the following optional subsets: ACMS Desktop for OSF/1 Is this correct? (y/n): If the displayed subsets are not the ones you intended to choose, enter n. In this case, the subset selection menu is again displayed and you can correct your choice of optional subsets. If the displayed subsets are the ones you want to load, enter y. 2.4.2 Monitoring Displays During the Subset Loading Process The installation procedure loads and verifies the selected ACMS Desktop subsets. The following example shows a display where the ACMS Desktop subset is being loaded from disk: Checking file system space required to install selected subsets: File system space checked OK. ACMS Desktop for OSF/1 Copying from /usr/users/build/kit/kit_output (disk) Verifying DESKTOP-ACMS-USER PRODUCER = DEC VERSION = 2.1 2-4 Installing ACMS Desktop Do you have this license installed? (y/n/?) Do you you want to run the IVP after this installation? (y/n/?) There are no further questions... The remainder of this installation will take approximately 2 minutes, including running the IVP (if selected). After the installation completes, please be sure to perform the postinstallation tasks specified in the installation guide. The release notes for this product are in: /usr/etc/acmsdi/install/acms_desktop_v21_release_notes.txt (text) /usr/etc/acmsdi/install/acms_desktop_v21_release_notes.ps (postscript) The installation for ACMS Desktop has completed When you see the "Verifying" message during the subset installation, the installation procedure is checking to see that the files are copied correctly; it is not an Installation Verification Procedure (IVP) message. During the installation, if you get errors from the setld utility, see the Diagnostics section of the setld(8) reference page for an explanation of the errors and the appropriate actions to take. Chapter 3 and Chapter 4 explain how to run the IVP after installation, and how to delete old ACMS Desktop subsets before installing a new version of ACMS Desktop. Installing ACMS Desktop 2-5 3 ________________________________________________________________ After Installation This chapter explains what you need to do after the installation to make ACMS Desktop ready for use. 3.1 Running the Installation Verification Procedure After installing ACMS Desktop, you can run the Installation Verification Procedure (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 ACMS Desktop. The ACMS Desktop IVP checks whether the ACMS Desktop gateway can be started and stopped successfully. To run the IVP after an installation, enter the following command: # /usr/etc/acmsdi/ADIBASE210_IVP.csh For a sample ACMS Desktop IVP, see Appendix A. If the verification process fails, look in the file /var /adm/smlogs/fverify.log for information to help diagnose the problem. 3.2 Deleting ACMS Desktop from Your System If you must remove a version of ACMS Desktop from your system, delete each subset that you previously installed. To delete subsets: 1. Log in as superuser (login name root). 2. Make sure that you are at the root directory (/) by entering the following command: # cd / After Installation 3-1 3. Enter the following form of the setld command: # setld -i | grep ADI 4. Look for the word "installed" in the listing produced, and then delete the installed versions. For example: # setld -d ADIBASE140 This example deletes ACMS Desktop for OSF/1 Version 1.4. 3.3 Displaying Documentation from CD-ROM The ACMS Desktop documentation is provided on the DEC OSF /1 AXP Layered Products Online Documentation CD-ROM in Bookreader (.decw_book) file format. You can display the Bookreader files on your workstation using the DECwindows Bookreader application. For information on accessing and displaying these files, see the DEC OSF/1 Layered Products Disc User's Guide. 3-2 After Installation 4 ________________________________________________________________ Running the ACMS Desktop for OSF/1 IVP This chapter describes how to run the ACMS Desktop for OSF/1 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 ACMS Desktop software and answer YES to the IVP question. If the IVP fails for any reason, correct the error and rerun the IVP. 4.1 IVP Operations The IVP checks that the installation procedure success- fully completed installing ACMS Desktop software and that the software can be used to set up and run ACMS Desktop applications. 4.2 Running the IVP Independently This section describes the steps to run the IVP and IVP error recovery. 4.2.1 IVP Steps To run the IVP independently of the installation procedure, follow these steps: 1. Log in to the Root account: login: root Password: 2. Set your default to the test directory: # cd /usr/etc/acmsdi/install # 3. Run the ACMS Installation Verification Procedure, ADIBASE210_IVP.csh. Running the ACMS Desktop for OSF/1 IVP 4-1 You can run the IVP only on your current booted system. You cannot run the IVP over a networked connection. 4-2 Running the ACMS Desktop for OSF/1 IVP To start the IVP, enter the following command: # ./ADIBASE210_IVP.csh . . . Beginning IVP for ACMS Desktop Copyright (c) Digital Equipment Corporation, 1994 Attempting to start ACMS Desktop gateway process The acmsdid process is attempting initialization on TCP/IP port: 1023 Issue: ps -p7655 -oVFMT - to see the state of the process PID TT STAT TIME SL PAGEIN VSZ RSS %CPU %MEM COMMAND 7655 ?? S 0:00.04 0 0 5.48M 424K 0.0 0.3 /usr/bin/acmsdid 8001 S 0 7655 1 0.0 41 0 480K event ?? 0:00.05 acmsdid ///////////////////////////////////////////////////////////////// / The IVP for ACMS Desktop V2.1-0 has completed successfully. / ///////////////////////////////////////////////////////////////// Shutting down gateway. Issue: ps -oVFMT -p7655 - to see the state of the process PID TT STAT TIME SL PAGEIN VSZ RSS %CPU %MEM COMMAND 7655 ?? S 0:00.05 10 0 6.23M 480K 0.0 0.4 /usr/bin/acmsdid Stopping the /usr/bin/acmsdid process using pid 7655 The process will be shutdown now, closing any open client connections The ACMS Desktop V2.1-0 IVP completed successfully Shutting down gateway # The IVP takes no more than 30 seconds to run, depending on the current system load. 4.2.2 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. Running the ACMS Desktop for OSF/1 IVP 4-3 Part II ________________________________________________________________ ACMS Desktop Client Services Part II describes how to install the ACMS Desktop client services and the 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 OSF/1 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 for the following items listed in Table 5-1. Table_5-1_Installing_ACMS_Desktop_Services________________ Components_________________DOS____Windows_____OSF/1_______ Application Programming X X X Interface Visual Basic Sample X Client OSF/Motif Sample Client X Network_Transport_Support__X______X___________X___________ This chapter is organized 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. Installing ACMS Desktop Portable API Services and Samples 5-1 o Section 5.3 Presents the API and sample installation procedures for the OSF/1 operating system. o Section 5.4 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 TCP/IP services to communicate with the ACMS Desktop gateway. Table 5-2 lists the products required to use the various APIs. Table_5-2_Products_Required_for_APIs____________________________ API____________________Product__________________________________ DOS and Windows PATHWORKS Version 5.0 for DOS or clients A TCP/IP package for DOS/Windows provid- ing a DLL that supports Version 1.1 of the WINSOCK standard. OSF/1 client TCP/IP support is provided in the _______________________base_kit_for_DEC_OSF/1_AXP.______________ Table 5-3 lists the products required to use the sample application. 5-2 Installing ACMS Desktop Portable API Services and Samples Table_5-3_Sample_Application_Product_Dependencies_______________ Sample______________Products_Required___________________________ DOS Microsoft COBOL Version 4.0 Microsoft C Version 6.0 or higher Microsoft Windows Microsoft Windows Version 3.0 or higher Microsoft C Version 6.0 or later Microsoft Windows Soft. Development Kit Version 3.0 or higher Visual Basic Microsoft Windows Version 3.0 or higher client Microsoft Visual Basic Version 1.0 or higher Motif on OSF/1 DEC C for OSF/1 AXP OSF-BASE and OSF-DEV licenses ____________________for_DEC_OSF/1_AXP___________________________ 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 Windows 10 minutes OSF/1____________10_minutes_______________________________ 5.1.2.2 Disk Space Table 5-5 lists the disk space required. Installing ACMS Desktop Portable API Services and Samples 5-3 Table_5-5_API_and_Library_Disk_Space_Requirements_________ DOS_Client____________Number_of_Bytes_____________________ DOS and Windows 400K API libraries and network software DOS sample files 420K Windows sample files 525K Visual Basic sample 81K files Macintosh API and 600K samples __________________________________________________________ OSF/1_Client__________Number_of_Kbytes____________________ API library and TCP 217K /IP module Motif_samples_files____644K_______________________________ 5.1.2.3 Resources Before you start the installation procedure, obtain the following: o TCP/IP host name for the OSF/1 system on which the ACMS Desktop gateway is installed o Valid account (user name and password) on the OSF/1 system on which the ACMS Desktop gateway 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 5-4 Installing ACMS Desktop Portable API Services and Samples 5.2 Installing the DOS and Windows APIs ACMS Desktop provides a command procedure to automate the installation of the DOS and Windows clients and sample applications. To install either the DOS API or Windows API, use the disetup.bat batch procedure. To download the Visual Basic sample, you also need to follow the procedures in Section 5.2.4. When the disetup.bat procedure runs, it asks you which API you want to install. When the command procedure completes, print the README.TXT file, and follow the instructions for your particular transport. Verify the installation by following the instructions in the next sections. 5.2.1 Installing the DOS or Windows API and Sample Client Software Installing the Client software on DOS or Windows involves: 1. Copying a batch file and a .EXE file from the server system to a directory on your PC 2. Running the batch file 3. Performing any additional steps discussed in the README.TXT file 4. Verifying the installation The ACMS Desktop kit contains an automated postinstalla- tion procedure for DOS and Windows clients. ________________________Note ________________________ The batch procedure that implements these procedures uses the FTP GET command to download files. If your PC is using a different service to download files from the server, edit the batch procedure to use the appropriate copy command. In addition, the batch procedure uses the -u option of the FTP PC/TCP implementation of the ftp file transfer program. PATHWORKS Version 5.0 does not support this option. _____________________________________________________ Installing ACMS Desktop Portable API Services and Samples 5-5 To use the automated procedures, follow these steps: 1. Create a new directory: > c:\acmsdi C: \acmsdi\AVERTZ C: \acmsdi\CLIENT 2. Download the following files, where nodename is the DEC OSF/1 AXP system where the ACMS Desktop product is installed: > ftp nodename ! Respond to login prompts ftp> cd /usr/etc/acmsdi/install ftp> get disetup.bat ftp> image ftp> get nwhat.exe 3. Run the disetup.bat file: > disetup nodename username password The disetup procedure prompts you for the platform and network transport you are using for the ACMS Desktop client. Default values for each prompt are displayed in square brackets. Note that certain Microsoft Windows programming environments, such as Visual Basic, require that applications use DLLs for services. The disetup procedure configures the ACMS Desktop client libraries for the network transport specified and, if requested, downloads the ACMS Desktop sample for you. It also generates a logicals.bat file in the target installation directory that can be used to set up logical names specific to ACMS Desktop. When disetup completes, read the readme.txt file in the target installation directory for any further instructions. 4. To display online help for disetup, type: > disetup help 5-6 Installing ACMS Desktop Portable API Services and Samples 5.2.1.1 Troubleshooting the DOS and Windows Postinstallation Procedure To display common problems and solutions for using disetup, use the disetup help on your PC. Additionally, keep in mind the following troubleshooting tips: o The disetup procedure uses the command ftp get. Make sure that the paths to these commands are listed in the PATH environment variable so that DOS can find them when they are invoked in disetup. o Verify that the software is installed on the OSF/1 system; verify that the software is located in the directories specified during disetup. 5.2.2 Verifying the NonWindows 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 C Version 6.0 or higher o C run-time library that is compatible with Microsoft C 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 . . . Installing ACMS Desktop Portable API Services and Samples 5-7 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 Appendix B to set up the sample application on the ACMSxp system. You can sign in to the ACMSxp system and use the reserve task of the application. The installation procedure is now complete and verified. 5.2.2.1 NonWindows Sample Files Added to the System All C and COBOL language files (.c, .h, .cbl) listed in Table 5-6 are copied to the desktop system during the installation of the nonWindows sample. Table_5-6_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 (continued on next page) 5-8 Installing ACMS Desktop Portable API Services and Samples Table_5-6_(Cont.)_NonWindows_Sample_Files_________________ Name_______________Description____________________________ DISABLE.C Sample presentation procedure ENABLE.C Sample presentation procedure GETSITE.CBL Sample presentation procedure LOADER.BAT Batch file to download the sample from the OSF/1 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 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 TRANS.C Sample presentation procedure TRANS.CBL Sample workspace TRANSHDW.CBL Sample workspace VERSION.C__________Sample_version-checking_procedure______ 5.2.3 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 C Version 6.0 or higher Installing ACMS Desktop Portable API Services and Samples 5-9 o C run-time library that is compatible with Microsoft C o Microsoft Windows Version 3.0 o Microsoft Windows Software Development Kit (SDK) Version 3.0 To build the sample application using DLLs, follow these steps: 1. Set default to the c:\AVERTZ directory and save the files AVERTZ and AVERTZ.DEF using different names. Copy AVERTZ and AVERTZ.DEF from the subdirectory WITHDLL. ________________________Note ________________________ These steps assume you answered yes to using WINSOCK when running the disetup procedure. _____________________________________________________ 2. Using the AVERTZ makefile, build the sample application by running either NMK or PWB in the directory containing the sample files. o To use NMK, enter the following command: nmk AVERTZ In Microsoft C Version 7, NMK has been replaced with nmake. Therefore, the application must be built using the command nmake AVERTZ. o To use PWB, follow these steps: a. Start the workbench: pwb b. In the Build menu, select the Set Program List command. c. In the dialog box that appears, enter the following: @AVERTZ ________________________Note ________________________ The at-sign (@) here tells PWB that AVERTZ is not a PWB-generated makefile. Some later versions of the 5-10 Installing ACMS Desktop Portable API Services and Samples PWB may not require or recognize the @ designator of foreign makefiles. You may, instead, find a checkbox that you can use to designate a foreign or non-PWB makefile. _____________________________________________________ d. In the Build menu, select the Build All command. When you first build AVERTZ, error messages appear indicating that certain modules are not found in the library. Ignore these messages. Because this is a new library and the makefile is trying to remove those modules before entering new ones, there are no objects to remove. The error messages do not appear during subsequent builds. e. In the File menu, select the Exit command. 3. Run Windows by entering the following command: win 4. 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: \AVERTZ\avertz o Add the AVERTZ program icon to the screen and double click on it: a. In the Program Manager File menu, select the New command. This creates a group window to contain the icon. b. In the dialog box, select the new Program Group and click on the OK button. Installing ACMS Desktop Portable API Services and Samples 5-11 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:avertz\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:\AVERTZ\avertz 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. If you want the sample desktop client program to communicate with the ACMSxp application, follow the procedures in Appendix B to set up the sample application on the ACMSxp system. After you set up the ACMSxp system, use the Session menu to sign in to the ACMSxp 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. 5-12 Installing ACMS Desktop Portable API Services and Samples 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:\dos;c:\c600\bin;c:\c600\binb;c:\windows;c:\windev;c:\tcpip;c:\acmsdi mouse set lib=c:\windev\lib;c:\c600\lib;c:\acmsdi;c:\tcpip\sockets\win set include=c:\windev\include;c:\c600\include;o:\acmsdi;c:\tcpip\sockets\include set helpfiles=c:\c600\help\*.hlp set init=c:\c600\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. 5.2.3.1 Windows Sample Files Added to the System All C language and header files (.c and .h), Windows (.def), icons (.ico), executable (.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 ACMS Desktop API (continued on next page) Installing ACMS Desktop Portable API Services and Samples 5-13 Table_5-7_(Cont.)_Windows_Sample_Files____________________ Name_______________Description____________________________ 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 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 HELP.TXT Overview of the AVERTZ user interface LIST_PKG.C Provides linked list functionality; 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 OSF/1 system RECVW.C Presentation procedure stub (continued on next page) 5-14 Installing ACMS Desktop Portable API Services and Samples Table_5-7_(Cont.)_Windows_Sample_Files____________________ Name_______________Description____________________________ REDCAR.ICO Icon for (an unselected) session that is not currently processing a task REQUESTW.C Presentation procedure stub RESVFORM.C Management and convenience routines for handling the reservation form RESVFORM.H Header file for resvform.c SDRIVING.ICO Icon for a selected session that is currently processing a task SENDW.C Presentation procedure to dispatch to specific routines in avertzpp 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 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.4 Installing the Visual Basic Sample Client Installing the Visual Basic Sample client involves: o Copying a batch file from the server system to a samples directory o Running the batch file Installing ACMS Desktop Portable API Services and Samples 5-15 o Verifying the installation 5.2.4.1 Copying the Visual Basic Sample Files To install the Visual Basic sample files on the desktop system, perform the following steps: 1. Create a directory on the desktop system to contain the sample files and move to that directory. For example: > c: > mkdir C:\VBAVERTZ > cd \VBAVERTZ 2. Use the FTP file-transfer utility to copy the batch file into the samples directory. For example: \VBAVERTZ> ftp nodename ! Respond to login prompts ftp> cd /usr/examples/acmsdi/msw/vb ftp> get loadvb.bat ftp> quit where: node Is the TCP/IP OSF/1 node name for the ACMS Desktop gateway system. 3. Run the batch file: \VBAVERTZ> LOADVB node username password . . . ******** SAMPLE INSTALLATION COMPLETE ********** \VBAVERTZ> ________________________Note ________________________ With some FTP TCP/IP products, you can issue the ftp connect command: > ftp -u username password hostname _____________________________________________________ For a list of the files to be transferred, see Table 5-8. 5-16 Installing ACMS Desktop Portable API Services and Samples 5.2.4.2 Verifying the Visual Basic Sample Installation To verify the success of the Visual Basic sample installation, bring up the Visual Basic development environment under Microsoft Windows. Make sure that the directory containing the appropriate ACMSDI.DLL is in your path variable, that is c:\acmsdi. 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.4.3 Visual Basic Sample Files Added to the System Table 5-8 lists the Visual Basic files added to the system. Table_5-8_Visual_Basic_Sample_Files_______________________ Name_______________Description____________________________ ACMSDI.BAS Include file of the ACMSDI declaration for Visual Basic applications HELP.TXT Online help file for the Visual Basic sample LOADVB.BAT Batch file to download the Visual Basic sample from the OSF/1 system MAINMENU.FRM GUI objects and code for the main window of Visual Basic AVERTZ (continued on next page) Installing ACMS Desktop Portable API Services and Samples 5-17 Table_5-8_(Cont.)_Visual_Basic_Sample_Files_______________ Name_______________Description____________________________ RESERVE.FRM GUI objects and code for the reserva- tion form of Visual Basic AVERTZ SIGNIN.FRM GUI objects and code for the 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 the AVERTZ ___________________sample_________________________________ 5.3 Installing the OSF/1 API and Sample Client Software The following sections describe how to install the OSF/1 API and sample client software on an OSF/1 desktop system. 5.3.1 Installing the OSF/1 API To install the OSF/1 API, follow these instructions: 1. Create the API directory on the desktop system: > mkdir acmsdi 2. Select the appropriate network object modules. To enable the desktop client program to communicate with the ACMSxp system, you must link your application programs with the proper network software. The network software for ACMS Desktop is TCP/IP. This software is already configured into the ACMS Desktop API library. 3. Copy the appropriate files from the ACMS Desktop gateway 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. 5-18 Installing ACMS Desktop Portable API Services and Samples Or, you can 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. The following instructions use italics to represent user-specific input: server_ Node name of the OSF/1 system where ACMS node Desktop has been installed and from which files are copied username Valid user account on server_node password Password of the user account username Using ftp to copy the files: 1. Copy the ACMS Desktop Header and Presentation Procedure Stubs File: > cd acmsdi > ftp server_node . . . ftp> get /usr/etc/acmsdi/common/acmsdi.h ftp> get /usr/etc/acmsdi/common/ppstubs.c ftp> get /usr/etc/acmsdi/common/forms.h ftp> get /usr/etc/acmsdi/common/tdms.h ftp> bye 2. Copy the ACMS Desktop client library: > su # cd /usr/lib # ftp server_node . . . ftp> binary ftp> cd /usr/etc/acmsdi/osf_axp ftp> get libacmsdi.a 3. Exit ftp: ftp> bye Installing ACMS Desktop Portable API Services and Samples 5-19 4. Exit superuser mode: # > After these steps, you are ready to build ACMS Desktop applications that use TCP/IP as a transport. 5.3.1.1 API Files Added to the OSF/1 Desktop System Files listed in Table 5-9 are copied to the OSF/1 system during the installation of the ACMS Desktop services for OSF/1 software. Table_5-9_OSF/1_Files_____________________________________ Name_____________Description______________________________ ACMSDI.H Include file for the ACMS Desktop API LIBACMSDI.A Library for the ACMS Desktop API PPSTUBS.C Presentation procedure and action routine _________________stubs____________________________________ 5.3.2 Installing the Motif Sample Client on OSF/1 To install the Motif sample files on the OSF/1 system, perform the following steps: 1. Create a directory on the OSF/1 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: a. Copy the shell: > ftp server_node . . . ftp> cd /usr/examples/acmsdi/motif ftp> get load_motif.sh ftp> bye 5-20 Installing ACMS Desktop Portable API Services and Samples 3. Run load_motif: > sh load_motif.sh Enter operating system ID (osf, mips_ultrix, sco_unix, vax_ultrix): mips_ultrix Enter location of sample files on OSF/1 host [/usr/examples/acmsdi/motif]: Enter Desktop Gateway Node: server_node Enter Username: username Enter Password: password Copying m_avertz resource file... Copying m_avertz.c... Copying m_avertz.h... . . . 5.3.2.1 Verifying the Motif Sample Installation on OSF/1 Compile, link, and run the source code for the sample client program to verify your capability to build applications. ________________________Note ________________________ If you copied libacmsdi.a to a local directory rather than /usr/lib, edit the DESKTOPLIB line in 'Makefile' to change '-lacmsdi' to '/mypath /libacmsdi.a'. _____________________________________________________ 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. Ensure that your PATH environment value includes your default directory in n/motif.avertz. 3. Run the application by entering the following command: > m_avertz Installing ACMS Desktop Portable API Services and Samples 5-21 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 ACMSxp application, follow the procedures in Appendix B to set up the sample application on the ACMSxp system. After you set up the sample application, use the Session menu to sign in to the ACMSxp 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. The environment variable ACMSDI.TCPIP_PORT_host, where host is the ACMS Desktop gateway host name, has a value that corresponds to the one being used on the remote host. You can enable logging on the client to help diagnose problems: > setenv acmsdi_log client.log 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.3.2.2 Sample Files Added to the OSF/1 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-10 are copied to the desktop system by the load_motif shell. 5-22 Installing ACMS Desktop Portable API Services and Samples Table_5-10_Motif_Sample_Files_for_the_OSF/1_System________ Name_____________Description______________________________ Makefile Makefile for building the sample acmsdi.h Include file for the ACMS Desktop API help.txt Overview of the AVERTZ user interface load_motif Command shell to download the Motif sample from the OSF/1 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 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 functionality 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 [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-23 Table 5-10 (Cont.) Motif Sample Files for the OSF/1 ___________________System_________________________________ Name_____________Description______________________________ 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 m_wkspaces.c Support routines for AVERTZ workspace structures m_wkspaces.h_____Defines_the_AVERTZ_workspace_structures__ 5.4 Installation Errors Errors can occur during the installation, if any of the following conditions exist when installing: o For the DOS API-ACMS Desktop gateway system, if the following directories are protected against read access: - /usr/etc/acmsdi/msdos - /usr/etc/acmsdi/common 5-24 Installing ACMS Desktop Portable API Services and Samples - /usr/examples/acmsdi/msdos - /usr/examples/acmsdi/msw - /usr/examples/acmsdi/msw_with_dll o For the OSF/1 API-ACMS Desktop gateway system, if the following directories are protected against read access: - /usr/etc/acmsdi/common - /usr/etc/acmsdi/osf_axp - /usr/examples/acmsdi/motif o ACMS Desktop gateway system does not have the DOS or the MS-Windows sample software installed. o ACMS Desktop gateway node does not have the network software functioning correctly. o ACMS Desktop gateway node is unavailable. o ACMS Desktop gateway node name is invalid. o ACMS Desktop gateway node is not running the ACMS system. o ACMS Desktop gateway node has not invoked acmsdi_ startup.csh and started the ACMSxp TP system and task servers. o ACMS Desktop gateway software is not installed or is improperly installed. o ACMS Desktop gateway 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-25 6 ________________________________________________________________ Installing the ACMS Desktop Macintosh System and Sample Software This chapter discusses the installation of the ACMS Desktop services for Macintosh software. After you install the ACMS Desktop for OSF/1 software on the OSF/1 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 applica- tions, but does not include files that are helpful for developing new applications. Choose this option 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 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. o Examples option Includes the following: - Sample applications written in 4th Dimension, HyperCard, and C Installing the ACMS Desktop Macintosh System and Sample Software 6-1 - A set of 4th Dimension Externals that invokes the ACMS Desktop API, which includes C source code to illustrate how to write your own 4th Dimension Externals - A set of HyperCard XFCNs that invokes the ACMS Desktop API, including C source code - A set of utility files containing C source code for 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 ACMS Desktop software on the OSF/1 system running the ACMS Desktop gateway. 2. Install the appropriate Communications Tool, MacTCP, on your Macintosh system to use the TCP/IP communications transport. 3. Log in to the OSF/1 system using an account with sufficient privileges. 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. 6-2 Installing the ACMS Desktop Macintosh System and Sample Software 6.2.2.2 Disk Space Installing the ACMS Desktop services for Macintosh software requires approximately 3000 blocks on your OSF/1 system. 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 137K bytes System Services 182K bytes Examples 1914K bytes System Services and 2223K bytes 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 OSF/1 system on which the ACMS Desktop gateway is installed. o Sufficient disk space to load the 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 OSF/1 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 system. Installing the ACMS Desktop Macintosh System and Sample Software 6-3 2. Double click on the installer file. 3. Follow the instructions that are displayed. 6.3.1.1 Copying the Installer This section describes how to copy the acms_desktop.installer file to your Macintosh. Several tools are available for copying files from your OSF/1 system to your Macintosh; for example, Fetch, an FTP file transfer utility, is available as shareware. After you install ACMS Desktop on the host OSF/1 system, the acms_desktop.installer file is located in the /usr /etc/acmsdi/macintosh directory. Using a file transfer facility, copy the acms_desktop.installer file from this directory to your Macintosh. The file on the OSF/1 system is in MacBinary format. Many file transfer facilities 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 the method described in Section 6.3.1.1. 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.1. Click on the Continue button. 6-4 Installing the ACMS Desktop Macintosh System and Sample Software 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. 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 three 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. - Run-Time Services: This option installs only the basic software needed for run-time support. The development aids and the Examples are not installed. - System Services: This option installs everything except the Examples . Installing the ACMS Desktop Macintosh System and Sample Software 6-5 - Examples: This option installs the Examples. Use it as a follow-up installation to a Run-Time Services option or a System Services option. 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.1)". All files except the DDEV 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. 6-6 Installing the ACMS Desktop Macintosh System and Sample Software A ________________________________________________________________ Sample Listings This appendix provides sample listings for the following procedures: o Installation of ACMS Desktop using disk media o Installation Verification Procedure (IVP) A.1 Sample ACMS Desktop Installation # setld -l kit/acmsdi The subsets listed below are optional: There may be more optional subsets than can be presented on a single screen. If this is the case, you can choose subsets screen by screen or all at once on the last screen. All of the choices you make will be collected for your confirmation before any subsets are installed. 1 ACMS Desktop for OSF/1 Or you may choose one of the following options: 2) ALL of the above 3) CANCEL selections and redisplay menus 4) EXIT without installing any subsets Enter your choices or press RETURN to redisplay menus. Choices (for example, 1 2 4-6):) 1 You are installing the following optional subsets: ACMS Desktop for OSF/1 Is this correct? (y/n): y Checking file system space required to install selected subsets: File system space checked OK. Sample Listings A-1 ACMS Desktop for OSF/1 Copying from kit/kit_output (disk) Verifying Do you have this license installed? (y/n/?) y Do you want to run the IVP after this installation? (y/n/?)y There are no further questions... The remainder of this installation will take approximately 2 minutes, including the IVP (if selected). After the installation completes, please be sure to perform the postinstallation tasks specified in the installation guide. The release notes for this product are in: /usr/examples/acmsdi/acms_desktop_v21_release_notes.txt (text) /usr/examples/acmsdi/acms_desktop_v21_release_notes.ps (postscript) The installation for ACMS Desktop has completed # A.2 Sample Installation Verification Procedure # /usr/etc/acmsdi/ADIBAS210_IVP.csh Beginning IVP for ACMS Desktop Copyright (c) Digital Equipment Corporation, 1994 Attempting to start ACMS Desktop gateway process The acmsdid process is attempting initialization on TCP/IP port: 1023 Issue: ps -p7655 -oVFMT - to see the state of the process PID TT STAT TIME SL PAGEIN VSZ RSS %CPU %MEM COMMAND 7655 ?? S 0:00.04 0 0 5.48M 424K 0.0 0.3 /usr/bin/acmsdid 8001 S 0 7655 1 0.0 41 0 480K event ?? 0:00.05 acmsdid ///////////////////////////////////////////////////////////////// / The IVP for ACMS Desktop V2.1-0 has completed successfully. / ///////////////////////////////////////////////////////////////// Shutting down gateway. Issue: ps -oVFMT -p7655 - to see the state of the process A-2 Sample Listings PID TT STAT TIME SL PAGEIN VSZ RSS %CPU %MEM COMMAND 7655 ?? S 0:00.05 10 0 6.23M 480K 0.0 0.4 /usr/bin/acmsdid Stopping the /usr/bin/acmsdid process using pid 7655 The process will be shutdown now, closing any open client connections Sample Listings A-3 B ________________________________________________________________ Setting Up the Sample Application The command procedure /usr/examples/acmsdi/acmsxp/avertz_ doit.csh sets up the sample application. You need to be a member of the acmsdi group to run the procedure. See the file acmsdi_vr_application_info.txt in the same directory for more information on setting up the sample. You can also perform management tasks related to your system, for example, authorizing user accounts. See the management information in ACMS Desktop for OSF/1 Application Development Guide. You can then run the DOS, Windows, and OSF/Motif clients to call the reserve task in vr_da_appl. Setting Up the Sample Application B-1 C ________________________________________________________________ Recovering from Errors This appendix provides information to help you deal with failures or errors that might occur during product installation or product use. If you find an error in the documentation, fill out and submit one of the Reader's Comments forms at the back of the document that contains the error. Include the section and page number of the error. C.1 Failures During Product Installation If errors occur during the installation, the system displays failure messages. For example, if the instal- lation fails due to insufficient disk space, the following message appears: There is not enough space for subset ACMS Desktop for OSF/1 ACMS Desktop (ACMS Desktop for OSF/1) will not be loaded. Errors can occur during the installation if any of the following conditions exist: o The operating system version is incorrect. o The prerequisite software version is incorrect. o There is insufficient disk space. o The system parameter values for successful installation are insufficient. For descriptions of error messages generated by these conditions, see the DEC OSF/1 AXP documentation on system messages, recovery procedures, and DEC OSF/1 AXP software installation. For information on system software requirements, see Section 1.4.3. Recovering from Errors C-1 C.2 Failures During Product Use If an error occurs while ACMS Desktop is in use and you believe the error is caused by a problem with the product, take one of the following actions: o If you have a Software Product Services Support Agreement, contact your Customer Support Center (CSC) by telephone or by using the electronic means provided with your support agreement (such as DSNlink). The CSC provides telephone support for high-level advisory and remedial assistance. When you initially contact the CSC, indicate the following: - Name and version number of the operating system you are using - Version number of ACMS Desktop you are using - Hardware system you are using (such as a model number) - Brief description of the problem (one sentence if possible) - How critical the problem is o If you have a Self-Maintenance Software Agreement, you can submit a Software Performance Report (SPR). o If you do not have any type of software services support agreement and you purchased ACMS Desktop within the past year, you can submit an SPR if you think the problem is caused by a software error. When you submit an SPR, take the following steps: 1. Describe as accurately as possible the circumstances and state of the system when the problem occurred. Include the description and version number of the ACMS Desktop being used. Demonstrate the problem with specific examples. 2. Reduce the problem to as small a size as possible. 3. Remember to include listings of any command files, INCLUDE files, or relevant data files, and so forth. 4. Provide a listing of the program. C-2 Recovering from Errors 5. If the program is longer than 50 lines, submit a copy of it on machine-readable media (floppy diskette or magnetic tape). If necessary, also submit a copy of the program library used to build the application. For information about submitting media, see the tar(1) reference page. 6. Report only one problem per SPR. This facilitates a faster response. 7. Mail the SPR package to Digital. If the problem is related to ACMS Desktop documentation, you can do one of the following: o Report the problem to the CSC (if you have a Software Product Services Support Agreement and the problem is severe). o Fill out the Reader's Comments form (in the back of the document that contains the error) and send the form to Digital. Be sure to include the section and page number of the error. Recovering from Errors C-3 ________________________________________________________________ Index A__________________________ I__________________________ API installation Installation errors, 5-24 requirements, 5-3 Installing DOS API, 5-5, 5-7 C__________________________ DOS sample, 5-5, 5-7 Copying the Installer, 6-4 OSF/1 API, 5-18 Windows API, 5-5 D Windows sample, 5-5, 5-7 ___________________________ IVP Disk space, 6-3 error recovery, 4-3 requirements, 5-3 operations performed by, 4-1 E__________________________ running independently, Examples option, 6-1 4-1 steps to run, 4-1 F__________________________ Files M__________________________ API Macintosh client added to OSF/1 system, installation 5-20 requirements, 6-2 sample Macintosh installation added to nonwindows options, 6-1 system, 5-8 added to OSF/1 system, O__________________________ 5-22 OSF/1 Motif sample, 5-20 added to Windows OSF/1 sample, 5-21 system, 5-13 Index-1 P__________________________ S__________________________ Preparing to install Sample Macintosh software, 6-2 Windows, 5-7 Prerequisite software System Services option, API, 5-2 6-1 sample application, 5-2 Prerequisite software for T__________________________ Macintosh systems, 6-2 Time to install, 5-3, 6-2 R__________________________ V Resources, 5-4 ___________________________ Run-Time Services option, Verifying 6-1 nonwindows sample, 5-7 Running the Installer, 6-4 Windows sample, 5-9 Index-2