HP Neoview ODBC Drivers Manual

Transcription

1 HP Neoview ODBC Drivers Manual HP Part Number: Published: March 2007 Edition: HP Neoview Release 2.0

2 Copyright 2007 Hewlett-Packard Development Company, L.P. Legal Notice 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, Pentium, and Celeron are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Java is a U.S. trademark of Sun Microsystems, Inc. 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. The OSF documentation and the OSF 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.OSF 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.

3 Table of Contents About This Document...9 Supported Release Version Updates (RVUs)...9 Intended Audience...9 New and Changed Information in This Edition...9 Document Organization...9 Notation Conventions...9 General Syntax Notation...9 Related Information...12 Publishing History...13 HP Encourages Your Comments HP ODBC Driver Overview for Windows...15 Driver Components...15 Data Sources...15 Default Data Source...16 Client Data Sources...16 Connections...16 Connecting a Client to a Data Source...16 Connection Pooling...16 Object Naming and Mapping...18 ANSI Name Type...18 Password Expiration...18 Release Considerations and Restrictions...18 Traces...19 INFOSTATS Command...19 Example of INFOSTATS...20 Unsupported ODBC API Functions and Data Types...21 API Functions...21 Data Types...21 Restricted ODBC API Functions...21 SQLBindParameter...21 SQLPutData HP ODBC Drivers Overview for Linux and HP-UX...23 Driver Components...23 Data Sources...23 Default Data Source...24 Client Data Sources...24 Connections...24 Connecting a Client to a Data Source...24 Object Naming and Mapping...24 ANSI Name Type...24 Password Expiration...24 Release Considerations and Restrictions...25 Traces...25 Using the Driver With a Third Party Driver Manager...25 INFOSTATS Command...26 Example of INFOSTATS...26 Unsupported ODBC API Functions and Data Types...27 Table of Contents 3

4 API Functions...27 Data Types...27 Restricted ODBC API Functions...27 SQLBindParameter...27 SQLPutData Installing the HP ODBC Drivers...29 Installing ODBC Client Software...29 Installing the HP ODBC Driver for Windows...29 Installation Requirements...30 Download and Run the Client Installation File...30 Start the InstallShield Wizard...30 Add a Client Data Source...31 Delete the Installation Folder...31 Reinstalling the HP ODBC Driver for Windows...31 Download and Run the ODBC Client Installation File...31 Start the InstallShield Wizard and Reinstall the Driver...31 Uninstalling the HP ODBC Driver for Windows...31 Setting Up the Client Environment...32 Troubleshooting...32 Begin Client Installation Again...32 Select Repair Option...32 Client Interface Files...33 Getting the Version of the Driver...34 ODBC API Reference...34 Installing or Reinstalling HP ODBC Drivers for Linux and HP-UX...34 Installation Package...34 Installing or Reinstalling the HP ODBC Drivers...35 Setting Up the Client Environment...36 Running the Sample Program...36 Troubleshooting...37 Debugging...38 Getting the Version of the Driver...39 ODBC API Reference Configuring Client Data Sources...41 Adding New Client Data Sources...41 Reconfiguring ODBC Client Data Sources...41 Configuring ODBC Client Data Sources for Update Operations...42 Removing ODBC Client Data Sources...42 Tracing Client Data Sources...42 Configure tracing on a client data source...42 Start tracing on a client data source...42 Stop tracing on a client data source...43 Enabling Connection Pooling...43 Configuring the Client Data Source on Linux and HP-UX...44 Setting Trace On...44 Setting Trace Level...45 Adding a New Data Source...45 Maximum Log File Size HP ODBC Drivers Conformance...47 ODBC API Functions Table of Contents

5 SQL Conformance Level...52 SQL Scalar Functions...52 CONVERT Function...55 ODBC Data Types...55 Unsigned Data Types...56 Partial Date/Time Values...56 Microsoft Escape Clauses...56 Stored Procedures...57 Transactions and Cursor Behavior with Multiple Statements HP ODBC Drivers Messages...59 HP ODBC Drivers Error Codes...59 HP ODBC Client Messages...59 Index...63 Table of Contents 5

6 6

7 List of Tables 1-1 Release Considerations and Restrictions for Windows Driver Release Considerations and Restrictions for Linux and HP-UX Drivers Connecting to a Data Source Obtaining Information About a Driver and Data Source Setting and Retrieving Driver Attributes Setting and Retrieving Descriptor Fields Preparing SQL Requests Submitting SQL Requests Retrieving Results and Information About Results Obtaining Information About a Data Source s System Tables Terminating a Statement Terminating a Connection Numeric Functions String Functions Time and Date Functions System Functions ODBC Data Types Behavior of Unsigned Data Types Microsoft Escape Clauses

8 8

