SNDPGMMSG (Send Program Message)

SNDPGMMSG Command syntax diagram

 

Purpose

The Send Program Message (SNDPGMMSG) command sends a message to a named message queue or to a call message queue. A call message queue can be the *EXT external message queue or a message queue associated with a call stack entry. Each time a program or procedure is called a new message queue is associated with its call stack entry. The message queue is identified by the name of its associated program or procedure.

A program can send a message to its own message queue or to a message queue that is associated with a different call stack entry.

This command can send both exception and non-exception messages. When an exception message is sent, processing of the sending program is interrupted until action is taken on the exception. Depending on the action taken, processing of the sending program may resume. If allowed to resume, processing continues in the sending program at the CL command immediately following the SNDPGMMSG command. When a non-exception message is sent, processing of the sending program is not interrupted. After the message is sent, the sending program continues to run at the CL command immediately following the SNDPGMMSG command.

When a program or procedure monitors for an exception message and an exception message is sent to the call stack entry in which that program or procedure is running, the related exception handler is called and run by the system. Therefore, a program or procedure can identify when an exception message is sent to the call stack entry in which it is running. There is no automatic notification for non-exception messages.

The message can be an immediate or a predefined message that is stored in a message file. Substitution data can be specified in the MSGDTA parameter (as a single character string containing one or more concatenated message data fields) to replace the substitution variables in the message. The message can be sent to the job's *EXT message queue, to a message queue associated with a call stack entry, to one or more nonprogram message queues (such as a user profile message queue), to the system operator message queue, or to the system history log, QHST.

 

Restrictions

1. This command is valid only in CL programs.
2. The SNDPGMMSG command allows a message of up to 512 characters to be sent. However, if the message is sent to the *EXT message queue of an interactive job, only 76 characters are shown on the Display Program Messages display. If the message is sent to a user's, work station's, or the system operator's message queue, the Display Message (DSPMSG) command allows all 512 characters to be displayed.
3. This command can only send inquiry messages (specified by MSGTYPE(*INQ)) to one message queue or to two nonprogram message queues if one of the queues is *HSTLOG.

 

Required Parameters

MSG

Specifies the message text that is sent. A maximum of 3000 characters can be specified or, if you are prompting for this command, a maximum of 512 characters can be specified. The string must be enclosed in apostrophes if special characters (including blanks) are used. If a value is specified on this parameter, the MSGID, MSGF, and MSGDTA parameters cannot be specified.

Coded Character Set Identifier (CCSID) Considerations

The text supplied on the MSG parameter is assumed to be in the CCSID of the job running this command unless a coded character set identifier is supplied in the CCSID parameter. For more information about the message handler and its use of CCSIDs, see the Globalization topic in the Information Center.

MSGID

Specifies the message identifier of a message description whose predefined message is being sent by the program to a message queue. If MSGID is specified, the MSG parameter cannot be specified.

MSGF

Specifies the qualified name of the message file that contains the predefined message being sent. This parameter is required if MSGID is specified.

The name of the message file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

message-file-name: Specify the name of the message file that contains the predefined message.

 

Optional Parameters

MSGDTA

Specifies the character string, or a CL variable that contains a character string, containing one or more substitution values that are used as message data fields within the predefined message. The substitution values take the place of the substitution variables that were defined in the message text when the message was defined.

Note:

MSGDTA is not valid if MSG is specified.

Rules for Replacing CL Variables with Character Strings

