HP NonStop Open System Services ODBC/MX Client Driver

Transcription

1 HP NonStop Open System Services ODBC/MX Client Driver Abstract This manual describes how to install and configure the HP NonStop Open System Services (OSS) ODBC/MX Client Driver. This product enables applications developed for the OSS Open Database Connectivity (ODBC) application programming interface to use HP NonStop SQL/MX to access HP NonStop SQL databases on an HP NonStop system. Product Version HP NonStop OSS ODBC/MX 3.0 Supported Release Version Updates (RVUs) This manual supports J06.11 and all subsequent J-series RVUs and H06.22 and all subsequent H-series RVUs, until otherwise indicated by its replacement publications. Part Number Published February 2011

2 Document History Part Number Product Version Published HP NonStop OSS ODBC/MX 3.0 February 2011

3 Legal Notices Copyright 2011 Hewlett-Packard Development Company L.P. Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR and , Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein. Export of the information contained in this publication may require authorization from the U.S. Department of Commerce. Microsoft, Windows, and Windows NT are U.S. registered trademarks of Microsoft Corporation. Intel, Itanium, Pentium, and Celeron are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Java is a registered trademark of Oracle and/or its affiliates. Motif, OSF/1, UNIX, X/Open, and the "X" device are registered trademarks and IT DialTone and The Open Group are trademarks of The Open Group in the U.S. and other countries. Open Software Foundation, OSF, the OSF logo, OSF/1, OSF/Motif, and Motif are trademarks of the Open Software Foundation, Inc. OSF MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THE OSF MATERIAL PROVIDED HEREIN, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. OSF shall not be liable for errors contained herein or for incidental consequential damages in connection with the furnishing, performance, or use of this material. 1990, 1991, 1992, 1993 Open Software Foundation, Inc. This documentation and the software to which it relates are derived in part from materials supplied by the following: 1987, 1988, 1989 Carnegie-Mellon University. 1989, 1990, 1991 Digital Equipment Corporation. 1985, 1988, 1989, 1990 Encore Computer Corporation Free Software Foundation, Inc. 1987, 1988, 1989, 1990, 1991 Hewlett-Packard Company. 1985, 1987, 1988, 1989, 1990, 1991, 1992 International Business Machines Corporation. 1988, 1989 Massachusetts Institute of Technology. 1988, 1989, 1990 Mentat Inc Microsoft Corporation. 1987, 1988, 1989, 1990, 1991, 1992 SecureWare, Inc. 1990, 1991 Siemens Nixdorf Informationssysteme AG. 1986, 1989, 1996, 1997 Sun Microsystems, Inc. 1989, 1990, 1991 Transarc Corporation. This software and documentation are based in part on the Fourth Berkeley Software Distribution under license from The Regents of the University of California. OSF acknowledges the following individuals and institutions for their role in its development: Kenneth C.R.C. Arnold, Gregory S. Couch, Conrad C. Huang, Ed James, Symmetric Computer Systems, Robert Elz. 1980, 1981, 1982, 1983, 1985, 1986, 1987, 1988, 1989 Regents of the University of California. Printed in the US

4

5 HP NonStop Open System Services ODBC/MX Client Driver Glossary Index Examples Figures Tables Legal Notices What s New in This Manual v Manual Information v New and Changed Information v About This Manual vii Audience vii Related Documentation vii Notation Conventions xi HP Encourages Your Comments xii 1. ODBC/MX Client Overview Client Components 1-1 Data Sources 1-1 Default Data Source 1-1 Data Source Configuration 1-2 OSS ODBC/MX Client Driver Architecture 1-2 Connections 1-4 Connecting a Client to a Data Source 1-4 Connection Mapping 1-6 Object Naming and Mapping 1-6 ANSI Name Type 1-6 Release Considerations and Restrictions 1-7 Traces 1-9 Supported APIs 1-10 Unsupported ODBC API Functions and Data Types 1-10 API Functions 1-10 Data Types 1-11 Unsupported Functionalities 1-12 Restricted ODBC API Functions 1-12 OSS ODBC/MX Client Driver Features 1-12 Limitations of OSS ODBC/MX Client Driver 1-13 Hewlett-Packard Company i

6 Contents 2. Configuring Client Data Source Attributes for ODBC/MX Connectivity 2. Configuring Client Data Source Attributes for ODBC/MX Connectivity Accessing the ODBC/MX Data Source 2-1 Configuring Data Sources 2-2 ODBCDSN File Format 2-3 Example ODBCDSN file 2-7 Adding New Data Sources 2-8 Modifying Data Sources 2-8 Removing Data Sources 2-8 Tracing OSS ODBC/MX Client Driver 2-8 Configure Tracing on a Client Data Source 2-8 Enabling Tracing for OSS ODBC/MX Client Driver 2-9 Disabling Tracing for OSS ODBC/MX Client Driver 2-9 Components of the MX Connectivity Service 2-9 Migration Considerations ODBC/MX Conformance ODBC API Functions 3-2 SQL Conformance Level 3-7 SQL Scalar Functions 3-7 ODBC Data Types 3-10 Unsigned Data Types 3-11 Partial Date/Time Values 3-12 SQL/MP Data Types and ODBC/MX Equivalents 3-12 Microsoft Escape Clauses 3-13 Stored Procedures 3-14 Transactions and Cursor Behavior with Multiple Statements 3-14 Timestamp Values with Fraction ODBC/MX Messages ODBC/MX Driver Error Codes 4-1 ODBC/MX Client Messages 4-1 A. Sample ODBC Application Compilation and Linking of the Sample ODBC Application A-1 Execution and Testing of Sample ODBC Application A-1 HP NonStop Open System Services ODBC/MX Client Driver ii