9 About This Document This manual describes how to install and configure HP ODBC drivers for Microsoft Windows, HP-UX, and Linux. The drivers enable applications developed for the Microsoft Open Database Connectivity (ODBC) application programming interface (API) to access the HP Neoview database. Supported Release Version Updates (RVUs) This manual supports Release 2.0 until otherwise indicated by a replacement publication. Intended Audience This document is intended for anyone who installs, configures, manages, or troubleshoots HP ODBC software and connectivity, for ODBC application programmers who write 32 bit applications to access an HP Neoview database, and other end users or application programmers who use HP ODBC drivers to access a Neoview database. New and Changed Information in This Edition The following information is new or changed in this edition of this manual: Added the INFOSTATS command in Chapter 1: HP ODBC Driver Overview for Windows and Chapter 2: HP ODBC Drivers Overview for Linux and HP-UX. Added information on traceflags in Chapter 4: Configuring Client Data Sources. Added information on password expiration in Chapter 1: HP ODBC Driver Overview for Windows and Chapter 2: HP ODBC Drivers Overview for Linux and HP-UX. Added information on third party driver manager in Chapter 2: HP ODBC Drivers Overview for Linux and HP-UX. Document Organization This document is organized as follows: Chapter 1: HP ODBC Driver Overview for Windows Chapter 2: HP ODBC Drivers Overview for Linux and HP-UX Chapter 3: Installing the HP ODBC Drivers Chapter 4: Configuring Client Data Sources Chapter 5: HP ODBC Drivers Conformance Chapter 6: HP ODBC Drivers Messages Notation Conventions General Syntax Notation Provides an overview of the HP ODBC driver on Windows. Provides an overview of the HP ODBC drivers on Linux and HP-UX. Explains how to install HP ODBC drivers on Windows, Linux, and HP-UX. Describes how to configure data sources on Windows, Linux, and HP-UX. Contains tables that describe HP ODBC drivers conformance to standard ODBC API functions and SQL conformance levels. Describes HP ODBC drivers error codes. This list summarizes the notation conventions for syntax presentation in this manual. Supported Release Version Updates (RVUs) 9

10 UPPERCASE LETTERS Italic Letters Computer Type Uppercase letters indicate keywords and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required. For example: SELECT Italic letters, regardless of font, indicate variable items that you supply. Items not enclosed in brackets are required. For example: file-name Computer type letters within text indicate case-sensitive keywords and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required. For example: myfile.sh Bold Text Bold text in an example indicates user input typed at the terminal. For example: ENTER RUN CODE?123 CODE RECEIVED: The user must press the Return key after typing the input. [ ] Brackets Brackets enclose optional syntax items. For example: DATETIME [start-field TO] end-field A group of items enclosed in brackets is a list from which you can choose one item or none. The items in the list can be arranged either vertically, with aligned brackets on each side of the list, or horizontally, enclosed in a pair of brackets and separated by vertical lines. For example: DROP SCHEMA schema [CASCADE] [RESTRICT] DROP SCHEMA schema [ CASCADE RESTRICT ] { } Braces Braces enclose required syntax items. For example: FROM { grantee[, grantee]...} A group of items enclosed in braces is a list from which you are required to choose one item. The items in the list can be arranged either vertically, with aligned braces on each side of the list, or horizontally, enclosed in a pair of braces and separated by vertical lines. For example: INTERVAL { start-field TO end-field } { single-field } 10 About This Document

11 INTERVAL { start-field TO end-field single-field } Vertical Line A vertical line separates alternatives in a horizontal list that is enclosed in brackets or braces. For example: {expression NULL} Ellipsis An ellipsis immediately following a pair of brackets or braces indicates that you can repeat the enclosed sequence of syntax items any number of times. For example: ATTRIBUTE[S] attribute [, attribute]... {, sql-expression}... An ellipsis immediately following a single syntax item indicates that you can repeat that syntax item any number of times. For example: expression-n Punctuation Parentheses, commas, semicolons, and other symbols not previously described must be typed as shown. For example: DAY Quotation marks around a symbol such as a bracket or brace indicate the symbol is a required character that you must type as shown. For example: "{" module-name [, module-name]... "}" Item Spacing Spaces shown between items are required unless one of the items is a punctuation symbol such as a parenthesis or a comma. For example: DAY (datetime-expression) DAY(datetime-expression) If there is no space between two items, spaces are not permitted. In this example, no spaces are permitted between the period and any other items: myfile.sh Notation Conventions 11

12 Line Spacing If the syntax of a command is too long to fit on a single line, each continuation line is indented three spaces and is separated from the preceding line by a blank line. This spacing distinguishes items in a continuation line from items in a vertical list of selections. For example: match-value [NOT] LIKE pattern [ESCAPE esc-char-expression] Related Information This manual is part of the Neoview customer library: Administration Neoview Database Administrator s Guide Neoview DB Admin Online Help Neoview Management Dashboard Client Guide for Database Administrators Neoview Owner s Manual Neoview Script Guide Neoview Script Online Help Information about how to load and manage the Neoview database by using the Neoview DB Admin and other tools. Context-sensitive help topics that describe how to use the HP Neoview DB Admin management interface. Information on using the Dashboard Client, including how to install the Client, start and configure the Client Server Gateway (CSG), use the Client windows and property sheets, interpret entity screen information, and use Command and Control to manage queries from the Client. Site-planning information and basic hardware information. Information about using the HP Neoview Script command-line interface to run SQL statements interactively or from script files. Command-line help that describes the interface commands supported in the current operating mode of Neoview Script. Reference Neoview SQL Reference Manual Neoview Messages Manual README for Neoview Platform for Release 2.0 Reference information about the syntax of SQL statements, functions, and other SQL language elements supported by the Neoview database software. Cause, effect, and recovery information for error messages. Information about known problems that are visible to customers. Connectivity Neoview JDBC Type 4 Driver API Reference Neoview JDBC Type 4 Driver Programmer s Reference Neoview ODBC Drivers Manual Reference information about the HP Neoview JDBC Type 4 Driver API. Information about using the HP Neoview JDBC Type 4 driver, which provides Java applications on client workstations access a Neoview database. Information about using HP Neoview ODBC drivers on a client workstation to access a Neoview database. 12 About This Document

