HP Neoview ODBC Drivers Manual

Transcription

1 HP Neoview ODBC Drivers Manual Abstract 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. Part Number Published August 2006

2 Document History Part Number Published August 2006

3 HP Neoview ODBC Drivers Manual Index Tables What s New in This Manual v Manual Information v New and Changed Information About This Manual vii Who Should Use This Manual How This Manual is Organized Where to Find Documentation Related Documentation viii Notation Conventions ix v vii vii vii 1. HP ODBC Driver Overview for Windows Driver Components 1-1 Data Sources 1-2 Default Data Source 1-2 Client Data Sources 1-2 Connections 1-3 Connecting a Client to a Data Source 1-3 Connection Pooling 1-3 Object Naming and Mapping 1-5 ANSI Name Type 1-5 Release Considerations and Restrictions 1-6 Traces 1-7 INFOSTATS Command 1-7 Unsupported ODBC API Functions and Data Types 1-8 API Functions 1-8 Data Types 1-8 Restricted ODBC API Functions 1-8 Hewlett-Packard Company i

4 Contents 2. HP ODBC Drivers Overview for Linux and HP-UX 2. HP ODBC Drivers Overview for Linux and HP-UX Driver Components 2-1 Data Sources 2-2 Default Data Source 2-2 Client Data Sources 2-2 Connections 2-2 Connecting a Client to a Data Source 2-2 Object Naming and Mapping 2-2 ANSI Name Type 2-2 Release Considerations and Restrictions 2-3 Traces 2-4 INFOSTATS Command 2-4 Unsupported ODBC API Functions and Data Types 2-4 API Functions 2-4 Data Types 2-4 Restricted ODBC API Functions Installing the HP ODBC Drivers Installing ODBC Client Software 3-1 Installing the HP ODBC Driver for Windows 3-1 Installation Requirements 3-2 Reinstalling the HP ODBC Driver for Windows 3-3 Uninstalling the HP ODBC Driver for Windows 3-4 Setting Up the Client Environment 3-4 Troubleshooting 3-4 Client Interface Files 3-5 Getting the Version of the Driver 3-6 ODBC API Reference 3-6 Installing or Reinstalling HP ODBC Drivers for Linux and HP-UX 3-6 Installation Package 3-6 Installing or Reinstalling the HP ODBC Drivers 3-8 Setting Up the Client Environment 3-9 Running the Sample Program 3-9 Troubleshooting 3-10 Debugging 3-11 Getting the Version of the Driver 3-11 ODBC API Reference 3-12 ii

5 Contents 4. Configuring Client Data Sources 4. Configuring Client Data Sources Adding New Client Data Sources 4-1 Reconfiguring ODBC Client Data Sources 4-2 Configuring ODBC Client Data Sources for Update Operations 4-2 Removing ODBC Client Data Sources 4-2 Tracing Client Data Sources 4-3 Enabling Connection Pooling 4-4 Configuring the Client Data Source on Linux and HP-UX 4-6 Setting Trace On 4-6 Adding a New Data Source HP ODBC Drivers Conformance ODBC API Functions 5-1 SQL Conformance Level 5-7 SQL Scalar Functions 5-7 ODBC Data Types 5-10 Unsigned Data Types 5-11 Partial Date/Time Values 5-12 Microsoft Escape Clauses 5-12 Stored Procedures 5-12 Transactions and Cursor Behavior with Multiple Statements HP ODBC Drivers Messages Index Tables HP ODBC Drivers Error Codes 6-1 HP ODBC Client Messages 6-1 Table 1-1. Release Considerations and Restrictions 1-6 Table 2-1. Release Considerations and Restrictions 2-3 Table 5-1. Connecting to a Data Source 5-2 Table 5-2. Obtaining Information About a Driver and Data Source 5-2 Table 5-3. Setting and Retrieving Driver Attributes 5-3 Table 5-4. Setting and Retrieving Descriptor Fields 5-3 Table 5-5. Preparing SQL Requests 5-3 Table 5-6. Submitting SQL Requests 5-4 Table 5-7. Retrieving Results and Information About Results 5-4 Table 5-8. Obtaining Information About a Data Source s System Tables 5-5 Table 5-9. Terminating a Statement 5-6 iii

