PURPOSE

TPSETUNSOL - set method of 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 System/T libraries. Prior to the first call to TPSETUNSOL, any unsolicited messages received by the System/T 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 routine _tm_dispatch1 through _tm_dispatch8 must conform to the parameter definition described in tpsetunsol(3c). Routines TMDISPATCH9 through TMDISPATCH16 must use TPGETUNSOL(3cbl) to receive the data.

Processing within the C language application unsolicited message handling routine is restricted to the following System/T calls:


tpalloc(3c)	
tpgetlev(3c)	
tprealloc(3c)
tptypes(3c)	
tpfree(3c)

Processing within the COBOL language application unsolicited message handling routine is restricted to the following System/T call: TPGETLEV(3cbl)

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 (e.g., from within a server).
[TPESYSTEM]: A System/T 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(3cbl) are supported on native site UNIX-based processors. In addition, the routines TPBROADCAST(3cbl) and TPCHKUNSOL(3cbl) as well as the routine TPSETUNSOL are supported on UNIX and MS-DOS workstation processors.