7 Contents Glossary Glossary Index Examples Example A-1. Example for compiling a threaded program A-1 Example A-2. Example for linking a threaded program A-1 Example A-3. Sample ODBC Application Code A-3 Figures Tables Figure 1-1. OSS ODBC/MX Client Driver Architecture on NonStop 1-3 Figure 1-2. Connection Data Flow 1-5 Table 1-1. Release Considerations and Restrictions 1-7 Table 2-1. Format of the ODBCDSN file 2-3 Table 3-1. Connecting to a Data Source 3-2 Table 3-2. Obtaining Information About a Driver and Data Source 3-2 Table 3-3. Setting and Retrieving Driver Attributes 3-3 Table 3-4. Setting and Retrieving Descriptor Fields 3-3 Table 3-5. Preparing SQL Requests 3-3 Table 3-6. Submitting SQL Requests 3-4 Table 3-7. Retrieving Results and Information About Results 3-4 Table 3-8. Obtaining Information About a Data Source s System Tables 3-5 Table 3-9. Terminating a Statement 3-6 Table Terminating a Connection 3-7 Table Numeric Functions 3-7 Table String Functions 3-8 Table Time and Date Functions 3-9 Table System Functions 3-9 Table ODBC Data Types 3-10 Table Behavior of Unsigned Data Types 3-11 Table SQL/MP to ODBC/MX Date/Time Mappings 3-12 Table Microsoft Escape Clauses 3-13 Table Transactions and Cursor Behavior 3-14 Table Sample Values Inserted From a C/C++ Program and Their Corresponding Expected Values in Microsecond 3-14 Table Sample Values Inserted From a C/C++ Program and Their Corresponding Expected Values in Nanosecond 3-16 Table SYSTEM_DEFAULT Values Retrieved Using a C/C++ Program 3-17 HP NonStop Open System Services ODBC/MX Client Driver iii

8 Contents Tables (continued) Tables (continued) Table Sample Values Retrieved Using a C/C++ Program and Their Corresponding Expected Values in Nanosecond 3-18 HP NonStop Open System Services ODBC/MX Client Driver iv

9 What s New in This Manual Manual Information Abstract HP NonStop Open System Services ODBC/MX Client Driver This manual describes how to install and configure the HP NonStop Open System Services (OSS) ODBC/MX Client Driver. This product enables applications developed for the OSS Open Database Connectivity (ODBC) application programming interface to use HP NonStop SQL/MX to access HP NonStop SQL databases on an HP NonStop system. Product Version HP NonStop OSS ODBC/MX 3.0 Supported Release Version Updates (RVUs) This manual supports J06.11 and all subsequent J-series RVUs and H06.22 and all subsequent H-series RVUs, until otherwise indicated by its replacement publications. Part Number Published February 2011 Document History Part Number Product Version Published HP NonStop OSS ODBC/MX 3.0 February 2011 New and Changed Information Changes to the manual: Updated the description of Client Components on page 1-1. Updated the description of Data Source Configuration on page 1-2. Updated the description of SQLCancel Function on page 1-7. Added the following topics: OSS ODBC/MX Client Driver Features on page 1-12 Limitations of OSS ODBC/MX Client Driver on page 1-13 Updated the description of Configuring Data Sources on page 2-2. Updated the description of TraceFile on page 2-3. Updated the description of TraceFlags on page 2-4. HP NonStop Open System Services ODBC/MX Client Driver v

10 What s New in This Manual New and Changed Information Updated the syntax of the domain name on page 2-5. Added new data source description, SQLFractionValue on page 2-5. Updated the ODBC/MX version and the syntax of the domain name under Example ODBCDSN file on page 2-7. Updated the description of the TraceFlags parameter on page 2-8. Added a note about the NUMERIC data type on page Added Timestamp Values with Fraction on page HP NonStop Open System Services ODBC/MX Client Driver vi

11 About This Manual Audience ODBC application programmers who write 32-bit applications to access an NonStop SQL database. Other end users or application programmers who use ODBC/MX to access a NonStop SQL database. Related Documentation The SQL/MX library of manuals, which includes: Introductory Guides SQL/MX Comparison Guide for SQL/MP Users SQL/MX Quick Start Reference Manuals SQL/MX Reference Manual SQL/MX Connectivity Service Administrative Command Reference DataLoader/MX Reference Manual SQL/MX Messages Manual SQL/MX Glossary Programming Manuals SQL/MX Programming Manual for C and COBOL SQL/MX Programming Manual for Java Describes SQL differences between SQL/MP and SQL/MX. Describes basic techniques for using SQL in the SQL/MX conversational interface (MXCI). Includes information about installing the sample database. Describes the syntax of SQL/MX statements, MXCI commands, functions, and other SQL/MX language elements. Describes the SQL/MX administrative command library (MACL) available with the SQL/MX conversational interface (MXCI). Describes the features and functions of the DataLoader/MX product, a tool to load SQL/MX databases. Describes SQL/MX messages. Defines SQL/MX terminology. Describes how to embed SQL/MX statements in ANSI C and COBOL programs. Describes how to embed SQL/MX statements in Java programs according to the SQLJ standard. HP NonStop Open System Services ODBC/MX Client Driver vii

