Transcription
Troubleshooting and Technical Support
Copyright and Trademark InformationThe information in this document is subject to change without notice.Copyright 2001 Extended Systems Incorporated. All rights reserved.This document refers to numerous products by their trade names. The Advantage DatabaseServer is a product of Extended Systems Incorporated. Advantage is a trademark of ExtendedSystems Incorporated. All other designations are trademarks or registered trademarks oftheir respective companies.Extended Systems Inc. 5777 N. Meeker Avenue Boise, Idaho 83713 U.S.A.ii
ContentsChapter 1Troubleshooting . 1Advantage Troubleshooting Tools . 1Non-Advantage Troubleshooting Tools . 3Error and Diagnostic Logs . 4Automatic Version Checking. 4Avoiding ANSI Collation Mismatch Errors . 4Avoiding OEM Collation Mismatch Errors. 5Troubleshooting in the NetWare Environment. 6Troubleshooting in the Windows NT/2000 Environment . 8Troubleshooting in the Linux/Unix Environment . 10Troubleshooting in the Windows 95/98/ME Environment. 11Installation of the Advantage ODBC Driver . 13Advantage CA-Visual Objects RDD Error Object . 13Advantage CA-Visual Objects RDD General Protection Faults. 14Advantage CA-Visual Objects RDD Run Time Problems. 14Troubleshooting Advantage Internet Server . 15Chapter 2Technical Support . 16Technical Support (U.S. and Canada). 16www.AdvantageDatabase.com. 17Chapter 3Networking Issues . 18Networking Protocols Used by the Advantage Database Server . 18Advantage Database Server Discovery. 19Advantage Client Communication Layer . 22Advantage Communication Transport Layer . 23Advantage Communications Troubleshooting . 24Workstation Configuration. 27Glossary of Terms. 30iii
Chapter 1TroubleshootingAdvantage Troubleshooting ToolsThe following tools will help assist in product development and troubleshooting.Advantage Data Architect (ARC32.EXE)This data management tool provides an interface for common table management tasks and manyother useful features. Some of the functionality of this tool include: Complete data management functionality such as table creation, restructuring, indexing,packing, etc. Importing and converting other table types such as Paradox and Access tables. Testing filter expressions to determine the level at which they will be optimized. Testing Advantage StreamlineSQL queries. Testing ODBC SQL queries. Environment checking which can be used to test and diagnose connection issues with theAdvantage Database Server. Checking server activity with the built in Advantage Management utility. With thisfunctionality, you can verify that files are actually opened by the Advantage Database Server.You can also remotely determine which index files are opened, which users are connected,what installation parameters where selected, what files or records are locked, and how manytransactions are in progress. Creating aliases. An alias configuration utility is included in the Advantage Data Architect.This functionality in ARC allows you to set up aliases similar to Delphi database aliases. Creating queries using a built in visual query designer16MODMAN.EXE and 32MODMAN.EXEThe Modman utilities are used to show which DLLs are being loaded by currently runningexecutables. This is useful in determining if the intended DLL is being loaded, or if a DLL is beingloaded from an unexpectedly directory which may cause unexpected behavior or versionmismatch errors.1
ADSVER.EXEThe installation of the Advantage Database Server includes a file called ADSVER.EXE. This canbe used to determine the version of Advantage that is linked into a CA-Clipper application, theversion of an Advantage client DLL, Library, or RDD, or the version of an Advantage DatabaseServer NLM, EXE, or DLL.TEST43.EXEWhen comparing the performance of Advantage with another driver, it's important to realize thatAdvantage will always read a record's contents across the network when you skip to it, because itassumes that you have moved to it for a reason. Other drivers may only change the position ofthe record pointer, so performance comparisons will be misleading. TEST43.EXE is a CA-Clipperapplication that demonstrates a simple example of how to do an accurate performance test.Readme and Help DocumentationDocumentation for all Advantage products is continuously being improved with each new release.Always check the latest Readme and Help documentation for the most up to date information.Advantage Internet Server DemoThe AIS demo can be used to demonstrate the Advantage Internet Server to your customers fromanywhere in the world, since it will connect to an Advantage Database Server here at ExtendedSystems via the Internet. The Advantage Data Architect can also be used to test an Internetconnection to the Advantage Database Server on your network or over the Internet.Advantage Developer Zone Web SiteThe main Advantage Web site can found at www.AdvantageDatabase.com. This is where youcan find product information, performance benchmark test results, and customer success stories.From this page there is a link to the Advantage Developer Zone Web site,http//:solutions.AdvantageDatabase.com, where you will find many valuable troubleshootingresources, such as the information knowledge base, developer newsgroups, and an FTP sitecontaining all Advantage troubleshooting tools, sample code, documentation, and serviceupdates.2
Non-Advantage Troubleshooting ToolsNetwork AnalyzersSometimes it is necessary to troubleshoot a problem with a network analyzer. Windows NT/2000Server comes with a basic network analyzer that can often trace packets enough to determine thesource of the networking problem. There are also more elaborate network analyzer s on themarket such as Net X-Ray and Lanalyzer.CONFIG.NLMMany times it is necessary to verify that a user's NetWare server has the correct NLMs installedand loaded. This can be done by loading NetWare's CONFIG.NLM, which will simply dumpinformation about the currently loaded modules to a file called CONFIG.TXT and then unloaditself.SCANBIND.EXESCANBIND.EXE is another tool provided by Novell and this utility will search the bindery for agiven NLM. This is particularly useful if users are getting a 6060 error which means that theAdvantage Database Server cannot be found.3
Error and Diagnostic LogsADS ERR.DBFFor troubleshooting purposes, the Advantage Database Server and the Advantage Local Servermaintain an error log. This log file is only created when an error occurs when executing anoperation in the Advantage server code. Many times a client workstation may encounter errorsthat the server may not know about, so there would be nothing logged in the server'sADS ERR.DBF file. The size of the file can be limited and its location can be set in theAdvantage configuration parameters. The most important fields are, Date and Time, Error Code,and Filename. Other useful information such as the connect name, Advantage version, andNetwork OS type and version can be found on the ADS ERR.DBF file.Environment Check Log FileThe environment check utilities are probably the most popular Advantage networktroubleshooting tools. Perhaps the most valuable information is the output of a log file containingall of the pertinent network information for a client workstation.Automatic Version CheckingAutomatic version checking currently exists in the Advantage Client Engine DLLs. At initializationtime, each DLL checks to verify that the DLLs it is using are of the same version. If the DLLs donot have matching versions, a message will be displayed indicating a specific DLL is newer orolder than another. The only result of the version mismatch is the message box. If one of thesemessages is displayed, the DLL will attempt to continue working. It is meant to be a warning tomake the user aware of the problem and to encourage the user to get matching DLLs.The Advantage TDataSet Descendent does not check the Advantage Client Engine DLLs,however, the DLLs do perform the internal checking at load time to make sure they all match.Avoiding ANSI Collation Mismatch ErrorsA single Advantage application can connect to multiple Advantage Database Servers, or one ormore Advantage Database Servers and the Advantage Local Server. If such an application isusing ANSI or OEM collation with non-USA collation sets, care must be taken to avoid a 5092Collation Mismatch error. To avoid such an error, make sure the same ANSI collation language isbeing used with all connections. To ensure the ANSI collation languages are the same, verify oneof the following is true:1. This first option is the easier method to make sure the ANSI collation languages are the samefor all connections. Specifically select an ANSI collation language when installing theAdvantage Database Server and Advantage clients. Make sure to specify the same ANSIlanguage for all installs. The ANSI collation language selected during an Advantage clientinstall will be placed in the Advantage Local Server configuration file, ADSLOCAL.CFG.2. If you do not wish to use option 1 above, select DEFAULT ON MACHINE for the ANSIcollation language when installing the Advantage Database Server and the Advantageclients. All computers used for installation of the Advantage Database Server should berunning the same Windows operating system. The computer running an application thatconnects to the Advantage Local Server should also be running this same OS. In addition tothe operating systems being the same, all computers should be using the same ANSIcollation language (which is specified via the Regional Settings icon).4
Note If your application is connecting to a single Advantage Database Server, just theAdvantage Local Server, or English ANSI collation language is always being used, no CollationMismatch errors will occur.Note If you change your ANSI collation language from one language to another, you need torebuild all of your index files.Avoiding OEM Collation Mismatch ErrorsA single Advantage application can connect to multiple Advantage Database Servers, or one ormore Advantage Database Servers and the Advantage Local Server. If such an application isusing ANSI or OEM collation with non-USA collation sets, care must be taken to avoid a 5092Collation Mismatch error. To avoid such an error, make sure the same OEM collation language isselected when installing the Advantage Database Server and the Advantage clients. The OEMcollation language selected during an Advantage client install will be placed in the AdvantageLocal Server configuration file, ADSLOCAL.CFG. Note when installing the U.S. version of theAdvantage Database Server, USA is the only OEM collation language available, so there is noability to select a different OEM collation language.Note If your application is connecting to a single Advantage Database Server, just theAdvantage Local Server, or USA OEM collation language is always being used, no CollationMismatch errors will occur.Note If you change your OEM collation language from one language to another, you need torebuild all of your index files.5
Troubleshooting in the NetWare EnvironmentError LogsThe Advantage Database Server provides error and warning information in two files:ADS ERR.DBF and ASSERT.LOG. Errors and warnings are logged when a recoverable, invalidcondition occurs on the Advantage Database Server. For specific error explanations, see theAdvantage Error Guide Windows Help documentation (ADSERROR.HLP).ADS ERR.DBF is a DBF table to which any application or data error or warning is recorded.Errors and warnings written to this error log file are not necessarily critical errors but are key totracing potential problems in the system or client applications. This error log may be configured toa maximum file size to prevent excessive disk space usage. See Advantage Database ServerConfiguration, to change this setting.ASSERT.LOG is a file to which critical Advantage internal assertion failures are recorded.Assertions are internal "sanity checks" placed throughout the Advantage Database Server codeto verify that code paths and data are valid during operation. If an assertion failure occurs on yourfile server, the Advantage Database Server NLM will be halted and a message will appear on thefile server monitor. An error will also be recorded to the Advantage error log file. For moreinformation on NLM Assertions, see the section below.These log files are configurable to be placed in a specified network directory location. SeeAdvantage Database Server Configuration for more information.AssertionsAn important functional requirement of the Advantage Database Server is to not cause a serverAbEnd (Abnormal End). During development of the Advantage Database Server, every effort wasmade to detect possible causes of NetWare server AbEnds and to properly recover in thosesituations.As an additional safeguard, the Advantage Database Server contains assertion checks. Anassertion check is a run-time verification of the current state of the Advantage Database Server.Assertion checks are used to verify function parameters, memory contents, etc. Assertion checkswill halt Advantage Database Server processing when an unknown state is encountered, ratherthan allowing the Advantage Database Server to continue processing and possibly cause aserver AbEnd.A failed assertion check causes the currently active Advantage Database Server thread to enteran infinite loop that displays a warning message on the main console screen of the file server. Amessage is also displayed on the Advantage Database Server NLM screen. An entry is made inthe Advantage Assertion Failure Log (ASSERT.LOG) and a current Advantage Database Serverinternal data dump is written to an ADS SNAP.LOG file. By default, the Assertion Failure log fileand ADS SNAP.LOG file are located in the root directory of the SYS volume on the file serverwhere the Advantage Database Server is loaded. The Assertion Failure log file can be configuredto be located on any valid file server directory.Important! If an assertion failure occurs, all users must exit their Advantage applications.6
Unloading the Advantage Database Server NLM in an assertion failure state does not generallycause problems. However, an assertion failure creates an unknown state, so the possibility existsthat your file server may go down. To minimize possible damage:1. Have all users connected to the file server (Advantage or otherwise) exit their applications.2. Wait a few minutes for the file server to flush all dirty cache buffers.3. Unload the Advantage Database Server NLM. If the Advantage Database Server NLMunloads successfully, you can resume normal activity.4. Save the following files: The Advantage Assertion Failure Log file (ASSERT.LOG), theADS SNAP.LOG file containing the Advantage Database Server internal data dump, and theAdvantage Error Log file (ADS ERR.DBF).After you save the necessary files, re-load the Advantage Database Server NLM on the networkfile server and resume your Advantage applications. Then, contact Advantage Technical Support.ABEND.LOGWith NetWare version 4.11 and later, Abnormal Ends (AbEnds) are logged in a file calledABEND.LOG. CONLOG.NLM must be loaded for this to occur. The ABEND.LOG is very useful indetermining the cause of the AbEnd. If your server AbEnds, and ADS.NLM is the runningprocess, send the ABEND.LOG to Advantage Technical Support. If your server AbEnds, theNetWare server is older than version 4.11, and ADS.NLM is the running process, consult theprocedure for troubleshooting an AbEnd in the Advantage Knowledge Base to gather necessaryinformation to send to Advantage Technical Support.7
Troubleshooting in the Windows NT/2000 EnvironmentNote The Advantage Database Server for Windows NT/2000 is a Windows NT/2000 Service. Itcannot run as a standard Windows application. If running the Advantage Database ServerService is attempted from Windows 95 or Windows 98, the following error will occur: "TheADS.EXE file is linked to missing export NETAPI32.DLL NetShareGet Info". Refer to Installingand Starting the Advantage Database Server for Windows NT/2000 for more information onWindows NT/2000 Services and how to start them.Event LogWindows NT/2000 event logging provides a centralized way for applications and services torecord events such as when a service was stopped or started as well as error conditions. TheWindows NT/2000 Event Viewer provides a standard user interface for viewing logged events.There are three types of event logs: System Log - tracks Windows NT/2000 system information Security Log - tracks events triggered by security violations Application Log - tracks events written by an applicationThe Event Viewer is accessed through the Administrative Tools group/folder. Select the type oflog file you want to view (System, Security, or Application). Double click the event in the list toview the Event Detail Window.Information, warnings, and errors pertaining to the Advantage Database Server Service isrecorded in the Event Viewer Application Log. Information messages are used to record when theAdvantage Database Server Service was started or stopped. Advantage Database ServerService warnings alert users of recoverable problems. Errors, however, are used to display nonrecoverable conditions that are likely to cause an application failure.Error LogFor troubleshooting purposes, the Advantage Database Server Service maintains an error log.As a default, the error log, ADS ERR.DBF, is located in the root of the C: drive. This error log filemay be configured to be located on any valid server directory. When an error occurs, pertinenterror information is appended to this file.Errors are logged when a recoverable, invalid condition occurs in the Advantage Database ServerService. All errors are returned to the client. For specific error explanations, see the online ErrorHelp file, ADSERROR.HLP.8
AssertionsA primary functional requirement of the Advantage Database Server Service is to not cause anexception or server crash. During development of the Advantage Database Server Service, everyeffort was made to detect possible causes of exceptions and to properly recover in thosesituations.As an additional safeguard, the Advantage Database Server Service contains assertion checks.An assertion check is a run-time verification of the current state of the Advantage DatabaseServer Service. Assertion checks are used to verify function parameters, memory contents, etc.Assertion checks will halt Advantage Database Server Service processing when an unknownstate is encountered, rather than allow the Advantage Database Server Service to continueprocessing and possibly cause an exception.A failed assertion check causes the currently active Advantage Database Server Service threadto enter an infinite loop that displays a warning message on the main console screen of theserver. A message box is also displayed on the server screen. An entry is made in the AdvantageAssert Log (ASSERT.LOG) and a current Advantage Database Server Service memory dump iswritten to an ADS SNAP.LOG file. By default, the ASSERT log file and ADS SNAP.LOG file arelocated at the root of the C: drive.The ASSERT log file can be configured to be located on any valid server directory.Important! If an assertion failure occurs, all users must exit their Advantage applications.Stopping an Advantage Database Server Service in an assertion failure state does not generallycause problems. However, an assertion failure creates an unknown state, so the possibility existsthat an exception may occur. To minimize possible damage:1. Have all users connected to the Advantage Database Server exit their applications.2. Wait a few minutes for the server to flush all buffers.3. Stop the Advantage Database Server Service. Once the Advantage Database Server Serviceis stopped, you can resume normal activity.4. Save the following files: Advantage Assert Log file (ASSERT.LOG) The ADS SNAP.LOG file containing the Advantage Database Server memory dump Advantage Database Server Error Log file (ADS ERR.DBF)5. After you save the necessary files, re-start the Advantage Database Server Service andresume your Advantage applications. Then, contact Advantage Technical Support.9
Troubleshooting in the Linux/Unix EnvironmentError LogsThe Advantage Database Server provides error and warning information in three files:ads err.dbf, assert.log, and ads log.txt. Errors and warnings are logged when a recoverable,invalid condition occurs on the Advantage Database Server.ads err.dbf is a DBF table to which any application or data error or warning is recorded. Errorsand warnings written to this error log file are not necessarily critical errors but are key to tracingpotential problems in the system or client applications. This error log may be configured to amaximum file size to prevent excessive disk space usage.ads log.txt is a text file to which all fatal errors are logged. If the Advantage daemon will not load,crashes, or encounters any other critical errors, check the ads log.txt file for more information.assert.log is a file to which critical Advantage internal assertion failures are recorded. Assertionsare internal "sanity checks" placed throughout the Advantage Database Server code to verify thatcode paths and data are valid during operation. If an assertion failure occurs on your file server,the Advantage daemon will be stopped and a message will appear on in the ads log.txt file. Anerror will also be recorded to the Advantage error log file.These log file locations are configurable, with the default directory being /var/log/advantage. Ifyou modify the default location, verify that the advantage user has privileges to the directory inquestion. See Advantage Database Server Configuration in the Advantage Database Server Helpdocumentation (ADS.HLP) for more information. (Note that each of the Advantage products andtheir corresponding Help files are installed separately.)10
Troubleshooting in the Windows 95/98/ME EnvironmentError LogFor troubleshooting purposes, the Advantage Database Server maintains an error log.As default, the error log, ADS ERR.DBF, is located in the root of the C: drive. This error log filemay be configured to be located on any valid server directory. When an error occurs, pertinenterror information is appended to this file.Errors are logged when a recoverable, invalid condition occurs in the Advantage DatabaseServer. All errors are returned to the client. For specific error explanations, see the online ErrorHelp file, ADSERROR.HLP.AssertionsA primary functional requirement of the Advantage Database Server is to not cause an exceptionor server crash. During development of the Advantage Database Server, every effort was madeto detect possible causes of exceptions and to properly recover in those situations.As an additional safeguard, the Advantage Database Server contains assertion checks. Anassertion check is a run-time verification of the current state of the Advantage Database Server.Assertion checks are used to verify function parameters, memory contents, etc. Assertion checkswill halt Advantage Database Server processing when an unknown state is encountered, ratherthan allow the Advantage Database Server to continue processing and possibly cause anexception.A failed assertion check causes the currently active Advantage Database Server thread to enteran infinite loop that displays a warning message on the main console screen of the server. Amessage box is also displayed on the server screen. An entry is made in the AdvantageDatabase Server Assert Log (ASSERT.LOG) and a current Advantage Database Server memorydump is written to an ADS SNAP.LOG file. By default, the ASSERT log file and ADS SNAP.LOGfile are located at the root of the C: drive.The ASSERT log file can be configured to be located on any valid server directory.Important! If an assertion failure occurs, all users must exit their Advantage applications.11
Stopping the Advantage Database Server executable in an assertion failure state does notgenerally cause problems. However, an assertion failure creates an unknown state, so thepossibility exists that an exception may occur. To minimize possible damage:1. Have all users connected to the Advantage Database Server exit their applications.2. Wait a few minutes for the server to flush all buffers.3. Shut down the Advantage Database Server executable. Once the Advantage DatabaseServer is stopped, you can resume normal activity.4. Save the following files: Advantage Assert Log file (ASSERT.LOG) The ADS SNAP.LOG file containing the Advantage Server Memory dump Advantage Database Server Error Log file (ADS ERR.DBF)5. After you save the necessary files, re-start the Advantage Database Server executable andresume your Advantage applications. Then, contact Advantage Technical Support.12
Installation of the Advantage ODBC DriverThe message [Microsoft][ODBC DLL] "Specified driver could not be loaded" may indicate that oneof the necessary DLLs could not be loaded. The DLLs needed for the Advantage ODBC C32.DLL(Advantage Local Server Only)ADSLOCAL.CFG(Advantage Local Server Only)EXTEND.CHR(Non-USA OEM Language Support)ANSI.CHR(ANSI Language Support)Advantage CA-Visual Objects RDD Error ObjectIn most cases, run-time errors can be detected by your code. When an error is encountered, anerror message is generated and passed to an error object in your CA-Visual Objects error handleror a screen will pop up with an error code.If a run-time error occurs, identify the error class and specific message. Advantage will use theinstance variable, "OSCode", in the CA-Visual Objects error object. You may see error codes inthe OSCode field. Advantage error codes are listed in the Advantage Error Guide Help File.CAUTION When opening a table, the error object is no longer populated if an error occurs. Thisis because the error object was triggering the default error handler to be called even if the errorwas handled within the application. This was implemented to provide the ability to control errorhandling without the resulting default message box being displayed.13
The example code below can be used for determining if an error occurred while attempting toopen a table:LOCAL oDBAS DBServerLOCAL dwErrorAS DWORDLOCAL pacError AS PSZLOCAL wLenAS WORDLOCAL lReturnAS LONGINTpacError : MemAlloc( 200 )wLen : 200RDDSETDEFAULT("AXDBFCDX")oDB : DBServer {"d:\demo10.dbf", DBShared,, "AXDBFCDX"}lReturn : AdsGetLastError( @dwError, pacError, @wLen)IF lReturn ! AE SUCCESSErrorBox{ , "Failed to get last error" }:Show()ELSEIF dwError ! AE SUCCESSErrorBox{ , " Advantage error " pacError }:Show()ENDIFAdvantage CA-Visual Objects RDD General Protection FaultsGeneral Protection Faults (GPFs) are errors in Windows applications which may occur when theapplication attempts to execute an invalid operation, access an invalid segment or access beyondthe end of a valid segment.If an application that uses an Advantage RDD consistently GPFs, make sure that Advantage iscausing the GPF. Simply recompile the application without using any Advantage RDDs in anywork area or data server. Then run the application to determine if the GPF still occurs.If the problem persists, contact Extended Systems Technical Support.Advantage CA-Visual Objects RDD Run Time ProblemsIn the Windows environment, any single application can cause problems that may have lingeringeffects on other applications. If an application is not functioning properly, close Windows, rebootthe PC, and reload Windows. Verify the application is still experiencing the same problems andcontact Extended Systems Web Assist Technical Support.14
Troubleshooting Advantage Internet ServerIf the client is unable to connect to the Advantage Database Server over the Internet, verify thefollowing: The correct DLLs are being used on the client. The ADS.INI file exists in the \WINDOWS directory, the \WINNT directory, or in theapplication’s search path. The client has an Internet connection by pinging the Advantage Internet Server hostcomputer. Reference the ADS.INI file to get the IP address of the PC running the AdvantageInternet Server. Example: C:\ ping 199.103.103.202. The server name in which the database application is trying to use is in the ADS.INI file. Drive letter mappin
Troubleshooting Advantage Troubleshooting Tools . This functionality in ARC allows you to set up aliases similar to Delphi database aliases. . anywhere in the world, since it will connect to an Advantage Database Server here at Extended Systems via the Internet. The Adva
