Pensieri di un lunatico minore

Fixing Logging (Pt. 2) – Message Catalogs

In earlier posts, I ranted about the state of logging and made some observations about who the audience might be. Now I want to talk about something called “message catalogs”. Now, there’s actually two meanings to this term that are often used that mean different things.

First, there’s the idea of a collection of messages that are used for internationalizing an application into multiple languages. This is most commonly typified by something like the GNU gettext tools and the PO files. A simple X=Y mapping is provided, and nothing more.

The second, is something older and more rooted in what companies like IBM, DEC, HP, etc. have done for their large machines. Take the following message description from the z/VM information center:

---

DMS006E No read/write {disk|filemode|filemode filemode} accessed [for fn ft]

Explanation:
The user does not have access to a read/write file mode on which the command can write its output or utility files. If the message displayed is NO READ/WRITE ‘A’ FILEMODE ACCESSED, the command, in order to be executed, requires that file mode A be accessed in read/write mode.

For RECEIVE, SENDFILE, or DISCARD (which is equivalent to RECEIVE issued with the PURGE option) the LOG option was in effect, and no read/write file mode was accessed.

For the CONVERT command, the program tried to find a read/write file mode for the table, but was unsuccessful.

System action:
RC=36. Execution of the command is terminated. The system status remains the same.

For the CONVERT command, conversion stops.

User response:
Access a R/W SFS directory or a R/W minidisk (as appropriate) and reissue the command. Or, for a minidisk, issue the CP LINK command to reset the minidisk to read/write, access it as file mode A again, and reissue the command.

For the CONVERT command, where the table can be built, access a minidisk or SFS directory in read/write mode and reissue the command.

---

In this example, there’s a message code (DMS006E), a textual description, but also a clear explanation of what that message means, how the system will behave, and most importantly, how the user should deal with the issue. Note that this is very specific to the platform (z/VM in this case). The point is that it makes it crystal clear what the message means, why it occurred and how to fix it. In the Unix world, this kind of thing is maybe covered, partially, in man pages, but more commonly, you end up Googling to find something, somewhere, that explains what in the world went wrong.

It also demonstrates another thing that, while useful, is not quite a necessity—just a nicety—and that is the use of message codes. Why do these matter? First, it is a discriminator for looking things up. Finding DMS006E is a lot easier in an index/ToC than it is to find some phrase/sentence. Second, it makes it easier to ensure that different parts of code use the same messages uniformly. Finally, it does make it easier on any automated tools that are looking for specific issues.

To me, this is some of the most useful documentation a developer can write. What do their error messages actually mean to a human being? And if it can’t be resolved by anyone, then why are you logging it?