Ingres®
Connectivity Guide r3
P00264-2E
This documentation and related computer software program (hereinafter referred to as the "Documentation") is for the end user's informational purposes only and is subject to change or withdrawal by Computer Associates International, Inc. ("CA") at any time. This documentation may not be copied, transferred, reproduced, disclosed or duplicated, in whole or in part, without the prior written consent of CA. This documentation is proprietary information of CA and protected by the copyright laws of the United States and international treaties. Notwithstanding the foregoing, licensed users may print a reasonable number of copies of this documentation for their own internal use, provided that all CA copyright notices and legends are affixed to each reproduced copy. Only authorized employees, consultants, or agents of the user who are bound by the confidentiality provisions of the license for the software are permitted to have access to such copies. This right to print copies is limited to the period during which the license for the product remains in full force and effect. Should the license terminate for any reason, it shall be the user's responsibility to return to CA the reproduced copies or to certify to CA that same have been destroyed. To the extent permitted by applicable law, CA provides this documentation "as is" without warranty of any kind, including without limitation, any implied warranties of merchantability, fitness for a particular purpose or noninfringement. In no event will CA be liable to the end user or any third party for any loss or damage, direct or indirect, from the use of this documentation, including without limitation, lost profits, business interruption, goodwill, or lost data, even if CA is expressly advised of such loss or damage. The use of any product referenced in this documentation and this documentation is governed by the end user's applicable license agreement. The manufacturer of this documentation is Computer Associates International, Inc. Provided with "Restricted Rights" as set forth in 48 C.F.R. Section 12.212, 48 C.F.R. Sections 52.227-19(c)(1) and (2) or DFARS Section 252.227-7013(c)(1)(ii) or applicable successor provisions. © 2005 Computer Associates International, Inc. All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.
Contents
Chapter 1: Introducing Ingres Connectivity 13 Basic Networking Concepts...... 14 Ingres Components and Tools...... 15 Ingres Instance...... 16 Advantage Enterprise Access and Advantage EDBC ...... 17 System-specific Text in This Guide ...... 17 Terminology Used in This Guide ...... 18 Syntax Conventions Used in This Guide ...... 18
Chapter 2: Exploring Net 19 Ingres Net...... 19 General Communication Facility ...... 20 Net Security ...... 21 Installation Configurations That Require Net ...... 22 Net and Other Ingres-related Products ...... 22 Net and Enterprise Access and EDBC Products ...... 23 Net and Distributed Option ...... 23 Net Product Integration Summary ...... 24 Benefits of Net...... 25 Net Concepts ...... 26 Virtual Node Names ...... 26 Connection Data ...... 26 Remote User Authorizations ...... 27 Global and Private Definitions ...... 28 Net Management Tools...... 29 Net and Bridge Users ...... 30 System Administrator ...... 31 Database Administrator ...... 31 End Users ...... 31
Chapter 3: Installing and Configuring Net 33 Installation Components...... 33 How You Prepare for Installation...... 33 Network Installation and Testing ...... 33 Setup Parameters for Net ...... 37
Contents iii
How Net Setup Works on an Existing Installation ...... 39 How Communications Are Enabled ...... 39 How You Install Net ...... 40 Create Password Validation Program (UNIX) ...... 41 Net Configuration Parameters—Customize the Installation ...... 42
Chapter 4: Establishing Communications 43 How User Access Is Established ...... 43 Requirements for Accessing Remote Instances ...... 44 Requirements for Accessing Distributed Databases ...... 45 Access Tools for Defining Vnodes ...... 46 Netutil (Net Management Utility) ...... 47 Netutil Startup Screen ...... 48 Virtual Node Name Table in Netutil ...... 48 Login and Password Data Table in Netutil...... 49 Connection Data Table in Netutil ...... 51 Other Attribute Data Table in Netutil ...... 53 Netutil Operations ...... 53 Prerequisites to Establish and Test a Remote Connection...... 54 Establish and Test a Remote Connection Using Netutil ...... 55 Delete an Entry ...... 60 Change an Entry ...... 62 Define an Installation Password for the Local Instance ...... 66 Netutil Non-Interactive Mode...... 67 Command Line Flags in Netutil Non-interactive Mode ...... 68 Create Function—Create a Remote User Authorization ...... 70 Destroy Function—Destroy a Remote User Authorization...... 71 Show Function—Display Remote User Authorizations...... 72 Create Function—Define an Installation Password for the Local Instance ...... 73 Create Function—Create a Connection Data Entry ...... 73 Destroy Function—Destroy a Connection Data Entry ...... 75 Show Function—Display Connection Data Entries ...... 76 Stop and Quiesce Commands—Stop or Quiesce One or More Communications Servers...... 77 Network Utility and Visual DBA ...... 78 Virtual Nodes Toolbar ...... 78 Types of Vnodes ...... 79 Advanced Vnode Parameters ...... 79 Installation Password Definitions for the Local Instance...... 82 Changing Installation Passwords ...... 82 Additional Vnode-Related Tasks ...... 82 Server-related Tasks...... 84
iv Connectivity Guide
Chapter 5: Using Net 85 Connecting to Remote Databases ...... 85 Database Access Syntax...... 85 Using the SQL Connect Statement with Net...... 87 Commands and Net...... 88 User Identity on Remote Instance...... 89 -u Command Flag—Impersonate User ...... 89 Verify Your Identity ...... 90
Chapter 6: Maintaining Connectivity 91 Start Communications Server ...... 91 Stop Communications Server ...... 92 Network Server Control Screen in Netutil ...... 92 Stop or Quiesce a Communications Server Using Netutil ...... 94 Inbound and Outbound Session Limits ...... 96 How You Set Inbound and Outbound Session Limits ...... 97 Logging Levels ...... 97 How You Change the Logging Level ...... 97 How You Direct Logging Output to a File ...... 98 Default Remote Nodes ...... 99 How You Set Default Remote Nodes ...... 99 Start DAS ...... 100 Stop DAS ...... 100
Chapter 7: Troubleshooting Connectivity 101 How Connection Between the Application and DBMS Server Is Established ...... 101 Where Ingres Net Information Is Stored...... 102 config.dat—Store Net Configuration Values ...... 103 Name Server Database—Store Remote Access Information ...... 104 Causes of Connectivity Problems ...... 106 How You Diagnose Connectivity Problems...... 106 General Net Installation Check ...... 107 Connection Errors...... 111 How You Resolve Net Registration Problems ...... 114 Security and Permission Errors ...... 114
Chapter 8: Exploring Bridge 117 Ingres Bridge ...... 117 How the Bridge Server Works ...... 117
Contents v
Tools for Configuring Bridge ...... 118 Installation Configurations That Require Bridge...... 118 How Bridge Is Installed ...... 120 How Bridge Is Started ...... 120 config.dat File—Store Bridge Configuration ...... 121 iigcb Command—Start the Bridge Server ...... 122 How the Client Is Set Up ...... 122 vnode Definition—Enable Client Access to Remote Servers Through Bridge ...... 123 Monitor the Bridge Server ...... 123 Stop the Bridge Server...... 124 How a Connection Is Established Through Bridge...... 124 Bridge Troubleshooting ...... 125 Sample Bridge Server Configuration ...... 126
Chapter 9: Configuring the Data Access Server 129 Data Access Server...... 129 How You Configure the DAS ...... 129 DAS Parameters—Configure DAS ...... 130 How You Enable DAS Tracing ...... 131 Tracing Levels ...... 131
Chapter 10: Introducing JDBC Connectivity 133 JDBC Components ...... 133 JDBC Driver ...... 133 JDBC Information Utility—Load the JDBC Driver ...... 134 Unsupported JDBC Features ...... 135 JDBC Driver Interface ...... 136 JDBC Driver and Data Source Classes ...... 136 JDBC Implementation Considerations ...... 143 JDBC User ID Options ...... 143 How Transactions Are Autocommitted...... 144 Cursors and Result Set Characteristics ...... 145 Cursors and Select Loops ...... 146 Database Procedures ...... 147 Named and Unnamed Parameters ...... 148 Additional Parameter Considerations ...... 148 Executing Procedures ...... 149 BLOB Column Handling...... 149 Date/Time Columns and Values ...... 150 National Character Set Columns...... 152
vi Connectivity Guide
Data Type Compatibility ...... 153 JDBC Tracing...... 155 Tracing Levels ...... 156
Chapter 11: Introducing ODBC Connectivity 157 ODBC Driver...... 157 ODBC Call-level Interface ...... 158 Supported ODBC Functions and Features ...... 159 Unsupported ODBC Features ...... 160 Read-Only Driver Option...... 160 ODBC Driver Requirements ...... 160 ODBC Driver Manager Programs...... 161 Protocols Supported by ODBC Driver...... 161 Support for Previously Released ODBC Drivers...... 162 Configure a Data Source (Windows) ...... 163 Data Source Tab, Ingres ODBC Administrator (Wiindows) ...... 166 Advanced Tab, Ingres ODBC Administrator (Windows) ...... 168 Configure a Data Source (UNIX and VMS) ...... 170 Data Source Configuration Form (UNIX and VMS) ...... 173 Advanced Data Source Configuration Options (UNIX and VMS) ...... 174 View Data Source Configuration Details...... 176 Driver Configuration Options ...... 177 Enable ODBC Tracing ...... 178 Select a Driver Path ...... 178 View Driver Configuration Details...... 180 Select a Data Source Configuration File Path ...... 180 Test a Data Source Connection ...... 182 Edit and Remove Data Sources ...... 182 Connection String Keywords...... 183 ODBC CLI Implementation Considerations ...... 185 Configuration on UNIX, Linux, and VMS...... 185 Optional Data Source Definitions ...... 186
Chapter 12: Introducing .NET Data Provider Connectivity 187 .NET Data Provider ...... 187 .NET Data Provider Architecture ...... 187 Data Provider Data Flow ...... 188 Data Provider Assembly ...... 188 Data Provider Namespace ...... 189 Data Retrieval Strategies ...... 189
Contents vii
Sample Program Constructed with .NET Data Provider...... 190 Connection Pooling ...... 191 Code Access Security...... 192 .NET Data Provider Classes...... 192 IngresConnection Class ...... 193 IngresCommand Class...... 200 IngresDataReader Class ...... 202 IngresDataAdapter Class ...... 208 IngresError Class ...... 212 IngresErrorCollection Class ...... 213 IngresException Class ...... 215 IngresInfoMessageEventArgs Class ...... 216 IngresInfoMessageEventHandler Class...... 217 IngresParameter Class ...... 218 IngresParameterCollection Class ...... 222 IngresRowUpdatedEventArgs Class ...... 224 IngresRowUpdatedEventHandler Class ...... 225 IngresRowUpdatingEventArgs Class ...... 226 IngresRowUpdatingEventHandler Class ...... 227 IngresTransaction Class ...... 227 Data Types Mapping ...... 229 DbType Mapping ...... 230 Coercion of Unicode Strings...... 231 IngresDataReader Object—Retrieve Data from the Database ...... 231 Build the IngresDataReader ...... 232 IngresDataReader Methods ...... 232 Example: Using the IngresDataReader ...... 233 ExecuteScalar Method—Obtain a Single Value from a Database ...... 234 GetBytes Method—Obtain BLOB Values from a Database...... 234 GetSchemaTable Method—Obtain Schema Information from a Database ...... 235 ExecuteNonQuery Method—Modify and Update Database ...... 235 IngresDataAdapter Object—Manage Data ...... 236 Integration with Visual Studio .NET ...... 237 Install the Data Provider into the Toolbox ...... 238 Start the Ingres Data Adapter Configuration Wizard ...... 239 How SQL Statements Are Generated...... 242 Design a Query Using the Query Builder ...... 242 Application Configuration File—Troubleshoot Applications ...... 245
Chapter 13: Configuring Ingres to Use Kerberos 247 Kerberos ...... 247
viii Connectivity Guide
Kerberos Configuration in the Enterprise...... 248 Kerberos Configuration Files—Configure Kerberos for Ingres ...... 250 The Ingres Service Principal—Authorize Client Connections ...... 251 How You Configure Ingres to Use Kerberos ...... 252 Ingres Configuration Options for Kerberos ...... 253 iisukerberos Command—Prepare Ingres for Kerberos Configuration...... 253 Base Configuration for Kerberos ...... 253 remote_mechanism Parameter—Configure Client in a Homogeneous Kerberos Environment ... 254 vnode Connection Attributes—Configure Client in a Heterogeneous Kerberos Environment .... 255 Encryption Parameters—Enable Kerberos Encryption ...... 256 Use Kerberos for Local Authentication ...... 257 How Name Server Delegation Works ...... 257
Appendix A: TCP/IP Protocol 259 TCP/IP Listen Address—Enable Communications ...... 259 Windows...... 259 UNIX ...... 260 VMS ...... 261 MVS ...... 262
Appendix B: SNA LU0 Protocol 265 SNA LU0 Listen Address—Enable Communications ...... 265 MVS ...... 265
Appendix C: SNA LU62 Protocol 267 SNA LU62 Listen Address—Enable Communications ...... 267 MVS ...... 267 Solaris ...... 268 HP-UX ...... 269 RS/6000...... 271
Appendix D: DECnet Protocol 273 DECnet Listen Address—Enable Communications ...... 273 VMS ...... 273
Appendix E: SPX/IPX Protocol 275 SPX/IPX Listen Address—Enable Communications...... 275 Windows...... 275
Contents ix
UNIX and VMS ...... 276
Appendix F: LAN Manager Protocol 279 LAN Manager Listen Address—Enable Communications...... 279
Appendix G: SunLink Gateway Configuration Files 281 SunLink Gateway Configuration File ...... 281 Solaris Independent LUs ...... 282 Solaris Dependent LUs ...... 284 SunOS (or Sun-4) Independent LUs...... 286 SunOS (or Sun-4) Dependent LUs ...... 288
Appendix H: AIX SNA Services/6000 Configuration Profiles 291 Sample Configuration Profiles ...... 291 CONNECTION Profile for Independent LUs ...... 292 CONNECTION Profile for Dependent LUs ...... 292 LOCALLU Profile for Independent LU ...... 293 LOCALLU Profile for Dependent LU ...... 294 MODE Profile for Independent LUs...... 295 MODE Profile for Dependent LUs ...... 295
Appendix I: HP-UX SNAplus Configuration 297 Sample Configuration File Excerpts...... 297 Independent LUs ...... 298 Dependent LUs ...... 299 Dynamically Loadable TP...... 300
Appendix J: Netu Procedures 301 Start Netu ...... 301 Netu User Interface ...... 302 Stop the Communications Server ...... 302 Modify Node Entry ...... 303 Modify Remote Authorization Entry ...... 303 Exit Netu...... 304 Remote Node Definition Operations ...... 304 Add or Merge Remote Node Definitions ...... 305 Delete Remote Node Definitions...... 307 How You Change Remote Node Definitions ...... 308
x Connectivity Guide
Retrieve Remote Node Definition Information ...... 310 Remote User Authorization Operations ...... 312 Define Remote User Authorizations...... 313 Delete Remote User Authorizations ...... 314 Change Remote User Authorizations...... 315 Retrieve Remote User Authorizations ...... 318 Netu Options for Stopping the Communications Server ...... 319 Obtain GCF Address ...... 320 Stop Communications Server...... 321
Index 323
Contents xi
Chapter 1: Introducing Ingres Connectivity
The Connectivity Guide describes how to establish and maintain communications between Ingres® installations. It includes the following information: