Sending Replies

5.5.1 Sending Replies

The tpreturn(3c) function marks the end of the service routine and sends a message to the requester. Use the following signature to call the tpreturn() function:

void
tpreturn(int rval, int rcode, char *data, long len, long flags)

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

Table 5-2 tpreturn( ) Function Arguments

Argument	Description
`rval`	Indicates whether or not the service has completed successfully on an application-level. The value is an integer that is represented by a symbolic name. Valid settings include: `TPSUCCESS`—the calling function succeeded. The function stores the reply message in the caller’s buffer. If there is a reply message, it is in the caller’s buffer. `TPFAIL` (default)—the service terminated unsuccessfully. The function reports an error message to the client process waiting for the reply. In this case, the client’s `tpcall()` or `tpgetrply()` function call fails and the system sets the `tperrno(5)` variable to `TPESVCFAIL` to indicate an application-defined failure. If a reply message was expected, it is available in the caller’s buffer. `TPEXIT`—the service terminated unsuccessfully. The function reports an error message to the client process waiting for the reply, and exits. For a description of the effect that the value of this argument has on global transactions, refer to Writing Global Transactions.
`rcode`	Returns an application-defined return code to the caller. The client can access the value returned in `rcode` by querying the `tpurcode(5)` global variable. The function returns this code regardless of success or failure.
`data`	Pointer to the reply message that is returned to the client process. The message buffer must have been allocated previously by `tpalloc()`. If you use the same buffer that was passed to the service in the `SVCINFO` structure, you need not be concerned with buffer allocation or disposition because both are handled by the system-supplied `main()`. You cannot free this buffer using the `tpfree()` command; any attempt to do so quietly fails. You can resize the buffer using the `tprealloc()` function. If you use another buffer (that is, a buffer other than the one passed to the service routine) to return the message, it is your responsibility to allocate it. The system frees the buffer automatically when the application calls the `tpreturn()` function. If no reply message needs to be returned, set this argument to the NULL pointer. Note: If no reply is expected by the client (that is, if `TPNOREPLY` was set), the `tpreturn()` function ignores the data and len arguments and returns control to `main()`.
`len`	Length of the reply buffer. The application accesses the value of this argument through the `olen` parameter of the `tpcall()` function or the len parameter of the `tpgetrply()` function. Acting as the client, the process can use this returned value to determine whether the reply buffer has grown. If a reply is expected by the client and there is no data in the reply buffer (that is, if the `data` argument is set to the NULL pointer), the function sends a reply with zero length, without modifying the client’s buffer. The system ignores the value of this argument if the `data` argument is not specified.
`flag`	Currently not used.

The primary function of a service routine is to process a request and return a reply to a client process. It is not necessary, however, for a single service to do all the work required to perform the requested function. A service can act as a requester and pass a request call to another service the same way a client issues the original request: through calls to tpcall() or tpacall().

Note:

The tpcall() and tpacall() functions are described in detail in Writing Request/Response Clients and Servers.

When tpreturn() is called, control always returns to main(). If a service has sent requests with asynchronous replies, it must receive all expected replies or invalidate them with tpcancel()before returning control to main(). Otherwise, the outstanding replies are automatically dropped when they are received by the Oracle Tuxedo system main(), and an error is returned to the caller.

If the client invokes the service with tpcall(), after a successful call to tpreturn(), the reply message is available in the buffer referenced by * odata. If tpacall() is used to send the request, and tpreturn() returns successfully, the reply message is available in the tpgetrply() buffer that is referenced by * data.

If a reply is expected and tpreturn() encounters errors while processing its arguments, it sends a failed message to the calling process. The caller detects the error by checking the value placed in tperrno. In the case of failed messages, the system sets tperrno to TPESVCERR. This situation takes precedence over the value of the tpurcode global variable. If this type of error occurs, no reply data is returned, and both the contents and length of the caller’s output buffer remain unchanged.

