
 















             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 <CTRL/x>,
                              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 <RET>.

             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 <CTRL/C>.

                                                   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
