DEC DB Integrator Gateway for_DB2[TM]_Client_for_OpenVMS________________ Installation and Configuration Guide Part Number: AA-MH82D-TE November 1994 This guide describes how install the DEC DB Integrator Gateway for DB2 Client software. Revision/Update Information: This is a revised guide and supersedes previous versions. Operating System: OpenVMS VAX OpenVMS AXP Software Version: DEC DB Integrator Gateway for DB2 Client Version 3.1 Digital Equipment Corporation Maynard, Massachusetts __________________________________________________________ Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description. Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor. © Digital Equipment Corporation 1994. All rights reserved. The following are trademarks of Digital Equipment Corporation: ACMS, ALL-IN-1, AlphaGeneration, AXP, Bookreader, CDD/Plus, CDD/Repository, CI, DEC, DEC Rdb, DEC TCP/IP, DECdecision, DECdtm, DECforms, DECintact, DECnet, DECnet-DOS, DECplan, DECpresent, DECtp, DECtrace, DECwindows, Digital, HSC, MASSBUS, MicroVAX, OpenVMS, PATHWORKS, RA, Rdb Language Translator, Rdb/VMS, SPM, ULTRIX, UNIBUS, VAX, VAX Ada, VAX BASIC, VAX C, VAX CDD, VAX COBOL, VAX DATATRIEVE, VAX DBMS, VAX DOCUMENT, VAX FMS, VAX FORTRAN, VAX MACRO, VAX Pascal, VAX Performance Advisor, VAX RALLY, VAX Rdb/ELN, VAX RMS, VAX SCAN, VAX 6000, VAX TEAMDATA, VAX Xway, VAXcluster, VAXELN, VAXset, VAXstation, VIDA, VMS, VMScluster, and the DIGITAL logo. The following are third-party trademarks: PostScript is a registered trademark of Adobe Systems Incorporated. Apple is a registered trademark of Apple Computer, Inc. CA-ACF2 is a trademark of Computer Associates International, Inc. Interbase is a registered trademark of Borland International, Inc. Cincom is a registered trademark of Cincom Systems, Inc. SequeLink is a trademark and is licensed by Digital Equipment Corporation, Maynard, Massachusetts, from GnOsIs NV 1990, and TechGnosis Incorporated 1991. TechGnosis is a registered trademark of GnOsIs NV. All rights reserved. HP and HP-UX are registered trademarks of Hewlett-Packard Company. API/SQL, EDA/Link, EDA/SQL, Enterprise Data Access, and Enterprise Data Access/SQL are trademarks of Information Builders, Inc. INFORMIX is a registered trademark of Informix Software, Inc. INGRES is a registered trademark of Ingres Corporation. IBM is a registered trademark of International Business Machines Corporation. DB2, CICS, CICS/ESA, CICS/MVS, MVS/ESA, MVS/XA, RACF, and VTAM are trademarks of International Business Machines Corporation. ACCESS, Microsoft, MS, and MS-DOS are registered trademarks of Microsoft Corporation. Windows is a trademark of Microsoft Corporation. OSF and OSF/1 are registered trademarks of the Open Software Foundation, Inc. ORACLE, SQL*Net, and SQL*Plus are registered trademarks of the Oracle Corporation. Pro*C is a trademark of Oracle Corporation. Powersoft is a registered trademark of Powersoft Corporation. PowerBuilder is a trademark of Powersoft Corporation. PROGRESS is a registered trademark of Progress Software Corp. GemBase is a registered trademark of Ross Systems. SmartStar is a registered trademark of SmartStar Corporation. ADABAS is a registered trademark of Software AG of North America, Inc. SYBASE is a registered trademark of Sybase, Inc. DB-Library, Open Client, SYBASE Open Server, and SYBASE SQL Server are trademarks of Sybase, Inc. UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Ltd. All other trademarks and registered trademarks are the property of their respective holders. This document is available on CD-ROM. This document was prepared using VAX DOCUMENT Version 2.1. ________________________________________________________________ Contents Send Us Your Comments.................................... vii Preface.................................................. xi 1 Introduction to DEC DB Integrator Gateway for DB2 Client 1.1 Overview..................................... 1-1 1.2 Product Name................................. 1-2 1.3 Data Access Issues That the Gateway for DB2 Solves....................................... 1-2 1.4 Gateway for DB2 Features..................... 1-3 1.5 Gateway for DB2 Configuration................ 1-4 1.6 Gateway for DB2 Software Environment......... 1-5 1.6.1 Software on the Digital System........... 1-6 1.6.2 Software on the IBM System............... 1-7 1.7 Digital and IBM Site Coordination............ 1-9 1.7.1 Gateway for DB2 Coordinator.............. 1-9 1.7.2 Access to a DB2 System................... 1-10 1.8 Using Character Set Translation Files with the Gateway for DB2 Client................... 1-11 1.8.1 Default Character Translation............ 1-12 1.8.2 Assigning User-Defined Tables to a Logical Name or Qualifier................ 1-15 1.8.3 Using Different Translation Tables During Multiple Attachments..................... 1-16 1.8.4 Character Sets........................... 1-17 1.9 Network and Communications Support for the Gateway for DB2 Client....................... 1-27 1.9.1 IBM Systems Software..................... 1-27 iii 2 Preparing for DEC DB Integrator Gateway for DB2 Client Installation 2.1 Prerequisite Hardware........................ 2-1 2.2 Prerequisite and Optional Software........... 2-1 2.2.1 Common Components Installation Requirement.............................. 2-2 2.2.1.1 Why You Must Install Common Components............................. 2-3 2.2.1.2 Checking for Common Components......... 2-3 2.3 License Registration......................... 2-4 2.4 Installation Procedure Requirements.......... 2-5 2.4.1 Privileges Required...................... 2-5 2.4.2 Disk Space............................... 2-6 2.4.2.1 Disk Space Required.................... 2-6 2.4.2.2 Checking Disk Space.................... 2-6 2.4.3 System Parameters........................ 2-6 2.4.3.1 System Parameters Required............. 2-6 2.4.3.2 Checking System Parameter Values....... 2-7 2.4.3.3 Calculating the Values for GBLPAGES and GBLSECTIONS............................ 2-8 2.4.3.4 Changing System Parameter Values with AUTOGEN................................ 2-8 2.4.4 VMSINSTAL Requirements................... 2-9 2.4.5 System Disk Backup....................... 2-10 3 Installing DEC DB Integrator Gateway for DB2 Client 3.1 Installation Procedure....................... 3-1 3.2 Running the Installation Verification Procedure (IVP).............................. 3-9 3.3 Error Recovery............................... 3-10 4 After Installing DEC DB Integrator Gateway for DB2 Client 4.1 Running the Installation Verification Procedure Separately......................... 4-1 4.2 Editing the System Files..................... 4-1 4.3 User Account Requirements.................... 4-2 4.3.1 Privileges............................... 4-2 4.4 Determining and Reporting Problems........... 4-2 iv A Prerequisite Installation of Common Components A.1 Common Components............................ A-1 A.1.1 Media Required........................... A-2 A.1.2 Version Variants and Existing Databases................................ A-2 A.2 Disk Space Required.......................... A-3 A.3 OpenVMS Privileges Required.................. A-3 A.4 Unlocking the Process Account Password....... A-5 A.5 Installing Common Components................. A-6 A.6 Installing Common Components Images as Shared....................................... A-8 A.6.1 Editing the Startup and Shutdown Procedures for Shared Images............. A-10 A.6.2 Verifying Global Pages and Sections...... A-12 A.6.3 Removing Installed Images................ A-14 A.7 Installing SQL Images for Privileged Applications................................. A-17 A.7.1 Editing the Startup and Shutdown Procedures for Privileged Applications... A-18 A.8 Using Different Versions of the Common Components................................... A-19 A.9 Deleting Versions of the Common Components... A-21 B Sample Installation B.1 Sample Installation.......................... B-1 B.2 Sample Installation Verification Procedure (IVP)........................................ B-4 C Files Installed on Your System D How to Order Additional Documentation Index v Examples 1-1 EBCDIC to DMCS Default Character Translation Table........................ 1-13 1-2 DMCS to EBCDIC Default Character Translation Table ....................... 1-14 Figures 1-1 Conceptual View of Digital to DB2 Data Access................................... 1-5 1-2 Data Access Path from the Digital User Interface Software to DB2 Data (the Gateway for DB2 Software View)........... 1-6 Tables 1-1 Computer Character Sets.................. 1-17 2-1 Disk Space Requirements.................. 2-6 2-2 Minimum Required System Parameter Values................................... 2-7 A-1 Global Pages and Sections Required for Common Components OpenVMS VAX Images .... A-13 A-2 Global Pagelets and Sections Required for Common Components OpenVMS AXP Images .... A-14 vi ________________________________________________________________ Send Us Your Comments We welcome your comments on this manual or any DEC DB Integrator product manual. If you have suggestions for improvement or find any errors, please indicate the chapter, section, and page number (if available). Your input is valuable in improving future releases of our documentation. You can send comments to us in the following ways: o Electronic mail - DATABASE_DOC@WEORG.ENET.DEC.COM o FAX - 603-881-0120 Attn: DBI Documentation o Postal service Digital Equipment Corporation DEC DB Integrator Products Documentation 110 Spit Brook Road, ZKO2-1/R34 Nashua, NH 03062-2698 USA You can use the following questionnaire to give us information. vii Name _____________________________Title_______________________ Company __________________________Department ________________ Mailing Address __________________Telephone_Number __________ ________________________________________________________________________ Book Title _______________________Version_Number ____________ viii 1. How does the DBI documentation compare to documentation from other vendors that you have used? What do you like about other vendors' documentation that you would like the DBI documentation to implement? 2. What other topics or examples would you like to see included in this documentation set? 3. Do you use the online help for the DBI products? Are there other topics you would like to see included in the online help? 4. Interviews, telephone surveys, user observation, questionnaires, and other similar activities help us to improve our documentation. May we contact you about participating in future efforts? 5. If you have suggestions for improving particular sections or find any errors, please indicate the title of the manual and include the section number. 6. Please include any other comments or suggestions you have. ix ________________________________________________________________ Preface DEC DB Integrator Gateway for DB2 Client allows you to access data stored in DB2 databases. Who Should Use This Guide This guide is intended for system managers or others who are responsible for installing the DEC DB Integrator Gateway for DB2 Client software. Structure of This Guide This guide contains the following chapters and appendixes: Chapter 1 Describes the DEC DB Integrator Gateway for DB2 Client configuration. Chapter 2 Describes preparations you must make before installing the software. Chapter 3 Describes how to install the software. Chapter 4 Describes any tasks you must perform after installing the software. Appendix A Describes how to install the Common Components software, which you must install if you do not have DEC Rdb installed. Appendix B Contains a sample installation. Appendix C Lists the files installed by DEC DB Integrator Gateway for DB2 Client. Appendix D Describes how to order additional documenta- tion from Digital Equipment Corporation. xi Conventions In examples, an implied carriage return occurs at the end of each line, unless otherwise noted. You must press the Return key at the end of each input line. Often in examples, the prompts are not shown. Generally, they are shown where it is important to depict an interactive sequence exactly; otherwise, they are omitted in order to focus full attention on the statements or commands themselves. This section explains the conventions used in this guide: . . . Horizontal ellipsis points in statements or commands mean that parts of the statement or command not directly related to the example have been omitted. . Vertical ellipsis points in an example mean . that information not directly related to the . example has been omitted. italic Italic text indicates emphasis and complete text manual titles. boldface Boldface text indicates the first instance of text terms defined in the text. In online versions, bold is used to show user input. UPPERCASE Uppercase text indicates the name of an SQL TEXT statement or an SQL logical name. lowercase Lowercase text indicates an operating system text command or the name of a file. input entered by the user. DBADM References to DBADM, unless specifically qualified, refer to that database privilege having been granted or received either with or without the WITH GRANT OPTION clause. monospaced Monospaced text indicates example programs and text examples of user interfaces. xii $ Dollar signs represent the default DIGITAL Command Language (DCL) prompt. This symbol indicates that the system is ready for input. The OpenVMS icon denotes the beginning of information specific to the OpenVMS VAX and OpenVMS AXP operating systems. The DEC OSF/1 icon denotes the beginning of information specific to the DEC OSF/1 AXP operating system. The VAX icon denotes the beginning of information specific to the OpenVMS VAX operating system. The AXP icon denotes the beginning of information specific to the OpenVMS AXP operating system. The diamond symbol (<>) denotes the end of information specific to an operating system. For More Information This section describes where to find information about the DEC DB Integrator product family, RdbAccess products, and SQL. For each of the products listed in the section, the following information is available: o Before You Install Lists hardware and software required to install the product. o Software Product Description (SPD) Provides information on the compatibility of other software products. Use the SPD to verify which versions of your operating system are compatible with which versions of the DEC DB Integrator (DBI) product family software. o Release Notes Provide information about a specific release of the product. Available in online format only. xiii DEC DB Integrator Product Family Information Information about the DEC DB Integrator product family is available in the following manuals: o DEC DB Integrator Product Family User's Guide Describes how to use the DBI Gateway software and DEC DB Integrator software to access and integrate data stored in relational and nonrelational databases. o DEC DB Integrator Handbook Describes how to use DEC DB Integrator to set up and maintain a multidatabase management system. The system provides the capability to access and update data stored in multiple databases, in distributed locations, and with multiple data formats. o DEC DB Integrator for OpenVMS Installation Guide Provides detailed software installation instructions for hardware systems that support DEC DB Integrator on OpenVMS VAX and OpenVMS AXP operating systems. Also provides detailed information about the hardware, operating system versions, and software packages that are compatible with this version of DBI. o DEC DB Integrator Gateway installation and configura- tion guides for the following gateway products: - DEC DB Integrator Gateway for DB2 - DEC DB Integrator Gateway for DSM - DEC DB Integrator Gateway for EDA/SQL - DEC DB Integrator Gateway for ORACLE - DEC DB Integrator Gateway for SequeLink - DEC DB Integrator Gateway for SYBASE o DEC DB Integrator Gateway for DBMS Accessing DEC DBMS Data with SQL Describes how to use the DEC DBMS data driver with the Non-SQL Data Server to access DEC DBMS data. o DEC DB Integrator Gateway for RMS Accessing RMS and VSAM Files with SQL xiv Describes how to use the RMS data driver with the Non- SQL Data Server to access nonrelational files. o Accessing Nonrelational Data with SQL Describes how to use SQL with the Non-SQL Data Server to access nonrelational files. o DEC DB Integrator Gateway for Custom Drivers Driver Development Guide Describes how to write data and metadata drivers to handle data and metadata sources that are not explicitly supported by DEC DB Integrator Gateway for RMS. o DEC DB Integrator Gateway for Custom Drivers/DEC DB Integrator Gateway for RMS Installation Guide Describes how to install and maintain DEC DB Integrator Gateway for Custom Drivers and DEC DB Integrator Gateway for RMS software on the OpenVMS operating system. RdbAccess Information Information about RdbAccess products is available from the following guides: ________________________Note ________________________ The following guides have been superseded by the corresponding DEC DB Integrator Gateway guides. The information is provided for the benefit of users who have not upgraded their RdbAccess software products. _____________________________________________________ o DEC RdbAccess Client for DB2 User's Guide o DEC RdbAccess Server for DB2 Installation and Administration Guide o DEC RdbAccess Client for DB2 Installation Guide o DEC RdbAccess for ORACLE User's Guide o DEC RdbAccess for ORACLE Installation Guide xv SQL Information Information about SQL is available in the following manuals: o DEC Rdb SQL Reference Manual Provides reference material and a complete description of the statements, the interactive, dynamic, and module language interfaces, and the syntax for SQL. o DEC Rdb Introduction to SQL Introduces the interactive and programming components of ANSI/ISO SQL and presents a tutorial of the SQL language elements for designing, creating, modifying, and retrieving data through interactive SQL. o DEC Rdb Guide to SQL Programming Describes how to write database application programs that use ANSI/ISO SQL. o DEC Rdb Guide to Distributed Transactions Describes the two-phase commit protocol and distributed transactions, and explains how to use DEC Rdb with distributed transactions. IBM Parameters for Gateway Products For detailed information about IBM parameters for the various types of gateways, consult the following manuals: o DEC SNA Domain Gateway Guide to IBM Resource Definition o DEC SNA Peer Server Guide to IBM Resource Definition o DECnet/SNA Gateway-CT Guide to IBM Parameters o DECnet/SNA Gateway-ST Guide to IBM Parameters o DECnet/SNA VMS Gateway Management o DEC SNA APPC/LU62 for OpenVMS Administrators Guide xvi References to Products The DBI documentation set often refers to the following Digital products by their abbreviated names: o The CDD/Repository for OpenVMS AXP and CDD/Repository for OpenVMS VAX products are referred to as CDD/Repository, the data dictionary, dictionary, or, more commonly, repository. o The DEC Data Distributor for OpenVMS AXP and DEC Data Distributor for OpenVMS VAX products are referred to as Data Distributor. o The DEC DATATRIEVE for OpenVMS AXP and DEC DATATRIEVE for OpenVMS VAX products are referred to as DATATRIEVE. o The DEC DB Integrator product is referred to as DBI. It is available on the OpenVMS AXP, OpenVMS VAX, and DEC OSF/1 AXP systems. o The DEC DB Integrator Gateway for DB2, DEC DB Integrator Gateway for EDA/SQL, DEC DB Integrator Gateway for ORACLE, DEC DB Integrator Gateway for SequeLink, and DEC DB Integrator Gateway for SYBASE, products are referred to as the relational gateways. o The DEC DB Integrator Gateway for Custom Drivers, DEC DB Integrator Gateway for DBMS, DEC DB Integrator Gateway for DSM, and DEC DB Integrator Gateway for RMS products are referred to as the nonrelational gateways. o The DEC DB Integrator Gateway family of data access products is often referred to as DBI Gateway. The DEC DB Integrator Gateway family is made up of the following products. Each product is often referred to as the gateway for [identifying product name]. For example, the DEC DB Integrator Gateway for Custom Drivers is often referred to as the gateway for Custom Drivers. - DEC DB Integrator Gateway for Custom Drivers[1] ___________________ [1]This product is available on the OpenVMS AXP and OpenVMS VAX systems. xvii - DEC DB Integrator Gateway for DB2 Client[1], [2] - DEC DB Integrator Gateway for DB2 Server[3] - DEC DB Integrator Gateway for DBMS[1] - DEC DB Integrator Gateway for DSM[1] - DEC DB Integrator Gateway for EDA/SQL[1], [2] - DEC DB Integrator Gateway for ORACLE[1], [2] - DEC DB Integrator Gateway for RMS[1] - DEC DB Integrator Gateway for SequeLink[1], [2] - DEC DB Integrator Gateway for SYBASE[1], [2] o The DEC RdbExpert for OpenVMS AXP and DEC RdbExpert for OpenVMS VAX products are referred to as RdbExpert. o The Digital gateways to SNA networks are referred to as the DEC SNA gateway products. These products include: - OpenVMS SNA - DECnet SNA Gateway for Channel Transport - DECnet SNA Gateway for Synchronous Transport - DEC SNA Domain Gateway - DEC SNA Peer Server o The DECnet/SNA Data Transfer Facility product is referred to as DTF. o The DECtrace for OpenVMS AXP and DECtrace for OpenVMS VAX products are referred to as DECtrace. o The DEC Rdb for OpenVMS AXP and DEC Rdb for OpenVMS VAX products are both referred to as DEC Rdb. Prior to DEC Rdb Version 5.0, this product was called VAX Rdb/VMS. o The OpenVMS RMS (Record Management Services) product is referred to as RMS. ___________________ [2]This product is available on the DEC OSF/1 AXP system. [3]This product is only available on the IBM system. xviii o SQL refers to the SQL interface to DEC Rdb and to the DBI family of products. SQL is Digital Equipment Corporation's implementation of the SQL standard ANSI X3.135-1992, ISO 9075:1992, commonly referred to as ANSI/ISO SQL. xix 1 ________________________________________________________________ Introduction to DEC DB Integrator Gateway for DB2 Client This chapter introduces the DEC DB Integrator Gateway for DB2 Client product, often referred to as either the gateway for DB2 client or the gateway for DB2. It provides an overview of the product and descriptions of the following: o How the gateway for DB2 works o Data access issues solved by the Gateway for DB2 o Gateway for DB2 features o DB2 configuration for data access o DB2 software environment o Digital and IBM site coordination o Using character sets o Network and communications support 1.1 Overview The gateway for DB2 client is a software facility that provides Digital users read-only and read/write access to data stored in Database 2 (DB2) on an IBM mainframe. The gateway for DB2 uses the Digital DEC SNA Gateway and the APPC/LU 6.2 (Advanced Program-to-Program Communication /Logical Unit) Programming Interface for OpenVMS to connect to the IBM system. As a database access product, the gateway for DB2 client provides both transport and translation services. Users use a software product, such as the SQL interface to DEC Rdb Version 5.1 (or higher), DATATRIEVE, or SQL/Services as the interface for data access. Introduction to DEC DB Integrator Gateway for DB2 Client 1-1 1.2 Product Name DEC DB Integrator Gateway for DB2 Client is the name for the RdbAccess Client for DB2 product, which was formerly known as the VIDA Client for DB2 product. DEC DB Integrator Gateway for DB2 Server is the new name for the RdbAccess Server for DB2 product, which was formerly known as the VIDA Server for DB2 product. 1.3 Data Access Issues That the Gateway for DB2 Solves The gateway for DB2 provides solutions to problems that users in heterogeneous database environments experience. Incompatibilities between Digital and IBM systems can make transparent access to data across multivendor environments difficult. The gateway for DB2 simplifies data access and retrieval by resolving the following system incompatibilities: o Syntax for and interpretation of user input Digital software and IBM software employ different database calling protocols. The DEC DB Integrator Gateway for DB2 Client component understands both calling protocols and acts as an intermediary. The gateway for DB2 client converts requests from Digital software into a form that can be interpreted by IBM software. o Computer character set differences Digital software is based on DMCS, the DEC Multinational Character Set. DMCS is an extension of the ASCII character set. IBM software is built on EBCDIC, a different character set standard. The gateway for DB2 provides a character translation table to manage the differences. To facilitate special application needs, the gateway for DB2 allows sites to use a customized translation table. o Signing on to DB2 1-2 Introduction to DEC DB Integrator Gateway for DB2 Client The gateway for DB2 client attach specification is an access string that contains all the information necessary to connect to a DB2 system and identify the data tables with which the user wants to work. In addition to identifying the data that the user wants to access, the attach specification identifies the user to the DB2 system. o Data storage formats The data storage formats available on an IBM system and those on a Digital OpenVMS system are not the same in all cases. The gateway for DB2 automatically translates IBM data storage formats into appropriate OpenVMS data types for the retrieved data. o Data definition rules Databases on Digital OpenVMS systems and on IBM systems have different rules for data definitions (metadata). For example, column (field) names on a DB2 table can contain characters not allowed in column names in a Digital OpenVMS database system. Similarly, column names on the Digital database system can contain characters not allowed in column names on the DB2 table. The gateway for DB2 translates DB2 metadata to Digital relational metadata for the retrieved data. 1.4 Gateway for DB2 Features The gateway for DB2 offers the following features: o Read-only or read/write access to DB2 data from Digital software products and applications. DEC DB Integrator Gateway for DB2 Server at the IBM site can be configured for either read-only or read/write access to DB2 data. o Fast and efficient data transmission. The gateway for DB2 takes advantage of the LU 6.2 communications protocol. Offered by IBM as part of the Advanced Program-to-Program Communication (APPC) architecture, the LU 6.2 protocol allows direct communication between programs. Introduction to DEC DB Integrator Gateway for DB2 Client 1-3 o Interactive and batch access. Digital users can interactively query DB2 data, or submit queries in batch mode. The gateway for DB2 can handle both types of access. o Sharing and distribution of data. Through the use of one or more Digital user interface products for relational databases, data can be shared among a number of users. o Configuration management. Any version of the gateway for DB2 client software is compatible with any version of the gateway for DB2 server software and vice versa. This feature allows you to upgrade to a new version of client software without upgrading to a new version of server software. o Tracing facility. This allows you to have a record of events, statistics, and actual data records in a log file. This information can help you to assess performance, resolve error conditions, and verify the data being transferred to and from the IBM system. o Security. The security system that is in place at the IBM site works with the gateway to ensure the security of DB2 data. The gateway for DB2 works with security mechanisms that a given site might have in place on the IBM system, such as ACF2, RACF, or the default, CICS. If the IBM site is configured for ATTACHSEC(IDENTIFY) security, then Digital users do not need to send passwords over the network to access the IBM system. 1.5 Gateway for DB2 Configuration The gateway for DB2 is comprised of two software products: o The gateway for DB2 client o The gateway for DB2 server 1-4 Introduction to DEC DB Integrator Gateway for DB2 Client The gateway for DB2 client, which is installed on a Digital AXP or VAX system, operates in conjunction with the gateway for DB2 server, which is installed on an IBM system. Together, the client and server provide read-only or read/write access to DB2 data. Before data stored in DB2 data can be accessed on the IBM system, the gateway for DB2 requires that additional products be in place, as described in Section 2.2. Figure 1-1 Conceptual View of Digital to DB2 Data Access Figure 1-1 provides a high-level view of one configuration for the gateway for DB2. It shows the Digital side connected by network software to the IBM side. A user on the Digital side issues an SQL query that the gateway for DB2 client processes and sends through the DEC SNA (Systems Network Architecture) gateway to the gateway for DB2 server installed in Customer Information Control Systems (CICS) on the IBM system. The server passes the SQL query to DB2, which executes the query and returns the results of the query back to the user on the Digital side. 1.6 Gateway for DB2 Software Environment The gateway for DB2 client component processes data requests, passing them to the DEC SNA APPC/LU 6.2 Programming Interface for OpenVMS. Data requests are then routed through a DEC SNA gateway to the IBM system. On the IBM system, the Virtual Telecommunications Access Method (VTAM) routes the data requests to the CICS where the gateway for DB2 server is installed as a transaction processing program. The gateway for DB2 server receives the data requests and routes them to DB2. The required data is then returned back to the user on the Digital Introduction to DEC DB Integrator Gateway for DB2 Client 1-5 system using a reverse path through the same software components. Figure 1-2 shows the major software components that form the data access path from the Digital system to the DB2 database. Figure 1-2 Data Access Path from the Digital User Interface Software to DB2 Data (the Gateway for DB2 Software View) The following sections describe each of the software components in Figure 1-2 that form the data access path. 1.6.1 Software on the Digital System The following software is installed on the Digital system. o User interface User interfaces for submitting data access requests to the gateway for DB2 client include: - Data manipulation language (DML) embedded in third- generation language - DEC ODBC Driver for MS Windows - SQL interface to DEC Rdb - SQL/Services - DEC Data Distributor - Rdb/Dispatch The DEC Rdb routing software is called Rdb/Dispatch. All data requests made from user interfaces are routed through this software. Rdb/Dispatch processes the data 1-6 Introduction to DEC DB Integrator Gateway for DB2 Client requests and sends them to the gateway for DB2 client for further processing. o Gateway for DB2 client The client software on the Digital system passes the data requests through the DEC SNA gateway to the gateway for DB2 server on the IBM system. o DEC SNA APPC/LU 6.2 Programming Interface for OpenVMS This interface transfers data access requests from the client through the gateway to the IBM system. This is the communication interface used by gateway for DB2 client and must be installed on the Digital system prior to using the gateway for DB2. o DEC SNA gateway products The DEC SNA gateway products (OpenVMS SNA, DECnet SNA Gateway for Synchronous Transport, DECnet Gateway for Channel Transport, DEC SNA Domain Gateway, and the DEC SNA Peer Server) are interconnect systems that allow Digital systems to communicate with one or more IBM hosts in an IBM SNA network. These interconnect systems and associated software handle the protocol differences between IBM SNA networks and Digital DECnet networks. Whichever gateway you choose depends on your configura- tion needs. A DEC SNA gateway must be in place as the gateway for DB2 communications. 1.6.2 Software on the IBM System The following software is installed on the IBM system: o ACF/VTAM The Advanced Communications Facility/Virtual Telecommunications Access Method (ACF/VTAM, or simply VTAM) is the foundation for an IBM communications subsystem. The VTAM software provides the interface between VTAM application programs and other resources in the SNA network. Introduction to DEC DB Integrator Gateway for DB2 Client 1-7 The IBM systems programmer responsible for VTAM defines its communications protocols and network resources. The communications protocols are defined in the VTAM Logon Mode Table entries. The network resources that can be defined include: - Applications such as CICS and Time-Sharing Option (TSO) - Local devices such as a channel-attached communica- tions controller - Lines and remote devices that are subordinate to a communications controller - Network resources "owned" by another VTAM system Refer to the Digital DEC SNA or OpenVMS SNA documenta- tion for further information on the requirements for your gateway configuration. o MVS/XA or MVS/ESA MVS is the IBM operating system environment that supports DB2. o CICS/MVS or CICS/ESA CICS resides on the IBM host. CICS is defined to VTAM as an application program. CICS performs task and resource scheduling and controls sessions between application programs and devices associated with the application program. The gateway for DB2 server installation requires definitions in CICS tables. o DB2 DB2 is an IBM relational database product for the MVS operating system. o DEC DB Integrator Gateway for DB2 Server The gateway for DB2 server is the companion software to gateway for DB2 client. The gateway for DB2 server software runs as a CICS application program which accesses the DB2 database. The gateway for DB2 client on the Digital computer communicates with the gateway for DB2 server software 1-8 Introduction to DEC DB Integrator Gateway for DB2 Client using a proprietary protocol layered upon CICS/SNA APPC communication protocols. There is no direct user interface to the gateway for DB2 server. The gateway for DB2 server is initiated when the gateway for DB2 client on the Digital side makes a connection to the CICS system and requests the transaction code associated with the gateway for DB2 server. Digital users can choose from several Digital interface products to access data contained on a DB2 database system. For a list of Digital interface products, see Section 1.6.1. 1.7 Digital and IBM Site Coordination Setting up an access pathway to DB2 data requires some planning. The gateway for DB2 coordinator needs to evaluate information from a number of individuals within the organization. This section provides general suggestions to help you set up the access path. 1.7.1 Gateway for DB2 Coordinator The gateway for DB2 coordinator refers to the person who is responsible for the gateway for DB2 client use at your site. The coordinator supplies information to the DB2 database administrator (DBA) about the gateway for DB2 client users who want to access DB2 data. The coordinator might be the system manager or the database administrator for the system where the gateway for DB2 server is installed. The gateway for DB2 coordinator also works with network and systems personnel at the IBM and Digital sites to oversee the configuration and the setup of the gateway for DB2. These individuals include: o Digital system manager o Network manager for DEC SNA or OpenVMS SNA o CICS system administrator o VTAM system administrator o DB2 DBA Introduction to DEC DB Integrator Gateway for DB2 Client 1-9 1.7.2 Access to a DB2 System The following checklist will help the gateway for DB2 coordinator in planning for the gateway for DB2: 1. Ensure prerequisite software is installed: a. DEC DB Integrator Gateway for DB2 Client b. An SNA gateway c. APPC LU 6.2 Programming Interface d. DEC DB Integrator Gateway for DB2 Server Find out if the gateway for DB2 server at the IBM site is configured for read-only or read/write access to DB2 data by asking your DB2 DBA. 2. Ensure the DEC SNA configuration file has been modified for the gateway for DB2 client. See Section 1.9 for more information on network and communications support for the gateway for DB2 client. 3. Ensure that the following are available at the IBM site: - User accounts on the IBM system for the gateway for DB2 users - LU 6.2 communications - User names that are authorized to execute the gateway for DB2 server transactions with CICS 4. Ensure the DB2 database administrator grants the gateway for DB2 client users appropriate privileges on DB2 data and the metadata plans used by the gateway for DB2 server. 5. Assist the gateway for DB2 client users with in- formation on attach specification qualifiers and logical names needed to access DB2 data. See the DEC DB Integrator Product Family User's Guide for more information on accessing DB2 data. 6. Decide whether or not to use the default character set translation tables provided, or to build site-specific character set translation tables. See Section 1.8 for options on character set translation tables. 1-10 Introduction to DEC DB Integrator Gateway for DB2 Client 7. Decide whether or not the gateway for DB2 client events should be traced, and whether or not trace files should be centralized. See the DEC DB Integrator Product Family User's Guide for information on how to use tracing at your site. 1.8 Using Character Set Translation Files with the Gateway for DB2 Client Software and hardware in a Digital system support the ASCII character set or the Digital Multinational Character Set (DMCS). (DMCS is a superset of ASCII.) Software and hardware in an IBM system support EBCDIC, a character set developed by IBM. Differences between computer character sets mean that the gateway for DB2 client must use a translation table to specify how it converts text data that it passes to and receives from DB2. The gateway for DB2 client determines which translation table it uses by checking character set assignments when it first activates a link to IBM on behalf of an OpenVMS process. Users at your site can: o Choose not to specify a character set value in a gateway for DB2 client attach specification. As long as no value for character set translation has been specified in the attach specification, the requests submitted to the gateway for DB2 client use its internal default character translation table. o Specify a site-specific translation table image file with the CHARACTER_SET qualifier of the gateway for DB2 client attach specification. Users can edit the LDB2$DMCS_TABLE.MAR source code file supplied by the gateway for DB2 client kit and build an image that meets the gateway for DB2 client requirements. The SYS$COMMON:[SYSLIB] directory, also known as SYS$SHARE, is the default location for the translation table image and source files. Introduction to DEC DB Integrator Gateway for DB2 Client 1-11 You can then use the CHARACTER_SET attach specification qualifier in the gateway for DB2 client attach specification to assign a file specification for the new translation table image. The following sections explain these options more completely. The tables included in this chapter identify EBCDIC and DMCS characters using hexadecimal notation. For your convenience, Section 1.8.4 includes a table to tell you which character corresponds to a hexadecimal value in those character sets. ________________________Note ________________________ DMCS does not vary from one Digital system to another. EBCDIC, on the other hand, uses a system of national replacement characters to meet foreign language requirements. Therefore, the graphic represented by a hexadecimal value can vary from one IBM system to another. Section 1.8.4 provides the EBCDIC graphic assigned to a hexadecimal value for English (U.S.), according to the IBM publication IBM 3270 Display System Character Set Reference, Order No. GA27-2837-7. If the version of EBCDIC in Section 1.8.4 does not apply to the IBM data that you want to access, request the correct EBCDIC table from the manager of the IBM system where that data resides. _____________________________________________________ 1.8.1 Default Character Translation Example 1-1 and Example 1-2 show the default character translation tables that the gateway for DB2 client uses. Immediately following each table are instructions on how to read it. These tables show the character translation that applies to a DB2 data request when the default translation is used. 1-12 Introduction to DEC DB Integrator Gateway for DB2 Client Example 1-1 EBCDIC to DMCS Default Character Translation Table EBCDIC Bits 4-7 EBCDIC Bits 0-3 0 1 2 3 4 5 6 7 8 9 A B C D E F 0 00 10 -- -- 20 26 2D F8 D8 B0 B5 A2 7B 7D 5C 30 1 01 11 -- -- -- E9 2F C9 61 6A 7E A3 41 4A -- 31 2 02 12 -- 16 E2 EA C2 CA 62 6B 73 A5 42 4B 53 32 3 03 13 -- -- E4 EB C4 CB 63 6C 74 -- 43 4C 54 33 4 -- -- -- -- E0 E8 C0 C8 64 6D 75 -- 44 4D 55 34 5 09 -- 0A -- E1 ED C1 CD 65 6E 76 A7 45 4E 56 35 6 -- 08 17 -- E3 EE C3 CE 66 6F 77 B6 46 4F 57 36 7 7F 87 1B 04 E5 EF C5 CF 67 70 78 -- 47 50 58 37 8 -- 18 -- -- E7 EC C7 CC 68 71 79 -- 48 51 59 38 9 -- 19 -- -- F1 DF D1 60 69 72 7A -- 49 52 5A 39 A -- -- -- -- 5B 5D 7C 3A AB AA A1 -- -- B9 B2 B3 B 0B -- -- -- 2E 24 2C 23 BB BA BF -- F4 FB D4 DB C 0C 1C -- 14 3C 2A 25 40 -- E6 -- -- F6 FC D6 DC D 0D 1D 05 15 28 29 5F 27 -- -- -- -- F2 F9 D2 D9 E 0E 1E 06 -- 2B 3B 3E 3D -- C6 -- -- F3 FA D3 DA F 0F 1F 07 1A 21 5E 3F 22 B1 A8 -- -- F5 FD D5 FF In Example 1-1: o Numbers in the header row represent the high-order bits (4-7) of the EBCDIC character in hexadecimal notation. o Numbers in the leftmost column represent the low-order bits (0-3) of the EBCDIC character in hexadecimal notation. o Numbers in the body of the table represent the equivalent DMCS character in hexadecimal notation. o Characters that do not translate (marked with "-") are converted to ASCII backslash (hex 5C). For example, the EBCDIC character 52 (5 in the header row and 2 in the leftmost column) translates to the DMCS character EA (EA in the body of the table). Introduction to DEC DB Integrator Gateway for DB2 Client 1-13 Example 1-2 DMCS to EBCDIC Default Character Translation Table DMCS Bits 4-7 DMCS Bits 0-3 0 1 2 3 4 5 6 7 8 9 A B C D E F 0 00 10 40 F0 7C D7 79 97 -- -- -- 90 64 -- 44 -- 1 01 11 4F F1 C1 D8 81 98 -- -- AA 8F 65 69 45 49 2 02 12 7F F2 C2 D9 82 99 -- -- B0 EA 62 ED 42 CD 3 03 13 7B F3 C3 E2 83 A2 -- -- B1 FA 66 EE 46 CE 4 37 3C 5B F4 C4 E3 84 A3 -- -- -- -- 63 EB 43 CB 5 2D 3D 6C F5 C5 E4 85 A4 -- -- B2 A0 67 EF 47 CF 6 2E 32 50 F6 C6 E5 86 A5 -- -- -- B6 9E EC 9C CC 7 2F 26 7D F7 C7 E6 87 A6 -- -- B5 -- 68 -- 48 -- 8 16 18 4D F8 C8 E7 88 A7 -- -- 9F -- 74 80 54 70 9 05 19 5D F9 C9 E8 89 A8 -- -- -- DA 71 FD 51 DD A 25 3F 5C 7A D1 E0 91 A9 -- -- 9A 9B 72 FE 52 DE B 0B 27 4E 5E D2 4A 92 C0 -- -- 8A 8B 73 FB 53 DB C 0C 1C 6B 4C D3 E0 93 6A -- -- -- -- 78 FC 58 DC D 0D 1D 60 7E D4 5A 94 D0 -- -- -- -- 75 -- 55 DF E 0E 1E 4B 6E D5 5F 95 A1 -- -- -- -- 76 -- 56 -- F 0F 1F 61 6F D6 6D 96 07 -- -- -- AB 77 59 57 FF In Example 1-2: o Numbers in the header row represent the high-order bits (4-7) of the DMCS character in hexadecimal notation. o Numbers in the leftmost column represent the low- order bits (0-3) of the DMCS character in hexadecimal notation. o Numbers in the body of the table represent the equivalent EBCDIC character in hexadecimal notation. o Characters that do not translate (marked with "-") are converted to EBCDIC SUB (hex 3F). For example, the DMCS character EA (E in the header row and A in the leftmost column) translates to the EBCDIC character 52 (52 in the body of the table). 1-14 Introduction to DEC DB Integrator Gateway for DB2 Client 1.8.2 Assigning User-Defined Tables to a Logical Name or Qualifier The gateway for DB2 client provides a source code file called LDB2$DMCS_TABLE.MAR, which is an example of a user-defined macro translation file. It contains the supplementary translation macros used to create the gateway for DB2 client default internal translation table. You can customize a translation table for your site by editing the LDB2$DMCS_TABLE.MAR file so that it includes the translation macros you need. The macros you supply in this file override or supplement the character translation specified in the default LDB2$TRAPRE.MAR file. After you have created the macros, you can link both files to build a translation table image. For your convenience, the gateway for DB2 client software kit includes a command file that you can use to assemble and link a translation table for use with the gateway for DB2 client. The file is SYS$LIBRARY:LDB2$TRANS_TABLE.COM. ________________________Note ________________________ If you have already built translation tables to use with DEC SNA products, note that the gateway for DB2 client requires you to build a translation table image differently than most other DEC SNA products require. When building an image for gateway for DB2 client use, be sure to use the LINK command. _____________________________________________________ The following example builds an executable image, copies it to a directory that all gateway for DB2 client users can access, and defines LDB2$CHARACTER_SET as a systemwide logical name. You must have EXECUTE privileges to do this. In the following example, the file names the users supply are in lowercase: Introduction to DEC DB Integrator Gateway for DB2 Client 1-15 $ LINK/SHARE=trans-table.exe trans-table.obj, SYS$INPUT/OPT UNIVERSAL = VIDA2$EBCDIC_TO_ASCII UNIVERSAL = VIDA2$ASCII_TO_EBCDIC $ COPY trans-table.exe MY$DISK:*.*/PROT=W:RE $ DEFINE/SYSTEM LDB2$CHARACTER_SET MY$DISK:trans-table.exe ________________________Note ________________________ The gateway for DB2 client assumes that the default location for the translation table image is SYS$SHARE, which is the SYS$COMMON:[SYSLIB] directory. Therefore, if you use a translation table from another location, you must specify the device and directory in the attach specification. _____________________________________________________ 1.8.3 Using Different Translation Tables During Multiple Attachments If an application uses different translation tables for each attachment, then each translation table must have a unique file name. This means you cannot use translation tables with the same file name that are in different directories. If you do this, the translation table used in later attachments is the same translation table used during the first attachment. You can store executable images of translation tables in any directory. You do not need to install these images, even though the LDB2SHR image might be installed, unless the image is installed with privileges. In this case, you must then install the translation table images. The following example shows the correct way to specify two different translation tables for two different attachments to a gateway database: 1-16 Introduction to DEC DB Integrator Gateway for DB2 Client SQL> ! The following attachment uses the SQL> ! translation table LDB2$DIR:TRANS_TABLE1 SQL> ATTACH 'FILENAME/TYPE=DB2/TAB=VIDA2.TABLE1- cont> /CHAR=LDB2$DIR:TRANS_TABLE1'; SQL> DISCONNECT ALL; SQL> ! The following attachment uses the SQL> ! translation table LDB2$DIR:TRANS_TABLE2 SQL> ATTACH 'FILENAME/TYPE=DB2/TAB=VIDA2.TABLE2- cont> /CHAR=LDB2$DIR:TRANS_TABLE2'; 1.8.4 Character Sets This section relates hexadecimal values to graphics in both the DMCS and EBCDIC computer character sets. Table 1-1 relates values (in hexadecimal notation) to the characters they represent in DMCS and in EBCDIC. Hexadecimal values 00 to 7F in DMCS define the ASCII character set. DMCS is a superset of the ASCII character set. Graphic representations of DMCS values are not variable. Graphic representations of EBCDIC values can vary from one IBM site to another. This table represents EBCDIC as documented for English (U.S.) in the IBM publication IBM 3270 Display System Character Set Reference, Order No. GA27-2837-7. Your IBM systems staff should be able to tell you if the version of EBCDIC in that document is the correct one for your site. Table_1-1_Computer_Character_Sets_________________________ Hex Value__DMCS_Character_________EBCDIC_Character____________ 00 NUL NUL 01 SOL undefined 02 STX undefined 03 ETX undefined 04 EOT undefined 05 ENQ PT (continued on next page) Introduction to DEC DB Integrator Gateway for DB2 Client 1-17 Table_1-1_(Cont.)_Computer_Character_Sets_________________ Hex Value__DMCS_Character_________EBCDIC_Character____________ 06 ACK undefined 07 BEL undefined 08 BS undefined 09 HT undefined 0A LF undefined 0B VT undefined 0C FF FF 0D CR undefined 0E SO undefined 0F SI undefined 10 DLE undefined 11 DC1 SBA 12 DC2 EUA 13 DC3 IC 14 DC4 undefined 15 NAK NL 16 SYN undefined 17 ETB undefined 18 CAN undefined 19 EM EM 1A SUB undefined 1B ESC undefined 1C FS DUP 1D GS SF 1E RS FM 1F US undefined 20 (space) undefined 21 ! (exclamation) undefined (continued on next page) 1-18 Introduction to DEC DB Integrator Gateway for DB2 Client Table_1-1_(Cont.)_Computer_Character_Sets_________________ Hex Value__DMCS_Character_________EBCDIC_Character____________ 22 " (double quotation undefined mark) 23 # (pound sign) undefined 24 $ (dollar sign) undefined 25 % (percent sign) undefined 26 & (ampersand) undefined 27 ' (single quotation undefined mark, apostrophe) 28 ( (left parenthesis) undefined 29 ) (right parenthesis) undefined 2A * (asterisk) undefined 2B + (plus sign) undefined 2C , (comma) undefined 2D - (hyphen, minus undefined sign) 2E . (period,decimal undefined point) 2F / (slash, division undefined sign) 30 0 undefined 31 1 undefined 32 2 undefined 33 3 undefined 34 4 undefined 35 5 undefined 36 6 undefined 37 7 undefined 38 8 undefined 39 9 undefined (continued on next page) Introduction to DEC DB Integrator Gateway for DB2 Client 1-19 Table_1-1_(Cont.)_Computer_Character_Sets_________________ Hex Value__DMCS_Character_________EBCDIC_Character____________ 3A : (colon) undefined 3B ; (semicolon) undefined 3C < (less than sign) RA 3D = (equal sign) undefined 3E > (greater than sign) undefined 3F ? (question mark) SUB 40 @ (commercial at (space) sign) 41 A undefined 42 B undefined 43 C undefined 44 D undefined 45 E undefined 46 F undefined 47 G undefined 48 H undefined 49 I undefined 4A J ¢(cent sign) 4B K . (period, decimal point) 4C L < (less than sign) 4D M ( (left parenthesis) 4E N + (plus sign) 4F O | (solid vertical bar) 50 P & (ampersand) 51 Q undefined 52 R undefined 53 S undefined 54 T undefined (continued on next page) 1-20 Introduction to DEC DB Integrator Gateway for DB2 Client Table_1-1_(Cont.)_Computer_Character_Sets_________________ Hex Value__DMCS_Character_________EBCDIC_Character____________ 55 U undefined 56 V undefined 57 W undefined 58 X undefined 59 Y undefined 5A Z ! (exclamation point) 5B [ (left bracket) $ (dollar sign) 5C \ (backslash) * (asterisk) 5D ] (right bracket) ) (right parenthesis) 5E ^ (circumflex, caret) ; (semicolon) 5F _ (underscore) ^ (circumflex, caret) 60 ` (grave accent) - (hyphen, minus sign) 61 a / (slash, division sign) 62 b undefined 63 c undefined 64 d undefined 65 e undefined 66 f undefined 67 g undefined 68 h undefined 69 i undefined 6A j (broken vertical bar) 6B k , (comma) 6C l % (percent sign) 6D m _ (underscore) 6E n > (greater than sign) 6F o ? (question mark) 70 p undefined (continued on next page) Introduction to DEC DB Integrator Gateway for DB2 Client 1-21 Table_1-1_(Cont.)_Computer_Character_Sets_________________ Hex Value__DMCS_Character_________EBCDIC_Character____________ 71 q undefined 72 r undefined 73 s undefined 74 t undefined 75 u undefined 76 v undefined 77 w undefined 78 x undefined 79 y undefined 7A z : (colon) 7B { (left brace) # (pound sign) 7C | (vertical bar) @ (commercial at sign) 7D } (right brace) ' (single quotation mark, apostrophe) 7E ~ (tilde) = (equal sign) 7F DEL " (double quotation mark) 80 undefined undefined 81 undefined a 82 undefined b 83 undefined c 84 IND d 85 NEL e 86 SSA f 87 ESA g 88 HTS h 89 HTJ i 8A VTS undefined 8B PLD undefined (continued on next page) 1-22 Introduction to DEC DB Integrator Gateway for DB2 Client Table_1-1_(Cont.)_Computer_Character_Sets_________________ Hex Value__DMCS_Character_________EBCDIC_Character____________ 8C PLU undefined 8D R1 undefined 8E SS2 undefined 8F SS3 undefined 90 DCS undefined 91 PU1 j 92 PU2 k 93 STS l 94 CCH m 95 MW n 96 SPA o 97 EPA p 98 undefined q 99 undefined r 9A undefined undefined 9B CS1 undefined 9C ST undefined 9D OSC undefined 9E PM undefined 9F APC undefined A0 undefined undefined A1 ¡ undefined A2 ¢(cent sign) s A3 £ t A4 undefined u A5 ¥ v A6 undefined w A7 § x (continued on next page) Introduction to DEC DB Integrator Gateway for DB2 Client 1-23 Table_1-1_(Cont.)_Computer_Character_Sets_________________ Hex Value__DMCS_Character_________EBCDIC_Character____________ A8 ¤ y A9 © z AA ª (feminine ordinal) undefined AB « undefined AC undefined undefined AD undefined undefined AF undefined undefined B0 ° undefined B1 ± undefined B2 ² undefined B3 ³ undefined B4 undefined undefined B5 µ undefined B6 ¶ undefined B7 (bullet) undefined B8 undefined undefined B9 ¹ undefined BA º (masculine ordinal) undefined BB » undefined BC ¼ undefined BD ½ undefined BE undefined undefined BF ¿ undefined C0 À undefined C1 Á A C2 Â B C3 Ã C C4 Ä D (continued on next page) 1-24 Introduction to DEC DB Integrator Gateway for DB2 Client Table_1-1_(Cont.)_Computer_Character_Sets_________________ Hex Value__DMCS_Character_________EBCDIC_Character____________ C5 Å E C6 Æ F C7 Ç G C8 È H C9 É I CA Ê undefined CB Ë undefined CC Ì undefined CD Í undefined CE Î undefined CF Ï undefined D0 undefined undefined D1 Ñ J D2 Ò K D3 Ó L D4 Ô M D5 Õ N D6 Ö O D7 OE P D8 Ø Q D9 Ù R DA Ú undefined DB Û undefined DC Ü undefined DD Ý undefined DE undefined undefined DF ß undefined E0 à undefined (continued on next page) Introduction to DEC DB Integrator Gateway for DB2 Client 1-25 Table_1-1_(Cont.)_Computer_Character_Sets_________________ Hex Value__DMCS_Character_________EBCDIC_Character____________ E1 á undefined E2 â S E3 ã T E4 ä U E5 å V E6 æ W E7 ç X E8 è Y E9 é Z EA ê undefined EB ë undefined EC ì undefined ED í undefined EE î undefined EF ï undefined F0 undefined 0 F1 ñ 1 F2 ò 2 F3 ó 3 F4 ô 4 F5 õ 5 F6 ö 6 F7 oe 7 F8 ø 8 F9 ù 9 FA ú undefined FB û undefined FC ü undefined (continued on next page) 1-26 Introduction to DEC DB Integrator Gateway for DB2 Client Table_1-1_(Cont.)_Computer_Character_Sets_________________ Hex Value__DMCS_Character_________EBCDIC_Character____________ FD ý undefined FE undefined undefined FF_____undefined______________undefined___________________ 1.9 Network and Communications Support for the Gateway for DB2 Client The gateway for DB2 client uses the DEC SNA gateway software to communicate with the IBM system. The gateway and its associated resources must be defined to the IBM system software (ACF/VTAM, CICS). As many logical units as needed should be made available to gateway for DB2 client users to support peak simultaneous access to the IBM system. Digital recommends that an access name specifically for gateway for DB2 client use be included in the gateway configuration file. An access name has associated with it the circuit name or physical unit, a range of session addresses, the VTAM application ID of the application the process is connecting to, and a logon mode name. If the gateway to DB2 client does not specify the access name, then the other parameters have to be specified individually. 1.9.1 IBM Systems Software When defining the gateway to the IBM system software, the IBM systems programmer should follow the instructions given in the OpenVMS SNA Guide to IBM Parameters, specifically noting the requirements for DEC APPC/LU6.2. The OpenVMS SNA Guide to IBM Parameters provides the information that the IBM systems programmer needs to specify for the following software components: o ACF/VTAM o CICS Introduction to DEC DB Integrator Gateway for DB2 Client 1-27 The IBM systems programmer should check the VTAM Logon Mode Table entry that will be used for the gateway for DB2 client and server communication. The VTAM Logon Mode Table entry defines the session characteristics (such as RU sizes) of sessions between two logical units. The Logon Mode Table entry should be appropriate for LU type 6.2 communications and, to enhance performance, should specify an RU size of 2048 or greater. 1-28 Introduction to DEC DB Integrator Gateway for DB2 Client 2 ________________________________________________________________ Preparing for DEC DB Integrator Gateway for DB2 Client Installation This chapter discusses the preparations and requirements necessary for installing the DEC DB Integrator Gateway for DB2 Client. Your bill of materials (BOM) and indented bills report (BIL) specify the number and contents of your media. Be sure to verify the contents of your kit with this information. If your kit is damaged or if you find that parts of it are missing, contact your Digital representative. DEC DB Integrator Gateway for DB2 Client provides online release notes. Digital strongly recommends that you read the release notes before proceeding with the installation. For information on accessing the online release notes, see Section 3.1. 2.1 Prerequisite Hardware DEC DB Integrator Gateway for DB2 Client works with all AXP and VAX hardware. 2.2 Prerequisite and Optional Software You must have the following software installed on the same node on which you will install the gateway for DB2 client and it must be installed before you install the gateway for DB2 client: o OpenVMS VAX Version 5.5-2 o OpenVMS AXP Version 6.1 o Common Components-refer to Section 2.2.1 for instruc- tions Preparing for DEC DB Integrator Gateway for DB2 Client Installation 2-1 In addition, you can have DEC DB Integrator installed and use it with the gateway for DB2 client. You must have the following software installed on the system that will be the server system for the DB2 client: o DEC DB Integrator Gateway for DB2 Server Version 3.1 The Software Product Description (SPD) contains a complete list of prerequisite and optional software and their required version numbers. 2.2.1 Common Components Installation Requirement The Common Components are software components that provide relational database functions for several Digital products. The Common Components consist of: o SQL interface o SQL/Services server o Rdb/Dispatch interface and Rdb/Remote server The Common Components are required in order to use the following products: o DEC DB Integrator (DBI) o DEC DB Integrator Gateway products o DEC Rdb DBI requires Common Components in the following ways: o Any process that runs the DBI software or that accesses a DBI logical database, locally or remotely, requires Rdb/Dispatch. For example, if a DBI application is running on a local node and attaches to a DBI logical database on a remote node, both nodes must have Rdb/Dispatch installed. o Creating a DBI logical database requires SQL. A Common Components kit is provided with each product. The Common Components kit is part of the DEC Rdb media kit and the Common Components have the same version number as DEC Rdb. However, you can install the Common Components separately from the other components of DEC Rdb and they do not require a DEC Rdb license. 2-2 Preparing for DEC DB Integrator Gateway for DB2 Client Installation 2.2.1.1 Why You Must Install Common Components Each product that requires Common Components requires a specific version of Common Components. In the case of DEC Rdb, the product installation automatically includes the Common Components installation. For DBI or a DBI gateway installation, however, you must separately install the Common Components. If the required version of Common Components is not installed on your system, you can install DBI or a DBI gateway, but you cannot successfully use the product. The DBI or gateway installation procedure prints a warning and completes, but the Installation Verification Procedure (IVP) fails. Because each product requires a specific version of Common Components, you may need to have more than one version of Common Components installed on a system at any given time. For example, suppose you want to install DBI on a system running VAX Rdb/VMS Version 4.2 with a critical set of databases and applications. The Version 4.2 Common Components cannot be disturbed. However, to use DBI Version 3.1, you must install Common Components Version 6.0. The solution is to install the multiversion variant of Common Components Version 6.0, as described in Section A.1.2. This variant allows multiple versions of Common Components, or DEC Rdb itself, to coexist on the same system without affecting each other, and does not significantly add to the tasks of system or database administration. 2.2.1.2 Checking for Common Components It is not necessary to install a single version of Common Components more than once per system. Use the following procedure to determine whether or not the correct version of Common Components has already been installed on a system. If Version 6.0 has not been installed, you must perform the procedure described in Appendix A in order to use Version 3.1 of DBI or any DBI gateway product. Preparing for DEC DB Integrator Gateway for DB2 Client Installation 2-3 To find out if the Common Components have been installed on your OpenVMS system, enter: $ DIR SYS$LIBRARY:SQL$SETVER.COM If the file SYS$LIBRARY:SQL$SETVER.COM does not exist, you must install Common Components. If the file does exist, enter: $ @SYS$LIBRARY:SQL$SETVER 6.0 If you see any of the following messages, you must install Common Components: %SQL-E-SETVER SQL Version 6.0 does not exist on your system. %SQL-E-SETVER SYS$COMMON:[SYSLIB]SQL$SHR.EXE Image Ident Problem %SQL-E-SETVER IMAGE IDENT = n.n, VERSION = 6.0 The last two messages indicate that standard (nonmul- tiversion) DEC Rdb software has been installed on the system. If you see the following messages, with or without the word MULTIVERSION, Common Components have already been installed. You do not need to install the Common Components software again. Current PROCESS SQL environment is version V6.0-nn (MULTIVERSION) Current PROCESS Rdb/Dispatch environment is version V6.0-nn (MULTIVERSION) 2.3 License Registration Before you install and run the gateway for DB2 client on a newly licensed node or cluster, you must first register a Product Authorization Key (PAK) using the License Management Facility (LMF). The PAK may be shipped along with the kit if you ordered the license and media together; otherwise, it is shipped separately to a location based on your license order. If you are installing the gateway for DB2 client as an update on a node or cluster already licensed for this software, you have previously completed the PAK registration requirements. 2-4 Preparing for DEC DB Integrator Gateway for DB2 Client Installation If you are installing prerequisite or optional software along with the gateway for DB2 client, review the PAK status and install the PAKs for any prerequisite or optional software before you install the gateway for DB2 client. You must register and load your license for the gateway for DB2 client before you can use the software. To register a license under OpenVMS, first log in to the system manager's account, SYSTEM. You then have a choice of two ways to perform the registration: o Invoke the SYS$UPDATE:VMSLICENSE.COM procedure. When it prompts you for information, respond with data from your PAK. o At the DCL prompt, enter the LICENSE REGISTER command with the appropriate qualifiers that correspond to PAK information. 2.4 Installation Procedure Requirements The following sections discuss various requirements for installing DEC DB Integrator Gateway for DB2 Client. The installation takes approximately 1 minute. Installing the gateway for DB2 client and running the Installation Verification Procedure (IVP) takes approximately 2 minutes. 2.4.1 Privileges Required To install the gateway for DB2 client, you must be logged in to an account that has SETPRV or at least the following privileges: o CMKRNL o WORLD o SYSPRV The VMSINSTAL procedure turns off BYPASS privilege at the start of the installation. Preparing for DEC DB Integrator Gateway for DB2 Client Installation 2-5 2.4.2 Disk Space The following sections list the disk space required for installation and show you how to check for available disk space. 2.4.2.1 Disk Space Required Table 2-1 summarizes the storage requirements for the gateway for DB2 client during installation and after installation. Table_2-1_Disk_Space_Requirements_________________________ Blocks During Blocks After Kit______________Installation__________Installation_______ DEC DB 20,156 12,804 Integrator Gateway for DB2 Client____________________________________________________ 2.4.2.2 Checking Disk Space To determine the number of available disk blocks on the current system disk, enter the following command at the DCL prompt: $ SHOW DEVICE SYS$SYSDEVICE 2.4.3 System Parameters The following sections list the system parameters required for installation and discuss how to check and calculate system parameters. 2.4.3.1 System Parameters Required Installing the gateway for DB2 client requires certain system parameter settings. Table 2-2 lists the minimum required system parameter values for the installation. Depending on the kinds of programs and applications running at your site, you might need higher values for some settings. 2-6 Preparing for DEC DB Integrator Gateway for DB2 Client Installation Table_2-2_Minimum_Required_System_Parameter_Values________ System_Parameter___________Minimum_Value__________________ GBLPAGES[1] n+5912 GBLSECTIONS[1] n+5 PROCSECTCNT 90 VIRTUALPAGECNT 35,000 [1]The_values_listed_for_these_system_parameters_represent the number of available global pages and global sections required for the installation, not the total number you need to run your system and other software. __________________________________________________________ The following sections show you how to: o Check system parameter values o Calculate values for the GBLPAGES and GBLSECTIONS system parameters o Change parameter values with the OpenVMS AUTOGEN utility o Set dynamic parameters with the OpenVMS System Generation utility (SYSGEN) 2.4.3.2 Checking System Parameter Values To check the values of your system parameters, enter the following command at the DCL prompt to invoke SYSGEN: $ RUN SYS$SYSTEM:SYSGEN SYSGEN> At the SYSGEN> prompt, enter the SHOW command to display the value of a system parameter. The values displayed should equal or exceed the value of each system parameter listed in Table 2-2. The following example displays the value for the WSMAX system parameter: SYSGEN> SHOW WSMAX After checking the parameters with the SHOW command, enter the EXIT command at the SYSGEN> prompt to return to DCL level. Preparing for DEC DB Integrator Gateway for DB2 Client Installation 2-7 2.4.3.3 Calculating the Values for GBLPAGES and GBLSECTIONS To install and run the gateway for DB2 client, you must have sufficient available global pages and global sections. You must first find out how many available global pages and sections you have on your system. Then use AUTOGEN if you need to increase the GLBPAGES and GBLSECTIONS system parameters. The n + 5912 value for GBLPAGES and the n + 5 value for GBLSECTIONS in Table 2-2 indicate that you must have at least 5912 unused global pages and 5 unused global sections available on your system for the installation to process successfully. To calculate how many unused global pages and global sections your system has use the WRITE command with the F$GETSYI lexical function to find the number of available global pages and global sections. The following example shows how to get this information at your terminal (the default for SYS$OUTPUT): $ WRITE SYS$OUTPUT F$GETSYI("FREE_GBLPAGES") 15848 $ WRITE SYS$OUTPUT F$GETSYI("FREE_GBLSECTS") 24 If the values displayed by the system are greater than the values in Table 2-2, you do not need to increase the values for these parameters. If the displayed values of global pages or global sections are less than the values in Table 2-2, you must increase the system parameter setting. Section 2.4.3.4 describes the procedures for increasing these values using the AUTOGEN utility. 2.4.3.4 Changing System Parameter Values with AUTOGEN Use the AUTOGEN utility to change system parameters. The AUTOGEN utility automatically adjusts values for parameters that are associated with the values you reset manually. To change system parameters with AUTOGEN, edit the following file: SYS$SYSTEM:MODPARAMS.DAT Use an editor to access the file. To change a parameter value listed in this file, delete the current value associated with that parameter and enter the new value. 2-8 Preparing for DEC DB Integrator Gateway for DB2 Client Installation To add a new parameter, add a line to the file that includes both the name of the parameter and its value, for example: WSMAX = 1024 To modify incremental parameters such as GBLPAGES and GBLSECTIONS, use the prefix ADD_. The following example increases the global page setting by 2000: ADD_GBLPAGES = 2000 When you set the page file quota, do not use a value that exceeds the amount of page file space available on the system. After you make all your changes, exit from the editor and execute the AUTOGEN utility to recalculate your system parameters. Enter the following command at the DCL prompt: $ @SYS$UPDATE:AUTOGEN GETDATA REBOOT When you specify REBOOT, the AUTOGEN utility performs an automatic system shutdown and then restarts (reboots) the system. Any users logged on to the system are immediately disconnected during the shutdown. The automatic reboot puts the new parameter values into effect. The AUTOGEN utility automatically adjusts some of the SYSGEN parameters based on the consumption of resources since the last reboot. If you do not want to take advantage of this automatic adjustment, include the NOFEEDBACK qualifier on the AUTOGEN command line. For more information about using AUTOGEN, see the OpenVMS System Management documentation. 2.4.4 VMSINSTAL Requirements When you invoke the VMSINSTAL procedure, it checks the following: o If you have set your default device and directory to SYS$UPDATE o If you are logged in to a privileged account o If you have adequate quotas for installation o If DECnet is running Preparing for DEC DB Integrator Gateway for DB2 Client Installation 2-9 o If any users are using the system help library If the VMSINSTAL procedure detects any problems during the installation, it notifies you and asks if you want to continue the installation. In some instances, you can enter YES to continue. To stop the installation process and correct the situation, enter NO or press the Return key. Then correct the problem and restart the installation. 2.4.5 System Disk Backup At the beginning of the installation, the VMSINSTAL procedure asks if you have backed up your system disk. Digital recommends that you do a system disk backup before installing any software. Use the backup procedures that are established at your site. For details on performing a system disk backup, see the section on the Backup utility in the OpenVMS System Management documentation. 2-10 Preparing for DEC DB Integrator Gateway for DB2 Client Installation 3 ________________________________________________________________ Installing DEC DB Integrator Gateway for DB2 Client This chapter explains how to install DEC DB Integrator Gateway for DB2 Client. Section 3.1 contains a step-by- step description of the installation procedure. Section 3.2 describes the Installation Verification procedure. The samples shown in this chapter are from a VAX installation. An AXP installation would be similar. 3.1 Installation Procedure The gateway for DB2 client installation procedure consists of a series of questions and informational messages. See Appendix B for sample installations. To abort the installation procedure at any time, press the Ctrl/Y keys. When you press Ctrl/Y, the installation procedure deletes all files it has created up to that point and exits. You can then start the installation again. 1. Invoke VMSINSTAL. @SYS$UPDATE:VMSINSTAL saveset-name device-name OPTIONS N To start the installation, invoke the VMSINSTAL command procedure from a privileged account, such as the SYSTEM account. The VMSINSTAL procedure is in the SYS$UPDATE directory. The following list defines the elements of the VMSINSTAL command procedure: Installing DEC DB Integrator Gateway for DB2 Client 3-1 saveset-name The installation name for the component. For the gateway for DB2 client, use the following installation name: LDB2031 device-name The name of the device on which you plan to mount the media. For example, MTA0: is the device name for a tape drive. It is not necessary to use the console drive for this installation. However, if you do use the console drive, you should replace any media you removed once the installation is complete. OPTIONS N An optional parameter that indicates you want to see the question on release notes. The question on release notes asks if you want to print or display the release notes. If you do not include the OPTIONS N parameter, VMSINSTAL does not ask you about the release notes. You should review the release notes before proceeding with the installation in case they contain additional information about the installation. If you are restarting the installation and have already reviewed the release notes, you do not need to specify OPTIONS N. There are several other options you can select when you invoke VMSINSTAL. o Auto_answer option (A): Initially creates a file that contains your answers to VMSINSTAL questions and prompts. You can then use the option (and the answer file) to save time during a re-installation (typically after upgrading your system). o Get saveset option (G): Lets you store product save sets temporarily on a magnetic tape or in a disk directory. o File log option (L): Logs all activity to the terminal during installation. 3-2 Installing DEC DB Integrator Gateway for DB2 Client o Alternate root option (R): Lets you install the product to a system root other than that of the running system. See the OpenVMS documentation on software installation in the OpenVMS System Management documentation for detailed information on these options. If you specify more than one option, separate the options with commas (OPTIONS A,N). The following example invokes VMSINSTAL to install the gateway for DB2 client from tape drive MTA0: and shows the system response. This example uses the OPTIONS N release note parameter. $ @SYS$UPDATE:VMSINSTAL LDB2031 MTA0: OPTIONS N VMS/VAX Software Product Installation Procedure V5-5.2 It is 12-OCT-1994 at 16:53. Enter a question mark (?) at any time for help. If you do not supply either the product name or the device name, VMSINSTAL prompts you for this information later in the installation procedure. The VMSINSTAL procedure does not prompt you for any options, so be sure to include OPTIONS N on the VMSINSTAL command line to access the release notes during the installation. 2. Note active processes. %VMSINSTAL-W-ACTIVE, The following processes are still active: SQLSRV$SERVER * Do you want to continue anyway [NO]?Y * Are you satisfied with the backup of your system disk [YES]? The VMSINSTAL procedure displays a list of all active processes and asks if you want to continue with the installation. The default answer is NO. 3. Confirm system backup. * Are you satisfied with the backup of your system disk [YES]? The VMSINSTAL procedure asks if you are satisfied with your system backup. You should always back up Installing DEC DB Integrator Gateway for DB2 Client 3-3 your system disk before performing an installation. If you are satisfied with the backup of your system disk, press the Return key. Otherwise, enter NO to discontinue the installation. After you back up your system disk, you can restart the installation. 4. Mount the media. Please mount the first volume of the set on MTA0:. * Are you ready? YES %MOUNT-I-MOUNTED, DEC DB Integrator Gateway for DB2 Client MOUNTED ON _$$MTA0: (NODE 1) The following products will be processed: LDB2 V3.1 Beginning installation of LDB2 V3.1 at 16:54 %VMSINSTAL-I-RESTORE, Restoring product save set A... You should now mount the first distribution volume on the device you specified when you invoked VMSINSTAL. The device name appears in the line preceding the question. VMSINSTAL then asks you if you are ready to continue with the installation. If you respond YES to indicate that you are ready, VMSINSTAL displays a message that the media containing the gateway for DB2 client has been mounted on the specified device and that the installation has begun. If you entered the wrong device name when you invoked VMSINSTAL and need to restart the installation, enter NO in response to the "Are you ready?" question. To abort the installation for other reasons, press Ctrl/Y. 5. Select a release notes option. If you specified OPTIONS N when you started the installation, VMSINSTAL asks a question on release notes. You have four options for handling the release notes. You see the following display: 3-4 Installing DEC DB Integrator Gateway for DB2 Client Release notes included with this kit are always copied to SYS$HELP. Additional Release Notes Options: 1. Display release notes 2. Print release notes 3. Both 1 and 2 4. None of the above * Select option [2]: If you select option 1, VMSINSTAL displays the release notes immediately on the terminal. You can terminate the display at any time by pressing Ctrl/C. If you select option 2, VMSINSTAL prompts you for the name of the print queue: * Queue name [SYS$PRINT]: You can press the Return key to send the file to the default output print device or you can enter another queue name. If you select option 3, VMSINSTAL displays the release notes immediately on the terminal and then prompts you for a queue name for the printed version. Select option 4 if you reviewed the release notes and are restarting the installation. Next, VMSINSTAL displays the following question: * Do you want to continue the installation [N]?: Y %VMSINSTAL-I-RELMOVED, Product's release notes have been moved to SYS$HELP. To continue the installation, enter Y or YES. Otherwise, press the Return key. In either case, the release notes are copied to a file in the SYS$HELP directory: SYS$HELP:LDB2031.RELEASE_NOTES ________________________Note ________________________ The name of the release notes file installed by VMSINSTAL consists of LDB2 and a 3-digit version Installing DEC DB Integrator Gateway for DB2 Client 3-5 number. _____________________________________________________ 6. Print installation guide. ************************************************************** Installation procedure for DEC DB Integrator Gateway Client for DB2 V3.1-00 for OpenVMS VAX ************************************************************** © Digital Equipment Corporation 1993,1994. All rights reserved. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c) (1) (ii) of DFARS 252.227-7013, or in FAR 52.227-19, or in FAR 52.227-14 Alt. III, as applicable. This software is proprietary to and embodies the confidential technology of Digital Equipment Corporation. Possession, use, or copying of this software and media is authorized only pursuant to a valid written license from Digital or an authorized sublicensor. ************************************************************** * Would you like to print the LDB2 Installation guide? [NO]: * Do you want to proceed with the installation? [YES]: The installation procedure asks if you would like to print the installation guide. It then asks if you want to continue with the installation. 3-6 Installing DEC DB Integrator Gateway for DB2 Client 7. Respond to license registration queries. Product: DB-GATEWAY-DB2 Producer: DEC Version: 3.1 Release Date: 1-SEP-1994 * Does this product have an authorization key registered and loaded? The installation procedure displays license information about your product and then asks if you have registered and loaded your Product Authorization Key (PAK). If you have not registered and loaded your PAK, you must answer NO to this question. You have to register and load your PAK to successfully complete the installation. If you have not done so, you should stop the installation, register and load your PAK, and then restart the installation. 8. Decide if you want to purge files. * Do you want to purge files replaced by this installation [YES]? You have the option of purging files replaced by this installation. 9. Read about the Installation Verification Procedure (IVP) option. There are no more questions. The installation takes approximately 1 to 5 minutes depending on the processor type. Because the Installation Verification Procedure is interactive, it will not be run as part of the installation. You may run the IVP separately any time you wish. To execute it, type: $ @SYS$TEST:LDB2$IVP The installation procedure provides information about running the IVP after the installation. The IVP for the gateway for DB2 client checks to be sure that the installation is successful. It is recommended that you run the IVP. Installing DEC DB Integrator Gateway for DB2 Client 3-7 See Section 3.2 for more information about running the IVP. 10.Read messages. At this point, the installation procedure displays a number of messages that report on the progress of the installation. There are no further questions. If the installation procedure has been successful up to this point, VMSINSTAL moves the new or modified files to their target directories, updates help files, and updates DCL tables, if necessary. If you chose to have files purged, that work is done now. The following messages are displayed: ************************************************************** Beginning installation of DEC DB Integrator Gateway Client for DB2 V3.1-00 ************************************************************** %VMSINSTAL-I-RESTORE, Restoring product save set B ... ************************************************************** LDB2$STARTUP.COM has been placed in SYS$STARTUP. The following line should be placed in your system startup file. $ @SYS$STARTUP:LDB2$STARTUP.COM ************************************************************** LDB2$SHUTDOWN.COM has been placed in SYS$MANAGER. The following line should be placed in your system shutdown file. $ @SYS$STARTUP:LDB2$SHUTDOWN.COM ************************************************************** ************************************************************** Finishing installation of DEC DB Integrator Gateway Client for DB2 V3.1-00 ************************************************************** %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... 3-8 Installing DEC DB Integrator Gateway for DB2 Client 11.Note the end of the installation procedure. Installation of LDB2 3.1 completed at 16:55 Adding history entry in VMI$ROOT:[SYSUPD]VMSINSTAL.HISTORY Creating installation data file: VMI$ROOT:[SYSUPD]LDB2031.VMI_DATA VMSINSTAL procedure done at 16:55 The previous messages indicate that the entire installation procedure is complete. You can now log out of the privileged account: $ LOGOUT SYSTEM logged out at 12-OCT-1994 16:56:00.00 The VMSINSTAL procedure deletes or changes entries in the process symbol tables during the installation. Therefore, if you are going to continue using the system manager's account and you want to restore these symbols, you should log out and log in again. 3.2 Running the Installation Verification Procedure (IVP) The Installation Verification Procedure (IVP) is interactive; it is not run as part of the installation. You can run the IVP separately any time you wish. To execute it, enter: $ @SYS$TEST:LDB2$IVP ***************************************************************** Installation Verification Procedure (IVP) for DEC DB Integrator Gateway for DB2 Client V3.1-00 for OpenVMS VAX Copyright Digital Equipment Corporation 1993,1994. All rights reserved. This IVP verifies that all the gateway images are in place and a simple query can be executed. ***************************************************************** Installing DEC DB Integrator Gateway for DB2 Client 3-9 The IVP prompts you for an attach specification to be used to attach to the DB2 database. After you enter the attach specification and the IVP confirms it, the IVP attaches to the database and displays the output of an SQL SHOW TABLES statement. Enter a SQL attach string terminated by a semi-colon. Example: /TYPE=DB2/USER=FRED/PASSWORD=CHRIS/NODE=NODE01/TIDCS=DBIV/ACCESS_NAME=MYACCESS /LOGON_MODE=MYMODE/DATABASE=MYDATABASE; attach string:/TYPE=DB2/USER=DBIUSER/PASSWORD=PASSWORD/NODE=SNAGWY /ACC=CICS/DATA=PERSONNL The current string is: /TYPE=DB2/USER=DBIUSER/PASSWORD=PASSWORD/NODE=SNAGWY/ACC=CICS/DATA=PERSONNL Are you satisfied with that? (Y/N):Y Current PROCESS SQL environment is version T6.1-05 (STANDARD) Current PROCESS Rdb/Dispatch environment is version T6.1-05 (STANDARD) User tables in database with filename SQL$DATABASE COLLEGES DEGREES DEPARTMENTS EMPLOYEES JOBS JOB_HISTORY SALARY_HISTORY WORK_STATUS When the IVP is finished, the following message is displayed: IVP completed successfully. 3.3 Error Recovery If errors occur during the installation itself or when the IVP is running, VMSINSTAL displays failure messages. If the installation fails, you see the following message followed by more information: %VMSINSTAL-E-CANT-INSTALL, Error installing LDB2. The installation failed for the following reasons: 3-10 Installing DEC DB Integrator Gateway for DB2 Client If the IVP fails, you see this message: ******************************** The IVP has failed ******************************** Errors can occur during the installation if any of the following conditions exists: o The operating system version is incorrect. o Quotas necessary for successful installation are insufficient. o System parameter values for successful installation are insufficient. o The VMS Help Library is currently in use. For descriptions of the error messages generated by these conditions, see the OpenVMS documentation on system messages, recovery procedures, and OpenVMS software installation. If you are notified that any of these conditions exists, you should take the appropriate action as described in the message. For information on installation requirements, see Chapter 2. Installing DEC DB Integrator Gateway for DB2 Client 3-11 4 ________________________________________________________________ After Installing DEC DB Integrator Gateway for DB2 Client The following tasks take place after installing DEC DB Integrator Gateway for DB2 Client: o Running the Installation Verification Procedure separately o Editing the system startup files o Setting user account quotas and privileges o Reporting problems 4.1 Running the Installation Verification Procedure Separately You usually run the Installation Verification Procedure (IVP) immediately following the installation. You can also run the IVP at a later time to ensure the integrity of installed files should system problems occur. Enter the following command to execute the IVP command procedure: $ @SYS$TEST:LDB2$IVP.COM See Section 3.2 for a description of the IVP. 4.2 Editing the System Files You may want to edit the system startup files to provide for automatic startup of the gateway for DB2 client when your system is restarted. Add the command line that starts the gateway for DB2 client to the system startup file, SYS$MANAGER:SYSTARTUP.COM. The LDB2$STARTUP.COM procedure installs the gateway images as shared images. This reduces system overhead and memory requirements when running the gateway for DB2. After Installing DEC DB Integrator Gateway for DB2 Client 4-1 You must position this new command line after the line that invokes the network startup command procedure. The following example shows the network startup command line followed by the gateway for DB2 client startup command line: $ @SYS$MANAGER:STARTNET.COM . . . $ @SYS$STARTUP:LDB2$STARTUP.COM 4.3 User Account Requirements To work with the gateway for DB2 client, user accounts on your system must have certain privileges and quotas. The next two sections contain information on these requirements. 4.3.1 Privileges To use the gateway for DB2 client, each account must have at least the TMPMBX and NETMBX privileges. Use the OpenVMS Authorize utility (AUTHORIZE) to determine whether or not users have the privileges they require. 4.4 Determining and Reporting Problems If you encounter a problem while using the gateway for DB2 client, report it to Digital. 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 Send Us Your Comments form if the problem has to do with the gateway for DB2 client documentation. These forms are at the front of each manual. Use the form from the manual in which you found the error. Include the section and page number. 4-2 After Installing DEC DB Integrator Gateway for DB2 Client Review the Software Product Description (SPD) and Warranty Addendum for an explanation of warranty. If you encounter a problem during the warranty period, report the problem as indicated previously or follow alternate instructions provided by Digital for reporting SPD nonconformance problems. After Installing DEC DB Integrator Gateway for DB2 Client 4-3 A ________________________________________________________________ Prerequisite Installation of Common Components This chapter describes how to install the Common Components, a prerequisite for installation of DEC DB Integrator (DBI) and the DEC DB Integrator Gateway products (DB Integrator Gateways, also referred to as the gateway products). Please note the following requirements: o If you have an existing DEC Rdb kit on your system, you must install the Common Components or install DEC Rdb Version 6.0 before you can use any member of the DBI product family. o If you choose not to upgrade to DEC Rdb Version 6.0, Digital recommends that you install the multiversion Common Components. Installing the multiversion Common Components will not break applications or production systems that require previous versions of DEC Rdb. For more information, see Section A.1.2. o If you do not have DEC Rdb on your system, and do not plan to install it, you must install the Common Components before you can use the DBI product family. A.1 Common Components The Common Components provides support for relational database functions for Digital database products. These components are common to DBI, the DBI gateway products, and DEC Rdb. The Common Components are: o SQL interface o SQL/Services server Prerequisite Installation of Common Components A-1 o Rdb/Dispatch and Rdb/Remote server These components must be present on a system in order to run SQL applications. A.1.1 Media Required When you purchase any of the Digital database access products (DBI, DB Integrator Gateways, or DEC Rdb), you receive the kit for that product, plus an entire DEC Rdb software kit, which contains the Common Components. You only need to install the Common Components from the DEC Rdb kit, not the entire kit to use the Common Components with DBI or the gateway products. Install the Common Components using the DEC Rdb installation procedure by choosing the Common Components option during the installation. The Common Components must be present on your system before you can install DBI or a gateway product. A.1.2 Version Variants and Existing Databases If you have a version of DEC Rdb prior to Version 6.0 installed, you do not need to upgrade DEC Rdb in order to install members of the DBI product family, but you must install the Common Components from the DEC Rdb media. Digital recommends that you install the multiversion Common Components if you expect to maintain more than one version of Rdb. The Common Components have two possible variants: o Standard Use when you have only one version of DEC Rdb on your system. o Multiversion Use when you have multiple versions of DEC Rdb or a version DEC Rdb that is different from the version of the Common Components being installed. Installing the multiversion variant will not write over any existing DEC Rdb images from previous versions, such as the Online Help. If you install the multi- version variant of Common Components, you can use the SYS$LIBRARY:SQL$SETVER.COM procedure to control the A-2 Prerequisite Installation of Common Components version of Common Components whenever your database environment requires a particular version of SQL or Rdb/Dispatch. For more information about SQL$SETVER, see Section A.8. A.2 Disk Space Required The following tables summarize the storage requirements for installing the Common Components. The values in the lists are approximate. The disk space requirements for OpenVMS AXP are: __________________________________________________________ Needed for Used After Kit______________Installation_________Installation________ Full Development 62,000 62,000 Run-Time_________62,000_______________39,000<>____________ The disk space requirements for OpenVMS VAX are: __________________________________________________________ Used After Kit______________Needed_for_Installation_Installation_____ Full Development 40,000 40,000 Run-Time_________40,000__________________28,000<>_________ A.3 OpenVMS Privileges Required The VMSINSTAL command procedure is located in SYS$UPDATE, which is a restricted directory. To install the Common Components, you must use an account that has the SETPRV privilege authorized. As one of its first actions, the VMSINSTAL command procedure grants all privileges except BYPASS to the process that invokes it. The VMSINSTAL command succeeds only if the installing account has SETPRV privilege. To check the default privileges of the installing account, log in and enter this DCL command: $ SHOW PROCESS/PRIVILEGES Prerequisite Installation of Common Components A-3 If the installing account lacks the SETPRV privilege, you cannot install the Common Components. You have two options: o Ask your system manager to use the OpenVMS Authorize utility (AUTHORIZE) to modify the default privileges of the account to include the SETPRV privilege. A-4 Prerequisite Installation of Common Components o Run AUTHORIZE and make the changes yourself, if the installing account has the SYSPRV privilege: $ SET DEFAULT SYS$SYSTEM $ RUN AUTHORIZE UAF> MODIFY /PRIVILEGES=(SETPRV) UAF> EXIT To activate the change in privileges, you must log out and then log in. ________________________Note ________________________ When installing the Common Components on systems with DECnet/OSI, the installing account must also have the NET$MANAGE identifier. _____________________________________________________ A.4 Unlocking the Process Account Password The installing account cannot have a locked password. If this is the initial installation of the Common Components, the installation procedure creates an account called RDB$REMOTE, or RDB$REMOTEnn for a multiversion installation. If the installing account has a locked password, the installation procedure will be unable to automatically generate a password for this account, and will abort with the following message: ************************************************************* Error generating password for remote account. ************************************************************** To modify an account with a locked password, enter: $ MCR AUTHORIZE UAF> MODIFY /FLAGS=NOLOCKPWD Prerequisite Installation of Common Components A-5 A.5 Installing Common Components To install Common Components: 1. Invoke the VMSINSTAL command procedure from a privileged account, using the following syntax: @SYS$UPDATE:VMSINSTAL variant-name device-name OPTIONS N Supply the appropriate name for the variant you want to install from the following table: _______________________________________________________ Name_____________Variant__________OpenVMS______________ DECRDBA060 standard AXP DECRDBAMV060 multiversion AXP DECRDB060 standard VAX DECRDBMV060______multiversion_____VAX__________________ Digital recommends that you install the multiversion kit. This avoids possible problems in writing over existing files and images for a different version of the Common Components or DEC Rdb. For example, to install the Common Components OpenVMS AXP multiversion kit on device ddcu, enter: $ @SYS$UPDATE:VMSINSTAL decrdbamv060 ddcu: OPTIONS N To install the Common Components OpenVMS VAX standard kit on device ddcu, enter: $ @SYS$UPDATE:VMSINSTAL decrdb060 ddcu: OPTIONS N 2. Type CC (for COMMON COMPONENTS) when prompted for the kit type to install. The menu and response should appear as follows: *********************************************************************** From the following menu, please select the type of DEC Rdb kit to install. Choice CC (COMMON COMPONENTS) is included in all 3 DEC Rdb installations and should only be selected when installing a product, other than DEC Rdb, that requires the common components. *********************************************************************** A-6 Prerequisite Installation of Common Components Please select the type of DEC Rdb kit you wish to install: Enter DEV for DEC Rdb DEVELOPMENT (the default) Enter INT for DEC Rdb INTERACTIVE Enter RTO for DEC Rdb RUNTIME-ONLY Enter CC for COMMON COMPONENTS * Enter the kit type to install [DEV]: CC Prerequisite Installation of Common Components A-7 When you enter CC, only the Common Components save set (B) will be restored. The following submenu will be displayed: *********************************************************************** The COMMON COMPONENTS option should be selected only when installing a product other than Rdb. It is not intended for use with any Rdb installation. *********************************************************************** Please select the type of COMMON COMPONENTS kit you wish to install: Enter DEV for DEVELOPMENT Enter RTO for RUNTIME-ONLY (the default) * Enter the type of COMMON COMPONENTS to install [RTO]: 3. Press the Return key to select the default option, RUNTIME-ONLY. Do not select the DEVELOPMENT option unless you have purchased one of the following development licenses: o DEC SQL development license o DEC Rdb development license o DEC DB Integrator (DBI) development license Selecting the DEVELOPMENT option provides the addi- tional SQL files needed for development: SQL$PREnn.EXE, SQL$MODnn.EXE; a small number of related files; and all the Rdb/Dispatch and SQL files installed with the RTO default. A.6 Installing Common Components Images as Shared The Common Components installation procedure does not install any images as shared. If you expect Common Components images to be used extensively on your system, you can reduce the system overhead and memory requirements by installing images as shared. When images are not installed as shared, multiple users who access the images at the same time must each have his or her own copy of those images in memory. When the images are installed as shared, everyone uses the same copy of the image, A-8 Prerequisite Installation of Common Components eliminating duplicate copies of an image and improving performance. Prerequisite Installation of Common Components A-9 A.6.1 Editing the Startup and Shutdown Procedures for Shared Images The separate startup and shutdown procedures, which are provided to install and remove the SQL and Rdb/Dispatch images, are as follows: o SYS$STARTUP:SQL$STARTUP.COM o SYS$MANAGER:SQL$SHUTDOWN.COM DBI and the DBI Gateways will call these procedures from their own startup and shutdown procedures. The following Rdb/Dispatch images are automatically installed by the SQL$STARTUP.COM procedure: o SYS$LIBRARY:RDBSHR.EXE o SYS$LIBRARY:RDB$SHARE.EXE o SYS$MESSAGE:RDBMSGS.EXE o SYS$MESSAGE:COSIMSG.EXE SQL files are not currently installed by the SQL$STARTUP.COM procedure. However, subroutines to install or to remove these images are included in the SQL$STARTUP.COM proce- dure. To activate the subroutines for the installation and/or removal of SQL images, remove the comment character (!) from the following lines in the SQL$STARTUP.COM and SQL$SHUTDOWN.COM procedures: $ ! GOSUB INSTALL_SQL_IMAGES $ ! GOSUB REMOVE_SQL_IMAGES If you invoke the INSTALL_SQL_IMAGES subroutine, the SQL$STARTUP.COM procedure installs the following SQL images: o SYS$LIBRARY:SQL$INT.EXE o SYS$LIBRARY:SQL$SHR.EXE o SYS$MESSAGE:SQL$MSG.EXE The INSTALL_SQL_IMAGES subroutine also includes code to install the SQL$UTL_SHARE60.EXE image and the development images, SQL$.EXE, SQL$MOD.EXE, and SQL$PRE.EXE. To execute the installations, remove the comment character preceding the code. The SQL$STARTUP.COM procedure provides an A-10 Prerequisite Installation of Common Components explanation why these images are not included in the default installations. Prerequisite Installation of Common Components A-11 Because SQL$UTL_SHAREnn.EXE is a variant image for both standard and multiversion Common Components, you must add additional lines of code to install images for each Common Components version you install as shared. Development images are not typically installed as shared images. A.6.2 Verifying Global Pages and Sections Table A-1 and Table A-2 show the remaining Common Components images not installed as shared on your system. SQL images not installed as shared during Common Components installation are also included in these tables to show the global page and global section requirements. If you install some or all of these images as shared, you must verify that you have enough global pages and global sections to accommodate the shared images. Use the following DCL F$GETSYI lexical function to determine the number of available global pages and global sections: $ WRITE SYS$OUTPUT F$GETSYI("FREE_GBLPAGES") $ WRITE SYS$OUTPUT F$GETSYI("FREE_GBLSECTS") If the number of unused global pages or global sections is less than the number specified in Table A-1 and Table A-2, increase the value using the AUTOGEN utility. Table A-1 lists the approximate number of global pages and global sections required for each Common Components OpenVMS VAX image that you install as shared. <> Table A-2 lists the approximate number of global pagelets and global sections required for each Common Components OpenVMS AXP image that you install as shared. On OpenVMS AXP systems, the size of a page can differ on different systems. Pagelets are 512 bytes and correspond to OpenVMS VAX pages; they are not system-specific. <> A-12 Prerequisite Installation of Common Components Table A-1 Global Pages and Sections Required for Common __________Components_OpenVMS_VAX_Images_________________________ GlobalGlobal Component_____________Image_Name[1]___________________Pages[Sections[2] SQL images SYS$LIBRARY:SQL$INT.EXE[3] 3 2 * SYS$LIBRARY:SQL$SHR.EXE 16 2 SYS$LIBRARY:SQL$UTL_ 142 3 SHARE60.EXE * SYS$MESSAGE:SQL$MSG.EXE 329 1 * SYS$SYSTEM:SQL$.EXE 1635 2 * SYS$SYSTEM:SQL$PRE.EXE 4911 3 * SYS$SYSTEM:SQL$MOD.EXE 4768 3 [1]If_you_have_installed_the_multiversion_variant_of_the_Common_ Components, some images have the version number added to the end of the image name. Those images are marked with an asterisk next to the image name. [2]Values supplied are approximate. If you have installed the multiversion variant of the Common Components, multiply the supplied values by the number of versions of the Common Components running on your system. [3]SQL$INT calls either SQL$SHR, or a version-specific variant (such as SQL$SHR60), depending on what version you have specified. ________________________________________________________________ Prerequisite Installation of Common Components A-13 Table A-2 Global Pagelets and Sections Required for Common __________Components_OpenVMS_AXP_Images_________________________ GlobalGlobal Component_____________Image_Name[1]___________________PageleSections[2] SQL images SYS$LIBRARY:SQL$INT.EXE[3] 65 1 * SYS$LIBRARY:SQL$SHR.EXE 2394 2 SYS$LIBRARY:SQL$UTL_ 431 2 SHARE60.EXE * SYS$MESSAGE:SQL$MSG.EXE 329 1 * SYS$SYSTEM:SQL$.EXE 3237 1 * SYS$SYSTEM:SQL$PRE.EXE 8461 2 * SYS$SYSTEM:SQL$MOD.EXE 8166 2 [1]If_you_have_installed_the_multiversion_variant_of_the_Common_ Components, some images have the version number added to the end of the image name. Those images are marked with an asterisk next to the image name. [2]Values supplied are approximate. If you have installed the multiversion variant of the Common Components, multiply the supplied values by the number of versions of the Common Components running on your system. [3]SQL$INT calls either SQL$SHR, or a version-specific variant (such as SQL$SHR60), depending on what version you have specified. ________________________________________________________________ A.6.3 Removing Installed Images The SQL$SHUTDOWN.COM procedure removes Common Components images that have been installed. By default, the SQL$SHUTDOWN.COM procedure removes only the images installed by Rdb/Dispatch. However, a subroutine is included that removes the SQL images. To activate this subroutine, remove the comment character (!) from the following line in the SQL$SHUTDOWN.COM procedure where this subroutine is invoked: $ ! GOSUB REMOVE_SQL_IMAGES ! In SQL$SHUTDOWN.COM A-14 Prerequisite Installation of Common Components The SQL$SHUTDOWN.COM procedure only removes images when no other client requiring the Common Components is installed on the system. Consequently, it requires that you pass a calling-client parameter, which is also referred to as P1, to determine if any other clients are still present on the system. You must execute the SQL$SETVER.COM procedure before you execute the SQL$SHUTDOWN.COM procedure. Otherwise, you receive an error message indicating that the logical names were not set. For more information about SQL$SETVER.COM, see Section A.8. The syntax for using the SQL$SHUTDOWN.COM procedure is as follows: $ @SYS$LIBRARY:SQL$SETVER $ @SYS$MANAGER:SQL$SHUTDOWN In the preceding example, is the Common Components version shipped with the client, and is one of the following: o DBI-use for DBI and the relational gateway products o NSDS-use for the nonrelational gateway products o RDBB-use for Rdb/ELN o RDM-use for DEC Rdb o VIDA-use for VIDA for IDMS/R o VIDA2-use for RdbAccess for DB2 Version 1.0 or Version 2.0 o VIDAO-use for RdbAccess for ORACLE Version 1.0 or Version 2.0 The relational gateway products are: o DEC DB Integrator Gateway for DB2 o DEC DB Integrator Gateway for EDA/SQL o DEC DB Integrator Gateway for ORACLE o DEC DB Integrator Gateway for SequeLink o DEC DB Integrator Gateway for SYBASE Prerequisite Installation of Common Components A-15 The nonrelational gateway products are: o DEC DB Integrator Gateway for Custom Drivers o DEC DB Integrator Gateway for DBMS o DEC DB Integrator Gateway for DSM o DEC DB Integrator Gateway for RMS The following example sets the Common Components to Version 6.0, then removes the images for the nonrelational gateway products: $ @SYS$LIBRARY:SQL$SETVER 6.0 $ @SYS$MANAGER:SQL$SHUTDOWN NSDS By default, the removal of images from the INSTALL utility is triggered by the logical names SQL$VERSION_VARIANT and RDB$DISPATCH_VERSION_VARIANT, which are defined by the SYS$LIBRARY:SQL$SETVER.COM procedure. ________________________Note ________________________ It is possible to set these logical names to different versions for the process, job, group, and system tables, if necessary. However, be very careful to avoid creating incompatibilities if you do so. Do this only when advised that it is absolutely necessary to solve a particular problem. _____________________________________________________ You can override the SQL$VERSION_VARIANT and RDB$DISPATCH_ VERSION_VARIANT logical names by passing a valid calling- client name as parameter P1, and the Common Components version to remove as P2. To override the use of the logical names to determine which Common Component images to remove, pass the version as P2. The following command removes Version 6.0 images: $ @SYS$MANAGER:SQL$SHUTDOWN DBI 6.0 If the DEC Rdb multiversion Version 6.0 software is installed, only the Version 6.0 images will be removed; otherwise the standard images, if they are Version 6.0 images, will be removed. A-16 Prerequisite Installation of Common Components A.7 Installing SQL Images for Privileged Applications Applications that use SQL and are installed with privileges require that you install the following images: o SYS$LIBRARY:SQL$INT.EXE o SYS$LIBRARY:SQL$SHR.EXE (or SYS$LIBRARY:SQL$SHR60.EXE) None of the SQL images supplied as part of the Common Components is installed unless you modify the SQL$STARTUP.COM procedure to permit it. Unless you install these images, applications installed with privileges will encounter the following error: %SQL-F-NOENTRYPT, Older SQL version not compatible with compiled SQL It is not necessary to install the SQL images as shared or with privileges to avoid this error. Installing in any manner will avoid the error. The separate startup and shutdown procedures, which are provided to install and remove the SQL and Rdb/Dispatch images, are as follows: o SYS$STARTUP:SQL$STARTUP.COM o SYS$MANAGER:SQL$SHUTDOWN.COM DBI and the DBI Gateways will call these procedures from their own startup and shutdown procedures. The following Rdb/Dispatch images are automatically installed by the SQL$STARTUP.COM procedure: o SYS$LIBRARY:RDBSHR.EXE o SYS$LIBRARY:RDB$SHARE.EXE o SYS$MESSAGE:RDBMSGS.EXE o SYS$MESSAGE:COSI$MSG.EXE Prerequisite Installation of Common Components A-17 A.7.1 Editing the Startup and Shutdown Procedures for Privileged Applications SQL files are not currently installed by the SQL$STARTUP.COM procedure. However, a subroutine to install these images is included in the SQL$STARTUP.COM procedure. To activate the installation and/or removal of SQL images, remove the comment character (!) from the following lines in the SQL$STARTUP.COM and SQL$SHUTDOWN.COM procedures: $ ! GOSUB INSTALL_SQL_IMAGES $ ! GOSUB REMOVE_SQL_IMAGES The INSTALL_SQL_IMAGES subroutine in the SQL$STARTUP.COM procedure installs the following SQL images: o SYS$LIBRARY:SQL$INT.EXE o SYS$LIBRARY:SQL$SHR.EXE (or SYS$LIBRARY:SQL$SHR60.EXE) o SYS$MESSAGE:SQL$MSG.EXE (or SYS$MESSAGE:SQL$MSG60.EXE) The subroutine also includes code to install the development images SQL$.EXE, SQL$MOD.EXE, and SQL$PRE.EXE, and the internal SQL utilities image SQL$UTL_SHARE60.EXE. To execute the installations, you must remove the comment character that precedes the code. The SQL$STARTUP.COM procedure provides an explanation of why these images are not included in the default installations. Because the SQL$UTL_SHAREnn.EXE image is a variant image for both standard and multiversion Common Components, you must add additional lines for each Common Components version you install as shared. Development images are not typically installed as shared images. If you install some or all of these images as shared, you must verify that you have enough global pages and global sections to accommodate the shared images. Table A-1 lists the approximate number of global pages and global sections required for each Common Components for OpenVMS VAX image that you install as shared.<> Table A-2 provides the global pagelets and sections required for the Common Components for OpenVMS AXP images. On OpenVMS AXP systems, the size of a page can differ on A-18 Prerequisite Installation of Common Components different CPUs. Pagelets are 512 bytes and correspond to OpenVMS VAX pages; they are not CPU-specific. <> A.8 Using Different Versions of the Common Components Certain environments may require a specific version of the Common Components, or may need to set each component to a different version. The SYS$LIBRARY:SQL$SETVER.COM and SYS$LIBRARY:SQL$SHOVER.COM procedures are provided with the Common Components installation to set up the logical names and symbols necessary for using a particular version of SQL and/or Rdb/Dispatch. ________________________Note ________________________ To use the DBI Gateway products or DEC DB Integrator, the Common Components' environment must be set to 6.0. This can be done at the system, group, or process level, as described in the following section. _____________________________________________________ The SQL$SETVER.COM procedure will accept the following three parameters: o P1 = (REQUIRED) version (that is, S for STANDARD, 6.0 for MULTIVERSION) or RESET to reset SQL symbols or REMOVE to remove SQL and DISPATCH logical names. o P2 = (OPTIONAL) Logical name table qualifier (PROCESS, GROUP, JOB, or SYSTEM). The default is PROCESS. o P3 = (OPTIONAL) Common Components logical names to set (SQL, DISPATCH, or ALL). The default is ALL. This can go in P2 or P3 as the last parameter. The following example sets both SQL and Rdb/Dispatch to multiversion Version 6.0. If multiversion Version 6.0 is not installed and a standard version is found, the standard version will be set. $ @SYS$LIBRARY:SQL$SETVER 6.0 Current PROCESS SQL environment is version 6.0-0 (MULTIVERSION) Current PROCESS Rdb/Dispatch environment is version 6.0-0 (MULTIVERSION) Prerequisite Installation of Common Components A-19 The following examples show other possible parameters: ! To set only Rdb/Dispatch $ @SYS$LIBRARY:SQL$SETVER 6.0 DISPATCH ! To set only SQL $ @SYS$LIBRARY:SQL$SETVER 6.0 SQL ! To set only SQL in group table $ @SYS$LIBRARY:SQL$SETVER 6.0 /GROUP SQL ! To set both SQL and Rdb/Dispatch to standard version $ @SYS$LIBRARY:SQL$SETVER S ! To set only Rdb/Dispatch to standard version $ @SYS$LIBRARY:SQL$SETVER S DISPATCH ! To set only SQL to standard version $ @SYS$LIBRARY:SQL$SETVER S SQL The SQL$SHOVER.COM procedure has the following two functions: o To show the current settings for each logical name table: $ @SYS$LIBRARY:SQL$SHOVER Current PROCESS SQL environment is version 6.0-0 (MULTIVERSION) Current PROCESS DISPATCH environment is version 6.0-0 (MULTIVERSION) o To show all the versions installed on the system. You can use this to determine what the highest version of Rdb/Dispatch or SQL is installed on the system. $ @SYS$LIBRARY:SQL$SHOVER VERSIONS "SQL$INSTALLED_VERSIONS" = "*6.0-0" (LNM$PROCESS_TABLE) "RDB$DISPATCH_INSTALLED_VERSIONS" = "V4.0-5" (LNM$PROCESS_TABLE) "*6.0-0" The * in the preceding output indicates a multiversion kit. The following examples show other possible parameters: ! To show only Rdb/Dispatch $ @SYS$LIBRARY:SQL$SHOVER VERSIONS DISPATCH ! To show only SQL $ @SYS$LIBRARY:SQL$SHOVER VERSIONS SQL ! To show only 6.0 Rdb/Dispatch $ @SYS$LIBRARY:SQL$SHOVER VERSIONS DISPATCH 6.0 ! To show only 6.0 SQL and suppress output $ @SYS$LIBRARY:SQL$SHOVER VERSIONS SQL 6.0 NOSHOW A-20 Prerequisite Installation of Common Components A.9 Deleting Versions of the Common Components For your convenience, the Common Components kit provides a command procedure, SYS$MANAGER:SQL$DEINSTALL_DELETE.COM, to delete current or previous versions of the Common Components. You must run this command procedure from an account that has SETPRV privileges, or from an account that has SYSPRV, CMKRNL, SYSNAM, and WORLD privileges. You can use this command file to delete previous versions of the Common Components when you have installed a newer version and determine that prior versions are no longer needed. ________________________Note ________________________ The SQL$DEINSTALL_DELETE.COM procedure will not execute if multiple products requiring Common Components are found on the system or DEC Rdb of the same version is found on the system. _____________________________________________________ When you run the command procedure, you may choose to pass a single parameter that indicates the output location for all messages generated while the command procedure processes. This parameter can either be the name of a file (for example, SQL$DEINSTALL_DELETE.LOG) or the logical name SYS$OUTPUT (which displays messages on your screen). To run the SQL$DEINSTALL_DELETE command procedure and have messages sent to a file named SQL$DEINSTALL_DELETE.LOG, enter: $ @SYS$MANAGER:SQL$DEINSTALL_DELETE.COM SQL$DEINSTALL_DELETE.LOG The command procedure checks for the existence of the different versions of the Common Components on your system, and then displays a menu listing each version found (standard first, and then the oldest to the most current multiversion): Prerequisite Installation of Common Components A-21 SQL versions currently installed on your system * Version 5.1 (Multiversion) 1 Version 6.0 (Multiversion) 0 Quit (* This version cannot be deinstalled by this procedure) Enter Choice to deinstall (0...1) : 0 If the command procedure displays an asterisk (*) next to a version entry on the menu, it means that version cannot be deleted by the SQL$DEINSTALL_DELETE.COM procedure because it is prior to Version 6.0. Enter the menu number for the version you want to delete. For example, to delete Version 6.0 multiversion, enter the following: Enter Choice to deinstall (0...1) : 1 The command procedure displays the following message: You are about to deinstall SQL 6.0 (Multiversion) If your system is a cluster member, this procedure creates the SYS$SCRATCH:SQL$CLUSTER_DEINSTALL60.COM procedure. Use this command procedure to remove the Common Components Version 6.0 (multiversion) from other nodes in the cluster. You must either run this command procedure on each node that has Common Components Version 6.0 (multiversion) installed, or use the SYSMAN utility to run it clusterwide. Next, the command procedure asks you to confirm that you want to continue with the deinstallation (whether or not your system is part of a cluster): Enter Y(ES) to continue to deinstall SQL 6.0 (Multiversion): YES The final prompt asks you whether or not you want to delete the RDB$REMOTE account for the version you specified (keep this account if, for example, you plan to use it as a template to build other accounts): Do you want to delete RDB$REMOTE60? [N]: YES A-22 Prerequisite Installation of Common Components When the command procedure completes the deletion of the appropriate files, it displays the following message: %SQL-I-END Deinstallation of SQL 6.0 (Multiversion) now complete Prerequisite Installation of Common Components A-23 B ________________________________________________________________ Sample Installation This appendix contains a sample VAX installation of DEC DB Integrator Gateway for DB2 Client. It also contains a sample of the VAX Installation Verification Procedure (IVP). The AXP installation of DEC DB Integrator Gateway for DB2 Client and the IVP would be very similar. The following logs may vary slightly from the log shown in Chapter 3. B.1 Sample Installation VAX/VMS Software Product Installation Procedure V5-5.2 It is 12-OCT-1994 at 16:53. Enter a question mark (?) at any time for help. %VMSINSTAL-W-ACTIVE, The following processes are still active: SQLSRV$SERVER * Do you want to continue anyway [NO]? y * Are you satisfied with the backup of your system disk [YES]? The following products will be processed: LDB2 3.1 Beginning installation of LDB2 3.1 at 16:54 %VMSINSTAL-I-RESTORE, Restoring product save set A ... Release notes included with this kit are always copied to SYS$HELP. Additional Release Notes Options: 1. Display release notes 2. Print release notes 3. Both 1 and 2 4. None of the above Sample Installation B-1 * Select option [2]: 4 * Do you want to continue the installation [NO]? y %VMSINSTAL-I-RELMOVED, Product's release notes have been moved to SYS$HELP. ************************************************************** Installation procedure for DEC DB Integrator Gateway Client for DB2 V3.1-00 for OpenVMS VAX ************************************************************** © Digital Equipment Corporation 1993,1994. All rights reserved. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c) (1) (ii) of DFARS 252.227-7013, or in FAR 52.227- 19, or in FAR 52.227-14 Alt. III, as applicable. This software is proprietary to and embodies the confidential technology of Digital Equipment Corporation. Possession, use, or copying of this software and media is authorized only pursuant to a valid written license from Digital or an authorized sublicensor. ************************************************************** * Would you like to print the LDB2 Installation guide [NO]? * Do you want to continue the installation [YES]? Product: DB-GATEWAY-DB2 Producer: DEC Version: 3.1 Release Date: 1-SEP-1994 * Does this product have an authorization key registered and loaded? y * Do you want to purge files replaced by this installation [YES]? ************************************************************** There are no more questions. The installation takes approximately 1 to 5 minutes depending on the processor type. Because the Installation Verification Procedure is interactive, it will not be run as part of the installation. You may run the IVP separately any time you wish. To execute it, type: B-2 Sample Installation $ @SYS$TEST:LDB2$IVP ************************************************************** ************************************************************** Beginning installation of DEC DB Integrator Gateway Client for DB2 V3.1- 00 ************************************************************** %VMSINSTAL-I-RESTORE, Restoring product save set B ... ************************************************************** LDB2$STARTUP.COM has been placed in SYS$STARTUP. The following line should be placed in your system startup file. $ @SYS$STARTUP:LDB2$STARTUP.COM ************************************************************** LDB2$SHUTDOWN.COM has been placed in SYS$MANAGER. The following line should be placed in your system shutdown file. $ @SYS$STARTUP:LDB2$SHUTDOWN.COM ************************************************************** ************************************************************** Finishing installation of DEC DB Integrator Gateway Client for DB2 V3.1- 00 ************************************************************** %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... Installation of LDB2 3.1 completed at 16:55 Adding history entry in VMI$ROOT:[SYSUPD]VMSINSTAL.HISTORY Creating installation data file: VMI$ROOT:[SYSUPD]LDB2031.VMI_ DATA VMSINSTAL procedure done at 16:55 Sample Installation B-3 B.2 Sample Installation Verification Procedure (IVP) $ @SYS$TEST:LDB2$IVP ***************************************************************** Installation Verification Procedure (IVP) for DEC DB Integrator Gateway for DB2 Client V3.1-00 for OpenVMS VAX Copyright Digital Equipment Corporation 1993,1994. All rights reserved. This IVP verifies that all the gateway images are in place and a simple query can be executed. ***************************************************************** Enter a SQL attach string terminated by a semi-colon. Example: /TYPE=DB2/USER=FRED/PASSWORD=CHRIS/NODE=NODE01/TIDCS=DBIV/ACCESS_NAME=MYACCESS /LOGON_MODE=MYMODE/DATABASE=MYDATABASE; attach string:/TYPE=DB2/USER=DBIUSER/PASSWORD=PASSWORD/NODE=SNAGWY /ACC=CICS/DATA=PERSONNL The current string is: /TYPE=DB2/USER=DBIUSER/PASSWORD=PASSWORD/NODE=SNAGWY/ACC=CICS/DATA=PERSONNL Are you satisfied with that? (Y/N):Y Current PROCESS SQL environment is version T6.1-05 (STANDARD) Current PROCESS Rdb/Dispatch environment is version T6.1-05 (STANDARD) User tables in database with filename SQL$DATABASE COLLEGES DEGREES DEPARTMENTS EMPLOYEES JOBS JOB_HISTORY SALARY_HISTORY WORK_STATUS B-4 Sample Installation C ________________________________________________________________ Files Installed on Your System DEC DB Integrator Gateway for DB2 Client installs the following files on your system: o SYS$HELP:DBIHELP.HLP o SYS$HELP:DBI_MSG.DOC o SYS$HELP:LDB2031.RELEASE_NOTES o SYS$HELP:LDB2031_RELEASE_NOTES.PS o SYS$HELP:LDB2031.INSTALL_GUIDE o SYS$HELP:LDB2031_INSTALL_GUIDE.PS o SYS$HELP:LDRVHELP.HLP o SYS$HELP:LDRV_MSG.DOC o SYS$LIBRARY:LDRV$DB2_SHR.EXE o SYS$LIBRARY:DBI$SHR.EXE o SYS$MANAGER:LDB2$SHUTDOWN.COM o SYS$MESSAGE:LDRV_MSG.EXE o SYS$MESSAGE:DBI_MSG.EXE o SYS$STARTUP:LDB2$STARTUP.COM o SYS$TEST:LDB2$IVP Files Installed on Your System C-1 D ________________________________________________________________ How to Order Additional Documentation Technical Support If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825) and press 2 for technical assistance. Electronic Orders If you wish to place an order through your account at the Electronic Store, dial 800-234-1998, using a modem set to 2400- or 9600-baud. You must be using a VT terminal or terminal emulator set at 8 bits, no parity. If you need assistance using the Electronic Store, call 800-DIGITAL (800-344-4825) and ask for an Electronic Store specialist. Telephone and Direct Mail Orders __________________________________________________________ From__________Call______________Write_____________________ U.S.A. DECdirect Digital Equipment Phone: 800- Corporation DIGITAL P.O. Box CS2008 (800-344-4825) Nashua, New Hampshire FAX: (603) 884- 03061 5597 Puerto Rico Phone: (809) Digital Equipment 781-0505 Caribbean, Inc. FAX: (809) 749- 3 Digital Plaza, 1st 8377 Street Suite 200 Metro Office Park San Juan, Puerto Rico 00920 How to Order Additional Documentation D-1 __________________________________________________________ From__________Call______________Write_____________________ Canada Phone: 800-267- Digital Equipment of 6215 Canada Ltd. FAX: (613) 592- 100 Herzberg Road 1946 Kanata, Ontario, Canada K2K 2A6 Attn: DECdirect Sales International -- Local Digital subsidiary or approved distributor Internal DTN: 264-3030 U.S. Software Supply Orders[1] (603) 884-3030 Business (SSB) (for Digital Equipment software Corporation and hardware 10 Cotton Road documentation) Nashua, New Hampshire 03063-1260 [1]Call_to_request_an_Internal_Software_Order_Form_(EN-___ 01740-07).________________________________________________ D-2 How to Order Additional Documentation ________________________________________________________________ Index A Character sets (cont'd) ___________________________ standardization of, 1-12 Accessing DB2 data, 1-3 CICS/ESA software, 1-8 batch mode, 1-4 CICS/MVS software, 1-8 interactively, 1-4 CICS security, 1-4 Access name, 1-27 CMKRNL privilege Access path required for installation planning, 1-9 , 2-5 ACF2 security, 1-4 Common Components ACF/VTAM software, 1-7 deleting version, A-21 ASCII Communications and network See DMCS support, 1-27 ASCII character sets, 1-2, IBM systems software, 1-17table 1-27 Authorize utility, A-5 Configuration, 1-4 AUTOGEN command procedure, Configuration management, 2-8 1-4 AUTOGEN utility, 2-8 Connecting AXP system, 1-5 to a DB2 system, 1-3 Coordinator B__________________________ job responsibilites, 1-9 Backing up system disk, COSIMSG image, A-17 2-10 D Batch mode access, 1-4 ___________________________ Data access, 1-2 C__________________________ Data access path, 1-6 Character sets, 1-11, Data definition rules, 1-3 1-17table Data retrieval, 1-2 ASCII, 1-1, 1-11, 1-17 Data storage formats, 1-3 DMCS, 1-1, 1-11, 1-17 DATATRIEVE, 1-1 EBCDIC, 1-1, 1-11, 1-12, 1-17 Index-1 DB2, 1-1, 1-8 Displaying release notes, DB2 data 3-4 accessing, 1-3 Distributed data, 1-4 batch mode, 1-4 DMCS character sets, 1-2, interactively, 1-4 1-17table DEC DB Integrator Gateway DNA, 1-5 for DB2 Client, 1-4 required software, 1-7 E__________________________ DEC DB Integrator Gateway EBCDIC character sets, for DB2 Server, 1-4 1-2, 1-17table required software, 1-8 Editing DECnet/OSI system files, 4-1 NET$MANAGE identifier, Environment A-5 software, 1-5 DEC SNA APPC/LU 6.2 Error recovery programming interface during installation, 3-10 for OpenVMS, 1-5 during IVP, 3-10 required software, 1-7 DEC SNA gateways, 1-7 F__________________________ Digital Network Failure message Architecture IVP, 3-11 See DNA Features of DB2 Gateway, Digital system software, 1-3 1-6 Files DEC DB Integrator Gateway created during for DB2 Client, 1-7 installation, C-1 DEC SNA APPC/LU 6.2 purging, 3-7 Programming Interface for OpenVMS, 1-7 G__________________________ DEC SNA gateways, 1-7 Gateway OpenVMS user interfaces, DEC SNA, 1-7 1-6 Gateway for DB2 coordinator optional, 2-1 , 1-9 Rdb/Dispatch, 1-6 job responsibilities, 1-9 required, 2-1 GBLPAGES system parameter user interface, 1-6 calculating, 2-8 Disk space GBLSECTIONS system checking, 2-6 parameter required for installation calculating, 2-8 , 2-6table Global pagelets required for Common Components for OpenVMS AXP Index-2 Global pagelets Installation Verification required for Common Procedure Components for OpenVMS See IVP AXP (cont'd) Interactive access, 1-4 table, A-13 Invoking VMSINSTAL command Global pages procedure, 3-1 calculating, 2-8 IVP, 3-9example, required for Common B-1example Components for OpenVMS completion message, 3-10 VAX error recovery, 3-10 table, A-13 failure message, 3-11 Global sections queries during calculating, 2-8 installation, 3-7 required for Common running, 3-9 Components for OpenVMS running separate from VAX installation, 4-1 table, A-13 L__________________________ I__________________________ LDB2$DMCS_TABLE.MAR macro IBM Database 2 source file, 1-11 See DB2 License Management Facility IBM Systems Network See LMF Architecture License PAK, 2-4 See SNA queries during IBM system software installation, 3-7 ACF/VTAM, 1-7 License Product CICS/ESA, 1-8 Authorization Key CICS/MVS, 1-8 See License PAK DB2, 1-8 License registration MVS/ESA, 1-8 See LMF MVS/XA, 1-8 LMF, 2-4 Images Logging out of privileged installing as shared, A-8 account, 3-9 Information messages Logical names during installation, 3-8 assigning to user-defined Installation guide translation tables, printing, 3-6 1-15 Installation log, B-1example Installation procedure, 3-1 Index-3 Privileges M__________________________ required for installation Media , 2-5 mounting, 3-4 CMKRNL, 2-5 Messages SYSPRV, 2-5 completion of IVP, 3-10 WORLD, 2-5 during installation, 3-8 required for OpenVMS, A-3 Mounting media, 3-4 required for user MVS/ESA software, 1-8 accounts, 4-2 MVS/XA software, 1-8 Problems reporting, 4-2 N__________________________ Process symbol tables, 3-9 Names Purging new product names, 1-2 files, 3-7 NET$MANAGE identifier R DECnet/OSI, A-5 ___________________________ Network and communications RACF security, 1-4 support, 1-27 RDB$REMOTE account, A-22 IBM systems software, RDB$SHARE image, A-17 1-27 Rdb/Dispatch, 1-6 Network startup command RdbAccess Client for DB2 line, 4-2 new product name, 1-2 RdbAccess Server for DB2 O new product name, 1-2 ___________________________ RDBMSGS image, A-17 OpenVMS Authorize utility, RDBSHR image, A-17 A-4 Reader's comment forms, OpenVMS privileges 4-2 required, A-3 Release notes output options, 3-4 P__________________________ Reporting PAK installation problems, See License PAK 4-2 Planning Required software, 1-5 checklist, 1-10 See also Digital system site coordination, 1-9 software Printing installation guide See also IBM system , 3-6 software Printing release notes, See also DEC DB 3-4 Integrator Gateway Privileged account for DB2 Server, 1-7 logging out, 3-9 Index-4 Required time for SQL interface to DEC Rdb, installation, 2-5 1-1 SYS$SYSTEM:MODPARAMS.DAT S__________________________ file, 2-8 Sample installation, B-1 SYS$UPDATE:VMSLICENSE.COM Security procedure, 2-5 ACF2, 1-4 SYSGEN utility, 2-7 CICS, 1-4 SYSPRV privilege RACF, 1-4 required for installation SETPRV privilege, A-3 , 2-5 Sharing data, 1-4 System backup Site coordination, 1-9 VMSINSTAL command checklist, 1-10 procedure, 3-3 SNA, 1-5 System disk Software backing up, 2-10 See Digital system System files software editing, 4-1 network startup command See IBM system software line, 4-2 Software compatibility System Generation utility, DEC DB Integrator Gateway 2-7 for DB2 Client, 1-4 System parameter values, DEC DB Integrator Gateway 2-6 for DB2 Server, 1-4 changing SYS$SYSTEM:MODPARAMS.DAT Software environment, 1-5 file, 2-8 Software Performance changing with AUTOGEN, Reports (SPRs), 4-2 2-8 SQL$CLUSTER_DEINSTALL60 checking, 2-7 command procedure, A-22 minimum required, 2-6t SQL$DEINSTALL_DELETE command procedure, A-21 T__________________________ SQL$ image, A-18 Time required for SQL$INT image, A-18 SQL$MOD image, A-18 installation, 2-5 SQL$MSG image, A-18 Tracing facility, 1-4 SQL$PRE image, A-18 Translation tables SQL$SHR image, A-18 customized, 1-11, 1-15 SQL$UTL_SHARE60 image, default, 1-11, 1-12, 1-14 A-18 for multiple attachments, SQL$UTL_SHAREnn image, 1-16 A-18 function, 1-11 SQL/Services, 1-1 options for using, 1-11 Index-5 components, 3-1 U__________________________ error recovery, 3-10 User account requirements, invoking, 3-1 4-2 IVP options, 3-7 privileges, 4-2 license PAK queries, 3-7 User-defined translation mounting the media, 3-4 tables, 1-15 printing installation User interface guide, 3-6 required software, 1-6 purging files, 3-7 reading informational V messages, 3-8 ___________________________ release note options, 3-4 VIDA2$DMCS_TABLE.MAR file, requirements, 2-9 1-15 system backup, 3-3 VIDA2$TRAPRE.MAR file, VTAM software, 1-7 1-15 VIDA Client for DB2 W__________________________ new product name, 1-2 WORLD privilege VIDA Server for DB2 required for installation new product name, 1-2 , 2-5 VMSINSTAL command procedure , 3-3example, A-3 Index-6