• Multiple values must be concatenated to form a single character string (more information is in the CL Programming book).
• If more than one substitution variable exists in the message, the specified character string must be the same length as the sum of the message data fields defined in the message.
• The length of the entire character string of concatenated substitution values cannot be greater than 3000 characters, or if you are prompting for this command, the length cannot be greater than 512 characters. More information about the length of individual message data fields is in the FMT parameter description in the ADDMSGD (Add Message Description) command.
• Each substitution value, specified in the same order in the string as defined in the FMT parameter of the ADDMSGD command, must be specified but only if its associated variable was defined.
• If the length of the message data that is passed to a substitution variable is shorter than the length specified for the FMT parameter of the ADDMSGD command, the substitution value becomes a null field.
• If the length of the message data passed to a substitution variable is longer than the length specified for ADDMSGD FMT, the message data is truncated.

  Note:

  If the last character in the string passed to the substitution variable is blank (for the format types *BIN, *ITV, or *DTS, a blank is indicated by the hex value 40), the system truncates the blank. If the resulting string is shorter than the length specified on the FMT parameter of the ADDMSGD command, the substitution variable becomes a null field. To prevent the system from truncating the blanks, concatenate a nonblank character (for the format type *BIN, *ITV, and *DTS, add value other than 40) to the string after the blanks. The system retains the blanks and truncates the additional character.

*NONE: No message data is supplied for the message.

character-string: Specify either the character string that gives the substitution values in the specified predefined message sent by the program, or the name of the CL variable that contains the character string.

If the message contains more than one substitution variable, the character string containing the replacement values must be coded with the proper fill characters (zeros for numeric values, and blanks for character values) to position the values properly in the string to match the concatenated fields used to create the single string. If the string contains special characters (including blanks), it must be enclosed in apostrophes. The null value *N cannot be specified for a substitution value.

For example, if a predefined message contains the following three substitution variables:

Variable	Format Type	Length	Expected Values
&1	*CHAR	3 characters	Yes or no
&2	*CHAR	4 digits	4 digits
&3	*CHAR	8 characters	One or two words

the following valid character strings can be specified:

MSGDTA('Yes0007not done')
MSGDTA('No 0285finished')
MSGDTA(&DTA)

Note that the variable &2 is defined as a character variable, not as a decimal variable. If a character string is to be used instead of a CL variable to specify the substitution values in the MSGDTA parameter, the associated substitution variables must be defined (in the FMT parameter of the ADDMSGD command) as character variables to prevent results that are not valid in the text of the message that is sent.

The last example shows, instead of the actual character string, the CL variable &DTA, whose value is used as the message data. &DTA might have been declared in the sending program as:

DCL   VAR(&DTA)  TYPE(*CHAR)
  LEN(15)  VALUE('YES0175not done')

The character string, specified as the initial value for &DTA, contains the three concatenated substitution values YES, 0175, and not done, which are to be sent as message data.

Coded Character Set Identifier (CCSID) Considerations

The text supplied on the MSGDTA parameter that corresponds to the *CCHAR type field is assumed to be in the CCSID of the job running this command unless the coded character set identifier is supplied in the CCSID parameter. All other text supplied on the MSGDTA parameter is assumed to be 65535 and is not converted. For more information about the message handler and its use of CCSIDs, see the Globalization topic in the Information Center. For more information about the *CCHAR type fields, see the Add Message Description (ADDMSGD) command.

TOUSR

Specifies that the message is to be sent to the message queue specified in the user profile for the user named on this parameter. This parameter cannot be used if TOMSGQ or TOPGMQ is specified.

*SYSOPR: The message is sent to the system operator's message queue, QSYS/QSYSOPR. Any message sent to QSYSOPR automatically has a copy of the message sent to QHST.

*REQUESTER: The message is sent to the user profile's message queue for interactive jobs or to the system operator's message queue (QSYS/QSYSOPR) for batch jobs.

*ALLACT: A copy of the message is sent to the user profile message queue of each user profile with an interactive job currently running. This value cannot be specified if an inquiry message is being sent (the value *INQ is specified in the MSGTYPE parameter).

user-profile-name: Specify the name of the user profile of the user to whom the message is sent.

TOMSGQ

Specifies the qualified names of up to 50 nonprogram message queues to which an informational message is sent. For an inquiry message, one message queue may be specified or two message queues may be specified if one of the queues is *HSTLOG. This parameter cannot be used if TOUSR is specified.

*TOPGMQ: The message is sent only to the call message queue specified on the TOPGMQ parameter.

*SYSOPR: The message is sent to the system operator's message queue, QSYS/QSYSOPR. Any message sent to QSYSOPR automatically has a copy of the message sent to QHST.

