Diagnsis and Trubleshting DataDirect Cnnect Series ODBC Drivers Intrductin This paper discusses the diagnstic tls that are available t cnfigure and trublesht yur ODBC envirnment and prvides a trubleshting sectin that discusses sme cmmn types f issues that yu may experience when using ODBC applicatins. These tls and techniques apply t bth the DataDirect Cnnect fr ODBC (32-bit) and DataDirect Cnnect64 fr ODBC (64-bit) drivers. Further infrmatin n these tpics can be fund in the prduct dcumentatin at: http://www.datadirect.cm/dwnlad/dcs/dchme/index.ssp Diagnstic Tls This sectin discusses the diagnstic tls that are available t yu when yu are cnfiguring and trubleshting yur ODBC envirnment fr DataDirect Cnnect fr ODBC and DataDirect Cnnect64 fr ODBC. ODBC Trace ODBC tracing allws yu t trace calls t ODBC drivers and create a lg f the traces. Creating a trace lg is particularly useful when yu are trubleshting an issue. T create a trace lg, turn n tracing, start the ODBC applicatin, reprduce the issue, stp the applicatin, and turn ff tracing. Then, pen the lg file in a text editr and review the utput t help yu debug the prblem. Be sure t turn ff tracing when yu are finished reprducing the issue because tracing decreases the perfrmance f yur ODBC applicatin. Fr a mre thrugh explanatin f tracing, see the fllwing DataDirect Knwledgebase dcument: http://knwledgebase.datadirect.cm/kbase.nsf/ SupprtLink+Online/2549739SL Enabling Tracing On Windws, yu enable tracing by clicking the Start Tracing buttn n the Tracing tab f the ODBC Administratr. Yu can als specify the name and lcatin f the trace lg n this tab.
On UNIX and Linux, the [ODBC] sectin in the system infrmatin file must include the keywrds Trace and TraceFile. Fr example: Trace=1 TraceFile=\hme\user\dbctrace.ut In this example, tracing is enabled and trace infrmatin is lgged in a file named dbctrace.ut. Althugh a path t the trace lg is shwn in the example, it is nt required. T disable tracing, set the Trace value t 0. ivtestlib Tl The ivtestlib tl (ddtestlib n DataDirect Cnnect64 and Cnnect64 XE fr ODBC) is prvided t help diagnse cnfiguratin prblems in the UNIX and Linux envirnments (such as envirnment variables nt crrectly set r missing database client cmpnents). This tl is installed in the bin subdirectry in the DataDirect prduct installatin directry, fr example, /pt/dbc/bin. The tl attempts t lad a specified ODBC driver and prints ut all available errr infrmatin if the lad fails. On Slaris, fr example, if drivers are installed in /pt/dbc/lib, the cmmand: ivtestlib /pt/dbc/lib/ddivraxx.s attempts t lad the Oracle Wire Prtcl driver, where xx is the driver level number. If the driver cannt be laded, ivtestlib returns an errr message explaining why. NOTE: On Slaris, AIX, and Linux, the full path t the driver des nt have t be specified fr ivtestlib. The HP-UX versin f ivtestlib, hwever, requires the full path. Yu can use ivtestlib t check the versin strings f the ODBC drivers and Driver Manager n UNIX and Linux. Use the fllwing cmmand line: ivtestlib shared_bject Lading the 5.1 versin f the Oracle Wire Prtcl driver: ivtestlib ivra21.s might, fr example, return 5.1.0001 (B0001, U0002) Lading the 5.1 versin f the Driver Manager n Slaris: ivtestlib libdbc.s might, fr example, return 5.1.0001 (U0001) 2 OF 7 DATADIRECT TECHNOLOGIES J ULY 2005
ODBC Test On Windws, Micrsft ships alng with their ODBC SDK an ODBCenabled applicatin, named ODBC Test, that yu can use t test ODBC drivers and the ODBC Driver Manager. ODBC 3.51 includes bth ANSI and Unicde-enabled versins f ODBC Test. T use ODBC Test, yu must understand the ODBC API, the C language, and SQL. Fr mre infrmatin abut ODBC Test, see the Micrsft ODBC SDK Guide. demdbc Applicatin The prduct is shipped with a small C applicatin, demdbc, n UNIX and Linux that is useful fr: Executing SELECT * FROM emp, where EMP is a database table (ne fr each supprted database) that is prvided with the prduct. The scripts fr building the EMP database tables are in the dem subdirectry in the prduct installatin directry. Testing database cnnectins. Creating reprducibles. Persisting data t an XML data file. Demdbc is installed in the dem subdirectry in the prduct installatin directry. See the readme in the dem directry fr an explanatin f hw t build and use this applicatin. example Applicatin The prduct is shipped with a small C applicatin, named example, n Windws and UNIX/Linux that is useful fr: Executing any type f SQL statement Testing database cnnectins Testing SQL statements Verifying yur database envirnment Example is installed in the example subdirectry in the prduct installatin directry. See the readme in the example directry fr an explanatin f hw t build and use this applicatin. DATADIRECT TECHNOLOGIES J ULY 2005 3 OF 7
Other Tls The DataDirect Technlgies Supprt Web site prvides ther diagnstic tls that yu can dwnlad t assist yu with trubleshting. These tls are nt shipped with the prduct. See the DataDirect Web page: http://www.datadirect.cm/supprt/dwnlads/tls/index.ssp DataDirect Technlgies als prvides a knwledge base that is useful in trubleshting prblems. See the DataDirect Knwledgebase page: http://knwledgebase.datadirect.cm/ Trubleshting When yu are having an issue while using a DataDirect Cnnect Series ODBC prduct, the first thing t d is determine the type f issue that yu are seeing: Setup/cnnectin Interperability (ODBC applicatin, ODBC driver, ODBC Driver Manager, and/r data surce) This sectin describes these tw types f issues, prvides sme typical causes f the issues and, in sme cases, explains pssible actins yu can take t reslve the issues. Setup/Cnnectin Issues Yu are experiencing a setup/cnnectin issue if yu are encuntering an errr r hang while yu are trying t make a database cnnectin with the ODBC driver r are trying t cnfigure the ODBC driver. Sme cmmn errrs that are returned by the ODBC driver if yu are experiencing a setup/cnnectin issue are: Specified driver culd nt be laded Data surce name nt fund and n default driver specified Cannt pen share library: libdbc.sl ORA-12203: Unable t cnnect t destinatin ORA-01017: invalid username/passwrd; lgn denied 4 OF 7 DATADIRECT TECHNOLOGIES J ULY 2005
Trubleshting the Issue Sme cmmn reasns that setup/cnnectin issues ccur are: The library path envirnment variable is nt set crrectly fr the ODBC drivers: PATH n Windws LD_LIBRARY_PATH n Slaris and Linux SHLIB_PATH n HP-UX (32-bit) LD_LIBRARY_PATH HP-UX (64-bit) LIBPATH n AIX The ODBCINI envirnment variable is nt set crrectly fr the ODBC drivers n UNIX and Linux. The ODBC driver s cnnectin attributes are nt set crrectly in the system infrmatin file (dbc.ini in mst cases) n UNIX and Linux. Fr example, the hst name r prt number are nt crrectly cnfigured. See each individual driver chapter in the DataDirect prduct dcumentatin fr a list f cnnectin string attributes that are required fr each driver t cnnect prperly t the underlying database. The database and/r listener are nt started. Fr UNIX and Linux users, see ivtestlib Tl in the Diagnstic Tls sectin. Interperability Issues Interperability issues ccur when yu have a wrking ODBC applicatin in place. In these cases, the issue ccurs in ne r mre f the fllwing cmpnents f ODBC the ODBC applicatin, ODBC driver, ODBC Driver Manager, and/r data surce. Sme cmmn examples f what yu might experience if yu have an interperability issue are: SQL statements fail t execute Data is returned/updated/deleted/inserted incrrectly A hang r cre dump Trubleshting the Issue When yu experience an interperability issue, yu must islate the cmpnent in which the issue is ccurring. Is it an ODBC applicatin, an ODBC driver, an ODBC Driver Manager, r a data surce issue? DATADIRECT TECHNOLOGIES J ULY 2005 5 OF 7
The first step First, test t see if yur ODBC applicatin is the surce f the prblem. T d this, replace yur ODBC applicatin with a smaller, simpler applicatin. If yu can reprduce the issue using a simpler ODBC applicatin, then yu knw yur ODBC applicatin is nt the cause f the issue. On Windws, yu can use ODBC Test, which is part f the Micrsft ODBC SDK, r the example applicatin that is shipped with yur DataDirect prduct. On UNIX and Linux, yu can use the example applicatin. See example Applicatin in the Diagnstic Tls sectin The secnd step Secnd, test t see if the data surce is the surce f the prblem. T d this, use the native database tls that are prvided by yur database vendr. The third step If yu find that neither the ODBC applicatin nr the data surce is the surce f yur prblem, yu then can trublesht the ODBC driver and the ODBC Driver Manager. In this case, we recmmend that yu create an ODBC trace lg s that yu can prvide this t DataDirect technical supprt. See ODBC Trace in the Diagnstic Tls sectin fr details. Summary DataDirect Technlgies prvides a number f diagnstic tls that are available t cnfigure and trublesht yur ODBC envirnment, and prvides dcumentatin that discusses sme cmmn types f issues that yu may experience when using ODBC applicatins. This paper gives an verview f these tls and issues, but further infrmatin n these tpics can be fund in the prduct dcumentatin at: http://www.datadirect.cm/dwnlad/dcs/dchme/index.ssp We welcme yur feedback! Please send any cmments cncerning dcumentatin, including suggestins fr ther tpics that yu wuld like t see, t: dcgrup@datadirect.cm 6 OF 7 DATADIRECT TECHNOLOGIES J ULY 2005
FOR MORE INFORMATION 800-876-3101 Wrldwide Sales Belgium (French)...0800 12 045 Belgium (Dutch)...0800 12 046 France...0800 911 454 Germany...0800 181 78 76 Japan...0120.20.9613 Netherlands...0800 022 0524 United Kingdm...0800 169 19 07 United States...800 876 3101 Cpyright 2005 DataDirect Technlgies Crp. All rights reserved. DataDirect Cnnect is a registered trademark f DataDirect Technlgies Crp. in the United States and ther cuntries. DataDirect XQuery is a trademark f DataDirect Technlgies Crp. in the U.S. and ther cuntries. Java and all Java based trademarks and lgs are trademarks r registered trademarks f Sun Micrsystems, Inc. in the United States and ther cuntries. Other cmpany r prduct names mentined herein may be trademarks r registered trademarks f their respective cmpanies. DataDirect Technlgies is fcused n standards-based data cnnectivity, enabling sftware develpers t quickly develp and deply business applicatins acrss all majr databases and platfrms. DataDirect Technlgies ffers the mst cmprehensive, prven line f data cnnectivity cmpnents available anywhere. Develpers wrldwide at mre than 250 leading independent sftware vendrs and thusands f crprate IT departments rely n DataDirect prducts t cnnect their applicatins t an unparalleled range f data surces using standards-based interfaces such as ODBC, JDBC and ADO.NET. Develpers als depend n DataDirect t radically simplify cmplex data integratin prjects using XML prducts based n the emerging XQuery and XQJ standards. DataDirect Technlgies is an perating cmpany f Prgress Sftware Crpratin (Nasdaq: PRGS), a US$300+ millin glbal sftware industry leader. Headquartered in Bedfrd, Mass., DataDirect Technlgies can be reached n the Web at http://www.datadirect.cm r by phne at +1-800-876-3101. DATADIRECT TECHNOLOGIES J ULY 2005 7 OF 7