If tpreturn() returns a message in a buffer of an unknown type or a buffer that is not allowed by the caller (that is, if the call is made with flags set to TPNOCHANGE), the system returns TPEOTYPE in tperrno(5). In this case, application success or failure cannot be determined, and the contents and length of the output buffer remain unchanged.

The value returned in the tpurcode(5) global variable is not relevant if the tpreturn() function is invoked and a timeout occurs for the call waiting for the reply. This situation takes precedence over all others in determining the value that is returned in tperrno(5). In this case, tperrno(5) is set to TPETIME and the reply data is not sent, leaving the contents and length of the caller’s reply buffer unchanged. There are two types of timeouts in the Oracle Tuxedo system: blocking and transaction timeouts (discussed in "Writing Global Transactions").

The example code in this section shows the TRANSFER service that is part of the XFER server. Basically, the TRANSFER service makes synchronous calls to the WITHDRAWAL and DEPOSIT services. It allocates a separate buffer for the reply message since it must use the request buffer for the calls to both the WITHDRAWAL and the DEPOSIT services. If the call to WITHDRAWAL fails, the service writes the message cannot withdraw on the status line of the form, frees the reply buffer, and sets the rval argument of the tpreturn() function to TPFAIL. If the call succeeds, the debit balance is retrieved from the reply buffer.

Note:

In the following example, the application moves the identifier for the “destination account” (which is retrieved from the cr_id variable) to the zeroth occurrence of the ACCOUNT_ID field in the transf fielded buffer. This move is necessary because this occurrence of the field in an FML buffer is used for data-dependent routing. Refer to Setting Up an Oracle Tuxedo Application for more information.

A similar scenario is followed for the call to DEPOSIT. On success, the service frees the reply buffer that was allocated in the service routine and sets the rval argument to TPSUCCESS, returning the pertinent account information to the status line.

Listing tpreturn( ) Function

#include <stdio.h>          /* UNIX */
#include <string.h>         /* UNIX */
#include "fml.h"            /* ORACLE Tuxedo System */
#include "atmi.h"           /* ORACLE Tuxedo System */
#include "Usysflds.h"       /* ORACLE Tuxedo System */
#include "userlog.h"        /* ORACLE Tuxedo System */
#include "bank.h"           /* BANKING #defines */
#include "bank.flds.h"      /* bankdb fields */

/*
 * Service to transfer an amount from a debit account to a credit 
 * account
 */

void
#ifdef __STDC__
TRANSFER(TPSVCINFO *transb)

#else
TRANSFER(transb)
TPSVCINFO *transb;
#endif