12 About This Manual Related Documentation Specialized Guides SQL/MX Installation and Management Guide SQL/MX Query Guide SQL/MX Data Mining Guide SQL/MX Queuing and Publish/Subscribe Services SQL/MX Report Writer Guide SQL/MX Connectivity Service Manual SQL/MX Guide to Stored Procedures in Java NSM/web Installation Guide Online Help The SQL/MX Online Help consists of: Reference Help Messages Help Glossary Help NSM/web Help Visual Query Planner Help Describes how to plan for, install, create, and manage an SQL/MX database. Explains how to use installation and management commands and utilities. Describes how to understand query execution plans and write optimal queries for an SQL/MX database. Describes the SQL/MX data structures and operations to carry out the knowledge-discovery process. Describes how SQL/MX integrates transactional queuing and publish/subscribe services into its database infrastructure. Describes how to produce formatted reports using data from a NonStop SQL/MX database. Describes how to install and manage the SQL/MX Connectivity Service (MXCS), which enables applications developed for the Microsoft Open Database Connectivity (ODBC) application programming interface (API) and other connectivity APIs to use SQL/MX. Describes how to use stored procedures that are written in Java within SQL/MX. Describes how to install NSM/web and troubleshoot NSM/web installations. Overview and reference entries from the SQL/MX Reference Manual. Individual messages grouped by source from the SQL/MX Messages Manual. Terms and definitions from the SQL/MX Glossary. Context-sensitive help topics that describe how to use the NSM/web management tool. Context-sensitive help topics that describe how to use the Visual Query Planner graphical user interface. The NSM/web and Visual Query Planner help systems are accessible from their respective applications. You can download the Reference, Messages, and Glossary online help from the $SYSTEM.ZMXHELP subvolume or by following the instructions HP NonStop Open System Services ODBC/MX Client Driver viii

13 About This Manual Related Documentation mentioned under the SQL/MX Online Help and Sample Programs document. This document can be accessed from the following documentation links available at the HP Business Support Center (BSC), HP Integrity NonStop H-Series HP Integrity NonStop J-Series For more information about downloading online help, see the SQL/MX Installation and Management Guide. These manuals are part of the SQL/MP library of manuals and are essential references for information about SQL/MP Data Definition Language (DDL) and SQL/MP installation and management: Related SQL/MP Manuals SQL/MP Reference Manual SQL/MP Installation and Management Guide Describes the SQL/MP language elements, expressions, predicates, functions, and statements. Describes how to plan, install, create, and manage an SQL/MP database. Describes installation and management commands and SQL/MP catalogs and files. HP NonStop Open System Services ODBC/MX Client Driver ix

14 About This Manual Related Documentation Introductory Guides Programming Manuals SQL/MX Comparison Guide for SQL/MP Users SQL/MX Quick Start SQL/MX Programming Manual for C and COBOL SQL/MX Programming Manual for Java SQL/MX Guide to Stored Procedures in Java Reference Manuals SQL/MX Reference Manual SQL/MX Messages Manual SQL/MX Glossary SQL/MX Connectivity Service Command Reference Data- Loader/MX Reference Manual Specialized Guides SQL/MX Online Help SQL/MX Installation and Management Guide SQL/MX Query Guide SQL/MX Data Mining Guide Reference Help Messages Help SQL/MX Queuing and Publish/ Subscribe Services SQL/MX Report Writer Guide SQL/MX Connectivity Service Manual Glossary Help NSM/web Help VST001.vsd The following documentation is helpful for understanding the concepts and terminology of this manual: Other Related Documentation EMS Manual SQL/MX Connectivity Service Manual HP NonStop Open System Services ODBC/MX Client Driver x

15 About This Manual Notation Conventions Notation Conventions Hypertext Links Blue underline is used to indicate a hypertext link within text. By clicking a passage of text with a blue underline, you are taken to the location described. For example: This requirement is described under Backup DAM Volumes and Physical Disk Drives on page 3-2. General Syntax Notation This list summarizes the notation conventions for syntax presentation in this manual. UPPERCASE LETTERS. Uppercase letters indicate keywords and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required. For example: MAXATTACH lowercase italic letters. Lowercase italic letters indicate variable items that you supply. Items not enclosed in brackets are required. For example: file-name computer type. Computer type letters within text indicate C and Open System Services (OSS) keywords and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required. For example: myfile.c italic computer type. Italic computer type letters within text indicate C and Open System Services (OSS) variable items that you supply. Items not enclosed in brackets are required. For example: pathname Punctuation. Parentheses, commas, semicolons, and other symbols not previously described must be typed as shown. For example: error := NEXTFILENAME ( file-name ) ; LISTOPENS SU $process-name.#su-name Notation for Messages This list summarizes the notation conventions for the presentation of displayed messages in this manual. HP NonStop Open System Services ODBC/MX Client Driver xi

16 About This Manual Change Bar Notation Nonitalic text. Nonitalic letters, numbers, and punctuation indicate text that is displayed or returned exactly as shown. For example: Backup Up. The CRE has many new message types and some new message type codes for old message types. In the CRE, the message type SYSTEM includes all messages except LOGICAL-CLOSE and LOGICAL-OPEN. Change Bar Notation Change bars are used to indicate substantive differences between this manual and its preceding version. Change bars are vertical rules placed in the right margin of changed portions of text, figures, tables, examples, and so on. Change bars highlight new or revised information. For example: The message types specified in the REPORT clause are different in the COBOL85 environment and the Common Run-Time Environment (CRE). The CRE has many new message types and some new message type codes for old message types. In the CRE, the message type SYSTEM includes all messages except LOGICAL-CLOSE and LOGICAL-OPEN. HP Encourages Your Comments HP encourages your comments concerning this document. We are committed to providing documentation that meets your needs. Send any errors found, suggestions for improvement, or compliments to Include the document title, part number, and any comment, error found, or suggestion for improvement concerning this document. HP NonStop Open System Services ODBC/MX Client Driver xii

17 1 ODBC/MX Client Overview This chapter includes these sections: Client Components Data Sources OSS ODBC/MX Client Driver Architecture Connections Object Naming and Mapping Release Considerations and Restrictions Traces Supported APIs Unsupported ODBC API Functions and Data Types OSS ODBC/MX Client Driver Features Limitations of OSS ODBC/MX Client Driver Applications developed for the OSS Open Database Connectivity (ODBC) application programming interface (API) access a NonStop SQL database on an HP NonStop server, through HP NonStop SQL/MX connectivity services (MXCS). Client Components Client components are installed in the OSS environment for J06.11 and all subsequent J-series RVUs and H06.22 and all subsequent H-series RUVs. ODBC client application: A user-written application or third-party product that uses the ODBC API to access data. OSS ODBC/MX Client Driver: Implements ODBC functions (a subset of the ODBC API), which allow an ODBC client application to access a NonStop SQL database through the MXCS service. Data Sources To configure ODBC client access to SQL/MX (which accesses NonStop SQL databases), MXCS requires data source to be defined and started on NonStop server. Default Data Source MXCS provides a preconfigured, default server data source on the server called TDM_Default_DataSource. You can stop and start the TDM_Default_DataSource using HP NonStop Open System Services ODBC/MX Client Driver

