Subject: PROPOSAL: CAP Error codes definition and handling

From: [email-masked]
Date: Fri, 14 May 1999 11:56:25 -0400

Within CAP, there is a fundamental need for well defined
return code handling. Every operation sent from the CUA
to the CS needs to have a returned status code indicating 
the result of the operation. 

As a representative of the group at interim meeting in Atlanta,
I am proposing the following:

That to each transaction from the CUA to the server, the
satus be reported as follows:

<statuscode>;<text>

Where:

statuscode is the error code defined in the status code table
in the draft.

text is a USASCII text string, for diagnostics purposes, that
is not to be displayed by the CUA.

For example

3.5.4; Can't write: disk full.

I also propose that whatever this group chooses to do,
that we make that error code format identical between
iCal's and CAP.

I'm looking forward to see the group's feedback.

Andre Courtemanche
CS&T

---

From: [email-masked]
Date: Mon, 17 May 1999 18:46:06 GMT

>satus be reported as follows:
[Snip]
>that we make that error code format identical between

Why not just follow the same format that is defined in RFC 2445 for Request
Status (section 4.8.8.2)?  That defines the format of:

   The value consists of a short return status component, a longer
  return status description component, and optionally a status-specific
  data component. The components of the value are separated by the
  SEMICOLON character (US-ASCII decimal 59).
[Snip]
   Format Definition: The property is defined by the following notation:

    rstatus    = "REQUEST-STATUS" rstatparam ":"
                 statcode ";" statdesc [";" extdata]

    rstatparam = *(

               ; the following is optional,
               ; but MUST NOT occur more than once

                (";" languageparm) /

               ; the following is optional,
               ; and MAY occur more than once

               (";" xparam)

               )

    statcode   = 1*DIGIT *("." 1*DIGIT)
    ;Hierarchical, numeric return status code

    statdesc   = text
    ;Textual status description

    extdata    = text
    ;Textual exception data. For example, the offending property
    ;name and value or complete property line.