{
   FBFR *transf;              /* fielded buffer of decoded message  */
   long db_id, cr_id;         /* from/to account id’s                */
   float db_bal, cr_bal;      /* from/to account balances           */
   float tamt;                /* amount of the transfer             */
   FBFR *reqfb;               /* fielded buffer for request message */
   int reqlen;                /* length of fielded buffer           */
   char t_amts[BALSTR];       /* string for transfer amount         */
   char db_amts[BALSTR];      /* string for debit account balance   */
   char cr_amts[BALSTR];      /* string for credit account balance  */

/* Set pointr to TPSVCINFO data buffer */
transf = (FBFR *)transb->data;

/* Get debit (db_id) and credit (cr_id) account IDs */

/* must have valid debit account number */
if (((db_id = Fvall(transf, ACCOUNT_ID, 0)) < MINACCT) || (db_id > MAXACCT)) {
   (void)Fchg(transf, STATLIN, 0,"Invalid debit account number",(FLDLEN)0);
   tpreturn(TPFAIL, 0, transb->data, 0L, 0);
}
/* must have valid credit account number */
if ((cr_id = Fvall(transf, ACCOUNT_ID, 1)) < MINACCT || cr_id > MAXACCT) {
   (void)Fchg(transf,STATLIN, 0,"Invalid credit account number",(FLDLEN)0);
   tpreturn(TPFAIL, 0, transb->data, 0L, 0);
}

/* get amount to be withdrawn */
if (Fget(transf, SAMOUNT, 0, t_amts, < 0) 0 || strcmp(t_amts,"") == 0) {
   (void)Fchg(transf, STATLIN, 0, "Invalid amount",(FLDLEN)0);
   tpreturn(TPFAIL, 0, transb->data, 0L, 0);
}
(void)sscanf(t_amts,"%f",tamt);

/* must have valid amount to transfer */
if (tamt = 0.0) {
   (void)Fchg(transf, STATLIN, 0,
      "Transfer amount must be greater than $0.00",(FLDLEN)0);
    tpreturn(TPFAIL, 0, transb->data, 0L, 0);
}

/* make withdraw request buffer */
if ((reqfb = (FBFR *)tpalloc("FML",NULL,transb->len)) == (FBFR *)NULL) {
   (void)userlog("tpalloc failed in transfer\n");
   (void)Fchg(transf, STATLIN, 0,
      "unable to allocate request buffer", (FLDLEN)0);
    tpreturn(TPFAIL, 0, transb->data, 0L, 0);
}
reqlen = Fsizeof(reqfb);

/* put ID in request buffer */
(void)Fchg(reqfb,ACCOUNT_ID,0,(char *)&db_id, (FLDLEN)0);

/* put amount in request buffer */
(void)Fchg(reqfb,SAMOUNT,0,t_amts, (FLDLEN)0);

/* 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);
}

/* get "debit" balance from return buffer */

(void)strcpy(db_amts, Fvals((FBFR *)reqfb,SBALANCE,0));
void)sscanf(db_amts,"%f",db_bal);
if ((db_amts == NULL) || (db_bal < 0.0)) {
   (void)Fchg(transf, STATLIN, 0,
        "illegal debit account balance", (FLDLEN)0);
tpfree((char *)reqfb);
tpreturn(TPFAIL, 0, transb->data, 0L, 0);
}

/* put deposit account ID in request buffer */
(void)Fchg(reqfb,ACCOUNT_ID,0,(char *)&cr_id, (FLDLEN)0);

/* put transfer amount in request buffer */
(void)Fchg(reqfb,SAMOUNT,0,t_amts, (FLDLEN)0);

/* Up the priority of deposit call */
if (tpsprio(PRIORITY, 0L) == -1)
     (void)userlog("Unable to increase priority of deposit\n");

/* Do a tpcall to deposit to second account */
if (tpcall("DEPOSIT", (char *)reqfb, 0, (char **)&reqfb,
         (long *)&reqlen, TPSIGRSTRT) == -1) {
(void)Fchg(transf, STATLIN, 0,
         "Cannot deposit into credit account", (FLDLEN)0);
tpfree((char *)reqfb);
tpreturn(TPFAIL, 0,transb->data, 0L, 0);
}

/* get "credit" balance from return buffer */
(void)strcpy(cr_amts, Fvals((FBFR *)reqfb,SBALANCE,0));
(void)sscanf(cr_amts,"%f",&cr_bal);
if ((cr_amts == NULL) || (cr_bal 0.0)) {
(void)Fchg(transf, STATLIN, 0,
"Illegal credit account balance", (FLDLEN)0);
tpreturn(TPFAIL, 0, transb->data, 0L, 0);
}
/* set buffer for successful return */

(void)Fchg(transf, FORMNAM, 0, "CTRANSFER", (FLDLEN)0);
(void)Fchg(transf, SAMOUNT, 0, Fvals(reqfb,SAMOUNT,0), (FLDLEN)0);
(void)Fchg(transf, STATLIN, 0, "", (FLDLEN)0);
(void)Fchg(transf, SBALANCE, 0, db_amts, (FLDLEN)0);
(void)Fchg(transf, SBALANCE, 1, cr_amts, (FLDLEN)0);
tpfree((char *)reqfb);
tpreturn(TPSUCCESS, 0,transb->data, 0L, 0);
}

Parent topic: Terminating a Service Routine