18 ODBC/MX Client Overview Data Source Configuration NSM/web or MXCI in MXCS mode (MACL), but you cannot delete it. The TDM_Default_DataSource has these functions: ODBC clients can connect to TDM_Default_DataSource and access a NonStop SQL database with no special configuration required. If an ODBC client tries to connect to a data source in the NonStop system, and the client data source name and the NonStop system data source name do not match (including the case), the Association Server connects the ODBC client to TDM_Default_DataSource. Note. If an ODBC client tries to connect to a server data source that is stopped, MXCS rejects the connection. Data Source Configuration In OSS ODBC/MX Client Driver, the ODBCDSN file is used to specify the configuration details of data sources. The ODBCDSN file is an edit file that is available at the $SYSTEM.SYSTEM location. You can also save the ODBCDSN in the OSS location where the executable program is to be run. If you save the ODBCDSN file in the OSS location, it will take precedence over the ODBCDSN available at the $SYSTEM.SYSTEM location. The default data source configuration file must be updated with the proper values before usage. For more information on data source configuration, see Configuring Data Sources on page 2-2. The OSS ODBC/MX Client Driver accesses the ODBCDSN file to configure the data source at the time of initial connection establishment (using the SQLConnect() function) between the OSS ODBC/MX Client Driver and the data source. The OSS ODBC/MX Driver Manager is a part of the OSS ODBC/MX Client Driver that accesses the ODBCDSN file. The OSS ODBC/MX Client Driver initially parses through the ODBCDSN file and fetches the required data source configuration details. If an application requested data source is not available, default data source information specified in the ODBCDSN file is fetched. The OSS ODBC/MX Client Driver contacts the Association Server to connect to the data source. OSS ODBC/MX Client Driver Architecture The NonStop OSS ODBC/MX Client Driver is functionally equivalent to the Windows ODBC/ MX Driver, with few unsupported features. The OSS ODBC/MX Client Driver is thread-safe. This feature is introduced in the SQL/MX release. The OSS ODBC/MX Client Driver can be used with multi-threaded C/C++ programs, which use the T1248 standard POSIX thread library. During the ODBC call execution, the OSS ODBC/MX Client Driver is thread-blocking and not process-blocking. HP NonStop Open System Services ODBC/MX Client Driver

19 ODBC/MX Client Overview OSS ODBC/MX Client Driver Architecture Figure 1-1 shows the architecture of OSS ODBC/MX Client Driver. Figure 1-1. OSS ODBC/MX Client Driver Architecture on NonStop NonStop ODBC/MX Server Components (NSK System) Configuration Server NonStop OSS ODBC/MX Client (NSK System) Association Server ODBC Configuration Data ODBC Application ODBC Client Driver Library TDM_Default_DataSource ODBC Server ODBC Server Data Source 1 ODBC Server ODBC Server The SQL ODBC Applications interact with the OSS ODBC/MX Client Driver to communicate to the SQL/MX database. The ODBC server establishes a connection between the OSS ODBC/MX Client Driver and the SQL/MX database. The ODBC server interacts with the SQL/MX database, forwards the client requests to the database engine, and sends the responses to the OSS ODBC/MX Client Driver. The ODBC/MX APIs are directly exposed to the ODBC applications. The OSS ODBC/MX Client Driver exposes a set of APIs, which calls multiple ODBC APIs internally. These APIs depict a thin layer of driver manager to the OSS ODBC/MX Client Driver. Minimal OSS ODBC/MX Driver Manager functionalities are included within the Driver code. When the ODBC client application runs the SQLConnect() function to request for a data source, a connection is established between the OSS ODBC/MX Client Driver and the Association Server (MXOAS). The Association Server checks the status and the configuration details of the requested data source in the ODBCDSN file. HP NonStop Open System Services ODBC/MX Client Driver

20 ODBC/MX Client Overview Connections Meanwhile, the OSS ODBC/MX Client Driver waits for the reply from the Association Server. The following scenarios describe what steps the Association Server perform depending on configuration and status of the data source. If the data source is configured and is in a running state, the Association Server replies to the OSS ODBC/MX Client Driver after authenticating the client driver credentials. The OSS ODBC/MX Client Driver then connects to the MXOSRVR after receiving a success reply from the Association Server. User authentication is performed in the MXOSRVR as required for the SQL Executor. After successful user authentication, the Association Server assigns one of the available servers to the user. If the data source is configured, but is not in a running state, the Association Server starts the MXOSRVR and replies to the OSS ODBC/MX Client Driver. If the specified data source is not even configured in the ODBCDSN file, the Association Server forwards the request to the default data source to connect to the OSS ODBC/MX Client Driver. The OSS ODBC/MX Client Driver resides on the NSK-OSS environment while the server components are spread across NSK-Guardian and NSK-OSS environments. The Association Server runs in the NSK-Guardian environment. The ODBC Server and the Configuration Server run in NSK-OSS environment. Connections Connecting a Client to a Data Source Figure 1-2 shows the flow of data among the ODBC/MX components. The OSS ODBC/MX Client Driver routes the ODBC application requests to the ODBC server. The communication between the OSS ODBC/MX Client Driver and the MXCS server is done over TCP/IP sockets as a client/server paradigm. The client/server implementation maintains an SQL Session context from the beginning of the connection to the discontinuation of the connection. The messages from a SQL Session context use the Socket paradigm as the client/server abstraction, which is implemented using TCP/IP as the interconnect protocol. The IP address and the port number on which the MXOAS server is running, is obtained from the ODBCDSN file. The following scenario describes how an ODBC client application connects to an MXCS server through the Association Server: 1. The ODBC client application sends a connection request to the MXCS service using the client data source name. The client data source name specifies an IP address and port number, or NonStop server DNS name that is defined when the Association Server is started. 2. The Association Server assigns a connection request to an available MXOSRVR in a process labeled as association. If the Association Server does not find the 1-4