6 Contents Tables (continued) Tables (continued) Table Terminating a Connection 5-7 Table Numeric Functions 5-7 Table String Functions 5-8 Table Time and Date Functions 5-9 Table System Functions 5-10 Table ODBC Data Types 5-10 Table Behavior of Unsigned Data Types 5-12 Table Microsoft Escape Clauses 5-12 Table Transactions and Cursor Behavior 5-13 iv

7 What s New in This Manual Manual Information Abstract HP Neoview ODBC Drivers Manual 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. Part Number Published August 2006 Document History Part Number Published August 2006 New and Changed Information This is a new manual. v

8 What s New in This Manual New and Changed Information vi

9 About This Manual Who Should Use This Manual This manual is for Anyone who installs, configures, manages, or troubleshoots HP ODBC software and connectivity. ODBC application programmers who write 32-bit applications to access an HP Neoview database. Other end users or application programmers who use HP ODBC drivers to access a Neoview database. How This Manual is Organized Section 1, HP ODBC Driver Overview for Windows provides an overview of the HP ODBC driver on Windows. Section 2, HP ODBC Drivers Overview for Linux and HP-UX provides an overview of the HP ODBC drivers on Linux and HP-UX. Section 3, Installing the HP ODBC Drivers explains how to install HP ODBC drivers on Windows, Linux, and HP-UX. Section 4, Configuring Client Data Sources describes how to configure data sources on Windows, Linux, and HP-UX. Section 5, HP ODBC Drivers Conformance contains tables that describe HP ODBC drivers conformance to standard ODBC API functions and SQL conformance levels. Section 6, HP ODBC Drivers Messages describes HP ODBC drivers error codes. Where to Find Documentation Other documentation can be found on the HP Web site: The HP Neoview DB Admin help system is accessible from its respective application. vii

10 About This Manual Related Documentation Related Documentation This manual is part of the HP Neoview library, which includes: Customer Documentation Neoview Owner s Manual Neoview Database Administrator s Guide Neoview DB Admin Help ODBC Client Help Neoview ODBC Drivers Manual Neoview JDBC Type 4 Driver Programmer s Reference Neoview JDBC Type 4 Driver API Reference Neoview Script Guide Neoview SQL Reference Manual Neoview Messages Manual Neoview README HP Support Documentation Neoview Hardware Installation and Support Guide Neoview Database Support Guide Neoview ODBC and JDBC Troubleshooting Guide Boot App Help VST001.vsd Customer Documentation Neoview Owner s Manual Neoview Database Administrator s Guide Neoview DB Admin Online Help ODBC Client Administrator Online Help Neoview ODBC Drivers Manual Neoview JDBC Type 4 Driver Programmer s Reference Neoview JDBC Type 4 Driver API Reference Basic hardware information for customer reference. Basic task information for getting started and using the HP Neoview database software. Context-sensitive help topics that describe how to use the HP Neoview DB Admin management interface. Context-sensitive help topics that describe how to use the ODBC client interface. Information for using HP Neoview ODBC drivers on a client workstation to access a Neoview database. Information for using the HP Neoview JDBC Type 4 Driver on a client workstation to access a Neoview database. Reference information for the HP Neoview JDBC Type 4 API. viii

11 About This Manual Notation Conventions Neoview Script Guide Neoview SQL Reference Manual Neoview Messages Manual Neoview README HP Support Documentation Neoview Hardware Installation and Support Guide Neoview Database Support Guide Neoview ODBC and JDBC Troubleshooting Guide Boot Application Online Help 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: The SQL statements are listed in Appendix B, Supported SQL Statements. 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: SELECT Information for using the HP Neoview Script command-line interface to run SQL statements interactively or from script files. 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. Installation and replacement procedures. Procedures and reference information that are unique to the Neoview database software or not documented in other HP manuals. Guidelines for troubleshooting ODBC and JDBC connectivity to an HP Neoview data warehousing platform. Reference information for using the boot software. ix

