Programming Guide


Returns from a service request invocation


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


Specifies the service return status with one of these values:

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




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.

Appending Transaction Manager Data to Reply Messages

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

Invalid arguments are supplied


Invalid arguments are supplied


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})

See Also

service_call, service_forward, xa_begin, xa_end