Programming a Tuxedo ATMI Application Using C

Introduction to BEA Tuxedo Programming

BEA Tuxedo Distributed Application Programming

Communication Paradigms

BEA Tuxedo Clients

BEA Tuxedo Servers

Basic Server Operation

Servers as Requesters

BEA Tuxedo API: ATMI

Programming Environment

Updating the UBBCONFIG Configuration File

Setting Environment Variables

Including the Required Header Files

Starting and Stopping the Application

Managing Typed Buffers

Overview of Typed Buffers

Allocating a Typed Buffer

Putting Data in a Buffer

Resizing a Typed Buffer

Checking for Buffer Type

Freeing a Typed Buffer

Using a VIEW Typed Buffer

Setting Environment Variables for a VIEW Typed Buffer

Creating a View Description File

Executing the VIEW Compiler

Using an FML Typed Buffer

Setting Environment Variables for an FML Typed Buffer

Creating a Field Table File

Creating an FML Header File

Using an XML Typed Buffer and the Apache Xerces C++ Parser

About the XML Typed Buffer

About the Apache Xerces C++ Parser

XML Parser Control

XML Parser Support for ICU

XML Parser Sample Application

Xerces Schema Sample

Converting XML Data To and From FML/FML32 Buffers

Using On-Demand Conversion

Using Automatic Conversion

Mapping XML To and From FML/FML32 Field Types

Conversion Limitations

Using an MBSTRING Typed Buffer

Multibyte Character Encoding Control

Enabling MBSTRING to be Self-describing

Implementation

Safe/Unsafe Encoding Names

Multibyte Character Support Limitations

Multibyte Character Encoding Support for GNU libiconv

Customizing a Buffer

Defining Your Own Buffer Types

Coding Switch Element Routines

Adding a New Buffer Type to tm_typesw

Compiling and Linking Your New tm_typesw

Compiling and Linking Your New tm_typesw for a 16-bit Windows Platform

Data Conversion

Writing Clients

Joining an Application

Using Features of the TPINIT Typed Buffer

Client Naming

Unsolicited Notification Handling

System Access Mode

Resource Manager Association

Client Authentication

Leaving the Application

Building Clients

See Also

Client Process Examples

Writing Servers

BEA Tuxedo System main( )

System-Supplied Server and Services

System-Supplied Server: AUTHSVR( )

System-Supplied Services: tpsvrinit( ) Function

Receiving Command-line Options

Opening a Resource Manager

System-Supplied Services: tpsvrdone( ) Function

Guidelines for Writing Servers

Defining a Service

Example: Checking the Buffer Type

Example: Checking the Priority of the Service Request

Terminating a Service Routine

Sending Replies

Invalidating Descriptors

Forwarding Requests

Advertising and Unadvertising Services

Advertising Services

Unadvertising Services

Example: Dynamic Advertising and Unadvertising of a Service

Building Servers

See Also

Using a C++ Compiler

Declaring Service Functions

Using Constructors and Destructors

Writing Request/Response Clients and Servers

Overview of Request/Response Communication

Sending Synchronous Messages

Example: Using the Same Buffer for Request and Reply Messages

Example: Testing for Change in Size of Reply Buffer

Example: Sending a Synchronous Message with TPSIGRSTRT Set

Example: Sending a Synchronous Message with TPNOTRAN Set

Example: Sending a Synchronous Message with TPNOCHANGE Set

Sending Asynchronous Messages

Sending an Asynchronous Request

Example: Sending an Asynchronous Message with TPNOTRAN | TPNOREPLY

Example: Sending Asynchronous Requests

Getting an Asynchronous Reply

Setting and Getting Message Priorities

Setting a Message Priority

Getting a Message Priority

Writing Conversational Clients and Servers

Overview of Conversational Communication

Joining an Application

Establishing a Connection

Sending and Receiving Messages

Sending Messages

Receiving Messages

Ending a Conversation

Example: Ending a Simple Conversation

Example: Ending a Hierarchical Conversation

Executing a Disorderly Disconnect

Building Conversational Clients and Servers

Understanding Conversational Communication Events

Writing Event-based Clients and Servers

Overview of Events

Unsolicited Events

Brokered Events

Notification Actions

EventBroker Servers

System-defined Events

Programming Interface for the EventBroker

Defining the Unsolicited Message Handler

Sending Unsolicited Messages

Broadcasting Messages by Name

Broadcasting Messages by Identifier

Checking for Unsolicited Messages

Subscribing to Events

Notification via Unsolicited Message

Notification via Service Call or Reliable Queue

Unsubscribing from Events

Posting Events

Example of Event Subscription

Writing Global Transactions

What Is a Global Transaction?

Starting the Transaction

Suspending and Resuming a Transaction

Suspending a Transaction

Resuming a Transaction

Example: Suspending and Resuming a Transaction

Terminating the Transaction

Committing the Current Transaction

Prerequisites for a Transaction Commit

Two-phase Commit Protocol

Aborting the Current Transaction

Example: Committing a Transaction in Conversational Mode

Example: Testing for Participant Errors

Implicitly Defining a Global Transaction

Implicitly Defining a Transaction in a Service Routine

Defining Global Transactions for an XA-Compliant Server Group

Testing Whether a Transaction Has Started

See Also