12 About This Manual General Syntax Notation 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 case-sensitive keywords and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required. For example: myfile.sh italic computer type. Italic computer type letters within text indicate variable items that you supply. Items not enclosed in brackets are required. For example: pathname [ ] 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 } 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}... x

13 About This Manual Notation for Messages 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 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] Notation for Messages This list summarizes the notation conventions for the presentation of displayed messages in this manual. 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. xi

14 About This Manual Change Bar Notation Change Bar Notation Change bars indicate substantive differences between this manual and its preceding version. Change bars are vertical rules in the right margin of changed portions of text, figures, tables, examples, and so on. Change bars highlight new or revised information. For example: This edition of the manual describes new functionality in the database. Some of the new functionality provides enhancements that... xii

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 on page 1-1 Data Sources on page 1-2 Connections on page 1-3 Object Naming and Mapping on page 1-5 Release Considerations and Restrictions on page 1-6 Traces on page 1-7 INFOSTATS Command on page 1-7 Unsupported ODBC API Functions and Data Types on page 1-8 Unsupported ODBC API Functions and Data Types on page 1-8 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: 1-1

16 HP ODBC Driver Overview for Windows Data Sources ODBC test application Microsoft ODBC 3.51 (or later) driver manager HP ODBC driver Microsoft ODBC Administrator 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. 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 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. 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. 1-2

17 HP ODBC Driver Overview for Windows Connections 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 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 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 1-3

18 HP ODBC Driver Overview for Windows Connection Pooling 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 1-4

19 HP ODBC Driver Overview for Windows Object Naming and Mapping keywords in the call to SQLDriverConnect) and the connection attributes set after connection allocation to determine which connection in the pool should be used. 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 on page 4-4. 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. 1-5

20 HP ODBC Driver Overview for Windows Release Considerations and Restrictions Release Considerations and Restrictions Table 1-1. Release Considerations and Restrictions (page 1 of 2) ODBC driver manager HP ODBC client software Schema SQL_QUERY_TIMEOUT Option SQLCancel Function SQLPrimaryKeys Function 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 on page 3-1 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. 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. 1-6

21 HP ODBC Driver Overview for Windows Traces Table 1-1. Release Considerations and Restrictions (page 2 of 2) SQLSpecialColumns Function SQLStatistics Function SQLTables Function When SchemaName is SQL_ALL_SCHEMAS 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. When TableType is SQL_ALL_TABLE_TYPES SQL Table Names SQL Schema Names 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 on page 4-3. INFOSTATS Command INFOSTATS is a pass-through command that collects statistics for a prepared statement. Statistics are returned to the ODBC application as a result set as soon as the PREPARE is finished. For further information on the INFOSTATS command, see the HP Neoview SQL Reference Manual. 1-7

22 HP ODBC Driver Overview for Windows Unsupported ODBC API Functions and Data Types Unsupported ODBC API Functions and Data Types API Functions 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 on page 5-1. Data Types 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 on page 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. 1-8

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. This section describes: Driver Components on page 2-1 Data Sources on page 2-2 Connections on page 2-2 Object Naming and Mapping on page 2-2 Release Considerations and Restrictions on page 2-3 Traces on page 2-4 INFOSTATS Command on page 2-4 Unsupported ODBC API Functions and Data Types on page 2-4 Unsupported ODBC API Functions and Data Types on page 2-4 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. 2-1

24 HP ODBC Drivers Overview for Linux and HP-UX Data Sources 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. 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. 2-2

25 HP ODBC Drivers Overview for Linux and HP-UX Release Considerations and Restrictions 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. Release Considerations and Restrictions Table 2-1. Release Considerations and Restrictions HP ODBC driver software Schema SQLPrimaryKeys Function SQLSpecialColumns Function SQLStatistics Function SQLTables Function When SchemaName is SQL_ALL_SCHEMAS 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. When TableType is SQL_ALL_TABLE_TYPES SQL Table Names SQL Schema Names 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. 2-3

