opinion: A Beginners Guide to Creating Messages

So, I look down through the SYSLOG using SDSF, and I find this message:

COULD NOT FIND INPUT ACCOUNT

But what does this message mean? Is this a serious error, or just informational? What issued it, and who should I talk to about it?

Or in other words, this message is terrible. So, let me jump on my soap box and tell you how I think error messages that may appear on a z/OS console, or anywhere for that matter, should work.

1. Message ID

Every message should have a message ID. Ideally this will start with some characters to help determine the application or component issuing the message: maybe TCARDS or XBANK. So, if we see a message with the ID XBANK001, we know straight away the Banking support group knows about it.

This message ID should not be the same as any product; we don't want to confuse our messages with z/OS or other software messages. For example, z/OS messages can start with the letters 'IEC': best avoid these characters. I talk more about the characters used by z/OS and mainframe software in another article. In general, IBM products can issue messages beginning with the letters 'A' to 'I'; our messages should be further down the alphabet.

Having a message ID makes it easier to talk about the message. So, we can tell our operator "wake me if you see message XBANK040."

A message ID has another benefit: it allows us to use automation products with it. So, we could have a batch job that issues the message XBANK001 and an automation rule that starts a CICS region when this message is issued. Harder with no message ID.

2. Message Type

In our partner article, we talked about how many IBM messages have a character after the message ID with the message type. For example, we could have:

• I = Information – no error, nothing has to be done.
• W = Warning – may be an error, worth checking out.
• E = Error – something went wrong.

If our message ID has such a letter, we will immediately know if there the message indicates a serious problem or is just informational.

3. Issuing Job

Looking at our "ERROR – COULD NOT FIND INPUT ACCOUNT" message, it's not obvious what job issued the message. We could hunt this down using SDSF, but that takes time. Our message should start with the job (or started task) where the message came from.

4. Meaningful Text

Imagine our message is being read by a tired systems programmer at 3am who knows nothing about our application. The message should clearly tell this poor person what is happening. So, instead of

COULD NOT FIND INPUT ACCOUNT

how about

COULD NOT FIND ACCOUNT ACC1543 FROM INPUT FILE INACCT1 WHILE PERFORMING DAILY
INTEREST RUN.

There's a couple of things to look at here:

• It tells us what it was doing (DAILY INTEREST RUN) so we have some context of the processing the message relates to.
• This message also includes an account number (ACC1543), making it easier for a support person to diagnose the problem, and possible perform any actions required to make things right.
• This message specifies the DD name of the file in question: again, making it easier for a support person to figure things out.

5. What the Program Will Do

Finally, our message should say what will happen now: what our program will do (or not do). In our example, we could add to the end of the message "RECORD IGNORED" or "SKIPPING ACCOUNT AND PROCESSING NEXT." Now we know what the program will do without breaking open the source code – again, faster problem solving or remediation.

What It Looks Like

What I'm saying is that this message

COULD NOT FIND INPUT ACCOUNT

Is bad. A far better one is:

XBANK001E: (PRDJOB10) COULD NOT FIND ACCOUNT ACC1543 FROM INPUT FILE INACCT1
WHILE PERFORMING DAILY INTEREST RUN. RECORD IGNORED.

David Stephens

LongEx Quarterly is a quarterly eZine produced by Longpela Expertise. It provides Mainframe articles for management and technical experts. It is published every November, February, May and August.

The opinions in this article are solely those of the author, and do not necessarily represent the opinions of any other person or organisation. All trademarks, trade names, service marks and logos referenced in these articles belong to their respective companies.

Although Longpela Expertise may be paid by organisations reprinting our articles, all articles are independent. Longpela Expertise has not been paid money by any vendor or company to write any articles appearing in our e-zine.