Send Program Message (QMHSNDPM) API

The Send Program Message (QMHSNDPM) API sends a message to a call message queue or the external message queue. (The external message queue is the part of the job message queue that handles messages between an interactive job and the work station user. It is not associated with a specific call stack entry.) This API allows the current call stack entry to send a message to its caller, a previous caller, or itself.

In a multithreaded job, messages can be sent only to call message queues in the thread in which this API is called or to the external message queue. Messages cannot be sent to call message queues in other threads.

To send a message to a nonprogram message queue, see Send Nonprogram Message (QMHSNDM) API.

Before coding your call to the QMHSNDPM API, see Dependencies among Parameters.

Authorities and Locks

Message File Authority

*USE

Message File Library Authority

*EXECUTE

Required Parameter Group

Message identifier

INPUT; CHAR(7)

The identifying code for the predefined message being sent, or blanks for an immediate message.

When sending an escape, notify, or status message, you must specify a message identifier. When sending a request or command message, you must use blanks. When sending other types of messages, you can use either a message identifier or blanks.

If you specify a message identifier, you must specify a qualified message file name. If you do not specify a message identifier, the API ignores the qualified message file name parameter.

Qualified message file name

INPUT; CHAR(20)

For a predefined message, the name of the message file and the library in which it resides. The first 10 characters specify the file name, and the second 10 characters specify the library. You can use these special values for the library name:

*CURLIB	The job's current library
*LIBL	The library list

For an immediate message, use blanks for this parameter. If you specify a name, the API ignores it and does not return an error.

Replacement data or impromptu message text

INPUT; CHAR(*)

If a message identifier is specified, this parameter specifies the data to insert in the predefined message's substitution variables. If blanks are used for the message identifier, this parameter specifies the complete text of an immediate message.

If this parameter contains pointer data, each pointer must start on a 16-byte boundary to keep the data accurate.

Length of replacement data or impromptu message text

INPUT; BINARY(4)

The length of the replacement data or impromptu message text, in bytes. Valid values for each are:

Message data	0-32767
Immediate text	1-6000

Message type

INPUT;CHAR(10)

The type of the message. You must specify one of these values:

*CMD	Command
*COMP	Completion
*DIAG	Diagnostic
*ESCAPE	Escape
*INFO	Informational
*INQ	Inquiry. You can send inquiry messages only to the external message queue.
*NOTIFY	Notify
*RQS	Request
*STATUS	Status

Call stack entry

INPUT; CHAR(*) or Pointer

The call stack entry to send the message to, or the call stack entry to start counting from when using a value other than 0 for the Call stack counter parameter. The call stack entry you specify must be in the call stack. You can also specify the external message queue.

You can specify a call stack entry by providing the name of the OPM program or ILE procedure running in the entry, by providing an invocation pointer to the call stack entry, or by using one of the following special values:

*	The current call stack entry (that is, the one in which the program or procedure is using this API is running).
*PGMBDY	The call stack is for the boundary of the specified program object. The program object is identified explicitly by providing a program name in the optional Call stack entry qualification parameter. The program object can be specified by either not using the call stack entry qualification optional parameter or by specifying *NONE for the program name. In this case, the program object is assumed to be the program that is using this API. This option essentially identifies the oldest call stack entry that began a sequence of calls, and each call in this sequence involved the same program object. The call sequence could involve recursive calls to the same program or, in the case of ILE, calls to different procedures of the same ILE program or ILE service program. For OPM programs, in most cases using *PGMBDY produces the same results as using * or an OPM program name. A difference will appear when an OPM program calls itself recursively. In this case, using * or an OPM program name identifies the current recursion level of the program. In contrast, *PGMBDY identifies the first recursion level. For an ILE program, this option can be used to identify the first procedure of the ILE program that was called in the current sequence. If the ILE program was called using a dynamic call, this is the PEP (program entry procedure) of the ILE program. If sequence was started by calling by means of a procedure pointer, this is the call stack entry for the procedure that was pointed to. For ILE service programs, this special value can be used to identify the call stack entry for the first procedure called in the specified service program.
*CTLBDY	The call stack entry at the most recent control boundary. This call stack entry is in the same activation group as the one that is using the API. If this key word value is used and there is no control boundary in the current call stack, the error CPF24C8 is returned to the user of this API. This would happen if the only entries on the call stack are for OPM programs. In some cases, *PGMBDY and *CTLBDY will identify the same call stack entry. The option *CTLBDY does not care if all call stack entries in a call sequence involve the same program object. It cares only that a sequence started at a control boundary. Conversely, the start of a call sequence identified by *PGMBDY may not fall on a control boundary.
*PGMNAME	The call stack entry is identified entirely by the program name and optionally module name that is provided by the optional Call stack entry qualification parameter. For OPM programs, specifying this special value and the optional parameter is the same as specifying the OPM program name directly in this required parameter. For ILE programs or ILE service programs, this special key value is used to indicate that a procedure name is not being specified. Rather the call stack entry is identified by providing only the ILE program or service program name and optionally the ILE module name. This means that the call stack entry will be the most recently called procedure that is part of the specified ILE program or service program (and part of the ILE module if module name is also specified). The name of this most recently called procedure is not important in determining the correct call stack entry. If this key value is specified with a program name only, then the call stack entry is the most recently called OPM program that has the specified program name or the most recently called ILE procedure that is part of an ILE program or service program of the specified name, whichever is most recent on the call stack. If the module name is also specified, then the call stack entry is the most recently called ILE procedure that is part of the specified ILE program or service program and module. If module name is given then the call stack entry cannot be an OPM program.
*EXT	The external message queue. The Call stack counter parameter is ignored. You cannot send escape or command messages to this message queue. If you are sending an inquiry message, you must specify this message queue. If you are sending a status message to *EXT in an interactive job, the message is displayed at the bottom of the current job's display station.

