TPSETUNSOL(3cbl)


	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

TPSETUNSOL(3cbl)

Name

TPSETUNSOL() - sets method for handling unsolicited messages

Synopsis

01 CURR-ROUTINE  PIC S9(9) COMP-5. 
 
01 PREV-ROUTINE  PIC S9(9) COMP-5. 
 
01 TPSTATUS-REC.
   COPY TPSTATUS.  
 
CALL "TPSETUNSOL" USING CURR-ROUTINE PREV-ROUTINE TPSTATUS-REC.

Description

TPSETUNSOL() allows a client to identify the routine that should be invoked when an unsolicited message is received by the BEA Tuxedo system libraries. Before the first call to TPSETUNSOL(), any unsolicited messages received by the BEA Tuxedo system libraries on behalf of the client are logged and ignored. A call to TPSETUNSOL() with a function number, CURR-ROUTINE, set to 0 has the same effect. The method used by the system for notification and detection is determined by the application default, which can be overridden on a per-client basis (see TPINITIALIZE(3cbl)).

The routine number passed, in CURR-ROUTINE, on the call to TPSETUNSOL() selects one of 16 predefined routines. The routine names must be _tm_dispatch1 through _tm_dispatch8 for C routines that provide unsolicited message handling and TMDISPATCH9 through TMDISPATCH16 for COBOL routines that provide the same message handling. The C functions (_tm_dispatch1 through _tm_dispatch8) must conform to the parameter definition described in tpsetunsol(3c). The COBOL routines (TMDISPATCH9 through TMDISPATCH16) must use TPGETUNSOL() to receive the data.

Processing within the unsolicited message handling routine in a C application is restricted to the following BEA Tuxedo functions: tpalloc(), tpfree(), tpgetctxt(), tpgetlev(), tprealloc(), and tptypes().

Processing within the unsolicited message handling routine in a COBOL application is restricted to the following BEA Tuxedo functions: TPGETLEV() and TPGETCTXT().

Return Values

Upon successful completion, TPSETUNSOL() sets TP-STATUS to [TPOK] and returns the previous setting for the unsolicited message handling routine (0 in PREV-ROUTINE is a successful return indicating that no message handling routine had been set previously).

Errors

Under the following conditions, TPSETUNSOL() fails and sets TP-STATUS to:

[TPEINVAL]: Invalid arguments were given (for example, CURR-ROUTINE is not a valid routine value).
[TPEPROTO]: TPSETUNSOL() was called in an improper context (for example, from within a server).
[TPESYSTEM]: A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.
[TPEOS]: An operating system error has occurred.

Portability

The interfaces described in TPNOTIFY() are supported on native site UNIX-based processors. In addition, the routines TPBROADCAST() and TPCHKUNSOL() as well as the routine TPSETUNSOL() are supported on UNIX and MS-DOS workstation processors.

TPSETUNSOL() is not supported on Windows, OS/2, and RS6000 due to the way that Dynamic Link Libraries and Shared Libraries work in these environments; TPEPROTO() will be returned if called on these platforms. Use the C-language interface tpsetunsol() to set up a handler function in these environments.