Enqueuing Messages


	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Doc Home \| Programming \| Topic List \| Previous \| Next \| Contents

Using the BEA Tuxedo System /Q Component

Enqueuing Messages

The syntax for TPENQUEUE() is as follows.

01 TPQUEDEF-REC.
   COPY TPQUEDEF.
01 TPTYPE-REC.
   COPY TPTYPE.
01 DATA-REC.
   COPY User Data.
01 TPSTATUS-REC.
   COPY TPSTATUS.
CALL "TPENQUEUE" USING TPQUEDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.

When a TPENQUEUE() call is issued it tells the system to store a message on the queue identified in QNAME in TPQUEDEF-REC in the space identified in QSPACE-NAME in TPQUEDEF-REC. The message is in DATA-REC, and LEN in TPTYPE-REC has the length of the message. By the use of settings in TPQUEDEF-REC, the system is informed how the call to TPENQUEUE() is to be handled. Further information about the handling of the enqueued message and replies is provided in the TPQUEDEF-REC structure.

TPENQUEUE() Arguments

There are some important arguments to control the operation of TPENQUEUE(3cbl). Lets look at some of them.

TPENQUEUE(): the QSPACE-NAME in TPQUEDEF-REC Argument

QSPACE-NAME identifies a queue space previously created by the administrator. When a server is defined in the SERVERS section of the configuration file, the service names it offers are aliases for the actual queue space name (which is specified as part of the OPENINFO parameter in the GROUPS section). For example, when your application uses the server TMQUEUE, the value pointed at by QSPACE-NAME is the name of a service advertised by TMQUEUE. If no service aliases are defined, the name of the default service is the same as the server name, TMQUEUE. In this case the configuration file might include the following.

TMQUEUE
        SRVGRP = QUE1  SRVID = 1
        GRACE = 0  RESTART = Y CONV = N
        CLOPT = "-A"
or
        CLOPT = "-s TMQUEUE"

The entry for server group QUE1 has an OPENINFO parameter that specifies the resource manager, the pathname of the device and the queue space name. The QSPACE-NAME argument in a client program then looks like this.

 01  TPQUEDEF-REC.
     COPY TPQUEDEF.
 01  TPTYPE-REC.
     COPY TPTYPE.
 01  TPSTATUS-REC.
     COPY TPSTATUS.
 01  USER-DATA-REC  PIC X(100).
*
*
*
 MOVE LOW-VALUES TO TPQUEDEF-REC.
 MOVE "TMQUEUE" TO QSPACE-NAME IN TPQUEDEF-REC.
 MOVE "STRING" TO QNAME IN TPQUEDEF-REC.
 SET TPTRAN IN TPQUEDEF-REC TO TRUE.
 SET TPBLOCK IN TPQUEDEF-REC TO TRUE.
 SET TPTIME IN TPQUEDEF-REC TO TRUE.
 SET TPSIGRSTRT IN TPQUEDEF-REC TO TRUE.
 MOVE LOW-VALUES TO TPTYPE-REC.
 MOVE "STRING" TO REC-TYPE IN TPTYPE-REC.
 MOVE LENGTH OF USER-DATA-REC TO LEN IN TPTYPE-REC.
 CALL "TPENQUEUE" USING
         TPQUEDEF-REC
         TPTYPE-REC
         USER-DATA-REC
         TPSTATUS-REC.

The example shown on the TMQUEUE(5) reference page shows how alias service names can be included when the server is built and specified in the configuration file. The sample program in A Sample Application, also specifies an alias service name.

TPENQUEUE(): the QNAME in TPQUEDEF-REC Argument

When message queues are being used within a queue space to invoke services, they are named according to application services that process the requests. QNAME contains such a value; an exception in which QNAME is not an application service is described in Procedure for Dequeuing Replies from Services Invoked Through TMQFORWARD.

TPENQUEUE(): the DATA-REC and LEN in TPTYPE-REC Arguments

DATA-REC contains the message to be processed. LEN in TPTYPE-REC gives the length of the message. Some BEA Tuxedo record types (VIEW, for example) do not require LEN to be specified; in such cases, the argument is ignored. If RECTYPE in TPTYPE-REC is SPACES, DATA-REC and LEN are ignored and the message is enqueued with no data portion.

TPENQUEUE(): the Settings in TPQUEDEF-REC