If the call stack entry is to be identified by pointer, the pointer that is specified must address a valid call stack entry within the same job as the one the API is used in. Alternatively, the pointer can be set to Null. The Optional Parameter Group 1 must be used and the Length of Call Stack Entry parameter must be set to 16. In addition, the Optional Parameter Group 2 must also be used and the Call Stack Entry Format parameter must be set to *PTR. A couple ways to obtain an invocation pointer is from the exception data in a C program and from the Materialize Invocation Attributes (MATINVAT) MI instruction.

If the pointer provided is set to Null, this indicates that the call stack entry is the one in which the API is being used.

The call stack entry can be a nested procedure name from 1 through 4096 characters in length. When specifying nested procedures, each procedure name must be separated by a colon, and the outermost procedure is identified first followed by the procedures it contains. The innermost procedure is the last procedure identified in the string.

The call stack entry can be a partial name. To specify a partial name, place three less-than signs (<<<) at the beginning of the call stack entry identifier, or place three greater-than signs (>>>) at the end of the call stack entry identifier, or place both the less-than signs and the greater-than signs at their respective ends of the call stack entry identifier. The value for the call stack entry excluding the less-than signs and the greater-than signs is used to search backward through the stack for the requested call stack entry name.

When searching for a partial call stack entry name:

• If the less than signs (<<<) are specified only at the beginning of the call stack entry name, the less-than signs are truncated and the remaining character string is right-justified. The remaining string is then compared to the current call stack entry on the call stack. The comparison starts at the end of the call stack entry name and backwardly compares the number of characters in the specified string.
• If the greater-than signs (>>>) are specified only at the end of the call stack entry name, the greater-than signs are truncated. The remaining character string is compared to the current call stack entry on the call stack. The comparison starts at position 1 of the call stack entry name and compares the number of characters in the specified string.
• If the less-than signs (<<<) are specified at the beginning of the call stack entry name and the greater-than signs (>>>) are specified at the end of the call stack entry name, both the less-than signs and the greater-than signs are truncated. The remaining characters are used to scan and to compare the entire length of the specified string and the current call stack entry on the call stack.

Note: If the optional parameters Length of to call stack entry and To call stack entry data type are not specified, this parameter is assumed to be CHAR(10).

Call stack counter

INPUT; BINARY(4)

A number identifying the location in the call stack of the call stack entry to whose message queue the message is to be sent. The number is relative to the call stack entry identified by the Call stack entry parameter. It indicates how many calls up the call stack the target entry is from the one identified by the Call stack entry parameter. Valid values follow:

0	Send the messages to the message queue of the entry specified by the Call stack entry parameter.
1	Send the messages to the message queue of the call stack entry one earlier on the stack than the one identified by the Call stack entry parameter.
n (any positive number)	Send the messages to the queue of the nth call stack entry earlier in the stack from the one identified by the Call stack entry parameter. You can use any positive number that does not exceed the actual number of call stack entries in the call stack. Do not include the external message queue in your count.

Message key

OUTPUT; CHAR(4)

The key to the message being sent. This API assigns the key when it sends a message of any type except status. For a status message, no key is returned and this parameter is not changed.

For inquiry and notify messages, this is the key to the sender's copy of the message in the sending program's message queue.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

Note: The API does not return an error code for the message type of *STATUS if the qualified message file name parameter is specified incorrectly, unless the call stack entry parameter is the special value *EXT.

Optional Parameter Group 1

Length of call stack entry

INPUT; BINARY(4)

The length of the value for the Call stack entry parameter. Valid values for this parameter are as follows:

• 1 through 4096 if partial name indicators are not used.
• 16 if the call stack entry parameter is a pointer.
• 1 through 4102 if partial name indicators are used.

Note: The actual length of the call stack entry name cannot exceed 4096 characters. If this parameter is not used, the value for the call stack entry parameter is assumed to be 10 characters in length.

Call stack entry qualification

INPUT; CHAR(20)

This parameter is used when it is necessary to further identify the call stack entry. The parameter consists of two 10 character parts. The first part is the module name qualifier and the second part is the program name qualifier. The values provided in this parameter are used as a qualifier for the value provided in the Call stack entry parameter. The values that can be specified here depend upon the value provided in the Call stack entry parameter.

The following special value may be used to indicate that the module name qualifier or program name qualifier is not being specified:

*NONE

This value can be used for the value of the module name qualifier, program name qualifier, or both to indicate that no qualifier is being specified.

If the Call stack entry parameter contains an ILE procedure name then this parameter can contain the name of the module and program that the procedure was compiled and bound into. The module and program name qualifiers are used to distinguish the correct call stack entry in the case where different procedures of the same name are on the call stack at the same time. The first 10 characters specify the module name, and the second 10 characters specify the ILE program or Service program name. If *NONE is specified for both the module and program name qualifiers, only the specified procedure name is used to determine the call stack entry.

If the Call stack entry parameter contains the key value *PGMNAME, then the program name qualifier must contain either an OPM program name or an ILE program or service program name. For ILE, the module name qualifier may contain a module name; otherwise it must contain *NONE.

When the Call stack entry parameter specifies the special value * or *CTLBDY, both the module name qualifier and program name qualifier must be specified as *NONE.

When the Call stack entry parameter specifies an OPM program name, both the module name and program name qualifiers should be specified as *NONE. If a module name or program name is specified here, the name specified in the Call stack entry parameter is interpreted as an ILE procedure name rather than an OPM program name. Either the entry would not be found or an incorrect entry would be found.

When the Call stack entry parameter specifies the special value *PGMBDY, the module name qualifier must be specified as *NONE. For the program name qualifier, an OPM, ILE program, or ILE Service program name may be specified or *NONE may be used.

If the Call stack entry is identified by pointer, this parameter must still be passed to the API. The value specified for the module name qualifier must be set to *NONE. The program name qualifier serves as a qualifier for the pointer and must be specified as one of the following special values:

*NONE

The call stack entry addressed by the pointer is the one to which the message is to be sent or the one to start counting from when using a value other than 0 for the Call stack counter parameter.

*PGMBDY

The call stack entry to send the message to or to start counting from is an ILE program or Service program boundary. The ILE program or Service program is the one which contains the procedure that is running in the call stack entry addressed by the pointer. If the ILE program was called using a dynamic call, using this special value with a pointer will identify the call stack entry for the PEP of that program. If the call was made using a procedure pointer, it will identify the call stack entry for the procedure that was pointed to. If the pointer addresses a call stack entry that is running a procedure from an ILE service program, this option can be used to identify the call stack entry for the first procedure that was called in that service program. If the call stack entry addressed by the pointer is running an OPM program than using the special value *PGMBDY here will have the same effect as using *NONE in most cases. A difference will occur if the OPM program called itself recursively. In this case using *PGMBDY identifies the first recursion level while *NONE identifies the current recursion level.

Display program messages screen wait time

INPUT; BINARY(4)

The amount of time in seconds to wait on the display program messages screen for any user action when a message is sent to an external message queue. If there is no user action within the specified time, the control returns to the statement following the call of this API. Valid values follow:

-1	Wait on the display program messages screen for the maximum length of time allowed by the system (24 hours). If this parameter is not specified, this is the default.
0	Send the message, but do not show the display program messages screen.
>0	The amount of time to wait in seconds for user action. If there is no user action within the time, then control returns. If the display file currently being displayed is defined with the restore display attribute of *NO, the Display Program Messages screen wait time parameter is ignored.

Optional Parameter Group 2

Call stack entry data type

INPUT; CHAR(10)

The value of the Call stack entry parameter is a character string (a name or special value) or a pointer.

Use one of the following special values:

*CHAR	Value of the parameter is a character string (name or special value)
*PTR	Value of the parameter is a pointer.

If the above optional parameter is not specified, it is assumed that the value of the Call stack entry parameter is a character string.

Coded character set identifier

INPUT; BINARY(4)

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

If no message identifier is specified, the text supplied by the message data or immediate text parameter will all be assumed to be in the CCSID supplied by this parameter. For more information about message handler and its use of CCSIDs, see CCSID support for messages. The following values are allowed:

0	The message data or immediate text is assumed in the CCSID of the job running this API. This is the default value if this parameter is not specified.
65535	The message data or immediate text will not be converted.
CCSID	Specify a valid CCSID that your message data or immediate text is in. Valid values are between 1 and 65535. This API will validate the CCSID.

