Contents

1. Introduction and Overview

The BEA TUXEDO System Development Environment

Client Processes

Basic Client Operation

Client Sending Repeated Service Requests

Server Processes and Service Subroutines

Basic Server Operation

Servers as Requesters

The ATMI Primitives

An Overview of X/Open's TX Interface

Typed Buffers

Using VIEW and FML Buffers

Relationship Between Some VIEW Buffers and FML

Corresponding Data Type Definitions

Creating Header Files from View Descriptions

Header Files from Field Tables

Other Header Files

Environment Variables

Configuration File

Making the Configuration Usable

The Bulletin Board

Starting and Stopping an Application

Service Gateway

Programming Paradigms

Buffer Types

Configuration

Examples

2. Writing Client Programs

About This Chapter

Examples Taken from the Sample Application

Preliminaries

Client Naming

Unsolicited Notification

Security and Client Authentication

Writing Client Programs with SECURITY Set

Getting the Security Data

Joining the Application

Allocating the TPINIT Buffer

The Application Key

Joining and Leaving an Application

Buffer Management

Typed Buffers for Messages

Buffer Types: STRING

Buffer Types: CARRAY

Buffer Types: FML and FML32

Buffer Types: VIEW, VIEW32, X_C_TYPE, and X_COMMON

Buffer Types: Summary

ATMI Buffer Primitives

Allocating a Typed Buffer

tpalloc Examples

What About FML Buffer Management Functions?

Putting Data in the Buffer

Resizing a Typed Buffer

Checking for Buffer Type

Freeing a Typed Buffer

Service Calls

Sending Synchronous Messages: tpcall()

Values for the flags Argument: tpcall()

Examples of the Use of flags Arguments

Sending Asynchronous Messages: tpacall()

Values for the flags Argument: tpacall()

Getting an Asynchronous Reply: tpgetrply()

Getting and Setting Priority

Initiating a Conversational Connection

Sending a Broadcast Message

Compiling Client Programs

The buildclient Command

The buildclient -o Option

The buildclient -f and -l Options

3. Writing Service Routines

Writing Request/Response Services

Examples Taken from the Sample Application

Application Service Template

The TPSVCINFO Structure

The tpreturn() and tpforward() Functions

Sending Replies

Forwarding Requests

Sending Unsolicited Messages

Advertising, Unadvertising Services

System-Supplied Servers and Subroutines

System-Supplied Servers

AUTHSVR

The BEA TUXEDO System main()

BEA TUXEDO System-Supplied Subroutines

tpsvrinit()

tpsvrdone()

Compiling Subroutines to Build Servers

The buildserver Command

The buildserver -o Option

The buildserver -f and -l Options

The buildserver -r Option

The buildserver -s Option

Using C++

4. Conversational Clients and Services

Writing Conversational Clients and Services

Conversational Mode

The Connection Descriptor

Buffer Management

Joining an Application

Establishing a Connection

Values for the flags Argument: tpconnect()

Sending

Values for the flags Argument: tpsend()

Receiving

Values for the flags Argument: tprecv()

Ending a Conversation

Subordinate Calls tpreturn()

Hierarchy of Connections and tpreturn()

Ending a Conversation: Summary

Events and Their Significance

Disorderly Disconnection

Request/Response Calls and Conversations

Configuration Parameters

Building Conversational Clients and Servers

5. Global Transactions in BEA TUXEDO System

Introduction

What Is a Global Transaction?

ATMI Transaction Primitives

Explicitly Defining a Global Transaction

Starting the Transaction

Terminating the Transaction

Implicitly Defining a Global Transaction

In a Client Process

In a Service Routine

6. Using the Event Broker

Introduction

Notification Actions

User-Defined and System-Defined Events

Event Broker/Event Monitor Servers

Programming Interface

Posting Events

tppost() Arguments: eventname

tppost() Arguments: data and len

tppost() Arguments: flags

Example of Event Posting

Subscribing to Events

tpsubscribe() Arguments: eventexpr

tpsubscribe() Arguments: filter

tpsubscribe() Arguments: ctl

Notification Via Unsolicited Message

Notification Via Service Call or Reliable Queue

tpsubscribe() Arguments: flags

Example of Event Subscription

7. Error Management

Introduction

Communicating Errors

Values of tperrno

Protocol Errors

BEA TUXEDO System Errors

Operating System Errors

Errors from Invalid Arguments

Other Possible Error Categories

No Entry Errors

Permission Errors

Resource Manager Errors

Transaction-Related Errors

Typed Buffer Errors

Call Descriptor Errors

General Communication Call Errors

Conversational Errors

Time-Out Errors

Errors Leading to Abort

Errors Signaling Heuristic Decisions

Application-Specific Errors

How to Deal with Errors

Fatal Transaction Errors

Time-Out

Blocking vs. Transaction Time-Out

Effect on tpcommit()

Effect of the TPNOTRAN Flag

Roles of tpreturn() and tpforward()

Service in Same Transaction as Caller

Service in Different Transaction with AUTOTRAN Set

Service Starts New Explicit Transaction

Transaction Rules

Communication Etiquette

BEA TUXEDO System-Supplied Subroutines

tpsvrinit()

tpsvrdone()

Leaving the Application

Global Transactions and Resource Managers

Comprehensive Example

The Central Event Log

How the Log Is Named

What Log Entries Look Like

How to Write to the Event Log

Debugging Application Processes