21 ODBC/MX Client Overview Connecting a Client to a Data Source requested data source name, it assigns a server associated with the default data source. 3. The ODBC client application sends a connection request to the MXCS server, which is assigned by the Association Server. If the user information is not valid, the connection is rejected. 4. When the ODBC client application disconnects, the MXCS server notifies the Association Server that it is available for a new connection from other ODBC clients and returns to the data source server pool. An ODBC client application can connect to the default data source without creating an MXCS SQL server data source. Figure 1-2. Connection Data Flow ODBC Client Application ODBC API ODBC Driver Manager ODBC/MX Driver 1. Request connection to DS1 2. Connection to DS1 granted MXCS Association Server 3. Client connects to server 4. Server accepts connection MXCS SQL Server Other Data Source: DS1 MXCS SQL Server Tdm_Default_DataSource VST002.vsd v For more information on connecting to a data source, see the SQL/MX Connectivity Service Manual. 1-5

22 ODBC/MX Client Overview Connection Mapping Connection Mapping MXCS maps the client data source name in an incoming connection request to the server data source name (names are case sensitive). If the name matches but the server data source is not started, the connection request is rejected. If the server data source name does not exist, the Association Server routes the connection to the default data source. If the default data source is not started, the connection request is rejected. After a data source name is assigned, the Association Server uses any MXCS SQL server that is previously used by the same userid. If no such server is found, the Association Server assigns the first available server to the connection and reinitializes the user context to the one defined in the configuration for the data source name on the server. Object Naming and Mapping ODBC/MX can access SQL database objects as follows: with an alias, for SQL/MP objects that have an alias name (See ANSI Names for SQL/MP Objects). ANSI Name Type ODBC/MX supports only ANSI name types for NonStop SQL objects. Using the client interface at a client workstation, you can configure the default catalog and schema names used to qualify the table names in queries. The name format is as follows: catalog.schema.object-name ANSI names have a maximum of 128 characters for each part of the name (not including the dots). ANSI Names for SQL/MX Objects ANSI names for SQL/MX objects are registered in SQL/MX metadata residing in SQL/MX format tables. ANSI Names for SQL/MP Objects ANSI names (also called alias names) are logical names that map to physical Guardian names of existing SQL/MP objects. To add ANSI alias names for SQL/MP tables, use NSM/web or the MXCI command CREATE SQLMP ALIAS, which stores the alias name in the MP_PARTITIONS table in the SQL/MX catalog. The SQL/MX catalog and schema names must exist before you create the alias name. You can add alias names for NonStop SQL tables that are 1-6

23 ODBC/MX Client Overview Release Considerations and Restrictions registered in different NonStop SQL user catalogs, using the same SQL/MX catalog and schema names. Release Considerations and Restrictions Table 1-1. Release Considerations and Restrictions (page 1 of 2) ODBC/MX client software Catalog and schema SQL_QUERY_TIMEOUT Option SQLCancel Function An ODBC/MX client must be installed on a NonStop system. An ODBC client application can set the catalog and schema information in the ODBCDSN file. For more information on the ODBCDSN file, see ODBCDSN File Format on page 2-3. If an ODBC client does not set the catalog and schema for an ODBC client data source, the MXCS server defaults to NONSTOP_SYSTEM_NSK and PUBLIC_ACCESS_SCHEMA, respectively. Note: catalog and schema names follow SQL/MX rules, and are case sensitive catalog and schema names that are defined by default are not recognized by MXCS for client data sources because they are not defined in the ODBCDSN file. You must use the fully qualified object name. An ODBC application can call SQLSetStmtOption with the SQL_QUERY_TIMEOUT option to specify the number of seconds to wait for a query to execute. The SQL_QUERY_TIMEOUT option protects the MXCS server and ODBC client from long running queries. If a query exceeds the specified time before the data source returns the result set, the OSS ODBC/MX Client Driver returns HYT00 (Timeout expired) to the ODBC client. In an ODBC 2.0 application when the query is not running, ODBC/MX implements the SQLCancel function as an SQLFreeStmt with the SQL_CLOSE option. If the query is running, ODBC/MX tries to stop the server. If the attempt is successful, the client application receives an error and must reconnect. In an ODBC 3.0 application with a query (or queries) running, ODBC/MX behaves as it does for a 2.0 application. In an ODBC 3.0 application with no query running, ODBC/MX does not implement the SQLCancel function. The application is responsible for closing the cursor. 1-7