(For those out there who are not sure; Im not advocating the ENTIRE reuse
of this property and it params, etc, just the format of the 'value' part;
statcode ';"...)

Good reasons to do this include:

1: I can reuse my existing parser code and
2: Its already defined by iCal so why not reuse it in CAP?

Bruce
===========================================================================
Bruce Kahn                                INet: [email-masked]
Iris Associates                          Phone: 978.392.5335
Westford, MA, USA 01886                    FAX: and nothing but the FAX...
Standard disclaimers apply, even where prohibited by law...

---

From: [email-masked]
Date: Mon, 17 May 1999 15:45:54 -0400

By reading the details of the tokens,
you will see that in the following,

statdesc MUST be the description given in the RFC and
not some arbitrary text.

Furthuremore, statdesc is of a type that can be localized,
with a language tag, bla, bla bla.

It is much more restrictive than the one proposed.

Andre Courtemanche
CS&T

-----Original Message-----
From: [email-masked] [mailto:[email-masked]]
Sent: Monday, May 17, 1999 2:46 PM
To: [email-masked]
Cc: [email-masked]
Subject: Re: PROPOSAL: CAP Error codes definition and handling

[Snip]

    rstatparam = *(

                (";" languageparm) /

               (";" xparam)

               )

    statdesc   = text

    extdata    = text

Bruce

---

From: [email-masked]
Date: Tue, 18 May 1999 13:31:34 GMT

>statdesc MUST be the description given in the RFC and

Actually the RFC simply says:

 statdesc   = text

There is _no_ requirement as to what is in statdesc, just that is it text.
It could say "Boo" or "I dont like your name so good bye!" or it could be a
really useful message.

>with a language tag, bla, bla bla.

Yep, thats true.  However, your parser engine will probably have some
'default' language savy to it (or your code will tell it the default to use
when parsing).  Otherwise it may totally barf on LANGuages that dont fit
the assumption of always USASCII.  As a result, I dont see this as a big
issue not to reuse the format.

If you dont like the LANG= requirement we could restrict it a bit to
USASCII but then it wont be all that helpful in some internationalized
sites (ie: Japan, Russia, etc) where they dont use strict USASCII
characters for everything.  Status messages in the local language (ie:
Japan) are something customers will most likely want.

If the LANG= issue is the only real problem for Andre Id ask the WG to give
a thumbs up/down on leaving in the LANG= or not (and if not, defaulting it
to USASCII).  If there are any other issues then lets resolve 'em but I
still think we should reuse this format (just like we reused the iCalendar
hierarchical response code format and classes).

Bruce

---

From: Doug Royer <[email-masked]>
Date: Tue, 18 May 1999 14:13:29 -0700 (PDT)

> From: [email-masked]
> Date: Tue, 18 May 1999 13:31:34 GMT
> 
> ...
>
> ...

If the LANG is going to be there in the CAP protocol, then there
needs to be a way for the CUA to specify its preferred LANG to
be used in the CAP protocol replies. Otherwise there is no way
to know not to send some LANG content that is incompatible with
the CUA.

The REQUEST-STATUS iCalendar object contains application data
reply information.

The CAP protocol reply contains information independent of the
iCalendar application data.

I agree with Andre's proposal. 

	<statuscode>;<text>

Where <text> is optional, US-ASCII, and for diagnostics purposes only.
I am in favor of:

	<statuscode>[;<text>]

Where  the 'text' value is optional at all times.

-Doug
-------------------------------------------------------------------
[email-masked]		http://playground.sun.com/~dougr
Pager:				[email-masked]
801 W. El Camino #131		Work:   (650)786-7599
Mountain View, CA 94040		Ham Radio: N6AAW, Aviation: PP-ASEL

---

From: "lisal" <[email-masked]>
Date: Tue, 18 May 1999 15:25:11 -0700

The DAV RFC explains better than I have been able to how you can have
English text in error messages (for ease of design, debugging, coding
and testing), without worrying about localization.  

"For error reporting, we follow the convention of HTTP/1.1 status
   codes, including with each status code a short, English description
   of the code (e.g., 423 (Locked)).  While the possibility exists that
   a poorly crafted user agent would display this message to a user,
   internationalized applications will ignore this message, and display
   an appropriate message in the user's language and character set.

   Since interoperation of clients and servers does not require locale
   information, this specification does not specify any mechanism for
   transmission of this information."

-- Lisa

> From: Doug Royer [mailto:[email-masked]]
> Sent: Tuesday, May 18, 1999 2:13 PM
> To: [email-masked]
> Subject: RE: PROPOSAL: CAP Error codes definition and handling
> 
> 
>

---

From: Frank Dawson/CAM/Lotus <[email-masked]>
Date: Tue, 18 May 1999 23:16:43 GMT

Doug Royer wrote:

>the CUA."

There is a "LANGUAGE" parameter on any iCalendar property that takes a text
value. Is this what you are thinking of?

It seems weird that we would be asking the CS to "translate" text strings.
I understand that if there are multiple nationalized forms of the default
US-EN form of the text, as specified in the CAP standard, then you might
want to pre-select which one you want in any reply from the CS. Is this
what you mean?

>Where  the 'text' value is optional at all times.

What do you mean "US-ASCII". The replies are in a MIME object. That means
that the object can be returned in any IANA registered character set.

I think this could be a more fundamental issue. If a US-ASCII only CUA in
the US connects to a SHIFT-JIS only CS in Japan. We will have a problem
with basic character rendition; so forget about any language matter. Are we
providing for a CUA to request connection with a particular character set
too? What would this look like?

-- Frank Dawson

---

From: Doug Royer <[email-masked]>
Date: Tue, 18 May 1999 16:14:19 -0700 (PDT)

> From: Frank Dawson/CAM/Lotus <[email-masked]>
> Date: Tue, 18 May 1999 23:16:43 GMT
> 
> Doug Royer wrote:
> 

I thought that the issue was the reply from the server to the client.
Its is true that the server can add a LANG paramater. How will it
know which one the client wants? 

> It seems weird that we would be asking the CS to "translate" text strings.

I Never said that.

> want to pre-select which one you want in any reply from the CS. Is this

Yes - I think. *IF* there are going to be text messages. I think
that it is a MUST that the CUA be able to specify its preferred language.

I still think that the messages are not needed at the PROTOCOL level.
I think they are required at the iCalendar object level.

I think the CUA needs to be able to specify its preferred language for
any server text strings that will be returned to the CUA for any
required server generated text strings.

> that the object can be returned in any IANA registered character set.

Oops - Yea your are right - I meant some pre-defined language as
a MUST.

> too? What would this look like?

See previous oops.

-Doug

---

From: Frank Dawson/CAM/Lotus <[email-masked]>
Date: Tue, 18 May 1999 23:47:45 GMT

Doug Royer wrote:

>I think we are agreeing.  The text is optional and for
>diagnostic use only. From RFC-2068, the ABNF for 'status code'
>section 6.1.1:
>
>
>          extension-code = 3DIGIT
>
>          Reason-Phrase  = *<TEXT, excluding CR, LF>
>
>Where '*' denotes optional.

But if there is any text coming from the CS, shouldn't it be the text
specified in the CAP spec. If the CUA wants to display it fine. Or it could
display some other text, based on the hierarchical status code.

---

From: Frank Dawson/CAM/Lotus <[email-masked]>
Date: Tue, 18 May 1999 23:53:41 GMT

>I Never said that.

But you implied that the CUA could "ask" the CS for a particular
translation. That means that it must select the requested "translation" of
its standard response. An apparent translation, to me ;-)

