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. Expected exceptions, typically are thrown as SQLExceptions and not protocol errors.
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.
In cases where the client receives data from the server that it (the client) either doesn't expect or else doesn't recognize, the result is usually a client-side DisconnectException with a sometimes cryptic protocol error, such as "actual code point, -2 does not match expected code point, 8709", or perhaps even a more vague error saying "A communication error has been detected."
When debugging these kinds of server protocol failures, it is often a good idea to start by checking to see if the server sent any malformed or invalid data structures to the client. For a description of two of the more common ways in which a data structure can be malformed (and thus can break protocol), see DssProtocolErrors.
There are three tracing options that can be set to assist with debugging protocol errors.
Use the 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.
There is also server side tracing available by setting the derby.drda.traceAll and 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. This 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.