Digital SNA 3270 Application_Services__________________________ Installation (Digital UNIX) Part Number: AA-Q7VVB-TE July 1996 This document describes how to install the Digital SNA 3270 Application Services software on an Alpha AXP system running the Digital UNIX operating system. Revision/Update Information: This is a revised manual. Operating System and Version: Digital UNIX V3.2c Software Version: Digital SNA 3270 Application Services V1.2 Electronic Data Systems Corporation and Digital Equipment Corporation make no representations that the use of their 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. The information in this document is subject to change without notice and should not be construed as a commitment from Electronic Data Systems Corporation or Digital Equipment Corporation. Electronic Data Systems Corporation and Digital Equipment Corporation assume no responsibility for any errors that may appear in this document. Digital conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community. Copyright (© 1996 Electronic Data Systems Corporation. All Rights Reserved. Copyright © 1992, 1994. Digital Equipment Corporation. All Rights Reserved. The following are trademarks of Digital Equipment Corporation: Alpha AXP, DEC, DEC SNA Domain Gateway, DECnet, OpenVMS, ULTRIX, VAX, and the DIGITAL logo. The following are third-party trademarks: IBM is a registered trademark of International Business Machines Corporation. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Co. Ltd. This document is available on CD-ROM. ________________________________________________________________ Contents Preface.................................................. v 1 Preparing to Install the Digital SNA 3270 Application Services Software 1.1 Inspecting the Distribution Kit.............. 1-1 1.2 System Requirements.......................... 1-1 1.2.1 Required Hardware........................ 1-1 1.2.2 Required Software........................ 1-2 1.2.3 Installation Time........................ 1-2 1.3 Preparing to Install......................... 1-2 1.3.1 Checking the Currently Installed Version Level.................................... 1-3 1.3.2 Obtaining Superuser Privileges........... 1-3 1.3.3 Backing Up Your System................... 1-3 1.3.4 Removing Any Previous Version of the Digital 3270 Application Services Software................................. 1-3 1.3.5 Verifying Disk Space..................... 1-4 1.3.6 Reading the Release Notes................ 1-4 1.3.7 Registering the Product Authorization Key (PAK).................................... 1-5 1.4 Stopping the Installation.................... 1-7 2 Installing the Digital SNA 3270 Application Services Software 2.1 Installation from the CD-ROM or Your Network...................................... 2-1 2.1.1 Installing from a CD-ROM Drive........... 2-1 2.1.2 Installing over the Local Area Network with RIS................................. 2-3 iii 2.2 Possible Installation Errors................. 2-3 3 After Installing the Digital SNA 3270 Application Services Software 3.1 Running the Digital SNA 3270 Application Services Installation Verification Procedure (IVP)........................................ 3-1 3.2 IVP Error Messages........................... 3-2 3.3 Accessing the Digital SNA 3270 Application Services Man Page............................ 3-2 3.4 Deleting the Digital SNA 3270 Application Services Software from Your System........... 3-3 3.5 Determining and Reporting Problems........... 3-3 A Sample Installation Dialog B Files Installed on Your System B.1 Files Created................................ B-1 B.2 Softlinks Created............................ B-1 iv ________________________________________________________________ Preface Purpose of This Guide The Digital SNA 3270 Application Services software is a Digital Equipment Corporation product that provides a library of routines that you can call from your application. This product allows an IBM® 3270 user in an IBM SNA network to access Digital[TM] applications that support the processing of 3270 data streams. The Digital SNA 3270 Application Services software provides communications functions allowing the Digital application to send and receive 3270 data streams and SNA character strings (SCS). This guide explains how to install the Digital SNA 3270 Application Services software on Alpha AXP[TM] processors that are running the Digital UNIX operating system. Keep this document with your distribution kit as you will need it to install maintenance updates or to reinstall Digital SNA 3270 Application Services software for any other reason. The postage-prepaid Reader's Comments form on the last page of this document requests the user's critical evaluation to assist us in preparing future documentation. Intended Audience This manual is written for the system manager responsible for installing the Digital SNA 3270 Application Services software. v Structure This manual consists of the following chapters and appendixes: o Chapter 1 lists prerequisites for installing the Digital SNA 3270 Application Services software. o Chapter 2 describes the installation of the Digital SNA 3270 Application Services software on your Digital system. o Chapter 3 describes various procedures you may wish to use after installing the Digital SNA 3270 Application Services software. o Appendix A contains a sample installation. o Appendix B lists the files installed during the installation process. Associated Digital SNA 3270 Application Services Documents The other document in the Digital SNA 3270 Application Services documentation set is the following: o Digital SNA 3270 Application Services Programming and Management Associated Digital Documents You should have the following Digital documents available for reference: o DEC SNA Domain Gateway Installation o DEC SNA Domain Gateway Management o DEC SNA Domain Gateway Guide to IBM Resource Definition o Digital UNIX Programmer's Guide o Digital UNIX Guide to Programming Support Tools o Digital UNIX Guide to DECthreads o Digital UNIX Network Programmer's Guide vi Associated IBM Documents You should have the following IBM documents available for reference: o IBM 3174 Establishment Controller Functional Description (IBM Order No. GA23-0218) o IBM 3270 Data Stream Programmer's Reference (IBM Order No. GA23-0059) o IBM 3274 Control Unit Description and Programmer's Guide (IBM Order No. GA23-0061) o Systems Network Architecture - Sessions Between Logical Units (IBM Order No. GC20-1868) o Systems Network Architecture Concepts and Products (IBM Order No. GC30-3072) o Systems Network Architecture Reference Summary (IBM Order No. GA27-3136) o Systems Network Architecture Technical Overview (IBM Order No. GC30-3073) Conventions Used in This Guide Special type This special type in examples indicates system output or user input. Boldface Boldface type in examples indicates user input. UPPERCASE/lowercasUppercase and lowercase letters in command lines or in examples must be entered as shown. lowercase Lowercase italics in command syntax or italics examples indicate variables for which either the user or the system supplies a value. [ ] Square brackets include optional values. Do not type the brackets in the line of code. vii ( ) 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. Indicates that you press the specified key. Indicates that you should hold the Control key down and press the key specified by x. Indicates that you press the Return key. % This is the default user prompt. # This is the default superuser prompt. Acronyms IVP Installation Verification Procedure LDB LMF's License Database LMF Digital's License Management Facility PAK Product Authorization Key RIS Remote Installation Services SCS SNA character strings SNA IBM's Systems Network Architecture SPD Software Product Description SPR Software Performance Report viii 1 ________________________________________________________________ Preparing to Install the Digital SNA 3270 Application Services Software This chapter discusses the planning you must do prior to installing the Digital SNA 3270 Application Services product. Planning issues covered here include an overview of the installation procedure, system requirements, software license Product Authorization Key requirements, and other system dependencies. 1.1 Inspecting the Distribution Kit The software Bill of Materials (BOM) that shipped with your Digital SNA 3270 Application Services media distribution kit lists the contents of the kit. Carefully compare the items you received with the items listed in the BOM. If any components are missing or damaged, contact your Digital representative before continuing. 1.2 System Requirements This section lists and describes the hardware and software requirements your site must meet in order to install the Digital SNA 3270 Application Services software. 1.2.1 Required Hardware To install the Digital SNA 3270 Application Services software successfully, you must have the following minimum hardware configuration: o Alpha AXP workstation or server See the Software Product Description (SPD) for a list of the processors that support the Digital SNA 3270 Application Services software. The SPD ships with the software distribution kit. Preparing to Install the Digital SNA 3270 Application Services Software 1-1 In addition to the Alpha AXP workstation or server, you will need specific hardware for the DEC SNA Domain Gateway product. Refer to the Domain Gateway SPD for more information. 1.2.2 Required Software The following software is required to support the Digital SNA 3270 Application Services software: o Digital UNIX V3.2c or later o DEC SNA Domain Gateway V2.0 or later See the SPD for a complete list of software required to support the Digital SNA 3270 Application Services software. 1.2.3 Installation Time Installation of the Digital SNA 3270 Application Services software requires less than three minutes. 1.3 Preparing to Install Before you begin the actual installation, prepare your system for the Digital SNA 3270 Application Services software. Preparation includes the following activities: 1. For maintenance releases, checking the currently installed version level. 2. Obtaining superuser privileges. 3. Optionally, backing up your system disk. Digital strongly recommends that you perform a full system backup before installation. 4. Removing any previous version of the Digital 3270 Application Services software. 5. Checking for sufficient system disk space. 6. Reading the product's release notes. 7. Registering your Product Authorization Key (PAK). 1-2 Preparing to Install the Digital SNA 3270 Application Services Software 1.3.1 Checking the Currently Installed Version Level If you are installing a maintenance release, you should verify that the version you are about to install is greater than the version currently on your system. To check the version of the currently installed Digital SNA 3270 Application Services software, use the following command: # what -s /usr/shlib/libr3270.so 1.3.2 Obtaining Superuser Privileges To install the Digital SNA 3270 Application Services software, you must have superuser privileges. To acquire these privileges, issue the following command followed by the root password. See the Digital UNIX system manager documentation for more details. % su password: password # 1.3.3 Backing Up Your System Before installing the Digital SNA 3270 Application Services software, back up your system disk. See the document Digital UNIX Guide to System Administration for further details. 1.3.4 Removing Any Previous Version of the Digital 3270 Application Services Software Before you install this version of the Digital SNA 3270 Application Services software, you should remove any existing version of the Digital SNA 3270 Application Services software now on your system. Use the following command to see whether a version of the Digital SNA 3270 Application Services software is installed on your system: # setld -i | grep "R3270" The system displays the R3270 subset with the word "installed" if the subset is installed. Preparing to Install the Digital SNA 3270 Application Services Software 1-3 To delete the software from your system, log in as superuser and issue the setld command with the -d option, as follows: # setld -d R3270* 1.3.5 Verifying Disk Space Check the free disk space on your system. You must have sufficient free space to install the Digital SNA 3270 Application Services software. The installation will fail if there is insufficient space for copying the software from the distribution media. Minimum space requirements for the Digital SNA 3270 Application Services software are as follows: o 2 Mb in the /usr partition. To check the free space in the /usr partition, enter the following command: # df -k /usr 1.3.6 Reading the Release Notes Before you install the Digital SNA 3270 Application Services software, you should read the product release notes. To access the release notes, do the following: 1. Determine the location of the Digital SNA 3270 Application Services files on the Consolidated Software Distribution CD-ROM. See the master index table in the document Consolidated Software Distribution Disk User's Guide for the directory containing the files. 2. Insert the CD-ROM into the drive and mount the disk using the drive's device name. If you do not know the device name, issue the following command to list available drives. The drive will be either RRD40 or RRD42. # file /dev/rr*c To mount the disk, issue the following command, where dev-name is the device name of your drive. # mount -r -d /dev/dev-name /mnt 1-4 Preparing to Install the Digital SNA 3270 Application Services Software 3. Search the directory on the CD-ROM where the Digital SNA 3270 Application Services files are located for the file R3270_V12-0.release_notes. 1.3.7 Registering the Product Authorization Key (PAK) The Digital SNA 3270 Application Services software supports the License Management Facility (LMF). You must register your License Product Authorization Key (License PAK) in the License Database (LDB) to use the Digital SNA 3270 Application Services software on a newly licensed node. LMF maintains a file of registered software license PAKs. Also, LMF keeps a library of functions used by Digital licensed software. Four licenses are available for the Digital 3270 Application Services software product. LMF checks for the existence of these licenses in the following order: o SNA-3270-SVCS-DEV o SNA-3270-SVCS-RT o SNA-3270-SVCS-DEV-USER o SNA-3270-SVCS-RT-USER If LMF does not find any of these licenses, the error message will display the last license in this list. To register the Digital SNA 3270 Application Services software license PAK using LMF, proceed as follows: 1. Log on to your system as superuser. % su password: password # 2. Issue the following command from the su prompt. Press after the confirmation message appears: # lmfsetup Register PAK (type q or quit to exit) [template] Preparing to Install the Digital SNA 3270 Application Services Software 1-5 3. After you confirm the procedure, the system prompts you for information related to the fields on your PAK form. This form ships with your Digital SNA 3270 Application Services software distribution kit if you ordered the license and media together. Otherwise, Digital ships it separately to a location based on your license order. Using the information from your Digital SNA 3270 Application Services software PAK, reply to each question. Any fields left blank in your PAK should be left blank when you key in the data. 4. After you have answered all questions, the system issues the following completion message. Enter quit and press Return: Register PAK (type q or quit to exit) [template] quit 5. After leaving lmfsetup, issue the following reset command: # lmf reset 6. If you attempted to load a PAK when a previous PAK was already installed, a message similar to the following appears: Combine SNA-3270-SVCS-DEV auth-num with SNA-3270-SVCS-DEV auth-num 7. After completing the LMF procedure, verify your registration: # lmf list For further information concerning the use of the LMF software or for more details about obtaining a license and PAK, see the document Digital UNIX Guide to Software License Management. You can also reference the lmf and lmfsetup man pages (lmf(8) and lmfsetup(8)). This completes the preinstallation procedure for the Digital SNA 3270 Application Services software. Chapter 2 describes the actual installation process. 1-6 Preparing to Install the Digital SNA 3270 Application Services Software 1.4 Stopping the Installation To stop the installation at any time, press . You must then delete files created up to this point interactively. The directories and files created during the Digital SNA 3270 Application Services software installation are listed in Appendix B. Preparing to Install the Digital SNA 3270 Application Services Software 1-7 2 ________________________________________________________________ Installing the Digital SNA 3270 Application Services Software This chapter describes the procedure for installing the Digital SNA 3270 Application Services software. Before installing the software, you must register your software license PAK using LMF; see Chapter 1 for details. 2.1 Installation from the CD-ROM or Your Network You can install the Digital SNA 3270 Application Services software from two locations: the Consolidated Software Distribution CD-ROM or a remote node in your local area network using the Remote Installation Service (RIS). 2.1.1 Installing from a CD-ROM Drive To install the Digital SNA 3270 Application Services software from the Consolidated Software Distribution CD-ROM, do the following: 1. Determine the location of the Digital SNA 3270 Application Services files on the CD-ROM. See the master index table in the document Consolidated Software Distribution Disk User's Guide for the directory containing the files. 2. Insert the CD-ROM into the drive and mount the disk using the drive's device name. If you do not know the device name, issue the following command to list available drives. The drive will be either RRD40 or RRD42. # file /dev/rr*c To mount the disk, issue the following command, where dev-name is the device name of your drive. # mount -r -d /dev/dev-name /mnt Installing the Digital SNA 3270 Application Services Software 2-1 3. Install the Digital SNA 3270 Application Services software using the setld command, where r3270 is the name of the directory on the CD-ROM where the Digital SNA 3270 Application Services files are located: # setld -l /mnt/r3270 R3270BASE120 After you enter the setld command, the system displays the following messages. Digital SNA 3270 Application Services V1.2-0 (Rev. 0) for Digital UNIX (c) Electronic Data Systems Corporation 1996. All Rights Reserved. (c) Digital Equipment Corporation 1992, 1994. All Rights Reserved. This software is proprietary to and embodies the confidential technology of Electronic Data Systems Corporation and Digital Equipment Corporation. Possession, use, duplication or dissemination of this software and media is authorized only pursuant to a valid written license from Digital Equipment Corporation or an authorized sublicensor. 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. ********************* N O T E ************************* * * * You must register a licensed PAK for * * Digital SNA 3270 Application Services for Digital UNIX * * first before you begin using this product. * * * * If you have not done so, after the installation, * * use your specific PAK data to register and load * * the license with the following commands: * * * * lmfsetup * * lmf reset * * * ************************************************************ This installation will complete in about 1-3 minutes depending on processor type. 2-2 Installing the Digital SNA 3270 Application Services Software Digital SNA 3270 Services run-time library base kit Copying from /mnt/r3270 (disk) Verifying Creating softlinks for R3270BASE120 ... done. Release notes may be found in /usr/sna/R3270_V12-0_release_notes Digital SNA 3270 Application Services V1.2-0 (Rev. 0) for Digital UNIX successfully installed Configuring "Digital SNA 3270 Services run-time library base kit" (R3270BASE120) 2.1.2 Installing over the Local Area Network with RIS If you are installing the Digital SNA 3270 Application Services software over your local area network, use the Remote Installation Service (RIS) utility. See the Reference Pages in Section 8 of the document Guide to Sharing Software on LAN for RIS requirements. Issue the following command, where host-name is the name of the node from which you are loading the software. # setld -l host-name: The installation then proceeds as described in the previous section. 2.2 Possible Installation Errors If an error occurs during the installation procedure, the procedure displays one of the following three failure messages: File system space check This error indicates that the installation procedure did not find enough space in the /usr partition. You should increase the available space to at least 2 MB and retry the installation. Platform check The Digital SNA 3270 Application Services software must be installed on a Alpha AXP processor. This error indicates that the installation procedure detected a processor other than an Alpha AXP processor. Installing the Digital SNA 3270 Application Services Software 2-3 Operating system check The Digital SNA 3270 Application Services software must be installed on Alpha AXP processors running the Digital UNIX V3.2c (or greater) operating system. This error indicates that the installation procedure detected a processor running an earlier version of the Digital UNIX operating system. 2-4 Installing the Digital SNA 3270 Application Services Software 3 ________________________________________________________________ After Installing the Digital SNA 3270 Application Services Software This chapter describes the procedures for running the Digital SNA 3270 Application Services IVP, deleting the files created during the installation, and reporting problems to Digital. 3.1 Running the Digital SNA 3270 Application Services Installation Verification Procedure (IVP) You can run the Digital SNA 3270 Application Services IVP at any time. To run the Digital SNA 3270 Application Services IVP, use the following command: # setld -v R3270BASE120 After you enter the setld command, the system displays the following messages. Digital SNA 3270 Application Services run-time library base kit (R3270BASE120) Beginning IVP for Digital SNA 3270 Application Services V1.2-0 for Digital UNIX (c) Digital Equipment Corporation. 1992, 1996. All Rights Reserved. This software is proprietary to and embodies the confidential technology of Electronic Data Systems Corporation and Digital Equipment Corporation. Possession, use, duplication or dissemination of this software and media is authorized only pursuant to a valid written license from Digital Equipment Corporation or an authorized sublicensor. 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. Verifying files are in their correct locations Creating r3270_ivp executable After Installing the Digital SNA 3270 Application Services Software 3-1 Executing r3270_ivp IVP has succeeded Digital SNA 3270 Application Services V1.2-0 for Digital UNIX IVP succeeded 3.2 IVP Error Messages If the IVP detects an error condition, it displays the following line: Digital SNA 3270 Application Services V1.2 for Digital UNIX IVP failed This line is preceded by one of the following error messages: Files are missing from the system The IVP detected missing files. You should reinstall the product. If this fails to correct the problem, see Section 3.5. The IVP compile failed The IVP procedure failed to compile. Check the compiler and retry. If the IVP fails again, reinstall the product. If this fails to correct the problem, see Section 3.5. The IVP run failed The IVP procedure failed to run. Check that the LMF PAK is installed and retry. If the IVP fails again, reinstall the product. If this fails to correct the problem, see Section 3.5. 3.3 Accessing the Digital SNA 3270 Application Services Man Page The Digital SNA 3270 Application Services product includes a man page. To access the man page, enter the following command: # man r3270 3-2 After Installing the Digital SNA 3270 Application Services Software 3.4 Deleting the Digital SNA 3270 Application Services Software from Your System You may find it necessary to delete the Digital SNA 3270 Application Services files from your system. To delete the software from your system, log in as superuser and issue the setld command with the -d option, as follows: # setld -d R3270BASE120 3.5 Determining and Reporting Problems If you encounter a problem while using the Digital SNA 3270 Application Services software, report it to Digital. First, determine the version of the Digital SNA 3270 Application Services software (see Section 1.3.1) and the Digital UNIX operating system software. Then, depending on the nature of the problem and the type of support you have, you can take one of the following actions: o Call Digital if your software contract or warranty agreement entitles you to telephone support. o Submit a Software Performance Report (SPR). o Fill out and submit a Reader's Comments form if the problem has to do with the documentation. There is a Reader's Comments form at the back of each manual. Use the form from the manual in which you found the error. Include the section and page number. Review the Software Product Description (SPD) and Warranty Addendum for an explanation of the warranty. If you encounter a problem during the warranty period, report the problem as just indicated or follow alternate instructions provided by Digital for reporting SPD nonconformance problems. After Installing the Digital SNA 3270 Application Services Software 3-3 A ________________________________________________________________ Sample Installation Dialog This appendix contains a sample installation dialog for the Digital SNA 3270 Application Services software. # setld -l /mnt/r3270 R3270BASE120 Digital SNA 3270 Application Services V1.2-0 (Rev. 0) for Digital UNIX (c) Electronic Data Systems Corporation 1996. All Rights Reserved. (c) Digital Equipment Corporation 1992, 1994. All Rights Reserved. This software is proprietary to and embodies the confidential technology of Electronic Data Systems Corporation and Digital Equipment Corporation. Possession, use, duplication or dissemination of this software and media is authorized only pursuant to a valid written license from Digital Equipment Corporation or an authorized sublicensor. 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. ********************* N O T E ************************* * * * You must register a licensed PAK for * * Digital SNA 3270 Application Services for Digital UNIX * * first before you begin using this product. * * * * If you have not done so, after the installation, * * use your specific PAK data to register and load * * the license with the following commands: * * * * lmfsetup * * lmf reset * * * ************************************************************ Sample Installation Dialog A-1 This installation will complete in about 1-3 minutes depending on processor type. Digital SNA 3270 Services run-time library base kit Copying from . (disk) Verifying Creating softlinks for R3270BASE120 ... done. Release notes may be found in /usr/sna/R3270_V12-0_release_notes Digital SNA 3270 Application Services V1.2-0 (Rev. 0) for Digital UNIX successfully installed Configuring "Digital SNA 3270 Services run-time library base kit" (R3270BASE120) # A-2 Sample Installation Dialog B ________________________________________________________________ Files Installed on Your System This appendix describes the files and softlinks created when you install Digital SNA 3270 Application Services software. B.1 Files Created The installation procedure creates the following files on your system: /usr/opt/R3270BASE120/usr/include/r3270def.h /usr/opt/R3270BASE120/usr/man/man1/r3270.1 /usr/opt/R3270BASE120/usr/shlib/libr3270.so /usr/opt/R3270BASE120/usr/sna/R3270_V12-0.release_notes /usr/opt/R3270BASE120/usr/sna/r3270_example.c /usr/opt/R3270BASE120/usr/sna/r3270_ivp.c B.2 Softlinks Created The installation procedure creates the following softlinks on your system: /usr/include/r3270def.h /usr/man/man1/r3270.1 /usr/shlib/libr3270.so /usr/sna/R3270_V12-0.release_notes /usr/sna/r3270_example.c /usr/sna/r3270_ivp.c Files Installed on Your System B-1