13 ODBC Client Administrator Online Help README files Context-sensitive help topics that describe how to use the ODBC client interface. README for HP JDBC Type 4 Driver README for HP ODBC Driver for Windows README for HP ODBC Driver for Linux and HP-UX README for HP Neoview Script Other documentation can be found on the HP Web Site: The HP Neoview DB Admin help system is accessible from its respective application. Publishing History Part Number Product Version Neoview Release 2.0 Neoview Release 1.2 Neoview Release 1.1 Publication Date March 2007 November 2006 August 2006 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: pubs.comments@hp.com Include the document title, part number, and any comment, error found, or suggestion for improvement you have concerning this document. Publishing History 13

14 14

15 1 HP ODBC Driver Overview for Windows Open Database Connectivity (ODBC) is a widely accepted application programming interface (API) for database access. It is based on the Call-Level Interface (CLI) specifications from X/Open and ISO/IEC for database APIs and uses Structured Query Language (SQL) as its database access language. ODBC is designed for maximum interoperability that is, the ability of a single application to access different database management systems (DBMSs) with the same source code. Database applications call functions in the ODBC interface, which are implemented in database-specific modules called drivers. The use of drivers isolates applications from database-specific calls in the same way that printer drivers isolate word processing programs from printer-specific commands. Because drivers are loaded at run time, you only have to add a new driver to access a new DBMS; it is not necessary to recompile or relink the application. The HP ODBC drivers are 32-bit drivers. Applications that are not 32-bit must be compiled as 32-bit. This section describes: Driver Components Data Sources Connections Object Naming and Mapping Release Considerations and Restrictions Traces INFOSTATS Command Unsupported ODBC API Functions and Data Types Driver Components Driver components can be installed on any workstation running Windows 2000, Windows 2000 Server, Windows 2003 Server, Windows XP. These are the driver components: ODBC test application Microsoft ODBC 3.51 (or later) driver manager HP ODBC driver Microsoft ODBC Administrator An ODBC-enabled application that you can use to test ODBC drivers. Manages access to ODBC drivers for applications. The driver manager loads and unloads drivers and passes calls for ODBC functions to the correct driver. Implements ODBC function calls (a subset of the ODBC 3.51 API), to enable an ODBC client application to access the Neoview database. Manages database drivers and data sources. Data Sources To configure ODBC client access to the Neoview database, the HP Neoview Database Connectivity Service (NDCS) requires data source definitions on both the Neoview database and client workstation. Driver Components 15

16 Default Data Source NDCS 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 Neoview DB Admin, but you cannot delete it. The TDM_Default_DataSource has these functions: ODBC clients can connect to TDM_Default_DataSource. If an ODBC client tries to connect to a server data source that does not exist, it will default to TDM_Default_DataSource. Contact your Administrator to create server data sources. Client Data Sources Client data sources reside on a client workstation. Each client data source is a logical name that identifies the attribute values used to connect to NDCS and defines some local behavior for the connection. Use the Microsoft ODBC Administrator to add, configure, and remove the HP ODBC driver data sources. NOTE: If an ODBC client tries to connect to a server data source that is stopped, NDCS rejects the connection. Connections Connecting a Client to a Data Source The following scenario describes how an ODBC client application connects to NDCS: 1. The application connects using the client data source name. The client source data specifies an IP address or host name and port number. 2. If the user information is not valid, the connection is rejected. Connection Pooling Connection pooling enables an application to use a connection from a pool of connections that do not need to be reestablished for each use. Once a connection has been created and placed in a pool, an application can reuse that connection without performing the complete connection process. Using a pooled connection can result in significant performance gains, because applications can save the overhead involved in making a connection. This can be particularly significant for middle-tier applications that connect over a network, or for applications that repeatedly connect and disconnect, such as Internet applications. In addition to performance gains, the connection pooling architecture enables an environment and its associated connections to be used by multiple components in a single process. This means that stand-alone components in the same process can interact with each other without being aware of each other. A connection in a connection pool can be used repeatedly by multiple components. NOTE: Connection pooling can be used by an ODBC application exhibiting ODBC 2.x behavior, as long as the application can call SQLSetEnvAttr. When using connection pooling, the application must not execute SQL statements that change the database or the context of the database, such as changing the database name, which changes the catalog used by a data source. The connection pool is maintained by the Driver Manager. Connections are drawn from the pool when the application calls SQLConnect or SQLDriverConnect, and are returned to the pool when the application calls SQLDisconnect. The size of the pool grows dynamically based upon the requested resource allocations. It shrinks based on the inactivity timeout: If a connection is 16 HP ODBC Driver Overview for Windows

