Enterprise Connect Data Access Option for ODBC

Transcription

1 Users Guide for Access Services Enterprise Connect Data Access Option for ODBC 15.0 [ Microsoft Windows, Linux, and UNIX ]

2 DOCUMENT ID: DC LAST REVISED: August 2007 Copyright by Sybase, Inc. All rights reserved. This publication pertains to Sybase software and to any subsequent release until otherwise indicated in new editions or technical notes. Information in this document is subject to change without notice. The software described herein is furnished under a license agreement, and it may be used or copied only in accordance with the terms of that agreement. To order additional documents, U.S. and Canadian customers should call Customer Fulfillment at (800) , fax (617) Customers in other countries with a U.S. license agreement may contact Customer Fulfillment via the above fax number. All other international customers should contact their Sybase subsidiary or local distributor. Upgrades are provided only at regularly scheduled software release dates. No part of this publication may be reproduced, transmitted, or translated in any form or by any means, electronic, mechanical, manual, optical, or otherwise, without the prior written permission of Sybase, Inc. Sybase trademarks can be viewed at the Sybase trademarks page at Sybase and the marks listed are trademarks of Sybase, Inc. indicates registration in the United States of America. Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. Unicode and the Unicode Logo are registered trademarks of Unicode, Inc. All other company and product names mentioned may be trademarks of the respective companies with which they are associated. Use, duplication, or disclosure by the government is subject to the restrictions set forth in subparagraph (c)(1)(ii) of DFARS for the DOD and as set forth in FAR (a)-(d) for civilian agencies. Sybase, Inc., One Sybase Drive, Dublin, CA

3 Contents About This Book... ix CHAPTER 1 Introducing Enterprise Connect Data Access Option for ODBC 1 ECDA Option for ODBC... 1 ODBC driver... 2 How DirectConnect server routes access service requests... 2 Configuring properties for ECDA Option for ODBC... 3 Server external files... 4 Using DirectConnect Manager... 5 Globalization... 6 Internationalization... 6 Localization... 7 CHAPTER 2 Configuring the Access Service Library... 9 Understanding the configuration process... 9 Description of the configuration file How to change configuration property values Using DirectConnect Manager Using the text editor How to create additional services Using DirectConnect Manager Using the text editor Code page translation for ODBC-based products Configuration property categories Service library properties ACS Required property Catalog Stored Procedures properties Client Interaction properties Data Conversion Error properties Datatype Conversion properties Logging properties Target Interaction properties Tracing properties Access Service Users Guide iii

4 Contents Transfer properties CHAPTER 3 Configuring Access Services to Work with Related Products.. 57 Setting up Adaptive Server Enterprise Configure for remote access Define the access service as a remote server Define connectivity between ASE and an access service Setting up ECDA Option for ODBC for ASE/CIS Using ASE/CIS with the ASE transaction model Setting up ECDA Option for ODBC for Replication Server CHAPTER 4 Querying and Setting Operating Values Querying global variables Issuing set statements CHAPTER 5 Issuing SQL Statements Introduction passthrough mode sybase mode Transformations in sybase mode Standard transformations for T-SQL commands CHAPTER 6 Managing Transactions Transaction processing terms Request processing flow ODBC client API processing CT-Library client API processing Managing processing results Allocate configuration property StopCondition configuration property TransactionMode configuration property Resulting actions in transaction management Troubleshooting Tracing CHAPTER 7 Issuing RPC Events The RPC feature Creating and executing ASE remote stored procedures Executing a language statement as an RPC Rules for using language statements as RPCs Creating a transfer RPC event iv Enterprise Connect Data Access Option for ODBC

5 Contents Using triggers CHAPTER 8 Understanding the Transfer Process Overview Terms in the transfer process Transfer direction Unit of work as defined in the transfer process Transfer targets Datatype conversion for transfer processing How the transfer options process data Transfer errors Transfer errors and error handling Error reporting for transfer processing Controlling processing with the TransferErrorCount property. 97 CHAPTER 9 Using Bulk Copy Transfer and Express Transfer Overview Transfer process Syntax Express transfer Differences between bulk copy and express transfer Preparing to use express transfer Datatype conversion for express transfer statements Processing bulk copy values Character datatypes Numeric datatypes Date datatypes Binary datatypes Bulk copy and express transfer errors Bulk copy value processing rules Values that cause errors Bulk copy transfer error reporting CHAPTER 10 Using Destination-Template Transfer Overview Description of destination-template transfer processing Syntax Datatype qualifiers Special date and time qualifiers Destination-template processing transfer from statements transfer to statements Access Service Users Guide v

