Send Program Message (SNDPGMMSG)

Send Program Message (SNDPGMMSG)

Where allowed to run: Compiled CL program or interpreted REXX (*BPGM *IPGM *BREXX *IREXX)
Threadsafe: Yes Parameters
Examples
Error messages

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.
Restrictions:

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.
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.

Top

Parameters

Keyword Description Choices Notes
MSG Message text, or Character value Optional, Positional 1
MSGID Message identifier Name Optional, Positional 2
MSGF Message file Qualified object name Optional, Positional 3
Qualifier 1: Message file Name
Qualifier 2: Library Name, *LIBL, *CURLIB
MSGDTA Message data field values Character value, *NONE Optional, Positional 4
TOPGMQ Call stack entry message queue Single values: *EXT
Other values: Element list Optional
Element 1: Relationship *PRV, *SAME
Element 2: Call stack entry identifier Element list
Element 1: Call stack entry Character value, *
Element 2: Module Name, *NONE
Element 3: Bound program Name, *NONE
TOMSGQ Send to non-pgm message queue Single values: *TOPGMQ, *SYSOPR
Other values (up to 50 repetitions): Qualified object name Optional
Qualifier 1: Send to non-pgm message queue Name, *HSTLOG
Qualifier 2: Library Name, *LIBL, *CURLIB
TOUSR To user profile Name, *SYSOPR, *ALLACT, *REQUESTER Optional
MSGTYPE Message type *INFO, *INQ, *RQS, *COMP, *DIAG, *NOTIFY, *ESCAPE, *STATUS Optional
RPYMSGQ Message queue to get reply Single values: *PGMQ
Other values: Qualified object name Optional
Qualifier 1: Message queue to get reply Name
Qualifier 2: Library Name, *LIBL, *CURLIB
KEYVAR CL var for KEYVAR (4) Character value Optional
CCSID Coded character set ID 1-65535, *HEX, *JOB Optional

Top

Message text, or (MSG)

Specifies the message text that is to be sent. A maximum of 3000 characters can be specified or, if you are prompting for this command in an interactive job, a maximum of 512 characters can be specified. The string must be enclosed in apostrophes if special characters (including blanks) are used. If this parameter is specified, a value cannot be specified for the Message identifier (MSGID) parameter, and *ESCAPE, *NOTIFY, or *STATUS cannot be specified for the Message type (MSGTYPE) parameter. If this parameter is specified, a value cannot be specified for the Message file (MSGF) parameter or the Message data field values (MSGDTA) parameter, because these types require that a message identifier also be specified.
Coded Character Set Identifier (CCSID) Considerations
The text supplied for 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 iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.

Top

Message identifier (MSGID)

Specifies the message identifier of a message description whose predefined message is being sent by the program to a message queue. If this parameter is specified, a value cannot be specified for the Message text, or (MSG) parameter.

Top

Message file (MSGF)

Specifies the message file that contains the predefined message to be sent. This parameter is required if a value is specified for the Message identifier (MSGID) parameter.
Qualifier 1: Message file

name

Specify the name of the message file which contains the predefined message to be sent.

Qualifier 2: Library

*LIBL

All libraries in the library list for the current thread are searched until the first match is found.

*CURLIB

The current library for the job is used to locate the message file. If no current library entry exists in the library list, QGPL is used.

name

Specify the library where the message file is located.

Top