But I definitely concur that we are not asking the CS to "automagically"
translate textual responses.

Hence, why don't we just do as Lisa has suggested...provide a standard
US-EN text string in the CAP spec. The CS will always emit this, if it
emits an optional text string in addition to the hierarchical status code,
at all. And allow the CUA to use any of its nationalized strings to display
to the user, if it wants.

THEN...Let's move on to more productive CAP discussions !!!

---

From: Frank Dawson/CAM/Lotus <[email-masked]>
Date: Tue, 18 May 1999 23:43:24 GMT

Lisa:

I like both the reference and your pragmatic insight on this subject! I
agree with where you are taking this discussion.

- - Frank

---

From: Doug Royer <[email-masked]>
Date: Tue, 18 May 1999 16:55:45 -0700 (PDT)

> To: Doug Royer <[email-masked]>
> specified in the CAP spec.

1) I thought the whole point for the text was that some felt that
the numeric reply codes would not cover all cases. If you feel
the reason for the text is to say what can't be said in numeric
codes, then its useless if not in a known language to the calendar
user and the exact text can not be specified in the CAP specification.

2) If you are saying that CAP must specify the exact text for
any given reply code. Then I would strongly object to wasting
the bandwidth with duplicate information if its required text.
That is if "x.y" always sends "predefined text" - make the text
optional.

> If the CUA wants to display it fine. Or it could

See (1) above.
If the text is needed because the status codes do not specify
everything the CS might need to send, then the text needs to be localized
so the CUA can display in a user friendly way. Which would require a
way for the CUA to inform the CS of the CUAs preferred language.

-Doug

---

From: "lisal" <[email-masked]>
Date: Tue, 18 May 1999 18:11:24 -0700

The error text is NOT intended for end-users.  End-users, if using a
well-designed CUA, should never see the error text directly.
Well-designed CUAs will present a much longer, more informative string
to the user.  For example, instead of "403 Forbidden" (a sample error
code and text from HTTP), the client might present "You do not have
permission to access this resource.  Perhaps your administrator can set
your privileges".  Or "Acces a cet objet est interdit..."  In other
words, the CUA is entirely responsible for localization of error
messages.

The error text IS needed for us, the designers of this protocol; and for
coders, testers, software debuggers, log files, protocol captures,
system administrators, network troubleshooters everywhere as long as
this protocol is used.  There will be bugs and other problems -- and
text error messages will help everybody track them down.

Why do this at all if the text is always the same?  (a) for convenience
of designers, debuggers, etc, and (b) because the text will not always
be the same.  Even if the spec says "403 Forbidden" is the correct error
message and text pair, somebody might design a test implementation or
debug version that says "403 Forbidden: this file is read-only" in some
cases and "403 Forbidden: no credentials were provided".  This is still
not meant for end-user display, only for debuggers, log files, etc. etc.

Lisa

> Sent: Tuesday, May 18, 1999 4:56 PM

---

From: Frank Dawson/CAM/Lotus <[email-masked]>
Date: Wed, 19 May 1999 13:49:39 GMT

Doug Royer wrote:

>So when our product is released, we have our known (compiled in) messages
>translated and shipped with the product. In order for our servers
>to know which message file to open, the CUA MUST inform the CS.
>
>Without something like this, there is NO WAY a CS can guess at
>the language understood by the calendar user.
>
>I still would prefer that NO text ever be sent at the PROTOCOL level.

Exactly! Only the CUA knows best what language the status code description
should be displayed in. Hence, if the CUA is CAP compliant, it already
knows the standard status codes. We have previously decided that there will
be no non-standard status codes. SO... for a given version of CAP, if the
CUA supports that version it will already know the status codes and can be
built with the localization text variants that it can display.

After all, if the CUA doesn't have support for a particular localization,
then how will it be able to display the rest of the UI in the requested
(but not supported) localization!

Hence, it is the responsibility of the CUA to display localized versions of
the optional textual status description, not the CS.

Hence, we don't need no stinkin' localization support in the CS for the
optional textual status descriptions.

Let's move on...

-- Frank

---

From: Frank Dawson/CAM/Lotus <[email-masked]>
Date: Fri, 21 May 1999 12:24:29 GMT

Having the spec specify some standard text is useful. I don't mind if a
vendor wants to augment this, but we need to have some standardized text in
the spec for each numeric status code.

-- Frank

---

From: Frank Dawson/CAM/Lotus <[email-masked]>
Date: Mon, 24 May 1999 18:14:32 GMT

Patrik: Thanks for wadding in on this. -- Frank