24 ODBC/MX Client Overview Release Considerations and Restrictions Table 1-1. Release Considerations and Restrictions (page 2 of 2) SQLPrimaryKeys Function SQLSpecialColumns Function SQLStatistics Function SQLTables Function When CatalogName is SQL_ALL_CATALOGS This function does not support pattern value arguments for table names, and returns keys information for a specified table name in the SQL/MX catalog. If the table name and keys information is not in the SQL/MX catalog, then it looks in the SQL/MP object (matching the criteria) registered in the MP_PARTITIONS table (through aliases) by looking up the catalog (where each table is registered), and returns the keys information for that SQL/MP table. This function does not support pattern value arguments for table names, and returns an optimal set of columns that uniquely identifies a row in the table information for a specified table name the SQL/MX catalog. If the table name and optimal set of columns information is not in the SQL/MX catalog, then it looks in SQL/MP object (matching the criteria) registered in the MP_PARTITIONS table (through aliases) by looking up the catalog (where each table is registered), and returns the optimal set of columns that uniquely identifies a row in the table information for a specified table name. This function does not support pattern value arguments for table names, and returns index information for a specified table name in the SQL/MX catalog. If the index and table information is not in the SQL/MX catalog, then it looks in the SQL/MP object (matching the criteria) registered in the MP_PARTITIONS table (through aliases) by looking up the catalog (where each table is registered), then returns the index information for that SQL/MP table. Returns all catalogs defined in the SQL/MX metadata. When SchemaName is SQL_ALL_SCHEMAS Returns all schemas defined in the SQL/MX metadata. When TableType is SQL_ALL_TABLE_TYPES SQL Table Names SQL Catalog and Schema Names Returns all object types supported by SQL/MX. The OSS ODBC/MX Client Driver uses SQL_ATTR_METADATA_ID to determine whether to upshift a table name. This applies for catalog API to SQLTables, SQLPrimaryKey, and SQLStatistics. This does not apply to SQLColumns. 1-8

25 ODBC/MX Client Overview Traces For information on migrating NonStop ODBC Server client applications to an ODBC/MX environment, see SQL/MX Comparison Guide for NonStop SQL/MP Users. Traces The OSS ODBC/MX Client Driver supports tracing facility. The trace information is captured in an OSS log file. Tracing can be enabled or disabled through the ODBCDSN file. For information on configuring client data source traces, see Tracing OSS ODBC/MX Client Driver on page

26 ODBC/MX Client Overview Supported APIs Supported APIs This release of OSS ODBC/MX Client Driver supports the following ODBC API functions. Diagnostic Environment Connection Descriptor Statement Attribute Results Catalog Unsupported ODBC API Functions and Data Types API Functions OSS ODBC/MX Client Driver 3.0 does not support the following ODBC API functions. For descriptions of the ODBC API functions, see ODBC API Functions on page 3-2. Installer Data Sources SQLManageDataSources SQLRemoveDefaultDataSource SQLConfigDataSource SQLCreateDataSource SQLValidDSN SQLRemoveDSNFromIni SQLWriteDSNToIni Installer Drivers SQLRemoveDriver SQLConfigDriver SQLInstallDriver SQLInstallDriverEx 1-10

27 ODBC/MX Client Overview Data Types SQLGetInstalledDrivers Installer Driver Manager SQLRemoveDriverManager SQLInstallDriverManager Installer File DSN SQLReadFileDSN SQLWriteFileDSN Installer Installer Errors SQLInstallerError SQLPostInstallerError Installer Profile Strings SQLWritePrivateProfileString SQLGetPrivateProfileString Installer Translator SQLInstallTranslator SQLInstallTranslatorEx SQLRemoveTranslator SQLGetTranslator Installer Config Mode SQLSetConfigMode SQLGetConfigMode SQLBulkOperations SQLFetchScroll - supported for SQL_FETCH_NEXT attribute only SQLSetScrollOption Data Types This release of MXCS does not support the following ODBC data types. For more information about data types, see ODBC Data Types on page BIT TINYINT and TINYINT UNSIGNED BINARY VARBINARY LONG VARBINARY 1-11

28 ODBC/MX Client Overview Unsupported Functionalities Unsupported Functionalities The OSS ODBC/MX Client Driver does not support the following functionalities: Windows-specific APIs that are used for driver installation and driver configuration. Dynamic DLL loading while loading OSS ODBC/MX Client Driver, other ODBC Drivers to external data sources (for example, Oracle or SQLServer). Wide character support. Windows-styled exception handling. Asynchronous semantics. All calls are implemented synchronously. This implies that SQLCancel can only be invoked on a statement handle after returning from the last invocation on the handle, not when an operation is running. For example, a runaway query cannot be stopped by the client application. Cursor library. Translate library. Applications that use windows-specific function class or methods. Restricted ODBC API Functions SQLBindParameter The SQLBindParameter function has these restrictions: SQL_DEFAULT_PARAM is not supported for the pcbvalue argument. The SQL_LEN_DATA_AT_EXEC(length) macro is not supported for the pcbvalue argument. SQLPutData The SQLPutData function can send data in parts only for the SQL_LONGVARCHAR data type. For all other data types, only the latest value in the rgbvalue argument is used. OSS ODBC/MX Client Driver Features The OSS ODBC/MX Client Driver 3.0 supports the following features: Row size limit is increased to align with maximum block size for MX tables. A clustering key length up to 2048 bytes is allowed for range and hash partitioned MX tables. The precision of the NUMERIC data type is extended up to 128 digits for signed and unsigned values. 1-12

29 ODBC/MX Client Overview Limitations of OSS ODBC/MX Client Driver Limitations of OSS ODBC/MX Client Driver The system running an R 3.0 version of NonStop OSS ODBC/MX Driver does not connect to a NonStop system running an R 2.x version of ODBC/MX server objects. When you try to connect an R 3.0 version of NonStop OSS ODBC/MX Driver to an R 2.x version of ODBC/MX server objects, the behavior is unpredictable. 1-13

30 ODBC/MX Client Overview Limitations of OSS ODBC/MX Client Driver 1-14

