Send Messages Unto Others

Published: March 4, 2009

by Ted Holt

I'll never forget the guy who used to call my telephone with a cheery "My computer won't compute!" whenever he had a problem. Ambiguous appeals for help annoy me to no end. The least a guy can do is give me something to go on; some information to give me a place to start to look for his problem. But in fairness to users, I often find that they don't have much information to give me because the programmer didn't make the program tell them anything. A crafty CL programmer knows how to easily avoid such situations.

When something goes wrong, send a message to the user. But don't send any old message--make it a descriptive message! Here's how.

First, create a message file, if you don't have one already. The following CL command creates a message file called AUSRMSG in library TOOLS.

crtmsgf msgf(tools/ausrmsg)

Next, design a descriptive message, keeping the following ideas in mind.

1. Write a short message of 76 characters or less.
2. Write a longer, more detailed message.
3. Include placeholders (numbers prefixed with ampersands) in both of the aforementioned message texts. This is how you make your messages descriptive by replacing placeholders with appropriate text at run time.

For example, here's a short message:

xxxxxxxxxxxxxxxxxxxxxxxxx canceled; xxxxx errors were found.

Here's a longer message:

The xxxxxxxxxxxxxxxxxxxxxxxx application ended abnormally.
Status is xxxxxxxx.
You must correct the errors before you can continue.

I have left three placeholders: application name, status code, and number of errors.

Here's the Add Message Description command that implements the message description.

addmsgd msgid(usr1001) msgf(tools/ausrmsg) +
   msg('&1 canceled; &3 errors were found.') +
   seclvl('The &1 application ended abnormally. Status +
       is &2. You must correct the errors before you +
        can continue.') +
   sev(90) +
   fmt((*char 24) (*char 8) (*bin 2)) 

Notice the three placeholders: &1, &2, and &3. The FMT parameter defines them to be 24-byte character, 8-byte character, and 2-byte signed binary (integer) respectively.

The following program fragments illustrate how to use the message description. Program PAYEDIT returns the number of errors it finds in a payroll batch through the second parameter. If this number is more than zero, the program cancels, sending a descriptive message to the caller.

dcl   &AppName       *char     24   value(' Payroll edit')
dcl   &AppStatus     *char      8
dcl   &NbrErrors     *dec       5
                                 
dcl   &Bin2          *char      2

call PayEdit parm(&AppStatus &NbrErrors)
if (&NbrErrors *gt 0) do
   chgvar   var(%bin(&Bin2 1 2)) value(&NbrErrors)
   chgvar   var(&MsgDta)  value(&AppName *cat &AppStatus *cat &Bin2)
   sndpgmmsg msgid(usr1001) msgf(ausrmsg) msgdta(&msgdta) +
                msgtype(*escape)
enddo

Since CL cannot concatenate decimal values into a string, I defined the third parameter as integer, which can be copied bit-for-bit into a character value using the %BIN function.

The user sees the following in the message line at the bottom of his screen (or you see it his job log):

Payroll edit canceled; 3 errors were found.

If he positions the cursor to the messages and presses F1, he sees the second-level text:

The Payroll edit application ended abnormally. Status is 25-32126.
You must correct the errors before you can continue. 

If you need to send more than one message in response to an error, send all of them except for the last one as diagnostic messages.

sndpgmmsg msgid(usr1236) ... msgtype(*diag)
sndpgmmsg msgid(usr6642) ... msgtype(*diag)
sndpgmmsg msgid(usr3285) ... msgtype(*diag)
sndpgmmsg msgid(usr1124) ... msgtype(*escape)

Put yourself in the user's place. Send messages unto others as you would have messages sent unto you.

                     Post this story to del.icio.us
               Post this story to Digg
    Post this story to Slashdot