Dependencies among Parameters

You can use many different combinations of parameters when calling the QMHSNDPM API. The values you specify for the message identifier and message type parameters determine which other input parameters you must specify and which you must code as blanks. They also determine whether the system returns the message key in the message key output parameter.

Additional Information about Message Types

The following sections discuss additional considerations in using the different types of messages that you can specify when calling the QMHSNDPM API.

Completion and Diagnostic Messages:  You can send completion and diagnostic messages as immediate messages or with message identifiers to call message queues or to the external message queue.

Escape Messages:   You can send escape messages only with a message identifier and only to a call message queue. You cannot send them to the external message queue.

An escape message sent to a previous caller's call message queue ends the current call stack entry. Sending the escape message causes all the call stack entries up to but not including the call stack entry receiving the escape message to end. For example, if three call stack entries are active and the third call stack entry sends an escape message to the first, then the second and third call stack entries are ended.

Informational Messages:   You can send informational messages as immediate messages or with message identifiers to call message queues or to the external message queue.

When you send an informational or inquiry message to the external message queue and the job is interactive, the message is displayed on the work station of the current job. The user sees the Display Program Messages display. Sending messages of these types to the external message queue is the only way to make the Display Program Messages display appear.

Inquiry Messages:   You can send inquiry messages only to the external message queue. You cannot send them to call message queues. The sending call stack entry would have to end before the receiving call stack entry could receive the message and send a reply. At that point, the sending call stack entry is no longer active, so it cannot receive a reply.

When you send an inquiry message, it is displayed at the work station as described in Informational Messages. In addition, a copy of the message is placed in the reply message queue, which is always the sending call stack entry's call message queue. Sending an inquiry message lets your call stack entry receive the reply to the message by using the message key returned by this API.

An inquiry message sent to the external message queue requires either the default reply or a reply from an interactive user. Call stack entries cannot reply to inquiry messages sent to the external message queue. In batch mode, the default reply is automatically sent as the reply.

The QMHSNDPM API returns the message key to the copy of the inquiry message in the reply message queue. You can receive the reply to the inquiry message by using the Receive Program Message (QMHRCVPM) API specifying this key and the message type reply. You can receive the copy of the original inquiry message by specifying this key and the message type of *COPY. You cannot use this key to receive the original message.

Notify Messages You can send notify messages only with a message identifier. You can send them to a call message queue or to the external message queue.

The reply message queue is always the sending call stack entry's call message queue (*PGMQ). This API returns the message key to the copy of the message in the reply message queue. To receive the reply, use the Receive Program Message (QMHRCVPM) API specifying this key and a message type of reply (*RPY).

When a notify message is sent to a call message queue, the action taken depends on two things:

• Whether the receiving call stack entry monitors for the message.
• Whether the receiving call stack entry has specified an external exception handler to handle the message.

When a notify message is sent to the external message queue, the action taken is the same as if an inquiry message were sent, with this exception. Notify messages are not responded to by the system reply list.

In an interactive job where a notify message is sent to *EXT, the user must take action to send any reply, including the default reply. In a batch job, the default reply is automatically sent because programs cannot reply to notify messages sent to the external message queue.

Request Messages:   You can send a request message only as an immediate message. You can send it to a call message queue or to the external message queue.

Request messages sent to the external message queue are never displayed on the Display Program Messages display. The system program QCMD receives them. Before the Command Entry display appears, the QCMD program attempts to perform the commands contained in the request messages. The QCMD program performs this function only with request messages on the external message queue; it does not work with request messages on other queues.

Status Messages:   You must send status messages with a message identifier. You can send them to a call message queue or the external message queue.

When you send status messages to the external message queue in an interactive job, the system displays them at the bottom of the current job's display station. This shows the status of running programs. You can use this to reassure users that long programs are still running.

Status messages appear only on the display. Because they are never put in message queues and they do not have message keys, you cannot receive or resend them.

Status messages are predefined messages. However, you can send the user what appears to be an immediate status message by using a message type of status and message CPF9898. CPF9898 is in message file QCPFMSG in library QSYS. This message consists only of a substitution variable; thus, it uses the message data that you supply as the full message text. To use it, specify CPF9898 in the message identifier parameter and the text you want to send in the replacement data or impromptu text parameter. To clear the message from the bottom of the display, you can send CPI9801, which only contains a blank line as the message.

Command Messages:   You can send command messages only as immediate messages, and only to a call message queue. You cannot send them to the external message queue.

Command messages are intended for IBM use for logging commands to the job log when a CL program runs.

Error Messages

[ Back to top | Message Handling APIs | APIs by category ]