26 HP ODBC Drivers Overview for Linux and HP-UX Traces 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 INFOSTATS Command INFOSTATS is a pass-through command that collects statistics for a prepared statement. Statistics are returned to the ODBC application as a result set as soon as the PREPARE is finished. For further information on the INFOSTATS command, see the HP Neoview SQL Reference Manual. Unsupported ODBC API Functions and Data Types API Functions 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 Data Types NDCS does not support the following ODBC data types: BIT TINYINT and TINYINT UNSIGNED BINARY VARBINARY LONG VARBINARY 2-4

27 HP ODBC Drivers Overview for Linux and HP-UX Restricted ODBC API Functions 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. 2-5

28 HP ODBC Drivers Overview for Linux and HP-UX Restricted ODBC API Functions 2-6

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 on page 3-1 For installing on Windows: Installing the HP ODBC Driver for Windows on page 3-1 Reinstalling the HP ODBC Driver for Windows on page 3-3 Uninstalling the HP ODBC Driver for Windows on page 3-4 Setting Up the Client Environment on page 3-4 Troubleshooting on page 3-4 Getting the Version of the Driver on page 3-6 ODBC API Reference on page 3-6 For installing on Linux and HP-UX: Installing or Reinstalling HP ODBC Drivers for Linux and HP-UX on page 3-6 Setting Up the Client Environment on page 3-9 Running the Sample Program on page 3-9 Troubleshooting on page 3-10 Debugging on page 3-11 Getting the Version of the Driver on page 3-11 ODBC API Reference on page 3-12 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: 3-1

30 Installing the HP ODBC Drivers Installation Requirements 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. Installation Requirements Requirement Description Computer Memory Disk space Operating system Network software 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 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: From the Categories list, click Downloadable Tools. 4. Select HP ODBC Driver for Windows. Click File Download on the File Download dialog box. 5. Click Save, and save the file to the temporary folder. 6. Rename the file to HPODBC.exe. Start the InstallShield Wizard InstallShield wizard walks you through the steps to install the client components (HP ODBC 1.0) on your workstation. 1. Double-click the HPODBC.exe file to start the InstallShield wizard. 2. On the Welcome page, click Next. 3-2