17 inactive for a period of time (it has not been used in a connection), it is removed from the pool. The size of the pool is limited only by memory constraints and limits on the server. The Driver Manager determines whether a specific connection in a pool should be used according to the arguments passed in SQLConnect or SQLDriverConnect, and the connection attributes set after the connection was allocated. When the Driver Manager is pooling connections, it needs to be able to determine if a connection is still working before handing the connection out. Otherwise, the Driver Manager keeps on handing out the dead connection to the application whenever a transient network failure occurs. In ODBC 3.5 a new connection attribute, SQL_ATTR_CONNECTION_DEAD, has been defined. This is a read-only connection attribute that returns either SQL_CD_TRUE or SQL_CD_FALSE. The value SQL_CD_TRUE means that the connection has been lost, while the value SQL_CD_FALSE means that the connection is still alive. A driver must implement this option efficiently, or it will impair the connection pooling performance. Specifically, a call to get this connection attribute should not cause a round trip to the server. Instead, a driver should just return the last known state of the connection. The connection is dead if the last trip to the server failed, and not dead if the last trip succeeded. To use a connection pool, an application performs the following steps: 1. Enables connection pooling by calling SQLSetEnvAttr to set the SQL_ATTR_CONNECTION_POOLING environment attribute to SQL_CP_ONE_PER_DRIVER or SQL_CP_ONE_PER_HENV. This call must be made before the application allocates the shared environment for which connection pooling is to be enabled. The environment handle in the call to SQLSetEnvAttr should be set to null, which makes SQL_ATTR_CONNECTION_POOLING a process-level attribute. If the attribute is set to SQL_CP_ONE_PER_DRIVER, a single connection pool is supported for each driver. If an application works with many drivers and few environments, this may be more efficient because fewer comparisons may be required. If set to SQL_CP_ONE_PER_HENV, a single connection pool is supported for each environment. If an application works with many environments and few drivers, this may be more efficient because fewer comparisons may be required. Connection pooling is disabled by setting SQL_ATTR_CONNECTION_POOLING to SQL_CP_OFF. 2. Allocates an environment by calling SQLAllocHandle with the HandleType argument set to SQL_HANDLE_ENV. The environment allocated by this call will be an implicit shared environment because connection pooling has been enabled. The environment to be used is not determined, however, until SQLAllocHandle with a HandleType of SQL_HANDLE_DBC is called on this environment. 3. Allocates a connection by calling SQLAllocHandle with InputHandle set to SQL_HANDLE_DBC, and the InputHandle set to the environment handle allocated for connection pooling. The Driver Manager attempts to find an existing environment that matches the environment attributes set by the application. If no such environment exists, one is created, with a reference count (maintained by the Driver Manager) of 1. If a matching shared environment is found, the environment is returned to the application, and its reference count is incremented. The actual connection to be used is not determined by the Driver Manager until SQLConnect or SQLDriverConnect is called. 4. Calls SQLConnect or SQLDriverConnect to make the connection. The Driver Manager uses the connection options in the call to SQLConnect (or the connection keywords in the call to SQLDriverConnect) and the connection attributes set after connection allocation to determine which connection in the pool should be used. Connections 17

18 NOTE: How a requested connection is matched to a pooled connection is determined by the SQL_ATTR_CP_MATCH environment attribute. 5. Calls SQLDisconnect when done with the connection. The connection is returned to the connection pool and becomes available for reuse. For information on enabling connection pooling, see Enabling Connection Pooling. Object Naming and Mapping ANSI Name Type The HP ODBC driver supports only ANSI name types for database objects. Using the Microsoft OBDC Administrator at a client workstation, you can configure the default schema name used to qualify the table names in queries. The object name format is as follows: schema.object-name ANSI names have a maximum of 128 characters for each part of the name (not including the dots). Ensure the catalog name is not qualified while defining your schema. Password Expiration NDCS is configured to allow the driver to display password expiration warnings. You can change your password during the current session in one of two ways: Provide the old and new passwords in a dialog box that displays with the expiration warning. If you enter an invalid password, the connection is terminated. You can also cancel the password change and just continue with the current session. Provide the old and new passwords in the connection string: PWD=old_password, new_password, new_password Release Considerations and Restrictions Table 1-1 Release Considerations and Restrictions for Windows Driver ODBC driver manager HP ODBC client software Schema HP ODBC driver requires the Microsoft ODBC 3.51 (or later) driver manager. If you do not already have the 3.51 driver manager, the HP ODBC driver installs it for you. An HP ODBC driver can coexist with other ODBC drivers. An ODBC client application can set the schema for an ODBC client data source by using the HP ODBC Driver window in the Microsoft ODBC Administrator. See Installing ODBC Client Software for more information. If an ODBC client does not set the schema for an ODBC client data source, NDCS defaults to USR. Note: Schema names follow SQL rules and are case sensitive. Schema names that are defined by default are not recognized by NDCS for client data sources because they are not defined through the Microsoft ODBC Administrator. You must either define the catalog and schema names using the Microsoft ODBC Administrator, or use the fully qualified object name. 18 HP ODBC Driver Overview for Windows