The name of the message queue can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

message-queue-name: Specify the names of the message queues to which the message is sent. Up to 50 names can be specified.

*HSTLOG: The message is sent to the system history log message queue, QSYS/QHST. If *HSTLOG is specified more than once, only one message will be sent to QSYS/QHST. If *HSTLOG is specified with QSYSOPR only one message is sent to QSYS/QHST.

TOPGMQ

Specifies the call message queue to which the message is sent. The call message queue can be the *EXT external queue or the call message queue associated with a call stack entry.

Element 1: Relationship

Element 1 of this parameter specifies whether the message queue is associated with the call stack entry identified by Element 2, or if it is associated with the call stack entry that is immediately previous to the one identified by Element 2.

*PRV: The message is sent to the message queue of the call stack entry that is immediately previous to the one identified by Element 2. However, if the message queue immediately previous to the one identified by Element 2 is for an Integrated Language Environment (ILE) program entry procedure (PEP), the message is sent to the message queue that precedes the PEP message queue in the stack.

*SAME: The message is sent to the message queue of the call stack entry identified by Element 2.

Element 2: Program or Qualified Procedure

Element 2 is used to provide the information needed to identify a call stack entry. A call stack entry can be identified by specifying the name of the OPM program or ILE procedure that is running in that entry. It can also be identified by using a special value or a special value used in conjunction with a name.

Element 2 of this parameter has three items. Item 1 specifies an OPM program or ILE procedure name or a special value. Item 2 specifies an ILE module name which is used as a qualifier for the value specified in item 1. Item 3 can specify either an OPM program name or an ILE program name depending on what is specified in item 1. Item 3 is also used as a qualifier for what is specified in item 1.

Item 1: Program or Procedure Name

*: Identifies the OPM program or ILE procedure running the SNDPGMMSG command.

OPM-program or ILE-procedure name: Specify the OPM program name or ILE procedure name which will be used to identify the call stack entry. If item 1 is to identify an OPM program, the name specified can be a maximum of 10 characters. If item 1 is to identify an ILE procedure, the name specified can be a maximum of 256 characters. The system begins its search for the specified program or procedure with the most recently called program or procedure.

If an ILE procedure name is specified, that name may be further qualified by using items 2 and 3 to specify an ILE module name and an ILE program name. The module name identifies the module that procedure was compiled into. The program name identifies the program that the procedure was bound into. Either one or both of these items may be specified. When a module name or program name is specified, the corresponding call stack entry will not only be running a procedure by the specified name but that procedure will also be part of the specified module and specified program. Specify the name of the program or procedure used.

If Item 1 identifies a program, the name specified can be a maximum of 10 characters. If Item 1 identifies a procedure, the name specified can be a maximum of 256 characters.

The procedure name alone may not identify the correct procedure. Several different procedures with the same name can run in a job. To further identify a procedure, the name specified can be qualified by a module name, or by both a module name and a bound program name.

*CTLBDY: Specifies the call stack entry that is at the most recent control boundary. This entry will be running in the same activation group as the CL program that is running the SNDPGMMSG command. Note that a control boundary will not exist if all programs on the call stack are OPM programs.

*PGMBDY: Specifies the program boundary of either the program that is using the SNDPGMMSG command or the program whose name is specified in item 3. If no name is specified in item 3, it is assumed that the program is the one using the command.

If it is an ILE program that is being specified, this special value identifies the call stack entry for the program entry procedure (PEP) of that program, if the program was called by a dynamic call. If the program was called by a procedure pointer, this special value identifies the call stack entry for the procedure that was pointed to.

If it is an ILE service program that is being specified, this special value identifies the call stack entry for the first procedure that was called in that service program.

If the program being specified is an OPM program, this special value has the same effect as specifying the special value * or a program name for item 1. A difference will occur if the OPM program has called itself recursively. In this case, this special value identifies the first recursion level rather than the current recursion level as would be the case if the special value * or a program name was used.

