MQCreateVtiReceive() function

The MQCreateVtiReceive() function creates a table and maps it to a queue managed by WMQ.

Syntax

table_name: Required parameter. Specifies the name of the table to be created. The queue pointed to by the service_name parameter is mapped to this table.
service_name: Optional parameter. Refers to the value in the servicename column of the "informix".mqiservice table. If service_name is not specified, IDS.DEFAULT.SERVICE is used as the service. The maximum size of service_name is 48 bytes.
policy_name: Optional parameter. Refers to the value in the policyname column of the "informix".mqipolicy table. If policy_name is not specified, IDS.DEFAULT.POLICY is used as the policy. The maximum size of policy_name is 48 bytes.
maxMessage: Optional parameter. Specifies the maximum length of the message to be sent or received. The default value is 4000; the maximum allowable size is 32628.

Usage

The MQCreateVtiReceive() function creates a table_name bound to a queue specified by service_name, using the quality of service policy defined in policy_name. Selecting from this table returns all the available messages in the queue and also removes the messages from the queue. If no messages are available to be returned, the no rows are returned. An insert into the bound table puts messages in the queue.

The table created has the following schema and uses the "informix".mq access method:

create table table_name (
       msg lvarchar(maxMessage),
       correlid varchar(24),
       topic varchar(40),
       qname varchar(48),
       msgid varchar(12),
       msgformat varchar(8));
               using "informix".mq (SERVICE = service_name,
                                    POLICY = policy_name,
                                    ACCESS = "RECEIVE");

The mapping between a table bound to a queue requires translation of operation. Actions on specific columns within the table are translated into specific operations within the queue, as outlined here:

An insert operation maps the following columns to the MQ manager:
- msg. The text that will be inserted onto the queue. If msg is NULL, MQ functions send a zero-length message to the queue.
- correlid. The key recognized by queue manager to get messages from the queue
A select operation maps the following columns to the MQ manager:
- msg. The message is removed from the queue.
- correlid. Within the WHERE clause, is the value passed to the queue manager to qualify messages (the correlation identifier). The only operator that should be used when qualifying is equals (=).

The following table describes how the arguments for the MQCreateVtiReceive() function are interpreted.

Table 1. MQCreateVtiReceive() argument interpretation
Usage	Argument interpretation
MQCreateVtiReceive(arg1)	arg1 = table_name
MQCreateVtiReceive(arg1, arg2)	arg1 = table_name arg2 = service_name
MQCreateVtiReceive(arg1, arg2, arg3)	arg1 = table_name arg2 = service_name arg3 = policy_name
MQCreateVtiReceive(arg1, arg2, arg3, arg4)	arg1 = table_name arg2 = service_name arg3 = policy_name arg4 = maxMessage

Return codes

't': The operation was successful.
'f': The operation was unsuccessful.

Example

Create the table VtiReceiveTest using the default service name and policy name:

begin;
EXECUTE FUNCTION MQCreateVtiRead('VtiReceiveTest');
commit;

Insert a message to the queue:

INSERT INTO VtiReceiveTest(msg) values ('QMessage');

Read a message from the queue:

select * from VtiReceiveTest;

Attempting to read the queue a second time results in returning no rows because the table was created using the MQCreateVtiReceive() function, which removes entries as they are read.