CONTENTS Title Page Copyright Page Preface Part I Using DECmessageQ 1 Understanding DECmessageQ Overview of DECmessageQ Designing Your DECmessageQ Application System Design and Configuration DECmessageQ Configuration Communication Models Sending a Message Message Definition Message Formats Receiving a Message Queue Types and Queue Attributes Message Selection Additional Programming Services Creating Selection Masks Locating the Address of a Queue Setting Timers Displaying Pending Messages for a Queue Advanced Message Queuing Features Sending Recoverable Messages Broadcasting Messages Building Applications Using the Script Facility Using Message-Based Services 2 Sending Recoverable Messages 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 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 DECmessageQ Clients 3 Broadcasting Messages How Message Broadcasting Works Broadcast Scope Named MOTs Broadcast Communication Modes 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 4 Building and Testing Applications Formatting and Converting Message Data Byte Order Conversion Alignment of Data Structures Writing Portable DECmessageQ Applications Compiling and Linking DECmessageQ Applications Using DECmessageQ Include Files Connecting to the DECmessageQ Environment Compiling and Linking Applications UNIX Makefile Windows NT Makefile Building Your Macintosh Application OpenVMS Build Procedure Running a DECmessageQ Application Testing Return Status Using the DECmessageQ Test Utility Debugging DECmessageQ Applications Tracing Messages on UNIX Systems Tracing Messages on Windows NT Systems Tracing Messages on OpenVMS Systems 5 Using the Script Facility How to Use the Script Facility Using the DECmessageQ 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 Defining the Message Data Adding Repeats, Delays, and Comments to Scripts Repeating an Operation Entering Time Delays Entering Comments Verifying Script Files Verifying Scripts on UNIX Systems Verifying Scripts on OpenVMS Systems Resolving Script Verification Errors 6 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 Managing Message Recovery Files Opening, Closing and Failing Over SAF and DQF Files Opening and Closing Auxillary Journal Files Controlling Journaling to the PCJ File Transferring the Contents of a Destination Queue File Learning the Current Status of Queues Listing Attached Queues in a Group Receiving Attachment Notifications Part II DECmessageQ Technical Reference 7 Application Programming Interface pams_attach_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 putil_show_pending 8 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_BS_SEQGAP SBS_DEREG SBS_DEREG_ACK SBS_DEREG_BY_ID SBS_REG SBS_REG_EZ SBS_REG_EZ_REPLY SBS_REG_REPLY TIMER_EXPIRED UNAVAIL A Feature Reference B Programming Examples API Example Programs Example Descriptions C Supported Delivery Modes and Undeliverable Message Actions EXAMPLES 3-1 Creating a Named MOT 3-2 Configuring Ethernet Multicasting 4-1 Recommended #include Statements for DECmessageQ Applications 4-2 UNIX Makefile 4-3 Windows NT Makefile 4-4 Example OpenVMS Build Procedure 4-5 Command Procedure to Run as a Detached Process 4-6 Portable Code for Testing Return Status 5-1 Sample Script to Capture Messages 5-2 Sample Log Generated by a Script File 5-3 Sample Script Using Multiple Log Files 5-4 Turning On Scripts for a Running Application 5-5 Sample Script to Send a Message 5-6 Message Header Format 5-7 UNIX Message Header Format 5-8 Sample Script File With Errors 5-9 Sample Output of Script File Verification Utility FIGURES 1-1 Simple Request/Response Communication Model 1-2 Communication Model for Handling a Service Point 1-3 Queue Type and Queue Attribute Choice Hierarchy 2-1 Message Flow for Sending a Recoverable Message 2-2 PAMS Status Block 2-3 Message Flow for Receiving a Recoverable Message 3-1 DECmessageQ Broadcast Stream 3-2 SBS Message Transport Via Networks 3-3 SBS Message Transport via Multicasting 3-4 SBS Server Message Flow 4-1 DECmessageQ Test Utility 5-1 Sending Messages and Capturing Output 5-2 Sending Messages and Capturing Input 5-3 Capturing Output Without Sending Messages 5-4 Replaying Captured Messages 5-5 Receiving Messages from Applications and Scripts 5-6 Writing Scripts to Send and Capture Messages 6-1 Avail Server Message Flow 6-2 Requesting Cross-Group Information 6-3 Requesting Cross-Group Link Status 6-4 Using Link Management 6-5 MRS Server Message Flow 6-6 MRS Server Message Flow 6-7 Disabling Journaling 6-8 Qtransfer Server Message Flow 6-9 Listing All Queues 6-10 Listing Available Queues TABLES 1-1 Using DECmessageQ Application Programming Services 2-1 Supported Delivery Modes 2-2 Valid UMAs 2-3 PAMS Status Block 2-4 PSB Delivery Status Values 2-5 UMA Status Values 2-6 How to Use UMAs 3-1 Valid Operators for SBS_REG 4-1 C Include File Cross-Reference 4-2 Location of Include Files 4-3 DECmessageQ for OpenVMS Logical Names 4-4 Default Settings 5-1 DECmessageQ Script Facility Commands 5-2 Script Control Commands for UNIX 5-3 Script File Message Data Formats 6-1 Overview of Message-Based Services 6-2 Link Management Design Considerations 7-1 Callable Services Description Format 7-2 Valid Name Tables A-1 DECmessageQ Function Cross-Reference B-1 Where to Find DECmessageQ Programming Examples B-2 Callable Services Examples B-3 Example Descriptions C-1 Delivery Mode and UMA Cross-Reference