*PGMNAME: Specifies that the call stack entry will be identified only by using a program name and optionally a module name. When this special value is used, item 3 must specify an ILE program or service program name or OPM program name. Item 2 may contain either the special value *NONE or an ILE module name.

This special value is used to send a message to the most recently called procedure that is part of the specified ILE program or service program. When using this special value, it is not necessary to explicitly provide a procedure name. If a module name is also provided, then this special value is used to send a message to the most recently called procedure that is both part of the identified program and the identified module.

This special value may also be used to send a message to an OPM program. In this case, using this special value and providing the OPM program name in item 3 has exactly the same effect as providing that program name here in item 1. Note that if this special value is being used to send to an OPM program then the module name must be specified as *NONE.

Item 2: ILE Module Name

The module name qualifier identifies the ILE module into which an ILE procedure was compiled.

*NONE: No module name is specified.

ILE-module-name: Specify the ILE module name that is to be used as a qualifier for the value specified in item 1. A module name can be specified if item 1 contains an ILE procedure name or the special value *PGMNAME. The module name can be a maximum of 10 characters.

Use the special value *NONE when a module name is not being specified but a program name is in item 3.

Item 3: OPM Program Name or ILE Program Name

The ILE program or service program name or OPM program name that is to be used in conjunction with the procedure name or special value that is specified in item 1.

*NONE: No ILE or OPM program name is specified.

ILE-program-name: Specify the ILE program or service program name that is to be used as a qualifier for the value specified in item 1. An ILE program or service program name can be specified if item 1 contains an ILE procedure name or one of the special values of *PGMBDY or *PGMNAME. The ILE program or service program name can be a maximum of 10 characters.

OPM-program-name: Specify the OPM program name that is to be used as a qualifier for the value specified in item 1. An OPM program name can be specified if item 1 contains the special value of *PGMBDY or *PGMNAME. The OPM program name can be a maximum of 10 characters.

Single Values

*EXT: The message is sent to the external message queue of the job. The external message queue is used to communicate with the external requester of the job, such as a display station user. *INQ messages that are sent to *EXT in an interactive job wait for 24 hours before the default reply is sent. In a batch job the default reply is sent immediately.

Messages sent to this queue can be 512 characters in length, but only 76 characters of text are shown on the Program Messages display.

MSGTYPE

Specifies the message type assigned to a message sent by this program.

 

Notes

1. Inquiry messages can be sent only to the external queue or to a named message queue specified on the TOUSR or TOMSGQ parameters. When sending an inquiry with the TOMSGQ parameter, a second queue can be specified if the value is *HSTLOG.
2. Completion, diagnostic, escape, notify, and status messages can be sent only to a call message queue.
3. Escape messages cannot be sent to the external message queue.

*INFO: The message is sent as an informational message.

*INQ: The message is sent as an inquiry message.

*COMP: A completion message is sent to a call message queue. A completion message indicates the status of the work that is successfully performed.

*DIAG: A diagnostic message is sent to a call message queue. Diagnostic messages provide information about errors detected by this program. The errors are either in the input sent to it, or are those that occurred while it was running the requested function. An escape or notify message should also be sent to inform the receiving program or procedure of the diagnostic messages that are on its message queue.

*NOTIFY: A notify exception message is sent to a call message queue. A notify message describes a condition for which corrective action must be taken before the sending program can continue. A reply message is sent back to the sending program. After corrective action is taken, the sending program can resume running and can receive the reply message from its message queue.

*ESCAPE: An escape exception message is sent to a call message queue. An escape message describes an irrecoverable error condition. The sending program does not continue to run.

*RQS: A request message is sent to a call message queue. A request message allows request data received from device files to pass from this program to another program or procedure. An immediate message, specified by the MSG parameter, must be used to send the request.

*STATUS: A status exception message is sent to a call message queue. The status message describes the status of work performed by the sending program. The first 28 characters of message data in the MSGDTA parameter are used as the comparison data for message monitors (established by the Monitor Message (MONMSG) command). If the status exception message is not being monitored, control is returned to the sending program. If a status message is sent to the external message queue of an interactive job, the message is shown on line 24, processing continues, and no response is required.

