DIGITAL ACMS Desktop for_DIGITAL_UNIX____________________________________ Installation Guide Order Number: AA-Q19ZC-TE July 1997 This guide describes how to install ACMS Desktop on an Alpha system running the DIGITAL UNIX operating system. Revision/Update Information: This is a revised manual. Operating System & Version: DIGITAL UNIX Version 4.0 or higher. Future maintenance releases may require higher versions. Software Version: DIGITAL ACMS Desktop for DIGITAL UNIX Version 2.2 Digital Equipment Corporation Maynard, Massachusetts ________________________________________________________________ First Printing, December 1993 Second Printing, December 1994 Third Printing, July 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 1993, 1994, 1997. All Rights Reserved. The following are trademarks of Digital Equipment Corporation: ACMS Desktop, ACMSxp, 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-6 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 2.4.1 Selecting Subsets......................... 2-3 iii 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-2 3.3 Displaying Documentation from CD-ROM.......... 3-2 4 Running the DIGITAL ACMS Desktop for DIGITAL UNIX 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.1.2.4 Use of Self-Extracting Archives......... 5-5 5.2 Installing the DOS and Windows APIs........... 5-5 5.2.1 Installing the DOS Sample Application..... 5-6 5.2.2 Verifying the DOS Sample Installation..... 5-6 5.2.2.1 DOS Sample Files Added to the System.... 5-7 5.2.3 Using the Windows Client Services......... 5-9 5.2.4 Installing the Windows Sample Application............................... 5-9 5.2.5 Verifying the Windows Sample Installation.............................. 5-10 5.2.5.1 Windows Sample Files Added to the System.................................. 5-12 iv 5.2.6 Installing the Visual Basic Sample Applications.............................. 5-15 5.2.6.1 Verifying the Visual Basic AVERTZ Sample Installation............................ 5-15 5.2.6.2 Visual Basic Sample Files Added to the System.................................. 5-16 5.3 Installing the Windows 95 API................. 5-16 5.3.1 Installing the Windows 95 Client Software.................................. 5-16 5.3.2 Installing a Sample for Windows 95........ 5-18 5.4 Installing the Windows NT API................. 5-18 5.4.1 Installing the Windows NT Client Software.................................. 5-18 5.5 Installing the DIGITAL UNIX API and Sample Client Software............................... 5-20 5.5.1 Installing the DIGITAL UNIX API........... 5-20 5.5.1.1 API Files Added to the DIGITAL UNIX Desktop System.......................... 5-22 5.5.2 Installing the Motif Sample Client on DIGITAL UNIX.............................. 5-23 5.5.2.1 Verifying the Motif Sample Installation on DIGITAL UNIX......................... 5-23 5.5.2.2 Sample Files Added to the DIGITAL UNIX Desktop System.......................... 5-25 5.6 Installation Errors........................... 5-27 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-12 5-2 Sample config.sys File.................... 5-12 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 DOS Sample Files.......................... 5-7 5-7 Windows Sample Files...................... 5-12 5-8 Visual Basic Sample Files................. 5-16 5-9 DIGITAL UNIX Files........................ 5-22 5-10 Motif Sample Files for the DIGITAL UNIX System.................................... 5-25 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 DIGITAL UNIX 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 DIGITAL UNIX 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 DIGITAL UNIX 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 DIGITAL ACMS Desktop for DIGITAL UNIX 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 DIGITAL UNIX 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 DIGITAL UNIX system. 1 _________________________________________________________________ Preparing for ACMS Desktop Installation Your distribution kit includes a letter titled Read Before Installing DIGITAL ACMS Desktop for DIGITAL UNIX. 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_v22_release_notes.txt /usr/etc/acmsdi/install/acms_desktop_v22_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 DIGITAL UNIX 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 incomplete, 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 DIGITAL ACMS Desktop Software Product Description (SPD) for additional hardware requirements. 1.4.3 Checking Software Requirements DIGITAL ACMS Desktop for DIGITAL UNIX Version 2.2 requires the DIGITAL UNIX operating system Version 4.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 DIGITAL UNIX software subsets be loaded on the system where you install ACMS Desktop: o OSFBASE410-the "Base System" subset o DCECDS201-DCE Cell Directory Server Version 2.0a o DCEMAN201-DCE Reference Manual Pages Version 2.0a o DCERTS201-DCE Run-Time Services Version 2.0a o DCESEC201-DCE Security Server Version 2.0a o ACMSXPVBASE301-ACMSxp V3.0a for DIGITAL UNIX Base 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 DIGITAL UNIX 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/ACMSXPV301/bin/* /usr/opt/ACMSXPV301/shlib/* - The ACMSxp shared libraries /usr/opt/ACMSXPV301/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 DIGITAL UNIX. 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 DIGITAL UNIX 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: o /usr/opt - 6 000 Kbytes 1-4 Preparing for ACMS Desktop Installation 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. On systems where /usr/lib and /usr/man are mounted to different devices from /usr, enter the following command: # df /usr/lib /usr/man Preparing for ACMS Desktop Installation 1-5 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/ACMSDI220 /var/opt/ACMSDI220 If the ACMSDI220 directory node in the previous paths does not exist, the installation procedure creates it. If the ACMSDI220 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/ACMSDI220 and /var/opt /ACMSDI220. 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.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 1-6 Preparing for ACMS Desktop Installation 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 DIGITAL UNIX 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.2, 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 ADIBASE210 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/adi220/kit, enter the following command: # setld -l /cdrom/adi220/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. Make sure that you are at the root directory (/) by entering the following command: # cd / 2-2 Installing ACMS Desktop 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 DIGITAL UNIX Of 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 Installing ACMS Desktop 2-3 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 DIGITAL UNIX 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 DIGITAL UNIX Copying from /usr/users/build/kit/kit_output (disk) Verifying DESKTOP-ACMS-USER PRODUCER = DEC VERSION = 2.2 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... 2-4 Installing ACMS Desktop 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_v22_release_notes.txt (text) /usr/etc/acmsdi/install/acms_desktop_v22_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. You must run the IVP under the root account. The IVP is available only in the form of a C shell script, there is no Bourne shell version. If the root account is using the C shell, then you can run the IVP by entering the following command: # /usr/etc/acmsdi/install/ADIBASE220_IVP.csh If the the root account is running the Bourne shell, then issue the following command: # csh /usr/etc/acmsdi/install/ADIBASE220_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. After Installation 3-1 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 / 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 ADIBASE210 This example deletes ACMS Desktop for OSF/1 Version 2.1. 3.3 Displaying Documentation from CD-ROM The ACMS Desktop documentation is provided on the DIGITAL UNIX 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 DIGITAL UNIX Layered Products Disc User's Guide. 3-2 After Installation 4 _________________________________________________________________ Running the DIGITAL ACMS Desktop for DIGITAL UNIX IVP This chapter describes how to run the DIGITAL ACMS Desktop for DIGITAL UNIX 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 successfully 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, ADIBASE220_IVP.csh. Running the DIGITAL ACMS Desktop for DIGITAL UNIX 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 DIGITAL ACMS Desktop for DIGITAL UNIX IVP To start the IVP, enter the following command: # ./ADIBASE220_IVP.csh . . . Beginning IVP for ACMS Desktop Copyright (c) Digital Equipment Corporation, 1997 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.2-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.2-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 DIGITAL ACMS Desktop for DIGITAL UNIX 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 DIGITAL UNIX 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_________________ Win Win Win DIGITAL Components_______________DOS____V3.1_____95_____NT_____UNIX Application Programming X X X X X Interface Visual Basic Sample X X X Client OSF/Motif Sample Client X Network Transport X X X X X Support____________________________________________________ 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.5 Presents the API and sample installation procedures for the DIGITAL UNIX operating system. o Section 5.6 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 V3.1 PATHWORKS Version 5.0 clients (or higher) for DOS or A TCP/IP package for DOS/Windows providing a DLL that supports Version 1.1 of the WINSOCK standard. Windows 95 clients TCP/IP support is provided by Windows 95. Windows NT clients TCP/IP support is provided by Windows NT. DIGITAL UNIX client TCP/IP support is provided in the _______________________base_kit_for_DIGITAL_UNIX.________________ 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 5.0 Microsoft C Version 6.0 or higher Microsoft Windows Microsoft Windows Version 3.1 or higher Microsoft C Version 6.0 or later Microsoft Windows Soft. Development Kit Version 3.1 or higher Visual Basic Microsoft Windows Version 3.1 or higher client Microsoft Visual Basic Version 4.0 or higher Motif on DIGITAL DIGITAL C++ V5.4 for DIGITAL UNIX UNIX OSF-BASE and OSF-DEV licenses ____________________for_DIGITAL_UNIX_____________________________ 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 DIGITAL_UNIX_____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 Windows 95 API 1000K libraries and network software Windows NT API 1000K libraries and network software DOS sample files 420K Windows sample files 525K Visual Basic sample 300K files Macintosh API and 600K samples ___________________________________________________________ DIGITAL_UNIX_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 DIGITAL UNIX system on which the ACMS Desktop gateway is installed o Valid account (user name and password) on the DIGITAL UNIX 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.1.2.4 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 for DIGITAL UNIX. The files contained within the archive include the static-link library and the DLL for use with Windows. 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: > ftp nodename ! Respond to login prompts ftp> cd /usr/etc/acmsdi/msdos ftp> binary ftp> get 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 DIGITAL UNIX system in the directory /usr /etc/acmsdi/common: acmsdi.h forms.h ppstubs.c tdms.h Installing ACMS Desktop Portable API Services and Samples 5-5 Copy these files to the current directory, for example, using FTP: > ftp nodename ! Respond to login prompts ftp> cd /usr/etc/acmsdi/common ftp> ascii ftp> mget * The nodename is the DIGITAL UNIX system where the ACMS Desktop product is installed. If the directories into which you are copying the files 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 using c:\acmsdi: set LIB=%LIB%;c:\acmsdi set INCLUDE=%INCLUDE%;c:\acmsdi set PATH=%PATH%;d:\acmsdi 5.2.1 Installing the DOS Sample Application The DOS COBOL sample is provided on the DIGITAL UNIX system as a self-extracting archive file. To expand the archive, copy it in image mode (using FTP) to a clean directory on the PC, from the DIGITAL UNIX system where ACMS Desktop is installed, and execute it. For example, on the PC: > ftp nodename ! Respond to login prompts ftp> binary ftp> cd /usr/examples/acmsdi/msdos ftp> get egcobol.exe 5.2.2 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.51 or higher o C run-time library that is compatible with Microsoft Visual C++ Version 1.5 5-6 Installing ACMS Desktop Portable API Services and Samples 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 Appendix B to set up the sample application on the DIGITAL ACMSxp system. You can sign in to the DIGITAL ACMSxp system and use the reserve task of the application. The installation procedure is now complete and verified. 5.2.2.1 DOS Sample Files Added to the System All C and COBOL language files (.c, .h, .cbl) listed in Table 5-6 are contained within the egcobol.exe self- extracting archive. Table_5-6_DOS_Sample_Files_________________________________ Name_______________Description_____________________________ ACMSDI.H Include file for ACMSDI (continued on next page) Installing ACMS Desktop Portable API Services and Samples 5-7 Table_5-6_(Cont.)_DOS_Sample_Files_________________________ Name_______________Description_____________________________ 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 DIGITAL UNIX 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 (continued on next page) 5-8 Installing ACMS Desktop Portable API Services and Samples Table_5-6_(Cont.)_DOS_Sample_Files_________________________ Name_______________Description_____________________________ 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.3 Using the Windows Client Services Normally when building applications under Windows, the DLL provided with ACMS Desktop are used, rather than the static-link libraries. The name of the DLL that will be used by ACMS Desktop for Windows is ACMSDI.DLL. The DLL must be included in the path, or be the default working directory for Windows. 5.2.4 Installing the Windows Sample Application The Windows Avertz sample is provided in a single file on the DIGITAL UNIX system as a self-extracting archive file in the /usr/examples/acmsdi/msw directory. The file, SDK31DLL.EXE, contains both the sample sources and the make file in order to build against the DLL. 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 DLLs: > ftp nodename !Respond to login prompts ftp> binary ftp> cd /usr/examples/acmsdi/mswindows/msw31 ftp> get sdk31dll.exe Installing ACMS Desktop Portable API Services and Samples 5-9 5.2.5 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.51 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. 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 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. 5-10 Installing ACMS Desktop Portable API Services and Samples 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. If you want the sample desktop client program to communicate with the DIGITAL ACMSxp application, follow the procedures in Appendix B to set up the sample application on the DIGITAL ACMSxp system. After you set up the DIGITAL ACMSxp system, use the Session menu to sign in to the DIGITAL 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. Installing ACMS Desktop Portable API Services and Samples 5-11 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. 5.2.5.1 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 contained in the self-extracting archive.. Table_5-7_Windows_Sample_Files_____________________________ Name_______________Description_____________________________ ACMSDI.H Include file for the ACMS Desktop API AVERTZ Makefile for building the sample (continued on next page) 5-12 Installing ACMS Desktop Portable API Services and Samples Table_5-7_(Cont.)_Windows_Sample_Files_____________________ Name_______________Description_____________________________ 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 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 DIGITAL UNIX system RECVW.C Presentation procedure stub (continued on next page) Installing ACMS Desktop Portable API Services and Samples 5-13 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 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-14 Installing ACMS Desktop Portable API Services and Samples 5.2.6 Installing the Visual Basic Sample Applications There is a Visual Basic sample applications provided in the DIGITAL UNIX installation directory, /usr/examples/acmsdi /mswindows/vb, in the form of self-extracting archive file, AVERTZVB.EXE. AVERTZVB.EXE contains the files for the same sample that was provided for ACMS Desktop V2.1, it is a blocking, no exchange I/O AVERTZ sample. To expand the archive, copy it in image mode to a clean directory on the PC and execute it. For example on the PC: > ftp nodename !Respond to login prompts ftp> binary ftp> cd /usr/examples/acmsdi/mswindows/vb ftp> get avertzvb.exe 5.2.6.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. Installing ACMS Desktop Portable API Services and Samples 5-15 5.2.6.2 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 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.3 Installing the Windows 95 API ACMS Desktop Version 2.2 supports Windows 95 using TCP/IP. The following sections describe how to install the ACMS Desktop interface for Windows 95. 5.3.1 Installing the Windows 95 Client Software The client services for Windows 95 are contained in a self-extracting archive in the DIGITAL UNIX installation directory /usr/etc/acmsdi/win95. 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 FTP, type the following: > ftp nodename !Respond to login prompts ftp> binary ftp> cd /usr/etc/acmsdi/win95 ftp> get win95.exe 5-16 Installing ACMS Desktop Portable API Services and Samples This makes available the DLL and reference library for the TCP/IP version of the client services for Windows 95. Common Files for Windows 95 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 Windows 95 specific files, there are some common files that are needed to build an application. These files are on the DIGITAL UNIX system in the directory /usr/etc/acmsdi/common: acmsdi.h forms.h ppstubs.c tdms.h Copy these files to the current directory, using FTP: > ftp nodename !Respond to login prompts ftp> cd /usr/etc/acmsdi/common ftp> ascii ftp> mget * 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 the DLL, acmsdi.dll. The acmsdi.dll provides TCP/IP support and works with the Windows 95 Winsock DLL called Wsock32.dll. Make sure that the acmsdi.dll file is in the working directory or in the executable path. Installing ACMS Desktop Portable API Services and Samples 5-17 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.2 supports the following Windows NT configuration for ACMS Desktop clients: Platform: Intel, Alpha Network Transport: TCP/IP Windows NT Version: Version 4.0 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 4.0 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 DIGITAL UNIX installation directories. /usr/etc/acmsdi/nt_alpha/nt_alpha.zip /usr/etc/acmsdi/nt_alpha/unzip_alpha.exe /usr/etc/acmsdi/nt_i86 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: > ftp nodename !Respond to login prompts ftp> binary ftp> cd /usr/etc/acmsdi/nt_i86 ftp> get nt_i86.exe 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 TCP/IP versions of the client services for NT. 5-18 Installing ACMS Desktop Portable API Services and Samples 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\acmsdi.dll - The client services for TCP/IP 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 DIGITAL UNIX system in the directory /usr /etc/acmsdi/common: acmsdi.h forms.h ppstubs.c tdms.h Copy those files to the current directory, for example, using FTP: > ftp nodename !Respond to login prompts ftp> binary ftp> cd /usr/etc/acmsdi/common ftp> ascii ftp> mget * If this default directory 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: Installing ACMS Desktop Portable API Services and Samples 5-19 set LIB=%LIB%;c:\acmsdi set INCLUDE=%INCLUDE%;c:\acmsdi set PATH=%PATH%;c:\acmsdi 5.5 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. 5.5.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 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. 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: 5-20 Installing ACMS Desktop Portable API Services and Samples server_ Node name of the DIGITAL UNIX system where node ACMS 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: Installing ACMS Desktop Portable API Services and Samples 5-21 1. Copy the ACMS Desktop Header and Presentation Procedure Stubs File: > cd acmsdi > ftp server_node !Respond to login prompts ftp> get /usr/etc/acmsdi/common/acmsdi.h ftp> get /usr/etc/acmsdi/common/ppstubs.c ftp> bye 2. Copy the ACMS Desktop client library: > su # cd /usr/lib # ftp server_node !Respond to login prompts ftp> binary ftp> cd /usr/etc/acmsdi/digital_unix ftp> get libacmsdi.a 3. Exit ftp: ftp> bye 4. Exit superuser mode: # > After these steps, you are ready to build ACMS Desktop applications that use TCP/IP as a transport. 5.5.1.1 API Files Added to the DIGITAL UNIX Desktop System Files listed in Table 5-9 are copied to the DIGITAL UNIX system during the installation of the ACMS Desktop services for DIGITAL UNIX software. Table_5-9_DIGITAL_UNIX_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-22 Installing ACMS Desktop Portable API Services and Samples 5.5.2 Installing the Motif Sample Client on DIGITAL UNIX To install the Motif sample files on the DIGITAL UNIX system, perform the following steps: 1. Create a directory on the 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: a. Copy the shell: > ftp server_node !Respond to login prompts ftp> cd /usr/examples/acmsdi/motif ftp> get load_motif.sh ftp> bye 3. Run load_motif: > sh load_motif.sh Enter location of sample files on DIGITAL UNIX host [/usr/examples/acmsdi/motif]: Enter Desktop Server Host Name: hostname Enter Username: username Enter Password: password Copying m_avertz resource file... Copying m_avertz.c... Copying m_avertz.h... . . . 5.5.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. ________________________ 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'. ______________________________________________________ Installing ACMS Desktop Portable API Services and Samples 5-23 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 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-24 Installing ACMS Desktop Portable API Services and Samples 5.5.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-10 are copied to the desktop system by the load_motif shell. Table_5-10_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 help.txt Overview of the AVERTZ user interface load_motif Command shell to download the Motif sample from the DIGITAL UNIX 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 [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-25 Table 5-10 (Cont.) Motif Sample Files for the DIGITAL UNIX ___________________System__________________________________ Name_____________Description_______________________________ 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 m_wkspaces.c Support routines for AVERTZ workspace structures m_wkspaces.h_____Defines_the_AVERTZ_workspace_structures___ 5-26 Installing ACMS Desktop Portable API Services and Samples 5.6 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 - /usr/examples/acmsdi/msdos - /usr/examples/acmsdi/mswindows o For the DIGITAL UNIX API-ACMS Desktop gateway system, if the following directories are protected against read access: - /usr/etc/acmsdi/common - /usr/etc/acmsdi/unix_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. Installing ACMS Desktop Portable API Services and Samples 5-27 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. 5-28 Installing ACMS Desktop Portable API Services and Samples 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 DIGITAL UNIX software on the DIGITAL UNIX 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. 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 DIGITAL UNIX 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 DIGITAL UNIX 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 DIGITAL UNIX 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 DIGITAL UNIX 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 DIGITAL UNIX 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. 2. Double click on the installer file. Installing the ACMS Desktop Macintosh System and Sample Software 6-3 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 DIGITAL UNIX system to your Macintosh; for example, Fetch, an FTP file transfer utility, is available as shareware. After you install ACMS Desktop on the host DIGITAL UNIX 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 DIGITAL UNIX 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.2. 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 . - Examples: This option installs the Examples. Use it as a follow-up installation to a Run-Time Services option or a System Services option. Installing the ACMS Desktop Macintosh System and Sample Software 6-5 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.2)". 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 DIGITAL UNIX 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 DIGITAL UNIX Is this correct? (y/n): y Checking file system space required to install selected subsets: File system space checked OK. Copyright Digital Equipment Corporation 1994, 1997. All rights reserved. Sample Listings A-1 Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c) (1) (ii) of DFARS 252.227-7013, or in FAR 52.227-19, or in FAR 52.227- 14 Alt. III, as applicable. This software is proprietary to and embodies the confidential technology of Digital Equipment Corporation. Possession, use, or copying of this software and media is authorized only pursuant to a valid written license from DIGITAL or an authorized sublicensor. ACMS Desktop for DIGITAL UNIX 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_v22_release_notes.txt (text) /usr/examples/acmsdi/acms_desktop_v22_release_ notes.ps (postscript) The installation for ACMS Desktop has completed # A.2 Sample Installation Verification Procedure # /usr/etc/acmsdi/ADIBAS220_IVP.csh Beginning IVP for ACMS Desktop Copyright (c) Digital Equipment Corporation, 1997 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 A-2 Sample Listings 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.2-0 has completed successfully. / ///////////////////////////////////////////////////////////////// Shutting down gateway. Sample Listings A-3 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 A-4 Sample Listings 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 DIGITAL ACMS Desktop for DIGITAL UNIX Application Development Guide. You can then run the DOS, Windows, and DIGITAL UNIX 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 installation fails due to insufficient disk space, the following message appears: There is not enough space for subset ACMS Desktop for DIGITAL UNIX ACMS Desktop (ACMS Desktop for DIGITAL UNIX) 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 DIGITAL UNIX Alpha documentation on system messages, recovery procedures, and DIGITAL UNIX Alpha 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 Forced Nonblocking _______________________________ Visual Basic Sample Files, API installation requirements, 5-16 5-3 I______________________________ C______________________________ Installation errors, 5-27 Copying the Installer, 6-4 Installing DIGITAL UNIX API, 5-20 D______________________________ DOS API, 5-5 DIGITAL UNIX Motif sample, DOS sample, 5-5 5-23 DOS Sample Application, 5-6 DIGITAL UNIX sample, 5-23 Visual Basic Samples, 5-15 Disk space, 6-3 Windows 95 API, 5-16 requirements, 5-3 Windows API, 5-5 Windows link library options, E 5-9 _______________________________ Windows NT API, 5-18 Examples option, 6-1 Windows NT client software, 5-18 F______________________________ Windows sample, 5-5 Files Windows Sample Application, API 5-9 added to DIGITAL UNIX Windows transport options, system, 5-22 5-9 sample Installing Windows 95 sample, added to DIGITIAL UNIX 5-18 system, 5-25 IVP added to nonWindows system error recovery, 4-3 , 5-7 operations performed by, 4-1 added to Windows system, running independently, 4-1 5-12 steps to run, 4-1 Index-1 M______________________________ R______________________________ Macintosh client installation Resources, 5-4 requirements, 6-2 Run-Time Services option, 6-1 Macintosh installation options Running the Installer, 6-4 , 6-1 S______________________________ P______________________________ Self-Extracting Archives, 5-5 Preparing to install Macintosh System Services option, 6-1 software, 6-2 Prerequisite software T______________________________ API, 5-2 Time to install, 5-3, 6-2 sample application, 5-2 Prerequisite software for V______________________________ Macintosh systems, 6-2 Verifying nonWindows sample, 5-6 Windows sample, 5-10 Visual Basic AVERTZ Sample Verifying installation, 5-15 Index-2