19 Table 1-1 Release Considerations and Restrictions for Windows Driver (continued) SQL_QUERY_TIMEOUT Option SQLCancel Function SQLPrimaryKeys Function SQLSpecialColumns Function SQLStatistics Function SQLTables Function When SchemaName is: SQL_ALL_SCHEMAS When TableType is: SQL_ALL_TABLE_TYPES SQL Table Names SQL Schema Names 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 NDCS server and ODBC client from long running queries. If a query exceeds the specified time before the data source returns the result set, the HP ODBC driver returns HYT00 (Timeout expired) to the ODBC client. In an ODBC 2.0 application, the HP ODBC driver implements the SQLCancel function as an SQLFreeStmt with the SQL_CLOSE option. If the query is running, HP ODBC driver 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, the HP ODBC driver behaves as it does for a 2.0 application. In an ODBC 3.0 application with no query running, the HP ODBC driver does not implement the SQLCancel function. The application is responsible for closing the cursor. This function does not support pattern value arguments for table names, and returns keys information for a specified table name. 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. This function does not support pattern value arguments for table names, and returns index information for a specified table name. Returns all schemas defined in the SQL metadata. Returns all object types supported by SQL. The ODBC 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. Traces You can trace activity for the ODBC client. The following data is collected: Entry and exit calls from Microsoft ODBC driver manager to the HP ODBC driver. Contents of the buffers, except password buffers. Activity between the HP ODBC driver and the transport layer. For more information about client tracing, click the Help button on the Client Microsoft Administrator. For information about configuring client data source traces, see Tracing Client Data Sources. INFOSTATS Command INFOSTATS is a pass-through command that collect statistics for a prepared statement. Statistics are returned to the ODBC application as a result set as soon as the PREPARE is finished. The result set has these columns: Traces 19

20 Query ID (SQL_CHAR) CPUTime (SQL_DOUBLE): An estimate of the number of seconds of processor time it might take to execute the instructions for this query. A value of is 1 second. IOTime (SQL_DOUBLE): An estimate of the number of seconds of I/O time (seeks plus data transfer) to perform the I/O for this query. MsgTime (SQL_DOUBLE): An estimate of the number of seconds it takes for the messaging for this query. The estimate includes the time for the number of local and remote messages and the amount of data sent. IdleTime (SQL_DOUBLE): An estimate of the maximum number of seconds to wait for an event to happen for this query. The estimate includes the amount of time to open a table or start an ESP process. TotalTime (SQL_DOUBLE): Estimated cost associated to execute the query. Cardinality (SQL_DOUBLE): Estimated number of rows that will be returned. INFOSTATS { stmt-name cursor-name sql-stmt } stmt-name is the name of a prepared statement. If a case-sensitive statement name is used, you must enclose it in double quotes. cursor-name is an SQL identifier. The name is unique within the containing module or compilation unit. The maximum length of a cursor name is 128 characters. If a case-sensitive cursor name is used, you must enclose it in double quotes. sql-stmt is any valid SQL query surrounded by double-quotes. Example of INFOSTATS Suppose an application prepares a SELECT statement: SELECT * FROM T1. Use SQLGetCursorName to find the statement name. In this example, the returned statement name is SQL_CUR_3. To get statistics for SELECT * FROM T1, the application must allocate another statement handle and issue SQLExecDirect on INFOSTATS SQL_CUR_3. The statistics are returned as a result set. Use SQLFetch to retrieve the result. SQLPrepare: In: StatementHandle - 0x003A1940, StatementText = "select * from tst1", TextLength - 18 Return: SQL_SUCCESS=0 SQLGetCursorName: SQLAllocHandle: In: HandleType = SQL_HANDLE_STMT=3, InputHandle = 0x003A1720, OutputHandlePtr = 0x00158CF0 Return: SQL_SUCCESS=0 Out: *OutputHandlePtr = 0x003A2158 SQLExecDirect : In: hstmt = 0x003A2158, szsqlstr = "infostats SQL_CUR_3", cbsqlstr = -3 Return: SQL_SUCCESS=0 Get Data All: "QueryID", "CPUTime", "IOTime", "MsgTime", "IdleTime", "TotalTime"' "Cardinality" "MXID _16_SQL_CUR_3", , , , , , row fetched from 7 columns 20 HP ODBC Driver Overview for Windows