Settings in TPQUEDEF-REC are used to tell the BEA Tuxedo system how the TPENQUEUE() call is handled; the following are valid settings:

TPNOTRAN: If the caller is in transaction mode and this setting is used, the message is not enqueued within the caller's transaction. A caller in transaction mode that sets this to true is still subject to the transaction timeout (and no other). If message enqueuing fails that was invoked with this setting, the caller's transaction is not affected. Either TPNOTRAN or TPTRAN must be set.
TPTRAN: If the caller is in transaction mode, this setting specifies that the enqueuing of the message is to be done within the same transaction. Either TPNOTRAN or TPTRAN must be set.
TPNOBLOCK: The message is not enqueued if a blocking condition exists. If TPNOBLOCK is set and a blocking condition exists such as the internal buffers into which the message is transferred are full, the call fails and tperrno(5) is set to TPEBLOCK. If TPNOBLOCK is set and a blocking condition exists because the target queue is opened exclusively by another application, the call fails, tperrno() is set to TPEDIAGNOSTIC, and the diagnostic field of the TPQCTL structure is set to QMESHARE. In the latter case, the other application, which is based on a BEA product other than the BEA Tuxedo system, opened the queue for exclusive read and/or write using the Queuing Services API (QSAPI). Either TPNOBLOCK or TPBLOCK must be set.
TPBLOCK: When TPBLOCK is set and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). Either TPNOBLOCK or TPBLOCK must be set.
TPNOTIME: This setting asks that the call be immune to blocking timeouts; transaction timeouts may still occur. Either TPNOTIME or TPTIME must be set.
TPTIME: This setting asks that the call will receive blocking timeouts. Either TPNOTIME or TPTIME must be set.
TPSIGRSTRT: This setting says that any underlying system calls that are interrupted by a signal should be reissued. Either TPSIGRSTRT or TPNOSIGRSTRT must be set.
TPNOSIGRSTRT: This setting says that any underlying system calls that are interrupted by a signal should not be reissued. The call fails and sets TP-STATUS to TPEGOTSIG. Either TPSIGRSTRT or TPNOSIGRSTRT must be set.

TPQUEDEF-REC Structure

The TPQUEDEF-REC structure has members that are used by the application and by the BEA Tuxedo system to pass parameters in both directions between application programs and the queued message facility. It is defined in the COBOL COPY file. The client that calls TPQUEDEF-REC uses settings to mark members the application wants the system to fill in. The structure is also used by TPDEQUEUE(); some of the members do not come into play until the application calls that function. The complete structure is shown in the following listing.

The TPQUEDEF-REC Structure

The following is a list of valid settings for the parameters controlling input information for TPENQUEUE.

TPQTOP

Setting this value indicates that the queue ordering be overridden and the message placed at the top of the queue. This request may not be granted depending on whether or not the queue was configured to allow overriding the queue ordering. Set TPQDEFAULT to use default queue ordering. TPQTOP, TPQBEFOREMSGID, or TPQDEFAULT must be set.

TPQBEFOREMSGID

Setting this value indicates that the queue ordering be overridden and the message placed in the queue before the message identified by MSGID. This request may not be granted depending on whether or not the queue was configured to allow overriding the queue ordering. Set TPQDEFAULT to use default queue ordering. TPQTOP, TPQBEFOREMSGID, or TPQDEFAULT must be set.

Note that the entire 32 bytes of the message identifier value are significant, so the value identified by MSGID must be completely initialized (for example, padded with spaces).

TPQTIME-ABS

If this value is set, the message is made available after the time specified by DEQ-TIME. DEQ-TIME is an absolute time value as generated by time(2) or mktime(3C) (the number of seconds since 00:00:00 Universal Coordinated Time-UTC, January 1, 1970). Set TPQNOTIME if neither an absolute or relative time value is set. TPQTIME-ABS, TPQTIME-REL, or TPQNOTIME must be set. The absolute time is determined by the clock on the machine where the queue manager process resides.

TPQTIME-REL

If this value is set, the message is made available after a time relative to the completion of the enqueuing operation. DEQ-TIME specifies the number of seconds to delay after the enqueuing completes before the submitted message should be available. Set TPQNOTIME if neither an absolute or relative time value is set. TPQTIME-ABS, TPQTIME-REL, or TPQNOTIME must be set.

TPQPRIORITY