31 2 Configuring Client Data Source Attributes for ODBC/MX Connectivity This chapter includes these sections: Accessing the ODBC/MX Data Source Configuring Data Sources Adding New Data Sources Modifying Data Sources Removing Data Sources Tracing OSS ODBC/MX Client Driver Components of the MX Connectivity Service Migration Considerations Use the MXCS configuration to add, configure, and remove ODBC/MX data sources. Accessing the ODBC/MX Data Source To configure the ODBC/MX data source use the following commands: TACL > osh > mxci > mode mxcs The following example describes how the data source is accessed from the TACL prompt: TACL> osh /usr/tandem: /usr/tandem: mxci Hewlett-Packard NonStop(TM) SQL/MX Conversational Interface 2.3 (c) Copyright 2007 Hewlett-Packard Development Company, LP. >>mode mxcs; CS> For more information on configuration commands, refer the SQL/MX Connectivity Services Administrative commands reference manual on Business Support Center (BSC) at 2-1

32 Configuring Client Data Source Attributes for ODBC/MX Connectivity Configuring Data Sources Configuring Data Sources The ODBCDSN file contains all the data sources and their configuration details. The ODBCDSN file is an edit file and all the configuration details are maintained as a set of predefined attributes or parameters. The file can be located in the local directory of the application program, or alternatively one system definition can be located in the system default location $SYSTEM.SYSTEM.ODBCDSN (The OSS name is /G/system/system/odbcdsn). You must search the ODBCDSN file in the same location as that of the application. If you do not find the file, search for it in the $SYSTEM.SYSTEM location. 1. Edit the ODBCDSN file. The ODBCDSN file is installed in the $SYSTEM.SYSTEM subvolume. Change the ODBCDSN file so that the attributes are set to the correct values for your system (for example, names of data sources and attributes describing them). To use ODBC/MX data sources, the data source name in the ODBCDSN file must exactly match the data source name defined in the ODBC/MX service (data source names are case-sensitive). If the CATALOG and SCHEMA attributes are not defined in the ODBCDSN file, ODBC/MX uses the default values. For details on attributes and settings in the ODBCDSN file, see Table 2-1, Format of the ODBCDSN file, on page 2-3 and, Example ODBCDSN file on page Move the ODBCDSN file to the $SYSTEM.SYSTEM folder. The OSS ODBC/MX driver first searches for the ODBCDSN file in the same OSS directory as the executable file of the process. If the ODBCDSN file is not available, the driver searches for it in $SYSTEM.SYSTEM. You can also save the ODBCDSN in the OSS location where the executable program is to be run. If you save the ODBCDSN file in the OSS location, it will take precedence over the ODBCDSN available at the $SYSTEM.SYSTEM location. 2-2

33 Configuring Client Data Source Attributes for ODBC/MX Connectivity ODBCDSN File Format ODBCDSN File Format Table 2-1 describes the format of the ODBCDSN file. Table 2-1. Format of the ODBCDSN file (page 1 of 4) File Section [ODBC] Contents and Format Trace information Trace Attribute Description TraceStart Trace off = 0 Trace on =1 TraceFile If TraceStart keyword is omitted, TraceStart = 0 Name of the file that includes the tracing information and it resides in the OSS location where the program is executed. Trace file name is specified in the following format: TraceFile = file_name For example, if you specify the name of the trace file as Tracefile = trfetch, the system creates a file name as trfetch _ This file is located in the OSS location even if the ODBCDSN file is in the $SYSTEM.SYSTEM location. 2-3

34 Configuring Client Data Source Attributes for ODBC/MX Connectivity ODBCDSN File Format Table 2-1. Format of the ODBCDSN file (page 2 of 4) File Section [ODBC Data Sources] [data-source-name] TraceFlags Bitmask indicating trace level. For ODBC/MX 3.0: If TraceFlags keyword is omitted, TraceFlags = 0 TraceFlags can take the following values: ERROR Indicates some failed SQL calls and communication problems. WARNING Triggered by anything that generates a diagnostic record. CONFIG Provides details of configuration calls. INFO Provides details of what calls are made and other important markers. DEBUG (or number 6) Shows the detailed contents of many calls. List of data source name definitions Driver name One section per data source. Lists the attributes for each data source. Data Source Description Attribute DataLang Description FetchBufferSize Contents and Format Character set of SQL commands. Default = 0 Text string comment describing the data source. Size of buffer used to fetch rows Range: 0 to 256 Kb SYSTEM_DEFAULT = 8Kb Single row = 0 (use to get update on current operation or when exercising Publish/Subscribe) 2-4

35 Configuring Client Data Source Attributes for ODBC/MX Connectivity ODBCDSN File Format Table 2-1. Format of the ODBCDSN file (page 3 of 4) File Section [data-source-name] continued Data Source Description Server SQLFractionValue SQL_ATTR _CONNECTION _TIMEOUT SQL_LOGIN _TIMEOUT SQL_QUERY _TIMEOUT CATALOG Contents and Format Description IP address or domain name where ODBC/MX server is running, in the form: TCP:number1/number2 Where: number1 is IP address or domain name number2 is port number If SQLFractionValue = 9, the fraction value of SQL_C_TIMESTAMP variable is considered to be nanoseconds. If SQLFractionValue is not specified or if it is SQL_DEFAULT or another value apart from 9, the fraction part of SQL_C_TIMESTAMP variables is considered to be microseconds. Number of seconds the driver waits in an active connection with no exchange of data before closing the connection SYSTEM_DEFAULT = 60 NO_TIMEOUT (driver waits until a server becomes available or ODBC/MX is stopped) Number of seconds the driver will wait to establish a connection with the ODBC/MX Server SYSTEM_DEFAULT = 60 NO_TIMEOUT Number of seconds the driver waits before closing the cursor and returning control to the client. SYSTEM_DEFAULT = 60 NO_TIMEOUT (driver waits until query completes) Name of the catalog to be used. If not specified, the value is taken from those defined by the ODBC/MX service. 2-5

36 Configuring Client Data Source Attributes for ODBC/MX Connectivity ODBCDSN File Format Table 2-1. Format of the ODBCDSN file (page 4 of 4) File Section [DataSourceName] Contents and Format SCHEMA Name of the schema to be used. If not specified, the value is taken from those defined by the ODBC/MX service. List of drivers. Currently, only one driver can be used. The driver name for each data source defined by DataSourceName in [ODBC Data Sources] must match the driver name defined by Driver in [DataSourceName]. 2-6

