> Googling for [alphanumeric error codes] nailed it.  They pop up in
> embedded devices with simple alphanumeric displays!

True. Your links are illustrative. Also part numbers in catalogs.

I don't know whether it's simply selection bias from the search terms,
but all those links like to use the word "code". You say that DocBook
also uses the that word. Hence we should probably adopt it.

>     DocBook provides four elements for identifying the parts of an error
>     message: errorcode, for the alphanumeric error code (e.g., “–2”);
>     errorname, for the symbolic name of the error (e.g., “ENOENT”);
>     errortext, for the text of the error message (e.g., “file not
>     found”); and errortype, for the error type (e.g., “recoverable”).
>
> Maybe we should adopt these names.  DocBook has undergone a long
> evolution already.

I now strongly agree with 'code.

'text may be as good as 'message.

(foreign-status-ref st 'message)
(foreign-status-ref st 'text)

(foreign-status-ref st 'localized-message)
(foreign-status-ref st 'localized-text)

(foreign-statuf-ref st 'detail-message)  ; databases
(foreign-statuf-ref st 'detail-text)     ; databases

(foreign-statuf-ref st 'hint-message)    ; databases
(foreign-statuf-ref st 'hint-text)       ; databases

OK, 'text seems as good as 'message and is a shorter word.

The 'code and 'name combination is very clear indeed -- _in aggregate_:

(raise-foreign-status
  'code 128
  'name 'ENETUNREACH
  'text "Network is unreachable")

(raise-foreign-status
  'code 84
  'name 'ERROR_OUT_OF_STRUCTURES
  'text "Out of structures")

(raise-foreign-status
  'code 'SUd
  'text "The suds are excessive during the washing cycle")

(raise-foreign-status
  'code '|3E|
  'text "Tachogenerator does not transmit information")

So it's no wonder they like it for manuals where errors are tabulated.

But check out how unclear it is out of context:

(if (eq? 'EINTR (foreign-status-ref st 'name))
     ...)

(if (= 4 (foreign-status-ref st 'code))
     ...)

Is name really a semi-cryptic symbol? Is code really a number?

Worst of all, there's nothing obviously wrong with this:

(if (eq? 'EINTR (foreign-status-ref st 'code))
     ...)

A caffeine-deficient code reviewer would not catch that mistake.

By comparison, this is much more obvious:

(if (eq? 'EINTR (foreign-status-ref st 'symbol))
     ...)

(if (= 4 (foreign-status-ref st 'number))
     ...)

And the mistake is much more obvious:

(if (eq? 'EINTR (foreign-status-ref st 'number))
     ...)

Hence I would still go back to 'symbol and 'number for maximum clarity.

What to do about alphanumerics is not clear. I think we're blowing it
out of proportion given the paucity of examples in software. We could
either reuse 'symbol or add 'string or 'alphanumeric.

As for a 'type field with values such as 'recoverable, that seems way
generic. People could use 'recoverable? being #t or #f.

For generic severity levels, we have 'severity which is used by syslog,
VMS and probably many others.

>     category
>     class-code
>     class-title
>     subclass-code
>     Subclass-title
>
> All these things are determined by the SQLSTATE, so I don't see much
> reason for lugging them around in status objects.

OK, the SQLSTATE is simply a concatenation of the class and subclass
codes. Fair enough.

I wonder why the subclass is not called simply "code". Maybe several
db-engine-dependent codes are meant to be instances of a SQLSTATE
subclass. Postgres uses the subclasses directly for codes:
<https://www.postgresql.org/docs/10/errcodes-appendix.html>.

"Each class belongs to one of four categories: "S" denotes "Success"
(class 00), "W" denotes "Warning" (class 01), "N" denotes "No data"
(class 02) and "X" denotes "Exception" (all other classes)."

That category is basically a severity level. We could advise people who
want to ship it to put it in the 'severity property.