21 In this example, INFOSTATS is issued directly on the SQL statement. Again, use SQLFetch to retrieve the result: SQLExecDirect: In: -3 Return: hstmt = 0x003B1968 szsqlstr = "infostats "select * from t1"", cbsqlstr = SQL_SUCCESS=0 Get Data All: "QueryID", "CPUTime", "IOTime", "MsgTime", "IdleTime", "TotalTime" "Cardinality" "MXID _60_STMT_INFOSTATS ", , , , , , row fetched from 7 columns. Unsupported ODBC API Functions and Data Types API Functions Data Types This release of HP ODBC driver does not support the following ODBC 3.51 API functions: SQLBulkOperations SQLFetchScroll - supported for SQL_FETCH_NEXT attribute only SQLSetScrollOption For descriptions of the ODBC API functions, see ODBC API Functions. NDCS does not support the following ODBC data types: BIT TINYINT and TINYINT UNSIGNED BINARY VARBINARY LONG VARBINARY For more information about data types, see ODBC Data Types. Restricted ODBC API Functions SQLBindParameter SQLPutData 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. 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. Unsupported ODBC API Functions and Data Types 21

22 22

23 2 HP ODBC Drivers Overview for Linux and HP-UX Open Database Connectivity (ODBC) is a widely accepted application programming interface (API) for database access. It is based on the Call-Level Interface (CLI) specifications from X/Open and ISO/IEC for database APIs and uses Structured Query Language (SQL) as its database access language. ODBC is designed for maximum interoperability that is, the ability of a single application to access different database management systems (DBMSs) with the same source code. Database applications call functions in the ODBC interface, which are implemented in database-specific modules called drivers. The use of drivers isolates applications from database-specific calls in the same way that printer drivers isolate word processing programs from printer-specific commands. Because drivers are loaded at run time, a user only has to add a new driver to access a new DBMS; it is not necessary to recompile or relink the application. The HP ODBC driver for Linux and HP-UX provides two libraries. One library is the ODBC driver (libhodbc_drvr) and the other library (libhpodbc) provides the driver manager functionality along with the ODBC driver in a single library. The packaged driver manager only supports the HP ODBC driver. This section describes: Driver Components Data Sources Connections Object Naming and Mapping Release Considerations and Restrictions Traces Using the Driver With a Third Party Driver Manager INFOSTATS Command Unsupported ODBC API Functions and Data Types Driver Components To configure ODBC client access to the HP Neoview database, the HP Neoview Database Connectivity Service (NDCS) requires data source definitions on both the Neoview database and client workstation Driver components can be installed on any workstation running Linux or HP-UX. These are the client components: MXODSN file Sample program HP ODBC driver Text file that contains client data sources. Run the sample program to verify a connection for HP ODBC Linux and HP-UX driver. Is 3.0 compliant and implements a subset of the ODBC 3.51 APIs. Enables an ODBC client application to access the Neoview database. Data Sources To configure ODBC client access to the Neoview database, NDCS requires data source definitions on both the Neoview database and the client workstation. Driver Components 23

24 Default Data Source NDCS 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 Neoview DB Admin, but you cannot delete it. The TDM_Default_DataSource has these functions: ODBC clients can connect to TDM_Default_DataSource. If an ODBC client tries to connect to a server data source that does not exist, it will default to TDM_Default_DataSource. Contact your Administrator to create server data sources. Client Data Sources Client data sources reside on a client workstation. Each client data source is a logical name that identifies the attribute values used to connect to NDCS. Edit your data source configuration file (MXODSN) to add a new data source or change the data source configuration. NOTE: If an ODBC client tries to connect to a server data source that is stopped, NDCS rejects the connection. Connections Connecting a Client to a Data Source The following scenario describes how an ODBC client application connects to NDCS: 1. The ODBC client application connects using the client data source name. The client source data specifies an IP address or host name and port number. 2. If the user information is not valid, the connection is rejected. Object Naming and Mapping ANSI Name Type The HP ODBC drivers support only ANSI name types for database objects. Use your MXODSN file to configure the default schema name used to qualify the table names in queries. The name format is as follows: schema.object-name ANSI names have a maximum of 128 characters for each part of the name (not including the dots). Ensure the catalog name is not qualified while defining your schema. Password Expiration NDCS is configured to allow the driver to display password expiration warnings. You can change your password during the current session in one of two ways: Provide the old and new passwords in a dialog box that displays with the expiration warning. If you enter an invalid password, the connection is terminated. You can also cancel the password change and just continue with the current session. Provide the old and new passwords in the connection string: PWD=old_password, new_password, new_password 24 HP ODBC Drivers Overview for Linux and HP-UX

