db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Db-derby Wiki] Update of "ProtocolDebuggingTips" by KatheyMarsden
Date Tue, 11 Oct 2005 18:01:55 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Db-derby Wiki" for change notification.

The following page has been changed by KatheyMarsden:

New page:
Derby Network Server and client use an the Distributed Relational Database Architecture protocol
standard which is available for pubic download from http://www.opengroup.org/dbiop/ .  The
specification consists of three documents.

 * C043     DRDA V3 Vol. 1: Distributed Relational Database Architecture
               Describes protocol flows between server and client.
 * C044     DRDA V3 Vol. 2: Formatted Data Object Content Architecture
               Describes data representation for different environments
 * C045     DRDA V3 Vol. 3: Distributed Data Management Architecture
	       Describes the commands, objects and parameters that are used in the protocol flow
described in volume 1.

When there is some sort of violation of the protocol, the server or client will throw a protocol
error which might look something like this:

Execution failed because of a Distributed Protocol Error:  DRDA_Proto_SYNTAXRM;
CODPNT arg  = 2114; Error Code Value = e

This type of error is usually indicative of a bug in Derby.  All expected exceptions should
throw SQLExceptions and not protocol errors.

== Understanding DRDA ==

Before debugging the failure it is good to have a general understanding of DRDA.  The specs
are very large and can be somewhat intimidating, but Chapter 4 of  Volume 1 is an excellent
place to get a good overview of the protocol flow.
Volume 3 is a reference for the code points (protocol token's) that are exchanged in the flow.
 Each Codepoint has an integer value.  Appendix B has a table the term names sorted by codepoint
that can be very helpful.  These values can be found in the Codepoint.java files in server
and client.  

== Types of Protocol Errors ==

=== SYNTAXRM - Data Stream Sytax error ===
Typically protocol errors are manifested by a SYNTAXRM command response being sent by server
or client. The error will show the code point of the object causing the error.  The stack
trace will usually display the context of the protocol flow and whether the failure was because
a code point was missing, an invalid codepoint was sent etc.  So, for example in the stack
trace for DERBY-614 we see that the server was parsing a CNTQRY and found that it was missing
a required codepoint, x2114.  A first pass might be to look at the CNTQRY command in the DDM
Manual to see what is required and appendix B to see what 2114 is.  One thing to consider
is that often if there is an error in exchanging protocol where things get off by a byte or
two the code point value specified with SYNTAXRM may have no meaning and may just be the next
2 out of order bytes in the stream.

== Protocol Tracing ==

There are three tracing options that can be set to assist with debugging protocol errors.

=== Client Tracing ===
Use the [http://db.apache.org/derby/docs/10.1/adminguide/cadminappsclienttracing.html
 traceFile] or traceDirectory connection attributes to specify trace output files.  If you
are debugging protocol with multiple connections use traceDirectory instead of traceFile.
  The client side tracing shows  the protocol flow in the context of the jdbc calls so is
probably the best choice for tracing.

=== Server Tracing ===
There is also server side tracing available by setting the [ http://db.apache.org/derby/docs/10.1/adminguide/radminconfig.html
derby.drda.traceAll] and [http://db.apache.org/derby/docs/10.1/adminguide/radminconfigdb2jdrdatracedirectory.html
derby.drda.traceDirectory] properties.  The server side tracing shows just the protocol and
is usually only useful if a message for some reason is getting lost between the server and

=== Server SanityManager.DEBUG Output ===
With a sane build, you can set the derby property, derby.drda.debug=true.  Thise will produce
debug output on the server console which can be helpful in debugging protocol issues.  This
property also launches a thread which will print periodic memory usage information for the
server jvm, so can be useful in debugging memory leaks as well.

== Useful Links ==

Protocol Specifications - http://www.opengroup.org/dbiop/
Server admin guide - http://db.apache.org/derby/docs/10.1/adminguide/

View raw message