Note:

This value cannot be specified if the MSG parameter is specified.

RPYMSGQ

Specifies, for inquiry and notify messages only, the name of the call message queue or the qualified name of the nonprogram message queue to which a reply message is sent. If a notify message is sent, or an inquiry message is sent to *EXT, the reply message queue must specify *PGMQ.

*PGMQ: The reply to an inquiry or notify message is sent to the message queue associated with the call stack entry of the program or procedure using this command.

The name of the nonprogram message queue can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

message-queue-name: Specify the name of the message queue, that is not for a program, to which the reply is sent.

CCSID

Specifies the coded character set identifier (CCSID) that the supplied message or message data is in. If a message identifier is specified, the text supplied by the MSGDTA (message data) parameter that corresponds to the *CCHAR type field is assumed to be in the CCSID supplied by the CCSID parameter. The data supplied that does not correspond to the *CCHAR type field is assumed to be 65535 and is not converted. For more information about the *CCHAR type field see the Add Message Description (ADDMSGD) command.

If no message identifier is specified, the text specified by the MSG (message) parameter is assumed to be in the CCSID specified by the CCSID parameter. For more information about the message handler and its use of CCSIDs, see the Globalization topic in the Information Center.

*JOB: The message data or immediate text is assumed to be in the CCSID of the job running this command.

*HEX: The message data or immediate text is not converted. CCSID 65535 is used.

coded-character-set-identifier: Specify a valid CCSID in which you want your message or message data to be considered in. Valid values range from 1 through 65535. This command validates the CCSID. See the Globalization topic in the Information Center for a list of valid CCSID values.

KEYVAR

Specifies the name of the CL character variable, if any, that contains the message reference key that identifies the message sent by the program containing this SNDPGMMSG command. The message reference key is assigned by the system when the message is sent and is placed in the variable specified by KEYVAR. The message key can then, for example, be used in the MSGKEY parameter of the RCVMSG command to receive the reply to an inquiry message being sent by this command. The message reference key can be used by the program specified on the TOPGMQ parameter for building message subfiles. The CL variable is the name of the field for which the SFLMSGKEY keyword is specified in the DDS for the message subfile.

If a message is being sent to a message queue associated with a call stack entry, KEYVAR refers to that message queue (specified by the TOPGMQ parameter). If *INQ or *NOTIFY is specified for the MSGTYPE parameter, KEYVAR refers to the message queue specified in the RPYMSGQ parameter. In all other cases, KEYVAR refers to the message queue specified in the TOMSGQ parameter.

If an inquiry message has been sent to the *EXT message queue with a value specified for the KEYVAR parameter, the message reference key returned is that of the sender's copy message, which is located on the reply message queue. The reply message queue defaults to the program message queue of the program that sent the inquiry message.

Any type of message can be assigned a key when it is being sent to a program message queue. For messages sent to a nonprogram message queue, message reference keys are available for inquiry (*INQ) messages only. If another message type is sent to a nonprogram queue, no message key is available and blanks are returned for KEYVAR.

The variable must be a character variable having a length of 4 characters. If KEYVAR is not specified and a reply is required, it can be received by the program in FIFO order.

Examples for SNDPGMMSG

Example 1: Specifying Substitution Values

SNDPGMMSG   MSGID(UIN0023)  MSGF(INV)
  MSGDTA('50 100')  TOPGMQ(*EXT)

This command sends the message identified as UIN0023, which is stored in message file INV, to the external message queue of the job (the Display Program Messages presents the message at a display station). The data, which contains two substitution values specified in the MSGDTA parameter, is sent with the message. This data can then be used as substitution values when the message is received, or it can be used as data to be dumped, depending on how the message UIN0023 is defined in the message file. Assuming that the variables &1 and &2 have been defined in the message file as character variables, each 3 characters long, and that the first-level message text of the message UIN0023 is: 'Requested item decreased by &1; current balance &2.' The message text sent is: 'Requested item decreased by 50; current balance 100.'

