Setting and Getting Message Priorities


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Documentation \| Programming BEA Tuxedo ATMI Applications Using C \| Local Topics \| Previous Topic \| Next Topic \| Contents

Two ATMI functions allow you to determine and set the priority of a message request: tpsprio(3c) and tpgprio(3c). The priority affects how soon the request is dequeued by the server; servers dequeue requests with the highest priorities first.

This section describes:

Setting a Message Priority

The tpsprio(3c) function enables you to set the priority of a message request.

The tpsprio() function affects the priority level of only one request: the next request to be sent by tpcall() or tpacall(), or to be forwarded by a service subroutine.

Use the following signature to call the tpsprio() function:

int
tpsprio(int prio, long flags);

The following table describes the arguments to the tpsprio() function.

tpsprio( ) Function Arguments

Argument

Description

prio

Integer indicating a new priority value. The effect of this argument is controlled by the flags parameter. If flags is set to 0, prio specifies a relative value and the sign accompanying the value indicates whether the current priority is incremented or decremented. Otherwise, the value specified indicates an absolute value and prio must be set to a value between 0 and 100. If you do not specify a value within this range, the system sets the value to 50.

flags

Flag indicating whether the value of prio is treated as a relative value (0, the default) or an absolute value (TPABSOLUTE).

Argument	Description
prio	Integer indicating a new priority value. The effect of this argument is controlled by the flags parameter. If flags is set to 0, prio specifies a relative value and the sign accompanying the value indicates whether the current priority is incremented or decremented. Otherwise, the value specified indicates an absolute value and prio must be set to a value between 0 and 100. If you do not specify a value within this range, the system sets the value to 50.
flags	Flag indicating whether the value of prio is treated as a relative value (0, the default) or an absolute value (TPABSOLUTE).

The following sample code is an excerpt from the TRANSFER service. In this example, the TRANSFER service acts as a client by sending a synchronous request, via tpcall(), to the WITHDRAWAL service. TRANSFER also invokes tpsprio() to increase the priority of its request message to WITHDRAWAL, and to prevent the request from being queued for the WITHDRAWAL service (and later the DEPOSIT service) after waiting on the TRANSFER queue.

Setting the Priority of a Request Message

/* increase the priority of withdraw call */
if (tpsprio(PRIORITY, 0L) == -1)
   (void)userlog("Unable to increase priority of withdraw\n");
 
if (tpcall("WITHDRAWAL", (char *)reqfb,0, (char **)&reqfb, (long *)
\
       &reqlen,TPSIGRSTRT) == -1) {
   (void)Fchg(transf, STATLIN, 0, "Cannot withdraw from debit account", \
       (FLDLEN)0);
   tpfree((char *)reqfb);
   tpreturn(TPFAIL, 0,transb->data, 0L, 0);
}

Getting a Message Priority

The tpgprio(3c) function enables you to get the priority of a message request.

Use the following signature to call the tpgprio() function:

int
tpgprio();

A requester can call the tpgprio() function after invoking the tpcall() or tpacall() function to retrieve the priority of the request message. If a requester calls the function but no request is sent, the function fails, returning -1 and setting tperrno(5) to TPENOENT. Upon success, tpgprio() returns an integer value in the range of 1 to 100 (where the highest priority value is 100).

If a priority has not been explicitly set using the tpsprio() function, the system sets the message priority to that of the service routine that handles the request. Within an application, the priority of the request-handling service is assigned a default value of 50 unless a system administrator overrides this value.

The following example shows how to determine the priority of a message that was sent in an asynchronous call.

Determining the Priority of a Request After It Is Sent

#include <stdio.h>
#include "atmi.h"
 
main ()
{
int cd1, cd2;              /* call descriptors */
int pr1, pr2;              /* priorities to two calls */
char *buf1, *buf2;         /* buffers */
long buf1len, buf2len;     /* buffer lengths */
 
join application
 
if (buf1=tpalloc("FML", NULL, 0) == NULL)
   error
if (buf2=tpalloc("FML", NULL, 0) == NULL)
   error
 
populate FML buffers with send request
 
if ((cd1 = tpacall("service1", buf1, 0, 0)) == -1)
   error
if ((pr1 = tpgprio()) == -1)
   error
if ((cd2 = tpacall("service2", buf2, 0, 0)) == -1)
   error

if ((pr2 = tpgprio()) == -1)\
   error
 
if (pr1 >= pr2) {   /* base the order of tpgetrplys on priority of calls */
        if (tpgetrply(&cd1, &buf1, &buf1len, 0) == -1)
           error
        if (tpgetrply(&cd2, &buf2, &buf2len, 0) == -1)
           error
}
else {
        if (tpgetrply(&cd2, &buf2, &buf2len, 0) == -1)
           error
        if (tpgetrply(&cd1, &buf1, &buf1len, 0) == -1)
           error
}
. . .
}