Message data field values (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.

*NONE

There are no program-supplied substitution values used in the specified message.

character-string

Specify the character string that gives the substitution values in the specified predefined message that is sent by the program, or specify the name of the CL variable that contains the character string.
Coded Character Set Identifier (CCSID) Considerations
The text supplied for 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 for 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 iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter. For more information about the *CCHAR type fields, see the Add Message Description (ADDMSGD) command.

Top

Call stack entry message queue (TOPGMQ)

Specifies the call message queue to which the specified message is to be sent. The message queue can be the *EXT external queue or the call message queue associated with a call stack entry.
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 wait for 24 hours before the default reply is sent.
Messages sent to this queue can be 512 characters in length, but only 76 characters of text are shown on the Program Messages display.

Element 1: Relationship
Two parameter elements are used to specify the call stack entry message queue from which a message is to be removed. The first element specifies whether the message queue is associated with the program or procedure identified by the second element, or if it is associated with the caller of the program or procedure.

*PRV

The message is sent to the message queue of the call stack entry that is immediately previous to the one identified by the second element of this parameter. However, if the message queue immediately previous to the one identified by the second element 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 the second element of this parameter.

Element 2: Call stack entry identifier
The second element of this parameter has three elements. Element 1 specifies an OPM program or ILE procedure name or a special value. Element 2 specifies an ILE module name which is used as a qualifier for the value specified in element 1. Element 3 can specify either an OPM program name or an ILE program name or a service program name, depending on what is specified in element 1. Element 3 is also used as a qualifier for what is specified in element 1.

Element 1: Call stack entry

*

Specifies the OPM program or ILE procedure running this command.

name

Specify the name of the OPM program or ILE procedure used to identify the call stack entry.
If this element identifies an OPM program, the name specified can be a maximum of 10 characters. If this element identifies an ILE procedure, the name specified can be a maximum of 256 characters.
Nested procedure names can be specified by separating each procedure name with a colon (:). When specifying nested procedure names, the outermost procedure name is identified first, followed by its contained procedures. The innermost procedure name is identified last in the string.
Partial names of programs or procedures can be specified by placing three less-than symbols (<<<) at the beginning of the name or by placing three greater-than symbols (>>>) at the end of the name. If both the greater-than symbols and the less-than symbols are used, the program or procedure name specified is limited to 250 characters.
The system begins its search for the specified program or procedure name with the most recently called program or procedure.
When searching for a partial program or procedure name:

The less-than symbols (<<<) are truncated when specified only at the beginning of a program or procedure name and the remaining character string is right-justified. The remaining characters in the specified string are compared to the current program or procedure on the call stack, starting with the last position of the program or procedure name and comparing backward.
The greater-than symbols (>>>) are truncated when specified only at the end of a program or procedure name. The remaining characters in the specified string are compared to the current program or procedure on the call stack, starting with the first position of the program or procedure name.
The less-than symbols (<<<) and the greater-than symbols (>>>) are truncated when both are specified for a program or procedure name. The remaining characters are used to scan and compare the entire length of the specified string with the current program or procedure on the call stack.

Element 2: Module

*NONE

No ILE module qualifier is provided.

name

Specify the ILE module name to be used to identify the message queue.

Element 3: Program

*NONE

No program qualifier is provided.

name

Specify the program name to be used to identify the message queue.

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. The following special values can be specified for the first qualifier of the second element of this parameter:

*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 for qualifier 3 of this parameter. If no name is specified for qualifier 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, qualifier 3 must specify an ILE program or service program name or OPM program name. Qualifier 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.

Top

Send to non-pgm message queue (TOMSGQ)

Specifies 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 a value is specified for the To user profile (TOUSR) parameter.
Single values

*TOPGMQ

The message is sent only to the call message queue specified for the Call stack entry message queue (TOPGMQ) parameter.

*SYSOPR

The message is sent to the system operator message (message queue QSYSOPR in library QSYS). Any message sent to message queue QSYSOPR in library QSYS automatically has a copy of the message sent to the QHST (history log) message queue in library QSYS.

Qualifier 1: Send to non-pgm message queue

*HSTLOG

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

name

Specify the name of the message queue to which the message is to be sent. A maximum of fifty message queues can be specified.

Qualifier 2: Library

*LIBL

All libraries in the library list for the current thread are searched until the first match is found.

*CURLIB

The current library for the job is used to locate the message queue. If no current library entry exists in the library list, QGPL is used.

name

Specify the library where the message queue is located.

Top

To user profile (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 a value is specified for the Send to non-pgm message queue (TOMSGQ) parameter or the Call stack entry message queue (TOPGMQ) parameter.

*SYSOPR

The message is sent to the system operator (message queue QSYSOPR in library QSYS). Any message sent to message queue QSYSOPR in library QSYS automatically has a copy of the message sent to the QHST (history log) message queue in library QSYS.

*REQUESTER

The message is sent to the user profile message queue for interactive jobs or to the system operator's message queue (QSYSOPR in library QSYS) 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. *ALLACT cannot be specified with inquiry messages.

name

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

Top

Message type (MSGTYPE)

Specifies which message type is assigned to this message when it is sent by this program.
Notes:

Inquiry messages can be sent only to the external queue or to a named message queue specified for the TOUSR or TOMSGQ parameters. When sending an inquiry with the TOMSGQ parameter, a second queue can be specified if the value is *HSTLOG.
Completion, diagnostic, escape, notify, and status messages can be sent only to a call message queue.
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.

This value cannot be specified if the Message text, or (MSG) parameter, is specified.

Top

Message queue to get reply (RPYMSGQ)

Specifies, for inquiry and notify messages only, the call message queue or the non-program message queue to which the reply message is to be sent.
Single values

*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.

Qualifier 1: Message queue to get reply

name

Specify the name of the message queue to which the reply is sent.

Qualifier 2: Library

*LIBL

All libraries in the library list for the current thread are searched until the first match is found.

*CURLIB

The current library for the job is used to locate the message queue. If no current library entry exists in the library list, QGPL is used.

name

Specify the library where the message queue is located.

Top

CL var for KEYVAR (4) (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 command. The message reference key is assigned by the system when the message is sent and is placed in the variable specified here.
If a message is being sent to a message queue associated with a call stack entry, KEYVAR refers to that message queue (specified for the Call stack entry message queue (TOPGMQ) parameter). If *INQ or *NOTIFY is specified for the Message type (MSGTYPE) parameter, KEYVAR refers to the message queue specified for the Message queue to get reply (RPYMSGQ) parameter. In all other cases, KEYVAR refers to the message queue specified for the TOPGMQ parameter.
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.

Top

Coded character set ID (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 specified 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 supplied by the MSG (message) parameter is assumed to be in the CCSID supplied by the CCSID parameter. For more information about the message handler and its use of CCSIDs, see the Globalization topic in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.

*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 information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter for a list of valid CCSID values.

Top

Examples

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 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.

Top

Error messages

*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.

Top

Keyword	Description	Choices	Notes
MSG	Message text, or	Character value	Optional, Positional 1
MSGID	Message identifier	Name	Optional, Positional 2
MSGF	Message file	Qualified object name	Optional, Positional 3
	Qualifier 1: Message file	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
MSGDTA	Message data field values	Character value, *NONE	Optional, Positional 4
TOPGMQ	Call stack entry message queue	Single values: EXT Other values: Element list*	Optional
	Element 1: Relationship	PRV, SAME
	Element 2: Call stack entry identifier	Element list
	Element 1: Call stack entry	Character value, *
	Element 2: Module	Name, *NONE
	Element 3: Bound program	Name, *NONE
TOMSGQ	Send to non-pgm message queue	Single values: TOPGMQ, SYSOPR Other values (up to 50 repetitions): Qualified object name	Optional
	Qualifier 1: Send to non-pgm message queue	Name, *HSTLOG
	Qualifier 2: Library	Name, LIBL, CURLIB
TOUSR	To user profile	Name, SYSOPR, ALLACT, *REQUESTER	Optional
MSGTYPE	Message type	INFO, INQ, RQS, COMP, DIAG, NOTIFY, ESCAPE, STATUS	Optional
RPYMSGQ	Message queue to get reply	Single values: PGMQ Other values: Qualified object name*	Optional
	Qualifier 1: Message queue to get reply	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
KEYVAR	CL var for KEYVAR (4)	Character value	Optional
CCSID	Coded character set ID	1-65535, HEX, JOB	Optional