Programmer's Guide

 

This document provides a detailed description about using the BEA MessageQ application programming interface (API) to build and integrate distributed applications. This document contains both tutorial and reference information.

 

Sending and Receiving BEA MessageQ Messages

Overview

The Basics of Sending and Receiving Messages

Sending and Receiving Message Buffers

How to Send BEA MessageQ Messages

How to Send Large Messages

Receiving Messages Using Message Pointers

Self-Describing Messaging with FML

How Self-Describing Messaging Works

Benefits of Using FML

Performance Considerations When Using FML

Designing Applications to Use a Mixed Messaging Environment

How to Send an FML Message

Defining Field Identifiers

Building the FML Message

Sending the FML Message

How to Receive an FML Message

Reading the Message from the Queue

Interpreting the Message

Exchanging Messages Between BEA MessageQ and BEA TUXEDO or BEA M3

Enabling the Messaging Bridge

Data Transformation Between BEA MessageQ and TUXEDO

Data Types

Data Size and Length

Timeouts

Priorities

Target, Queue Space and Queue Name

Delivery

Undeliverable Messages

Correlation Identifiers

Return Values

Other BEA MessageQ API Elements

Other TUXEDO API Elements

 

Using Recoverable Messaging

Choosing a Message Delivery Mode

How the Message Recovery System Works

Choosing Recoverable and Nonrecoverable Delivery Modes

When to Use Nonrecoverable Message Delivery

When to Use Recoverable Message Delivery

Choosing an Undeliverable Message Action

How to Send a Recoverable Message

Sequence Numbers

Specifying Timeout Values

Checking Delivery Outcome

Checking the Delivery Status of WF Requests

Checking the Delivery Status of AK Requests

How to Receive a Recoverable Message

Confirming Message Receipt

Selecting a Confirmation Type

Selecting a Confirmation Order

Creating an Audit Trail of Confirmed Messages

Checking for Duplicate Messages

Using UMAs for Exception Processing

Using Discard and Discard and Log UMAs

Using the Return-to-Sender UMA

Using the Dead Letter Queue UMA

Using the Dead Letter Journal

Using the SAF UMA

Recoverable Messaging on BEA MessageQ Clients

 

Broadcasting Messages

How Message Broadcasting Works

Broadcast Scope

Named MOTs

Broadcast Communication Modes

Retransmission Protocol on BEA MessageQ for OpenVMS Systems

Sending Broadcast Messages

Receiving Broadcast Messages

Registering to Receive Broadcast Messages

Sending a Registration Message

Registering to Receive Selected Broadcast Messages

Registration Acknowledgment

Reading Broadcast Messages

Deregistering from Receiving Broadcast Messages

Running Existing SBS Applications

 

Using Naming

Understanding Naming

What is Naming?

What is a Name Space?

What is the Naming Agent?

Configuring Bus-Wide Naming

How Applications Use Naming

Specifying Names and Pathnames

Attaching and Locating Queues

Static and Dynamic Binding of Queue Addresses

How Dynamic Binding of Queue Addresses Works

How Caching and Binding Work

Examples of Static and Dynamic Binding

Client for Style 1 (Static Binding)

Client for Style 2 (Dynamic Binding)

Server for Style 1 (Static Binding)

Server for Style 2 (Dynamic Binding)

 

Using Message-Based Services

How Message-Based Services Work

Requesting a Service

Receiving a Response

Obtaining the Status of a Queue

Monitoring and Controlling Link Status

Listing Cross-Group Connections, Entries, and Groups

Obtain Notification of Cross-Group Links Established and Lost

Controlling Cross-Group Links

Link Management Control Functions

Link Management Design Considerations

Learning the Current Status of Queues

Listing Attached Queues in a Group

Receiving Attachment Notifications

Managing Message Recovery Files

Opening, Closing, and Failing Over SAF and DQF Files

Opening and Closing Auxiliary Journal Files

Controlling Journaling to the PCJ File

Transferring the Contents of a Destination Queue File

 

Building and Testing Applications

Formatting and Converting Message Data

Byte Order Conversion

Alignment of Data Structures

Writing Portable BEA MessageQ Applications

Compiling and Linking BEA MessageQ Applications

Using BEA MessageQ Include Files

Programming Language Support

Connecting to the BEA MessageQ Environment

Compiling and Linking Applications

UNIX Makefile