6 Contents Datatype conversion for transfer to statements Destination-template transfer errors Obtaining error information Creating a transfer RPC Executing a transfer RPC CHAPTER 11 Accessing Catalog Information with CSPs Description of CSPs Syntax RPC events Treatment of special characters ODBC information ODBC conformance levels Compatibility sp_column_privileges sp_columns sp_databases sp_datatype_info sp_fkeys sp_pkeys sp_server_info sp_special_columns sp_sproc_columns sp_statistics sp_stored_procedures sp_table_privileges sp_tables CHAPTER 12 Retrieving Information with System Procedures ECDA Option for ODBC and ASE system procedures sp_capabilities sp_configure sp_groups sp_helpserver sp_sqlgetinfo sp_thread_props sp_who APPENDIX A Configuration Quick Reference Table Quick reference table APPENDIX B Converting Datatypes vi Enterprise Connect Data Access Option for ODBC

7 Contents Limitations ODBC-to-Open Server datatypes Result set data value conversion Data values sent to the client application Open Server-to-ODBC datatypes Data values embedded as strings Data values received as parameters CS_DATAFMT usertype field values Datatype names Microsoft SQL Server ODBC-supported datatypes DB2 UDB / ODBC-supported datatypes APPENDIX C Using Stored Procedures Using SQL stored procedures Running SQL stored procedures Using DB2 stored procedures Running DB2 stored procedures APPENDIX D Using Sybase Mode Commands Transact-SQL commands alter table (core) begin transaction (T-SQL only) commit transaction (T-SQL only) create index (core) create table (minimum) create view (core) delete (minimum) delete (core) delete (minimum) drop index (core) drop table (minimum) drop view (core) execute grant (core) insert (minimum) prepare transaction revoke (core) rollback transaction select (minimum) truncate table (extension using where 1=1) update (core) update (core) update (core) Access Service Users Guide vii

8 Contents use Glossary Index viii Enterprise Connect Data Access Option for ODBC

9 About This Book This book describes how to configure and use an Enterprise Connect Data Access (ECDA) Option for ODBC access service, including datatype conversion, request processing, data transfer, and stored procedures. Audience This book is written for: Application Programmers, who develop programs for their organization using the major features of the ECDA Option for ODBC. System Administrators, who install and test ECDA Option for ODBC. When the ECDA Option for ODBC is running, System Administrators provide ongoing administration support, disaster recovery, and troubleshooting support. System Programmers, who install and test ECDA Option for ODBC, and provide product administration, troubleshooting, and disaster recovery. How to use this book This book covers the following topics: Chapter Chapter 1, Introducing Enterprise Connect Data Access Option for ODBC Chapter 2, Configuring the Access Service Library Chapter 3, Configuring Access Services to Work with Related Products Chapter 4, Querying and Setting Operating Values Chapter 6, Managing Transactions Topic Introduces the product and describes the components of ECDA Option for ODBC. Tells how to configure access service library and access service properties. Provides instructions for setting up the Component Integration Services functionality in Adaptive Server Enterprise (ASE/CIS) and Replication Server to use with a DirectConnect access service. Explains how to use global variables and set statements to query and set operating values for your client connections. Describes the transaction management processing flow and explains how to configure properties to manage the process. Access Service Users Guide ix

10 Chapter Chapter 5, Issuing SQL Statements Chapter 7, Issuing RPC Events Chapter 8, Understanding the Transfer Process Chapter 9, Using Bulk Copy Transfer and Express Transfer Chapter 10, Using Destination-Template Transfer Chapter 11, Accessing Catalog Information with CSPs Chapter 12, Retrieving Information with System Procedures Appendix A, Configuration Quick Reference Table Appendix B, Converting Datatypes Appendix C, Using Stored Procedures Appendix D, Using Sybase Mode Commands Topic Describes SQL transformation modes and standard transformations for SQL commands. Describes how to create, configure, and execute remote procedure calls (RPCs). Describes several concepts of the transfer process. Describes how to use bulk copy transfer, including syntax statements and error handling. Explains how to use destination-template transfer, including syntax statements and error handling. Provides a description and reference for supported catalog stored procedures (CSPs). Provides a description and reference for supported system procedures. Contains a quick reference table, with the configuration properties listed in alphabetical order. Describes datatype conversions between ODBC and Open Server. Describes SQL stored procedures and DB2 stored procedures, including rules for using them. Describes SQL commands that the ECDA Option for ODBC access service recognizes in sybase mode. Related documents To configure and administer Enterprise Connect Data Access products, use the following guides: Enterprise Connect Data Access Installation Guide for Linux and UNIX Enterprise Connect Data Access Installation Guide for Windows Enterprise Connect Data Access and Mainframe Connect Server Administration Guide For Open Database Connectivity (ODBC) information, use the following document: Microsoft ODBC 3.5 Programmer s Reference and SDK Guide x Enterprise Connect Data Access Option for ODBC

