DECnet/SNA VMS Application Programming Interface (API) Installation Order Number: AA-EW86B-TE This document tells the user how to install the DECnet/SNA VMS Application Programming Interface Version 2.3 software. The document also explains how to configure the IBM software to communicate with the interface. Revision/Update Information: This is a new manual. Operating System and Version: VMS Version 5.0, 5.1, or 5.2 Software Version: DECnet/SNA VMS Application Programming Interface Version 2.3 Digital Equipment Corporation ________________________ May 1989 __________ The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document. The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license. No responsibility is assumed for the use or reliability of software on equipment that is not supplied by Digital Equipment Corporation or its affiliated companies. __________ Copyright ©1989 by Digital Equipment Corporation All Rights Reserved. Printed in U.S.A. __________ The postpaid READER'S COMMENTS form on the last page of this document requests the user's critical evaluation to assist in preparing future documentation. The following are trademarks of Digital Equipment Corporation: DEC DIBOL UNIBUS DEC/CMS EduSystem VAX DEC/MMS IAS VAXcluster DECnet MASSBUS VMS DECsystem-10 PDP VT DECSYSTEM-20 PDT DECUS RSTS DECwriter RSX DIGITAL This document was prepared using VAX DOCUMENT, Version 1.1 Contents ________________________________________________________________ __________________________________________________________ PREFACE vi ________________________________________________________________ CHAPTER 1 PREPARING FOR INSTALLATION 1-1 1.1 CHECKING THE DISTRIBUTION KIT 1-1 1.2 VMS SYSTEM REQUIREMENTS 1-2 1.2.1 Installation Requirements 1-2 1.2.1.1 VAX Supported Processors 1-4 1.2.1.2 VMS/SNA and Gateway Support 1-4 1.2.2 VMS License Management Facility Requirements 1-4 1.2.3 VMS Tailor Requirements 1-5 1.2.4 Calculating the Value for GBLSECTIONS 1-5 1.3 VAXCLUSTER CONSIDERATIONS 1-6 1.4 VAX OPTIONAL PRODUCTS 1-7 1.5 VMSINSTAL REQUIREMENTS 1-7 1.5.1 Using VMSINSTAL 1-8 1.6 ACCESSING THE ON-LINE RELEASE NOTES 1-9 iii ________________________________________________________________ CHAPTER 2 INSTALLING THE API 2-1 2.1 THE INSTALLATION PROCEDURE 2-1 2.1.1 Running VMSINSTAL 2-1 2.2 POSTINSTALLATION CONSIDERATIONS 2-7 2.2.1 Files Created During Installation 2-8 2.2.2 Installing the API as a Shareable Image 2-11 2.2.3 Running the Installation Verification Procedure 2-11 2.2.4 Adding the SNA_API Help File to the Help File of an Editor 2-11 2.2.5 License Management Facility in a VAXcluster 2-12 2.3 ERROR RECOVERY 2-12 2.3.1 Installation Verification Procedure Messages 2-13 2.4 SAMPLE INSTALLATION ON A VAX SYSTEM WITH OPTIONS N 2-15 2.5 SAMPLE INSTALLATION ON A VAX SYSTEM WITHOUT OPTIONS N 2-18 ________________________________________________________________ TABLES 1-1 Installation Specifications for the VMS API 1-2 1-2 Disk Space Requirements for the VMS API 1-3 2-1 File Locations After Installation 2-8 iv Preface ________________________________________________________________ The DECnet/SNA VMS Application Programming Interface (API) is a Digital Equipment Corporation software product that enables VAX users to communicate with programs running on IBM systems through one of Digital's interconnect systems. __________________________________________________________ Manual Objectives The DECnet/SNA VMS Application Programming Interface Installation manual provides the information needed to in- stall and verify the API software. __________________________________________________________ Intended Audience This manual is intended for system managers and network managers responsible for the installation of the Application Programming Interface. __________________________________________________________ Document Structure This document consists of two chapters. Chapter 1 Provides introductory information about Application Programming Interface. vi Chapter 2 Describes the installation process, including the Product Authorization Key (PAK) and Installation Verification Procedure (IVP). It also contains sample installations. __________________________________________________________ Associated Documents The following is a list of documents related to this product: o DECnet/SNA VMS Application Programming Interface Problem Solving o DECnet/SNA VMS Application Programming Interface Programming o DECnet/SNA Gateway Problem Determination Guide o VMS/SNA Problem Determination Guide o DECnet/SNA Guide to IBM Parameters o Guide to VAX/VMS Software Installation __________________________________________________________ Conventions Used in This Manual This manual uses the following conventions: _____________________________________________________________ Convention_______Meaning_____________________________________ UPPERCASE Represent constant values or symbols. Code LETTERS these exactly as they are specified. lowercase Represent variables for which you must italics supply a value. vii _____________________________________________________________ Convention_______Meaning_____________________________________ [ ] Square brackets enclose optional values. Do not type the brackets in the line of code. ( ) Parentheses enclose group values that must be specified for a parameter. These values must be typed in the line of code in the indicated order. Parentheses must be typed where they appear in a line of code. Special type Examples of system input and output are printed in special type. System output is in black; user input is in red. [RET] Unless otherwise specified, every command line is terminated by pressing the RETURN key. [CTRL/x] Control characters are shown as , where x is an alphabetic character. The CTRL key and the appropriate key should be _________________pressed_simultaneously._____________________ viii Chapter 1 Preparing for Installation ________________________________________________________________ Before you install the DECnet/SNA VMS Application Programming Interface software, referred to as API, you should prepare your system. This installation involves writing to your system disk. Digital Equipment Corporation recommends that you make a backup copy of your system disk before you begin. NOTE Unless stated otherwise, the term Gateway refers to the DECnet/SNA Gateway or VMS/SNA when used in this manual. __________________________________________________________ 1.1 Checking the Distribution Kit Before beginning the installation, check that you have a complete distribution kit by comparing the kit against the bill of materials (BOM). If any part of the kit is missing, contact your Digital representative. Each API kit consists of one or more volumes of software media (depending on the media) and a set of documentation. Preparing for Installation 1-1 __________________________________________________________ 1.2 VMS System Requirements This section discusses VMS requirements as well as calculat- ing parameter values for the API. __________________________________________________________ 1.2.1 Installation Requirements Before you install the API software, verify that the fol- lowing installation requirements and disk space requirements have been met: Table_1-1:__Installation_Specifications_for_the_VMS_API______ RequirementsSpecifications___________________________________ Software VMS Version 5.0, 5.1 and 5.2 Privileges System manager level Disk space 4700 blocks during installation 4600 blocks after installation Image 5 sections Global 257 pages Approximate 5 to 15 minutes, depending on the medium used instal- lation time 1-2 Preparing for Installation Table 1-1 (Cont.): Installation Specifications for the VMS ____________________API______________________________________ RequirementsSpecifications___________________________________ Associated The Guide to VAX/VMS Software Installation con- documents___tains_general_installation_information___________ Table_1-2:__Disk_Space_Requirements_for_the_VMS_API__________ Minimum for API installa- 4700 tion Permanent for API and all 4600 languages Permanent for API instal- 308 lation For ADA 3289 For BASIC 28 For BLISS 76 For C 103 For FORTRAN 99 For LIBRARY 30 For MACRO 56 For Pascal 310 Preparing for Installation 1-3 Table_1-2_(Cont.):__Disk_Space_Requirements_for_the_VMS_API__ For_PLI____________________147_______________________________ To determine how much permanent disk space you need after installation of a particular language, add the permanent disk space required for that language to the disk space required for API. For example, to the permanent disk space for BASIC, which is 28 blocks, add 308 blocks required for API. A total of 336 blocks are required. __________________________________________________________ 1.2.1.1 VAX Supported Processors Refer to the Software Product Description (SPD) for the latest official list of supported processors. __________________________________________________________ 1.2.1.2 VMS/SNA and Gateway Support Refer to the Software Product Description (SPD) or the System Support Addendum (SSA) for the latest official list of sup- ported versions of VMS/SNA software, and Gateway software and hardware. __________________________________________________________ 1.2.2 VMS License Management Facility Requirements Before you install API, you should register your Product Authorization Key (PAK) with the License Management Facility (LMF). The PAK, which contains information about the license, is a paper certificate shipped with the product. During the installation, the system prompts you asking if you have registered the Application Programming Interface license and loaded the appropriate Product Authorization Key (PAK). If you have not already done so, you can complete the installation and run the Installation Verification Procedure (IVP). The Application Programming Interface will not run 1-4 Preparing for Installation if you have not registered the license or loaded the PAK. Once you perform the license registration and have loaded the PAK, you will be able to run the Application Programming Interface. To register and load the license, log in to the system man- ager's account. Then type the following command: @ SYS$UPDATE:VMSLICENSE.COM When you are prompted for information, enter the data from your PAK. For more information on LMF, see the VMS License Management Utility Manual in the VMS documentation set. __________________________________________________________ 1.2.3 VMS Tailor Requirements The required classes are: VMS Required Save Set, Network Support, Programming Support, and Utilities. Be certain these classes are installed on your system before installing the product. Refer to VMS Tailor documentation in the VMS documentation set for more information. __________________________________________________________ 1.2.4 Calculating the Value for GBLSECTIONS Make sure that you have enough global pages and global sec- tions free. If there are not enough global pages and global sections, the API software cannot be installed as a shareable image. You can check the number of global pages and global sections available by entering the following commands: $ RUN SYS$SYSTEM:SYSGEN SYSGEN> SHOW GBLPAGES SYSGEN> SHOW GBLSECTIONS Preparing for Installation 1-5 You can then check the number of global pages and global sections in use by entering the following commands: $ INSTALL INSTALL> LIST/GLOBAL By subtracting the second set of values from the first, you can determine if there are enough global pages and global sections available for your use. If you need to modify these values, you must edit the SYS$SYSTEM:MODPARAMS.DAT file and include the following lines: ADD_GBLPAGES=257 ADD_GBLSECTIONS=5 After modifying these values, you must run AUTOGEN by using the following commands: $ @SYS$UPDATE:AUTOGEN SAVPARAMS GENPARAMS $ @SYS$UPDATE:AUTOGEN SETPARAMS REBOOT These commands will recompute your system parameters. AUTOGEN will also perform an automatic shutdown and reboot when it is finished. __________________________________________________________ 1.3 VAXcluster Considerations This layered product is fully supported when installed on any valid and licensed VAXcluster configuration, with the following restrictions: o The API must be installed and run on each node in the VAXcluster containing a synchronous communications inter- face connected to an IBM system. o When you run the API in interactive mode, you must run it from a node with a synchronous device interface and API locally installed. 1-6 Preparing for Installation __________________________________________________________ 1.4 VAX Optional Products For general background information on installing optional products on a VAX/VMS system, refer to the Guide to VAX/VMS Software Installation for Version 5.0 systems. This manual has an appendix dealing with optional product installation. __________________________________________________________ 1.5 VMSINSTAL Requirements Installing the Application Programming Interface on a VMS system involves running the VMSINSTAL procedure. The dialogue is self-explanatory. The system tells you to answer questions and waits for you to tell it to continue. Most questions require a simple YES (Y) or no (N) answer. The questions display default answers (where available) in the following way: [YES]: To answer a question with the default YES, press . When you invoke VMSINSTAL, it checks that: o You are logged in to a privileged account. o You have adequate quotas for installation. o All users are logged off. o DECnet is shut down. Note that the following explanation of VMSINSTAL deals with the simplest case; in actual practice, the procedure may ask other questions, depending on your configuration and the products already installed. Refer to the Guide to VAX/VMS Software Installation for a full description of how VMSINSTAL works. To install the distribution kit on your VMS host: o Log in to the system manager's account. Preparing for Installation 1-7 o Make sure you have backed up the system disk. o Make sure that you have at least 4700 free blocks on the system disk. o Make sure that you have 257 global pages free. (If there are not enough global pages, the API cannot be installed as a shareable image.) o Make sure you have five global sections free. o Make sure that all users are logged out and all batch jobs are complete. o Disable logins and DECnet. __________________________________________________________ 1.5.1 Using VMSINSTAL VMSINSTAL is a command procedure that installs VMS layered software products. The VMSINSTAL command line has the follow- ing format: $ @SYS$UPDATE:VMSINSTAL SNALU0nnn ddcu: [OPTIONS N] where: nnn represents the major version number and the current maintenance update in that version. The first and second digits represent the major version num- ber, and the third digit represents the current maintenance update version number. For the version number of your kit, refer to the label on the distribution kit or the BOM. If you do not supply the product name and version number, VMSINSTAL prompts you for them. ddcu represents a device name for the API installation media, where dd is the device code, c is the controller id, and u is the unit number. 1-8 Preparing for Installation It is not necessary to use the console drive. If you do not supply the device name, VMSINSTAL prompts you for it. MTA0: is the device name used in examples in this document. OPTIONS N is an optional parameter you should provide if you want to be prompted to display or print the release notes. If you do not include the OPTIONS N parameter, VMSINSTAL does not prompt you to display or print the release notes. When you install a product using VMSINSTAL, you have two installation options. Either you can enter the VMSINSTAL command line specifying the product name, version number, device name, and release notes option, or you can enter the following command: $ @SYS$UPDATE:VMSINSTAL If you enter the preceding command, VMSINSTAL prompts you for the product name, version number, and device name during the installation. If you use this command, you do not have the option of displaying or printing the release notes. __________________________________________________________ 1.6 Accessing the On-line Release Notes This product provides on-line release notes. You should review the release notes before installing the product. They contain the latest enhancements to the product, which may include changes to the installation procedure. If you specify the OPTIONS N parameter on the VMSINSTAL command line, the system prompts you regarding how you would like to see the release notes. After installing the product, you can read the release notes in the file SYS$HELP:SNALU0vvu.RELEASE_NOTES, where vv is the major version number and u is the update number (1 digit). Preparing for Installation 1-9 Chapter 2 Installing the API ________________________________________________________________ This chapter describes how to install the DECnet/SNA VMS Application Programming Interface, which this chapter refers to as the API. It contains a step-by-step description of the installation considerations. The final section includes actual system installation logs using PAK information and VMSINSTAL. __________________________________________________________ 2.1 The Installation Procedure The API installation consists of a series of questions and informational messages. The process takes 5 to 15 minutes to complete. __________________________________________________________ 2.1.1 Running VMSINSTAL Digital recommends that you use a hard-copy terminal for installing the Application Programming Interface if you would like a copy of the installation process. If you want a hard- copy terminal, you can produce a copy of the installation procedure in a file by typing: $ SET HOST 0/LOG=filename where: Installing the API 2-1 filename is the name of the file in which you want the log file stored. Step 1: Log in to system manager's account. To start the installation, invoke the VMSINSTAL command procedure from a privileged account, such as the SYSTEM account. Username: SYSTEM [RET] Password: [RET] Step 2: Invoke VMSINSTAL. Use the following syntax to invoke VMSINSTAL: $ @SYS$UPDATE:VMSINSTAL SNALU0nnn ddcn: OPTIONS N Replace nnn in the product name with the version number of the software, for example, SNALU0023. Replace ddcn with the name of the device on which you plan to mount the media, where dd is the device name, c is the controller ID, and n is the unit number. OPTIONS N is an optional parameter that indicates you want to be prompted to display or print the release notes, or copy them to SYS$HELP. If you do not include the OPTIONS N parameter, VMSINSTAL does not prompt you to display, print, or copy the release notes. Please read the release notes before proceeding with this installation. VAX/VMS Software Product Installation Procedure V5.0 It is dd-mmm-yyyy at hh::mm. Enter a question mark (?) at any time for help. 2-2 Installing the API Step 3: Product Installation Begins. VMSINSTAL displays a message that the media containing the API has been mounted on the specified device and that the installation has begun. Please mount the first volume of the set on ddcn: * Are you ready? YES %MOUNT-I-MOUNTED, SNALU0 mounted on _ddcn: The following products will be processed: SNALU0 Vn.n Beginning installation of SNALU0 Vn.n at hh::mm %VMSINSTAL-I-RESTORE, Restoring product saveset A... Wheren.n is automatically replaced with the version number of the API, for example, V2.3. Step 4: Select a release notes option. If you specified OPTIONS N when you invoked VMSINSTAL, the installation procedure prompts you for a release notes op- tion. Release Notes Options: 1. Display release notes 2. Print release notes 3. Both 1 and 2 4. Copy release notes to SYS$HELP 5. Do not display, print or copy release notes. Select option [2]: If you select option 1, VMSINSTAL displays the release notes immediately on your terminal. You can terminate the display at any time by pressing . Installing the API 2-3 If you select option 2 or 3, VMSINSTAL prompts you for a print queue name: Queue name [SYS$PRINT]: Enter a queue name or press RETURN to send the file to the default output print device, SYS$PRINT. No matter which option you select, VMSINSTAL then asks you if you want to continue the installation. Answer YES to continue or NO to exit VMSINSTAL. * Do you want to continue the installation? YES %VMSINSTAL-I-RELMOVED, The products release notes have been successfully moved to SYS$HELP. Step 5: Register the product with the License Management Facility. The installation procedure prints out information specific to the particular license and asks if you have registered and loaded your PAK for the Application Programming Interface. Product: SNA-API Producer: DEC Version: n.n Release Date: dd-mmm-yyyy * Does this product have an authorization key registered and loaded? If you have not registered and loaded your PAK, answer NO to this question. The installation reminds you to register the PAK before you run the product. The installation continues. 2-4 Installing the API Step 6: Select installation options. You have the option to purge files from previous versions of the Application Programming Interface that are superseded by this installation. Purging is recommended because it will save disk space. * Do you want to purge files replaced by this installation [YES]? The system now asks if you want to have the IVP run auto- matically at the end of the installation. The IVP for the Application Programming Interface checks to be sure that the installation is successful. You should run the IVP immedi- ately after installation. * Do you want to run the IVP after the installation [YES]? Press RETURN to exit from the procedure, unless you have more products to install using VMSINSTAL. When the procedure is complete, either reboot your system or enable logins and DECnet manually. Step 7: Select language symbols. You have the option of installing only those symbol files necessary for the programming languages you are using. You need 4138 blocks of disk space to install all the symbol files. If you do not want all the symbol files offered, answer NO to the following: * Would you like all the symbol files installed on this system [Y]? A NO answer to this question results in a list that displays the languages offered and the disk requirements for the symbol files of each of those languages. Installing the API 2-5 Please enter Yes (Y) or No (N) if you want the symbol files installed for the following languages: * ADA (3289 blocks) [N]? * BASIC (28 blocks) [N]? * BLISS (76 blocks) [N]? * CC (103 blocks) [N]? * FORTRAN (99 blocks) [N]? * LIBRARY (30 blocks) [N]? * MACRO (56 blocks) [N]? * PASCAL (310 blocks) [N]? * PLI (147 blocks) [N]? You have chosen the following languages: () * Is this OK [Y]? Step 9: Read informational message. The installation procedure now displays the following infor- mational message: %SNALU0-I-NOQUEST, No further questions will be asked The IVP for this product, SNALU0$IVP.COM, can be found in the SYS$TEST directory. To install the SNASHR.EXE, SNALU0SHR.EXE and SNALU0MSG.EXE images as shareable each time the system reboots, you must add the following line to your system startup procedure: $ @SYS$STARTUP:SNALU0$STARTUP On-line release notes for this product can be found in the file, SYS$COMMON:[SYSHLP]SNALU00nn.RELEASE_NOTES %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories ... 2-6 Installing the API Step 10: The IVP is run. The installation procedure calls the IVP to verify that the API software was successfully installed. The system displays the following messages: ** DECnet/SNA VMS Application Programming Interface Vn.n Installation Test ** .... Testing API Vn.n file locations .... Testing Basic API Vn.n .... Testing Extended API Vn.n ** DECnet/SNA VMS Application Programming Interface Vn.n Test Successful ** Step 11: End the installation procedure. The following messages indicate that the entire installation procedure is complete: Installation of SNALU0 Vn.n completed at hh::mm VMSINSTALL procedure done at hh::mm __________________________________________________________ 2.2 Postinstallation Considerations The installation procedure for API installs SNALU0SHR.EXE, SNASHR.EXE, SNALU0MSG.EXE, and SNAGWAMSG.EXE files as share- able images. Section 2.2.1 lists the files added to the system. To install API on other nodes that share a common system disk in a cluster environment, run the SYS$STARTUP:SNALU0$STARTUP.COM command procedure on each node. For nodes in a cluster envi- ronment that do not share a common system disk, the API must be installed on each node. Section 2.2.2 shows the command procedure for installing API as a shareable image. Installing the API 2-7 Verification of the installation can be done either during installation through the VMSINSTAL utility or at any other time by running the SNALU0$IVP.COM command procedure found in the SYS$TEST directory. This command procedure verifies that the API has been installed correctly on your system. It does not verify connection between IBM and the DECnet/SNA Gateway or VMS/SNA. Section 2.2.3 shows the command procedure for running the IVP. The API Help file can be added to an editor's Help file. Section 2.2.4 shows the command procedure for adding API Help. __________________________________________________________ 2.2.1 Files Created During Installation During installation, the files listed below are placed on your system. Note that these files are divided into two parts: basic and extended. The basic files correspond to Version 1.1 of the DECnet/SNA VMS Application Programming Interface and have been added so existing VMS applications have backward compatibility. The extended files add new func- tions for later versions. To maintain backward compatibil- ity, the modules are separated into two shareable images: SNASHR.EXE and SNALU0SHR.EXE. NOTE API V2.0 or later does not provide the object library, SNA.OLB. If you wish to use existing applications, you must link them with SNASHR.EXE. Table_2-1:__File_Locations_After_Installation________________ File_Name_____________Location_______________________________ Basic API 2-8 Installing the API Table_2-1_(Cont.):__File_Locations_After_Installation________ File_Name_____________Location_______________________________ SNASHR.EXE (SYS$SHARE) SNAGWAMSG.EXE (SYS$MESSAGE) SNALIBDEF.ADA (SYS$LIBRARY) SNALIBDEF.BAS (SYS$LIBRARY) SNALIBDEF.R32 (SYS$LIBRARY) SNALIBDEF.PAS (SYS$LIBRARY) SNALIBDEF.PEN (SYS$LIBRARY) SNALIBDEF.LIB (SYS$LIBRARY) SNALIBDEF.MAR (SYS$LIBRARY) SNALIBDEF.PLI (SYS$LIBRARY) SNALIBDEF.FOR (SYS$LIBRARY) SNALIBDEF.H (SYS$LIBRARY) Extended API SNALU023.RELEASE_ (SYS$HELP) NOTES SNALU0SHR.EXE (SYS$SHARE) SNALU0MSG.EXE (SYS$MESSAGE) Installing the API 2-9 Table_2-1_(Cont.):__File_Locations_After_Installation________ File_Name_____________Location_______________________________ SNALU0DEF.ADA (SYS$LIBRARY) SNALU0DEF.BAS (SYS$LIBRARY) SNALU0DEF.FOR (SYS$LIBRARY) SNALU0DEF.H (SYS$LIBRARY) SNALU0DEF.LIB (SYS$LIBRARY) SNALU0DEF.MAR (SYS$LIBRARY) SNALU0DEF.PAS (SYS$LIBRARY) SNALU0DEF.PEN (SYS$LIBRARY) SNALU0DEF.PLI (SYS$LIBRARY) SNALU0DEF.R32 (SYS$LIBRARY) SNALU0$STARTUP.COM (SYS$STARTUP) SNALU0$IVP.COM________(SYS$TEST)_____________________________ You can find HELP information for the API in the system help facility under the topic SNA_API. 2-10 Installing the API __________________________________________________________ 2.2.2 Installing the API as a Shareable Image The file SYS$STARTUP:SNALU0$STARTUP.COM contains the start- up command procedure for the API. To install the API as a shareable image, execute the command procedure as follows: $ @SYS$STARTUP:SNALU0$STARTUP Include the above command in your system start-up procedure to automatically install the API as a shareable image when you boot the system. __________________________________________________________ 2.2.3 Running the Installation Verification Procedure The Installation Verification Procedure (IVP) verifies the success of the installation. It checks that the new files were transferred to their proper locations and that files are not in the wrong location. If you encounter problems using the API, you should run the IVP as a first step in finding a solution. The IVP is designed to catch problems with missing files and old files left on your system. If a problem develops with the API, run the IVP first. To run the IVP after you install the product, invoke the command: $ @SYS$TEST:SNALUO$IVP If the IVP fails, correct the situation, and run the IVP again. Section 2.3.1 describes IVP failures in more detail. __________________________________________________________ 2.2.4 Adding the SNA_API Help File to the Help File of an Editor The API HELP information that is added to the HELPLIB file during installation can also be inserted into the HELP file of an editor for programmers who use editors to develop DECnet/SNA or VMS/SNA applications. The following commands Installing the API 2-11 perform this operation. These commands require system manager privileges. $ LIBRARY/HELP/EXTRACT=SNA API/OUTPUT=SNAAPI SYS$HELP:HELPLIB $ LIBRARY/HELP/INSERT SYS$HELP:xxxHELP SNAAPI $ DELETE SNAAPI.HLP;* where xxx is the name of your editor. For example, EDT or LSE. __________________________________________________________ 2.2.5 License Management Facility in a VAXcluster Refer to the VMS License Management Utility Manual for infor- mation on managing licenses in a VAXcluster environment. __________________________________________________________ 2.3 Error Recovery If errors occur during the installation or when the IVP is running, VMSINSTAL displays error messages. Errors can occur during the installation if any of the fol- lowing conditions exist: 1.The operating system version is incorrect. 2.A prerequisite software version is incorrect. 3.Quotas necessary for successful installation are insuffi- cient. 4.System parameter values for successful installation are insufficient. 5.The VMS help library is currently in use. 6.The product is not properly licensed. 7.Your system has insufficient disk space. 2-12 Installing the API For descriptions of the error messages generated by these conditions, see the VMS documentation on system messages, recovery procedures, and VMS software installation. If any of these conditions exist, you should take the appropriate action as described in the message. (You might need to change a system parameter or increase an authorized quota value.) These requirements are part of the installation requirements in Chapter 1 of this manual. __________________________________________________________ 2.3.1 Installation Verification Procedure Messages This section shows the different messages that the SNALU0$IVP command procedure displays: Beginning IVP Installation ** DECnet/SNA VMS Application Programming Interface Vn.n Installation Test ** Error Messages %SNALU0$IVP-E-FILNOTFOU, the following files were not found: This message displays a list of files not found. The list will include one, some, or all of the following files: Installing the API 2-13 SYS$SHARE:SNASHR.EXE SYS$SHARE:SNALU0SHR.EXE SYS$MESSAGE:SNALU0MSG.EXE SYS$MESSAGE:SNAWAMSG.EXE %SNALU0$IVP-F-ASSEMFAI, failed to assemble Basic API Vn.n test program %SNALU0$IVP-E-LINKFAI, failed to link Basic API Vn.n test program with SNASHR.EXE %SNALU0$IVP-E-RUNFAI, failed to run Basic API Vn.n test program $SNALU0$IVP-F-ASSEMFAI, failed to assemble Extended API Vn.n test program $SNALU0$IVP-E-LINKFAI, failed to link Extended API Vn.n test program with SNALU0SHR.EXE $SNALU0$IVP-E-RUNFAI, failed to run Extended API Vn.n test program Completing IVP Installation ** DECnet/SNA VMS Application Programming Interface Vn.n Test Successful ** ** DECnet/SNA VMS Application Programming Interface Vn.n Test FAILED ** 2-14 Installing the API __________________________________________________________ 2.4 Sample Installation on a VAX System with OPTIONS N A sample of the entire installation procedure follows: $ @SYS$UPDATE:VMSINSTAL SNALU0023 MUA0 VAX/VMS Software Product Installation Procedure V5.0 It is 01-MAY-1989 at 20:45 Enter a question mark (?) at any time for help. * Are you satisfied with the backup of your system disk [YES]? Please mount the first volume of the set on MUA0: The following products will be processed: SNALU0 V2.3 Beginning installation of SNALU0 V2.3 at 20:45 %VMSINSTAL-I-RESTORE, Restoring product saveset A... Release Notes Options: 1. Display release notes 2. Print release notes 3. Both 1 and 2 4. Copy release notes to SYS$HELP 5. Do not display, print or copy release notes * Select option [2]: 4 * Do you want to continue the installation? YES %VMSINSTAL-I-RELMOVED, The products release notes have been successfully moved to SYS$HELP. Product: SNA-API Producer: DEC Version: 2.3 Release Date: 28-APR-1989 Installing the API 2-15 * Does this product have an authorization key registered and loaded? YES * Do you want to purge files replaced by this installation [YES]? * Do you want to run the IVP after the installation [YES]? Installing all the symbol files for the supported languages requires 4138 blocks of permanent storage. * Would you like all the symbol files installed on this system [Y]? NO Please enter Yes (Y) or No (N) if you want the symbol files installed for the following languages: * ADA (3289 blocks) [N]? Y * BASIC (28 blocks) [N]? Y * BLISS (76 blocks) [N]? Y * CC (103 blocks) [N]? Y * FORTRAN (99 blocks) [N]? Y * LIBRARY (30 blocks) [N]? Y * MACRO (56 blocks) [N]? Y * PASCAL (310 blocks) [N]? Y * PLI (147 blocks) [N]? Y You have chosen the following languages: (ADA,BASIC,BLISS,CC,FORTRAN,LIBRARY,MACRO,PASCAL,PLI) * Is this OK [Y]? %SNALU0-I-NOQUEST, No further questions will be asked The IVP for this product, SNALU0$IVP.COM, can be found in the SYS$TEST directory. To install the SNASHR.EXE, SNALU0SHR.EXE and SNALU0MSG.EXE images as shareable each time the system reboots, you must add the following line to your system startup procedure: $ @SYS$STARTUP:SNALU0$STARTUP On line release notes for this product can be found in the file, SYS$COMMON:[SYSHLP]SNALU0023.RELEASE_NOTES %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... ** DECnet/SNA VMS Application Programming Interface V2.3 Installation Test ** 2-16 Installing the API .... Testing API V2.3 file locations .... Testing Basic API V2.3 .... Testing Extended API V2.3 ** DECnet/SNA VMS Application Programming Interface V2.3 Test Successful ** Installation of SNALU0 V2.3 completed at 20:50 VMSINSTAL procedure done at 20:50 $ Installing the API 2-17 __________________________________________________________ 2.5 Sample Installation on a VAX System without OPTIONS N A sample of the entire installation procedure (without OPTIONS N) follows: $ @SYS$UPDATE:VMSINSTAL SNALU0023 MUA0 VAX/VMS Software Product Installation Procedure V5.0 It is 01-MAY-1989 at 18:08 Enter a question mark (?) at any time for help. * Are you satisfied with the backup of your system disk [YES]? Please mount the first volume of the set on MUA0: * Are you ready? Yes %MOUNT-I-MOUNTED, SNALU0 mounted on _MUA0: The following products will be processed: SNALU0 V2.3 Beginning installation of SNALU0 V2.3 at 18:08 %VMSINSTAL-I-RESTORE, Restoring product saveset A... %VMSINSTAL-I-RELMOVED, The products release notes have been successfully moved to SYS$HELP. Product: SNA-API Producer: DEC Version: 2.3 Release Date: 28-APR-1989 * Does this product have an authorization key registered and loaded? * Do you want to purge files replaced by this installation [YES]? * Do you want to run the IVP after the installation [YES]? Installing all the symbol files for the supported languages requires 4138 blocks of permanent storage. * Would you like all the symbol files installed on this system [Y]: %SNALU0-I-NOQUEST, No further questions will be asked 2-18 Installing the API The IVP for this product, SNALU0$IVP.COM, can be found in the SYS$TEST directory. To install the SNASHR.EXE, SNALU0SHR.EXE and SNALU0MSG.EXE images as shareable each time the system reboots, you must add the following line to your system startup procedure $ @SYS$STARTUP:SNALU0$STARTUP On-line release notes for this product can be found in the file, SYS$COMMON:[SYSHLP]SNALU0023.RELEASE_NOTES %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... ** DECnet/SNA VMS Application Programming Interface V2.3 Installation Test ** .... Testing API V2.3 file locations .... Testing Basic API V2.3 .... Testing Extended API V2.3 ** DECnet/SNA VMS Application Programming Interface V2.2 Test Successful ** Installation of SNALU0 V2.3 completed at 18:19 VMSINSTAL procedure done at 18:19 $ Installing the API 2-19