25 Release Considerations and Restrictions Table 2-1 Release Considerations and Restrictions for Linux and HP-UX Drivers HP ODBC driver software Schema SQLPrimaryKeys Function SQLSpecialColumns Function SQLStatistics Function SQLTables Function When SchemaName is: SQL_ALL_SCHEMAS When TableType is: SQL_ALL_TABLE_TYPES SQL Table Names SQL Schema Names An HP ODBC driver cannot coexist with other ODBC drivers. Since the HP ODBC drivers consist of a driver manager and driver, an application that links HP ODBC cannot link in with other ODBC drivers. An ODBC client application can set the schema for an ODBC client data source by editing your MXODSN file. If an ODBC client does not set the schema for an ODBC client data source, NDCS defaults to USR. Note: Schema names follow SQL rules and are case sensitive. Schema names that are defined by default are not recognized by NDCS for client data sources. This function does not support pattern value arguments for table names, and returns keys information for a specified table name. 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. This function does not support pattern value arguments for table names, and returns index information for a specified table name. Returns all schemas defined in the SQL metadata. Returns all object types supported by SQL. The ODBC 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. Traces You can trace activity for the ODBC client. The following data is collected: Entry and exit calls to the HP ODBC drivers Contents of the buffers, except password buffers Activity between the HP ODBC drivers and the transport layer Using the Driver With a Third Party Driver Manager For questions related to your third party driver manager, refer to your driver manager's documentation. You must configure the following data source attributes. For an example of configuration values, refer to the MXODSN file template provide with the installation. DESCRIPTION = Default Data Source Catalog = CAT Schema = SCH DataLang = 0 FetchBufferSize = SYSTEM_DEFAULT Server = TCP:arc0101.caclab.cac.cpqcorp.net:5000 SQL_ATTR_CONNECTION_TIMEOUT = SYSTEM_DEFAULT Release Considerations and Restrictions 25

26 SQL_LOGIN_TIMEOUT = SYSTEM_DEFAULT SQL_QUERY_TIMEOUT = NO_TIMEOUT INFOSTATS Command INFOSTATS is a pass-through command that collect statistics for a prepared statement. Statistics are returned to the ODBC application as a result set as soon as the PREPARE is finished. The result set has these columns: Query ID (SQL_CHAR) CPUTime (SQL_DOUBLE): An estimate of the number of seconds of processor time it might take to execute the instructions for this query. A value of is 1 second. IOTime (SQL_DOUBLE): An estimate of the number of seconds of I/O time (seeks plus data transfer) to perform the I/O for this query. MsgTime (SQL_DOUBLE): An estimate of the number of seconds it takes for the messaging for this query. The estimate includes the time for the number of local and remote messages and the amount of data sent. IdleTime (SQL_DOUBLE): An estimate of the maximum number of seconds to wait for an event to happen for this query. The estimate includes the amount of time to open a table or start an ESP process. TotalTime (SQL_DOUBLE): Estimated cost associated to execute the query. Cardinality (SQL_DOUBLE): Estimated number of rows that will be returned. INFOSTATS { stmt-name cursor-name sql-stmt } stmt-name is the name of a prepared statement. If a case-sensitive statement name is used, you must enclose it in double quotes. cursor-name is an SQL identifier. The name is unique within the containing module or compilation unit. The maximum length of a cursor name is 128 characters. If a case-sensitive cursor name is used, you must enclose it in double quotes. sql-stmt is any valid SQL query surrounded by double-quotes. Example of INFOSTATS Suppose an application prepares a SELECT statement: SELECT * FROM T1. Use SQLGetCursorName to find the statement name. In this example, the returned statement name is SQL_CUR_3. To get statistics for SELECT * FROM T1, the application must allocate another statment handle and issue SQLExecDirect on INFOSTATS SQL_CUR_3. The statistics are returned as a result set. Use SQLFetch to retrieve the result. SQLPrepare: In: StatementHandle - 0x003A1940, StatementText = "select * from tst1", TextLength - 18 Return: SQL_SUCCESS=0 SQLGetCursorName: SQLAllocHandle: In: HandleType = SQL_HANDLE_STMT=3, InputHandle = 0x003A1720, OutputHandlePtr = 0x00158CF0 Return: SQL_SUCCESS=0 Out: *OutputHandlePtr = 0x003A2158 SQLExecDirect : In: hstmt = 0x003A2158, szsqlstr = "infostats SQL_CUR_3", cbsqlstr = HP ODBC Drivers Overview for Linux and HP-UX

27 Return: SQL_SUCCESS=0 Get Data All: "QueryID", "CPUTime", "IOTime", "MsgTime", "IdleTime", "TotalTime"' "Cardinality" "MXID _16_SQL_CUR_3", , , , , , row fetched from 7 columns In this example, INFOSTATS is issued directly on the SQL statement. Again, use SQLFetch to retrieve the result: SQLExecDirect: In: hstmt = 0x003B1968 szsqlstr = "infostats "select * from t1"", cbsqlstr = -3 Return: SQL_SUCCESS=0 Get Data All: "QueryID", "CPUTime", "IOTime", "MsgTime", "IdleTime", "TotalTime" "Cardinality" "MXID _60_STMT_INFOSTATS ", , , , , , row fetched from 7 columns. Unsupported ODBC API Functions and Data Types API Functions Data Types This release of the HP ODBC drivers does not support the following ODBC 3.51 API functions: SQLBulkOperations SQLCancel SQLFetchScroll - supported for SQL_FETCH_NEXT attribute only SQLSetScrollOption NDCS does not support the following ODBC data types: BIT TINYINT and TINYINT UNSIGNED BINARY VARBINARY LONG VARBINARY Restricted ODBC API Functions SQLBindParameter SQLPutData 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. 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. Unsupported ODBC API Functions and Data Types 27

28 28