11 About This Book For additional references, use the following documents: Open Client and Open Server Common Libraries Reference Manual Open Client Client-Library/C Reference Manual Open Client Client-Library/C Programmers Guide Open Server Server-Library/C Reference Manual Software Developer s Kit and Open Server Installation Guide for Microsoft Windows and UNIX Component Integration Services Users Guide for Adaptive Server Enterprise and OmniConnect Adaptive Server Reference Manual, volumes 1 and 2 Note For detailed information about the ECDA Option for Oracle, see the Enterprise Connect Data Access Option for Oracle Server Administration and Users Guide. Other sources of information Use the Sybase Getting Started CD, the SyBooks CD, and the Sybase Product Manuals Web site to learn more about your product: The Getting Started CD contains release bulletins and installation guides in PDF format, and may also contain other documents or updated information not included on the SyBooks CD. It is included with your software. To read or print documents on the Getting Started CD, you need Adobe Acrobat Reader, which you can download at no charge from the Adobe Web site using a link provided on the CD. The SyBooks CD contains product manuals and is included with your software. The Eclipse-based SyBooks browser allows you to access the manuals in an easy-to-use, HTML-based format. Some documentation may be provided in PDF format, which you can access through the PDF directory on the SyBooks CD. To read or print the PDF files, you need Adobe Acrobat Reader. Refer to the SyBooks Installation Guide on the Getting Started CD, or the README.txt file on the SyBooks CD for instructions on installing and starting SyBooks. Access Service Users Guide xi

12 The Sybase Product Manuals Web site is an online version of the SyBooks CD that you can access using a standard Web browser. In addition to product manuals, you will find links to EBFs/Maintenance, Technical Documents, Case Management, Solved Cases, newsgroups, and the Sybase Developer Network. Sybase certifications on the Web To access the Sybase Product Manuals Web site, go to Product Manuals at Technical documentation at the Sybase Web site is updated frequently. Finding the latest information on product certifications 1 Point your Web browser to Technical Documents at 2 Click Certification Report. 3 In the Certification Report filter select a product, platform, and time frame and then click Go. 4 Click a Certification Report title to display the report. Finding the latest information on component certifications 1 Point your Web browser to Availability and Certification Reports at 2 Either select the product family and product under Search by Base Product; or select the platform and product under Search by Platform. 3 Select Search to display the availability and certification report for the selection. Creating a personalized view of the Sybase Web site (including support pages) Set up a MySybase profile. MySybase is a free service that allows you to create a personalized view of Sybase Web pages. 1 Point your Web browser to Technical Documents at 2 Click MySybase and create a MySybase profile. xii Enterprise Connect Data Access Option for ODBC

13 About This Book Sybase EBFs and software maintenance Style conventions Finding the latest information on EBFs and software maintenance 1 Point your Web browser to the Sybase Support Page at 2 Select EBFs/Maintenance. If prompted, enter your MySybase user name and password. 3 Select a product. 4 Specify a time frame and click Go. A list of EBF/Maintenance releases is displayed. Padlock icons indicate that you do not have download authorization for certain EBF/Maintenance releases because you are not registered as a Technical Support Contact. If you have not registered, but have valid information provided by your Sybase representative or through your support contract, click Edit Roles to add the Technical Support Contact role to your MySybase profile. 5 Click the Info icon to display the EBF/Maintenance report, or click the product description to download the software. This book uses the following style conventions: The names of files and directories are shown as: econnect\servers\servername\cfg The names of programs, utilities, procedures, and commands are shown as: the set statement The names of properties are shown as: Allocate The names of options are shown as: connect Code examples and text on screen are shown as: ** Prepare the statement. In a command line display, commands you should enter are shown as: Allocate=connect Access Service Users Guide xiii

14 In a sample command line display, variables (words you should replace with the appropriate value for your system) are shown as: ClientIdleTimeout=integer Syntax conventions Syntax statements that display options for a command look like this: sp_columns table_name [, table_owner] [, table_qualifier] [, column_name] The following table explains the syntax conventions used in this book. Table 1: Syntax conventions Symbol Convention ( ) Include parentheses as part of the command. { } Braces indicate that you must choose at least one of the enclosed options. Do not type the braces when you type the option. [ ] Brackets indicate that you can choose one or more of the enclosed options, or none. Do not type the brackets when you type the options. The vertical bar indicates that you can select only one of the options shown. Do not type the bar in your command., The comma indicates that you can choose one or more of the options shown. Separate each choice by using a comma as part of the command. Accessibility features This document is available in an HTML version that is specialized for accessibility. You can navigate the HTML with an adaptive technology such as a screen reader, or view it with a screen enlarger. ECDA 15.0 and the HTML documentation have been tested for compliance with U.S. government Section 508 Accessibility requirements. Documents that comply with Section 508 generally also meet non-u.s. accessibility guidelines, such as the World Wide Web Consortium (W3C) guidelines for Web sites. Note You might need to configure your accessibility tool for optimal use. Some screen readers pronounce text based on its case; for example, they pronounce ALL UPPERCASE TEXT as initials, and MixedCase Text as words. You might find it helpful to configure your tool to announce syntax conventions. Consult the documentation for your tool. For information about how Sybase supports accessibility, see Sybase Accessibility at The Sybase Accessibility site includes links to information on Section 508 and W3C standards. xiv Enterprise Connect Data Access Option for ODBC