37 Configuring Client Data Source Attributes for ODBC/MX Connectivity Example ODBCDSN file Example ODBCDSN file The following example shows an ODBCDSN file that defines connections to three client data sources, TDM_Default_DataSource, DS1, and DS2. In this example, the attributes Catalog and Schema for data source DS1 are defined as DS1CAT and DS1SCH. [ODBC] TraceFlags = 6 TraceStart = 0 TraceFile = trlog [ODBC Data Sources] TDM_Default_DataSource = NonStop ODBC/MX 3.0 DS1 = NonStop ODBC/MX 3.0 DS2 = NonStop ODBC/MX 3.0 DataSourceName = Driver [TDM_Default_DataSource] Description = Default Data Source Catalog = CAT Schema = SCH DataLang = 0 FetchBufferSize = SYSTEM_DEFAULT Server = TCP:xxx.xxx.xxx.xxx/xxxx SQL_ATTR_CONNECTION_TIMEOUT = SYSTEM_DEFAULT SQL_LOGIN_TIMEOUT = SYSTEM_DEFAULT SQL_QUERY_TIMEOUT = NO_TIMEOUT [DS1] Description = Sample Data Source 1 Catalog = DS1CAT Schema = DS1SCH Server = TCP:xxx.xxx.xxx.xxx/xxxx [DS2] Description = Sample Data Source 2 Catalog = DS2CAT Schema = DS2SCH Server = TCP: /61000 [DataSourceName] Driver = NonStop ODBC/MX 2-7

38 Configuring Client Data Source Attributes for ODBC/MX Connectivity Adding New Data Sources Adding New Data Sources To add a new data source entry in the ODBCDSN file, include the data source name and its description. If the values of the parameters are not specified in the ODBCDSN file, the OSS ODBC/MX Client Driver uses default values when creating a connection. Modifying Data Sources To modify a data source entry, complete the following steps: 1. Modify the ODBCDSN file. 2. Restart the application to reflect the modified changes. Note. It is mandatory to restart the application to view the modified changes in the ODBCDSN file. Removing Data Sources To remove a data source entry, complete the following steps: 1. Edit the ODBCDSN file to remove the data source and its values and save the file. 2. Restart the application to reflect the edited changes. Note. It is mandatory to restart the application to view the edited changes in the ODBCDSN file. Tracing OSS ODBC/MX Client Driver Configure Tracing on a Client Data Source Tracing of ODBC is enabled or disabled through the ODBCDSN file. This is determined at the time when all other parameters are fetched from the ODBCDSN file before establishing connection between the MXOSRVR and the OSS ODBC/MX Client Driver. Note. To turn tracing on or off, modify the ODBCDSN file accordingly and restart the application. If tracing is enabled, the global trace flag is set and all the traceable ODBC data is logged into the trace file henceforth. The tracing parameters of the ODBCDSN file are: [ODBC] parameter signifies the tracing support for ODBC. TraceStart parameter determines whether the tracing facility is enabled or disabled. TraceFlags parameter indicates the tracing level. It can take the following values: 2-8

39 Configuring Client Data Source Attributes for ODBC/MX Connectivity Enabling Tracing for OSS ODBC/MX Client Driver ERROR Indicates some failed SQL calls and communication problems. WARNING Triggered by anything that generates a diagnostic record. CONFIG Provides details of configuration calls. INFO Provides details of what calls are made and other important markers. DEBUG (or number 6) Shows the detailed contents of many calls. TraceFile parameter indicates the name of the trace file. The trace file is a normal OSS log file which is editable. Enabling Tracing for OSS ODBC/MX Client Driver To enable the tracing facility for the OSS ODBC/MX Client Driver, perform the following steps: 1. Stop the application. 2. Modify the TraceStart parameter in the ODBCDSN file to one (1). 3. Start the application. Disabling Tracing for OSS ODBC/MX Client Driver To disable the tracing facility for the OSS ODBC/MX Client Driver, perform the following steps: 1. Stop the application. 2. Modify the TraceStart parameter in the ODBCDSN file to zero (0). 3. Start the application. Components of the MX Connectivity Service To fully install all components of connectivity service, you must install the following: ODBC/MX Server Components OSS ODBC/MX Client Driver SQL/MX installed on a NonStop system Migration Considerations The OSS ODBC/MX Client Driver (ZODBCDLL) is a dynamic library for OSS applications to connect to the SQL/MX database. User applications using the eld linker dynamically links to the ZODBCDLL file. 2-9

40 Configuring Client Data Source Attributes for ODBC/MX Connectivity Migration Considerations 2-10

41 3 ODBC/MX Conformance This chapter contains tables that describe the ODBC/MX conformance to standard ODBC API functions and SQL conformance levels. Table ODBC API Functions: Page Connecting to a Data Source 3-2 Obtaining Information About a Driver and Data Source 3-2 Setting and Retrieving Driver Attributes 3-3 Setting and Retrieving Descriptor Fields 3-3 Preparing SQL Requests 3-3 Submitting SQL Requests 3-4 Retrieving Results and Information About Results 3-4 Obtaining Information About a Data Source s System Tables 3-5 Terminating a Statement 3-6 Terminating a Connection 3-7 SQL Scalar Functions: Numeric Functions 3-7 String Functions 3-8 Time and Date Functions 3-9 System Functions 3-9 CONVERT Function 3-10 SQL Conformance Level: ODBC Data Types 3-10 Unsigned Data Types 3-11 Partial Date/Time Values 3-12 SQL/MP Data Types and ODBC/MX Equivalents 3-12 Microsoft Escape Clauses 3-13 Stored Procedures 3-14 Timestamp Values with Fraction