[Db-derby Wiki] Update of "ProtocolDebuggingTips" by KatheyMarsden

[Apache Wiki <wi...@apache.org>]

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:
http://wiki.apache.org/db-derby/ProtocolDebuggingTips

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 client.


=== 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/