15 About This Book If you need help For a Section 508 compliance statement for Enterprise Connect Data Access version 15.0, go to Voluntary Product Assessment Templates at Each Sybase installation that has purchased a support contract has one or more designated people who are authorized to contact Sybase Technical Support. If you cannot resolve a problem using the manuals or online help, please have the designated person contact Sybase Technical Support or the Sybase subsidiary in your area. Access Service Users Guide xv

16 xvi Enterprise Connect Data Access Option for ODBC

17 CHAPTER 1 Introducing Enterprise Connect Data Access Option for ODBC In Enterprise Connect Data Access (ECDA) version 15.0, the Option for DB2 UDB and the Option for Microsoft SQL Server have been merged into the ECDA Option for ODBC. In addition, the Option for Informix is no longer available. Topic Page ECDA Option for ODBC 1 Using DirectConnect Manager 5 Globalization 6 Note This Access Service Guide covers the ECDA Option for ODBC only. For information about the ECDA Option for Oracle, see the Enterprise Connect Data Access Option for Oracle Server Administration and Users Guide. ECDA Option for ODBC ECDA Option for ODBC is a Sybase solution that gives client applications ODBC data access. It combines the functionality of the ECDA Option for ODBC architecture with ODBC to provide dynamic SQL access to target data, as well as the ability to support stored procedures and text and image pointers The ECDA Option for ODBC provides access management, copy management, and remote systems management. It consists of: The DirectConnect server, which provides management and support functions for DirectConnect service libraries Access Service Users Guide 1

18 ECDA Option for ODBC An access service library, which accesses data from a particular target database, including DB2 UDB, Microsoft SQL Server, and other ODBCaccessible databases Access services, which contain specific sets of configuration properties relating to the target to be accessed and define how each access service behaves Using the IBM Distributed Relational Database Architecture (DRDA) protocol, ECDA Option for ODBC supports access to DB2 UDB on z/os, Windows, Linux, and UNIX platforms. For more information about ECDA architecture, see the Enterprise Connect Data Access Overview Guide. ODBC driver ECDA Option for ODBC provides basic connectivity to non-sybase data sources, using the ODBC back-end (server-side) driver that you purchase for your target database, such as IBM or Microsoft SQL. Following vendor s instructions, you install the ODBC driver on the same server as ECDA Option for ODBC and then configure ECDA Option for ODBC to use that ODBC driver for access to your database. Note Be sure to verify that your ODBC driver will be compatible with Sybase driver manager software. Because ODBC drivers have varying degrees of functionality, it is important that when working with non-sybase-provided, third-party ODBC drivers, you carefully integrate and test them to be sure they meet your needs. How DirectConnect server routes access service requests The DirectConnect server routes each client request for an access service to the appropriate access service library. The routing process can take one of two forms: Accessing the service directly, you specify the exact name of the access service. If the access service is defined correctly, the DirectConnect server matches the request with the access service. 2 Enterprise Connect Data Access Option for ODBC

19 CHAPTER 1 Introducing Enterprise Connect Data Access Option for ODBC Accessing the service with service name redirection, you can map your access service connections to allow client requests to be routed to assigned access services based upon user profiles. This feature allows you to centrally manage client access to access services. For information on access service name redirection and examples of how it works, see the Enterprise Connect Data Access Mainframe Connect Server Administration Guide. Configuring properties for ECDA Option for ODBC You can configure ECDA Option for ODBC properties on the server level, the access service library level, or on an individual access service level. To help you do this, configuration properties are grouped as follows: Server configuration files, which consist of the properties that manage a particular DirectConnect server. Access service library configuration files, which consist of general library configuration values and configuration sets for all access services associated with a particular access service library. Access service configuration properties, which define a particular access service and are stored in the access service library configuration file. When you install a DirectConnect server, the default configurations allow the server to run. For each access service you create within each server, you must provide additional configuration properties that define the connectivity to your target database system. For information on configuring the DirectConnect server, see the Enterprise Connect Data Access and Mainframe Connect Server Administration Guide. You can set access services to be enabled at start-up through a configuration setting. If this value is set to no, then you need to manually enable the access service before it can be used. For information on configuring access service libraries and access services, including instructions on creating new access services, see the Users Guide for Access Services for your database system. You can configure properties using DirectConnect Manager or a text editor. Sybase recommends using DirectConnect Manager for these reasons: Changes that you make with a text editor do not take effect until you restart the server. However, most changes that you make with DirectConnect Manager can be made to take effect immediately. Access Service Users Guide 3

