Programming Guide

Returns from a service request invocation

service_return [returnStatus] ([message]) [CODE returnCode]

returnStatus

Specifies the service return status with one of these values:

• SUCCESS—The service succeeded.

• FAILURE—The service failed.

• EXIT—The service failed and the server executable should terminate.

  Under Oracle Tuxedo, the middleware uses the service's return status to determine whether a transaction is successful. If any service that participates in a transaction returns with FAILURE or EXIT, the transaction is marked as abort-only. The transaction cannot be committed and must be aborted explicitly by the user.

  For more information about transactions, refer to xa_begin and xa_end

message

Specifies the message data to return to the invoking agent. This provides a mapping from Panther variables to the return arguments specified in the service call. Always enclose the data in message in parentheses even if no data is specified. The message format is determined by the transport method specified for the service in the JIF: JAMFLEX, STRING or an FML buffer.

For more information on message data, refer to "Service Messages and Data Types" in JetNet/Oracle Tuxedo Guide.

CODE returnCode

An integer to associate with the return. This code can be examined by the client agent; it is ignored by the middleware. If omitted, the default return value is 0.

JetNet, Oracle Tuxedo

Server

The service_return command returns data from a service request and indicates to the middleware whether the service was performed successfully. service_return and service_forward are the only commands by which a service can be explicitly completed. If a service routine terminates without using either of these, Panther completes the service automatically as if the service_return command were invoked with an empty argument list, with a returnCode equal to the return value from the service routine, and with a returnStatus of either FAILURE (if the service return value is negative), or SUCCESS (if the return value is 0 or greater).

All properties are restored to default settings after execution of service_return, since the service routine will have terminated.

On the client side, the tp_svc_outcome property is set to the service's return status, where it can be inspected by the client. The tp_svc_return property is set to the return code.

The tp_tran_status property is set to TP_WILL_ABORT if the service returned with a FAILURE or EXIT status.

If the JIF defines a service to use the transaction manager, any data that the transaction manager returns is automatically appended to the message argument. For example, service customer_s specifies Select as its transaction type. When that service returns, the middleware appends the query results to the reply message.

If a transaction returns data to the client, the service_return call must specify a message argument. Thus, a service that specifies Select as its transaction type returns (if successful) with the results of the database query, so service_return must specify a message argument; conversely, a Delete transaction returns no data to the client, so a service_return command that returns from a service of that transaction type can omit its message argument.

If a transaction returns data and the service_return command has no message data of its own, the command must use the default mapping format for its message arguments: {...}. For example:

service_return SUCCESS ({...})

service_return can generate the following exceptions:

Exception	Severity	Cause
TP_INVALID_ARGUMENT	TP_COMMAND	Invalid arguments are supplied
TP_INVALID_ARGUMENT_LIST	TP_COMMAND	Invalid arguments are supplied
TP_INVALID_CONTEXT	TP_COMMAND	Command is used outside of the service, or out of context

If, during processing of a service_return command, an exception of severity TP_ERROR or greater occurs before control returns to the middleware, the service is completed with an error return status. Panther ensures an error return status by using a FAILURE status unless the service_return command explicitly specifies an EXIT status, in which case an EXIT status is used.

The following code is the DEPOSIT service. The client side of this process is shown in the xa_end command.

proc deposit()
// service DEPOSIT
vars amount
receive arguments ({account_id, amount})
call sm_tm_command("SELECT")

if (!@dmrowcount)
{
	service_return failure ({message = "Invalid account."})
}
// need to check that overflow will not happen when
// depositing
if (account_balance + amount > max_balance)
{
	service_return failure \
		({message = "Balance field overflow"})
}
account_balance = account_balance + amount
call sm_tm_command("SAVE")
service_return ({message = @tpi_null, \
	balance = account_balance})

service_call, service_forward, xa_begin, xa_end

---

---