CONTENTS

  Title Page

  Copyright Page

  Preface

  1      Introduction to VOTS Programming

  1.1     An Overview of the VOTS Programming Interface

  1.2     The VOTS Device, Channels and Mailboxes

  1.3     Using $QIO or $QIOW System Service Calls

  1.4     NCBs and Item Lists

  1.5     Issuing an Outbound Connection Request
    1.5.1      The Status of an Outbound Connection Request

  1.6     Receiving an Inbound Connection Request
    1.6.1      Examining an Inbound Connection Request
    1.6.2      Accepting an Inbound Connection Request
    1.6.3      Rejecting an Inbound Connection Request

  1.7     Exchanging Data

  1.8     Canceling I/O on a Channel

  1.9     Disconnecting a Transport Connection
    1.9.1      Receiving a Disconnection
    1.9.2      Results of Disconnection

  1.10    Deassigning a Channel

  1.11    System Service Calls

  2      Programming Guidelines

  2.1     Including Definitions of Symbols
    2.1.1      VOTS-specific Symbols
    2.1.2      Mailbox Message Types

  2.2     Assigning a Channel and Setting up a Mailbox
    2.2.1      What Happens when you Assign a Channel to VOTS
    2.2.2      Assigning a Channel without Creating a Mailbox
    2.2.3      Assigning a Channel and Creating a Mailbox
    2.2.4      Associating One Mailbox with Several Channels
    2.2.5      Reading the Mailbox
    2.2.6      Reading a Mailbox Associated with Several Channels
    2.2.7      Removing an Associated Mailbox
    2.2.8      Mailbox Messages

  2.3     Issuing $QIO and $QIOW Calls to VOTS
    2.3.1      Input/Output Status Block (IOSB)
    2.3.2      Item Lists and NCBs
    2.3.3      Item Lists
      2.3.3.1      Input Item Lists
      2.3.3.2      Output Item Lists
      2.3.3.3      Structure of an Item in an Item List
    2.3.4      NCBs

  2.4     Initiating an Outbound Connection
    2.4.1      $QIO and $QIOW Calls for Connection Requests
    2.4.2      Supplying an Input Item List in a Connection Request
    2.4.3      Supplying an Output Item List Buffer in a Connection Request
    2.4.4      Supplying an NCB in a Connection Request
    2.4.5      Addressing the Remote Host
    2.4.6      Using Logical Names for VOTS-addresses
      2.4.6.1      Adding VOTS Logical Names to OSIT$NAMES
    2.4.7      Access Control Information in Outbound Connection Requests
    2.4.8      TSAPs in Outbound Connection Requests
      2.4.8.1      TSAP Identifiers in Input Item Lists
      2.4.8.2      TSAP Identifiers in NCBs
    2.4.9      Connection Status
      2.4.9.1      Reading the IOSB
      2.4.9.2      Reading the Mailbox
      2.4.9.3      Reading the Output Item List

  2.5     Inbound Connection Requests
    2.5.1      Transport Service Access Points
      2.5.1.1      Creating an Active TSAP Association
      2.5.1.2      A Passive TSAP Association That Becomes Active
      2.5.1.3      Deleting an Active TSAP Association
      2.5.1.4      Passive TSAP Association: Supplying a .COM file
      2.5.1.5      Passive TSAP Association: Access Control Information
    2.5.2      Reading Inbound Connection Requests
    2.5.3      Examining the NCB
    2.5.4      Examining the Connection Request Using $QIO(IO$_SENSEMODE)
      2.5.4.1      Input Item List for $QIO(IO$_SENSEMODE)
      2.5.4.2      Output Item List for $QIO(IO$_SENSEMODE)
    2.5.5      Accepting or Rejecting a Connection Request
      2.5.5.1      Accepting a Connection Request
      2.5.5.2      Rejecting a Connection Request
      2.5.5.3      Using Different Channels for Receiving and Accepting

  2.6     Exchanging Data
    2.6.1      Exchanging Normal Data with No Fragmentation
    2.6.2      Exchanging Expedited Data
    2.6.3      Correct Sequence for Expedited and Normal Data
    2.6.4      Fragmented Data Messages
      2.6.4.1      Fragmented Read Requests
      2.6.4.2      Fragmented Write Requests
    2.6.5      How VOTS Handles Write Requests
    2.6.6      Example Routines for Exchanging Data

  2.7     Canceling Input/Output on a Channel

  2.8     Disconnecting a Transport Connection
    2.8.1      Initiating a Disconnection
    2.8.2      Receiving a Disconnection Request

  2.9     Deassigning the Channel

  3      Calling the System Services

  3.1     Introduction

  3.2     MACRO Coding
    3.2.1      Argument Lists

  3.3     High-Level Language Coding
    3.3.1      Descriptors

  3.4     Return Status Codes
    3.4.1      Format of the Return Status
    3.4.2      Information Provided by Status Codes
    3.4.3      Testing the Status Code

  3.5     Obtaining Values for Other Symbolic Codes

  3.6     Special Return Conditions
    3.6.1      Resource Wait Mode
    3.6.2      System Service Failure Exception Mode

  4      System Service Calls Using Network Control Blocks

  4.1     Introduction

  4.2     Summary of Call Description
    4.2.1      Argument List
    4.2.2      Syntax of Calls

  4.3     Assign a Channel - $ASSIGN

  4.4     Canceling Read and Write Requests on a Channel - $CANCEL

  4.5     Deassign the Channel - $DASSGN

  4.6     Request a Transport Connection - $QIO(W)(IO$_ACCESS)

  4.7     Accept a Request to Set Up a Transport Connection - $QIO(W)(IO$_ACCESS)

  4.8     Reject a Request to Set Up a Transport Connection - $QIO(W)(IO$_ACCESS!IO$M_ABORT)

  4.9     Associate a Task with a TSAP - $QIO(W)(IO$_ACPCONTROL)

  4.10    Ending a Transport Connection - $QIO(W)(IO$_DEACCESS!IO$M_ABORT)

  4.11    Receive Data - $QIO(W)(IO$_READVBLK)

  4.12    Send Normal Data - $QIO(W)(IO$_WRITEVBLK)

  4.13    Send Expedited Data - $QIO(W)(IO$_WRITEVBLK!IO$M_INTERRUPT)

  5      System Service Calls using Item Lists

  5.1     Introduction

  5.2     Kinds of Item List
    5.2.1      Item Types

  5.3     Input Item Lists
    5.3.1      Description of Input Items
      5.3.1.1      Address (item type: OSIT$K_ITEM_ADDRESS)
      5.3.1.2      Called TSAP (item type: OSIT$K_ITEM_CALLED_TSAP)
      5.3.1.3      Calling TSAP (item type: OSIT$K_ITEM_CALLING_TSAP)
      5.3.1.4      Checksums (item type: OSIT$K_ITEM_CHECKSUM)
      5.3.1.5      Class (item type: OSIT$K_ITEM_CLASS)
      5.3.1.6      Expedited data (item type: OSIT$K_ITEM_EXPEDITED)
      5.3.1.7      Null (item type: OSIT$K_ITEM_NULL)
      5.3.1.8      Options (item type: OSIT$K_ITEM_OPTIONS)
      5.3.1.9      Protocol Type (item type: OSIT$K_ITEM_PROTOCOL_TYPE)
      5.3.1.10     Access Control (item type: OSIT$K_ITEM_SECURITY)
      5.3.1.11     TC Identifier (item type: OSIT$K_ITEM_TC_ID)
      5.3.1.12     Optional User Data (item type: OSIT$K_ITEM_USER_DATA)
      5.3.1.13     Example

  5.4     Output Item Lists
    5.4.1      Description of Output Items

  5.5     Request a Transport Connection - $QIO(W)(IO$_ACCESS)

  5.6     Accept a Request to Set Up a Transport Connection - $QIO(W)(IO$_ACCESS)

  5.7     Reject a Request to Set Up a Transport Connection - $QIO(W)(IO$_ACCESS!IO$M_ABORT)

  5.8     Examine Request to Set Up a Transport Connection - $QIO(W)(IO$_SENSEMODE!IO$M_ACCESS)

  6      Negotiating Protocol Classes and Options

  6.1     Options Within the Transport Protocol Standard

  6.2     Transport Protocol Version Number

  6.3     Transport Protocol Class
    6.3.1      Class Negotiation in Outbound Connection Requests
      6.3.1.1      Transport User Specifies Protocol Class
      6.3.1.2      Transport User Does Not Specify Protocol Class
    6.3.2      Class Negotiation in Inbound Connection Requests
    6.3.3      Special Restrictions Applying to Class 0 Connections

  6.4     Checksums, Expedited Data and TPDU format
    6.4.1      Specifying Checksums and Expedited Data
    6.4.2      TPDU Format
    6.4.3      Negotiating Protocol Options

  6.5     Maximum TPDU Size
    6.5.1      Outbound Connection Requests
    6.5.2      Inbound Connection Requests

  7      General Differences between VOTS and DECnet-VAX

  7.1     Device Name

  7.2     NCB Format
    7.2.1      NCB Format for Outbound Connection Requests
    7.2.2      NCB Format for Inbound Connection Request

  7.3     User Data
    7.3.1      User Data in Outbound Connection Requests
    7.3.2      User Data in Connection Response
    7.3.3      User Data in Disconnection Request

  7.4     Access Control Information

  7.5     Identifying Tasks
    7.5.1      Identifying a Task in an NCB

  7.6     Destination Address

  7.7     Using the $QIO(IO$_DEACCESS) call

  7.8     Zero-length TSDU

  7.9     Logical Names

  7.10    Source Node Identifier

  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     VOTS-Specific Reason Codes

  B   Mailbox Message Types

  C   Structure of IOSBs

  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   Example Programs

  E.1     Example Program
    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 VOTS
    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

  FIGURES

  2-1        Structure of an Item

  2-2        Handling Inbound Connection Requests

  2-3        Expedited and Normal Data

  3-1        Format of a Descriptor

  5-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

  1-1        Summary of System Service Calls in MACRO Format

  2-1        Item Types used in a Connection Request

  5-1        Item Types and Sizes

  5-2        Use of Input Items in $QIO(W) calls

  6-1        Option Negotiation

  A-1        Status Codes for $QIO System Services

  A-2        OSI Reason Codes

  A-3        VOTS-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