20 ECDA Option for ODBC You can use DirectConnect Manager as a guide to the properties that can be changed, as well as the valid values for each property. For more information, see Using DirectConnect Manager, in this chapter. Server external files License file Log file Server configuration file Access service library files Access service library configuration file The DirectConnect server manages external files that reside in various subdirectories. For information on the ECDA Option for ODBC directory structure for your installation, see the appropriate installation guide for your database system and platform. Following are brief descriptions of the server-managed external files. The license file contains licensing information entered by the client for the products and features that are being used. This site-specific file contains descriptions of server nodes that can run the license daemons, various vendor daemons, and licenses for the features and the supported products. The log file is an active log file that contains operational information that you can use to correct problems. Although the file is maintained in U.S. English, any logged client messages appear in the client language. The log file resides in the server log subdirectory. For more information, see Logging properties in Chapter 2, Configuring the Access Service Library. The server configuration file server.cfg contains all server configuration information. It resides in the server cfg subdirectory. For more information on server configuration, refer to the Enterprise Connect Data Access and Mainframe Connect Server Administration Guide. This dynamically-loaded shared library represents each access service library. The DirectConnect server identifies the library by the file name. To install, load, or access a library, verify that the executable file for that library exists in the server <install_dir>/dc-15_0/svclib subdirectory for UNIX, or the C:\<install_dir>\DC-15_0\svclib subdirectory for Windows. This file contains information for the access service library and all of its access services. Each access service library has a configuration collection. The server defines the file format, but each configuration property is defined by the access service library, regardless of whether the property is managed at the access service library or the access service level. The configuration files reside in the server cfg subdirectory. For information on configuring access service library properties, see the appropriate Access Service Guide for your database system. 4 Enterprise Connect Data Access Option for ODBC

21 CHAPTER 1 Introducing Enterprise Connect Data Access Option for ODBC Service name redirection file Trace file This optional file contains all information necessary to redirect incoming requests for access service names to other access services. The file resides in the server cfg subdirectory. For more information, see Chapter 6, Using Service Name Redirection, in the Enterprise Connect Data Access and Mainframe Connect Server Administration Guide. This file is the only active trace file for the system and it provides debugging information for Sybase Product Support Engineers and Technical Support personnel. You can turn it on and off through server configuration. Although the trace file is maintained in U.S. English, any logged client messages appear in the client language. The trace file resides in the log subdirectory. For tracing information, see Tracing properties in Chapter 2, Configuring the Access Service Library. Using DirectConnect Manager DirectConnect Manager graphically represents each DirectConnect object on a tree list or an icon map, a customizable workspace where you can add or remove objects. When you add a DirectConnect server to DirectConnect Manager, its server name, access service library, and any access services appear on the tree list or the icon map. DirectConnect Manager graphically represents each DirectConnect object on a tree list or an icon map, a customizable workspace where you can add or remove objects. When you add a DirectConnect server to DirectConnect Manager, its server name, access service library, and any access services appear on the tree list or the icon map. DirectConnect Manager communicates with DirectConnect servers asynchronously, which means you can continue to use DirectConnect Manager while a command is being processed. You can configure properties using DirectConnect Manager or a text editor. However, Sybase recommends using DirectConnect Manager for these reasons: Changes that you make with a text editor do not take effect until you restart the server. Most changes that you make with DirectConnect Manager can be made to take effect immediately. Access Service Users Guide 5

22 Globalization You can use DirectConnect Manager as a guide to the properties that can be changed, as well as the valid values for each property. DirectConnect Manager can perform all of its management functions remotely. With DirectConnect Manager, you do not need physical access to the DirectConnect server machine or directory. DirectConnect Manager provides management services to multiple servers at the same time, including the ability to copy access service configurations from one server to another. For more information about DirectConnect Manager features, use the DirectConnect Help available under the online Help menu option. You can install DirectConnect Manager and its required components from the DC Client CD. Note When you install a DirectConnect product on a Windows or UNIX platform or machine, you may install DirectConnect Manager on a separate platform or machine. This allows you to control any ECDA product from any machine. Globalization Globalization consists of internationalization and localization of messages. Internationalization Internationalization consists of character code set conversion and cultural formatting: Code set conversion involves converting the hexadecimal representation of a character from a code set in a target database to a code set in a client application, or the reverse. Cultural formatting involves designating decimal separators, monetary signs, date and time separators, and a 3-digit grouping symbol. Cultural formatting in DirectConnect is performed through the use of configuration properties. 6 Enterprise Connect Data Access Option for ODBC

23 CHAPTER 1 Introducing Enterprise Connect Data Access Option for ODBC Code page translation For ODBC-based products, code page translation can take place in two locations: Between the DirectConnect server and the target database Between the client and the DirectConnect server For more information about code page translation, refer to Chapter 2, Configuring the Access Service Library. Localization Two sets of messages can be localized: Messages generated by the target database manager and passed to the client application without change The target database manager can be any application between the DirectConnect server and the target data file, including the ODBC driver. Messages generated in ECDA Option for ODBC ECDA Option for ODBC does not localize database manager messages. For information on how to set up localization of such messages, see your database manager and the ODBC driver documentation.l. Access Service Users Guide 7

24 Globalization 8 Enterprise Connect Data Access Option for ODBC