Windows NT Makefile

OpenVMS Build Procedure

Running a BEA MessageQ Application

Running Existing BEA MessageQ Applications Under Version 5.0

Testing Return Status

Using the BEA MessageQ Test Utility

Debugging BEA MessageQ Applications

Tracing Messages on UNIX Systems

Tracing Messages on Windows NT Systems

Tracing Messages on OpenVMS Systems

Controlling Message Flow

 

Using the Script Facility

How to Use the Script Facility

Using the BEA MessageQ Scripting Language

Capturing, Replaying, and Simulating Message Exchange

Capturing Messages Using Scripts

Controlling Message Delivery Using Scripts

Displaying Captured Messages on the Screen

Writing Captured Messages to a Log File

Writing Captured Messages to Multiple Log Files

Replaying Messages

Script Processing on UNIX Systems

Script Processing on OpenVMS Systems

Writing Scripts to Send Messages

Defining Messages in Scripts

Defining the Message Header

Additional Arguments for UNIX Systems

Defining the Message Data

Adding Repeats, Delays, and Comments to Scripts

Repeating an Operation

Entering Time Delays

Entering Comments

End-of-Line Format

Comment Command Format

Verifying Script Files

Verifying Scripts on UNIX Systems

Verifying Scripts on OpenVMS Systems

Resolving Script Verification Errors

 

PAMS Application Programming Interface

BEA MessageQ API Description Format

BEA MessageQ API Data Types

pams_attach_q

pams_bind_q

pams_cancel_get

pams_cancel_select

pams_cancel_timer

pams_close_jrn

pams_confirm_msg

pams_detach_q

pams_exit

pams_get_msg

pams_get_msga

pams_get_msgw

pams_locate_q

pams_open_jrn

pams_put_msg

pams_read_jrn

pams_set_select

pams_set_timer

pams_status_text

putil_show_pending

 

Message Reference

AVAIL

AVAIL_DEREG

AVAIL_REG

AVAIL_REG_REPLY

DISABLE_NOTIFY

DISABLE_Q_NOTIFY_REQ

DISABLE_Q_NOTIFY_RESP

ENABLE_NOTIFY

ENABLE_Q_NOTIFY_REQ

ENABLE_Q_NOTIFY_RESP

LINKMGT_REQ

LINKMGT_RESP

LINK_COMPLETE

LINK_LOST

LIST_ALL_CONNECTIONS (Request)

LIST_ALL_CONNECTIONS (Response)

LIST_ALL_ENTRIES (Request)

LIST_ALL_ENTRIES (Response)

LIST_ALL_GROUPS (Request)

LIST_ALL_GROUPS (Response)

LIST_ALL_Q_REQ

LIST_ALL_Q_RESP

LOCATE_Q_REP

MRS_ACK

MRS_DQF_SET

MRS_DQF_SET_REP

MRS_DQF_TRANSFER

MRS_DQF_TRANSFER_ACK

MRS_DQF_TRANSFER_REP

MRS_JRN_DISABLE

MRS_JRN_DISABLE_REP

MRS_JRN_ENABLE

MRS_JRN_ENABLE_REP

MRS_SAF_SET

MRS_SAF_SET_REP

MRS_SET_DLJ

MRS_SET_DLJ_REP

MRS_SET_PCJ

MRS_SET_PCJ_REP

Q_UPDATE

SBS_DEREGISTER_REQ

SBS_DEREGISTER_RESP

SBS_REGISTER_REQ

SBS_REGISTER_RESP

SBS_SEQUENCE_GAP

SBS_STATUS_REQ

SBS_STATUS_RESP

TIMER_EXPIRED

UNAVAIL

 

Supported Delivery Modes and Undeliverable Message Actions

Delivery Mode and UMA Cross-Reference

 

Obsolete Functions and Services

Obsolete Message-Based Services for Message Broadcasting

SBS_BS_SEQGAP

SBS_DEREG

SBS_DEREG_ACK

SBS_DEREG_BY_ID

SBS_REG

SBS_REG_EZ

SBS_REG_EZ_REPLY

SBS_REG_REPLY

Obsolete PAMS API Functions

pams_create_handle

pams_decode

pams_delete_handle

pams_encode

pams_extract_buffer

pams_insert_buffer

pams_msg_length

pams_next_msg_field

pams_remove_encoding

pams_set_msg_position