MQSEND scalar function

The MQSEND function sends data to a specified IBM® MQ location.

Notes:

¹ correl-id cannot be specified unless a send service and a service policy are also specified.

The schema is DB2MQ.

The MQSEND function sends the data that is contained in msg-data to the IBM MQ location that is specified by send-service, using the quality-of-service policy that is defined in service-policy.

send-service

An expression that returns a value that is a built-in character string or graphic string data type that is not a LOB. The value of the expression must not be an empty string or a string with trailing blanks. The expression must have an actual length that is no greater than 48 bytes. The value of the expression must refer to a service point that is defined in the DB2MQ.MQSERVICE table. A service point is a logical end-point from which a message is sent or received. A service point definition includes the name of the IBM MQ queue manager and the name of the queue.

If send-service is not specified or is the null value, Db2.DEFAULT.SERVICE is used.

service-policy

An expression that returns a value that is a built-in character string or graphic string data type that is not a LOB. The value of the expression must not be an empty string or a string with trailing blanks. The expression must have an actual length that is no greater than 48 bytes. The value of the expression must refer to a service policy that is defined in the DB2MQ.MQPOLICY table. A service policy specifies a set of quality-of-service options that are to be applied to this messaging operation. These options include message priority and message persistence. See IBM MQ Application Messaging Interface for more details.

If service-policy is not specified or is the null value, DB2.DEFAULT.POLICY is used.

msg-data

An expression that returns a value that is a built-in character string data type. If the expression is a CLOB, the value must not be longer than 1 MB. Otherwise, the value must not be longer than 4000 bytes. The value of the expression is the message data that is to be sent through IBM MQ. A null value, an empty string, and a fixed length string with trailing blanks are all considered valid values.

correl-id

An expression that returns a value that is a built-in character string or graphic string data type that is not a LOB. The expression must have an actual length that is no greater than 24 bytes. The value of the expression specifies the correlation identifier that is associated with this message. A correlation identifier is often specified in request-and-reply scenarios to associate requests with replies. correl-id must not be specified unless send-service and service-policy are also specified.

A fixed length string with trailing blanks is considered a valid value. However, when the correl-id is specified on another request such as MQRECEIVE, the correl-id must be specified the same to be recognized as a match. For example, specifying a value of 'test' for correl-id on MQSEND does not match a correl-id value of 'test ' (with trailing blanks) specified subsequently on an MQRECEIVE request.

If correl-id is not specified, is an empty string, or is the null value, a correlation identifier is not sent.

The returned value is a varying-length character string with the value '1' if function execution was successful, or an error message if function execution was unsuccessful.

The CCSID of the result is the system CCSID that was in effect at the time that the IBM MQ function was installed into Db2.

Notes

The application needs to check the SQLCODE after issuing the MQSEND function. If the SQLCODE is not 0, the application needs to retrieve and handle the returned error message.

Examples

Example 1: Send the string "Testing msg" to the default service (Db2.DEFAULT.SERVICE), using the default policy (Db2.DEFAULT.POLICY) and no correlation identifier

   SELECT MQSEND('Testing msg')
     FROM SYSIBM.SYSDUMMY1;

The message is sent to the default service, using the default policy.

Example 2: Send the message 'Testing 345' to the service MYSERVICE, using the policy MYPOLICY, with no correlation identifier

   SELECT MQSEND('MYSERVICE','MYPOLICY','Testing 345')
     FROM SYSIBM.SYSDUMMY1;

The message 'Testing 345' is sent to the MYSERVICE service, using the policy MYPOLICY.

Example 3: Send the message 'Testing 123' to the service MYSERVICE, using the policy MYPOLICY and the correlation identifier 'TEST3'

   SELECT MQSEND('MYSERVICE','MYPOLICY','Testing 123','TEST3')
     FROM SYSIBM.SYSDUMMY1;

The message 'Testing 123' is sent to the service MYSERVICE, using the policy MYPOLICY and the correlation identifier "TEST3".

Example 4: Send the message 'Testing 901' to the service "MYSERVICE", using the default policy (Db2.DEFAULT.POLICY), and no correlation identifier

   SELECT MQSEND('MYSERVICE','Testing 901')
     FROM SYSIBM.SYSDUMMY1;

The message 'Testing 901' is sent to the service MYSERVICE, using the default policy (Db2.DEFAULT.POLICY).