25 CHAPTER 2 Configuring the Access Service Library Topic Page Understanding the configuration process 9 How to change configuration property values 14 How to create additional services 15 Code page translation for ODBC-based products 16 Configuration property categories 17 For an alphabetized list of all configuration properties, see Appendix A, Configuration Quick Reference Table. Understanding the configuration process The sections in this chapter describe how to configure properties to customize the access service library and the individual access services for the ECDA Option for ODBC, which includes DB2 UDB, Microsoft SQL Server, and ODBC-accessible database servers. To create additional access services and to edit, configure, and change existing properties in the access service library configuration file, use either one of these two methods: Use DirectConnect Manager to modify the access service library configuration file and dynamically change the properties without stopping and starting the server, or Access Service Users Guide 9

26 Understanding the configuration process Use a line text editor to edit the access service library configuration file that resides on the DirectConnect server. Upon completion, you must stop and restart the server for the changes to take effect. Note For convenience, Sybase recommends using DirectConnect Manager to modify the access service configuration file. For information about using DirectConnect Manager, see the DirectConnect Manager online help. The access service library uses some configuration information from the DirectConnect server. For details, see the Enterprise Connect Data Access and Mainframe Connect Server Administration Guide. Description of the configuration file Use DirectConnect Manager or your text editor to modify and save the configuration file named dcany.cfg. Configuration files are defined in this section for ECDA Option for ODBC. To find the location of the configuration file within the ECDA Option for ODBC directory structure, see the ECDA Option for ODBC installation guides for Windows or UNIX. Configuration file format An access service library configuration file consists of: A primary section [Service Library] that groups access service library properties. The name is hard-coded and cannot be changed. Access service sections [Service Name], shown in brackets. Subsections {Subsection Name}, shown in braces. Subsections group the properties by type. Configuration properties and values. You can include comments. Enter each comment on a separate line and begin with a semicolon or the # symbol in column one. 10 Enterprise Connect Data Access Option for ODBC

27 CHAPTER 2 Configuring the Access Service Library Configuration properties Each access service has a specific set of configuration properties. To configure an access service: Enter site-specific values for all required properties. For non-required properties, enter only the values that differ from the default values. These principles apply to properties: Server properties apply to all access services created for that server. Service library properties apply to the service library. Access service properties apply to specific access services. Note Configuration properties are not case sensitive. Configuration file templates The following templates for ECDA targets show all of the configuration properties, organized as they appear in the configuration file layout. Use these templates to set up your configuration file. Note In this template, two required properties have entries for ODBC data targets: ConnectionSpec1 and EnableAtStartup. For guidelines on configuring these properties, see Configuration property categories on page 17. [Service Library] {Client Interaction} ODBCDriverManager= SvclibDescription= {Logging} LogSvcLibStatistics= [Service Name] {ACS Required} ConnectionSpec1=ODBCDataSource {Catalog Stored Procedures} CSPColumnODBCVersion= CSPExclusions= Access Service Users Guide 11

28 Understanding the configuration process CSPIncludeAlias= CSPIncludeSynonym= CSPIncludeSystem= CSPIncludeTable= CSPIncludeView= DatatypeInfo= {Client Interaction} ClientDecimalSeparator= ClientIdleTimeout= EnableAtStartup= MaxResultSize= MaxRowsReturned= MaxSvcConnections= quoted_identifiers= SendWarningMessages= ServiceDescription= StripBinaryZero= StripString=TextSize= TextSize= TransactionMode= Version= {Data Conversion Errors} CharConvertError= DateTimeConvertError= DefaultDate= DefaultNum= DefaultTime= NumConvertError= {Datatype Conversion} BinaryResults= DateResults= DateTimeResults= DecimalResults= FloatResults= Int2Results= Int4results= RealResults= TimeResults= TinyIntResults= XNLChar= XNLVarChar= {Logging} LogConnectionStatistics= LogReceivedSQL= 12 Enterprise Connect Data Access Option for ODBC

29 CHAPTER 2 Configuring the Access Service Library LogRequestStatistics= LogServiceStatistics= LogTargetActivity= LogTransferStatistics= LogTransformedSQL= {Target Interaction} Allocate= DelimitSQLRequests= DisableROLock= IsolationLevel= QuotedStringDelimeter= ReturnNativeError= SQLOdbcCursors= SQLTransformation= StopCondition= TargetDBMS= TargetDecimalSeparator= {Tracing} TraceEvents= TraceInterface= TraceTarget= {Transfer} BulkCommitCount= TransferBatch= TransferBatchSeparator= TransferErrorAction= TransferErrorCount= TransferExpress= TransferPacketSize= Access Service Users Guide 13

