CONTENTS Title Page Copyright Page Preface Part I The Message Handling System Concept 1 Introduction 1.1 Message Handling Systems 1.2 Message Router and the Programmer's Kit 1.3 Message Router and Applications 1.4 Using the Message Router Programmer's Kit 1.5 Definition Files 1.6 Message Structure 1.7 Message Protocols 1.8 Message Type 1.8.1 User Message 1.8.2 Service Message 1.8.3 Probe Message 1.8.4 Receipt Notification Message 1.8.5 Non-P2 Message 2 Additional Services Provided with the Programmer's Kit 2.1 The Two Levels of Service 2.2 Upgrading Your Application to Use the V3.1 Level Of Service 2.2.1 User Messages 2.2.2 Complete Messages 2.2.3 Lists 2.2.4 Additional Element Types 2.3 Interworking Between Levels of Service 2.4 Version 3.1 Extended Level of Service 2.4.1 Probe Messages 2.4.2 Receipt Notification Messages 2.4.3 Non-P2 Messages 2.4.3.1 Message Structure 2.4.4 Service Messages 2.4.5 Additional Composite Elements 2.4.5.1 The Message Identifier on the User Envelope 2.4.5.2 Encoded Information Type 2.4.5.3 Converted Information Types 2.4.5.4 Inter and Intra Domain Trace Information 2.4.5.5 Per Domain Bilateral Information 2.4.5.6 Internal Domain Defined Attribute 2.4.5.7 Alternate Recipient Assignment 2.4.5.8 The Message Identifier on the User Message Content 2.4.5.9 Global Domain Identifier 2.4.5.10 Forwarded Interpersonal Message Bodypart 2.4.5.11 Delivery Information 2.4.5.12 Notification of Receipt Information 2.4.5.13 Notification of Non-Receipt Information 3 Preparing to Write an Application 3.1 Basic Concepts 3.1.1 The Interface Routines 3.1.2 The Message Context 3.1.3 The Message State 3.1.4 Message Elements 3.2 Message Templates 3.2.1 Message Structure 3.2.1.1 Complete_messages 3.2.1.2 Message Identifiers 3.2.2 Designing a Message Template 3.3 The State of a Message 3.4 Task Descriptions 3.4.1 Connecting to Message Router 3.4.1.1 Types of Connection 3.4.1.2 Other Connection Considerations 3.4.1.3 Mailbox Considerations 3.4.2 Assembling a Message for Message Router 3.4.3 Posting an Assembled Message to Message Router 3.4.4 Assembling and Posting a Message to Message Router 3.4.5 Fetching a Message from Message Router 3.4.6 Disassembling a Message from Message Router 3.4.7 Fetching and Disassembling a Message from Message Router 3.4.8 Adding an Assembled Message to the One Being Assembled 3.4.9 Adding Vendor-Defined Elements to the Message 3.4.10 Extracting a Message from Within the One Being Disassembled 3.4.11 Disassembling Vendor-Defined Elements 3.4.12 Disassembling an Unknown CLASS or ITEM 3.4.13 Querying a Mailbox 3.4.14 Handling Journaled Messages 4 The Application's Tasks 4.1 General 4.1.1 Tasks for Both User Agents and Gateways 4.1.2 Tasks for a User Agent 4.1.3 Tasks for a Gateway 4.2 Processing Bodyparts 4.2.1 Processing Bodyparts and Assembling a Message 4.2.1.1 TEXT-BODY 4.2.1.2 FORW-BODY 4.2.1.3 RNOTIF-BODY 4.2.1.4 FWDIPMSG-BODY 4.2.1.5 NON_P2-BODY 4.2.1.6 VEND-BODY 4.2.1.7 KNOWN-BODY 4.2.2 Processing Bodyparts and Disassembling a Message 4.2.2.1 TEXT-BODY 4.2.2.2 FORW-BODY 4.2.2.3 FWDIPMSG-BODY 4.2.2.4 RNOTIF 4.2.2.5 NON_P2-BODY 4.2.2.6 VEND-BODY 4.2.2.7 KNOWN-BODY 4.3 Guide to the Sequence of Processing a Message 4.3.1 Assembling and Posting The Example Message 4.3.2 Fetching and Disassembling The Example Message 5 Designing an Application 5.1 Searching for an Element in a Message File 5.2 Points to Consider 5.2.1 Privileges Needed by the User 5.2.2 Restrictions on Files in a Message 5.2.2.1 Text File Format 5.2.2.2 NBS File Format 5.2.2.3 WPL File Format 5.2.2.4 RMS File Format 5.2.3 NBS Data Elements 5.2.3.1 NBStype 5.2.3.2 NBSlength 5.2.3.3 NBSqualifier 5.2.4 Posting Messages Complete 5.2.5 Message Journaling 5.2.6 Handling CTRL/C 5.3 Decision Checklist 5.4 Interworking With ALL-IN-1 IOS 5.4.1 Read Receipts 5.4.2 Delivery Reports 5.4.3 ALL-IN-1 IOS Specific Fields 5.4.4 Addressing 5.4.5 Message Structure 5.4.5.1 Standard MAIL Message 5.4.6 Message With Attached Document 5.4.7 Multiple Bodyparts 6 Compiling and Linking Your Application 6.1 Compiling Your Application 6.1.1 VAX PASCAL 6.1.2 VAX C 6.1.3 VAX MACRO 6.1.4 VAX FORTRAN 6.1.5 VAX BLISS-32 6.2 Linking Your Application 6.2.1 Linking Your Application Where the Programmer's Kit Is Installed 6.2.2 Linking Your Application Where Message Router Is Installed 6.2.3 Privileges Needed by the Application 7 Message Elements 7.1 Elements 7.1.1 Elements on a User Envelope 7.1.2 Elements on a Content 7.1.3 Elements in a Complete_message 7.1.4 Elements in a Service Message 7.1.5 Elements in a Probe Message 7.1.6 Elements on a Receipt Notification 7.2 Interworking Between Versions 7.2.1 Existing Applications 7.2.2 Version 3.0 Applications 7.2.3 Version 2.0 Applications 7.2.4 Version 1.1 Applications Part II Reference Material 8 Type and Class on a Message 8.1 Structure of a Name 8.1.1 Using ROUTE and USERID 8.1.2 Delivering Messages 8.2 Flags 8.2.1 Constructing Flags to Add to the Message 8.2.2 Interpreting Flags when You Disassemble a Message 8.2.3 Bit Definitions in PERRECFLG 8.2.4 Bit Definitions in PERMSGFLG 8.2.5 Bit Definitions in PERLISTFLG 8.2.6 Bit Definitions in ENCODEDINFO and ENCODEDTYPES 8.2.7 Bit Definitions in G3NONBASIC 8.2.8 Bit Definitions in REPORTFLG 8.3 Integers 8.3.1 PRECEDENCE 8.3.2 CONTENTTYPES 8.3.3 HOPCOUNT 8.3.4 EXTENSIONID 8.3.5 EXPLICCONV 8.3.6 AUTOFORWARD 8.3.7 SENSITIVITY 8.3.8 REPLYREQ 8.3.9 REASON 8.3.10 DIAGNOSTIC 8.3.11 TRACE_ACTION 8.3.12 EXTERNAL_NUMBER 8.3.13 A1_FORWARD 8.3.14 TYPEOFUA 8.3.15 CONTLENGTH 8.3.16 RECEIPTTYPE 8.3.17 NRREASON 8.3.18 NRQUAL 8.3.19 REDIRECTREASON 9 The Interface Routines 9.1 Introduction 9.2 MRIF$EXAMPLE 9.3 MRIF$CONFIRM 9.4 MRIF$CONNECT 9.5 MRIF$DISCONNECT 9.6 MRIF$END_ASSEMBLE 9.7 MRIF$END_ASSEMBLE_POST 9.8 MRIF$END_DISASSEMBLE 9.9 MRIF$END_GET 9.10 MRIF$END_NBS_GET 9.11 MRIF$END_NBS_PUT 9.12 MRIF$END_PUT 9.13 MRIF$FETCH 9.14 MRIF$FETCH_START_DISASSEMBLE 9.15 MRIF$FIND 9.16 MRIF$GET_BITSTRING 9.17 MRIF$GET_DATE 9.17.1 Permitted Dates Using the V3.0 Level of Services 9.17.2 Permitted Dates Using the V3.1 Level of Services 9.18 MRIF$GET_FLAGS 9.18.1 Permitted Flags Using the V3.0 Level of Services 9.18.2 Permitted Flags Using the V3.1 Level of Services 9.19 MRIF$GET_INTEGER 9.19.1 Permitted Integers Using the V3.0 Level of Services 9.19.2 Permitted Integers Using the V3.1 Level of Services 9.20 MRIF$GET_NBS_FILE 9.21 MRIF$GET_NBS_RECORD 9.22 MRIF$GET_NON_P2_BUFFER 9.23 MRIF$GET_RMS_FILE 9.24 MRIF$GET_STRING 9.24.1 Permitted Strings Using the V3.0 Level of Services 9.24.2 Permitted Strings Using the V3.1 Level of Services 9.25 MRIF$GET_TEXT_FILE 9.26 MRIF$GET_TEXT_RECORD 9.27 MRIF$GET_WPL_FILE 9.28 MRIF$IDENTIFY 9.29 MRIF$ISPRIM 9.30 MRIF$POST 9.31 MRIF$PUT_BITSTRING 9.32 MRIF$PUT_DATE 9.32.1 Permitted Dates Using the V3.0 Level of Services 9.32.2 Permitted Dates Using the V3.1 Level of Services 9.33 MRIF$PUT_FLAGS 9.33.1 Permitted Flags Using the V3.0 Level of Services 9.33.2 Permitted Flags Using the V3.1 Level of Services 9.34 MRIF$PUT_INTEGER 9.34.1 Permitted Integers Using the V3.0 Level of Services 9.34.2 Permitted Integers Using the V3.1 Level of Services 9.35 MRIF$PUT_NBS_FILE 9.36 MRIF$PUT_NBS_RECORD 9.37 MRIF$PUT_NON_P2_BUFFER 9.38 MRIF$PUT_RMS_FILE 9.39 MRIF$PUT_STRING 9.39.1 Permitted Strings Using the V3.0 Level of Services 9.39.2 Permitted Strings Using the V3.1 Level of Services 9.40 MRIF$PUT_TEXT_FILE 9.41 MRIF$PUT_TEXT_RECORD 9.42 MRIF$PUT_WPL_FILE 9.43 MRIF$QUERY 9.44 MRIF$SELECT_ASSEMBLE 9.45 MRIF$SELECT_DISASSEMBLE 9.46 MRIF$START_ASSEMBLE 9.47 MRIF$START_DISASSEMBLE 9.48 MRIF$START_GET 9.48.1 Class Descriptions for the V3.0 Level of Services 9.48.1.1 Class=BODYPART 9.48.1.2 Class=DOMAINDEF 9.48.1.3 Class=LIST 9.48.1.4 Class=NAME 9.48.1.5 Class=REPORT 9.48.2 Class Descriptions for the V3.1 Level of Services 9.48.2.1 Class=BODYPART 9.48.2.2 Class=CONTENT_ID 9.48.2.3 Class=DELIVERY 9.48.2.4 Class=DOMAINDEF 9.48.2.5 Class=DOMAININFO 9.48.2.6 Class=ENVELOPE_ID 9.48.2.7 Class=ENCODED 9.48.2.8 Class=ITRACE 9.48.2.9 Class=ETRACE 9.48.2.10 Class=NAME 9.48.2.11 Class=GDOMID 9.48.2.12 Class=REPORT 9.48.2.13 Class=REDIRECTION 9.48.2.14 Class=RECEIPT 9.48.2.15 Class=NONRECEIPT 9.49 MRIF$START_NBS_GET 9.50 MRIF$START_NBS_PUT 9.51 MRIF$START_PUT 9.51.1 Class Descriptions for the V3.0 Level of Services 9.51.1.1 Class=BODYPART 9.51.1.2 Class=DOMAINDEF 9.51.1.3 Class=LIST 9.51.1.4 Class=NAME 9.51.2 Class Descriptions for the V3.1 Level of Services 9.51.2.1 Class=BODYPART 9.51.2.2 Class=CONTENT_ID 9.51.2.3 Class=DELIVERY 9.51.2.4 Class=DOMAINDEF 9.51.2.5 Class=DOMAININFO 9.51.2.6 Class=ENVELOPE_ID 9.51.2.7 Class=DOMAININFO 9.51.2.8 Class=ENVELOPE_ID 9.51.2.9 Class=ENCODED 9.51.2.10 Class=ITRACE 9.51.2.11 Class=ETRACE 9.51.2.12 Class=NAME 9.51.2.13 Class=GDOMID 9.51.2.14 Class=REPORT 9.51.2.15 Class=REDIRECTION 9.51.2.16 Class=RECEIPT 9.51.2.17 Class=NONRECEIPT 10 Condition Values 10.1 Interface Routine Condition Values 10.1.1 Success Statuses 10.1.2 Fatal Error Statuses 10.1.3 Non-fatal Error Statuses 10.2 Message Router Errors 10.3 Other Errors 11 The Backus-Naur Definition of a Message 11.1 Notation 11.2 Backus-Naur Format Definition of a Message For the V3.0 Level of Service 11.3 Backus-Naur Format Definition of a Message For the V3.1 Level of Service 12 Message Router NBS Message Dump Utility Glossary ALL-IN-1 IOS . . . Assembly Assembly context . . . Complete Component element . . . convprohib COUNTRY . . . DEFERRED DELIVERY . . . DOMAINDEF Domain-defined attributes . . . ENVELOPE_ID EXPLICCONV . . . FWDIPMSG FWDIPMSG-BODY . . . ia5text IDENTIFIER . . . KNOWN-BODY LAST_INTENDEDRECIP . . . MISCTERMCAPAB MRaddress . . . NRECEIPTINFO NRREASON . . . PERMSGFLG PERRECFLG . . . REASON RECEIPTDATE . . . Reply by REPLYBY . . . SENDER_DEN SENDER_DGN . . . SURNAME TELEPHONE . . . Type TYPEOFUA . . . voice voicenotif . . . X121ADDRESS FIGURES 1-1 The Message Handling System 1-2 The Structure of a User Message 1-3 Message Protocols 3-1 Simple Element 3-2 Composite Element 3-3 Nested Composite Elements 3-4 An Example of How States Are Stacked 3-5 Flowchart Illustrating How to Disassemble Application-defined Elements 4-1 Form of the Example User Message 5-1 Form of Message With Multiple Bodyparts TABLES 1 Conventions 3-1 Parameters for the Routine SELECT_ASSEMBLE 3-2 Return Statuses for the Routine SELECT_DISASSEMBLE 7-1 Elements on a User Message Envelope 7-2 Elements of ENVELOPE_ID 7-3 Elements of GDOMID 7-4 Elements of ENCODED 7-5 Elements of NAME(originator_envelope) on an Envelope 7-6 Elements of NAME(recipient_envelope) on an Envelope 7-7 Elements of DOMAINDEF 7-8 Elements of REDIRECTION 7-9 Components of a LIST on an envelope or content 7-10 Components of ETRACE 7-11 Components of ITRACE 7-12 Components of DOMAININFO 7-13 Elements on a User Message Content Header 7-14 Components of CONTENT_ID 7-15 Components of NAME (originator_content) on a Content Header 7-16 Components of NAME (recipient_content) on a Content Header 7-17 Bodyparts on a User Content 7-18 Elements in FWDIPMSG-BODY 7-19 Elements in DELIVERY 7-20 Elements in a Complete_message 7-21 Elements on the Envelope of a Service Message 7-22 Elements on the Content of a Service Message 7-23 Elements of a REPORT in a Service Message Content 7-24 Elements of a PROBE message 7-25 Elements of NAME(probe) on a Probe Envelope 7-26 Elements in a Receipt Notification Message 7-27 Elements in RECEIPT 7-28 Elements in NONRECEIPT 8-1 Bits Defined in PERRECFLG 8-2 Bits Defined in PERMSGFLG 8-3 Bits Defined in PERLISTFLG 8-4 Bits Defined in ENCODEDINFO and ENCODEDTYPES 8-5 Bits Defined in G3NONBASIC 8-6 Bits Defined in REPORTFLG 8-7 Values of REASON 8-8 Values of DIAGNOSTIC 10-1 Semantic errors