Programming a Multithreaded and Multicontexted ATMI Application

Support for Programming a Multithreaded/Multicontexted ATMI Application

Platform-specific Considerations for Multithreaded/Multicontexted Applications

Planning and Designing a Multithreaded/Multicontexted ATMI Application

What Are Multithreading and Multicontexting?

What Is Multithreading?

What Is Multicontexting?

Licensing a Multithreaded or Multicontexted Application

Advantages and Disadvantages of a Multithreaded/Multicontexted ATMI Application

Advantages of a Multithreaded/Multicontexted ATMI Application

Disadvantages of a Multithreaded/Multicontexted ATMI Application

How Multithreading and Multicontexting Work in a Client

Start-up Phase

Client Threads Join Multiple Contexts

Client Threads Switch to an Existing Context

Work Phase

Service Requests

Replies to Service Requests

Transactions

Unsolicited Messages

Userlog Maintains Thread-specific Information

Completion Phase

How Multithreading and Multicontexting Work in an ATMI Server

Start-up Phase

Work Phase

Server-dispatched Threads Are Used

Application-created Threads Are Used

Bulletin Board Liaison Verifies Sanity of System Processes

System Keeps Statistics on Server Threads

Userlog Maintains Thread-specific Information

Completion Phase

Design Considerations for a Multithreaded and Multicontexted ATMI Application

Environment Requirements

Design Requirements

Is the Task of Your Application Suitable for Multithreading and/or Multicontexting?

How Many Applications and Connections Do You Want?

What Synchronization Issues Need to Be Addressed?

Will You Need to Port Your Application?

Which Threads Model Is Best for You?

Interoperability Restrictions for Workstation Clients

Implementing a Multithreaded/ Multicontexted ATMI Application

Preliminary Guidelines for Programming a Multithreaded/Multicontexted ATMI Application

Prerequisites for a Multithreaded ATMI Application

General Multithreaded Programming Considerations

Concurrency Considerations

Writing Code to Enable Multicontexting in an ATMI Client

Context Attributes

Setting Up Multicontexting at Initialization

Implementing Security for a Multicontexted ATMI Client

Synchronizing Threads Before an ATMI Client Termination

Switching Contexts

Handling Unsolicited Messages

Coding Rules for Transactions in a Multithreaded/Multicontexted ATMI Application

Writing Code to Enable Multicontexting and Multithreading in an ATMI Server

Context Attributes

Coding Rules for a Multicontexted ATMI Server

Initializing and Terminating ATMI Servers and Server Threads

Programming an ATMI Server to Create Threads

Creating Threads

Associating Threads with a Context

Sample Code for Creating an Application Thread in a Multicontexted ATMI Server

Writing a Multithreaded ATMI Client

Coding Rules for a Multithreaded ATMI Client

Initializing an ATMI Client to Multiple Contexts

Context State Changes for an ATMI Client Thread

Getting Replies in a Multithreaded Environment

Using Environment Variables in a Multithreaded and/or Multicontexted Environment

Using Per-context Functions and Data Structures in a Multithreaded ATMI Client

Using Per-process Functions and Data Structures in a Multithreaded ATMI Client

Using Per-thread Functions and Data Structures in a Multithreaded ATMI Client

Sample Code for a Multithreaded ATMI Client

Writing a Multithreaded ATMI Server

Compiling Code for a Multithreaded/Multicontexted ATMI Application

Testing a Multithreaded/Multicontexted ATMI Application

Testing Recommendations for a Multithreaded/Multicontexted ATMI Application

Troubleshooting a Multithreaded/Multicontexted ATMI Application

Improper Use of the TPMULTICONTEXTS Flag to tpinit( )

Calls to tpinit( ) Without TPMULTICONTEXTS

Insufficient Thread Stack Size

Error Handling for a Multithreaded/Multicontexted ATMI Application

Managing Errors

System Errors

Abort Errors

BEA Tuxedo System Errors

Call Descriptor Errors

Limit Errors

Invalid Descriptor Errors

Conversational Errors

Duplicate Object Error

General Communication Call Errors

TPESVCFAIL and TPESVCERR Errors

TPEBLOCK and TPGOTSIG Errors

Invalid Argument Errors

MIB Error

No Entry Errors

Operating System Errors

Permission Errors

Protocol Errors

Queuing Error

Release Compatibility Error

Resource Manager Errors

Timeout Errors

Transaction Errors

Typed Buffer Errors

Application Errors

Handling Errors

Transaction Considerations

Communication Etiquette

Transaction Errors

Non-fatal Transaction Errors

Fatal Transaction Errors

Heuristic Decision Errors

Transaction Timeouts

Effect on the tpcommit() Function

Effect on the TPNOTRAN Flag

tpreturn( ) and tpforward( ) Functions

tpterm( ) Function

Resource Managers

Sample Transaction Scenarios

Called Service in Same Transaction as Caller

Called Service in Different Transaction with AUTOTRAN Set

Called Service That Starts a New Explicit Transaction

BEA TUXEDO System-supplied Subroutines

Central Event Log

Log Name

Log Entry Format

Writing to the Event Log

Debugging Application Processes

Debugging Application Processes on UNIX Platforms

Debugging Application Processes on Windows 2003 Platforms

Comprehensive Example

Contact BEA |  Feedback |  Privacy  |