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   |   Reference   |   Topic List   |   Previous   |   Next   |   Contents

   BEA Tuxedo COBOL Function Reference

TPFORWAR() - forward a BEA Tuxedo system service request to another routine

01 TPSVCDEF-REC.
 COPY TPSVCDEF. 
 
01 TPTYPE-REC.
 COPY TPTYPE. 
 
01 DATA-REC.
 COPY User data. 
 
01 TPSTATUS-REC.
 COPY TPSTATUS.
 
COPY TPFORWAR REPLACING TPSVCDEF-REC BY TPSVCDEF-REC
 TPTYPE-REC BY TPTYPE-REC
 DATA-REC BY DATA-REC
 TPSTATUS-REC BY TPSTAUS-REC 

TPFORWAR() allows a service routine to forward a client's request to another service routine for further processing. Since TPFORWAR() contains an EXIT PROGRAM statement, it should be called from within the same routine that was invoked to ensure correct return of control to the BEA Tuxedo system dispatcher (that is, TPFORWAR() should not be invoked in a sub-program of the service routine since control would not return to the BEA Tuxedo system dispatcher). TPFORWAR() cannot be called from within a conversational service.

This routine forwards a request to the service named by SERVICE-NAME in TPSVCDEF-REC using data contained in DATA-REC. A service routine forwarding a request receives no reply. After the request is forwarded, the service routine returns to the BEA Tuxedo system dispatcher and the server is free to do other work. Note that because no reply is expected from a forwarded request, the request may be forwarded without error to any service routine in the same executable as the service which forwarded the request.

If the service routine is in transaction mode, this routine puts the caller's portion of the transaction in a state where it may be completed when the originator of the transaction issues either TPCOMMIT() or TPABORT(). If a transaction was explicitly started with TPBEGIN() while in a service routine, the transaction must be ended with either TPCOMMIT() or TPABORT() before calling TPFORWAR(). Thus, all services in a "forward chain" are either all started in transaction mode or none are started in transaction mode.

The last server in a forward chain sends a reply back to the originator of the request using TPRETURN(). In essence, TPFORWAR() transfers to another server the responsibility of sending a reply back to the awaiting requester.

TPFORWAR() should be called after receiving all replies expected from service requests initiated by the service routine. Any outstanding replies which are not received will automatically be dropped by the BEA Tuxedo system dispatcher upon receipt. In addition, the communications handle for those replies become invalid and the request is not forwarded to SERVICE-NAME.

DATA-REC is the record to be sent and LEN in TPTYPE-REC specifies the amount of data in DATA-REC that should be sent. Note that if DATA-REC is a record of a type that does not require a length to be specified, then LEN is ignored (and may be 0). If REC-TYPE in TPTYPE-REC is SPACES, DATA-REC and LEN are ignored and a request with zero length data is sent. If REC-TYPE is STRING and LEN is 0, then the request is sent with no data portion.

Since the service routine writer does not regain control after calling TPFORWAR(), a blocking send with signal restart is used (that is, TPSIGRSTRT is implied). Currently, settings in TPSVCDEF-REC are reserved for future use and any specified are ignored.

A service routine does not return any value to its caller, the BEA Tuxedo system dispatcher. Thus, TP-STATUS is not set.

If any errors occur either in the handling of the parameters passed to the routine or in its processing, a "failed" message is sent back to the original requester (unless no reply is to be sent). The existence of outstanding replies or subordinate connections, or the caller's transaction being marked abort-only, qualify as failures which generate failed messages. Failed messages are detected by the requester with the TPESVCERR() error indication. When such an error occurs, the caller's data is not sent. Also, this error causes the caller's current transaction to be marked abort-only.

If a transaction timeout occurs either while in the service routine or while forwarding the request, the requester waiting for a reply with either TPCALL(), or TPGETRPLY() will get a TPETIME error return. Also, the waiting requester will not receive any data. Service routines, however, are expected to terminate using either TPRETURN() or TPFORWAR(). A conversational service routine must use TPRETURN(), and cannot use TPFORWAR().

If a service routine returns without using either TPRETURN() or TPFORWAR() or TPFORWAR() is called from a conversational server, the server will print a warning message in a log file and return a service error to the original requester. All open connections to subordinates will be disconnected immediately, and any outstanding asynchronous replies will be marked stale. If the server was in transaction mode at the time of failure, the transaction is marked abort-only. Note also that if either TPRETURN() or TPFORWAR() are used outside of a service routine (for example, in clients, or in TPSVRINIT() or TPSVRDONE()), then these routines simply return having no effect.

TPCONNECT(3cbl), TPRETURN(3cbl)