•
•
•
•
• Application should first attach to a queue using tpqattach(3c) before using queuing features and other advanced features provided by OTMQ.
• For message sending, application calls standard enqueue API tpenqplus(3c) with specified block, DIP and UMA, to determine whether messaging is synchronous or asynchronous, recoverable or not, and action to take when delivery failed as shown in Listing 1.
• Listing 2 Synchronous Message Dequeue
• Listing 3 Asynchonous Dequeue Message
• If received message requires confirmation, application calls tpqconfirmmsg(3c) to confirm receipt of the message as shown in Listing 4.OTMQ provides message filter which allows user to retrieve message that matching the selection criteria defined by the message filter. Application can designate message filter when calling standard dequeue API tpdeqplus(3c), or when calling subscription API tpqsubscribe(3c).Message filter can be specified when executing a tpdeqplus/tpdequeue. It only impacts the result of this operation itself. For simple filter use, you must set filter_idx=-1 and flags|=TPQGETBYFILTER, otherwise it reports an error.Message filter can be defined or canceled via a pair of APIs: tpqsetselect /tpqcancelselect. Once a filter is defined, the user can use it in a serial of dequeue or subscription operations.Table 1 shows how the selection criteria can be defined as select mode and value pairs.
Table 1 Select Mode Application calls tpqsetselect(3c) function first to define a filter and gets an index handle as return, which can be used later in the standard dequeue API to retrieve messages.Also the application can call tpqcancelselect(3c) to cancel the compound filter defined before as shown in Listing 6.For more information, see tpqsetselect(3c) and tpqcancelselect(3c) in the Oracle Tuxedo Message Queue Reference Guide.A publisher can send a broadcast message using tpqpublish(3c), and a subscriber can retrieve the subscribed message from its attached queue.To broadcast a message, a publisher program directs the message to the topic that identifies the broadcast stream to use for message distribution. When the application issues the tpqpublish(3c) function, OTMQ Message Queue Manager Server deals with the tpqpublish(3c) call and transparently redirects the message to all corresponding recipients.To receive broadcast messages, applications use a standard API tpqsubscribe(3c) to register for receipt with the local or remote OTMQ Message Queue Manager Server.The receiver/subscribing applications register for broadcast messages using the function tpqsubscribe(3c). The registration contains the string formatted topic plus any selection criteria (filter) related to messages that the application wishes to receive.The application subscribe the broadcast messages using the function tpqsubscribe(3c) supplied with the following information:Use the message filter of tpqsubscribe(3c) to register for selective reception of broadcast messages. This subscription request registers a target queue to receive a copy of all messages on a broadcast stream that meet a single selection rule.Table 2 shows how the Filter Regular Expression Rules can be defined.
Table 2 Regular Expression Rules The tpqsubscribe(3c) returns a subscription handle back to the subscriber. This handle should be used to unsubscribe the specific subscription.An application can withdraw subscribing messages from a broadcast stream by calling the tpqunsubscribe(3c). This action removes the subscription entry from the internal registration tables as shown in Listing 7Listing 7 Subscribe and Unsubscribe MessagesApplications send messages using the OTMQ standard enqueue function tpenqplus(3c) and one of two types of delivery modes: recoverable or non-recoverable. If a message is sent as non-recoverable, the message is lost if it cannot be delivered to the target queue unless the application incorporates an error recovery procedure. If the message is sent as recoverable, OTMQ Message Queue Manager Server and Offline Trade Driver can automatically guarantee delivery to the target queue in spite of system, process, and network failures.The delivery mode specified in tpenqplus(3c) function determines:OTMQ does not support all possible combinations of block type and delivery interest points. Table 3 lists the valid delivery modes and their meanings.
Table 3 Delivery Modes
• Using the tpenqplus(3c) function in conjunction with the delivery argument, you can use the UMA argument to specify what should happen to the message if it cannot be delivered to the delivery interest point.Table 4 lists the five valid UMAs.
Table 4 UMAs To send a recoverable message, use the tpenqplus(3c) function supplying the appropriate block type, DIP and UMA in the TPQCTL structure.To receive a recoverable message, use the tpdeqplus(3c) function. When a recoverable message is delivered to the target queue, the application must perform the following:
• Confirm message receipt, which allows the Offline Trade Driver (TuxMQFWD(5)) to delete the message being stored in the recovery journal queue before delivery.
• Check for duplicate messages via return code. Duplicate messages may be sent by the Offline Trade Driver if the application didn't confirm message receipt in time. For more information, see tpdeqplus(3c) in the Oracle Tuxedo Message Queue Reference Guide.
• If the queue is configured for explicit confirmation, the receiver should call the tpqconfirmmsg(3c) function to acknowledge receipt of the recoverable message using the message sequence number assigned by the OTMQ Message Manager Server when the message was sent. If the queue is configured for implicit confirmation, the acknowledge message will be sent by tpdeqplus(3c) automatically after the recoverable message is dequeued successfully. For more information, see tmqadmin(1) in the Oracle Tuxedo Message Queue Reference Guide.
• The tpqconfirmmsg(3c) function sends acknowledge notification to the Offline Trade Driver to notify the successful message delivery, which allows the Offline Trade Driver to remove the message from the message recovery journal queues.To use the dead letter queue, the sender program calls the tpenqplus(3c) function specifying the appropriate delivery argument and using OTMQ_UMA_DLQ as the UMA argument. Any messages that cannot be delivered to the receiver program are written to the dead letter queue of the sender's group. An application program can use tpqreadjrn(3c) function to retrieve undelivered messages and use the tpenqplus(3c) function to attempt redelivery.The dead letter journal provides disk storage for messages that could not be stored for automatic recovery. It is created automatically by tmqadmin(1) qspacecreate command.To use the dead letter journal, the sender program uses the tpenqplus(3c) function specifying the appropriate delivery argument and OTMQ_UMA_DLJ as the UMA argument. Any messages that cannot be stored by the message recovery system are written to the dead letter journal of the sender's group. An application program can use tpqreadjrn(3c) function to retrieve undelivered messages and use the tpenqplus(3c) function to attempt redelivery as shown in Listing 8.Table 5 lists the valid delivery modes and UMA combinations.
Table 5 DIP and UMA Support List The user must configure TMQ_NA(5) server in UBB to take advantage of the naming service.OTMQ Naming Server uses three levels of name spaces: process, local (qspace-wide) and global (cross qspace wide). When OTMQ Naming Server start up, the local scope alias will be stored in local name space. The global scope alias will be stored in global name space. The process name space is an application cache used to improve performance. The alias can be cached at different level name space, user can bypass caching when using tpqlocate(3c) if they prefer accuracy over performance.After creating the name space, you must set the DMQNS_DEVICE environment variable to specify a device name for the name space because access to the name space for global naming is system dependent. Therefore, when a global naming service is configured, it must be told what device name to be used when it accesses this name space. This is done by setting the environment variable DMQNS_DEVICE as follows:
•
• When an application refers to a queue by alias using the tpqlocate(3c) or the tpqbind(3c) functions, it can specify the alias as one of the following:
• unqualified name: The application uses only the queue alias such as "widgets" and does not specify the path. The naming service automatically prefixes the name with the value of the environment variable DMQNS_DEVICE. Furthermore, it prefix the value of the environment variable DMQNS_DEFAULTPATH begins with a "/". For example, if the DMQNS_DEVICE environment variable is set to "dev" and the DMQNS_DEFAULTPATH is set to "/inventory", the naming service would search for the name "widgets" in: /dev/inventory/widgets
• partially qualified name: The application specifies the queue alias and a portion of the path name. The naming service automatically prefixes the pathname and queue alias with the device specified as the DMQNS_DEVICE environment variable and the setting of the DMQNS_DEFAULTPATH environment variable. For example, if the DMQNS_DEVICE environment variable is set to "/dev" and the DMQNS_DEFAULTPATH is set to "/inventory", the naming service would search for the name "test/widgets" in: /dev/inventory/test/widgets.
• fully qualified name: The application specifies that the alias is a fully qualified name using "/" as the first character of the name. When the first character of a name begins with "/", the naming service does not prefix any information to the name other than the device name specified by the DMQNS_DEVICE environment variable. This means that a fully qualified name includes the full path name and queue name. For example, if the DMQNS_DEVICE environment variable is set to "dev" and the DMQNS_DEFAULTPATH is set to "/inventory", the naming service will search for the name "/production/test/widgets" in: /dev/production/test/widgets. Listing 9 shows a global namespace file example.Listing 9 Global Namespace File ExampleAn application must attach to a queue using the tpqattach(3c) function before reading message from or sending message to a queue. It can identify the queue by its alias or its name. When sending a message, the target queue is always identified by its name. An application can directly use the queue name or it can use the tpqlocate(3c) function to derive the queue name from its alias.Listing 10 shows locating queue example.Listing 10 Locating Queue ExampleStatic binding refers to associating a queue name with a queue alias using the name space file. To enable such association, you can specify the name space file when creating the queue space; or you can stop the Naming Server, then update the queue space to specify a name space file, then restart the Naming Server again. For more information, see tmqadmin(1) in the Oracle Tuxedo Message Queue Reference Guide.Dynamic binding refers to the use of tpqbind(3c) to associate a queue alias to a queue name at application runtime. The queue alias will not be bound to a specific queue name until the tpqbind(3c) successfully return. To modify such association, the application must first unbind the queue alias from the specific queue name using tpqbind(3c), and use the same API to associate another queue alias to the queue name again. When the application detach from the queue or exit the queue space, the Naming Server will unbind the association for this application automatically. shows a dynamic binding queue example.Listing 11 Dynamic Binding Queue ExampleIn WS mode, OTMQ messages that are sent using a recoverable delivery mode are written to the local store-and-forward (SAF) journal (tmqsaf.jrn) when the connection to the server system is not available.As counterparts of Tuxedo buildclient(1) and buildserver(1) commands, OTMQ provides buildqclient(1) and buildqserver(1).buildqclient(1) is used to construct an OTMQ client module. The command combines the supplied files with the standard Oracle Tuxedo ATMI libraries and OTMQ libraries to form a load module.buildqserver(1) is used to construct an OTMQ server load module. The command combines the supplied files with the standard server main routine, the standard Oracle Tuxedo ATMI libraries and OTMQ libraries to form a load module.