Contents for 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