CONTENTS Title Page Copyright Page Preface Part I DECnet Programming 1 Introduction to $IPC 1.1 Connection and Data Transfer Functions 1.2 General $IPC Services 2 Using the OpenVMS $IPC System Service 2.1 Introduction 2.2 The Application Database 2.3 Passing and Receiving Information from the $IPC System Service 2.3.1 Using the Interprocess Communication Block (IPCB) 2.3.2 Using Network Item Lists 2.4 $IPC Function Codes for Communication 2.5 Source and Target $IPC Operations 2.6 Opening an Association 2.7 Enabling Event Notification 2.8 Initiating a Connection 2.8.1 Identifying the Target Task 2.8.2 Disabling Outgoing Proxy 2.8.3 Automatically Disconnecting the Connection 2.8.4 Specifying Optional Access Verification Information 2.8.5 Requesting Source and Target Address Information 2.8.6 Passing a User-Specified Longword to the Session Control Layer 2.8.7 Sending Optional User Data 2.9 Completing the Connection 2.9.1 Accepting a Connection 2.9.2 Rejecting a Connection 2.9.3 Requesting Node Names 2.10 Exchanging Messages 2.10.1 Sending Data 2.10.2 Receiving Data 2.11 Terminating a Connection 2.11.1 Synchronously Disconnecting a Connection 2.11.2 Aborting a Connection 2.12 Terminating an Association 2.12.1 Stopping Connections to the Task's Association 2.12.2 Closing an Association 2.12.3 Programming Examples 2.13 Managing Information 2.13.1 Obtaining Local Protocol and Address Information 2.13.2 Maintaining the DNA$Towers Attribute 2.13.3 Obtaining Protocol Tower Information 2.13.4 Obtaining Node Name Information 2.13.5 Obtaining Connection Information 2.13.6 Verifying Node Name Information 2.13.7 Protocol Tower Fields 2.13.8 Protocol Tower Set Fields 2.14 $IPC Function Codes to Manage Information 2.15 Receiving Status and Error Reporting 3 $IPC Reference Calls 3.1 Arguments 3.2 IPCB Fields 3.3 Network Item List Fields 3.4 Function Codes 3.4.1 IPC$K_FC_ABORT_CONNECTION 3.4.2 IPC$K_FC_BACKTRANSLATE 3.4.3 IPC$K_FC_CLOSE_ASSOCIATION 3.4.4 IPC$K_FC_CONNECT_ACCEPT 3.4.5 IPC$K_FC_CONNECT_INITIATE 3.4.6 IPC$K_FC_CONNECT_REJECT 3.4.7 IPC$K_FC_DEREGISTER_OBJECT 3.4.8 IPC$K_FC_DISCONNECT_CONNECTION 3.4.9 IPC$K_FC_ENUMERATE_LOCAL_TOWERS 3.4.10 IPC$K_FC_GET_CONNECTION 3.4.11 IPC$K_FC_GET_PORT_INFORMATION 3.4.12 IPC$K_FC_OPEN_ASSOCIATION 3.4.13 IPC$K_FC_RECEIVE 3.4.14 IPC$K_FC_RECEIVE_EVENT 3.4.15 IPC$K_FC_REGISTER_OBJECT 3.4.16 IPC$K_FC_RESOLVE_NAME 3.4.17 IPC$K_FC_SHUT_ASSOCIATION 3.4.18 IPC$K_FC_TRANSMIT 3.4.19 IPC$K_FC_VERIFY_NODENAME 3.5 Item Codes 4 Queue I/O Request ($QIO) System Service 4.1 Establishing Communication with a Remote Node 4.2 Accessing Files on Remote Nodes 4.2.1 Using DCL Commands and Command Procedures 4.2.2 Using Higher-Level Language Programs 4.2.3 Using RMS Services from MACRO Programs 4.3 Performing Task-to-Task Operations 4.3.1 Transparent and Nontransparent Task-to-Task Communication 4.3.1.1 Transparent Communication 4.3.1.2 Nontransparent Communication 4.3.2 Task Specification Strings in Task-to-Task Applications 4.3.3 Functions Required for Performing Task-to-Task Operations 4.3.3.1 Initiating a Logical Link Connection 4.3.3.2 Completing the Logical Link Connection 4.3.3.3 Exchanging Messages 4.3.3.4 Terminating a Logical Link Connection 4.4 Performing Transparent Task-to-Task Operations 4.4.1 Using DCL Commands and Command Procedures 4.4.2 Using Higher-Level Language Programs 4.4.3 Using RMS Service Calls in MACRO Programs 4.4.4 Using System Service Calls in MACRO Programs 4.4.4.1 Requesting a Logical Link 4.4.4.2 Completing the Logical Link Connection 4.4.4.3 Exchanging Messages 4.4.4.4 Terminating the Logical Link 4.4.4.5 Status and Error Reporting 4.4.5 Summary of System Service Calls for Transparent Operations 4.4.5.1 $ASSIGN 4.4.5.2 $QIO (Sending a Message to a Target Task) 4.4.5.3 $QIO (Receiving a Message from a Target Task) 4.4.5.4 $DASSGN (Disconnecting a Logical Link) 4.5 Performing Nontransparent Task-to-Task Operations 4.5.1 Using System Services for Nontransparent Operations 4.5.1.1 Assigning a Channel to _NET: and Creating a Mailbox 4.5.1.2 Mailbox Message Format 4.5.1.3 Requesting a Logical Link Connection 4.5.1.4 Using the Network Connect Block 4.5.1.5 Completing the Establishment of a Logical Link 4.5.1.6 Disconnecting or Aborting the Logical Link 4.5.1.7 Terminating the Logical Link 4.5.2 System Service Calls for Nontransparent Operations 4.5.2.1 $ASSIGN (I/O Channel Assignment) 4.5.2.2 $QIO (Requesting a Logical Link Connection) 4.5.2.3 $QIO (Accepting Logical Link Connection Request) 4.5.2.4 $QIO (Rejecting a Logical Link Connection Request) 4.5.2.5 $QIO (Sending a Message to a Target Task) 4.5.2.6 $QIO (Receiving a Message from a Target Task) 4.5.2.7 $QIO (Sending an Interrupt Message to a Target Task) 4.5.2.8 $QIO (Synchronously Disconnecting a Logical Link) 4.5.2.9 $QIO (Aborting a Logical Link) 4.5.2.10 $QIO (Declaring a Network Name or Object Number) 4.5.2.11 $DASSGN (Terminating a Logical Link) 4.6 Designing Tasks 4.6.1 DCL Command Procedure for Task-to-Task Communication 4.6.2 FORTRAN Program for Task-to-Task Communication Part II OSI Transport Programming 5 Introduction to OSI Transport Programming 5.1 An Overview of the OSI Transport Programming Interface 5.2 The OpenVMS OSI Transport Service Device, Channels and Mailboxes 5.3 Using $QIO or $QIOW System Service Calls 5.4 NCBs and Item Lists 5.5 Issuing an Outbound Connection Request 5.5.1 The Status of an Outbound Connection Request 5.6 Receiving an Inbound Connection Request 5.6.1 Examining an Inbound Connection Request 5.6.2 Accepting an Inbound Connection Request 5.6.3 Rejecting an Inbound Connection Request 5.7 Exchanging Data 5.8 Canceling I/O on a Channel 5.9 Disconnecting a Transport Service Connection 5.9.1 Receiving a Disconnection 5.9.2 Results of Disconnection 5.10 Deassigning a Channel 5.11 System Service Calls 6 Programming Guidelines 6.1 Including Definitions of Transport Service Symbols 6.1.1 OpenVMS OSI Transport Service-specific Symbols 6.1.2 Mailbox Message Types 6.1.3 Mailbox Messages 6.2 Assigning a Channel and Setting Up a Mailbox 6.2.1 What Happens When You Assign a Channel to OpenVMS OSI Transport Service 6.2.2 Assigning a Channel without Creating a Mailbox 6.2.3 Assigning a Channel and Creating a Mailbox 6.2.4 Associating One Mailbox with Several Channels 6.2.5 Reading the Mailbox 6.2.6 Reading a Mailbox Associated with Several Channels 6.2.7 Removing an Associated Mailbox 6.3 Issuing $QIO and $QIOW Calls to OpenVMS OSI Transport Service 6.3.1 Input/Output Status Block (IOSB) 6.3.2 Item Lists and NCBs 6.3.3 Item Lists 6.3.3.1 Input Item Lists 6.3.3.2 Output Item Lists 6.3.3.3 Structure of an Item in an Item List 6.3.4 NCBs 6.4 Initiating an Outbound Connection 6.4.1 $QIO and $QIOW Calls for Connection Requests 6.4.2 Supplying an Input Item List in a Connection Request 6.4.3 Supplying an Output Item List Buffer in a Connection Request 6.4.4 Supplying an NCB in a Connection Request 6.4.5 Addressing the Remote Host 6.4.5.1 Changes in DECnet and OSI Programming Interface 6.4.5.2 Changes in OSI Programming Interface 6.4.6 Using Logical Names for OpenVMS OSI Transport Service-Addresses 6.4.6.1 Adding OpenVMS OSI Transport Service Logical Names to VMS OSIT$NAMES 6.4.7 Access Control Information in Outbound Connection Requests 6.4.8 TSAPs in Outbound Connection Requests 6.4.8.1 TSAP Identifiers in Input Item Lists 6.4.8.2 TSAP Identifiers in NCBs 6.4.9 Send Implementation ID in Item Lists 6.4.10 Connection Status 6.4.10.1 Reading the IOSB 6.4.10.2 Reading the Mailbox 6.4.10.3 Reading the Output Item List 6.5 Inbound Connection Requests 6.5.1 Transport Service Access Points 6.5.1.1 Creating an Active TSAP Association 6.5.1.2 A Passive TSAP Association that Becomes Active 6.5.1.3 Deleting an Active TSAP Association 6.5.1.4 Passive TSAP Association: Supplying a .COM File 6.5.1.5 Passive TSAP Association: Access Control Information 6.5.2 Reading Inbound Connection Requests 6.5.3 Examining the NCB 6.5.4 Examining the Connection Request Using $QIO(IO$_SENSEMODE) 6.5.4.1 Input Item List for $QIO(IO$_SENSEMODE) 6.5.4.2 Output Item List for $QIO(IO$_SENSEMODE) 6.5.5 Accepting or Rejecting a Connection Request 6.5.5.1 Accepting a Connection Request 6.5.5.2 Rejecting a Connection Request 6.5.5.3 Using Different Channels for Receiving and Accepting 6.6 Exchanging Data 6.6.1 Exchanging Normal Data with No Fragmentation 6.6.2 Exchanging Expedited Data 6.6.3 Correct Sequence for Expedited and Normal Data 6.6.4 Fragmented Data Messages 6.6.4.1 Fragmented Read Requests 6.6.4.2 Fragmented Write Requests 6.6.5 How OpenVMS OSI Transport Service Handles Write Requests 6.6.6 Example Routines for Exchanging Data 6.7 Canceling Input/Output on a Channel 6.8 Disconnecting a Transport Connection 6.8.1 Initiating a Disconnection 6.8.2 Receiving a Disconnection Request 6.9 Deassigning the Channel 7 Calling the System Services 7.1 MACRO Coding 7.1.1 Argument Lists 7.2 High-Level Language Coding 7.2.1 Descriptors 7.3 Return Status Codes 7.3.1 Format of the Return Status 7.3.2 Information Provided by Status Codes 7.3.3 Testing the Status Code 7.4 Obtaining Values for Other Symbolic Codes 7.5 Special Return Conditions 7.5.1 Resource Wait Mode 7.5.2 System Service Failure Exception Mode 8 System Service Calls Using Network Control Blocks 8.1 Summary of Call Description 8.1.1 Argument List 8.1.2 Syntax of Calls 8.2 Assign a Channel 8.3 Canceling Read and Write Requests on a Channel 8.4 Deassign the Channel 8.5 Request a Transport Service Connection 8.6 Accept a Request to Set Up a Transport Service Connection 8.7 Reject a Request to Set Up a Transport Service Connection 8.8 Associate a Task with a TSAP 8.9 Receive Data 8.10 Synchronously Disconnecting a Transport Service Connection 8.11 Send Normal Data 8.12 Send Expedited Data 9 System Service Calls Using Item Lists 9.1 Kinds of Item Lists 9.1.1 Item Types 9.2 Input Item Lists 9.2.1 Description of Input Items 9.2.1.1 Address (item type: VMS OSIT$K_ITEM_ADDRESS) 9.2.1.2 Destination NSAP (item type: VMS OSIT$K_ITEM_DESTINATION_NSAP) 9.2.1.3 Called TSAP (item type: VMS OSIT$K_ITEM_CALLED_TSAP) 9.2.1.4 Calling TSAP (item type: VMS OSIT$K_ITEM_CALLING_TSAP) 9.2.1.5 Class (item type: VMS OSIT$K_ITEM_CLASS) 9.2.1.6 Expedited Data (item type: VMS OSIT$K_ITEM_EXPEDITED) 9.2.1.7 Null (item type: VMS OSIT$K_ITEM_NULL) 9.2.1.8 Options (item type: VMS OSIT$K_ITEM_OPTIONS) 9.2.1.9 Protocol Type (item type: VMS OSIT$K_ITEM_PROTOCOL_TYPE) 9.2.1.10 Access Control (item type: VMS OSIT$K_ITEM_SECURITY) 9.2.1.11 TC Identifier (item type: VMS OSIT$K_ITEM_TC_ID) 9.2.1.12 Optional User Data (item type: VMS OSIT$K_ITEM_USER_DATA) 9.2.1.13 Network Service (item type: VMS OSIT$K_ITEM_NETWORK_SERVICE) 9.2.1.14 Example 9.3 Output Item Lists 9.3.1 Description of Output Items 9.4 Request a Transport Connection 9.5 Accept a Request to Set Up a Transport Connection 9.6 Reject a Request to Set Up a Transport Connection 9.7 Examine Request to Set Up a Transport Connection 10 Negotiating Protocol Classes and Options 10.1 Options Within the Transport Service Protocol Standard 10.2 Transport Service Protocol Version Number 10.3 Transport Protocol Class 10.3.1 Class Negotiation in Outbound Connection Requests 10.3.1.1 OpenVMS OSI Transport Service User Specifies Protocol Class 10.3.1.2 OpenVMS OSI Transport Service User Does Not Specify Protocol Class 10.3.2 Class Negotiation in Inbound Connection Requests 10.3.3 Special Restrictions Applying to Class 0 Connections 10.4 Checksums, Expedited Data, TPDU Format and Send Implementation 10.4.1 Specifying Checksums, Expedited Data, Extended Format and Send Implementation 10.4.2 Negotiating Protocol Options 10.5 Maximum TPDU Size 10.5.1 Outbound Connection Requests 10.5.2 Inbound Connection Requests 11 How OpenVMS OSI Transport Service Differs from DECnet/OSI for OpenVMS 11.1 Device Name 11.2 NCB Format 11.2.1 NCB Format for Outbound Connection Requests 11.2.2 NCB Format for Inbound Connection Requests 11.3 User Data 11.3.1 User Data in Outbound Connection Requests 11.3.2 User Data in Connection Response 11.3.3 User Data in Disconnection Request 11.4 Access Control Information 11.5 Identifying Tasks 11.5.1 Identifying a Task in a NCB 11.6 Destination Address 11.7 Zero-Length TSDU 11.8 Logical Names 11.9 Source Node Identifier 11.10 Template Support for DNA Session Part III CMISE API 12 CMISE Introduction 12.1 Data Structures 12.2 Detailed Parameters 12.2.1 Access Control 12.2.2 Action Info 12.2.3 Action Reply Info 12.2.4 Action Type 12.2.5 AE Invocation Identifier 12.2.6 AE Qualifier 12.2.7 AP Invocation Identifier 12.2.8 Application Context Name 12.2.9 AP Title 12.2.10 Association User data 12.2.11 Attribute Identifier List 12.2.12 Attribute List 12.2.13 CMISE Error Code 12.2.14 Connection Id 12.2.15 Context Identifier List 12.2.16 Event Code 12.2.17 Event Info 12.2.18 Event Reply Info 12.2.19 Event Type 12.2.20 Filter 12.2.21 Flags 12.2.22 Functional Units 12.2.23 Invoke Identifier 12.2.24 Linked Identifier 12.2.25 Network Service Access Point (NSAP) 12.2.26 NSAP Type 12.2.27 Object Class 12.2.28 Object Instance 12.2.29 Presentation Context Definition List 12.2.30 Presentation Selector (PSEL) 12.2.31 Problem Number 12.2.32 Problem Type 12.2.33 Protocol Version 12.2.34 Reference Object Instance 12.2.35 Refuse Reason 12.2.36 Release Urgency 12.2.37 Scope 12.2.38 Service Data 12.2.39 Session Connection Identifier 12.2.40 Session Selector (SSEL) 12.2.41 Source Reason 12.2.42 Template 12.2.43 Time 12.2.44 Transport Selector (TSEL) 12.3 Using the CMISE API 13 Common Management Information Services 13.1 M_INITIALIZE Service 13.1.1 M_INITIALIZE Request 13.1.2 Positive Response 13.1.3 M_INITIALIZE Negative Response 13.1.4 M_INITIALIZE Indication 13.1.5 M_INITIALIZE Positive Confirm 13.1.6 M_INITIALIZE Negative Confirm 13.2 M_TERMINATE Service 13.2.1 M_TERMINATE Request 13.2.2 M_TERMINATE Positive Response 13.2.3 M_TERMINATE Negative Response 13.2.4 M_TERMINATE Indication 13.2.5 M_TERMINATE Positive Confirm 13.2.6 M_TERMINATE Negative Confirm 13.3 M_U_ABORT Service 13.3.1 M_U_ABORT Request 13.3.2 M_ABORT Indication 13.3.3 M_P_ABORT Indication 13.4 M_EVENT_REPORT Service 13.4.1 M_EVENT_REPORT Request 13.4.2 M_EVENT_REPORT Indication 13.4.3 M_EVENT_REPORT Response 13.4.4 M_EVENT_REPORT Confirm 13.5 M_GET Service 13.5.1 M_GET Request 13.5.2 M_GET Indication 13.5.3 M_GET Response 13.5.4 M_GET Confirm 13.6 M_CANCEL_GET Service 13.6.1 M_CANCEL_GET Request 13.6.2 M_CANCEL_GET Indication 13.6.3 M_CANCEL_GET Response 13.6.4 M_CANCEL_GET Confirm 13.7 M_SET Service 13.7.1 M_SET Request 13.7.2 M_SET Indication 13.7.3 M_SET Response 13.7.4 M_SET Confirm 13.8 M_ACTION Service 13.8.1 M_ACTION Request 13.8.2 M_ACTION Indication 13.8.3 M_ACTION Response 13.8.4 M_ACTION Confirm 13.9 M_CREATE Service 13.9.1 M_CREATE Request 13.9.2 M_CREATE Indication 13.9.3 M_CREATE Response 13.9.4 M_CREATE Confirm 13.10 M_DELETE Service 13.10.1 M_DELETE Request 13.10.2 M_DELETE Indication 13.10.3 M_DELETE Response 13.10.4 M_DELETE Confirm 13.11 M_ERROR Service 13.11.1 M_ERROR Response 13.11.2 M_ERROR Confirm 13.11.3 CMISE_Error_Code Parameter Usage 13.12 M_REJECT Service 13.12.1 M_REJECT Response 13.12.2 M_REJECT Confirm 13.13 CMISE Support Services 13.13.1 cmise_wait_for_event 13.13.2 cmise_what_event 14 Checking CMISE Status Codes 14.1 Status Codes 14.1.1 OSAK Status Codes 14.2 CMIP Status Codes Part IV Appendixes A $QIO(W) Status Codes and OSI Reason Codes A.1 Status Codes Returned by $QIO(W) Calls A.2 OSI Reason Codes A.3 OSI Transport-Specific Reason Codes B Mailbox Message Types C Structure of an IOSB C.1 IOSB for Successful $QIO(W) Calls C.1.1 Successful $QIO(W) Call with Item List C.1.2 Successful $QIO(W) Call with No Item List C.1.3 Successful $QIO(W) Read and Write Calls C.2 IOSB for Unsuccessful $QIO(W) Calls C.2.1 Unsuccessful $QIO(W) Call with Input Item List Error C.2.2 Unsuccessful Read or Write $QIO(W) Call C.2.3 All Other Unsuccessful $QIO(W) Calls D LIB$PARSE_NCB E Programming Examples E.1 Example Program in the C Language E.1.1 Introduction and Data Structures E.1.2 Translation of SYS$NET E.1.3 Routine Called for Initiator E.1.4 Routine Called for Responder E.1.5 AST Routine to Check Status of Outbound Connection Request E.1.6 Initiate Outbound Connection Request E.1.7 Assign a Channel to OSI Transport E.1.8 Create Mailbox and Post a Read E.1.9 Deassign a Channel E.1.10 Check Status of Disconnection E.1.11 Disconnect Current Transport Connection E.1.12 Free Write Buffer When Write Request Completes E.1.13 Send Data on the Transport Connection E.1.14 Disconnect After Read Is Complete E.1.15 Read Data E.1.16 Check Acceptance of Inbound Connection E.1.17 Accept an Inbound Connection E.1.18 Build Input Item List E.1.19 Analyze NCB and Build Input Item List E.1.20 Build Input Item List for a Connection Request E.1.21 Display Output Item List E.1.22 Displays a Specified Item E.1.23 Report $QIO Error E.1.24 Read Mailbox E.1.25 Report Mailbox Message Type E.1.26 Wait for Mailbox Message and Read Mailbox EXAMPLES 4-1 Network Connect Block Format 4-2 FORTRAN Task-to-Task Communication FIGURES 2-1 Network Item List 2-2 Source and Target Communicating Using the $IPC System Service 2-3 Protocol Tower Set Example 2-4 Protocol Tower Data Structure 2-5 Protocol Tower Set 3-1 Network Item List 4-1 Mailbox Messages 4-2 Mailbox Message Format 6-1 Structure of an Item 6-2 Handling Inbound Connection Requests 6-3 Expedited and Normal Data 7-1 Format of a Descriptor 9-1 Example of an Input Item List B-1 Format of a Mailbox Message C-1 IOSB for Successful $QIO(W) Call with Item List C-2 IOSB for Successful $QIO(W) Call with No Item List C-3 IOSB for Successful Read and Write $QIO(W) Calls C-4 IOSB for $QIO(W) Call with Input Item List Error C-5 IOSB with SS$LINKABORT for Unsuccessful Read/Write $QIO(W) Calls C-6 IOSB for Unsuccessful $QIO(W) Call TABLES 2-1 $IPC System Service Function Codes for Communication 2-2 The $IPC System Service Function Codes to Manage Information 3-1 ABORT_CONNECTION 3-2 BACKTRANSLATE_ADDRESS 3-3 CLOSE_ASSOCIATION 3-4 CONNECT_ACCEPT 3-5 CONNECT_INITIATE 3-6 CONNECT_REJECT 3-7 DEREGISTER_OBJECT 3-8 DISCONNECT_CONNECTION 3-9 ENUMERATE_LOCAL_TOWERS 3-10 GET_CONNECTION 3-11 GET_PORT_INFORMATION 3-12 OPEN_ASSOCIATION 3-13 RECEIVE 3-14 RECEIVE_EVENT 3-15 REGISTER_OBJECT 3-16 RESOLVE_NAME 3-17 SHUT_ASSOCIATION 3-18 TRANSMIT 3-19 VERIFY_NODENAME 4-1 System Service Calls for Transparent Communication 4-2 System Service Calls for Nontransparent Communication 4-3 System Mailbox Messages 5-1 Summary of System Service Calls in MACRO Format 6-1 Item Types Used in a Connection Request 9-1 Item Types and Sizes 9-2 Use of Input Items in $QIO(W) calls 10-1 Option Negotiation A-1 Status Codes for $QIO System Services A-2 OSI Reason Codes A-3 OSI Transport-Specific Reason Codes Returned in the IOSB B-1 Mailbox Message Summary B-2 Contents of the INFO Field in a Mailbox Message C-1 Guide to IOSB Structure for $QIO Calls E-1 Example Programs