30 How to change configuration property values How to change configuration property values Although most access service configuration property values have default values, you will need to change some configuration property values for your site. You can change property values either by using DirectConnect Manager or by editing the text file. Using DirectConnect Manager For instructions on how to use DirectConnect Manager to edit the access service configuration file (dcany.cfg), go to the Managing Access Services topic of DirectConnect Manager online help and select Modifying access service configuration properties. Note Before you can use DirectConnect Manager to update the access service properties, you must have installed DirectConnect Manager as outlined in the installation guide for your platform. Also, you must identify and establish a connection between the DirectConnect server and DirectConnect Manager. This is described in a DirectConnect Manager online help topic, Connecting DirectConnect Manager to a DirectConnect Server. For additional information, use the verbose mode that is available with DirectConnect Manager. Using the text editor This procedure tells you how to change configuration properties using the text editor. To edit the configuration with a text editor 1 Locate and open the access service library configuration file dcany.cfg. 2 Update the service library configuration properties as needed. 3 Open the access service file server.cfg and change the access service property values as needed. List each property and value under the appropriate subsection. If the subsection is not shown, you must add it. 4 Save the file. 14 Enterprise Connect Data Access Option for ODBC

31 CHAPTER 2 Configuring the Access Service Library 5 Stop the server, and then restart it to implement the changes. How to create additional services Guidelines for access service names You can create additional access services the same way you change existing access services, either by using the text editor or by using DirectConnect Manager. Access service names must conform to these rules: Service names must be unique (without regard to case). Service names must not exceed 31 characters for Windows or UNIX operating systems. The initial character must be an alphabetic character (a z, A Z); subsequent characters can be alphabetic characters, numbers, or the underscore (_) character. Using DirectConnect Manager For instructions on how to use DirectConnect Manager to create a service, go to the Managing Access Services topic of the DirectConnect Manager online help and select Creating a new service or Copying a service. Using the text editor To create a service or additional services 1 Open the Access Service Library configuration file dcany.cfg. 2 Create a section for each new service and then add: The service name, in brackets Required properties below the service name, grouped in the {ACS Required} subsection Property value overrides listed below the service name, grouped by subsection 3 Save the file. Access Service Users Guide 15

32 Code page translation for ODBC-based products 4 Stop the server, and then restart it to implement the changes. 5 Enable a client machine to connect to a new access service. Enter the access service name in the sql.ini configuration file on Windows NT machines or the interfaces file on UNIX client machines. For instructions about editing the sql.ini or interfaces file, see the Enterprise Connect Data Access Installation Guide for UNIX and the Enterprise Connect Data Access Installation Guide for Microsoft Windows. Note If you choose to use service name redirection, make an assigned service name entry in the service name redirection file. For more information, see the Enterprise Connect Data Access and Mainframe Connect Server Administration Guide. For detailed information about configuration properties, see the section called Configuration property categories on page 17. Code page translation for ODBC-based products Code page translation between the DirectConnect server and the target database ODBC drivers incorporate code page translation within their normal data processing. The ECDA Option for ODBC uses this functionality to simplify code page translation. For ODBC-based products, code page translation can take place in two locations: Between the DirectConnect server and the target database Between the client and DirectConnect server The ODBC driver uses the server-platform-configured code page value as its client code page. Depending on the platform, the server-platform-configured code page value can be found: For Windows, in the Windows registry ACP value. To locate the value, use the registry editor called regedit to navigate through the registry tree to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\NIs\Co depage, which represents the platform s ODBC code page. On the right panel, scroll to the ACP value. 16 Enterprise Connect Data Access Option for ODBC

33 CHAPTER 2 Configuring the Access Service Library Code page translation between the client and the DirectConnect server For Linux and UNIX, you can use the locale command to determine the operating system, the platform, and ODBC code page value. Upon connection to the target, the ODBC driver queries the target database for its code page and compares the value to the server-platform-configured code page: If the values are not equal, the ODBC driver translates from the serverplatform code page to the target code page. If the values are equal, the ODBC driver does not perform any translation. As an Open Server API, the ECDA Option for ODBC relies on Open Server for datatype conversion. For proper code page translation, the ECDA code page identified by Open Server must match the server-platform-configured code page value. The default platform in the locales.dat configuration file identifies the Open Server code page. The DirectConnect server configuration property called OSCodeSetConvert determines whether the ECDA Option for ODBC allows Open Server to perform code page translation between the client and the DirectConnect server. Values for the OSCodeSetConvert property are: Yes indicates that the DirectConnect server will perform code page translation. No indicates that the DirectConnect server will not perform any code page translation. Configuration property categories The following sections describe by property category; property, syntax, range, default values, acceptable values, and comments: Service library properties ACS Required property Catalog Stored Procedures properties Client Interaction properties Data Conversion Error properties Datatype Conversion properties Access Service Users Guide 17

