Send Writer Message (QSPSNDWM) API

The Send Writer Message (QSPSNDWM) API is used by a driver exit program to send either an informational or inquiry message to the writer's message queue.

When an inquiry message is issued, the writer goes into message wait status and waits the specified number of seconds. When the message is answered, or the timeout value has been reached, the API clears the message wait status and returns to its caller. The answer to the inquiry message is returned through the receiver variable parameter.

When an informational message is issued, the API sets the status of the writer to message wait and returns to the caller. The API's caller must then call the API to clear the message wait status.

Authorities and Locks

None.

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The receiver variable that receives the information requested. You can specify the size of the area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold.

Length of receiver variable

INPUT; BINARY(4)

The length of the receiver variable provided. The length of receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable. The minimum length is 8 bytes.

Format name

INPUT; CHAR(8)

The format of the writer message data returned.

SNDM0100

Contains the information about the message and its reply.

Message identifier

INPUT; CHAR(7)

The message identifier of the message to issue.

Qualified message file name

INPUT; CHAR(20)

The name of the message file in which the message resides. The first 10 characters contain the message file name and the second 10 characters contain the name of the library in which the message file is located. If this field is blank, the system message file (QCPFMSG) is used.

The following special values are supported for the library name:

*LIBL	The library list of the writer job is used to locate the message file.
*CURLIB	The current library for the writer job is used to locate the message file.

Message data

INPUT; CHAR(*)

The data to insert in the predefined message's substitution variables

Length of message data

INPUT; BINARY(4)

The length of the message data in bytes. Value values are 1 through 512 bytes.

Message type

INPUT; CHAR(10)

The type of the message.

The Values are:

*INFO	The message to be sent is an informational message.
*INQ	The message to be sent is an inquiry message.

Message wait timeout

INPUT; BINARY(4)

The number of seconds to wait for a reply to an inquiry message. Any number greater than 0 is valid. This parameter is only used for inquiry messages. It is ignored for informational messages. The following special value is supported for this parameter.

-1	The maximum wait time is be used.

Note: This parameter is only used for inquiry messages. It is ignored for informational messages.

Message key

INPUT; CHAR(4)

The key of the message whose wait status is cleared. This field is blank when a message is being sent.

Writer handle

INPUT; CHAR(16)

The handle to the writer job. This handle is provided to the driver program on a writer call to the driver exit program during initialization.

Coded character set identifier

INPUT; BINARY(4)

The coded character set identifier used to convert the message data supplied as replacement text for message fields that correspond to *CCHAR type fields. The data supplied that does not correspond to a *CCHAR field is 65535 and is not converted. For more information about *CCHAR type fields, see the Add Message Description (ADDMSGD) command.

The following values are allowed:

0	The message data 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 is not be converted.
CCSID	Specify a valid CCSID that your replacement data or impromptu message is in. Valid values are between 1 and 65535. This API validates the CCSID. For a list of valid CCSIDs, see the Globalization topic in the iSeries Information Center.

Error code

I/O; CHAR(*)

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

SNDM0100 Format

The following table shows the information returned for the SNDM0100 format. For more details about the fields in the following table see, Field Descriptions.

Field Descriptions

Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.

Bytes returned. The number of bytes of data returned.

Length of message reply text available. The length of the message reply text that is available. This length is zero (0) for informational messages or when the message wait timeout value was reached.

Length of message reply text returned. The length of the message reply text that is returned in the message reply text. This length is zero (0) for informational messages or when the message wait timeout value was reached.

Message key. The key of the message issued. This can be used with message handler APIs to perform various functions.

Message reply text. The text of the reply received from the inquiry message.

Offset to message reply text. The offset to the message reply text, in bytes.

Reserved. The field is reserved.

Error Messages