SND-MSG (Send a Message to the Joblog)

Free-Form Syntax

SND-MSG{(E)} { *INFO | *ESCAPE } message-text
{ %TARGET(*SELF | *CALLER | program-or-procedure {: offset-in-program-stack }) };

SND-MSG{(E)} { *INFO | *ESCAPE } %MSG(message-id : message-file {: replacement-text } )
{ %TARGET(*SELF | *CALLER | program-or-procedure {: offset-in-program-stack }) };

Code	Factor 1	Extended Factor 2
SND-MSG{(E)}		{ INFO \| ESCAPE } message-text { %TARGET(SELF \| CALLER \| program-or-procedure {: offset-in-program-stack }) }
SND-MSG{(E)}		{ INFO \| ESCAPE } %MSG(message-id : message-file {: replacement-text } ) { %TARGET(SELF \| CALLER \| program-or-procedure {: offset-in-program-stack }) }

The SND-MSG operation sends an informational message or an exception message. The message can be sent to any procedure on the call stack, including the current procedure. The message appears in the joblog after it is sent.

The first operand is optional. It indicates the type of message to send. The default is *INFO.

*INFO

An informational message is sent.

*ESCAPE

An escape message is sent. An escape message causes an exception.

If the message is sent to the current procedure, the current procedure fails with status code 9999 unless the exception is handled with a MONITOR group or a *PSSR subroutine.
If the message is sent to an earlier program or procedure on the call stack, the current procedure ends immediately, and exception handling in the target program or procedure can handle the exception.

The second operand specifes the message to send. It can be

A character, UCS-2 or graphic expression that can be converted to the job CCSID. If the message type is *INFO, the message is sent directly without a message ID. If the message type is *ESCAPE, the message ID defaults to CPF9898, the message file defaults to *LIBL/QCPFMSG, and the second operand is used as the replacement text for message CPF9898.
The %MSG built-in function, specifying the message ID, message file, and optional replacement text, for the message to be sent.

The third operand is optional. It specifes which program or procedure currently on the program stack that the message is sent to. It must be the %TARGET built-in function. If the third operand is not specified, the default depends on the message type.

If the message type is *INFO, the default is %TARGET(*SELF). The message is sent to the current procedure.
If the message type is *ESCAPE, the default is %TARGET(*CALLER). The message is sent to the caller of the current procedure.

If an error occurs while sending the message, the SND-MSG operation fails with status code 126. Operation extender E can be specified to handle status code 126.

Note: Status code 126 indicates that the message was not sent. For example, if the message file specified for %MSG does not exist, or the program or procedure specified for %TARGET is not on the program stack.

Note: API QMHSNDPM is used to send the message.

Examples of SND-MSG

The following example sends an informational message to the joblog. The message is sent to the current procedure. No message ID or message file is associated with the message.


SND-MSG 'Hello';

The following example sends an escape message to the joblog. The message is sent to the caller of the current procedure. Message ID CPF9898 in message file *LIBL/QCPFMSG is used to send the message.


SND-MSG *ESCAPE 'File ' + filename + ' not found';

The following example sends an escape message to the current procedure.

If message file MYMSGF exists, the SND-MSG operation sends the escape message to the current procedure. The ON-ERROR block for status code 9999 runs, and the program displays "Escape message".
If message file MYMSGF does not exist, the SND-MSG operation cannot be sent, and the operation fails with status code 126. The ON-ERROR block for status code 126 runs, and the program displays "SND-MSG error".


   MONITOR;
      SND-MSG *ESCAPE %MSG('ABC1234' : 'MYMSGF') %TARGET(*SELF);
   ON-ERROR 126;
      DSPLY 'SND-MSG error';
   ON-ERROR 9999;
      DSPLY 'Escape message';
   ENDMON;

For more examples of SND-MSG, see Examples of %MSG and Examples of %TARGET.