34 Configuration property categories Logging properties Target Interaction properties Tracing properties Transfer properties See Appendix A, Configuration Quick Reference Table, for an alphabetized listing of all configuration properties within the service library for ECDA Option for ODBC. Service library properties These properties pertain to the service library and all of its services. {Client Interaction} ODBCDriverManager= SvclibDescription= {Logging} LogSvcLibStatistics= ODBCDriverManager {Client Interaction} (UNIX only) Specifies the full path name to the ODBCDriverManager access service library. Syntax ODBCDriverManager=ODBC Driver Manager library where ODBC Driver Manager library is the full path name to the ODBC driver manager library. Note Enter the library name with the full path; otherwise, the program must search the entire library for the correct driver manager library. Range Values String value up to 255 characters. Default values are the names the unixodbc driver manager installed with the product (found by the library path): libodbc.so (Solaris, Linux) libobdc.sl.1.0. (HP) libodbc.so.1 (AIX) 18 Enterprise Connect Data Access Option for ODBC

35 CHAPTER 2 Configuring the Access Service Library Comment The driver manager library uses a generic name, libdodbc.lib_ext. The ODBCDriverManager configuration property defaults to the unixodbc driver manager version name, libodbc.lib_ext.x, which makes it possible to place the unixodbc driver manager library in the DC-15_0/lib directory already located in the library path. SvclibDescription {Client Interaction} Describes the access service library. This property applies to a description of the access service library. Syntax Range Default Comment SvclibDescription=char characters None This property allows you to place descriptive information about the access service library in the configuration file. LogSvcLibStatistics {Logging} Specifies how often the access service library records accumulated statistics about connection requests to all access services associated with this access service library during the reporting interval. This is an access service library property that applies to the access service library as a whole. Syntax LogSvclibStatistics=integer Range Default 0 (zero) Values integer is a number of seconds. A value of 0 specifies that the access service library does not record statistics in the server log file. Comments Use this property to: Monitor load on the entire access service library Monitor load on the target database through the DirectConnect server Access Service Users Guide 19

36 Configuration property categories If you enable both LogSvclibStatistics (service library level) and LogServiceStatistics (service level) properties, Sybase recommends that you set the LogSvclibStatistics property to the same property value as the LogServiceStatistics or a multiple thereof. If you use DirectConnect Manager to change these two property values, set the LogSvclibStatistics property last for better synchronization. If the LogSvclibStatistics property value is greater than 0 (zero), the ECDA Option for ODBC records totals of the statistics for all access services in the access service library. For a list of recorded statistics data, see Table 2-2 on page 41. ACS Required property This property requires site-specific values. Be sure to supply this value for your installation. The subsection heading and the name of the property must appear in the access service library configuration file as shown: {ACS Required} ConnectionSpec1= ConnectionSpec1 Syntax Range Default Value Specifies an ODBC data source name (DSN) defined in the ODBC system information file. In Windows systems, the data sources are defined using the ODBC Administrator. In UNIX systems, the data sources are defined in an odbc.ini file. ConnectionSpec1=char characters None char is a valid data source name configured in the odbc.ini file. 20 Enterprise Connect Data Access Option for ODBC

37 CHAPTER 2 Configuring the Access Service Library Catalog Stored Procedures properties These properties control the information an access service returns from catalog stored procedures (CSPs). Note Many of the properties in this group are not supported, nor do they affect the access service. These properties are available for compatibility purposes only. The subsection heading and a list of the properties must appear in the access service library configuration file as shown: {Catalog Stored Procedures} CSPColumnODBCVersion= CSPExclusions= CSPIncludeAlias= CSPIncludeSynonym= CSPIncludeSystem= CSPIncludeTable= CSPIncludeView= DatatypeInfo= CSPColumnODBCVersion Specifies the ODBC version that catalog stored procedures results conform to. This affects interoperability with ASE/CIS. Syntax CSPColumnODBC Version = [ 2 3 ] Default 3 Values 2 specifies ASE/CIS version specifies ASE/CIS version 12.5 and later. Comment This property affects interoperability with ASE/CIS. This error might occur: Error column type mismatch in remote object when executing create existing table command to MSSQL server 2000SP 2. If it does, change the value from the default value to 2. Access Service Users Guide 21

38 Configuration property categories CSPExclusions Specifies an access service to limit access to information normally returned from sp_tables upon authorization. Syntax CSPExclusions=[ none user nonauth nonauthpublic ] Default user Values none specifies no exclusions, based upon authorization to information. user specifies exclusions, based upon specific user authorization to information. nonauth specifies that a user must be granted user or group authorization to access information. nonauthpublic specifies that a user must be granted user authorization, or that PUBLIC is granted some authorization. Comment This property is not supported and does not affect the ECDA Option for ODBC access service. It is available for compatibility purposes only. CSPIncludeAlias Syntax Default Specifies the access service to return information about aliases from sp_tables. no CSPIncludeAlias=[no yes] Values no specifies that the access service does not return alias information. yes specifies that the access service returns alias information. Comment This property is not supported and does not affect the ECDA Option for ODBC access service. It is available for compatibility purposes only. CSPIncludeSynonym Specifies the access service to return information about synonyms from sp_tables. Syntax Default no CSPIncludeSynonym=[no yes] Values no specifies the access service not to return synonym information. yes specifies the access service to return synonym information. 22 Enterprise Connect Data Access Option for ODBC