Sending Unsolicited Messages


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

Programming a BEA Tuxedo Application Using COBOL

The BEA Tuxedo system allows unsolicited messages to be sent to client processes without disturbing the processing of request/response calls or conversational communications.

Unsolicited messages can be sent to client processes by name, using TPBROADCAST(3cbl), or by an identifier received with a previously processed message, using TPNOTIFY(3cbl). Messages sent via TPBROADCAST can originate either in a service or in another client. Messages sent via TPNOTIFY can originate only in a service.

Broadcasting Messages By Name

The TPBROADCAST(3cbl) routine allows a message to be sent to registered clients of the application. It can be called by a service or another client. Registered clients are those that have successfully made a call to TPINITIALIZE and have not yet made a call to TPTERM.

Use the following signature to call the TPBROADCAST routine.

01 TPBCTDEF-REC.
   COPY TPBCTDEF.
01 TPTYPE-REC.
   COPY TPTYPE.
01 DATA-REC.
   COPY User Data.
01 TPSTATUS-REC.
   COPY TPSTATUS.
CALL "TPBROADCAST" USING TPBCTDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.

The following table describes the members of the TPBCTDEF-REC data structure.

TPBCTDEF-REC Data Structure Members

Member
Description

LMID

Pointer to the logical machine identifier for the client. A value of SPACES acts as a wildcard, so that a message can be directed to groups of clients.

USRNAME

User name of the client process, if one exists. A value of SPACES acts as a wildcard, so that a message can be directed to groups of clients.

CLTNAME

Client name of the client process, if one exists. A value of NULL acts as a wildcard, so that a message can be directed to groups of clients.

Settings (such as TPBLOCK-FLAG)

Settings for the TPBROADCAST command. Refer to TPBROADCAST(3cbl) in the BEA Tuxedo COBOL Function Reference for information on available settings.

Member	Description
LMID	Pointer to the logical machine identifier for the client. A value of SPACES acts as a wildcard, so that a message can be directed to groups of clients.
USRNAME	User name of the client process, if one exists. A value of SPACES acts as a wildcard, so that a message can be directed to groups of clients.
CLTNAME	Client name of the client process, if one exists. A value of NULL acts as a wildcard, so that a message can be directed to groups of clients.
Settings (such as TPBLOCK-FLAG)	Settings for the TPBROADCAST command. Refer to TPBROADCAST(3cbl) in the BEA Tuxedo COBOL Function Reference for information on available settings.

Refer to Defining a Service for a description of the TPTYPE-REC record.

The following example illustrates a call to TPBROADCAST for which all clients are targeted. The message to be sent is contained in a STRING record.

Using TPBROADCAST

    . . .
**************************************************
* Prepare the record to broadcasted
**************************************************
    MOVE "HELLO, WORLD" TO DATA-REC.
    MOVE 11 TO LEN.
    MOVE "STRING" TO REC-TYPE.
*
    SET TPNOBLOCK TO TRUE.
    SET TPNOTIME TO TRUE.
    SET TPSIGRSTRT TO TRUE.
*
    MOVE SPACES TO LMID.
    MOVE SPACES TO USRNAME.
    MOVE SPACES TO CLTNAME.
    CALL "TPBROADCAST" USING TPBCTDEF-REC
                       TPTYPE-REC
                       DATA-REC
                       TPSTATUS-REC.
    IF NOT TPOK
        error processing

Broadcasting Messages by Identifier

The TPNOTIFY(3cbl) routine is used to broadcast a message using an identifier received with a previously processed message. It can be called only from a service.

Use the following signature to call the TPNOTIFY routine.

01 TPSVCDEF-REC.
   COPY TPSVCDEF.
01 TPTYPE-REC.
   COPY TPTYPE.
01 DATA-REC.
   COPY User Data.
01 TPSTATUS-REC.
   COPY TPSTATUS.
CALL "TPNOTIFY" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.

Refer to Writing Global Transactions for information on the TPSVCDEF-REC data structure, and Defining a Service for a description of the TPTYPE-REC record.