Example 2: Sending an Inquiry Message

SNDPGMMSG   MSG('Mount payroll checks in printer
  before continuing')  MSGTYPE(*INQ)
  TOMSGQ(*SYSOPR)

This command sends an inquiry message to the system operator. The operator looks at the message that was sent by using the DSPMSG command and responds to the message directly on that display. A Receive Message (RCVMSG) command is used in the program to accept the operator's response.

Example 3: Sending an Escape Message

SNDPGMMSG   MSGID(USR0001)  MSGF(USRMSGR)
  TOPGMQ(*PRV  *)  MSGTYPE(*ESCAPE)

This command is an example of how a message could be sent to the caller of a program or procedure to cause an abnormal end. The message USR0001 could indicate that an invalid code was passed (such as a nonnumeric code when numeric is required). Because the message being sent is an escape message, the program or procedure that is sending the message cannot be resumed. The values *PRV and * did not have to be coded on this command because they are the default values on the TOPGMQ parameter.

Example 4: Sending an Escape Message to an ILE Procedure

SNDPGMMSG   MSGID(USR0001)  MSGF(USRMSGR)
  TOPGMQ(*SAME ACCOUNT_FINAL_TOTALS)  MSGTYPE(*ESCAPE)

This command sends a message to an ILE procedure. In this example, the call stack entry identifier is more than 10 characters. Since no qualifier is specified, the actual module name and bound program name associated with the procedure are not used in finding the procedure. The escape exception message is sent to the message queue associated with ACCOUNT_FINAL_TOTALS because *SAME is specified for Element 1.

Example 5: Sending an Escape Message using Qualifiers

SNDPGMMSG   MSGID(USR0001)  MSGF(USRMSGR)
  TOPGMQ(*PRV FIRST_QTR_SUMMARY SUMQTRS REPORTS)
  MSGTYPE(*ESCAPE)

This command sends an escape exception message to the caller of the procedure FIRST_QTR_SYMMARY. The procedure is qualified by the module name SUMQTRS and the bound program name REPORTS. The escape exception message interrupts the sending program and the sending program is not resumed.

Example 6: Sending a Completion Message using a Partial Procedure Name

SNDPGMMSG   MSGID(USR0001)  MSGF(USRMSGR)
  TOPGMQ(*SAME MANAGE_SALES>>>)
  MSGTYPE(*COMP)

This command sends a completion message to the most recent procedure whose name begins with MANAGE_SALES.

Error messages for SNDPGMMSG

*ESCAPE Messages

CPF24CB

*PGMNAME requires a specified program name.

CPF2409

Specified message type not valid with specified program message queue.

CPF2428

Message queue parameter is not valid.

CPF2453

Reply queue not sender's program message queue.

CPF2469

Error occurred when sending message &1.

CPF247A

Call stack entry not found.

CPF247E

CCSID &1 is not valid.

CPF2499

Message identifier &1 not allowed.

CPF2524

Exception handler not available because of reason code &1.

CPF2550

Exception message sent to a deleted program or procedure.

CPF2702

Device description &1 not found.

CPF7C08

No support network connection.

CPF8C0C

Content of problem record &1 not valid.

CPF8C0E

Library QGPL not found.

CPF8C01

Cannot connect to IBM service system. One session allowed.

CPF8C07

A parameter is not valid.

CPF8C08

Cannot specify *SELECT for the control point name.

CPF8C09

&1 not defined as a service provider.

CPF8C16

Error occurred while processing request.

CPF8C17

Sign-on failed.

CPF8C18

No support network connection.

CPF8C19

Remote support application failed.

CPF8C2A

Cannot connect to IBM service system.

CPF8C24

Error occurred while processing request.

CPF8C27

Alternate load device not found.

CPF8C32

PTF order cannot be processed.

CPF9830

Cannot assign library &1.

CPF9845

Error occurred while opening file &1.

CPF9846

Error while processing file &1 in library &2.

CPF9847

Error occurred while closing file &1 in library &2.