Commit 3f1d6c07 authored by Per Cederqvist's avatar Per Cederqvist

(Error Responses): New name for former "Error Codes". Moved to

	inside the "Client-Server Dialog" chapter.
(Special Errors): Moved inside the "Client-Server Dialog" chapter.
(Error Codes): New name for former "Normal Errors".
parent 1ffb903f
......@@ -2,7 +2,6 @@
@c
@c FIXME: Things ceder are about to fix:
@c FIXME:
@c FIXME: Make all types clickable in HTML (and info?)
@c FIXME: move "Error Codes" and "Special Errors" into "Client-Server Dialog"
@c FIXME: error-reply defined twice (conflicting).
@c FIXME: sentence-end-double-space!
......@@ -25,7 +24,7 @@
@c FIXME: "Review the last N by FOO to BAR" is empty
@c FIXME: "Remote control" contains no information
@c
@c $Id: Protocol-A.texi,v 1.137 2001/05/03 19:27:16 ceder Exp $
@c $Id: Protocol-A.texi,v 1.138 2001/05/03 19:40:38 ceder Exp $
@c %**start of header
@setfilename protocol-a.info
@settitle LysKOM Protocol A
......@@ -1331,7 +1330,7 @@ request.
Note that there is no whitespace after the initial indicator in the
reply.
Error reporting is covered in more detail in @ref{Error Codes}.
Error reporting is covered in more detail in @ref{Error Responses}.
Data elements sent from the client to the server are separated by one or
more space characters (ASCII 32). An entire call is terminated by a
......@@ -1353,6 +1352,103 @@ possible, which may result in one or more subsequent requests being
lost.
@menu
* Error Responses::
* Special Errors::
@end menu
@node Error Responses
@subsection Error Responses
If a call cannot complete successfully, LysKOM will respond with an
error reply, as defined below and earlier (@pxref{Client-Server
Dialog}).
@example
error-reply ::= normal-error | special-error
normal-error ::=
( "%"
ref-no : INT32;
error-no : Error-No;
error-status : INT32;
)
special-error ::= "%% LysKOM protocol error."
| "%%Insane token length."
| "%%Insane array size."
| "%%No connections left."
error-no ::= INT32;
@end example
The server may return two different types of errors. Normal errors are
replies to syntactically correct calls to the server. Special errors are
replies to syntactically incorrect calls and responses to exceptional
conditions.
A client should be prepared for any error code in response to any call,
no matter if the response makes any sense or not. The value returned in
@field{error-status} was more or less undefined before protocol version
10. For protocol version 10, the meaning of @field{error-status} is
defined below.
The meaning of @field{error-status} can be modified by any call. In
particular the calls that deal with Misc-Info lists set
@field{error-status} to the index of the misc item that caused the error
(if the error was caused by a misc item.)
Client should handle the error messages listed with each call in a
graceful manner. In addition, the following error types should always
be handled gracefully: @errorcode{temporary-failure},
@errorcode{internal-error}, @errorcode{feature-disabled},
@errorcode{not-implemented}, @errorcode{obsolete-call},
@errorcode{ldb-error}, @errorcode{feature-disabled},
@errorcode{out-of-memory}. Client should also be able to handle any
error in any situation without choking completely since bugs might
cause the wrong error message to be sent or new errors might be added
later on.
@node Special Errors
@subsection Special Errors
Special errors are sent in reply to syntactically incorrect calls to the
server. With the exception of the "No connections left" message, these
should never appear in the client-server dialog. If they do, there is
probably a bug in the client.
@table @asis
@item "%% LysKOM protocol error."
The client has sent a request that does not comply with protocol A. The
server will attempt to recover from this error, but additional calls may
be silently lost, and the server may send replies that the client does
not expect. This error is also returned when the client sends an array
that is longer than the maximum allowed by the server.
@item "%%No connections left."
This error is only sent when the client attempts to connect to the
server. It indicates that the server is not accepting additional
connections. This error is transient: the client may be able to connect
later. Clients should not attempt to connect immediately after
receiving this message.
@item "%%Insane token length."
The client has sent a single token that is insanely long. Typically this
means that the client has sent several kilobytes worth of digits, or
something similar. This is never returned for long strings. The server
will automatically disconnect a client who sends a token with an insane
length.
@item "%%Insane array size."
The client has send an array with a negative length. The server is not
easily fooled. The server will automatically disconnect a client who
sends an array with an insane length.
@end table
@node LysKOM Data Types
@chapter LysKOM Data Types
......@@ -7792,103 +7888,6 @@ See also @ref{async-leave-conf}.
@node Error Codes
@chapter Error Codes
If a call cannot complete successfully, LysKOM will respond with an
error reply, as defined below and earlier (@pxref{Client-Server
Dialog}).
@example
error-reply ::= normal-error | special-error
normal-error ::=
( "%"
ref-no : INT32;
error-no : Error-No;
error-status : INT32;
)
special-error ::= "%% LysKOM protocol error."
| "%%Insane token length."
| "%%Insane array size."
| "%%No connections left."
error-no ::= INT32;
@end example
The server may return two different types of errors. Normal errors are
replies to syntactically correct calls to the server. Special errors are
replies to syntactically incorrect calls and responses to exceptional
conditions.
A client should be prepared for any error code in response to any call,
no matter if the response makes any sense or not. The value returned in
@field{error-status} was more or less undefined before protocol version
10. For protocol version 10, the meaning of @field{error-status} is
defined below.
The meaning of @field{error-status} can be modified by any call. In
particular the calls that deal with Misc-Info lists set
@field{error-status} to the index of the misc item that caused the error
(if the error was caused by a misc item.)
Client should handle the error messages listed with each call in a
graceful manner. In addition, the following error types should always
be handled gracefully: @errorcode{temporary-failure},
@errorcode{internal-error}, @errorcode{feature-disabled},
@errorcode{not-implemented}, @errorcode{obsolete-call},
@errorcode{ldb-error}, @errorcode{feature-disabled},
@errorcode{out-of-memory}. Client should also be able to handle any
error in any situation without choking completely since bugs might
cause the wrong error message to be sent or new errors might be added
later on.
@menu
* Special Errors::
* Normal Errors::
@end menu
@node Special Errors
@section Special Errors
Special errors are sent in reply to syntactically incorrect calls to the
server. With the exception of the "No connections left" message, these
should never appear in the client-server dialog. If they do, there is
probably a bug in the client.
@table @asis
@item "%% LysKOM protocol error."
The client has sent a request that does not comply with protocol A. The
server will attempt to recover from this error, but additional calls may
be silently lost, and the server may send replies that the client does
not expect. This error is also returned when the client sends an array
that is longer than the maximum allowed by the server.
@item "%%No connections left."
This error is only sent when the client attempts to connect to the
server. It indicates that the server is not accepting additional
connections. This error is transient: the client may be able to connect
later. Clients should not attempt to connect immediately after
receiving this message.
@item "%%Insane token length."
The client has sent a single token that is insanely long. Typically this
means that the client has sent several kilobytes worth of digits, or
something similar. This is never returned for long strings. The server
will automatically disconnect a client who sends a token with an insane
length.
@item "%%Insane array size."
The client has send an array with a negative length. The server is not
easily fooled. The server will automatically disconnect a client who
sends an array with an insane length.
@end table
@node Normal Errors
@section Normal Errors
Normal errors are sent in reply to syntactically correct calls to the
server. The client should accept any error code in response to any call,
even if the error code in question is not listed in the description of
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment