Send Messages Unto Others
March 4, 2009 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.
Next, design a descriptive message, keeping the following ideas in mind.
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.