29 3 Installing the HP ODBC Drivers This section contains information on how to install the HP ODBC Drivers on Windows, Linux, and HP-UX. This section describes: Installing ODBC Client Software For installing on Windows: Installing the HP ODBC Driver for Windows Reinstalling the HP ODBC Driver for Windows Uninstalling the HP ODBC Driver for Windows Setting Up the Client Environment Troubleshooting Getting the Version of the Driver ODBC API Reference For installing on Linux and HP-UX: Installing or Reinstalling HP ODBC Drivers for Linux and HP-UX Setting Up the Client Environment Running the Sample Program Troubleshooting Debugging Getting the Version of the Driver ODBC API Reference Installing ODBC Client Software If you plan to use ODBC connectivity for any data source, you must install ODBC client software on each workstation that uses ODBC data sources. Although each client workstation can download the installation file directly from the HP Web site, in large installations it might be more efficient to download the installation file to an internal Web location for easier deployment to all client workstations. Installing the HP ODBC Driver for Windows The HP ODBC driver software is available as a downloadable distribution file without an extension. The ODBC client installation file installs or links to multiple client components: This client component... Microsoft ODBC Driver Manager HP ODBC driver Microsoft ODBC Administrator ODBC Test application Does this... Manages access to ODBC drivers for applications. The driver manager loads and unloads drivers and passes calls for ODBC functions to the correct driver. Implements ODBC function calls to enable an ODBC client application to access the HP Neoview database. Adds, configures, and removes ODBC data sources on client workstations. Tests ODBC functions. Installing ODBC Client Software 29

30 Installation Requirements Requirement Computer Memory Disk space Operating system Network software Description 100% IBM compatible PC workstations Recommended minimum 32 MB Minimum 30 MB additional free space Microsoft Windows 2000, Windows 2003, and Windows XP TCP/IP NOTE: To install the driver, you must be logged on with a user ID that has administrative privileges. Download and Run the Client Installation File NOTE: If you are using a Highlander Quality Code Delivery (QCD), see the QCD README for HP ODBC Driver for Windows at this location: The following instructions for downloading apply only to Neoview customers. 1. Close all other applications running on the client workstation. 2. Create a temporary client installation folder on the client workstation (for example: C:\ODBCTEMP). 3. From the client workstation, start a browser and navigate to the download site: 4. Search for Neoview ODBC in the Software Depot. 5. Click thehp Neoview ODBC Windows Driver link that appears in the search results. 6. Follow instructions to download the HP Neoview ODBC Windows driver. 7. Click HPODBC, and save the file to the temporary folder. 8. Rename the file to HPODBC.exe. Start the InstallShield Wizard InstallShield wizard walks you through the steps to install the client components (HP ODBC ) on your workstation. 1. Double-click the HPODBC.exe file to start the InstallShield wizard. 2. On the Welcome page, click Next. 3. On the License Agreement page, click to accept the terms of the agreement and proceed. 4. On the Choose Destination Location page, click Next to select the default location: C:\Program Files\Hewlett-Packard\HP ODBC 5. On the Setup Type page, Typical is selected. Click Next to select this type. 6. On the Select Program Folder page, select the HP ODBC program folder, and click Next. 7. On the Start Copying Files page, review the install options that you have selected, and click Next to begin copying program files. 8. If the HTML Help is not installed, you have the opportunity to install it. Click to install HTML Help. The HTML Help installer runs after installation of the ODBC client software is complete. 30 Installing the HP ODBC Drivers

31 9. On the InstallShield Wizard Complete page, click Finish to exit the wizard. 10. You might see the Restart Required dialog box. Click to automatically restart your system now. If you click No, you must restart your system for the installation to complete. Add a Client Data Source Follow the steps in Adding New Client Data Sources to add the data sources needed to support the ODBC applications on the client workstation. Delete the Installation Folder When the installation is complete, delete the temporary installation folder you created in Download and Run the Client Installation File (for example, C:\ODBCTEMP). Reinstalling the HP ODBC Driver for Windows Download and Run the ODBC Client Installation File 1. Close all other applications running on the client workstation. 2. Create a temporary client installation folder on the client workstation (for example: C:\ODBCTEMP). 3. From the client workstation, start a browser and navigate to the download site: 4. Search for Neoview ODBC in the Software Depot. 5. Click the HP Neoview ODBC Windows Driver link that appears in the search results. 6. Follow the instructions to download the HP Neoview ODBC Windows driver. 7. Click HPODBC, and save the file to the temporary folder. 8. Rename the file to HPODBC.exe. Start the InstallShield Wizard and Reinstall the Driver 1. Double-click the HPODBC.exe file to start the InstallShield wizard. 2. On the Welcome page, select the Repair option, and click Next. 3. Click Finish to complete the reinstallation of HP ODBC. NOTE: The newly installed HP ODBC driver uses pre-existing data source definitions from the Windows registry. You do not need to re-create these data source definitions after reinstalling the ODBC driver. Uninstalling the HP ODBC Driver for Windows 1. Start the HP ODBC uninstall process: Start> Programs> HP ODBC > Remove HP ODBC Click to completely remove HP ODBC. 2. Finish the uninstall process: Click Finish to complete the removal of HP ODBC. Reinstalling the HP ODBC Driver for Windows 31