31 Installing the HP ODBC Drivers Reinstalling the HP ODBC Driver for Windows 3. On the License Agreement page, click Yes 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 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 1.0 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 Yes to install HTML Help. The HTML Help installer runs after installation of the ODBC client software is complete. 9. On the InstallShield Wizard Complete page, click Finish to exit the wizard. 10. You might see the Restart Required dialog box. Click Yes 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 on page 4-1 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 on page 3-2 (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: From the Categories list, click Downloadable Tools. 4. Select the HP ODBC Driver for Windows. Click File Download on the File Download dialog box. 5. Click Save, and save the file to the temporary folder. 3-3

32 Installing the HP ODBC Drivers Uninstalling the HP ODBC Driver for Windows 6. 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 1.0. 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 1.0 uninstall process: Start> Programs> HP ODBC 1.0> Remove HP ODBC 1.0 Click Yes to completely remove HP ODBC Finish the uninstall process: Click Finish to complete the removal of HP ODBC 1.0. Note. Uninstalling the HP ODBC driver does not remove pre-existing data source definitions from the Windows registry. Setting Up the Client Environment All client data sources connect to the preconfigured server data source on the Neoview database, which is TDM_Default_DataSource. Only one data source, TDM_Default_DataSource, can be configured on the Neoview database, but you can create other data source definitions on the workstation. You can have more than one schema on the Neoview database. Instead of changing the schema definition in the data source definition on the workstation, you can create multiple data source definitions on the workstation with different schemas. However, the connection will default to TDM_Default_DataSource. Troubleshooting You can repair the ODBC client installation when the Windows Registry or a necessary ODBC file becomes corrupt, or a file is deleted by mistake. Begin Client Installation Again Perform the steps found in Download and Run the Client Installation File on page 3-2. Select Repair Option 3-4

33 Installing the HP ODBC Drivers Client Interface Files When the InstallShield detects a reinstallation, it displays a screen as follows: Screen Button Description Modify, Repair or Modify Adds and removes ODBC components. Remove the Repair Click Repair to reinstall the ODBC files and repair your program system. Remove Uninstalls the client program Finish Finish Performs installation cleanup and exits the installation. Reboot Required Yes/No This screen displays only if rebooting your system is required. Click Yes to automatically reboot your system now. If you click No, you must reboot your system later for the repair changes to take effect. Client Interface Files HP ODBC Driver core components: ODBC 3.51 Core Component (in system directory) OLE DB 2.0 files (in system directory) Translator (in system directory) ODBC Tools (in system directory) ds16gt.dll ds32gt.dll mdacmigr.dll * migrate.bat* migrate.reg* msdasql.dl msdasqlr.dll msdasqlrm.txt msvcrt.dl mtxdm.dll *Windows 98 only asycfilt.dll comcat.dll msdadc.dll msdaenum.dll msdaer.dll msdaosp.dll msdaps.dll msdasc.cnt msdasc.dll cpx cpx mscpxl32.dll gtrtst32.dll odbc.cnt odbc.hlp odbc16gt.dll odbc32.dll odbc32gt.dll odbcad32.exe odbccp32.cpl odbccp32.dll odbccr32.dll odbccu32.dll odbcinst.cnt odbcinst.hlp odbcinst.dll odbctrac.dll msdasc.hlp msdasc.txt msdatl2.dll msdatt.dll odbcte32.exe OdbcTest.cnt Odbctest.hlp 3-5

34 Installing the HP ODBC Drivers Getting the Version of the Driver Self Registering system files (in system directory) mfc42.dll HP ODBC Driver component: Driver files (in system directory) Driver support files (in system directory) Transport files (in system directory) ODBC documentation (in selected directory) Self Registering system files (in system directory) System files (in system directory) hp_oadm0100.dll hp_odbc0100.dll hp_odbctrace.dll hp_odbcdrvmsg_intl0100.dll hp_tcpipv4.dll hp_tcpipv6.dll odbcmxds.chm readme.txt mfc42.dll msvcp60.dll Getting the Version of the Driver 1. On the client workstation, navigate to the system32 directory. For example: C:\Windows\system32 on Windows XP C:\WINNT\system32 on Windows Locate the hp_odbc0100.dll file in the system32 directory. 3. Right-click on the hp_odbc0100.dll file, and select Properties. 4. On the Properties page, select the version tab, and note the version that is displayed under Value. ODBC API Reference For more information about the ODBC external specification, see Microsoft pages: Installing or Reinstalling HP ODBC Drivers for Linux and HP-UX Installation Package The HP ODBC Linux and HP-UX driver software is distributed as downloadable distribution files. 3-6

35 Installing the HP ODBC Drivers Installation Package The distribution files: (vvv is the version number. For example, 1.0.0) Linux: hpodbc_vvv_linux_pkg.tar.gz HPUX(IA-64): hpodbc_vvv_hpux_i_pkg.tar.gz HPUX(PA-RISC): hpodbc_vvv_hpux_p_pkg.tar.gz Files contained in the distribution file: Linux: libhpodbc_1.so.x.0.0 (The value of x increases with succeeding major releases.) LIBINFO.TXT MXODSN MD5SUM sql.h sqlext.h sqltypes.h install.sh connect_test.cpp HP-UX(IA-64): libhpodbc_i.sl.x (The value of x increases with succeeding major releases.) LIBINFO.TXT MXODSN MD5SUM sql.h sqlext.h sqltypes.h install.sh connect_test.cpp HP-UX(PA-RISC): libhpodbc_p.sl.x (The value of x increases with succeeding major releases.) LIBINFO.TXT MXODSN MD5SUM sql.h sqlext.h sqltypes.h install.sh connect_test.cpp By default, a new version of the HP ODBC driver will be installed in these directories unless you specify different directories during installation: /usr/lib /usr/include/hpodbc 3-7

36 Installing the HP ODBC Drivers Installing or Reinstalling the HP ODBC Drivers /etc/hpodbc /etc/hpodbc/sample Installing or Reinstalling the HP ODBC Drivers To install or reinstall HP ODBC driver for Linux or HP-UX, follow these steps: Note. You must have root access to install the HP ODBC drivers at the default system locations. 1. From the client workstation, start a browser and navigate to the download site: Note. For the most current installation instructions, click Read Mes in the Categories list and refer to the README for the HP ODBC Drivers for Linux and HP-UX document. From the Categories list, click Downloadable Tools. 2. Depending on your need, select the HP ODBC Driver for Linux, HP ODBC Driver for HP-UX (IA-64), or HP ODBC Driver for HP-UX (PA-RISC). Click File Download on the File Download dialog box. 3. Create a temporary directory. 4. Move the distribution file into the temporary directory. Linux: hpodbc_vvv_linux_pkg.tar.gz HP-UX(IA-64): hpodbc_vv_hpux_i_pkg.tar.gz HP-UX(PA-RISC): hpodbc_vvv_hpux_p_pkg.tar.gz 5. Expand the installation and product files: Linux: gunzip hpodbc_vvv_linux_pkg.tar.gz HP-UX(IA-64): gunzip hpodbc_vvv_hpux_i_pkg.tar.gz HP-UX(PA-RISC): gunzip hpodbc_vvv_hpux_p_pkg.tar.gz 6. Extract the installation and product files. A directory called PkgTmp is created. Linux: tar-xvf hpodbc_vvv_linux_pkg.tar HP-UX(IA-64): tar-xvf hpodbc_vvv_hpux_i_pkg.tar HP-UX(PA-RISC): tar-xvf hpodbc_vvv_hpux_p_pkg.tar 7. Install the product: cd PkgTmp./install.sh Note. Except for the sample file, the install.sh script saves a copy (.SAV) of your previous installation files, if they exist. 3-8

37 Installing the HP ODBC Drivers Setting Up the Client Environment 8. Enter a directory for the library file, or press Enter to use the default directory (/usr/lib). 9. Enter a directory for the data source template file (MXODSN file), or press Enter to use the default directory (/etc/hpodbc). 10. Enter a directory for the include files, or press Enter to use the default directory (/usr/include/hpodbc). 11. Enter a directory for the sample, or press Enter to use the default directory (/etc/hpodbc/sample). Setting Up the Client Environment If you selected default options during installation, ensure that: The include (*.h) files are in the /usr/include/hpodbc directory. An MXODSN file is in the /etc/hpodbc directory. Note. By default, the MXODSN file in the package will be installed as /etc/hpodbc/mxodsn.template. Rename it to MXODSN, and make necessary changes to the file before using the drivers. The library is located in the /usr/lib directory. If you selected non default locations during installation, ensure that the files are installed in the directories that you specified in Steps 6 to 9 in Installing or Reinstalling HP ODBC Drivers for Linux and HP-UX on page 3-6. Note. The drivers expect the MXODSN file to be present in either the default location (/etc/hpodbc) or the current working directory (CWD) of the application. Running the Sample Program The examples after each step assume that you have default installation directories. 1. Move to the directory where you installed the sample program: cd /etc/hpodbc/sample 2. Compile the sample program: For Linux or HP-UX(IA-64) gcc connect_test.cpp -L/usr/lib -I/usr/include/hpodbc \ -lhpodbc -o connect_test For HP-UX(PA-RISC) acc -AA connect_test.cpp -L/usr/lib \ -I/usr/include/hpodbc -lhpodbc -lhppa -lstd_v2 -lcsup_v2 \ -lm 3-9