SEND_MESSAGE can now send message to any message queue

When SEND_MESSAGE SQL procedure was introduced in 2021, as part of IBM i 7.3 TR10 and 7.4 TR4, it would be used to send messages to the System operator message queue. I have used this many times to do so, but I have always wondered how I could do the same to any message queue? Well, in the latest Technology Refreshes, IBM i 7.6 TR1 and 7.5 TR7, this functionality was added.

Two new parameters were added to the procedure to make this possible:

• MESSAGE_QUEUE_LIBRARY:  The library that contains the message queue I want to send the message to
• MESSAGE_QUEUE:  The message queue I want to send the message to

If I omit these parameters the message will be sent to the System operator message queue.

The first example I am going to show is using the procedure as it was intended, sending a message to the System operator message queue. I am going to use the message id CPF9898, which is a general escape message, i.e. I can provide any text I want for the message to use. I can show this using the MESSAGE_FILE_DATA SQL View:

01 SELECT MESSAGE_TEXT,MESSAGE_SECOND_LEVEL_TEXT 02 FROM QSYS2.MESSAGE_FILE_DATA 03 WHERE MESSAGE_FILE_LIBRARY = 'QSYS' 04 AND MESSAGE_FILE = 'QCPFMSG' 05 AND MESSAGE_ID = 'CPF9898'

Line 1: I only want to return the Message text and the Message details in the results.

Lines 3 and 4: CPF9898 is found in the QCPFMSG message file, which is in the library QSYS.

Line 5: I am only interested in Message id CPF9898.

This returns:

MESSAGE _TEXT MESSAGE_SECOND_LEVEL_TEXT ------- --------------------------------------------------------------------------------------------- &1. Cause . . . . . : This message is used by application programs as a general escape message.

The &1 means that the message will display whatever text I pass to it.

If I used SEND_MESSAGE as I have in the past:

01 CALL QSYS2.SEND_MESSAGE( 02 MESSAGE_ID => 'CPF9898', 03 MESSAGE_LENGTH => 16, 04 MESSAGE_TEXT => 'This is a test 1.' , 05 MESSAGE_FILE_LIBRARY => 'QSYS', 06 MESSAGE_FILE => 'QCPFMSG')

Line 2: I want to send CPF9898.

Line 3: The length of the message I will be sending is sixteen characters.

Line 4: This is the message text I am passing to CPF9898.

Line 5 and 6: As I explained above CPF9898 is in the message file QCPFMSG in .

There are several ways I can display messages in a message queue. In these examples I am going to use the MESSAGE_QUEUE_INFO SQL View:

01 SELECT MESSAGE_ID,MESSAGE_TEXT, 02 SEVERITY 03 FROM QSYS2.MESSAGE_QUEUE_INFO 04 WHERE MSGQ_NAME = 'QSYSOPR' 05 AND MESSAGE_ID = 'CPF9898' 06 ORDER BY MESSAGE_TIMESTAMP DESC 07 LIMIT 1

Line 1: I want to return the Message id and the Message text columns.

Line 4: Search the QSYSOPR Message queue.

Line 5: Where the Message id is CPF9898.

Line 6: As there might be more than one CPF9898 message in the System operator message queue, sort it by the timestamp the message was written to the message queue in descending order, in other words the most recent CPF9898 comes first.

Line 7: And return one result, which will be the most recent.

The result is:

MESSAGE_ID MESSAGE_TEXT ---------- ----------------- CPF9898 This is a test 1.

In the next example I am going to use the two new parameters to send a message to my message queue.

01 CALL QSYS2.SEND_MESSAGE( 02 MESSAGE_TEXT => 'This is a test 2.' , 03 MESSAGE_LENGTH => 16, 04 MESSAGE_ID => 'CPF9898', 05 MESSAGE_FILE => 'QCPFMSG', 06 MESSAGE_FILE_LIBRARY => 'QSYS', 07 MESSAGE_QUEUE => 'SIMON', 08 MESSAGE_QUEUE_LIBRARY => 'QUSRSYS')

When I am giving the procedure's parameter names I can rearrange the parameters in any order I like, as I have done here.

Line 2: I am sending this message.

Line 3: The message is sixteen characters long.

Line 4: I am using Message id CPF9898.

Lines 5 and 6: Which is the message file QCPFMSG in the library QSYS.

Line 7: I want to send the message to my message queue, SIMON.

Line 8: Which is found in the library QUSRSYS.

I can use MESSAGE_QUEUE_INFO to search for the message in my message queue:

01 SELECT MESSAGE_ID,MESSAGE_TEXT, 02 FROM QSYS2.MESSAGE_QUEUE_INFO 03 WHERE MSGQ_NAME = 'SIMON' 04 AND MESSAGE_ID = 'CPF9898'

As CPF9898 will only occur in my message queue I don't need to sort the results, or limit the number of results.

The result is:

MESSAGE_ID MESSAGE_TEXT ---------- ----------------- CPF9898 This is a test 2.

I am going to find this really useful as a way to send messages to any message queue, even ones that do not belong to a user profile.

 

You can learn more about the SEND_MESSAGE SQL Procedure from the IBM website here.

 

This article was written for IBM i 7.6 TR1 and 7.5 TR7.