CONTENTS Title Page Copyright Page Preface 1 Introduction to Message Queuing 1.1 Overview 1.2 Messages 1.3 Message Queues 1.3.1 Queue Types 1.3.2 Queue Attributes 1.4 Message Queuing Groups 1.5 Message Queuing Bus 1.6 Application Programming Interface 1.6.1 Basic Call Set 1.7 Message Queuing Services 1.8 Tools and Utilities 2 Getting Started with Message Queuing 2.1 Identifying the Message Queuing Bus Environment 2.2 Using a Queue Address 2.2.1 Source Queue Address 2.2.2 Target Queue Address 2.3 Attaching to a Queue 2.4 Sending a Message 2.4.1 Sending a Datagram Message 2.5 Receiving a Message 2.5.1 Receiving a Datagram Message 2.6 Detaching from the Message Queuing Bus 2.7 Simple Client Flow 2.8 Further Suggestions 3 Developing an Application 3.1 Defining the Message Flow Between Programs 3.2 Specifying the Queues 3.3 Defining the Message Data Structure 3.4 Choosing Messaging Options 3.4.1 Choosing Nonrecoverable Message Delivery 3.4.2 Choosing Recoverable Message Delivery 3.5 Implementing the Program Flow 3.6 Debugging the Application 4 Messaging Options 4.1 Sending Options 4.1.1 Using the Priority Argument for Sending 4.1.2 Using Message Type and Class for Sending 4.1.3 Setting the Delivery Argument for Sending 4.1.4 Setting the UMA Argument 4.1.5 Setting the Timeout Argument for Sending 4.1.6 Using the PSB Argument for Sending 4.1.7 Using the Resp_q Argument 4.2 Receiving Options 4.2.1 Using the Priority Argument for Receiving 4.2.2 Using the Source Argument 4.2.3 Using Message Type and Class for Receiving 4.2.4 Using the Len_data Argument 4.2.5 Using the Timeout Argument for Receiving 4.2.6 Using the Sel_filter Argument 4.2.7 Using the PSB Argument for Receiving 4.2.8 Using the Show_buffer Argument 5 Using Message Recovery Services 5.1 Message Recovery Overview 5.1.1 The MRS Server 5.1.2 Managing Disk Files with MRS 5.1.3 Undeliverable Message Conditions 5.2 Message Recovery Flow 5.3 Coding Programs to Send Recoverable Messages 5.3.1 Determining the Delivery Outcome 5.3.2 Timeouts During Recoverable Delivery 5.4 Delivery Modes 5.4.1 Wait for DQF Preservation 5.4.2 Wait for SAF Preservation 5.4.3 Acknowledgment After DQF Preservation 5.4.4 Acknowledgment After SAF Preservation 5.4.5 After Receiving the MRS Acknowledgment Message 5.5 Retrieving Messages from Journal Files 5.6 Retrieving Messages from the Dead Letter Queue 5.7 Writing Messages to the Postconfirmation Journal File 6 Using Selective Broadcast Services 6.1 Advantages of Selective Broadcast Services (SBS) 6.2 Broadcast Stream 6.2.1 Multipoint Outbound Targets 6.2.2 Private Broadcast Stream 6.2.3 Universal Broadcast Stream 6.3 Stages in SBS Broadcasting 6.3.1 Sending a Registration Message 6.3.2 Submitting a Message 6.3.3 Distributing a Message 6.3.4 Sending a Deregistration Message 6.4 SBS Broadcast Communication Modes 7 Using Symbolic Names 7.1 Naming 7.2 Static Naming 7.3 Dynamic Naming 7.3.1 Name Scope 7.3.2 Dynamic Naming Tools on VMS 7.4 Calls Used for Naming 7.4.1 Locating a Queue 7.5 Dynamic Namespace 7.6 Layout of a DNS Name 7.7 Using Dynamic Names 7.7.1 Creating a Name in DNS 7.7.2 Defining a Name in the Queue Configuration Table 7.7.3 Defining a Name in the Group Name Table 7.7.4 Specifying the Name Scope 7.7.5 Using the Loader Utility to Create Names 7.8 Updating a Dynamic Name Queue Address 8 Using Extended Calls 8.1 Receiving Messages Asynchronously 8.1.1 Using PAMS_GET_MSGA 8.1.2 Using PAMS_CANCEL_GET 8.1.3 AST Limitations 8.2 Using Journaling 8.2.1 Using PAMS_OPEN_JRN 8.2.2 Using PAMS_READ_JRN 8.2.3 Using PAMS_CLOSE_JRN 8.3 Specifying a Compound Selection for Receiving 8.3.1 Using PAMS_SET_SELECT 8.3.2 Using PAMS_CANCEL_SELECT 8.4 Using Timers 8.4.1 Using PAMS_SET_TIMER 8.4.2 Using PAMS_CANCEL_TIMER 8.5 DECmessageQ Monitoring Support 8.5.1 Using PUTIL_SHOW_PENDING 9 Using Message-Based Services 9.1 Request-Response Services 9.1.1 DECmessageQ Queue Lists 9.1.2 DECmessageQ Cross-Group Lists 9.1.3 Temporary Secondary Queue Requests 9.2 Event Subscription Services 9.2.1 Queue Attach and Exit Notification 9.2.2 Cross-Group Connection Notification 9.2.3 Queue Availability Services 10 Using PAMScript 10.1 PAMScript Files 10.1.1 Comments 10.1.2 Message Statements 10.1.3 Timed Delays 10.1.4 Repeat Groups 10.1.5 SET Command 10.1.6 SET LOG Command 10.1.7 SET RECEIVE ECHO or SET RECEIVE LOG Commands 10.2 Sample PAMScript File 10.3 Script Verification Utility 10.4 Enabling PAMScript Processing 11 Writing Portable Code 11.1 General Guidelines for Writing Portable Code 11.2 Guidelines for Writing Portable DECmessageQ Programs 11.3 Using DECmessageQ Include Files 11.4 DECmessageQ Return Status Codes 11.5 Maximum Message Lengths on Platforms 12 DECmessageQ Call Reference PAMS_ATTACH_Q PAMS_CANCEL_GET PAMS_CANCEL_SELECT PAMS_CANCEL_TIMER PAMS_CLOSE_JRN PAMS_CONFIRM_MSG 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 13 DECmessageQ Message Reference 13.1 Message Types by Server Target Queue 13.2 Message Formats and Descriptions ALLOCATED_SQ Response AVAIL Notification AVAIL_DEREG Request AVAIL_REG Request AVAIL_REG_REPLY Response DECLARE_SQ Request DISABLE_NOTIFY Request ENABLE_NOTIFY Request LINK_COMPLETE Notification LINK_LOSS Notification 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_DCLS Request LIST_DCLS Response PROCESS_DCL Notification PROCESS_EXIT Notification LOCATE_Q_REP Response MRS_ACK Response MRS_DEBUG_OFF Request MRS_DEBUG_ON Request MRS_DQF_SET Request MRS_DQF_SET_REP Response MRS_DQF_TRANSFER Request MRS_DQF_TRANSFER_ACK Acknowledgment MRS_DQF_TRANSFER_REP Response MRS_SET_DLJ Request MRS_SET_DLJ_REP Response MRS_SET_PCJ Request MRS_SET_PCJ_REP Response SBS_BS_SEQGAP Notification SBS_DEREG Request SBS_DEREG_BY_ID SBS_DUMP_TABLES Request SBS_PURGE Request SBS_PURGE_ACK Response SBS_REG Request SBS_REG_EZ Request SBS_REG_EZ_REPLY Response SBS_REG_REPLY Response TIMER_EXPIRED Response UNAVAIL Notification UNDECLARE_SQ Release Temporary Secondary Queue Request A Include Files A.1 Generic Type and Class File A.2 Generic Symbols File A.3 Generic Process Numbers File B Code Examples B.1 Client/Server Sample Programs B.1.1 Simple Client/Server in Ada B.1.2 Simple Client/Server in C B.1.3 Simple Client/Server in FORTRAN B.2 Heterogeneous Distributed Demo Application B.2.1 Building the Demo Software B.2.2 Running the Demo Software B.3 Selective Broadcast Sample Programs B.4 Miscellaneous Sample Programs B.5 Example Program Utilizing SBS Services C DECmessageQ for VMS C.1 Building the DECmessageQ Environment C.2 Using the Tools and Utilities C.2.1 Running the TEST Utility C.2.2 Running the MONITOR Utility C.3 Compiling C.4 Using High-Level Languages C.4.1 Ada C.4.2 BASIC C.4.3 BLISS C.4.4 C C.4.5 COBOL C.4.6 FORTRAN C.4.7 MACRO-32 C.4.8 Pascal C.4.9 PL/I C.5 Linking C.5.1 Linking with the Runtime Library C.5.2 Linking with the Object Library C.6 Running Programs C.6.1 Setting the Named Logical Name Table C.6.2 Running a Program as a Detached Process C.6.3 Getting a VMS Traceback C.6.4 DECmessageQ Message Translation C.7 Using VMS Logical Names at Run Time C.7.1 User Callbacks (UCBs) D Obsolete Call Services PAMS_ALLOC_MSG PAMS_DCL_PROCESS PAMS_FREE_MSG PAMS_RCV_MSG PAMS_RCV_MSGW PAMS_SEND_MSG PAMS_SHOW_MSG E DECmessageQ Product Family Cross-Reference Glossary EXAMPLES 2-1 Attaching to the Message Queuing Bus in FORTRAN 2-2 Sending a Nonrecoverable Datagram Message in C 2-3 Receiving a Nonrecoverable Datagram Message in C 2-4 Detaching from the Message Queuing Bus in FORTRAN 2-5 Program Flow for a Simple Client 3-1 Sending a Nonrecoverable Message in C 3-2 Control Flow for Client Modules 3-3 Control Flow for Server Modules 3-4 Control Flow for Server Modules with Compound Message Flow 4-1 Sending a Recoverable Message with Asynchronous Acknowledgement in a C Language Program 4-2 Selection by Queue in a C Language Program 4-3 Receiving and Confirming a Recoverable Message in a C Language Program 6-1 DMQ$INIT.TXT Entries Defining MOT Addresses 7-1 Locating a Queue Using PAMS_LOCATE_Q in Ada 8-1 Calling PAMS_CANCEL_GET in Ada 8-2 Checking the PSB for a PAMS_CANCEL_GET Status in Ada 8-3 Setting a Timer Using PAMS_SET_TIMER in Ada 9-1 Sending a Notification Message in PL/1 10-1 Example PAMScript Using Various Data Phrase Formats 11-1 Recommended #INCLUDE Statements for DECmessageQ Applications 11-2 Portable Code for Testing Return Status 12-1 Selection Record Data Structure in C 13-1 Q_address Structure B-1 Simple Client in Ada B-2 Simple Server in Ada B-3 Simple Client in C B-4 Simple Server in C B-5 Simple Client in FORTRAN B-6 Simple Server in FORTRAN B-7 SBS Registration Example in the C Language C-1 Command Procedure to Run as a Detached Process FIGURES 1-1 DECmessageQ Communication Layer 1-2 Queues on the Message Queuing Bus 1-3 Message Queuing Groups 1-4 Point-to-Point versus Message Queuing Bus Configuration 2-1 DECmessageQ Address 4-1 PAMS Status Block 4-2 Selection Argument Format 4-3 Default Selection Format 4-4 Format of Selection by Source 4-5 Compound Selection Format 4-6 Show_buffer Format 5-1 Disk Files Supporting MRS 6-1 SBS One-to-Many Broadcasting 7-1 Static Naming 7-2 DNS Name Layout 8-1 Typical Program Using ASTs B-1 Simple Client Logic Flow B-2 Simple Server Logic Flow TABLES 2-1 DECmessageQ Basic Calls 2-2 PAMS_ATTACH_Q Arguments 2-3 PAMS_PUT_MSG Arguments 2-4 PAMS_GET_MSG and PAMS_GET_MSGW Arguments 3-1 Queue Attributes 4-1 PAMS Status Block Fields 4-2 Selection Modes for Selection by Message Queue 4-3 Selection Modes for Selection by Message Attribute 4-4 PAMS_CONFIRM_MSG Arguments 4-5 Fields in the Buffer 5-1 Conditions Causing UMA to be Executed 5-2 Completion Codes for PDEL_MODE_WF_DQF 5-3 UMA for PDEL_MODE_WF_SAF 5-4 Completion Codes for PDEL_MODE_WF_SAF 7-1 PAMS_LOCATE_Q Arguments 8-1 Advanced Messaging Calls 8-2 PAMS_GET_MSGA Arguments 8-3 PAMS_CANCEL_GET Argument 8-4 PAMS_OPEN_JRN Arguments 8-5 PAMS_READ_JRN Arguments 8-6 PAMS_CLOSE_JRN Argument 8-7 PAMS_SET_SELECT Arguments 8-8 PAMS_CANCEL_SELECT Argument 8-9 PAMS_SET_TIMER Arguments 8-10 PAMS_CANCEL_TIMER Argument 8-11 PUTIL_SHOW_PENDING Arguments 10-1 PAMScript Facility Commands 10-2 Components of Decimal Binary Data Phrase 10-3 Components of Hexadecimal Binary Data Phrase 10-4 Components of Octal Binary Data Phrase 10-5 Components of Zero-fill Binary Data Phrase 10-6 Components of ASCII Data Phrase 10-7 Components of ASCII Space-Fill Data Phrase 11-1 Include File Cross-Reference 11-2 DECmessageQ Maximum Message Lengths 12-1 Fields in a Selection Record 13-1 Names and Addresses of DECmessageQ Servers 13-2 Target Queue: AVAIL_SERVER 13-3 Target Queue: SBS_SERVER 13-4 Target Queue: CONNECT_SERVER 13-5 Target Queue: QUEUE_SERVER 13-6 Target Queue: MRS_SERVER 13-7 Target Queue: QTRANSFER 13-8 Target Queue: Primary Queue of Requester 13-9 Data Types 13-10 Status Codes for the MRS Acknowledgment Message B-1 Demo Software Files C-1 Default Settings D-1 Obsolete Calls E-1 DECmessageQ Product Family Cross-Reference