MQCreateVtiRead() function

The MQCreateVtiRead() 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 MQCreateVtiRead() function creates a table bound to a queue specified by service_name, using the quality of service policy defined in policy_name. Selecting from the table created by this function returns all the committed messages in the queue, but does not remove the messages from the queue. If no messages are available to be returned, the SELECT statement returns no rows. An insert to the bound table puts a message into 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 = "READ");

The mapping for 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 inserts the following into the mapped table column:
- msg. The message text that will be inserted onto the queue. If msg is NULL, MQ functions send a zero-length message to the queue.
- correlid. The message will be sent with the specified correlation identifier.
A select operation maps these in the following way to a WMQ queue:
- msg. The message is retrieved 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 MQCreateVtiRead() function are interpreted.

Table 1. MQCreateVtiRead() argument interpretation
Usage	Argument interpretation
MQCreateVtiRead(arg1)	arg1 = table_name
MQCreateVtiRead(arg1, arg2)	arg1 = table_name arg2 = service_name
MQCreateVtiRead(arg1, arg2, arg3)	arg1 = table_name arg2 = service_name arg3 = policy_name
MQCreateVtiRead(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 a table called VtiReadTest using the default service name and policy name:

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

Insert a message into the queue:

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

Read a message from the queue:

select * from VtiReadTest;