Google
 

Trailing-Edge - PDP-10 Archives - QT020_T20_4.1_6.1_SWSKIT_851021 - swskit-documentation/sca-info.memos
There are 2 other files named sca-info.memos in the archive. Click here to see a list.
This file contains descriptions of the Systems Communications Architecture
protocol used to communicate over the CI hardware bus.


THIS FILE CONTAINS:

   o	The Corporate SCA Specification (SCA-CORP-SPEC.MEM)
   o	The LSG SCA Functional Specification (SCA.FUNCTIONAL-SPECIFICATION)
   o	SCA Design Specification for TOPS-20 (SCA-DESIGN.SPECIFICATION)
   o	SCA Design Notes (SCA-DESIGN-NOTES.TXT)
   o	More Design Notes (NEW-SCA-DESIGN-NOTES.TXT)
   o	Description of the SCS JSYS (SCS-JSYS.MEM)
   o	SCA Table Descriptions (SCA-TABLES.TXT)
   o	SCA Tester Description (SCSTST.MEM)

-------------------
   SYSTEMS COMMUNICATIONS ARCHITECTURE - DEC COMPANY CONFIDENTIAL  Page 1



   File:   SCA.MEM

   Date:    29-March-1983

   Author: William Strecker


   Abstract:

   This document describes a  communications  architecture  for  building
   clusters   of   computer   systems.   Included  are  message  formats,
   protocols, and implementation independent interface models.


   Revision:       Description     Author          Date

      0            Outline         Strecker        08-Dec-80

      1            Definitions     Strecker        09-Jan-81
                   in PASCAL

      2            Public Review   Strecker        09-Feb-81

      3            Path Blocks,    H. Levy         10-Dec-81
                   Disconnect, 
                   and Updates

      4            Disconnect      H. Levy         20-Jul-82
                   Changes

      5            Updates         Darrell Duffy    5-Oct-82

      6            Minor Updates   Darrell Duffy   29-Mar-83
   SYSTEMS COMMUNICATIONS ARCHITECTURE - DEC COMPANY CONFIDENTIAL  Page 2


   CHAPTER 1       INTRODUCTION


   CHAPTER 2       SCA TOPOLOGICAL NOTATION

           2.1     NETWORK  . . . . . . . . . . . . . . . . . . . . . 2-1
           2.2     SCA CLUSTER  . . . . . . . . . . . . . . . . . . . 2-1
           2.3     COMMMUNICATIONS SERVICE  . . . . . . . . . . . . . 2-1
           2.4     SYSTEM ADDRESS . . . . . . . . . . . . . . . . . . 2-1
           2.5     PORT . . . . . . . . . . . . . . . . . . . . . . . 2-1
           2.6     PORT DRIVER  . . . . . . . . . . . . . . . . . . . 2-2
           2.7     INTERCONNECT . . . . . . . . . . . . . . . . . . . 2-2
           2.8     POINT-TO-POINT INTERCONNECT  . . . . . . . . . . . 2-2
           2.9     MULTIACCESS INTERCONNECT . . . . . . . . . . . . . 2-2
           2.10    PORT ADDRESS . . . . . . . . . . . . . . . . . . . 2-2


   CHAPTER 3       SCA TOPOLOGY


   CHAPTER 4       SCA LAYERING


   CHAPTER 5       SYSAP-SCS INTERFACE NOTATION

           5.1     PROCESS  . . . . . . . . . . . . . . . . . . . . . 5-1
           5.2     PROCESS NAME . . . . . . . . . . . . . . . . . . . 5-1
           5.3     DIRECTORY  . . . . . . . . . . . . . . . . . . . . 5-1
           5.4     SYSTEM LIST  . . . . . . . . . . . . . . . . . . . 5-1
           5.5     SYSTEM BLOCK . . . . . . . . . . . . . . . . . . . 5-1
           5.6     PATH BLOCK . . . . . . . . . . . . . . . . . . . . 5-1
           5.7     CONNECTION . . . . . . . . . . . . . . . . . . . . 5-2
           5.8     CONNECTION BLOCK . . . . . . . . . . . . . . . . . 5-2
           5.9     CONNECT ID . . . . . . . . . . . . . . . . . . . . 5-2
           5.10    DATAGRAM COMMUNICATION SERVICE . . . . . . . . . . 5-2
           5.11    DATAGRAM BUFFER  . . . . . . . . . . . . . . . . . 5-2
           5.12    SEQUENTIAL MESSAGE COMMUNICATIONS SERVICE  . . . . 5-2
           5.13    MESSAGE BUFFER . . . . . . . . . . . . . . . . . . 5-3
           5.14    QUEUED BUFFER  . . . . . . . . . . . . . . . . . . 5-3
           5.15    BLOCK DATA COMMUNICATIONS SERVICE  . . . . . . . . 5-3
           5.16    NAMED BUFFER . . . . . . . . . . . . . . . . . . . 5-3
           5.17    FLOW CONTROL . . . . . . . . . . . . . . . . . . . 5-3
           5.18    CREDIT . . . . . . . . . . . . . . . . . . . . . . 5-3


   CHAPTER 6       SYSAP-SCS INTERFACE

           6.1     TYPE DEFINITIONS . . . . . . . . . . . . . . . . . 6-2
           6.2     CONFIGURATION SERVICES . . . . . . . . . . . . . . 6-5
           6.2.1     System Configuration . . . . . . . . . . . . . . 6-5
           6.2.2     Path Configuration . . . . . . . . . . . . . . . 6-6
           6.3     CONNECTION MANAGEMENT SERVICE  . . . . . . . . . . 6-8
           6.3.1     Connect  . . . . . . . . . . . . . . . . . . . . 6-9
           6.3.2     Listen . . . . . . . . . . . . . . . . . . . .  6-10
           6.3.3     Accept . . . . . . . . . . . . . . . . . . . .  6-11
   SYSTEMS COMMUNICATIONS ARCHITECTURE - DEC COMPANY CONFIDENTIAL  Page 3


           6.3.4     Reject . . . . . . . . . . . . . . . . . . . .  6-11
           6.3.5     Disconnect . . . . . . . . . . . . . . . . . .  6-12
           6.3.6     Connect State Poll . . . . . . . . . . . . . .  6-13
           6.4     DATAGRAM SERVICE . . . . . . . . . . . . . . . .  6-14
           6.4.1     Send Datagram  . . . . . . . . . . . . . . . .  6-14
           6.4.2     Send Datagram Poll . . . . . . . . . . . . . .  6-15
           6.4.3     Receive Datagram . . . . . . . . . . . . . . .  6-15
           6.4.4     Receive Datagram Poll  . . . . . . . . . . . .  6-16
           6.4.5     Cancel Receive Datagram  . . . . . . . . . . .  6-16
           6.5     SEQUENTIAL MESSAGE SERVICE . . . . . . . . . . .  6-17
           6.5.1     Send Message . . . . . . . . . . . . . . . . .  6-18
           6.5.2     Send Message Poll  . . . . . . . . . . . . . .  6-18
           6.5.3     Receive Message  . . . . . . . . . . . . . . .  6-19
           6.5.4     Receive Message Poll . . . . . . . . . . . . .  6-19
           6.5.5     Cancel Receive Message . . . . . . . . . . . .  6-20
           6.5.6     Cancel Receive Message Poll  . . . . . . . . .  6-20
           6.6     BLOCK DATA SERVICE . . . . . . . . . . . . . . .  6-21
           6.6.1     Map Buffer . . . . . . . . . . . . . . . . . .  6-21
           6.6.2     Unmap Buffer . . . . . . . . . . . . . . . . .  6-22
           6.6.3     Read . . . . . . . . . . . . . . . . . . . . .  6-22
           6.6.4     Read Poll  . . . . . . . . . . . . . . . . . .  6-23
           6.6.5     Write  . . . . . . . . . . . . . . . . . . . .  6-24
           6.6.6     Write Poll . . . . . . . . . . . . . . . . . .  6-25


   CHAPTER 7       SCS-PPD INTERFACE

           7.1     DATAGRAM SERVICE . . . . . . . . . . . . . . . . . 7-1
           7.1.1     Send Datagram  . . . . . . . . . . . . . . . . . 7-1
           7.1.2     Receive Datagram . . . . . . . . . . . . . . . . 7-2
           7.1.3     Return Datagram Buffer . . . . . . . . . . . . . 7-2
           7.2     VIRTUAL CIRCUIT SERVICE  . . . . . . . . . . . . . 7-3
           7.2.1     Start Virtual Circuit  . . . . . . . . . . . . . 7-3
           7.3     MESSAGE SERVICE  . . . . . . . . . . . . . . . . . 7-4
           7.3.1     Send Message . . . . . . . . . . . . . . . . . . 7-4
           7.3.2     Receive Message  . . . . . . . . . . . . . . . . 7-4
           7.3.3     Return Message Buffer  . . . . . . . . . . . . . 7-4
           7.4     BLOCK DATA SERVICE . . . . . . . . . . . . . . . . 7-5
           7.4.1     Send Data  . . . . . . . . . . . . . . . . . . . 7-5
           7.4.2     Request Data . . . . . . . . . . . . . . . . . . 7-6
           7.5     RESPONSES  . . . . . . . . . . . . . . . . . . . . 7-7


   CHAPTER 8       SCS MESSAGES AND DATAGRAMS

           8.1     TYPES  . . . . . . . . . . . . . . . . . . . . . . 8-1
           8.2     SCS CONTROL MESSAGES . . . . . . . . . . . . . . . 8-3
           8.2.1     Connect Request  . . . . . . . . . . . . . . . . 8-3
           8.2.2     Connect Response . . . . . . . . . . . . . . . . 8-4
           8.2.3     Accept Request . . . . . . . . . . . . . . . . . 8-5
           8.2.4     Accept Response  . . . . . . . . . . . . . . . . 8-6
           8.2.5     Reject Request . . . . . . . . . . . . . . . . . 8-7
           8.2.6     Reject Response  . . . . . . . . . . . . . . . . 8-8
           8.2.7     Disconnect Request . . . . . . . . . . . . . . . 8-9
           8.2.8     Disconnect Response  . . . . . . . . . . . . .  8-10
   SYSTEMS COMMUNICATIONS ARCHITECTURE - DEC COMPANY CONFIDENTIAL  Page 4


           8.2.9     Credit Request . . . . . . . . . . . . . . . .  8-11
           8.2.10    Credit Response  . . . . . . . . . . . . . . .  8-12
           8.3     APPLICATION MESSAGE  . . . . . . . . . . . . . .  8-13
           8.4     APPLICATION DATAGRAM . . . . . . . . . . . . . .  8-14


   CHAPTER 9       SCS OPERATION

           9.1     RELATION TO PPD VIRTUAL CIRCUIT  . . . . . . . . . 9-1
           9.2     SCS PROTOCOL VERSION RESOLUTION  . . . . . . . . . 9-1
           9.3     SCS CONTROL MESSAGE FLOW CONTROL . . . . . . . . . 9-1
           9.4     SCS OPERATION DESCRIPTION  . . . . . . . . . . . . 9-3
           9.5     TYPE, VARIABLE , FUNCTION, AND PROCEDURE 
                   DEFINITIONS  . . . . . . . . . . . . . . . . . . . 9-5
           9.6     CONFIGURATION SERVICE  . . . . . . . . . . . . .  9-10
           9.6.1     System Block . . . . . . . . . . . . . . . . .  9-10
           9.6.2     Path Block . . . . . . . . . . . . . . . . . .  9-12
           9.6.3     Configuration Services . . . . . . . . . . . .  9-13
           9.7     CONNECTION MANAGEMENT SERVICE  . . . . . . . . .  9-15
           9.7.1     Connection Block . . . . . . . . . . . . . . .  9-15
           9.7.2     Connection States  . . . . . . . . . . . . . .  9-19
           9.7.3     Connect  . . . . . . . . . . . . . . . . . . .  9-21
           9.7.4     Listen . . . . . . . . . . . . . . . . . . . .  9-22
           9.7.5     Accept . . . . . . . . . . . . . . . . . . . .  9-22
           9.7.6     Reject . . . . . . . . . . . . . . . . . . . .  9-23
           9.7.7     Disconnect . . . . . . . . . . . . . . . . . .  9-23
           9.7.8     State Poll . . . . . . . . . . . . . . . . . .  9-24
           9.8     DATAGRAM SERVICE . . . . . . . . . . . . . . . .  9-25
           9.8.1     Send Datagram  . . . . . . . . . . . . . . . .  9-25
           9.8.2     Send Datagram Poll . . . . . . . . . . . . . .  9-25
           9.8.3     Receive Datagram . . . . . . . . . . . . . . .  9-26
           9.8.4     Receive Datagram Poll  . . . . . . . . . . . .  9-26
           9.8.5     Cancel Receive Datagram  . . . . . . . . . . .  9-27
           9.9     SEQUENTIAL MESSAGE SERVICE . . . . . . . . . . .  9-28
           9.9.1     Send Message . . . . . . . . . . . . . . . . .  9-28
           9.9.2     Send Message Poll  . . . . . . . . . . . . . .  9-29
           9.9.3     Receive Message  . . . . . . . . . . . . . . .  9-29
           9.9.4     Receive Message Poll . . . . . . . . . . . . .  9-30
           9.9.5     Cancel Receive Message . . . . . . . . . . . .  9-31
           9.9.6     Cancel Receive Message Poll  . . . . . . . . .  9-31
           9.10    BLOCK DATA SERVICE . . . . . . . . . . . . . . .  9-33
           9.10.1    Buffer Descriptor Table  . . . . . . . . . . .  9-33
           9.10.2    Map Buffer . . . . . . . . . . . . . . . . . .  9-34
           9.10.3    Unmap Buffer . . . . . . . . . . . . . . . . .  9-34
           9.10.4    Read . . . . . . . . . . . . . . . . . . . . .  9-34
           9.10.5    Read Poll  . . . . . . . . . . . . . . . . . .  9-35
           9.10.6    Write  . . . . . . . . . . . . . . . . . . . .  9-35
           9.10.7    Write Poll . . . . . . . . . . . . . . . . . .  9-36
           9.11    SCS SEND . . . . . . . . . . . . . . . . . . . .  9-37
           9.12    SCS RECEIVE  . . . . . . . . . . . . . . . . . .  9-39


   CHAPTER 10      CI PPD OPERATION

           10.1    PPD DATAGRAMS  . . . . . . . . . . . . . . . . .  10-1
   SYSTEMS COMMUNICATIONS ARCHITECTURE - DEC COMPANY CONFIDENTIAL  Page 5


           10.1.1    Start  . . . . . . . . . . . . . . . . . . . .  10-1
           10.1.2    Start Acknowledge  . . . . . . . . . . . . . .  10-2
           10.1.3    Acknowledge  . . . . . . . . . . . . . . . . .  10-3
           10.2    START VIRTUAL CIRCUIT  . . . . . . . . . . . . .  10-4
           10.3    CONFIGURATION  . . . . . . . . . . . . . . . . .  10-6
           10.4    OTHER PPD INTERFACE FUNCTIONS  . . . . . . . . .  10-6


   CHAPTER 11      NI PPD OPERATION


   CHAPTER 12      BI PPD OPERATION


   APPENDIX A      PROCESS NAMING


   APPENDIX B      DIRECTORY SERVICE

           B.1     INTRODUCTION . . . . . . . . . . . . . . . . . . . B-1
           B.2     LOCAL DIRECTORY MANAGEMENT . . . . . . . . . . . . B-1
           B.2.1     Enter  . . . . . . . . . . . . . . . . . . . . . B-1
           B.2.2     Delete . . . . . . . . . . . . . . . . . . . . . B-2
           B.3     REMOTE DIRECTORY ACCESS  . . . . . . . . . . . . . B-2
           B.3.1     Lookup Request . . . . . . . . . . . . . . . . . B-3
           B.3.2     Lookup Response  . . . . . . . . . . . . . . . . B-4


   APPENDIX C      THIRD PARTY I/O


   APPENDIX D      SCS/PPD TYPE AND LENGTH CODES


   APPENDIX E      REJECTION AND DISCONNECTION REASON CODES


   APPENDIX F      CI START DATA FORMAT


   APPENDIX G      EXAMPLE CI MESSAGE


   APPENDIX H      MINIMAL SUPPORT


   APPENDIX I      CHANGE HISTORY











                                 CHAPTER 1

                                INTRODUCTION



   This document describes the Systems Communications Architecture (SCA).
   SCA  should  be  contrasted with a network communications architecture
   (e.g.   DECNET/DNA).   SCA  is  intended  to  be  useful  as  an   I/O
   architecture  in  the  traditional  sense:   it  is optimized for high
   performance.  This high performance is  achieved  by  restricting  the
   topologies,   by  specializing  the  function  of  the  communications
   services, and by assuming  that  communicating  processes  are  highly
   trustworthy.   A  network communications architecture, in contrast, is
   designed to support varied topologies, more generalized  communication
   services, and less trustworthy communicating processes.
|  
|  This document describes  an  architecture  and  is  not  a  functional
|  specification  for an implementation.  An architecture document can be
|  contrasted with a functional specification in several ways:
|  
|        o  The descriptions of  the  interfaces  (calls)  and  the  data
|           structures  are general and need not be adhered to exactly in
|           an implementation.   They  werve  to  specifiy  the  services
|           present but need not restrict additional services provided.
|  
|        o  An architecture provides a model of an implementation through
|           which  it describes the algorithms used in am implementation.
|           It is the algorithms that are important and not  the  details
|           of   the   data   passing   and   synchronization   that   an
|           implementation uses to embody those algorithms.
|  
|           Polling is used as the model of synchronization here  because
|           it  is  simple  to  describe  and  because  it requires fewer
|           interface calls.  To describe a model using polling  requires
|           only calls to lower layers and not calls from lower layers to
|           higher layers.
|  
|           The algorithms are important in so far as their  results  are
|           visible  at  interfaces  and in the protocol.  It may be that
|           implementations can modify the  algorithms  and  achieve  the
|           same result.
|  
|        o  Descriptions of protocol messages are exact and  their  order
|           is  important.   These  serve to allow all implementations of
|           the architecture to communicate.
   INTRODUCTION                                                  Page 1-2


   The current revision of  this  document  is  focused  on  clusters  of
   systems  interconnected  with  the  CI.   Later revisions will include
   additional information on the relation of SCA to the NI and BI.











                                 CHAPTER 2

                          SCA TOPOLOGICAL NOTATION



   2.1  NETWORK

   A set of interconnected  systems  that  communicate  using  a  network
   communications service (e.g.  DECNET/DNA NSP).
|  
|  
|  
|  2.2  SCA CLUSTER
|  
   A set of interconnected systems that  communicate  using  the  Systems
   Communications  Services  (SCS).  The systems in a cluster are managed
   by a single system manager and lie within a single security boundary.



   2.3  COMMMUNICATIONS SERVICE

   A module or process that provides a set of communications services  to
   a user.



   2.4  SYSTEM ADDRESS

   The 48-bit address  of  a  system  in  a  cluster  or  network.   More
   specifically,  it  is  the address of a network communications service
   and/or an SCS.  Not all systems necessarily  contain  both  a  network
   communications   service   and  an  SCS.   The  system  addresses  are
   necessarily unique within the cluster or network  and  are  preferably
   globally  unique.   System  addresses  with  bit 47 equal to 1 are not
   allowed.  System address 0 is not allowed.



   2.5  PORT

   The interface between an interconnect and the physical processor  that
   implements network communications services and/or SCS.
   SCA TOPOLOGICAL NOTATION                                      Page 2-2


   2.6  PORT DRIVER

   The software that controls a port.



   2.7  INTERCONNECT

   A physical communications path between ports.



   2.8  POINT-TO-POINT INTERCONNECT

   An interconnect joining two ports.



   2.9  MULTIACCESS INTERCONNECT

   An  interconnect   joining   multiple   ports   that   allows   direct
   communication   between   all  port  pairs.   An  n  port  multiaccess
   interconnect  is  logically  equivalent  to  n(n-1)/2   point-to-point
   interconnects.    The  CI  (Computer  Interconnect)  and  NI  (Network
   Interconnect) are multiaccess interconnects.
|  
|  
|  
|  2.10  PORT ADDRESS
|  
|  The 48 bit address of a port on a multiaccess interconnect.  The  port
|  address may or may not be related to the system address.  For example,
|  the 48-bit NI port address is  normally  the  system  address  of  the
|  system it interfaces.











                                 CHAPTER 3

                                SCA TOPOLOGY



   The basic topology supported by SCA is a fully, directly connected set
   of systems.  This can be realized either by a multiaccess interconnect
   or an equivalent set of point-to-point interconnects.  The purpose  of
   this restricted support is to eliminate the complexity of routing from
   SCA.  The multiaccess CI is the current focus for SCA:


                                                   CI
           --------+---------------+---------------+--------
                   |               |               |
                   |               |               |
             +-----+-----+   +-----+-----+   +-----+-----+
             |   system  |...|   system  |...|   system  | 
             +-----------+   +-----------+   +-----------+


   Note that the redundant dual path CI is logically a single CI.

   In large clusters a single CI may have inadequate bandwidth.  In  this
   case the acceptable topology is paralleled CI's:




                                           CI
           -----------+---------------+---------------+-----
                      |               |               |
                      |               |    CI         |                    
           --------+---------------+---------------+--------
                   |  |            |  |            |  |
                   |  |            |  |            |  |
             +-----+--+--+   +-----+--+--+   +-----+--+--+
             |   system  |...|   system  |...|   system  |
             +-----------+   +-----------+   +-----------+



   This topology retains the fully interconnected property.
   SCA TOPOLOGY                                                  Page 3-2


   Non-fully connected systems may be interconnected using multiple CI's.
   An  example  would  be several CPU's sharing file storage systems on a
   common CI but with private paging systems on private CI's:


                                   Common CI
           --------+-----------------+-----------------+--------
                   |                 |                 |
                   |                 |                 |
             +-----+------+    +-----+-----+    +------+-----+
             |  system X  |... |   system  |... |   system Y |
             +-----+------+    +-----------+    +------+-----+
                   |                                   |
           pvt     |                                   |    pvt
           CI      |                                   |    CI
                   |                                   |
                   |                                   |
             +-----+-----+                      +------+-----+
             |   system  |                      |  system Z  |
             +-----------+                      +------------+



   In this topology system X cannot communicate with system Z using  SCS.
   If  the services provided by system Z are to be available to system X,
   an intercept process (not part of SCA) must be provided in system Y.











                                 CHAPTER 4

                                SCA LAYERING



   SCA is described as a multilayer communications architecture.  Layer 0
   is  the  Physical  Interconnect (PI) layer (e.g., the CI).  Layer 1 is
   the Port/Port (PPD) Driver layer, which  controls  the  PI  layer  and
   provides  reliable,  sequential transfers of data between ports on the
   PI.  (In the case of the CI, most of the PPD layer is  implemented  by
   the  CI  port.)  Layer  2  is the Systems Communication Services (SCS)
   layer, which provides the process and  system  addressing,  connection
   management, and flow control necessary to multiplex the basic PPD data
   services among multiple users.  Layer 3  is  the  System  Applications
   (SYSAP) layer, which represents the users of SCS.
                      
                      
                      3.   System Applications (SYSAP)

                   -------------------------------------

                      2.   Systems Communications
                           Services (SCS)

                   -------------------------------------

                      1.   Port/Port Driver (PPD)

                   -------------------------------------

                      0.   Physical Interconnect (PI)

                   

   By analogy to DECNET/DNA  the  SCA  SYSAP  layer  corresponds  to  the
   DECNET/DNA Network Applications layer, SCS to NSP, and PPD to DDCMP.











                                 CHAPTER 5

                        SYSAP-SCS INTERFACE NOTATION



   5.1  PROCESS

   A communicating entity that uses SCS:  i.e., a SYSAP.



   5.2  PROCESS NAME

   A 16-byte string that identifies a SYSAP process within a system.  See
   Appendix A.



   5.3  DIRECTORY

   A list of SYSAP process names that exist in a system.  See Appendix B.



   5.4  SYSTEM LIST

   A data structure that contains information on systems  in  a  cluster.
   Included  are  system chracteristics, system port characteristics, and
   the state of port-to-port communications with the systems.



   5.5  SYSTEM BLOCK

   A data structure on the system list that describes the characteristics
   of a system in a cluster.



   5.6  PATH BLOCK

   A data structure on the system list that describes the characteristics
   of a particular interconnect used for port-to-port communications to a
   specific system in a cluster.
   SYSAP-SCS INTERFACE NOTATION                                  Page 5-2


   5.7  CONNECTION

   The synchronization of two connection blocks in the same or  different
   systems  to define a logical communications path between processes.  A
   process may participate in more than one connection at a time.



   5.8  CONNECTION BLOCK

   A data structure that contains the state of a connection.



   5.9  CONNECT ID

   The 32-bit identifier of a connection block within a system.  This  is
   normally  treated  as a 16-bit connection number and a 16-bit sequence
   number.
|  
|  
|  
|  5.10  DATAGRAM COMMUNICATION SERVICE
|  
|  The transmission of an independent information unit (datagram) over  a
|  connection.   Delivery  of  the datagram occurs with high probability,
|  but is not guaranteed.  Also, the order of delivery of a  sequence  of
|  datagrams is not guaranteed.



   5.11  DATAGRAM BUFFER

   A buffer that contains (or can contain) a datagram.  In SCA a datagram
   buffer  appears  in  layers  1,  2,  and  3.  To avoid copying between
   layers, a datagram buffer is defined large enough to support layer  1,
   2,  and  3  data.   Layer  3  ignores the layer 1 and 2 data;  layer 2
   ignores the layer 1 data.
|  
|  
|  
|  5.12  SEQUENTIAL MESSAGE COMMUNICATIONS SERVICE
|  
|  The transmission  of  a  sequence  of  independent  information  units
|  (messages)  over  a connection.  The messages are guaranteed to arrive
|  in the order they were sent (without loss or duplication) or an  error
|  condition is indicated to the sender.
   SYSAP-SCS INTERFACE NOTATION                                  Page 5-3


   5.13  MESSAGE BUFFER

   A buffer that contains (or can contain) a message.  A  message  buffer
   is  also  used  to  contain  control  information  for  the block data
   communications service.  In SCA a message buffer appears in layers  1,
   2,  and  3.   To  avoid  copying  between  layers, a message buffer is
   defined large enough to support layer 1,  2,  and  3  data.   Layer  3
   ignores the layer 1 and 2 data;  Layer 2 ignores the layer l data.



   5.14  QUEUED BUFFER

   Either a datagram or a message buffer.
|  
|  
|  
|  5.15  BLOCK DATA COMMUNICATIONS SERVICE
|  
|  The direct transmission of information (block data)  between  a  named
|  local  buffer  and a named destination buffer.  The transmission takes
|  place over a connection between the system containing the local  named
|  buffer  and  the  system containing the destination named buffer.  The
|  block data is guaranteed to arrive completely or an error condition is
|  indicated to the sender.



   5.16  NAMED BUFFER

   A named memory buffer used by the block data service.  A  buffer  name
   is  a 32-bit value.  A buffer is considered byte addressable with each
   byte specified by a 32-bit unsigned offset from the beginning (byte 0)
   of the buffer.



   5.17  FLOW CONTROL

   The method by which the rate of information flow from  the  sender  to
   the  receiver  is controlled.  In SCS there is no flow control applied
   to the datagram service.  For the sequential message  and  block  data
   services,  flow is controlled by a credit-based protocol that inhibits
   a sender from sending information (messages, block  data  control,  or
   block  data)  until  the receiver has provided a buffer to receive the
   information.



   5.18  CREDIT

   A logical token held by  a  sending  process  that  indicates  that  a
   receiving process has queued a message buffer to (1) receive a message
   or (2) permit a block data operation.











                                 CHAPTER 6

                            SYSAP-SCS INTERFACE



   The SCS interface  is  modelled  as  a  set  of  PASCAL  functions  or
   procedures of the form:

           function FUNCTIONNAME ([var] ARGUMENTNAME:TYPE
           [;[var]ARGUMENTNAME:TYPE]...):FUNCTIONSTATUS;

   or              
           procedure PROCEDURENAME([var]ARGUMENTNAME:TYPE
           [;[var]ARGUMENTNAME:TYPE]...);



   where:

   [] - indicates optional.

   var - indicates an output argument.

   FUNCTIONNAME - the name of the function.

   PROCEDURENAME - the name of the procedure.

   ARGUMENTNAME - the name of the argument.

   TYPE - the type of the argument.

   ...  - indicates replication.

   FUNCTIONSTATUS - the status of function execution.
   SYSAP-SCS INTERFACE                                           Page 6-2


   6.1  TYPE DEFINITIONS

   The following PASCAL  type  definitions  apply  to  the  function  and
   procedure arguments:

|  type    BYTE = -128..127;
|          
|          WORD = -32768..32767;
|          
|          LONG = {32-bit} integer;
|          
|          QUAD = packed array [1..8] of BYTE;
|  
|          SEPTA = packed array [1..12] of BYTE;
|  
|          OCTA = packed array [1..16] of BYTE;
|  
|          SYSTEM = packed array [1..6] of BYTE;           { system address }
|          
|          PORT = packed array [1..6] of BYTE;             { port address }
|          
|          PROC_NAME = packed array [1..16] of BYTE;       { process name }
|          
|          CONNECT_ID = record                             { connect id } 
|                  INDEX: WORD;
|                  SEQ: WORD
|                  end;
|          
|          SB_INDEX = WORD;                                { system block index }
|  
|          PB_INDEX = WORD;                                { path block index }
|  
|          C_DATA = packed array [1..16] of BYTE;          { connect data }
|          
|          APPL_MSG_LEN = 0..MAX_APPL_MSG;                 { SYSAP message length }
|          
|          APPL_DG_LEN = 0..MAX_APPL_DG;                   { SYSAP datagram length } 
|          
|          BUF_USE = (BLK_ARG,MSG_DG);                     { variant record selector }
|          
|          MSGDG = (MSG,DG);                               { variant record selector }
|  
|          MSG_USE = (CONTROL,APPL);                       { variant record selector }
|          
|          Q_BUF_PTR = ^Q_BUFFER;                          { address of a queued buffer }
|  
|          Q_BUFFER = record                               { queued command buffer for message, datagram, or block transfer }
|                  NEXT: Q_BUF_PTR;                        { next buffer in queue }
|                  { PPD layer data }
|                  case BUF_USE of
|  
|                  BLK_ARG:(                               { block data command }
|                          SEND_BLOCK_ID: WORD;            { connection block index for the transfer }
|                          SEND_XID: WORD;                 { transaction number }
|                          DATA_LENGTH: LONG;              { number of bytes to be transferred }
   SYSAP-SCS INTERFACE                                           Page 6-3


|                          SEND_NAME: LONG;                { buffer name of source buffer }
|                          SEND_OFFSET: LONG;              { starting byte in source buffer }
|                          REC_NAME: LONG;                 { buffer name of destination buffer }
|                          REC_OFFSET: LONG);              { starting byte in destination buffer }
|  
|                  MSG_DG:(                                { message or datagram command }
|                          LENGTH: WORD;                   { length in bytes of following fields }
|                          PPD_TYPE: WORD;                 { PPD message type code }
|                          SCS_TYPE: WORD;                 { SCS message type code }
|                          CREDIT: WORD;                   { number of credits to extend }
|                          REC_CONNECT_ID: CONNECT_ID;     { destination connect ID }
|                          SEND_CONNECT_ID: CONNECT_ID;    { source connect ID }
|                          case MSGDG of
|  
|                          DG:(                            { if Datagram, just include application info. }
|                                  DG_TEXT: packed array [1..MAX_APPL_DG]
|                                  of BYTE);
|  
|                          MSG:(                           { if Message ... }
|                                  case MSG_USE of
|  
|                                  CONTROL:(               { ... and this is SCS control message, then ... }
|                                          MIN_CREDIT: WORD;       { credit extended }
|                                          STATUS: WORD;           { reason for accept/reject }
|                                          REC_PROC: PROC_NAME;    { destination process name }
|                                          SEND_PROC: PROC_NAME;   { source process name }
|                                          SEND_DATA: C_DATA);     { connect data }
|  
|                                  APPL:(                  { ... else SYSAP message, so just include SYSAP stuff. }
|                                          MSG_TEXT: packed array
|                                          [1..MAX_APPL_MSG] of BYTE)))
|                  end;
|                                  
|          
|          { BUF_DESCR = implementation specific named buffer descriptor }
|  
|          
|  
|          C_STATE = (                             { process-to-process connection state }
|                  CLOSED,                         { connection is closed by command }
|                  LISTENING,                      { listening for connection request }
|                  CONNECT_SENT,                   { connect request was transmitted }
|                  CONNECT_REC,                    { connect request was received }
|                  CONNECT_ACK,                    { connect response was received }
|                  OPEN,                           { connection is open }
|                  ACCEPT_SENT,                    { accept request was sent }
|                  REJECT_SENT,                    { reject request was sent }
|                  DISCONNECT_SENT,                { disconnect message was transmitted }
|                  DISCONNECT_REC,                 { disconnect message was received }
|                  DISCONNECT_ACK,                 { response received, waiting for remote disconnect }
|                  DISCONNECT_MATCH                { waiting for matching response confirmation }  
|                  );
|  
|          FSTATUS = (FAIL,SUCCESS,NULL,NOT_OPEN); { function status }
|  
   SYSAP-SCS INTERFACE                                           Page 6-4


|          PORT_CHAR = packed array [1..16] of BYTE; { see appropriate port specification }
|  
|          VC_STATE = (                            { port-to-port virtual circuit state }
|                  MAINT,                          { maintenance state }
|                  VC_CLOSED,                      { virtual circuit closed }
|                  START_SENT,                     { start sequence initiated }
|                  START_REC,                      { start sequence received }
|                  VC_OPEN                         { virtual circuit is open }
|                  ); { virtual circuit state }{SYSAPDEF}
   SYSAP-SCS INTERFACE                                           Page 6-5


   6.2  CONFIGURATION SERVICES

   The configuration services allow the caller to determine the  identity
   of  the  connected  systems and the number of paths to each system.  A
   system block is read by calling CONFIG_SYS.  The system block contains
   information   on   a   remote   system,   its  hardware  and  software
   characteristics, and the number of connecting paths.  A path block  is
   read   by   calling   CONFIG_PATH.    The  path  block  contains  port
   characteristics and the state of port  to  port  communications.   The
   REQ_ID  procedure  updates  the  port  characteristics field of a path
   block.



   6.2.1  System Configuration

   This function reads a system block:

|  function CONFIG_SYS(
|          ENTRY: SB_INDEX;
|          var FIRST_PB: PB_INDEX;
|          var SYS: SYSTEM;
|          var MAX_DG: WORD;
|          var MAX_MSG: WORD;
|          var SW_TYPE: LONG;
|          var SW_VERSION: LONG;
|          var SW_INCARNATION: QUAD;
|          var HW_TYPE: LONG;
|          var HW_VERSION: SEPTA;
|          var NODE_NAME: QUAD;
|          var PORT_COUNT: WORD):
|          FSTATUS;
   where:

       ENTRY           the system list entry:  entries start at one.

       FIRST_PB        the path block index of  the  first  path  to  the
                       destination system.

       SYS             the destination system address.

       MAX_DG          the maximum size datagram (in bytes) supported  by
                       the destination system.

       MAX_MSG         the maximum size message (in bytes)  supported  by
                       the destination system.

       SW_TYPE         4-character ASCII software type of the destination
                       system.

       SW_VERSION      4-character  ASCII   software   version   of   the
                       destination system.
   SYSAP-SCS INTERFACE                                           Page 6-6


|      SW_INCARNATION  software incarnation of  the  destination  system.
|                      This  is  initialized  by  the  system at its boot
|                      time.  When  a  ppd  vc  is  established  and  the
|                      SW_INCARNATION  changes  from a previous value, it
|                      indicates that all of the  system  software  state
|                      has been lost.

       HW_TYPE         the hardware type of the destination system.

       HW_VERSION      the hardware version of the destination system.

       NODE_NAME       the 8-byte ASCII  node  name  of  the  destination
                       system.

       PORT_COUNT      the number of ports to the destination system.

       FSTATUS         SUCCESS if entry is valid;  FAIL otherwise.



   6.2.2  Path Configuration

   This function reads a path block.  The path block index for the  first
   path  block  to  a  destination  system is determined by first calling
   CONFIG_SYS for that system.  Successive calls to  CONFIG_PATH  can  be
   made to scan the list of path blocks for a particular system.

   function CONFIG_PATH(
           ENTRY: PB_INDEX;
           var STATE: VC_STATE;
           var PRT: PORT;
           var NEXT_PB: PB_INDEX;
           var SB: SB_INDEX;
           var CHAR: PORT_CHAR):
           FSTATUS;

   where:

       ENTRY           the index of the path block to be examined;   path
                       block indices start at one.

       STATE           the  virtual  circuit  state  to  the  destination
                       system   over   this   path.   (MAINT,  VC_CLOSED,
                       START_SENT, START_REC, VC_OPEN)

       PRT             the destination system port address.

       NEXT_PB         the path block index of  the  next  path  to  this
                       system, or zero if this is the last path block.

       SB              the system block index  of  the  system  block  to
                       which this path block is queued.
   SYSAP-SCS INTERFACE                                           Page 6-7


       CHAR            the  characteristics  of  the  destination  system
                       port.  (See the appropriate port specification.)

       FSTATUS         SUCCESS if entry is valid;  FAIL otherwise.

   Only if STATE =  VC_OPEN  can  the  connection  management,  datagram,
   sequential message, and block data services be used.
|  
|  REQUEST ID REMOVED
   SYSAP-SCS INTERFACE                                           Page 6-8


   6.3  CONNECTION MANAGEMENT SERVICE

|  A connection exists in one  of  several  states:   CLOSED,  LISTENING,
|  CONNECT_SENT,   CONNECT_ACK,  CONNECT_REC,  ACCEPT_SENT,  REJECT_SENT,
|  OPEN,    DISCONNECT_SENT,    DISCONNECT_REC,    DISCONNECT_ACK     and
|  DISCONNECT_MATCH.
|  
|  There are two sides to a connection termed the  active  side  and  the
|  passive side.
|  
|  The passive side indicates a willingness to establish a connection  by
|  calling LISTEN.  This moves the passive side to the LISTENING state.
|  
|  The  active  side  initiates  a  connection  by  calling  CONNECT.   A
|  CONNECT_REQ  message  is  sent and the state moves to CONNECT_SENT.  A
|  CONNECT_RSP is received with a status of NO_MATCH indicating  that  no
|  such  process  is  listening,  NO_RESOURCES  if  no  connect  block is
|  available, or CONNECTED if  the  connection  can  be  handled  by  the
|  destination  system.  The connect request is handed to the destination
|  SYSAP at this point.  When  CONNECTED  is  returned,  the  CONNECT_ACK
|  state is entered, otherwise the CLOSED state is entered.
|  
|  In the CONNECT_ACK state a REJECT_REQ  causing  the  state  to  go  to
|  CLOSED  or  ACCEPT_REQ message can be received causing the state to go
|  to OPEN.
|  
|  When the SYSAP on the destination receives  the  connect  request,  it
|  responds  with  an  ACCEPT  causing  its side to go to the ACCEPT_SENT
|  state or a REJECT causing its side to  go  to  the  REJECT_SENT.   The
|  appropriate  reply from the active side of ACCEPT_RSP causes the state
|  to go OPEN, and recept of REJECT_RSP causes the state to go CLOSED.

   When the connection is OPEN,  the  datagram,  sequenced  message,  and
   block data services may be used.

   Either  side  initiates  termination  of  the  connection  by  calling
   DISCONNECT.   Following  the  DISCONNECT call, no datagram, sequential
   message, or block transfer transmission operations can be performed by
   the  disconnecting  side.   Attempts  to initiate a transfer will fail
   with status NOT_OPEN.  The sequence of  states  is  dependent  on  the
   order  of  the DISCONNECT calls.  The protocol is generally asymmetric
   with one side, called the active side, initiating the disconnect.

   The active side calling DISCONNECT moves to the DISCONNECT_SENT  state
   while the passive side moves to DISCONNECT_REC state.  When the active
   side is notified of receipt of the disconnect request by  the  passive
   side,  it  moves  to  DISCONNECT_ACK  state.   Both sides wait for the
   passive SYSAP to be notified of the request and to  respond  with  its
   own  DISCONNECT.  When the passive SYSAP calls DISCONNECT, the passive
   side moves to DISCONNECT_MATCH and notifies the  active  side  of  the
   SYSAP's  action.   The  active  side  moves  to  CLOSED state, and the
   passive side moves to CLOSED upon  confirmation.   Should  both  sides
   issue   DISCONNECT  requests  simultaneously,  the  protocol  will  be
   symmetric   with   both   active   sides   moving    through    states
   DISCONNECT_SENT, DISCONNECT_MATCH, and CLOSED.
   SYSAP-SCS INTERFACE                                           Page 6-9


|  If there is any failure  of  lower  SCA  layers,  both  sides  of  any
|  non-closed connection move to the CLOSED state.

   The (local side) state  of  a  connection  is  determined  by  calling
   CONNECT_STATE_POLL.    Section   9.6   contains  a  full  state  table
   describing the above states and transition conditions.
|  
|  SYSAPs that require a minimum size for messages and datagrams  operate
|  in the following manner to assure that these message sizes are present
|  on a connection:  When the SYSAP starts, it checks the  message  sizes
|  on the local system and does not perform a LISTEN if the message sizes
|  are too small.  Before a SYSAP  performs  a  connect,  it  checks  the
|  message sizes of the remote system and does not perform the CONNECT if
|  the remote systems message sizes are too small.  The message sizes can
|  be determined with the CONFIG_SYS request.



   6.3.1  Connect

   This function allocates a connection block  and  actively  requests  a
   connection:

|  function CONNECT(
|          var CID: CONNECT_ID;
|          SRC_PROC: PROC_NAME;
|          DST_PROC: PROC_NAME;
|          DST: SB_INDEX;
|          THRSH: WORD;
|          { [CREDITS: Q_BUF_PTR];... }
|          DATA: C_DATA
|          { [PATH: PB_INDEX] }
|          ):
|          FSTATUS;
   where:

       CID             the connect id of the connection  block  allocated
                       by CONNECT.

       SRC_PROC        the local process name.

       DST_PROC        the destination process name.

       DST             the system block corresponding to the  destination
                       system.

       THRSH           the  minimum  number  of   message   buffers   the
                       destination  process  should  maintain  for proper
                       operation of the SYSAP protocol.
|  
|      CREDITS         the address of a  list  of  message  buffers  that
|                      represent an initial credit.
   SYSAP-SCS INTERFACE                                          Page 6-10


       DATA            initial connection data.  The format  of  DATA  is
                       process specific.

       PATH            optional Path  Block  index,  if  SYSAP  needs  to
                       request connection over a specific interconnect.
|  
|      ERROR           REMOVED

       FSTATUS         SUCCESS if a connection block is allocated;   FAIL
                       otherwise.



   6.3.2  Listen

   This function allocates a connection block and passively listens for a
   connection request from a destination process:

|  function LISTEN(
|          var CID: CONNECT_ID;
|          SRC_PROC: PROC_NAME;
|          DST_PROC: PROC_NAME;
|          DST: SB_INDEX ):
|          FSTATUS;
   where:

       CID             the connect id of the connection  block  allocated
                       by LISTEN.

       SRC_PROC        the local process name.

       DST_PROC        the destination process name.  A DST_PROC field of
                       all  blanks  indicates a willingness to connect to
                       any process.

       DST             the system block corresponding to the  destination
                       system.   A DST field of 0 indicates a willingness
                       to connect to any system.
|  
|      THRSH           REMOVED

       FSTATUS         SUCCESS if a connection block is available;   FAIL
                       otherwise.
   SYSAP-SCS INTERFACE                                          Page 6-11


   6.3.3  Accept

   This procedure accepts a requested connection:

|  procedure ACCEPT(
|          CID: CONNECT_ID;
|          { [CREDITS: Q_BUF_PTR];...}
|          THRSH : WORD;
|          DATA: C_DATA);

   where:

       CID             the local connect id.

       CREDITS         the address of a message buffer that represents an
                       initial credit.
|  
|      THRSH           the  minimum  number  of   message   buffers   the
|                      destination  process  should  maintain  for proper
|                      operation of the SYSAP procotol.

       DATA            initial connection data.  The format  of  DATA  is
                       process specific.



   6.3.4  Reject

   This procedure rejects a requested connection:

   procedure REJECT(
           CID: CONNECT_ID;
           REASON: WORD);

   where:

       CID             the local connect id.
|  
|      REASON          the reason for rejection.  See Appendix E.
   SYSAP-SCS INTERFACE                                          Page 6-12


   6.3.5  Disconnect

   This procedure requests termination  of  a  connection.   Following  a
   disconnect  call,  further  transfer requests will be returned with an
   error.

   procedure DISCONNECT(
           CID: CONNECT_ID;
           REASON: WORD);

   where:

       CID             the local connect id.
|  
|      REASON          the reason for disconnection.  See Appendix E.
|  
|  /Due to the port design of the CI port, there is a restriction in  the
|  CI  PPD  layer.   DISCONNECT  cannot  be  called  until  all  (locally
|  initiated) outstanding block data transfers have completed.  SCS based
|  on  other  interconnects  need  not  have  this  restriction.  On some
|  interconnects waiting for block transfers could be too time  consuming
|  to make waiting practical./

   After DISCONNECT is called only the following connection  related  SCS
   calls are valid:

        1.  STATE_POLL

        2.  SEND_DG_POLL

        3.  REC_DG_POLL

        4.  CANCEL_REC_DG

        5.  SEND_MSG_POLL

        6.  REC_MSG_POLL

        7.  CANCEL_REC_MSG_POLL
   SYSAP-SCS INTERFACE                                          Page 6-13


   6.3.6  Connect State Poll

   This procedure returns the state of a connection:

   procedure STATE_POLL(
           CID: CONNECT_ID;
           var STATE: C_STATE;
           var DST_CID: CONNECT_ID;
           var DST_PROC: PROC_NAME;
           var DST_SB: SB_INDEX;
           var DST_PB: PB_INDEX;
           var DATA: C_DATA;
           var REASON: WORD);

   where:

       CID             the local connect id.
|  
|      STATE           the   connection   state.    (CLOSED,   LISTENING,
|                      CONNECT_SENT,       CONNECT_ACK,      CONNECT_REC,
|                      ACCEPT_SENT, REJECT_SENT,  OPEN,  DISCONNECT_SENT,
|                      DISCONNECT_REC,         DISCONNECT_ACK,         or
|                      DISCONNECT_MATCH.)

       DST_CID         the destination connect id.

       DST_PROC        the destination process name.

       DST_SB          the system block corresponding to the  destination
                       system.

       DST_PB          the path block corresponding to  the  interconnect
                       over which the connection exists.

       DATA            connect data.

       REASON          the reason for rejection or disconnection.

   Any queued datagram or message buffers remaining after a connection is
   closed are disposed of in an implementation specific manner.
   SYSAP-SCS INTERFACE                                          Page 6-14


   6.4  DATAGRAM SERVICE

   A datagram is sent by calling SEND_DG.  A  parameter  in  the  SEND_DG
   call  determines whether the buffer containing the datagram to be sent
   is to be returned or queued to receive  a  datagram.   In  the  former
   case,  the  datagram  buffer  is  returned by calling SEND_DG_POLL.  A
   datagram buffer is queued to receive  a  message  by  calling  REC_DG.
   Receipt  of a datagram is checked by calling REC_DG_POLL.  Return of a
   queued datagram buffer is requested by calling CANCEL_REC_DG.
|  
|  Datagrams are queued and accounted for on a per connection basis.   It
|  is possible to return datagrams quickly to the receive queues when too
|  many arrive for a connection and thereby  make  it  more  likely  that
|  datagram  receive buffers are available to connections which carefully
|  manage the number of datagram receive buffers they queue.



   6.4.1  Send Datagram

   This function sends a datagram over a connection:

   function SEND_DG(
           CID: CONNECT_ID;
           RET_FLAG: boolean;
           DLEN: APPL_DG_LEN;
           PTR: Q_BUF_PTR):
           FSTATUS;

   where:

       CID             the local connect id.

       RET_FLAG        true if the datagram buffer  is  to  be  returned,
                       false otherwise.

       DLEN            the length (in bytes) of the datagram text.

       PTR             the address of the datagram buffer.

       FSTATUS         SUCCESS if the send is  queued,  NOT_OPEN  if  the
                       connection has been closed.

   When RET_FLAG is false, SEND_DG  does  an  implicit  Receive  Datagram
   since  the  datagram  buffer  is  available after sending to receive a
   datagram.
   SYSAP-SCS INTERFACE                                          Page 6-15


   6.4.2  Send Datagram Poll

   This function checks the return of a datagram sent with  the  RET_FLAG
   true:

   function SEND_DG_POLL(
           CID: CONNECT_ID;
           var PTR: Q_BUF_PTR):
           FSTATUS;

   where:

       CID             the local connect id.

       PTR             the address of the datagram buffer.

       FSTATUS         SUCCESS  if  the   buffer   is   returned;    FAIL
                       otherwise.

   Note that the original buffer contents are returned intact.



   6.4.3  Receive Datagram

   This function queues a datagram buffer to receive a datagram:

   function REC_DG(
           CID: CONNECT_ID;
           PTR: Q_BUF_PTR):
           FSTATUS;

   where:

       CID             the local connect id.

       PTR             the address of the datagram buffer.

       FSTATUS         SUCCESS if the receive buffer is queued,  NOT_OPEN
                       if the connection has been closed.
   SYSAP-SCS INTERFACE                                          Page 6-16


   6.4.4  Receive Datagram Poll

   This function checks if a datagram has been received in  a  previously
   queued datagram buffer:

   function REC_DG_POLL(
           CID: CONNECT_ID;
           var DLEN: APPL_DG_LEN;
           var PTR: Q_BUF_PTR):
           FSTATUS;

   where:

       CID             the local connect id.

       DLEN            the length (in bytes) of the datagram text.

       PTR             the address of the datagram buffer.

       FSTATUS         SUCCESS if a datagram  has  been  received;   FAIL
                       otherwise.



   6.4.5  Cancel Receive Datagram

   This function dequeues a datagram buffer:

   function CANCEL_REC_DG(
           CID: CONNECT_ID;
           var PTR: Q_BUF_PTR):
           FSTATUS;

   where:

       CID             the local connect id.

       PTR             the address of the datagram buffer.

       FSTATUS         SUCCESS if a buffer is dequeued;  FAIL otherwise.
   SYSAP-SCS INTERFACE                                          Page 6-17


   6.5  SEQUENTIAL MESSAGE SERVICE

   A message is sent by calling SEND_MSG.  A parameter  in  the  SEND_MSG
   call  determines  whether  the  buffer containing the message is to be
   returned or queued to receive a message.   In  the  former  case,  the
   message buffer is returned by calling SEND_MSG_POLL.  A message buffer
   is queued to receive a message  by  calling  REC_MSG.   Receipt  of  a
   message  is  checked  by  calling  REC_MSG_POLL.   Return  of a queued
   message buffer is requested by  calling  CANCEL_REC_MSG.   The  queued
   message buffer is returned by calling CANCEL_REC_MSG_POLL.

   The  sequential  message  service  uses  credit-based  flow   control.
   Consider  two  sides of a connection X and Y.  When X queues a message
   buffer, Y receives a send credit.  In general, if Y queues  y  buffers
   and X queues x buffers, Y has x send credits and X has y send credits.

   To send a message, a send credit is needed.  When the message is sent,
   the number of send credits is decremented by 1.

   In order to support messages  of  different  importance  on  a  single
   connection,  a threshold mechanism is employed.  A threshold parameter
   appears in two places:

        1.  When a  connection  is  established  each  side  specifies  a
            threshold  which  is  the  minimum  number  of queued message
            buffers the other side should maintain for  proper  operation
            of  the  SYSAP  protocol  (i.e.   the  support of messages of
            different importance).  A CANCEL_REC_MSG call does not return
            buffers  that  would  drop  the number of send credits on the
            other side below the SYSAP protocol threshold.

        2.  A SEND_MSG call (also the READ  and  WRITE  calls:   see  the
            section  on  block  data service) has a threshold number that
            results in a message being sent only if at least that  number
            of send credits would remain after sending the message.
   SYSAP-SCS INTERFACE                                          Page 6-18


   6.5.1  Send Message

   This function sends a message over a connection:

   function SEND_MSG(
           CID: CONNECT_ID;
           THRSH: WORD;
           RET_FLAG: boolean;
           MLEN: APPL_MSG_LEN;
           PTR: Q_BUF_PTR):
           FSTATUS;

   where:

       CID             the local connect id.

       THRSH           the message is sent only if  at  least  this  many
                       send   flow  control  credits  will  remain.   The
                       minimum value of THRSH is 0.

       RET_FLAG        true if the message  buffer  is  to  be  returned;
                       false otherwise.

       MLEN            the length (in bytes) of the message.

       PTR             the address of the message buffer.

       FSTATUS         SUCCESS if the send is queued,  FAIL  if  no  flow
                       control  credit  is  available,  NOT_OPEN  if  the
                       connection has been closed.

   When RET_FLAG is false, SEND_MSG  does  an  implicit  Receive  Message
   since the message buffer is available to receive a message.



   6.5.2  Send Message Poll

   This function checks the return of a message sent  with  the  RET_FLAG
   true:

   function SEND_MSG_POLL(
           CID:CONNECT_ID;
           var PTR: Q_BUF_PTR):
           FSTATUS;

   where:

       CID             the local connect id.

       PTR             the address of the message buffer.

       FSTATUS         SUCCESS if a buffer is returned;  FAIL otherwise.
   SYSAP-SCS INTERFACE                                          Page 6-19


   Note that the original buffer contents are returned intact.



   6.5.3  Receive Message

   This function queues a message buffer to receive a message and extends
   a flow control credit to the destination process:

   function REC_MSG(
           CID: CONNECT_ID;
           PTR: Q_BUF_PTR):
           FSTATUS;

   where:

       CID             the local connect id.

       PTR             the address of the message buffer.

       FSTATUS         SUCCESS if the buffer has been queued, NOT_OPEN if
                       the connection has been closed.



   6.5.4  Receive Message Poll

   This function checks if a message has been received  in  a  previously
   queued message buffer:

   function REC_MSG_POLL(
           CID: CONNECT_ID;
           var MLEN: APPL_MSG_LEN;
           var PTR: Q_BUF_PTR):
           FSTATUS;

   where:

       CID             the local connect id.

       MLEN            the length (in bytes) of the message.

       PTR             the address of the message buffer.

       FSTATUS         SUCCESS if a  message  has  been  received;   FAIL
                       otherwise.
   SYSAP-SCS INTERFACE                                          Page 6-20


   6.5.5  Cancel Receive Message

   This procedure requests return of a message buffer (and the associated
   flow control credit from the destination process):

   procedure CANCEL_REC_MSG(
           CID: CONNECT_ID);

   where:

       CID             the local connect id.

   Cancellation does not occur if (1) the flow control  credit  has  been
   used  by the destination process to send a message or for a block data
   operation, or (2) the number of destination credits would  drop  below
   the SYSAP protocol threshold.



   6.5.6  Cancel Receive Message Poll

   This function checks if a cancel operation has completed:

   function CANCEL_REC_MSG_POLL(
           CID: CONNECT_ID;
           var PTR: Q_BUF_PTR):
           FSTATUS;

   where:

       CID             the local connect id.

       PTR             the address of the message buffer.

       FSTATUS         SUCCESS if a buffer  is  returned;   NULL  if  the
                       cancel cannot be completed;  FAIL otherwise.

   CANCEL_REC_MSG_POLL must be called until every cancel has  a  matching
   SUCCESS  or  NULL FSTATUS.  Null status indicates that the destination
   would not allow the buffer to be returned in order to keep the  number
   of credits above threshold.
   SYSAP-SCS INTERFACE                                          Page 6-21


   6.6  BLOCK DATA SERVICE

   A name is associated with a named buffer by calling  MAP.   This  name
   may  be used locally or passed to the other side of a connection using
   one of the communications services.  A name is  disassociated  from  a
   buffer by calling UNMAP.

   By calling WRITE, data is transferred  from  the  local  side  to  the
   destination  side.   The  completion  of  the  transfer  is checked by
   calling WRITE_POLL.  Similarly, by calling READ, data  is  transferred
   from  the  destination  side to the local side.  The completion of the
   transfer is checked by calling READ_POLL.

   To initiate a block data transfer, the local side  must  hold  a  send
   credit.  The send credit is used for the duration of the transfer, but
   is available again after completion of the transfer.
|  
|  In the following description, no  provision  is  made  for  cancelling
|  block  data  transfers.   An  implementation  must  provide  a  cancel
|  function.  Due to a restriction in the CI-780 port, it is not possible
|  to  withdraw  a  block transfer that has started without shutting down
|  the port to port VC.  This is not the intent  of  SCA  and  should  be
|  viewed as an implementation restriction.



   6.6.1  Map Buffer

   This function associates a name with a local named buffer:

   function MAP(
           {BLOCK_BUF: BUF_DESCR;}
           var NAME: LONG):
           FSTATUS;

   where:

       BLOCK_BUF       a descriptor of  a  named  buffer  (implementation
                       specific).

       NAME            the name of buffer returned by MAP.

       FSTATUS         SUCCESS if a name is associated;  FAIL otherwise.

   The  MAP  function  may  have   additional   implementation   specific
   parameters.   An  examples  is  a  connect  id that indicates that the
   connection block has additional information on how to map the  buffer.
   This  would  be needed if there were multiple ports on the system with
   different named buffer mapping techniques.
   SYSAP-SCS INTERFACE                                          Page 6-22


   6.6.2  Unmap Buffer

   This procedure disassociates a name from a named buffer:

   procedure UNMAP(
           NAME: LONG);

   where:

       NAME            the buffer name.



   6.6.3  Read

   This function requests transfer  of  data  from  a  destination  named
   buffer to a local block data buffer:

   function READ(
           CID: CONNECT_ID;
           THRSH: WORD;
           PTR: Q_BUF_PTR;
           var XID: WORD):
           FSTATUS;

   where:

       CID             the local connect id.

       THRSH           the transfer is started only if at least this many
                       send   flow  control  credits  will  remain.   The
                       minimum value of THRSH is 0.

       PTR             the address of the message buffer  containing  the
                       block data arguments.

       XID             the transaction id assigned by READ.

       FSTATUS         SUCCESS if the transfer is queued, FAIL if no flow
                       control  credit  is  available,  NOT_OPEN  if  the
                       connection has been closed.

   The block data arguments include:

       DATA_LENGTH     the number of bytes to be transferred.

       SEND_NAME       the name of the buffer  from  which  the  data  is
                       read.

       SEND_OFFSET     the starting byte in sending buffer.

       REC_NAME        the name of  the  buffer  to  which  the  data  is
                       written.
   SYSAP-SCS INTERFACE                                          Page 6-23


       REC_OFFSET      the starting byte in the receiving buffer.



   6.6.4  Read Poll

   This function checks if a read transfer has completed:

   function READ_POLL(
           CID: CONNECT_ID;
           var PTR: Q_BUF_PTR;
           var XID: WORD):
           FSTATUS;

   where:

       CID             local connect id.

       PTR             the address of  the  message  buffer  returned  by
                       READ_POLL.

       XID             the transaction id of the completed read.

       FSTATUS         SUCCESS if a read has completed;  FAIL otherwise.
   SYSAP-SCS INTERFACE                                          Page 6-24


   6.6.5  Write

   This function requests transfer of data from a local named buffer to a
   destination block data buffer:

   function WRITE(
           CID: CONNECT_ID;
           THRSH: WORD;
           PTR: Q_BUF_PTR;
           var XID: WORD):
           FSTATUS;

   where:

       CID             the local connect id.

       THRSH           the transfer is started only  if  this  many  send
                       flow  control  credits  will  remain.  The minimum
                       value of THRSH is 0.

       PTR             the address of the message buffer  containing  the
                       block data arguments.

       XID             the transaction id assigned by WRITE.

       FSTATUS         SUCCESS if the transfer is queued, FAIL if no flow
                       control  credit  is  available,  NOT_OPEN  if  the
                       connection has been closed.

   The block data arguments include:

       DATA_LENGTH     the number of bytes to be transferred.

       SEND_NAME       the name of the buffer  from  which  the  data  is
                       read.

       SEND_OFFSET     the starting byte in sending buffer.

       REC_NAME        the name of  the  buffer  to  which  the  data  is
                       written.

       REC_OFFSET      the starting byte in the receiving buffer.
   SYSAP-SCS INTERFACE                                          Page 6-25


   6.6.6  Write Poll

   This function checks if a write transfer has completed:

   function WRITE_POLL(
           CID: CONNECT_ID;
           var PTR: Q_BUF_PTR;
           var XID: WORD):
           FSTATUS;

   where:

       CID             the local connect id.

       PTR             the address of  the  message  buffer  returned  by
                       WRITE_POLL.

       XID             the transaction id of the completed write.

       FSTATUS         SUCCESS if a write has completed;  FAIL otherwise.











                                 CHAPTER 7

                             SCS-PPD INTERFACE



   The PPD interface is modelled as a set of function and procedure calls
   of  the  same  form  as  the  SCS  interface.   The  PPD  interface is
   essentially the CI port architecture, and the function  and  procedure
   names  (where  appropriate)  are  the  corresponding  CI  port command
   mnemonics.
|  
|  REQUEST ID REMOVED



   7.1  DATAGRAM SERVICE

   7.1.1  Send Datagram

   This procedure sends a datagram to a destination system:

   procedure SNDDG(
           DST: PB_INDEX;
           RET_FLAG: boolean;
           PTR: Q_BUF_PTR);

   where:

       DST             the destination port path block address.

       RET_FLAG        true if a  DGSNT  response  is  to  be  generated;
                       false otherwise.

       PTR             the address of the datagram buffer.
   SCS-PPD INTERFACE                                             Page 7-2


   7.1.2  Receive Datagram

   This procedure queues a datagram buffer to receive a datagram:

   procedure INSERT_DFREEQ(
           PTR: Q_BUF_PTR);

   where:

       PTR             the address of the datagram buffer.



   7.1.3  Return Datagram Buffer

   This function dequeues a datagram buffer:

   function REMOVE_DFREEQ(
           var PTR: Q_BUF_PTR):
           FSTATUS;

   where:

       PTR             the address of the datagram buffer.

       FSTATUS         SUCCESS if a buffer is dequeued;  FAIL otherwise.
   SCS-PPD INTERFACE                                             Page 7-3


   7.2  VIRTUAL CIRCUIT SERVICE

   7.2.1  Start Virtual Circuit

   This procedure requests the opening of a virtual circuit  between  the
   local and a destination system:

   procedure START_VC(
           DST: PB_INDEX;
           DATA: START_DATA;
           MPTR1: Q_BUF_PTR;
           MPTR2: Q_BUF_PTR;
           DPTR: Q_BUF_PTR);

   where:

       DST             the path block corresponding  to  the  destination
                       port.

       DATA            start data.  See Appendix G.

       MPTR1           the address of a message buffer.

       MPTR2           the address of a message buffer.

       DPTR            the address of a datagram buffer.
|  
|  Both message buffers, MPTR1 and MPTR2, are used to communicate between
|  SCS  instances  to establish and maintain connections.  One is used to
|  send control messages and  is  immediately  queued  as  a  receive  to
|  receive  the response.  One buffer is queued at all times as a receive
|  for commands from the other side and is queued as a transmit  for  the
|  response.   After  the response transmit it is queued as a receive for
|  the next incoming command.  There  is  at  most  one  outstanding  SCS
|  command  being  processed by the other side and one being processed by
|  this side.
|  
|  The datagram message buffer, DPTR, is used to start the port  to  port
|  virtual circuit and is used for both transmit and receive.
   SCS-PPD INTERFACE                                             Page 7-4


   7.3  MESSAGE SERVICE

   7.3.1  Send Message

   This procedure sends a message to a destination system:

   procedure SNDMSG(
           DST: PB_INDEX;
           RET_FLAG: boolean;
           PTR: Q_BUF_PTR);

   where:

       DST             the destination port path block address.

       RET_FLAG        true if a MSGSNT  response  is  to  be  generated;
                       false otherwise.

       PTR             the address of the message buffer.

   SNDMSG requires an open virtual circuit to exist to DST.



   7.3.2  Receive Message

   This procedure queues a message buffer to receive a message:

   procedure INSERT_MFREEQ(
           PTR: Q_BUF_PTR);

   where:

       PTR             the address of the message buffer.



   7.3.3  Return Message Buffer

   This function dequeues a message buffer:

   function REMOVE_MFREEQ(
           var PTR: Q_BUF_PTR):
           FSTATUS;

   where:

       PTR             the address of the message buffer.

       FSTATUS         SUCCESS if a buffer is dequeued;  FAIL otherwise.
   SCS-PPD INTERFACE                                             Page 7-5


   7.4  BLOCK DATA SERVICE

   7.4.1  Send Data

   This procedure sends data from a named buffer in the local system to a
   named buffer in the destination system:

   procedure SNDDAT(
           DST: PB_INDEX;
           PTR: Q_BUF_PTR);

   where:

       DST             the destination port path block address.

       PTR             the address of the message buffer  containing  the
                       block data arguments.

   The block data arguments include:

       DATA_LENGTH     the number of bytes to be transferred.

       SEND_NAME       the name of the buffer  from  which  the  data  is
                       read.

       SEND_OFFSET     the starting byte in sending buffer.

       REC_NAME        the name of  the  buffer  to  which  the  data  is
                       written.

       REC_OFFSET      the starting byte in the receiving buffer.

   SNDDAT requires a open virtual circuit to exist to DST.
   SCS-PPD INTERFACE                                             Page 7-6


   7.4.2  Request Data

   This procedure requests the sending of data from a named buffer  in  a
   destination system to a named buffer in the local system:

   procedure REQDAT(
           DST: PB_INDEX;
           PTR: Q_BUF_PTR);

   where:

       DST             the destination port path block address.

       PTR             the address of the message buffer  containing  the
                       block data arguments.

   The block data arguments include:

       DATA_LENGTH     the number of bytes to be transferred.

       SEND_NAME       the name of the buffer  from  which  the  data  is
                       read.

       SEND_OFFSET     the starting byte in sending buffer.

       REC_NAME        the name of  the  buffer  to  which  the  data  is
                       written.

       REC_OFFSET      the starting byte in the receiving buffer.

   REQDAT requires a open virtual circuit to exist to DST.
   SCS-PPD INTERFACE                                             Page 7-7


   7.5  RESPONSES

   This function checks if a message has been sent, a  message  has  been
   received, a datagram has been sent, a datagram has been received, sent
   data has been confirmed, requested data has been received,  or  an  id
   has been received.

   function RSP_POLL(
           var RSP: RSP_TYPE;
           var DST: PB_INDEX;
           var PTR: Q_BUF_PTR):
           FSTATUS;

   where:

       RSP             the response type:  (MSGSNT, DGSNT, MSGREC, DGREC,
                       CNFREC, DATREC, IDREC, MCNFREC, MDATREC).

       DST             the destination port path block address.

       PTR             the  address  of  a  queued  buffer  returned   by
                       RSP_POLL.   The  buffer  is  a messsage buffer for
                       MSGSNT, MSGREC, CNFREC, and DATREC and a  datagram
                       buffer otherwise.

       FSTATUS         SUCCESS if a response is present;  FAIL otherwise.











                                 CHAPTER 8

                         SCS MESSAGES AND DATAGRAMS



   8.1  TYPES

   SCS messages and datagrams  are  of  two  basic  types:   control  and
   application.   Control  messages  carry  information  between peer SCS
   processes while application messages and datagrams  carry  information
   between  peer  SYSAP processes.  Control messages are of two subtypes:
   request and response.  A request message from SCS  process  X  to  SCS
   process  Y is followed by a response message from SCS process Y to SCS
   process X that acknowledges the previous request and  enables  sending
   the next request.
   SCS MESSAGES AND DATAGRAMS                                    Page 8-2


   The general format of an SCS message or datagram is:



                    3               1
                    1               5             0
                   +---------------+---------------+
                   |    CREDIT     |   SCS_TYPE    |
                   +---------------+---------------+
                   |         REC_CONNECT_ID        |
                   +-------------------------------+
                   |         SEND_CONNECT_ID       |
                   +-------------------------------+
                   |                               |
                   =        SCS_TYPE_SPECIFIC      =
                   |                               |
                   +-------------------------------+



   where:
                       SCS_TYPE the message or datagram type.

       CREDIT          the flow control credit.

       REC_CONNECT_ID  the connect id of the process  that  is  receiving
                       the  message  or datagram or on whose behalf it is
                       being received.

       SEND_CONNECT_ID the connect id of the process that is sending  the
                       messsage  or  datagram  or  on  whose behalf it is
                       being sent.

       SCS_TYPE_SPECIFIC depends on SCS_TYPE.
   SCS MESSAGES AND DATAGRAMS                                    Page 8-3


   8.2  SCS CONTROL MESSAGES

   8.2.1  Connect Request

   The CONNECT_REQ request message requests a connection.  The format  of
   CONNECT_REQ is:


                    3               1
                    1               5             0
                   +---------------+---------------+
                   |      CREDIT   |    SCS_TYPE   |
                   +---------------+---------------+
                   |               0               |
                   +---------------+---------------+
                   |        SEND_CONNECT_ID        |
                   +---------------+---------------+
                   |       0       |  MIN_CREDIT   |
                   +---------------+---------------+
                   |                               |
                   =           REC_PROC            =
                   |                               |
                   +-------------------------------+
                   |                               |
                   =           SEND_PROC           =
                   |                               |
                   +-------------------------------+
                   |                               |
                   =           SEND_DATA           =
                   |                               |
                   +-------------------------------+



   where:

       SCS_TYPE         CONNECT_REQ.

       CREDIT          the  initial  number  of  flow   control   credits
                       extended.  CREDIT must be non-negative.

       SEND_CONNECT_ID the connect id of the process sending the  connect
                       request.

       MIN_CREDIT      the minimum number of flow control credits needed.
                       MIN_CREDIT must be non-negative.

       REC_PROC        the name of the process to receive the request.

       SEND_PROC       the name of the process sending the request.

       SEND_DATA       connect data from the sending process.
   SCS MESSAGES AND DATAGRAMS                                    Page 8-4


   8.2.2  Connect Response

   The CONNECT_RSP response message acknowledges the CONNECT_REQ  message
   and   enables  sending  the  next  request  message.   The  format  of
   CONNECT_RSP is:


                    3               1
                    1               5             0
                   +---------------+---------------+
                   |       0       |   SCS_TYPE    |
                   +---------------+---------------+
                   |         REC_CONNECT_ID        |
                   +-------------------------------+
                   |         SEND_CONNECT_ID       |
                   +---------------+---------------+
                   |     STATUS    |       0       |
                   +---------------+---------------+



   where:

       SCS_TYPE        CONNECT_RSP.

       REC_CONNECT_ID  the connect id of the process sending the  connect
                       request.

       SEND_CONNECT_ID the connect id of the process  responding  to  the
                       connect request.
|  
|      STATUS          CONNECTED  if  the  connect  request  was  queued,
|                      NO_MATCH or NO_RESOURCES otherwise.
   SCS MESSAGES AND DATAGRAMS                                    Page 8-5


   8.2.3  Accept Request

   The ACCEPT_REQ request message  accepts  a  connection  request.   The
   format of ACCEPT_REQ is:


                    3               1
                    1               5             0        
                   +---------------+---------------+
                   |     CREDIT    |    SCS_TYPE   |
                   +---------------+---------------+
                   |         REC_CONNECT_ID        |
                   +-------------------------------+
                   |         SEND_CONNECT_ID       |
                   +---------------+---------------+
                   |       0       |   MIN_CREDIT  |
                   +---------------+---------------+
                   |                               |
                   =            REC_PROC           =
                   |                               |
                   +-------------------------------+
                   |                               |
                   =            SEND_PROC          =
                   |                               |
                   +-------------------------------+
                   |                               |
                   =            SEND_DATA          =
                   |                               |
                   +-------------------------------+




   where:

       SCS_TYPE        ACCEPT_REQ.

       CREDIT          the initial number of  credits  extended.   CREDIT
                       must be non-negative.

       REC_CONNECT_ID  the  connect  id  of  the  process  receiving  the
                       request.

       SEND_CONNECT_ID the connect id of the process sending the request.

       MIN_CREDIT      the minimum number of flow control credits needed.
                       MIN_CREDIT must be non-negative.

       REC_PROC        the name of the process receiving the request.

       SEND_PROC       the name of the process sending the request.

       SEND_DATA       connect data from the sending process.
   SCS MESSAGES AND DATAGRAMS                                    Page 8-6


   8.2.4  Accept Response

   The ACCEPT_RSP response message acknowledges  the  ACCEPT_REQ  message
   and   enables  sending  the  next  request  message.   The  format  of
   ACCEPT_RSP response is:
|  
|  
|                   3               1
|                   1               5             0
|                  +---------------+---------------+
|                  |       0       |   SCS_TYPE    |
|                  +---------------+---------------+
|                  |         REC_CONNECT_ID        |
|                  +-------------------------------+
|                  |         SEND_CONNECT_ID       |
|                  +-------------------------------+
|                  |   REASON      |       0       |
|                  +-------------------------------+
|  

   where:

       SCS_TYPE        ACCEPT_RSP.

       REC_CONNECT_ID  same as SEND_CONNECT_ID in the ACCEPT_REQ message.

       SEND_CONNECT_ID same as REC_CONNECT_ID in the ACCEPT_REQ  message.
|                      REASON  reason  for  failure to accept connection.
|                      NO_RESOURCES  and   DISCONNECTED   are   possible.
|                      CONNECTED  means  that  the  ACCEPT_REQ  is  being
|                      processed.
   SCS MESSAGES AND DATAGRAMS                                    Page 8-7


   8.2.5  Reject Request

   The REJECT_REQ request message  rejects  a  connection  request.   The
   format of REJECT_REQ is:
|  
|  
|                   3               1
|                   1               5             0
|                  +---------------+---------------+
|                  |       0       |   SCS_TYPE    |
|                  +---------------+---------------+
|                  |         REC_CONNECT_ID        |
|                  +-------------------------------+
|                  |         SEND_CONNECT_ID       |
|                  +---------------+---------------+
|                  |    REASON     |       0       |
|                  +---------------+---------------+
|                  
|  

   where:

       SCS_TYPE        REJECT_REQ.

       REC_CONNECT_ID  the connect id of process receiving the request.

       SEND_CONNECT_ID the connect id of the process sending the request.
|  
|      REASON          the reason for rejection.  See Appendix E.
   SCS MESSAGES AND DATAGRAMS                                    Page 8-8


   8.2.6  Reject Response

   The REJECT_RSP response message acknowledges  the  REJECT_REQ  message
   and   enables  sending  the  next  request  message.   The  format  of
   REJECT_RSP is:

                    3               1
                    1               5             0
                   +---------------+---------------+
                   |       0       |   SCS_TYPE    |
                   +---------------+---------------+
                   |         REC_CONNECT_ID        |
                   +-------------------------------+
                   |         SEND_CONNECT_ID       |
                   +-------------------------------+



   where:

       SCS_TYPE        REJECT_RSP.

       REC_CONNECT_ID  same as SEND_CONNECT_ID in the REJECT_REQ message.

       SEND_CONNECT_ID same as REC_CONNECT_ID in the REJECT_REQ message.
   SCS MESSAGES AND DATAGRAMS                                    Page 8-9


   8.2.7  Disconnect Request

   The DISCONNECT_REQ request message requests disconnection.  The format
   of DISCONNECT_REQ is:
|  
|  
|                   3               1
|                   1               5             0                
|                  +---------------+---------------+
|                  |     0         |    SCS_TYPE   |
|                  +---------------+---------------+
|                  |         REC_CONNECT_ID        |
|                  +-------------------------------+
|                  |         SEND_CONNECT_ID       |
|                  +---------------+---------------+
|                  |     REASON    |       0       |
|                  +---------------+---------------+
|  
|  

   where:

       SCS_TYPE        DISCONNECT_REQ.

       REC_CONNECT_ID  the  connect  id  of  the  process  receiving  the
                       request.

       SEND_CONNECT_ID the connect id of the process sending the request.
|  
|      REASON          the reason for disconnection.  See Appendix E.
   SCS MESSAGES AND DATAGRAMS                                   Page 8-10


   8.2.8  Disconnect Response

   The DISCONNECT_RSP response message  acknowledges  the  DISCONNECT_REQ
   message  and  enables sending the next request message.  The format of
   DISCONNECT_RSP is:


                    3               1
                    1               5             0
                   +---------------+---------------+
                   |     0         |    SCS_TYPE   |
                   +---------------+---------------+
                   |         REC_CONNECT_ID        |
                   +-------------------------------+
                   |         SEND_CONNECT_ID       |
                   +-------------------------------+



   where:

       SCS_TYPE        DISCONNECT_RSP.

       REC_CONNECT_ID  same  as  SEND_CONNECT_ID  in  the  DISCONNECT_REQ
                       message.

       SEND_CONNECT_ID same  as  REC_CONNECT_ID  in  the   DISCONNECT_REQ
                       message.
   SCS MESSAGES AND DATAGRAMS                                   Page 8-11


   8.2.9  Credit Request

   The CREDIT_REQ request message carries credits for flow control.   The
   format of CREDIT_REQ is:


                    3               1
                    1               5             0
                   +---------------+---------------+
                   |     CREDIT    |    SCS_TYPE   |
                   +---------------+---------------+
                   |         REC_CONNECT_ID        |                 
                   +-------------------------------+
                   |        SEND_CONNECT_ID        |
                   +-------------------------------+


   where:

       SCS_TYPE        CREDIT_REQ.

       CREDIT          a signed  integer  giving,  if  non-negative,  the
                       number   of   additional   credits  extended;   if
                       negative, the number of credits  requested  to  be
                       returned.

       REC_CONNECT_ID  the  connect  id  of  the  process  receiving  the
                       credits.

       SEND_CONNECT_ID the connect id of the process sending the credits.
   SCS MESSAGES AND DATAGRAMS                                   Page 8-12


   8.2.10  Credit Response

   The CREDIT_RSP response message acknowledges  the  CREDIT_REQ  message
   and  enables  sending  of  the  next  request  message.  The format of
   CREDIT_RSP is:


                    3               1
                    1               5             0
                   +---------------+---------------+
                   |     CREDIT    |    SCS_TYPE   |
                   +---------------+---------------+
                   |         REC_CONNECT_ID        |
                   +-------------------------------+
                   |         SEND_CONNECT_ID       |
                   +-------------------------------+


   where:

       SCS_TYPE        CREDIT_RSP.

       CREDIT          if the CREDIT field in the CREDIT_REQ message  was
                       non-negative, then the value of CREDIT;  otherwise
                       the negative of the  number  of  credits  actually
                       returned.

       REC_CONNECT_ID  same as SEND_CONNECT_ID in the CREDIT_REQ message.

       SEND_CONNECT_ID  same as REC_CONNECT_ID in the CREDIT_REQ message.
   SCS MESSAGES AND DATAGRAMS                                   Page 8-13


   8.3  APPLICATION MESSAGE

   The APPL_MSG application message carries a SYSAP layer  message.   The
   format of APPL_MSG is:


                    3               1
                    1               5             0
                   +---------------+---------------+
                   |     CREDIT    |    SCS_TYPE   |
                   +---------------+---------------+
                   |         REC_CONNECT_ID        |
                   +-------------------------------+
                   |         SEND_CONNECT_ID       |
                   +-------------------------------+
                   |                               |
                   =         SYSAP_MSG_TEXT        =
                   |                               |
                   +-------------------------------+



   where:

       SCS_TYPE        APPL_MSG.

       CREDIT          the number of flow control credits being extended.
                       CREDIT must be non-negative.

       REC_CONNECT_ID  the  connect  id  of  the  process  receiving  the
                       message.

       SEND_CONNECT_ID the connect id of the process sending the message.

       SYSAP_MSG_TEXT  the SYSAP layer message text.
   SCS MESSAGES AND DATAGRAMS                                   Page 8-14


   8.4  APPLICATION DATAGRAM

   The APPL_DG datagram carries a SYSAP layer datagram.   The  format  of
   APPL_DG is:


                    3               1
                    1               5             0
                   +---------------+---------------+
                   |     0         |    SCS_TYPE   |
                   +---------------+---------------+
                   |         REC_CONNECT_ID        |
                   +-------------------------------+
                   |         SEND_CONNECT_ID       |
                   +-------------------------------+
                   |                               |
                   =          SYSAP_DG_TEXT        =
                   |                               |
                   +-------------------------------+



   where:

       SCS_TYPE        APPL_DG.

       REC_CONNECT_ID  the  connect  id  of  the  process  receiving  the
                       datagram.

       SEND_CONNECT_ID the  connect  id  of  the  process   sending   the
                       datagram.

       SYSAP_DG_TEXT   the SYSAP layer datagram text.











                                 CHAPTER 9

                               SCS OPERATION



   9.1  RELATION TO PPD VIRTUAL CIRCUIT

   All SCS messages flow over a port-to-port virtual circuit provided  by
   the  PPD  layer.   All  SYSAP-SCS  connections are multiplexed on this
   virtual circuit.  Closing the PPD virtual  circuit  by  either  system
   requires  closing  all  SCS  connections.   The SYSAPs are notified of
   connection close by calling the STATE_POLL function.
|  
|  
|  
|  9.2  SCS PROTOCOL VERSION RESOLUTION
|  
|  The start data contains a protocol version number.   This  allows  SCA
|  version  upgrade  in  the future.  The first version of SCA is version
|  zero.
|  
|  The version field is compared in such a way to allow newer versions to
|  be  written  to  talk  down  to  older  versions  as  well as to their
|  contemporary versions.  This is done by leaving the decision of making
|  the start_vc to the higher numbered version.  The lower number version
|  always accepts starts from the same or higher versions.  Higher number
|  versions  always  accept  equal  version starts and may as well accept
|  starts from lower numbered versions if the higher version  is  willing
|  to  talk down to the older version.  Talking down is an implementation
|  decision.  Accepting connects from higher versions is required.



   9.3  SCS CONTROL MESSAGE FLOW CONTROL

   When a port-to-port virtual circuit is opened, each system supplies  2
   message  buffers.  The first, termed the local message buffer, is used
   to send SCS  control  request  messages  and  receive  the  associated
   response control message.  This buffer is initially queued on the path
   block, dequeued to send a request  message,  and  requeued  after  the
   response  is  received.   The  second,  termed the destination message
   buffer, is used to receive SCS control request messages and  send  the
   associated  response control message.  This buffer is initially queued
   on the PPD MFREEQ, dequeued when a SCS control  request  is  received,
   and requeued after the response is sent.  At most 1 request message on
   SCS OPERATION                                                 Page 9-2


   each direction of the virtual circuit can be outstanding  at  a  time.
   Only  when  the  destination  of  the request responds with a response
   message can another request message be sent.
|  
|  These are some descriptions of the credit variables used  in  the  SCS
|  operation description which will help to understand credit management.
|  
|      THRSH           this value is the name of a call  parameter  which
|                      corresponds to MIN_SEND_CREDIT.  When a connection
|                      is    established,    this    parameter    becomes
|                      MIN_SEND_CREDIT.  In other calls when a circuit is
|                      running,  it  is  compared  to   SEND_CREDIT   and
|                      SEND_CREDIT   must  be  at  least  this  value  to
|                      succeed.
|  
|      SEND_CREDIT     credits extended  to  this  side  by  partner  for
|                      transmit  buffers.   Or  the  number  of  receives
|                      queued by the partner.
|  
|      MIN_SEND_CREDIT minimum number of credits a SYSAP expects to  have
|                      to  transmit to the other side.  In other words, a
|                      SYSAP expects to have this many buffers queued  as
|                      receives  by  its partner.  This is a constant for
|                      each connection and is established by the  partner
|                      SYSAP.
|  
|      REC_CREDITS     credits this side has extended to the  other  side
|                      to transmit.  The number of receives queued here.
|  
|      MIN_REC_CREDIT  minimum number of credits the other  side  expects
|                      to  have  to  transmit.   Or the minimum number of
|                      receives we will keep  queued  here.   This  is  a
|                      constant for each connection and is established by
|                      the SYSAP on this side.
|  
|      PEND_REC_CREDIT accumulated  number  of  credits  that  have  been
|                      queued  as receives here but have not been sent to
|                      the partner in a credit message.
|  
|      REQ_CREDIT      the number of credits sent in the last  CREDIT_REQ
|                      message.   This  cell  is used for the duration of
|                      the credit_req, _rsp pair to  enable  the  correct
|                      setting of RET_NULL.
|  
|      RET_CREDIT      number  of  credits  actually  obtained  from  the
|                      partner    or   deducted   on   this   side   from
|                      PEND_REC_CREDIT by cancel credit calls.   This  is
|                      the  count  of buffers that can be returned to the
|                      SYSAP caller requesting to cancel receives.
|  
|      RET_NULL        the number of cancel credit requests for which  no
|                      buffer  is  available  because  they have not been
|                      returned in a credit_rsp message  from  the  other
|                      side.
   SCS OPERATION                                                 Page 9-3


   9.4  SCS OPERATION DESCRIPTION

   The SCS process is described as expansions of the SCS interface  calls
   and as 2 subprocesses, SCS_SEND and SCS_REC.

   SCS_SEND sends SCS control request messages.  An  SCS  interface  call
   needing  the  SCS  request  message  service  queues  the  appropriate
   connection block on the appropriate path block.  The  path  block,  if
   not  already queued, is placed on the SCS_SEND_Q work queue.  SCS_SEND
   removes the path block from the work queue and sends a request message
   (using   the   local   message   buffer).   The  following  shows  the
   relationship of the data structures used by SCS_SEND:


                                           +-------+       
                                           |       |-----> next system
                                           |system |          block
                                           | block |
                                           |       |
                                           +-------+
                                               ^
                                               |
                                               |
                                               V
           +-------+       +-------+       +-------+       +-------+
   <-------|       |<------|       |<------|       |------>|       |
           |connect|       |connect|       | path  |       | local |
           | block |       | block |       | block |       |msg buf|
           |       |       |       |       |       |       |       |
           +-------+       +-------+       +-------+       +-------+
                                               |
                                               |
                                               |
                                               V
                                           next path
                                             block
   SCS OPERATION                                                 Page 9-4


   SCS_REC receives all incoming messages  and  datagrams  and  does  the
   following:

        1.  Processes and delivers SYSAP messages and datagrams;  DATREC;
            MDATREC;  DATCNF;  and MDATCNF responses.

        2.  Processes  SCS  request  control  messages  and   sends   the
            appropriate response.

        3.  Processes SCS response control  messages,  queues  the  local
            message buffer on the path block, and if the CB_Q in the path
            block is non-empty, queues the path block on  the  SCS_SEND_Q
            work queue.

        4.  Delivers IDREC responses.  If  the  IDREC  is  from  a  'new'
            system, calls START_VC to start the PPD virtual circuit.


   The focal points of SCS operation are the path and  connection  blocks
   that  are  modified by the SCS interface calls, SCS_SEND, and SCS_REC.
   It is assumed that modifications to a path and  connection  block  are
   synchronized  by some standard technique:  e.g.  all the modifications
   are done at the same IPL.
   SCS OPERATION                                                 Page 9-5


   9.5  TYPE, VARIABLE , FUNCTION, AND PROCEDURE DEFINITIONS

   The  following  PASCAL  definitions  apply  to   the   SCS   operation
   description.

   type
           SB = record { system block definition }
                   SB$NEXT_SB: SB_PTR;             { address of next SB }
                   SB$FIRST_PB: PB_INDEX;          { array index of first path block }
                   SB$DST_PORT_COUNT: WORD;        { number of interconnects to dst }
                   SB$DST_SYS: SYSTEM;             { destination system address }
                   SB$DST_MAX_DG: WORD;            { max. datagram size allowed }
                   SB$DST_MAX_MSG: WORD;           { max. message size allowed }
                   SB$DST_SW_TYPE: LONG;           { software type }
                   SB$DST_SW_VERSION: LONG;        { software version }
                   SB$DST_SW_INCAR: QUAD;          { software incarnation number }
                   SB$DST_HW_TYPE: LONG;           { hardware type }
                   SB$DST_HW_VERSION: SEPTA;       { hardware version }
                   SB$DST_NODE_NAME: QUAD          { ASCII node name }
                   end;


           PB = record { path block definition }
                   PB$NEXT_PB: PB_INDEX;           { index of next path block to system }
                   PB$SB: SB_INDEX;                { index of system block for this PB }
                   PB$DST_VC_STATE: VC_STATE;      { state of port-to-port virtual circuit }
                   PB$DST_PORT: PORT;              { destination port address }
                   PB$DG_Q: Q_BUF_PTR;             { datagram return queue }
                   PB$MSG_PTR: Q_BUF_PTR;          { scs control message pointer }
                   PB$CB_Q: CB_PTR;                { queue of CBs requiring SCS service }
                   PB$DST_PORT_CHAR: PORT_CHAR     { characteristics of remote port }
                   end;
                   

           B_STATE = ( { Connection block state for CB$BLOCK_STATE.  This field is used as
                         an opcode to SCS_SEND, which examines it to determine what type of 
                         control message to send. }
                   FREE,                           { connection block is unused }
                   ALLOC,                          { connection block is allocated }
                   CONNECT_PEND,                   { send a connect message }
                   ACCEPT_PEND,                    { send an accept message }
                   REJECT_PEND,                    { send a reject message }
                   CREDIT_PEND,                    { send a credit message }
                   DISCONNECT_PEND                 { send a disconnect message }
                   );

           
           CB = record { connection block }
                   CB$NEXT_CB: CB_PTR;             { address of next CB in queue }
                   CB$CONNECT_STATE: C_STATE;      { state of process-to-process connection }
                   CB$BLOCK_STATE: B_STATE;        { state of this connection block }
                   CB$SRC_CONNECT_ID: CONNECT_ID;  { id of local connection block }
                   CB$DST_CONNECT_ID: CONNECT_ID;  { id of remote connection block }
                   CB$SRC_PROC_NAME: PROC_NAME;    { local process name }
                   CB$DST_PROC_NAME: PROC_NAME;    { remote process name }
   SCS OPERATION                                                 Page 9-6


                   CB$CONNECT_DATA: C_DATA;        { connection data }
                   CB$SRC_REASON: WORD;            { local reason for reject or disconnect }
                   CB$DST_REASON: WORD;            { remote reason for reject or disconnect }
                   CB$SEND_CREDIT: WORD;           { number of available send credits }
                   CB$MIN_SEND_CREDIT: WORD;       { protocol threshold }
                   CB$REC_CREDIT: WORD;            { max. unused credits held by remote side }
                   CB$MIN_REC_CREDIT: WORD;        { min. send credits needed by remote side }
                   CB$PEND_REC_CREDIT: WORD;       { receive buffers queued, or cancels pending }
                   CB$REQ_CREDIT: WORD;            { credits sent but not acknowledged }
                   CB$RET_CREDIT: WORD;            { credits actually returned from remote side }
                   CB$RET_NULL: WORD;              { credits requested but not returned from remote side }
                   CB$DG_REC: WORD;                { number of datagram buffers queued }
                   CB$RESERVED: WORD;              { unused }
                   CB$DST_SB: SB_INDEX;            { system block for destination system }
                   CB$DST_PB: PB_INDEX;            { path block for interconnect to destination }
                   CB$DG_Q: Q_BUF_PTR;             { queue of DGREC responses }
                   CB$MSG_Q: Q_BUF_PTR;            { queue of MSGREC responses }
                   CB$READ_Q: Q_BUF_PTR;           { queue of DATREC responses }
                   CB$WRITE_Q: Q_BUF_PTR;          { queue of CNFREC responses }
                   CB$DG_RET_Q: Q_BUF_PTR;         { queue of DGSNT responses }
                   CB$MSG_RET_Q: Q_BUF_PTR         { queue of MSGSNT responses }
                   end;

           CB_Q_STATE = (FILLED,WAS_EMPTY,NOW_EMPTY); { connection block queue state }

           RSP_TYPE = (DGREC,DGSNT,MSGREC,MSGSNT,DATREC,CNFREC,
                           IDREC,MDATREC,MCNFREC); { PPD response type }


           START_DATA = packed array [1..36] of BYTE;

   var     CBA: array [1..MAX_CB] of CB;           { connection blocks }

           SBA: array [1..MAX_SB] of SB;           { system blocks }

           PBA: array [1..MAX_PB] of PB;           { path blocks }

           CUR_SB: WORD;                           { the highest current system list entry }

           CUR_PB: WORD;                           { the highest current path list entry }

           SCS_SEND_Q: SB_PTR;                     { SCS_SEND work queue }

   function ALLOC_CB(
           var CID:CONNECT_ID):
           boolean;
           
           begin

           { allocate connect block, initialize to zero,
           set CB$NEXT_CB to point to itself,
           set CB$BLOCK_STATE to ALLOC, and return CID:
           return true if block allocated; false otherwise }

           end;{ALLOC_CB}
   SCS OPERATION                                                 Page 9-7



   function CB_CLOSED( { test connection state }
           CID: CONNECT_ID):
           boolean;

           begin

           {return TRUE if connection is closed,
           return FALSE otherwise }

           end;{CB_CLOSED}

   procedure CHOOSE_PATH( { select path to system }
           ENTRY: SB_INDEX;
           var PATH: PB_INDEX);

           begin

           { select path over which connection to
           specified system is to be attempted. }

           end;{CHOOSE_PATH}

   function PBPTR_TO_PBINDEX(  { change pointer to index }
           PTR: PB_PTR): PB_INDEX;

           begin

           { calculate index from address pointer }

           end;{PBPTR_TO_PBINDEX}

   function NEXT_XID:
           WORD;

           begin

           { assign a new transaction number }

           end;{NEXT_XID}

   function CONNECT_MATCH(
           PTR: Q_BUF_PTR;
           var CNCT_INDEX: WORD):
           boolean;

           begin

           { search for connect block in LISTENING connect
           state which matches the connect request: set CB$DST_SB, CB$DST_PB }

           end;{CONNECT_MATCH}

   function INSERT_CB_Q(
           Q: CB_PTR;
   SCS OPERATION                                                 Page 9-8


           PTR: CB_PTR):
           CB_Q_STATE;

           begin

           { insert entry whose address is PTR in queue Q:
           return WAS_EMPTY if queue was previously empty;
           FILLED otherwise }

           end;

   function REMOVE_CB_Q(
           Q: CB_PTR;
           var PTR: CB_PTR):
           CB_Q_STATE;

           begin

           { remove entry from queue Q and return address in
           PTR : return NOW_EMPTY if queue is now empty;
           FILLED otherwise }

           end;

   procedure INSERT_SCS_Q(
           INDEX: PB_INDEX);
           
           begin

           { insert path block identified by INDEX
           on the SCS_SEND_Q work queue }

           end;{INSERT_SCS_Q}
           
   function REMOVE_SCS_Q(
           var PTR: PB_PTR):
           boolean;
           
           begin

           { remove an entry from the SCS_SEND_Q work queue and return
           its address in PTR: return true if entry removed;
           false otherwise }

           end;{REMOVE_SCS_Q}
           
   procedure INSERT(
           Q: Q_BUF_PTR;
           PTR: Q_BUF_PTR);

           begin

           { insert entry whose address is PTR in queue Q }

           end;{INSERT}
   SCS OPERATION                                                 Page 9-9



   function REMOVE(
           Q: Q_BUF_PTR;
           var PTR: Q_BUF_PTR):
           boolean;

           begin

           { remove entry from queue Q and return address of
           entry in PTR: return true if entry removed;
           false otherwise }

           end;{REMOVE}
           {SCSDEF}
   SCS OPERATION                                                Page 9-10


   9.6  CONFIGURATION SERVICE

   9.6.1  System Block

   The system list is a data structure built and maintained  by  the  PPD
   layer  and  used  by  the  SCS  layer.  An entry on the system list is
   termed  a  system  block.   A  representative  system  block  has  the
   following format:

                    3
                    1                             0
                   +-------------------------------+
                   |            NEXT_SB            |
                   +---------------+---------------+
                   |DST_PORT_COUNT |FIRST_PB_INDEX |
                   +-------------------------------+               
                   |               |   RESERVED    |
                   |               +---------------+
                   |           DST_SYS             |
                   +---------------+---------------+
                   | DST_MAX_MSG   | DST_MAX_DG    |
                   +---------------+---------------+
                   |         DST_SW_TYPE           |
                   +-------------------------------+
                   |        DST_SW_VERSION         |
                   +-------------------------------+
                   |       DST_SW_INCARNATION      |
                   |                               |
                   +-------------------------------+
                   |         DST_HW_TYPE           |
                   +-------------------------------+
                   |                               |
                   =        DST_HW_VERSION         =
                   |                               |
                   +-------------------------------+
                   |           NODE_NAME           |
                   |                               |
                   +-------------------------------+


   where:

       NEXT_SB         the address of the next system block  on  the  the
                       SCS_SEND_Q.

       FIRST_PB_INDEX  path block index of the first path block for  this
                       system.

       DST_PORT_COUNT  number of paths to the destination system.

       RESERVED        reserved word.

       DST_SYS         the destination system.
   SCS OPERATION                                                Page 9-11


       DST_MAX_DG      the maximum datagram size (in bytes) supported  by
                       the system.

       DST_MAX_MSG     the maximum message size (in bytes)  supported  by
                       the system.

       DST_SW_TYPE     the 4-character ASCII type of the software in  the
                       system.

       DST_SW_VERSION  the  4-character  ASCII  version  number  of   the
                       software in the system.

       DST_SW_INCARNATION  (8  bytes)  the  incarnation  number  of   the
                       software in the system.

       DST_HW_TYPE     the type of system hardware.
|  
|      DST_HW_VERSION  (12  bytes)  the  version  number  of  the  system
|                      hardware.

       NODE_NAME       (8 bytes) the ASCII node name of the system.
   SCS OPERATION                                                Page 9-12


   9.6.2  Path Block

   The path block is a data  structure  containing  information  about  a
   single   system-to-system   path.    That  is,  it  describes  one  of
   potentially several ports to a destination system.

                    3
                    1                              0
                   +-------------------------------+
                   |      SB       |   NEXT_PB     |
                   +-------------------------------+
                   |               | DST_VC_STATE  |
                   |               +---------------|
                   |          DST_PORT             |
                   +-------------------------------+
                   |              DG_Q             |
                   +-------------------------------+
                   |            MSG_PTR            |
                   +-------------------------------+
                   |             CB_Q              |
                   +---------------+---------------+
                   |                               |
                   =         DST_PORT_CHAR         =
                   |                               |
                   +-------------------------------+


       NEXT_PB         path  block  index  of  the  next  path   to   the
                       destination system.

       SB              system block index of the system  block  to  which
                       this path block is queued.

       DST_VC_STATE    the  state  of  the   virtual   circuit   to   the
                       destination port.

       DST_PORT        the destination system port address.

       DG_Q            the  datagram   return   queue   for   maintenance
                       operations.

       MSG_PTR         the address of the local message buffer associated
                       with the port-to-port virtual circuit.

       CB_Q            the queue  of  connection  blocks  of  connections
                       requiring SCS control message service.

       DST_PORT_CHAR   the characteristics of the destination port.
   SCS OPERATION                                                Page 9-13


   9.6.3  Configuration Services


|  REQ_ID REMOVED

   function CONFIG_SYS(
           ENTRY: SB_INDEX;
           var FIRST_PB: PB_INDEX;
           var SYS: SYSTEM;
           var MAX_DG: WORD;
           var MAX_MSG: WORD;
           var SW_TYPE: LONG;
           var SW_VERSION: LONG;
           var SW_INCARNATION: QUAD;
           var HW_TYPE: LONG;
           var HW_VERSION: SEPTA;
           var NODE_NAME: QUAD;
           var PORT_COUNT: WORD):
           FSTATUS;

           { Return information about destination SYSTEM from the
           specified System Block. }

           begin
           if ENTRY <= CUR_SB then with SBA[ENTRY] do
                   begin
                   FIRST_PB:=SB$FIRST_PB;
                   SYS:=SB$DST_SYS;
                   MAX_DG:=SB$DST_MAX_DG;
                   MAX_MSG:=SB$DST_MAX_MSG;
                   SW_TYPE:=SB$DST_SW_TYPE;
                   SW_VERSION:=SB$DST_SW_VERSION;
                   SW_INCARNATION:=SB$DST_SW_INCAR;
                   HW_TYPE:=SB$DST_HW_TYPE;
                   HW_VERSION:=SB$DST_HW_VERSION;
                   NODE_NAME:=SB$DST_NODE_NAME;
                   PORT_COUNT:=SB$DST_PORT_COUNT;
                   CONFIG_SYS:=SUCCESS
                   end
           else CONFIG_SYS:=FAIL
           end;{CONFIG_SYS}


   function CONFIG_PATH(
           ENTRY: PB_INDEX;
           var STATE: VC_STATE;
           var PRT: PORT;
           var NEXT_PB: PB_INDEX;
           var SB: SB_INDEX;
           var CHAR: PORT_CHAR):
           FSTATUS;

           { Return information about the specified INTERCONNECT
           from the specified Path Block. }
   SCS OPERATION                                                Page 9-14


           begin
           if ENTRY <= CUR_PB then with PBA[ENTRY] do
                   begin
                   STATE:=PB$DST_VC_STATE;
                   PRT:=PB$DST_PORT;
                   NEXT_PB:=PB$NEXT_PB;
                   SB:=PB$SB;
                   CHAR:=PB$DST_PORT_CHAR;
                   CONFIG_PATH:=SUCCESS
                   end
           else CONFIG_PATH:=FAIL
           end;{CONFIG_PATH}
   SCS OPERATION                                                Page 9-15


   9.7  CONNECTION MANAGEMENT SERVICE

   9.7.1  Connection Block

   A representative connection block has the following format:
   SCS OPERATION                                                Page 9-16



                    3
                    1                             0
                   +-------------------------------+
                   |            NEXT_CB            |
                   +---------------+---------------+
                   |  BLOCK_STATE  | CONNECT_STATE |
                   +---------------+---------------+
                   |         SRC_CONNECT_ID        |
                   +-------------------------------+
                   |         DST_CONNECT_ID        |
                   +-------------------------------+
                   |                               |
                   =         SRC_PROC_NAME         =
                   |                               |
                   +-------------------------------+
                   |                               |
                   =         DST_PROC_NAME         =
                   |                               |
                   +-------------------------------+
                   |                               |
                   =          CONNECT-DATA         =
                   |                               |
                   +---------------+---------------+
                   |   DST_REASON  |  SRC_REASON   |
                   +---------------+---------------+
                   |MIN_SEND_CREDIT|  SEND_CREDIT  |
                   +---------------+---------------+
                   |MIN_REC_CREDIT |  REC_CREDIT   |
                   +---------------+---------------+
                   |  REQ_CREDIT   |PEND_REC_CREDIT|
                   +---------------+---------------+
                   |    RET_NULL   |  RET_CREDIT   |
                   +---------------+---------------+
                   |   RESERVED    |    DG_REC     |
                   +---------------+---------------+
                   |    DST_PB     |    DST_SB     |
                   +---------------+---------------+
                   |             DG_Q              |
                   +-------------------------------+
                   |             MSG_Q             |
                   +-------------------------------+
                   |            READ_Q             |
                   +-------------------------------+
                   |            WRITE_Q            |
                   +-------------------------------+
                   |            DG_RET_Q           |
                   +-------------------------------+
                   |            MSG_RET_Q          |
                   +-------------------------------+
   SCS OPERATION                                                Page 9-17


   where:

       NEXT_CB         the address of the next connection  block  on  the
                       SCS send queue.

       CONNECT_STATE   the connection state.

       BLOCK_STATE     the state of the connection block.

       SRC_CONNECT_ID  the connect id of the local connection block.

       DST_CONNECT_ID  the connect id of destination connection block.

       SRC_PROC_NAME   the process name of local process  allocating  the
                       connection block.

       DST_PROC_NAME   the process name of destination process.

       CONNECT_DATA    connection data.

       SRC_REASON      the local reject or disconnect reason.

       DST_REASON      the destination reject or disconnect reason.

       SEND_CREDIT     the number of available credits to send.

       MIN_SEND_CREDIT the SYSAP protocol threshold.

       REC_CREDIT      the upper bound  of  the  number  of  unused  send
                       credits held by the destination SYSAP process.

       MIN_REC_CREDIT  the minimum number of send credits needed  by  the
                       destination SYSAP process.

       PEND_REC_CREDIT if non-negative, the number of buffers  queued  to
                       receive  messages,  but  not  yet  credited to the
                       destination process;  otherwise  the  negative  of
                       the   number  of  cancels  not  yet  sent  to  the
                       destination process.

       REQ_CREDIT      the number of  credits  sent  to  the  destination
                       process  in a CREDIT_REQ, but not yet responded to
                       by a CREDIT_RSP.

       RET_CREDIT      the number of credits returned by the  destination
                       as specified in the CREDIT_RSP.

       RET_NULL        the number of credits requested to be returned  in
                       a   CREDIT   message   but  not  returned  in  the
                       CREDIT_RSP.

       DG_REC          the number  datagram  buffers  queued  to  receive
                       datagrams.
   SCS OPERATION                                                Page 9-18


       RESERVED        reserved word.

       DST_SB          system  block  corresponding  to  the  destination
                       system.

       DST_PB          path   block   on   which   this   connection   is
                       established.

       DG_Q            the queue of DGREC responses.

       MSG_Q           the queue of MSGREC responses.

       READ_Q          the queue of DATREC responses.

       WRITE_Q         the queue of CNFREC responses.

       DG_RET_Q        the queue of DGSNT responses.

       MSG_RET_Q       the queue of MSGSNT response.
   SCS OPERATION                                                Page 9-19


   9.7.2  Connection States

|  A  connection  exists  in  1  of  several  states:   CLOSED,   LISTEN,
|  CONNECT_SENT,   CONNECT_ACK,  CONNECT_REC,  ACCEPT_SENT,  REJECT_SENT,
|  OPEN, DISCONNECT_SENT, DISCONNECT_REC, DISCONNECT_ACK, and  DISCONNECT
|  MATCH.  Events cause transitions between states.  An event is either a
|  connection  management  function  call  or  receipt  of  a  connection
|  management control message.
|  
|  The connection state table follows:
|  
|  Current           Event                      Action               New
|  State                                                            State
|  
|  CLOSED          LISTEN call                     -               LISTENING
|                  CONNECT call            send CONNECT_REQ        CONNECT_SENT
|                  *rcv CONNECT_REQ        send CONNECT_RSP        CLOSED
|                                          with NO_MATCH
|                  *rcv ACCEPT_REQ         send ACCEPT_RSP         CLOSED
|                                          with NO_MATCH
|                  DISCONNECT call         nop                     CLOSED
|  
|  LISTENING       rcv CONNECT_REQ         send CONNECT_RSP        CONNECT_REC
|  
|                  DISCONNECT call         cancel listen           CLOSED
|  
|  CONNECT_SENT    rcv CONNECT_RSP
|                  with SUCCESS            await ACCEPT or         CONNECT_ACK
|                                          REJECT
|                  with NO_MATCH                   -               CLOSED
|                  with NO_RESOURCES               -               CLOSED
|  
|                  DISCONNECT call         return success on       CLOSED
|                                          DISCONNECT, abort on
|                                          CONNECT
|  
|  CONNECT_ACK     rcv REJECT_REQ          send REJECT_RSP         CLOSED
|                  rcv ACCEPT_REQ          send ACCEPT_RSP         OPEN
|                  DISCONNECT call                 -               CLOSED
|  
|  CONNECT_REC     ACCEPT call             send ACCPET_REQ         ACCEPT_SENT
|                  REJECT call             send REJECT_REQ         REJECT_SENT
|                  DISCONNECT call         send REJECT_REQ         REJECT_SENT
|  
|  ACCEPT_SENT     rcv ACCEPT_RSP
|                  with SUCCESS                    -               OPEN
|                  with DISCONNECTED               -               CLOSED
|  
|                  DISCONNECT call         SUCCESS on DISCONNECT   CLOSED
|  
|                                          ABORT on ACCEPT
|  
|  REJECT_SENT     rcv REJECT_RSP                  -               CLOSED
|  
|                  DISCONNECT call         SUCCESS on DISCONNECT   CLOSED
   SCS OPERATION                                                Page 9-20


|                                          SUCCESS on REJECT
|  
|  OPEN            DISCONNECT call         send DISCONNECT_REQ     DISCONNECT_SENT
|                  rcv DISCONNECT_REQ      send DISCONNECT_RSP     DISCONNECT_REC
|  
|  DISCONNECT_SENT rcv DISCONNECT_REQ      send DISCONNECT_RSP     DISCONNECT_MATCH
|                  rcv DISCONNECT_RSP              -               DISCONNECT_ACK
|  
|                  DISCONNECT call         SUCCESS on both         CLOSED
|                                          DISCONNECTs
|  
|  DISCONNECT_REC  DISCONNECT call         Send DISCONNECT_REQ     DISCONNECT_MATCH
|  
|  DISCONNECT_ACK  rcv DISCONNECT_REQ      send DISCONNECT_RSP     CLOSED
|  
|                  DISCONNECT call         SUCCESS on both         CLOSED
|                                          DISCONNECTs
|  
|  
|  DISCONNECT_MATCH
|                  rcv DISCONNECT_RSP              -               CLOSED
|  
|                  DISCONNECT call         SUCCESS on both         CLOSED
|                                          DISCONNECTs
|  
|  
|  
|  any non-CLOSED  close port/port VC            -                 CLOSED
|  
|  any state       any inappropriate       close port/port VC      CLOSED
|                  event
|  

   The reason that ACCEPT/REJECT are separated  from  CONNECT_RSP  is  to
   allow  a  system  to  initiate  a potentially time consuming operation
   (e.g.  process creation)  in  response  to  an  incoming  CONNECT_REQ.
   DISCONNECT_ACK and DISCONNECT_MATCH states are used to ensure that (1)
   both sides wait until the passive SYSAP issues a  DISCONNECT  request,
   and  (2)  both  sides  have  acknowledged  that  they  know the second
   DISCONNECT was issued.  At that point, no  further  transfer  requests
   can  be issued by either side.  To ensure that all messages in transit
   when the DISCONNECT was issed have completed before the connection  is
   closed,  all  disconnect messages should be sent at lowest priority on
   ports that implement multiple priority messages.
   SCS OPERATION                                                Page 9-21


   9.7.3  Connect


|  function CONNECT(
|          var CID: CONNECT_ID;
|          SRC_PROC: PROC_NAME;
|          DST_PROC: PROC_NAME;
|          DST: SB_INDEX;
|          THRSH: WORD;
|          { [CREDITS: Q_BUF_PTR];... }
|          DATA: C_DATA
|          { [PATH: PB_INDEX] }
|          ):
|          FSTATUS;
|          
|          begin
|  
|           { Allocate a connection block, fill in appropriate fields, and place
|           on SCS work queue for processing. }
|  
|          if ALLOC_CB(CID) then with CBA[CID.INDEX] do 
|                  begin
|                  CB$CONNECT_STATE:=CLOSED;
|                  CB$BLOCK_STATE:=CONNECT_PEND;
|                  CB$SRC_CONNECT_ID:=CID;
|                  CB$SRC_PROC_NAME:=SRC_PROC;
|                  CB$DST_PROC_NAME:=DST_PROC;
|                  CB$CONNECT_DATA:=DATA;
|                  CB$MIN_SEND_CREDIT:=THRSH;
|                  { CB$PEND_REC_CREDIT:= count of CREDITS;
|                  queue buffers with INSERT_MFREEQ }
|                  CB$DST_SB:=DST;
|                  
|                   { Select a path to destination and store path block index 
|                   in CB. Insert CB on connection queue in chosen path block.
|                   If queue is currently empty, then place the PB on
|                   the SCS work queue for processing. }
|  
|                  CHOOSE_PATH(DST,CB$DST_PB); 
|                  if INSERT_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB) = WAS_EMPTY
|                          then INSERT_SCS_Q(CB$DST_PB);
|                  CONNECT:=SUCCESS
|                  end
|          else CONNECT:=FAIL
|          end;{CONNECT}
   SCS OPERATION                                                Page 9-22


   9.7.4  Listen


|  function LISTEN(
|          var CID: CONNECT_ID;
|          SRC_PROC: PROC_NAME;
|          DST_PROC: PROC_NAME;
|          DST: SB_INDEX ):
|          FSTATUS;
|          
|          { Allocate a connection block and initialize fields to
|          indicate waiting for matching connection request. }
|          
|          begin
|          if ALLOC_CB(CID) then with CBA[CID.INDEX] do
|                  begin
|                  CB$CONNECT_STATE:=LISTENING;
|                  CB$SRC_CONNECT_ID:=CID;
|                  CB$SRC_PROC_NAME:=SRC_PROC;
|                  CB$DST_PROC_NAME:=DST_PROC;
|                  CB$DST_SB:=DST;
|                  LISTEN:=SUCCESS
|                  end
|          else LISTEN:=FAIL
|          end{LISTEN};



   9.7.5  Accept


|  procedure ACCEPT(
|          CID: CONNECT_ID;
|          { [CREDITS: Q_BUF_PTR];...}
|          THRSH : WORD;
|          DATA: C_DATA);
|          
|          { Accept a connection request.  Set CB$BLOCK_STATE for SCS_SEND
|          process and insert PB on work queue.  Queue some message buffers
|          so credits can be extended.}
|  
|          begin with CBA[CID.INDEX] do
|                  begin
|                  CB$BLOCK_STATE:=ACCEPT_PEND;
|                  CB$CONNECT_DATA:=DATA;
|                  { CB$PEND_REC_CREDIT:= count of CREDITS;
|                  queue buffers with INSERT_MFREEQ }
|                  CB$MIN_SEND_CREDIT:=THRSH;
|                  if INSERT_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB) = WAS_EMPTY
|                                  then INSERT_SCS_Q(CB$DST_PB);
|                  end
|          end;{ACCEPT}
   SCS OPERATION                                                Page 9-23


   9.7.6  Reject


   procedure REJECT(
           CID: CONNECT_ID;
           REASON: WORD);
           
           { Reject a connection request.  Set CB$BLOCK_STATE for SCS_SEND
           process, note reason for rejection, and queue PB for processing. }

           begin with CBA[CID.INDEX] do
                   begin
                   CB$BLOCK_STATE:=REJECT_PEND;
                   CB$SRC_REASON:=REASON;
                   if INSERT_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB) = WAS_EMPTY
                                   then INSERT_SCS_Q(CB$DST_PB);
                   end
           end;{REJECT}



   9.7.7  Disconnect

   procedure DISCONNECT(
           CID: CONNECT_ID;
           REASON: WORD);

           { Disconnect the connection.  First, check to see if 
           the connection is in operation.  If so, transmit the 
           DISCONNECT_REQ message and move to DISCONNECT_SENT state.
           Otherwise, disconnection has already begun due to remote
           disconnect request.  Move to DISCONNECT_MATCH state and send
           DISCONNECT_REQ message to notify the other side that local
           SYSAP has disconnected.  Set connection state, set block
           state for SCS_SEND, and insert PB if needed for sending. }

           begin
           with CBA[CID.INDEX] do
               begin
               case  CB$CONNECT_STATE of

               OPEN:
                   begin
                   CB$CONNECT_STATE := DISCONNECT_SENT;
                   CB$BLOCK_STATE := DISCONNECT_PEND
                   end;

               DISCONNECT_REC:
                   begin
                   CB$CONNECT_STATE := DISCONNECT_MATCH;
                   CB$BLOCK_STATE := DISCONNECT_PEND
                   end;

               CONNECT_REC:
                   begin
   SCS OPERATION                                                Page 9-24


                   CB$CONNECT_STATE := REJECT_SENT;
                   CB$BLOCK_STATE := REJECT_PEND
                   end;

               OTHERWISE
                   begin
                   CB$CONNECT_STATE := CLOSED;
                   CB$BLOCK_STATE := FREE
                   end;

               end;
               CB$SRC_REASON:=REASON;
               if INSERT_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB) = WAS_EMPTY
                       then INSERT_SCS_Q(CB$DST_PB)
               end;
           end;{DISCONNECT}



   9.7.8  State Poll


   procedure STATE_POLL(
           CID: CONNECT_ID;
           var STATE: C_STATE;
           var DST_CID: CONNECT_ID;
           var DST_PROC: PROC_NAME;
           var DST_SB: SB_INDEX;
           var DST_PB: PB_INDEX;
           var DATA: C_DATA;
           var REASON: WORD);
           
           { Return the state of a process-to-process connection}

           begin with CBA[CID.INDEX] do
                   begin
                   STATE:=CB$CONNECT_STATE;
                   DST_CID:=CB$DST_CONNECT_ID;
                   DST_PROC:=CB$DST_PROC_NAME;
                   DST_SB:=CB$DST_SB;
                   DST_PB:=CB$DST_PB;
                   DATA:=CB$CONNECT_DATA;
                   REASON:=CB$DST_REASON
                   end
           end;{STATE_POLL}
   SCS OPERATION                                                Page 9-25


   9.8  DATAGRAM SERVICE

   9.8.1  Send Datagram


   function SEND_DG(
           CID: CONNECT_ID;
           RET_FLAG: boolean;
           DLEN: APPL_DG_LEN;
           PTR: Q_BUF_PTR):
           FSTATUS;
           
           { Check to see that connection is still open.  Fill in SCS header 
           information and call PPD send datagram. }

           begin with CBA[CID.INDEX] do 
                   if CB_CLOSED(CID) then SEND_DG:=NOT_OPEN else
                   begin
                   if not RET_FLAG then CB$DG_REC:=CB$DG_REC+1;
                   PTR^.LENGTH:=DLEN+AP_DG_HDR_LEN;
                   PTR^.SCS_TYPE:=APPL_DG;
                   PTR^.CREDIT:=0;
                   PTR^.REC_CONNECT_ID:=CB$DST_CONNECT_ID;
                   PTR^.SEND_CONNECT_ID:=CB$SRC_CONNECT_ID;
                   SNDDG(CB$DST_PB,RET_FLAG,PTR);
                   SEND_DG:=SUCCESS
                   end
           end;{SEND_DG}



   9.8.2  Send Datagram Poll


   function SEND_DG_POLL(
           CID: CONNECT_ID;
           var PTR: Q_BUF_PTR):
           FSTATUS;

           { Check datagram return queue for datagram transmission buffer
           from previous send. }

           begin with CBA[CID.INDEX] do
                   if REMOVE(CB$DG_RET_Q,PTR) then
                           SEND_DG_POLL:=SUCCESS
                   else SEND_DG_POLL:=FAIL
           end;{SEND_DG_POLL}
   SCS OPERATION                                                Page 9-26


   9.8.3  Receive Datagram


   function REC_DG(
           CID: CONNECT_ID;
           PTR: Q_BUF_PTR):
           FSTATUS;
           
           { Queue a buffer to the datagram receive queue. }

           begin with CBA[CID.INDEX] do
                   if CB_CLOSED(CID) then REC_DG:=NOT_OPEN else
                   begin
                   CB$DG_REC:=CB$DG_REC+1;
                   INSERT_DFREEQ(PTR);
                   REC_DG:=SUCCESS;
                   end
           end;{REC_DG}



   9.8.4  Receive Datagram Poll


   function REC_DG_POLL(
           CID: CONNECT_ID;
           var DLEN: APPL_DG_LEN;
           var PTR: Q_BUF_PTR):
           FSTATUS;

           { Check CB datagram queue and return datagram if any
           have been received. }

           begin with CBA[CID.INDEX] do if REMOVE(CB$DG_Q,PTR) then
                   begin
                   DLEN:=PTR^.LENGTH-AP_DG_HDR_LEN;
                   REC_DG_POLL:=SUCCESS
                   end
           else
                   REC_DG_POLL:=FAIL
           end;{REC_DG_POLL}
   SCS OPERATION                                                Page 9-27


   9.8.5  Cancel Receive Datagram


   function CANCEL_REC_DG(
           CID: CONNECT_ID;
           var PTR: Q_BUF_PTR):
           FSTATUS;
           
           { Return a queued datagram receive buffer.  Function FAILS if
           no buffers are queued for this connection or if the global
           queue is empty. }

           begin with CBA[CID.INDEX] do if CB$DG_REC > 0 then
                   if REMOVE_DFREEQ(PTR) = SUCCESS then
                           begin
                           CB$DG_REC:=CB$DG_REC-1;
                           CANCEL_REC_DG:=SUCCESS
                           end
                   else CANCEL_REC_DG:=FAIL
           else CANCEL_REC_DG:=FAIL
           end;{CANCEL_REC_DG}
   SCS OPERATION                                                Page 9-28


   9.9  SEQUENTIAL MESSAGE SERVICE

   9.9.1  Send Message


   function SEND_MSG(
           CID: CONNECT_ID;
           THRSH: WORD;
           RET_FLAG: boolean;
           MLEN: APPL_MSG_LEN;
           PTR: Q_BUF_PTR):
           FSTATUS;

           { Check that connection is operating.  Send Message if credits are 
           available. }
           
           begin with CBA[CID.INDEX] do 
               if CB_CLOSED(CID) then SEND_MSG:=NOT_OPEN 
               else if CB$SEND_CREDIT > THRSH then

               begin
                   CB$SEND_CREDIT:=CB$SEND_CREDIT-1;
                   
                   { If we're keeping this buffer, note one more credit to extend. }

                   if not RET_FLAG then CB$PEND_REC_CREDIT:=
                           CB$PEND_REC_CREDIT+1;

                   { If we have extra receive buffers to report, update estimated
                   unused credits held by destination (CB$REC_CREDIT), send
                   the outstanding credits by placing in message CREDIT field,
                   and zero PENDING_REC_CREDIT to note that we're up to date. }

                   if CB$PEND_REC_CREDIT > 0 then
                           begin
                           CB$REC_CREDIT:=CB$REC_CREDIT+CB$PEND_REC_CREDIT;
                           PTR^.CREDIT:=CB$PEND_REC_CREDIT;
                           CB$PEND_REC_CREDIT:=0;
                           end
                   else

                           { Otherwise, we have not reported some
                           cancelled buffers. }

                           begin
                           PTR^.CREDIT:=0;
                           CB$RET_CREDIT:=CB$RET_CREDIT+1
                           end;

                   { Fill in SCS header and transmit messge. }

                   PTR^.LENGTH:=AP_MSG_HDR_LEN+MLEN;
                   PTR^.SCS_TYPE:=APPL_MSG;
                   PTR^.REC_CONNECT_ID:=CB$DST_CONNECT_ID;
                   PTR^.SEND_CONNECT_ID:=CB$SRC_CONNECT_ID;
   SCS OPERATION                                                Page 9-29


                   SNDMSG(CB$DST_PB,RET_FLAG,PTR);
                   SEND_MSG:=SUCCESS
                   end
               else 
                   SEND_MSG:=FAIL
           end;{SEND_MSG}



   9.9.2  Send Message Poll


   function SEND_MSG_POLL(
           CID:CONNECT_ID;
           var PTR: Q_BUF_PTR):
           FSTATUS;

           { Check message return queue for received message }

           begin with CBA[CID.INDEX] do
                   if REMOVE(CB$MSG_RET_Q,PTR) then
                           SEND_MSG_POLL:=SUCCESS
                   else SEND_MSG_POLL:=FAIL
           end;{SEND_MSG_POLL}



   9.9.3  Receive Message


   function REC_MSG(
           CID: CONNECT_ID;
           PTR: Q_BUF_PTR):
           FSTATUS;
           
           { Receive message.  Check connection status, queue the supplied buffer,
           and note that there is one more credit for the connection. } 
           
           begin with CBA[CID.INDEX] do if CB_CLOSED(CID) 
               then REC_MSG:=NOT_OPEN 
               else
                   begin
                   REC_MSG:=SUCCESS;
                   INSERT_MFREEQ(PTR);
                   CB$PEND_REC_CREDIT:=CB$PEND_REC_CREDIT+1;

                   { If we were going to ask for credits back, note that we
                   got one back. }

                   if CB$PEND_REC_CREDIT <= 0 then
                           CB$RET_CREDIT:=CB$RET_CREDIT+1

                   { If remote side is below threshold, send credit message now. }

                   else if CB$REC_CREDIT <= CB$MIN_REC_CREDIT then
   SCS OPERATION                                                Page 9-30


                           begin
                           if CB$BLOCK_STATE = ALLOC then
                                   begin
                                   CB$BLOCK_STATE:=CREDIT_PEND;
                                   if INSERT_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB)
                                     = WAS_EMPTY then 
                                           INSERT_SCS_Q(CB$DST_PB);
                                   end
                           end
                   end
           end;{REC_MSG}



   9.9.4  Receive Message Poll


   function REC_MSG_POLL(
           CID: CONNECT_ID;
           var MLEN: APPL_MSG_LEN;
           var PTR: Q_BUF_PTR):
           FSTATUS;

           { Check for reception of a message.  Return buffer and data length. }

           begin with CBA[CID.INDEX] do if REMOVE(CB$MSG_Q,PTR) then
                   begin
                   MLEN:=PTR^.LENGTH-AP_MSG_HDR_LEN;
                   REC_MSG_POLL:=SUCCESS
                   end
           else
                   REC_MSG_POLL:=FAIL
           end;{REC_MSG_POLL}
   SCS OPERATION                                                Page 9-31


   9.9.5  Cancel Receive Message


   procedure CANCEL_REC_MSG(
           CID: CONNECT_ID);
           
           { Cancel a receive message request.  Note one less credit to send (or
           one more to take back).  If we're going to extend more credits then
           note that we got one back (increment CB$RET_CREDIT) so that user will
           get buffer back.  Otherwise, prepare CB so that credit message will
           be sent.  The buffer is returned by calling CANCEL_REC_MSG_POLL. }

           begin with CBA[CID.INDEX] do
                   begin
                   CB$PEND_REC_CREDIT:=CB$PEND_REC_CREDIT-1;
                   if CB$PEND_REC_CREDIT >= 0 then
                           CB$RET_CREDIT:=CB$RET_CREDIT+1
                   else
                           begin
                           if CB$BLOCK_STATE = ALLOC then
                                   begin
                                   CB$BLOCK_STATE:=CREDIT_PEND;
                                   if INSERT_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB)
                                     = WAS_EMPTY then 
                                           INSERT_SCS_Q(CB$DST_PB);
                                   end
                           end
                   end
           end;{CANCEL_REC_MSG}



   9.9.6  Cancel Receive Message Poll


   function CANCEL_REC_MSG_POLL(
           CID: CONNECT_ID;
           var PTR: Q_BUF_PTR):
           FSTATUS;
           
           { Request return of buffers cancelled by CANCEL_REC_MESSAGE.
           CB$RET_CREDIT indicates number of buffers that can be returned.
           CB$RET_NULL indicates number of cancels requested but credits not
           returned from remote side.  Status of NULL indicates that the
           cancel succeeded but the buffer can not be given back to the caller. }

           begin with CBA[CID.INDEX] do
                   begin
                   if CB$RET_CREDIT > 0 then
                           begin
                           CB$RET_CREDIT:=CB$RET_CREDIT-1;
                           CANCEL_REC_MSG_POLL:=REMOVE_MFREEQ(PTR)
                           end
                   else if CB$RET_NULL > 0 then
                           begin
   SCS OPERATION                                                Page 9-32


                           CB$RET_NULL:=CB$RET_NULL-1;
                           CANCEL_REC_MSG_POLL:=NULL
                           end
                   else CANCEL_REC_MSG_POLL:=FAIL
                   end
           end;{CANCEL_REC_MSG_POLL}
   SCS OPERATION                                                Page 9-33


   9.10  BLOCK DATA SERVICE

   9.10.1  Buffer Descriptor Table

   The buffer descriptor table is a data structure maintained by the  SCS
   layer  and  readable by the PPD layer.  The buffer descriptor table is
   referenced by buffer name and contains the length, address, and access
   control information for named buffers.

   A representative buffer  descriptor  table  entry  has  the  following
   format:


                    3                             
                    1                             0
                   +-------------------------------+
                   |          BUF_LENGTH           |
                   +-------------------------------+
                   |          BUF_ADDRESS          |
                   +-------------------------------+
                   |          BUF_ACCESS           |
                   +-------------------------------+



   where:

       BUF_LENGTH      the length of buffer.

       BUF_ADDR        the address of the buffer  and/or  buffer  mapping
                       tables.

       BUF_ACCESS      the buffer access control.
   SCS OPERATION                                                Page 9-34


   9.10.2  Map Buffer


   function MAP(
           {BLOCK_BUF: BUF_DESCR;}
           var NAME: LONG):
           FSTATUS;
           
           begin
           {fill in Buffer Descriptor Table entry
           end return buffer name}
           end;{MAP}



   9.10.3  Unmap Buffer


   procedure UNMAP(
           NAME: LONG);
           
           begin
           {invalidate name and free Buffer Descriptor
           Table entry}
           end;{UNMAP}



   9.10.4  Read


   function READ(
           CID: CONNECT_ID;
           THRSH: WORD;
           PTR: Q_BUF_PTR;
           var XID: WORD):
           FSTATUS;
           
           { Request block data transfer from destination.  First check for
           connection condition and sufficient credits to perform operation. 
           Assign a new transaction number for this transaction and return
           it to caller. }

           begin with CBA[CID.INDEX] do if CB_CLOSED(CID) 
               then READ:=NOT_OPEN 
               else if CB$SEND_CREDIT > THRSH then
                   begin
                   CB$SEND_CREDIT:=CB$SEND_CREDIT-1;
                   PTR^.SEND_BLOCK_ID:=CID.INDEX;
                   XID:=NEXT_XID;
                   PTR^.SEND_XID:=XID;
                   REQDAT(CB$DST_PB,PTR);
                   READ:=SUCCESS
                   end
           else READ:=FAIL
   SCS OPERATION                                                Page 9-35


           end;{READ}



   9.10.5  Read Poll


   function READ_POLL(
           CID: CONNECT_ID;
           var PTR: Q_BUF_PTR;
           var XID: WORD):
           FSTATUS;
           
           { Check for completion of read block transfer. }

           begin with CBA[CID.INDEX] do if REMOVE(CB$READ_Q,PTR) then
                   begin
                   XID:= PTR^.SEND_XID;
                   READ_POLL:=SUCCESS;
                   end
           else READ_POLL:=FAIL;
           end{READ_POLL};



   9.10.6  Write


   function WRITE(
           CID: CONNECT_ID;
           THRSH: WORD;
           PTR: Q_BUF_PTR;
           var XID: WORD):
           FSTATUS;
           
           { Request block data transfer to destination system. Verify that
           connection is open, assign a new transaction number, and call
           PPD routine to perform the transfer. }

           begin with CBA[CID.INDEX] do if CB_CLOSED(CID) 
               then WRITE:=NOT_OPEN 
               else if CB$SEND_CREDIT > THRSH then
                   begin
                   CB$SEND_CREDIT:=CB$SEND_CREDIT-1;
                   PTR^.SEND_BLOCK_ID:=CID.INDEX;
                   XID:=NEXT_XID;
                   PTR^.SEND_XID:=XID;
                   SNDDAT(CB$DST_PB,PTR);
                   WRITE:=SUCCESS
                   end
           else WRITE:=FAIL
           end;{WRITE}
   SCS OPERATION                                                Page 9-36


   9.10.7  Write Poll


   function WRITE_POLL(
           CID: CONNECT_ID;
           var PTR: Q_BUF_PTR;
           var XID: WORD):
           FSTATUS;
           
           { Check for completion of write block transfer. }

           begin with CBA[CID.INDEX] do if REMOVE(CB$WRITE_Q,PTR) then
                   begin
                   XID:=PTR^.SEND_XID;
                   WRITE_POLL:= SUCCESS
                   end
           else WRITE_POLL:=FAIL
           end{WRITE_POLL};
   SCS OPERATION                                                Page 9-37


   9.11  SCS SEND

|  procedure SCS_SEND; {PROCESS}
|  
|          var     PTR: PB_PTR;
|  
|          { SCS work queue process to send SCS command messages.  Path blocks
|          are queued to the work queue when a command is to be sent for
|          a connection.  The CB$BLOCK_STATE field of the first connect
|          block queued to the PB specifies the work to be performed.
|          A control message is constructed in the single SCS command buffer
|          queued to the path block (PB), and the message is transmitted. }
|  
|          begin
|          
|          { Get next path block address in PTR.  Dispatch on block state. }
|  
|          while REMOVE_SCS_Q(PTR) do with PTR^ do begin
|          case PB$CB_Q^.CB$BLOCK_STATE of
|  
|          CONNECT_PEND:
|  
|                  { Prepare Connect Request Message.  Fill in number of credits
|                  now available (CB$PEND_REC_CREDIT) and the minimum number
|                  of credits needed by destination (CB$MIN_REC_CREDIT). }
|  
|                  begin
|                  PB$MSG_PTR^.LENGTH:=CONNECT_REQ_LEN;
|                  PB$MSG_PTR^.SCS_TYPE:=CONNECT_REQ;
|                  PB$MSG_PTR^.CREDIT:=PB$CB_Q^.CB$PEND_REC_CREDIT;
|                  { Update CB to note credits extended }
|                  PB$CB_Q^.CB$PEND_REC_CREDIT:=0;
|                  PB$MSG_PTR^.MIN_CREDIT:=PB$CB_Q^.CB$MIN_REC_CREDIT;
|                  PB$MSG_PTR^.STATUS:=0;
|                  PB$MSG_PTR^.REC_PROC:=PB$CB_Q^.CB$DST_PROC_NAME;
|                  PB$MSG_PTR^.SEND_PROC:=PB$CB_Q^.CB$SRC_PROC_NAME;
|                  PB$MSG_PTR^.SEND_DATA:=PB$CB_Q^.CB$CONNECT_DATA;
|                  PB$CB_Q^.CB$CONNECT_STATE:=CONNECT_SENT
|                  end;
|  
|          ACCEPT_PEND:
|  
|                  { Prepare Accept message.  Fill in number of credits
|                  now available (CB$PEND_REC_CREDIT) and the minimum number
|                  of credits needed by destination (CB$MIN_REC_CREDIT). }
|  
|                  begin
|                  PB$MSG_PTR^.LENGTH:=ACCEPT_REQ_LEN;
|                  PB$MSG_PTR^.SCS_TYPE:=ACCEPT_REQ;
|                  PB$MSG_PTR^.CREDIT:=PB$CB_Q^.CB$PEND_REC_CREDIT;
|                  { Update CB to note credits extended }
|                  PB$CB_Q^.CB$PEND_REC_CREDIT:=0;
|                  PB$MSG_PTR^.MIN_CREDIT:=PB$CB_Q^.CB$MIN_REC_CREDIT;
|                  PB$MSG_PTR^.STATUS:=0;
|                  PB$MSG_PTR^.REC_PROC:=PB$CB_Q^.CB$DST_PROC_NAME;
   SCS OPERATION                                                Page 9-38


|                  PB$MSG_PTR^.SEND_PROC:=PB$CB_Q^.CB$SRC_PROC_NAME;
|                  PB$MSG_PTR^.SEND_DATA:=PB$CB_Q^.CB$CONNECT_DATA;
|                  PB$CB_Q^.CB$CONNECT_STATE:=ACCEPT_SENT
|                  end;
|  
|          REJECT_PEND:
|  
|                  { Prepare Reject message with reason for rejection.
|                  Give no credits (adding insult to injury). }
|  
|                  begin
|                  PB$MSG_PTR^.LENGTH:=REJECT_REQ_LEN;
|                  PB$MSG_PTR^.SCS_TYPE:=REJECT_REQ;
|                  PB$MSG_PTR^.CREDIT:=0;
|                  PB$MSG_PTR^.MIN_CREDIT:=0;
|                  PB$MSG_PTR^.STATUS:=PB$CB_Q^.CB$SRC_REASON;
|                  PB$CB_Q^.CB$CONNECT_STATE:=REJECT_SENT
|                  end;
|  
|          DISCONNECT_PEND:
|  
|                  { Prepare Disconnect Request message. Connection state has 
|                  already been set to DISCONNECT_SENT or DISCONNECT_MATCH. }
|  
|                  begin
|                  PB$MSG_PTR^.LENGTH:=DISCON_REQ_LEN;
|                  PB$MSG_PTR^.SCS_TYPE:=DISCON_REQ;
|                  PB$MSG_PTR^.CREDIT:=0;
|                  PB$MSG_PTR^.MIN_CREDIT:=0;
|                  PB$MSG_PTR^.STATUS:=PB$CB_Q^.CB$SRC_REASON
|                  end;
|  
|          CREDIT_PEND:
|  
|                  { Prepare credit message. }
|  
|                  begin
|                  PB$MSG_PTR^.LENGTH:=CREDIT_REQ_LEN;
|                  PB$MSG_PTR^.SCS_TYPE:=CREDIT_REQ;
|                  PB$MSG_PTR^.CREDIT:=PB$CB_Q^.CB$PEND_REC_CREDIT;
|                  PB$CB_Q^.CB$REQ_CREDIT:=PB$CB_Q^.CB$PEND_REC_CREDIT;
|                  PB$CB_Q^.CB$PEND_REC_CREDIT:=0
|                  end;
|          end;
|  
|          { Now that message has been prepared, fill in source and 
|          destination connect ID and send the message. }
|  
|          PB$MSG_PTR^.REC_CONNECT_ID:=PB$CB_Q^.CB$DST_CONNECT_ID;
|          PB$MSG_PTR^.SEND_CONNECT_ID:=PB$CB_Q^.CB$SRC_CONNECT_ID;
|          { must convert PTR to a PB Index for SNDMSG call }
|          SNDMSG( PBPTR_TO_PBINDEX(PTR) , false , PB$MSG_PTR);
|          end;
|          end;{SCS_SEND}
   SCS OPERATION                                                Page 9-39


   9.12  SCS RECEIVE

|  procedure SCS_REC; {PROCESS}
|  
|          var     PTR: Q_BUF_PTR;
|                  RSP: RSP_TYPE;
|                  CNCT_INDEX: WORD;
|                  DST: PB_INDEX;
|          
|          { Process to handle reception of messages, datagrams, and command
|          responses.  There is a single SCS command buffer for each 
|          port-to-port virtual circuit.  Therefore, only one command can be
|          outstanding per path block.  The buffer is consumed when an SCS
|          command is transmitted.  When a response is received, the buffer
|          containing the response can be used to transmit another command.
|          This is done immediately if an immediate response is required.  
|          Otherwise, the buffer is queued to the PB, and if any other CBs
|          are waiting on the PB, the PB is queued to the send work queue
|          for service. }
|  
|          begin
|          while RSP_POLL(RSP,DST,PTR) = SUCCESS do case RSP of
|  
|          { PTR now has address of a buffer (Q_BUF_PTR)
|          that has been received.  Dispatch on the type
|          of response received.  If DGSNT or MSGSNT response,
|          insert buffer on DG or MSG response queue. }
|  
|          DGSNT:
|                  INSERT(CBA[PTR^.SEND_CONNECT_ID.INDEX].CB$DG_RET_Q,PTR);
|  
|          MSGSNT:
|                  INSERT(CBA[PTR^.SEND_CONNECT_ID.INDEX].CB$MSG_RET_Q,PTR);
|  
|  
|          DGREC:
|  
|          { Datagram received.  If receive queue has a buffer, insert
|          datagram on CB and note one less buffer available.  Otherwise,
|          return buffer to datagram receive queue. }
|  
|                  with CBA[PTR^.REC_CONNECT_ID.INDEX] do if CB$DG_REC > 0
|                          then
|                          begin
|                          CB$DG_REC:=CB$DG_REC-1;
|                          INSERT(CB$DG_Q,PTR)
|                          end
|                  else INSERT_DFREEQ(PTR);
|  
|          MSGREC:
|  
|          { Message received.  Locate CB for the message and dispatch
|          on the SCS message type. }
|  
|                  with CBA[PTR^.REC_CONNECT_ID.INDEX] 
   SCS OPERATION                                                Page 9-40


|                  DO case PTR^.SCS_TYPE of
|  
|                  { begin new case block }
|  
|                  CONNECT_REQ:
|  
|                  { Connect request recieved.  Check if this conect
|                  matches a pending Listen request.  If so, initialize
|                  credit and name fields.  Return the Connect Response
|                  message with proper status. }
|  
|                  begin
|                  if CONNECT_MATCH(PTR,CNCT_INDEX) then
|                          with CBA[CNCT_INDEX] do
|                          begin
|                          CB$CONNECT_STATE:=CONNECT_REC;
|                          CB$SEND_CREDIT:=PTR^.CREDIT;
|                          CB$DST_CONNECT_ID:=PTR^.SEND_CONNECT_ID;
|                          CB$DST_PROC_NAME:=PTR^.SEND_PROC;
|                          CB$MIN_REC_CREDIT:=PTR^.MIN_CREDIT;
|                          CB$CONNECT_DATA:=PTR^.SEND_DATA;
|                          PTR^.STATUS:=CONNECTED
|                          end
|                  else PTR^.STATUS:=NO_MATCH;
|                  PTR^.LENGTH:=CONNECT_RSP_LEN;
|                  PTR^.SCS_TYPE:=CONNECT_RSP;
|                  PTR^.CREDIT:=0;
|                  PTR^.REC_CONNECT_ID:=PTR^.SEND_CONNECT_ID;
|                  PTR^.SEND_CONNECT_ID:=CB$SRC_CONNECT_ID;
|                  PTR^.MIN_CREDIT:=0;
|                  SNDMSG(DST,false,PTR)
|                  end;
|                  
|                  CONNECT_RSP:
|  
|                  { Connect response received.  Note whether connect was 
|                  processed or no matching listen was found.  Restore the
|                  message buffer for this PB, remove CB from queue, and 
|                  reinsert PB on work queue if more CB's are waiting. }
|  
|                  begin
|                  if PTR^.STATUS = CONNECTED then
|                          CB$CONNECT_STATE:=CONNECT_ACK
|                  else
|                      begin
|                      CB$CONNECT_STATE:=CLOSED;
|                      CB$DST_REASON := PTR^.STATUS
|                      end;
|                  PBA[CB$DST_PB].PB$MSG_PTR:=PTR;
|                  if REMOVE_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB) <> NOW_EMPTY
|                          then INSERT_SCS_Q(CB$DST_PB);
|                  end;
|  
|                  ACCEPT_REQ:
|  
   SCS OPERATION                                                Page 9-41


|                  { Accept Request received.  Open connection and 
|                  initialize credit and connect data information.  Send
|                  The Accept Response message. }
|  
|                  begin
|                  CB$SEND_CREDIT:=PTR^.CREDIT;
|                  CB$MIN_REC_CREDIT:=PTR^.MIN_CREDIT;
|                  CB$CONNECT_STATE:=OPEN;
|                  CB$CONNECT_DATA:=PTR^.SEND_DATA;
|                  PTR^.LENGTH:=ACCEPT_RSP_LEN;
|                  PTR^.SCS_TYPE:=ACCEPT_RSP;
|                  PTR^.CREDIT:=0;
|                  PTR^.REC_CONNECT_ID:=PTR^.SEND_CONNECT_ID;
|                  PTR^.SEND_CONNECT_ID:=CB$SRC_CONNECT_ID;
|                  SNDMSG(DST,false,PTR)
|                  end;
|  
|                  ACCEPT_RSP:
|  
|                  { Accept Response message received.  Save our message buffer,
|                  remove CB from queue, and requeue PB if more to do for this
|                  path. }
|  
|                  begin
|                  CB$CONNECT_STATE:=OPEN;
|                  PBA[CB$DST_PB].PB$MSG_PTR:=PTR;
|                  if REMOVE_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB) <> NOW_EMPTY
|                          then INSERT_SCS_Q(CB$DST_PB);
|                  end;
|  
|                  REJECT_REQ:
|  
|                  { Reject Request received.  Close the channel, save the reject
|                  reason, and send the Reject Response message. }
|  
|                  begin
|                  CB$CONNECT_STATE:=CLOSED;
|                  CB$DST_REASON:=PTR^.STATUS;
|                  PTR^.LENGTH:=REJECT_RSP_LEN;
|                  PTR^.SCS_TYPE:=REJECT_RSP;
|                  PTR^.CREDIT:=0;
|                  PTR^.REC_CONNECT_ID:=PTR^.SEND_CONNECT_ID;
|                  PTR^.SEND_CONNECT_ID:=CB$SRC_CONNECT_ID;
|                  SNDMSG(DST,false,PTR)
|                  end;
|  
|                  REJECT_RSP:
|  
|                  { Reject Response received.  Save our SCS message buffer
|                  and check if more work for this PB. }
|  
|                  begin
|                  CB$CONNECT_STATE:=CLOSED;
|                  PBA[CB$DST_PB].PB$MSG_PTR:=PTR;
|                  if REMOVE_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB) <> NOW_EMPTY
   SCS OPERATION                                                Page 9-42


|                          then INSERT_SCS_Q(CB$DST_PB);
|                  end;
|  
|                  DISCON_REQ:
|  
|                  { Disconnect request received.  The connection can be in
|                  one of three states:  OPEN, DISCONNECT_SENT, or DISCONNECT_ACK.
|                  For each state, set the correct new state.  For OPEN or
|                  DISCONNECT_SENT states, a DISCONNECT_RSP message must
|                  be transmitted.  A DISCONNECT_REQ message received while in
|                  DISCONNECT_SENT state means that both SYSAPS initated 
|                  disconnection simultaneously.  If the connection is in 
|                  DISCONNECT_ACK  state, the connection is closed, the message 
|                  buffer is saved, and the queue is checked for more work. }
|  
|                  begin
|                  case CB$CONNECT_STATE of
|                      OPEN:  CB$CONNECT_STATE:=DISCONNECT_REC;
|                      DISCONNECT_SENT:  CB$CONNECT_STATE:=DISCONNECT_MATCH;
|                      DISCONNECT_ACK:  CB$CONNECT_STATE:=CLOSED
|                  end;
|                  
|                  if CB$CONNECT_STATE=CLOSED
|                  then
|                      begin
|                      PBA[CB$DST_PB].PB$MSG_PTR:=PTR;
|                      if REMOVE_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB) <>
|                          NOW_EMPTY then INSERT_SCS_Q(CB$DST_PB)
|                      end
|                  else
|                      begin
|                      CB$DST_REASON:=PTR^.STATUS;
|                      PTR^.LENGTH:=DISCON_RSP_LEN;
|                      PTR^.SCS_TYPE:=DISCON_RSP;
|                      PTR^.CREDIT:=0;
|                      PTR^.REC_CONNECT_ID:=PTR^.SEND_CONNECT_ID;
|                      PTR^.SEND_CONNECT_ID:=CB$SRC_CONNECT_ID;
|                      SNDMSG(DST,false,PTR)
|                      end
|                  end;
|  
|                  DISCON_RSP:
|  
|                  { Disconnect Response received.  The connection can be
|                  in one of two states.  If in DISCONNECT_SENT state, we initiated
|                  the disconnect, and now move to DISCONNECT_ACK to wait for
|                  the remote SYSAP to disconnect.  If in DISCONNECT_MATCH state,
|                  we're waiting for confirmation that the initator knows that
|                  we've received the passive SYSAP disconnect.  Here we close
|                  down the connection and look for more work to do. }
|  
|                  begin
|                  if CB$CONNECT_STATE = DISCONNECT_SENT
|                  then
|                      begin
   SCS OPERATION                                                Page 9-43


|                      CB$CONNECT_STATE:= DISCONNECT_ACK;
|                      CB$DST_REASON:=PTR^.STATUS;
|                      PTR^.LENGTH:=DISCON_RSP_LEN;
|                      PTR^.SCS_TYPE:=DISCON_RSP;
|                      PTR^.REC_CONNECT_ID:=PTR^.SEND_CONNECT_ID;
|                      PTR^.SEND_CONNECT_ID:=CB$SRC_CONNECT_ID;
|                      SNDMSG(DST,false,PTR)
|                      end
|                  else { CB$CONNECT_STATE = DISCONNECT_MATCH }
|                      begin
|                      CB$CONNECT_STATE:=CLOSED;
|                      PBA[CB$DST_PB].PB$MSG_PTR:=PTR;
|                      if REMOVE_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB) <>
|                          NOW_EMPTY then INSERT_SCS_Q(CB$DST_PB)
|                      end
|                  end;
|  
|                  CREDIT_REQ:
|  
|                  { Credit Request received.  Credit request can be positive
|                  (to indicate more credits) or negative (to take some back).
|                  If negative, only give back the minimum of the number 
|                  requested and the number available without going below
|                  the SCS threshold for this connection.  Return
|                  Credit Response message. }
|  
|                  begin
|                  if PTR^.CREDIT < 0 
|                      then PTR^.CREDIT:=
|                             -MIN(  MAX(0,CB$SEND_CREDIT-CB$MIN_SEND_CREDIT),
|                                    -PTR^.CREDIT);
|  
|                  { make positive or negative adjustment }
|  
|                  CB$SEND_CREDIT:=CB$SEND_CREDIT+PTR^.CREDIT;
|                  PTR^.LENGTH:=CREDIT_RSP_LEN;
|                  PTR^.SCS_TYPE:=CREDIT_RSP;
|                  PTR^.REC_CONNECT_ID:=PTR^.SEND_CONNECT_ID;
|                  PTR^.SEND_CONNECT_ID:=CB$SRC_CONNECT_ID;
|                  SNDMSG(DST,false,PTR)
|                  end;
|                  
|                  CREDIT_RSP:
|  
|                  { Credit Response received.  Adjust credit values for
|                  number actually returned, if credit return was requested.  }
|  
|                  begin
|                  if CB$REQ_CREDIT < 0 then
|                          begin
|                          CB$RET_CREDIT:=CB$RET_CREDIT-PTR^.CREDIT;
|                          CB$RET_NULL:=CB$RET_NULL+PTR^.CREDIT-CB$REQ_CREDIT;
|                          end;
|                  CB$REC_CREDIT:=CB$REC_CREDIT+PTR^.CREDIT;
|                  PBA[CB$DST_PB].PB$MSG_PTR:=PTR;
   SCS OPERATION                                                Page 9-44


|  
|                  { If credits are waiting to be taken back from the destination
|                  due to cancels, OR if there are buffers not credited AND
|                  the destination is below threshold, then insert this PB
|                  on the work queue to send the credit message. }
|  
|                  if (CB$PEND_REC_CREDIT < 0) or
|                  ((CB$PEND_REC_CREDIT > 0) and
|                          (CB$REC_CREDIT < CB$MIN_REC_CREDIT)) then
|                          INSERT_SCS_Q(CB$DST_PB)
|  
|                  { Otherwise, just check to see if there's anything else to do. }
|  
|                  else if REMOVE_CB_Q(PBA[CB$DST_PB].PB$CB_Q,CB$NEXT_CB) <>
|                          NOW_EMPTY then INSERT_SCS_Q(CB$DST_PB)
|                  end;
|  
|                  APPL_MSG:
|  
|                  { Application Message received.  Insert on message queue for
|                  this connection. }
|  
|                  begin
|                  CB$REC_CREDIT:=CB$REC_CREDIT-1;
|                  CB$SEND_CREDIT:=CB$SEND_CREDIT+PTR^.CREDIT;
|                  INSERT(CB$MSG_Q,PTR)
|                  end;
|  
|          end;{case PTR^.SCS_TYPE}
|  
|  
|          DATREC:
|                  with CBA[PTR^.SEND_BLOCK_ID] do begin
|                  INSERT(CB$READ_Q,PTR);
|                  CB$SEND_CREDIT:=CB$SEND_CREDIT+1;
|                  end;
|  
|          CNFREC:
|                  with CBA[PTR^.SEND_BLOCK_ID] do begin
|                  INSERT(CB$WRITE_Q,PTR);
|                  CB$SEND_CREDIT:= CB$SEND_CREDIT+1;
|                  end;
|  
|          IDREC:
|                  {if <id indicates a maintenance state> then
|                          PBA[PTR^.SEND_BLOCK_ID].PB$DST_VC_STATE:=
|                                  MAINT
|                  else if PBA[PTR^.SEND_BLOCK_ID].PB$DST_VC_STATE =
|                          CLOSED then VC_START( )}
|                  INSERT(PBA[PTR^.SEND_BLOCK_ID].PB$DG_Q,PTR);
|  
|          MDATREC,
|          MCNFREC:
|                  INSERT(PBA[PTR^.SEND_BLOCK_ID].PB$DG_Q,PTR);
|  
   SCS OPERATION                                                Page 9-45


|          end;{case RSP}
|          end;{SCS_REC}











                                 CHAPTER 10

                              CI PPD OPERATION



   The operation of  the  PPD  layer  is  port  specific.   This  section
   describes the operation of the CI PPD layer.



   10.1  PPD DATAGRAMS

   10.1.1  Start

   The START datagram is used to start  virtual  circuit  initialization.
   The format of START is:


                    3               1
                    1               5             0
                   +---------------+---------------+
                   |    PPD_TYPE   |    LENGTH     |
                   +---------------+---------------+
                   |                               |
                   =           START_DATA          =
                   |                               |
                   +-------------------------------+


   where:

       LENGTH          START_LEN.

       PPD_TYPE        START.

       START_DATA      start data.  See Appendix F.
   CI PPD OPERATION                                             Page 10-2


   10.1.2  Start Acknowledge

   The STACK datagram is used to acknowledge receipt  of  a  START.   The
   format of STACK is:


                    3               1
                    1               5             0
                   +---------------+---------------+
                   |    PPD_TYPE   |    LENGTH     |
                   +---------------+---------------+
                   |                               |
                   =           START_DATA          =
                   |                               |
                   +-------------------------------+


   where:

       LENGTH          STACK_LEN.

       PPD_TPE         STACK.

       START_DATA      start data.  See Appendix F.
   CI PPD OPERATION                                             Page 10-3


   10.1.3  Acknowledge

   The ACK datagram is used to acknowledge the receipt of a  STACK.   The
   format of ACK is:


                    3               1
                    1               5             0
                   +---------------+---------------+
                   |    PPD_TYPE   |    LENGTH     |
                   +---------------+---------------+



   where:

       LENGTH          ACK_LEN.

       PPD_TYPE        ACK.
   CI PPD OPERATION                                             Page 10-4


   10.2  START VIRTUAL CIRCUIT

   A  virtual  circuit  exists  in  one  of  four   states:    VC_CLOSED,
   START_SENT,  START_REC,  and  VC_OPEN.   The  state  is  stored in the
   appropriate system block.  Events cause  transitions  between  states.
   An   event   is  either  an  initialization  function  call,  a  timer
   expiration, or receipt of a virtual circuit initialization datagram.

   The initialization sequence is a standard 3-way handshake  (used,  for
   example, by DECNET/DNA DDCMP).

   The initialization state table follows:


   CURRENT STATE   EVENT           ACTION                  NEW STATE


   VC_CLOSED       START call      send START              START_SENT
                                   start timer

   START_SENT      rec STACK       open port VC            VC_OPEN
                                   send ACK
                                   stop timer

                   rec START       open port VC            START_REC
                                   send STACK
                                   start timer

                   timer expires   send START              START_SENT
                                   start timer

   START_REC       rec ACK         stop timer              VC_OPEN
                   rec SCS request stop timer              VC_OPEN
                   control message 

                   rec STACK       send ACK                VC_OPEN
                                   stop timer

                   rec START       send STACK              START_REC
                                   start timer

                   timer expires   send STACK              START_REC
                                   start timer

   VC_OPEN         rec START       close port VC           VC_CLOSED
                                   notify SCS
                   rec STACK       send ACK                VC_OPEN
                   rec ACK         -                       VC_OPEN

                   VC failure      notify SCS              VC_CLOSED
                   detected
   CI PPD OPERATION                                             Page 10-5


   Notes:
|  
|       1.  The initial value of the timer is at least one second.

        2.  The port VC is opened and closed using the SETCKT command.
   CI PPD OPERATION                                             Page 10-6


   10.3  CONFIGURATION

|  The system list is built by the PPD  layer  polling  with  REQID  port
|  functions  directed  to  all  possible  destination  ports.  The IDREC
|  responses are used to fill in the system blocks.   This  procedure  is
|  repeated  periodically  to  insure  that  the  system list is current.
|  Also, any unsolicited IDREC responses received are used to fill in the
|  system blocks and path blocks.



   10.4  OTHER PPD INTERFACE FUNCTIONS

   The other PPD interface functions and  procedures  are  in  one-to-one
   correspondence with CI port commands and responses.











                                 CHAPTER 11

                              NI PPD OPERATION



   \TBS\











                                 CHAPTER 12

                              BI PPD OPERATION



   \TBS\











                                 APPENDIX A

                               PROCESS NAMING



   A process name is a 16 byte string.  A process  name  starts  with  an
   upper  case  letter  (A-Z)  or  a  dollar  sign  ($).   The  remaining
   characters can be upper case letters, numbers (0-9), dollar signs,  or
   underlines  (_) except that the last character cannot be an underline.
   Blank () characters are added to the end of the string if necessary to
   fill the string to 16 characters.

   It is intended in SCA that process names be human understandable.  The
   preferred structure for naming is as follows:

           <generic facility name>$<generic service name>

   Examples of names are:

           MSCP$DISK - MSCP disk service.
           MSCP$TAPE - MSCP tape service.
           SCS$DIRECTORY - SCS process name directory service.











                                 APPENDIX B

                             DIRECTORY SERVICE



   B.1  INTRODUCTION

   Each  system  maintains  a  directory  process   with   process   name
   SCS$DIRECTORY.

   SYSAP processes can obtain a directory of processes in  a  destination
   system  by  connecting  to  the  directory  process in the destination
   system.



   B.2  LOCAL DIRECTORY MANAGEMENT

   Process names are entered in and  deleted  from  the  local  directory
   using  SCS  level  function  calls  of the same form as the SCS or PPD
   interface.



   B.2.1  Enter

   This function enters process name in the local directory:

                   function ENTER(
                            PROC: PROC_NAME,
                            INFO: PROC_INFO):
                            FSTATUS;


   where:

       PROC            the process name to be entered.

       INFO (16 bytes) additional process information.

       FSTATUS         SUCCESS if name entered;  FAIL otherwise.
   DIRECTORY SERVICE                                             Page B-2


   B.2.2  Delete

   This function deletes a process name from the local directory:

                   function DELETE(
                            PROC: PROC_NAME):
                            FSTATUS;


   where:

       PROC            process name to be deleted.

       FSTATUS         SUCCESS  if  process  name  in  directory;    FAIL
                       otherwise.



   B.3  REMOTE DIRECTORY ACCESS

   After connecting to the remote directory process, the SYSAP  sends  an
   application  message  containing  a  lookup  request.   The  directory
   process returns a lookup response application message  containing  the
   result of the lookup operation.
   DIRECTORY SERVICE                                             Page B-3


   B.3.1  Lookup Request

   The format of the message is:


                    3               1
                    1               5             0
                   +---------------+---------------+
                   |     ENTRY     |     FORM      |
                   +---------------+---------------+
                   |                               |
                   =           PROC_NAME           =
                   |                               |
                   +-------------------------------+



   where:

       FORM            the form of directory lookup  (BY_NAME,  BY_ENTRY)
                       BY_NAME = 0, BY_ENTRY = 1.

       ENTRY           the entry number if BY_ENTRY;  ignored  otherwise:
                       entries start at one.

       PROC_NAME       the process name if BY_NAME;  ignored otherwise.
|  
|  BY_ENTRY lookup is  used  to  obtain  a  complete  list  of  directory
|  entires.   This  is  done  by specifying entry one and then succeeding
|  entry numbers until a failure status is returned indicating there  are
|  no more entries.  Entry numbers are densely assigned.
   DIRECTORY SERVICE                                             Page B-4


   B.3.2  Lookup Response

   The format of the message is:


                    3               1
                    1               5             0
                   +---------------+---------------+
                   |     ENTRY     |    STATUS     |
                   +---------------+---------------+
                   |                               |
                   =           PROC_NAME           =
                   |                               |
                   +-------------------------------+
                   |                               |
                   =           PROC_INFO           =
                   |                               |
                   +-------------------------------+



   where:

       STATUS          SUCCESS  if  a   directory   name   found;    FAIL
                       otherwise.

       ENTRY           if  SUCCESS,  the  entry  number;    UNPREDICTABLE
                       otherwise.

       PROC_NAME       if  SUCCESS,  the  process  name;    UNPREDICTABLE
                       otherwise.

       PROC_INFO (16 bytes) if SUCCESS, additional  process  information;
                       UNPREDICTABLE otherwise.











                                 APPENDIX C

                              THIRD PARTY I/O



   Third party I/O is an I/O operation involving three or  more  systems.
   Consider the following:

                                                       CI
   --------------+---------------+---------------+--------------
                 |               |               |
                 |               |               |
         +-------+------+ +------+------+ +------+-------+
         |  system X(U) | | system Y(F) | |  system Z(D) |
         +--------------+ +-------------+ +--------------+


   System X contains a file user process U.  System  Y  contains  a  file
   server  process  F.  System Z contains a disk server process D for the
   disks storing the file system.  For D to directly read block data from
   U  or  write  block  data to U for file operations the following steps
   apply:

        1.  Process U connects to F requesting file services.

        2.  F sends to U the identity of  Z  and  D  and  requests  U  to
            connect to D.

        3.  U sends to F the <D connect id, U connect id> pair.

        4.  F requests D to perform block data operations directly  to  U
            by passing (in a higher level protocol such as MSCP) a 96-bit
            qualified buffer name of the following format:
   THIRD PARTY I/O                                               Page C-2



                    3
                    1                             0
                   +-------------------------------+
                   |        SRC_CONNECT_ID         |
                   +-------------------------------+
                   |        DST_CONNECT_ID         |
                   +-------------------------------+
                   |             NAME              |
                   +-------------------------------+



   where:

       SRC_CONNECT_ID  the connect id of the process initiating the block
                       data transfers (in this example D).

       DST_CONNECT_ID  the connect id of the target  of  the  block  data
                       transfers (in this example U).

       NAME            the buffer name of the target of  the  block  data
                       transfers (in this example U).











                                 APPENDIX D

                       SCS/PPD TYPE AND LENGTH CODES




|                                                  {SCSPPDDEF}
|  
|                  { Define SCS message types codes. }
|  
|          CONNECT_REQ     = 0;                    { connect message }
|  
|          CONNECT_RSP     = 1;                    { connect response }
|  
|          ACCEPT_REQ      = 2;                    { accept connection }
|  
|          ACCEPT_RSP      = 3;                    { accept response }
|  
|          REJECT_REQ      = 4;                    { reject connection }
|  
|          REJECT_RSP      = 5;                    { reject response }
|  
|          DISCON_REQ      = 6;                    { disconnect message }
|  
|          DISCON_RSP      = 7;                    { disconnect response }
|  
|          CREDIT_REQ      = 8;                    { extend/retract credits }
|  
|          CREDIT_RSP      = 9;                    { credit response }
|  
|          APPL_MSG        = 10;                   { application message }
|  
|          APPL_DG         = 11;                   { application datagram }
|  
|                  { Define PPD message type codes. }
|  
|          START           = 0;                    { start virtual circuit }
|  
|          STACK           = 1;                    { acknowledge START }
|  
|          ACK             = 2;                    { acknowledge STACK }
|  
|          SCS_DG          = 3;                    { SCS datagram }
|  
|          SCS_MSG         = 4;                    { SCS message }
   SCS/PPD TYPE AND LENGTH CODES                                 Page D-2


|  
|          { PPD message types with the sign bit set are reserved for }
|          { implementation use and are not part of the protocol over }
|          { the interconnect. }
|  
|                  { Define SCS/PPD  message lengths }
|  
|          CONNECT_REQ_LEN = 66;
|  
|          CONNECT_RSP_LEN = 18;
|  
|          ACCEPT_REQ_LEN  = 66;
|  
|          ACCEPT_RSP_LEN  = 18;
|  
|          REJECT_REQ_LEN  = 18;
|  
|          REJECT_RSP_LEN  = 14;
|  
|          DISCON_REQ_LEN  = 18;
|  
|          DISCON_RSP_LEN  = 14;
|  
|          CREDIT_REQ_LEN  = 18;
|  
|          CREDIT_RSP_LEN  = 14;
|  
|          AP_MSG_HDR_LEN  = 14;
|  
|          AP_DG_HDR_LEN   = 14;
|  
|          START_LEN       = 42;
|  
|          STACK_LEN       = 42;
|  
|          ACK_LEN         = 6;                    {SCSPPDEND}











                                 APPENDIX E

                  REJECTION AND DISCONNECTION REASON CODES




|  There is no guarantee that additional assigned codes are  contiguously
|  assigned.   All  unassigned  values are reserved for SYSAP private use
|  and their use may overlap between different SYSAP  protocols.   Common
|  useage is encouraged, however.
|                                                  {CONREJDEF}
|  
|                  { Connection accept/reject reason codes. }
|  
|          { Message codes have two fields.  The lower three bits are }
|          { the severity and the bits 3-15 are the code. }
|  
|          { Severity values }
|  
|          { 0 = warning }
|          { 1 = success }
|          { 2 = error }
|          { 3 = reserved }
|          { 4 = severe error }
|          { 5 - 7 = reserved }
|  
|          CONNECTED       = 1;                    { general success }
|          
|          NO_MATCH        = 10;                   { no matching listen found }
|  
|          NO_RESOURCES    = 18;                   { no resources available to process request }
|  
|          DISCONNECTED    = 26;                   { connection has been broken }
|  
|          RESERVED        = 34;                   { RESERVED }
|  
|                                                  {CONREJEND}











                                 APPENDIX F

                            CI START DATA FORMAT



|          
|                   3                             
|                   1                             0
|                  +-------------------------------+
|                  |   PPD MTYPE   |   LENGTH      |
|                  +-------------------------------+
|                  |           SEND_SYS            |
|                  +---------------+               |
|                  | MBZ   | PRTVRS|               |
|                  +---------------+---------------+
|                  |    MAX_MSG    |    MAX_DG     |
|                  +---------------+---------------+
|                  |            SW_TYPE            |
|                  +-------------------------------+
|                  |           SW_VERSION          |
|                  +-------------------------------+
|                  |         SW_INCARNATION        |
|                  |                               |
|                  +-------------------------------+
|                  |            HW_TYPE            |
|                  +-------------------------------+
|                  |                               |
|                  =           HW_VERSION          =
|                  |                               |
|                  +-------------------------------+
|                  |           NODE_NAME           |
|                  |                               |
|                  +-------------------------------+
|                  |            CUR_TIME           |
|                  |                               |
|                  +-------------------------------+
|  

   where:

       SEND_SYS        the system address of the system sending the start
                       data.
   CI START DATA FORMAT                                          Page F-2


|      PRTVRS           protocol version (MBZ at this time).

       MAX_DG          the maximum datagram size (in bytes) supported  by
                       the system.

       MAX_MSG         the maximum message size (in bytes)  supported  by
                       the system.

       SW_TYPE         the type of the software in the system.  Currently
                       defined are 'VMS ','T-10', and 'T-20'.

       SW_VERSION      the version number of the software in the system.

       SW_INCARNATION  (8 bytes) the incarnation number of  the  software
                       in the system.

       HW_TYPE         the type of system hardware.
|  
|      HW_VERSION      (12  bytes)  the  version  number  of  the  system
|                      hardware.

       NODE_NAME       (8 bytes)  the  ASCII  node  name  of  the  system
                       sending the message.

       CUR_TIME        (8 bytes) the 64-bit current system  time  on  the
                       system sending the message.











                                 APPENDIX G

                             EXAMPLE CI MESSAGE



   The following figure shows  a  SYSAP  message  and  its  encapsulation
   inside of SCS, PPD, and CI Port layer headers.  This figure represents
   the send message command as presented to the CI  port  command  queue.
   The double lines indicate layer boundaries.


                    3       2       1
                    1       3       5       7     0
                   +-------------------------------+
                   |             FLINK             |    
                   +-------------------------------+
                   |             BLINK             |
                   +-------+-------+---------------+  CI PORT HEADER
                   |SWFLAG | TYPE  |    SIZE       |
                   +-------+-------+-------+-------+
                   | FLAGS | OPC   | STATUS|  PORT |
                   +=======+=======+=======+=======+
                   |   PPD MTYPE   |    LENGTH     |  PPD HEADER
                   +===============+===============+
                   |     CREDIT    |   SCS MTYPE   |
                   +---------------+---------------+
                   |    DESTINATION CONNECT ID     |  SCS HEADER
                   +-------------------------------+
                   |      SOURCE  CONNECT ID       |
                   +===============================+
                   |                               |
                   .                               .
                   .        APPLICATION MESSAGE    .  SYSAP MESSAGE
                   .                               .
                   |                               |
                   +-------------------------------+

   where:

       FLINK           command queue forward link.

       BLINK           command queue backward link.
   EXAMPLE CI MESSAGE                                            Page G-2


       SIZE            size in bytes of structure containing  the  entire
                       message (used by software only).

       TYPE            software data structure  type  (used  by  software
                       only).

       SWFLAG          software flags (used by software only).

       PORT            destination CI port number.

       STATUS          packet status on response.

       OPC             CI port opcode, e.g., SNDMSG in this case.

       FLAGS           CI command flags.

       LENGTH          number of bytes from PPD MTYPE  field  to  end  of
                       SYSAP message (this field is shared by the PPD and
                       SCS layers).

       PPD MTYPE       command type code for PPD layer, e.g., SCS_SEND in
                       this case.

       SCS MTYPE       message type for SCS layer, e.g., APPL_MSG in this
                       case.

       DESTINATION CONNECT ID connect ID of the target SYSAP process.

       SOURCE CONNECT ID connect ID of the sending SYSAP process.

       APPLICATION MESSAGE the data  to  be  transmitted  to  the  target
                       SYSAP.











                                 APPENDIX H

                              MINIMAL SUPPORT



   Subsetting of the SCS features is  allowed.   For  example,  some  SCS
   systems  may  not  implement  block transfer operations.  However, all
   systems implementing SCS must be able to:

        1.  Process the PPD start sequence.

        2.  Interpret all SCS messages.

        3.  Process all SCS control messages and provide proper response.











                                 APPENDIX I

                               CHANGE HISTORY



   Rev.  2 to Rev.  3 change history.  (All changes within change bars.)

        1.  Change data structures to  allow  for  multiple  interconnect
            paths  between systems.  Each system block now has a chain of
            path blocks, one for each intersystem path.  The system block
            and  connection  block  data structures are modified, and the
            path block data structure is added.  The SCS  message  buffer
            is now queued to the path block, and the path block is queued
            to the SCS work queue for  control  message  processing.   In
            addition,   the   following   procedures  required  interface
            modifications:

            1.  CONFIGURATION (changed to two procedures:  CONFIG_SYS and
                CONFIG_PATH)

            2.  INSERT_SCS_Q

            3.  REMOVE_SCS_Q

            4.  SNDDG

            5.  SNDMSG

            6.  SNDDAT

            7.  REQDAT

            8.  REQID

            9.  RSP_POLL

           10.  START_VC

           11.  STATE_POLL

           12.  REQ_ID

            The following required minor code changes (due  to  calls  to
            changed interfaces listed above).
   CHANGE HISTORY                                                Page I-2


            1.  ACCEPT

            2.  REJECT

            3.  CONNECT

            4.  DISCONNECT

            5.  SEND_DG

            6.  SEND_MSG

            7.  REC_MSG

            8.  CANCEL_REC_MSG

            9.  READ

           10.  WRITE

           11.  SCS_REC


        2.  Two optional parameters  are  added  to  CONNECT.   The  PATH
            parameter  allows  a  SYSAP  to  request  connection  over  a
            specific  path.   The  ERROR  parameter  provides  a  calling
            address  for  SCS  to  notify  the SYSAP on the receipt of an
            erroneous packet.

        3.  A DISCONNECT request by one side now causes the connection to
            be  closed  by  both  local  and  remote  SCSs.  A new state,
            DISCONNECT_CNF, is added to the state  diagram.   A  new  SCS
            disconnect  confirmed  control  message  and  response  pair,
            DISCNF_REQ and DISCNF_RSP, are added.   This  second  set  of
            disconnect   messages   ensure   that  all  pending  transfer
            operations  terminate   before   connection   resources   are
            released.  The following changes are made:

            1.  A new function, CB_CLOSED, is added to check  for  closed
                state of a connection.

            2.  Procedures SEND_DG, REC_DG, and REC_MSG  are  changed  to
                functions.

            3.  Functions SEND_DG, REC_DG, SEND_MSG, REC_MSG,  READ,  and
                WRITE  now  check  to verify that the connection is open.
                If the connection has been  closed,  status  NOT_OPEN  is
                returned.


        4.  All PPD and SCS maintenance commands, messages, and responses
            are removed.
   CHANGE HISTORY                                                Page I-3


        5.  The position of the  reserved  word  in  Start  Data  Format,
            Appendix G, is changed to follow the system address.

        6.  The HW_VERSION field is changed to 16 bytes.

        7.  A new appendix is added showing the format  of  a  sample  CI
            message  transmission,  including  application  message,  SCS
            header, PPD header, and CI port header.

        8.  A new appendix is added describing minimal support.

        9.  Former appendix D, Multi CI Port Support, is removed.

       10.  New connection state CLOSED_NR  is  added  to  indicate  that
            destination  had  no resources to process CONNECT, e.g., busy
            processing another connect request.   This  is  indicated  by
            NO_RESOURCES response.

       11.  Substantial style changes are made to  the  Pascal  code  and
            specification.


   Rev.  3 to Rev.  4 change history.  (included in Rev.  3 change bars)

        1.  Change disconnect protocol to require both  SYSAPs  to  issue
            DISCONNECT  requests  before the connection is shutdown.  The
            new protocol  uses  only  two  messages,  DISCONNECT_REQ  and
            DISCONNECT_RSP,  but  introduces  states DISCONNECT_MATCH and
            DISCONNECT_ACK.  The following sections required changes:

            1.  Section 6.1, Type Definitions, was modified  to  add  the
                new states to the C_STATE definition.

            2.  Section 6.3, Connection Management Services, was modified
                to add the new states and a description of the disconnect
                protocol.

            3.  Section  6.3.5,  Disconnect   call   in   the   SYSAP-SCS
                interface, was changed to note that only the calling side
                is prohibited from transmitting further messages.

            4.  Former Sections 8.2.9 and 8.2.10 of Version 3, describing
                the Disconnect Confirmation messages, were removed.

            5.  Section 9.6.2, Connection States in  SCS  Operation,  was
                modified.   The  connection  state  table  was changed to
                reflect the new protocol, and the  description  following
                that   table   was   modified   to  note  the  disconnect
                requirements for multi-priority ports.

            6.  Section 9.6.7, Disconnect procedure  code,  was  modified
                because disconnect can be called in one of two states.
   CHANGE HISTORY                                                Page I-4


            7.  Section 9.10, the SCS Send procedure code, was  modified.
                The  DISCONNECT_PEND code was changed (only the comments)
                to note the possible current states.

            8.  Section 9.11, SCS Receive procedure code,  was  modified.
                The  DISCNF_REQ  and  DISCNF_RSP  code  from Rev.  3 were
                removed.  The DISCON_REQ and DISCON_RSP code was modified
                to show the path for various connection states.


        2.  The Start/Stack Data Format, Appendix F, is  changed  to  add
            two  new  fields.   The  CUR_TIME  field  is added to provide
            system time for initializing nodes that do not have a  clock.
            The  NODE_NAME  field  specifies  the  ASCII node name of the
            sender.

        3.  The System Block  data  structure  is  modified  to  add  the
            NODE_NAME field.

        4.  The CONFIG_SYS function, Section 6.2.1, is changed to add the
            NODE_NAME return parameter.

|  
|  Rev.  4 to Rev.  5 change history.  (change bars include only Rev.   5
|  changes)
|  
|       1.  Contrasting of architecture and functional specifications  in
|           Introduction.
|  
|       2.  Remove reference to requirements for supporting clusters with
|           multiple CI's.
|  
|       3.  Describe SW_INCARNATION in system block.
|  
|       4.  Remove CLOSED_NM, _NR,  _REJ  and  _VC  states  leaving  only
|           CLOSED.    Add   CONNECT_ACK,  ACCEPT_SENT,  and  REJECT_SENT
|           states.   Update  description  in  section   6.3   Connection
|           management  services  and  pascal code to reflect these state
|           changes.
|  
|       5.  Rename PTR to CREDITS in CONNECT and ACCEPT calls.
|  
|       6.  Remove THRSH from LISTEN and put it in ACCEPT.
|  
|       7.  Remove ERROR from CONNECT call.
|  
|       8.  State that datagrams  are  queued  and  accounted  for  on  a
|           connection  by  connection  basis  in  section  6.4  Datagram
|           service.
|  
|       9.  State that an implementation "MUST" provide a  provision  for
|           canceling   block   data  transfers,  but  that  there  is  a
|           restriction due to design of CI port hardware.   Section  6.6
|           block data service.
   CHANGE HISTORY                                                Page I-5


|      10.  Describe need for MPTR1 and MPTR2 and DPTR in START_VC  call.
|           Section 7.3.1 Start Virtual Circuit.
|  
|      11.  Remove REQ_ID and REQID functions from PPD interface.
|  
|      12.  Rewrite section 9.6.2 Connection States to reflect reality.
|  
|      13.  Define PPD message type codes with sign bit set  as  reserved
|           for an implementation to use internally.
|  
|      14.  Change definitions of reject and disconnect reason  codes  to
|           include more codes and severity encoding.
|  
|      15.  Change definition of Start Data format  to  include  protocol
|           version field and remove 4 bytes from the HW_VERSION.
|  
|      16.  Define the credit management variables a little better.
|  
|      17.  Explain START/STACK  operation  with  protocol  mismatch  for
|           later use.
|  
|      18.  Fix the pascal  program  to  store  something  in  REQ_CREDIT
|           before using the value stored there.
|  
|      19.  Minor updates.
|  
|  
|  Rev.  5 to Rev.  6 changes (included in Rev.  5 change bars)
|  
|       1.  Describe rules for verifying minimum message size  for  SYSAP
|           protocol.  Section 6.3.
|  
|       2.  Define BY_NAME and BY_ENTRY in section B.3.1.
|  
|       3.  Make statement about REJECT and DISCONNECT  reason  codes  in
|           appendix E.  Reserve code 34.
|  


















                          Functional description of the
                       Systems Communications Architecture

                                    21-Nov-83

                              Version 1, Revision 5
   SCA Functional specification                                         Page 2


     1.0  Revision history

     Revision 1:

     1.  Change user interface for packet sends to reflect data  being  copyed
         rather than mapped into monitor space.

     2.  Add set port counters function (.SSSPC)

     3.  Add configuration change PSI channel to .SSAIC JSYS function.


          Note: There are no change bars for this revision. Change bars
             will begin with the next revision of the specification.



     Revision 2:

     Update path specification handling in  .SSSDG  and  .SSSMG  functions  of
     SCS%.



     Revision 3:

     Make maintainance data send and receive work correctly.



     Revision 4:

     Fix additional problems with maintainance data send and receive.



     Revision 5:

     Add user level maintainance functions for reset/start  a  remote  system.
     Also add "monotonic counter" to set/read port counter calls.
   SCA Functional specification                                         Page 3


     2.0  Table of Contents

           1.0     Revision history . . . . . . . . . . . . . . . . . . 2
           2.0     Table of Contents  . . . . . . . . . . . . . . . . . 3
           3.0     Definitions  . . . . . . . . . . . . . . . . . . . . 5
           4.0     Introduction . . . . . . . . . . . . . . . . . . . . 6
           4.1       Related documents  . . . . . . . . . . . . . . . . 6
           4.2       Scope  . . . . . . . . . . . . . . . . . . . . . . 6
           4.3       Module interactions  . . . . . . . . . . . . . . . 7
           4.4       SCA overview . . . . . . . . . . . . . . . . . . . 9
           4.5       General differences  . . . . . . . . . . . . . . . 9
           4.5.1       TOPS-20 only functionality . . . . . . . . . . . 9
           4.6       Service required of PHYKLP . . . . . . . . . . .  11
           4.7       PHYKLP interface . . . . . . . . . . . . . . . .  12
           4.8       Data structures  . . . . . . . . . . . . . . . .  17
           4.8.1       System block . . . . . . . . . . . . . . . . .  17
           4.8.2       Connect block  . . . . . . . . . . . . . . . .  20
           4.8.3       Connect ID . . . . . . . . . . . . . . . . . .  23
           5.0     Writing a monitor SYSAP  . . . . . . . . . . . . .  24
           5.1       General rules  . . . . . . . . . . . . . . . . .  24
           5.1.1       Buffer allocation and management . . . . . . .  24
           5.1.2       Starting a connection  . . . . . . . . . . . .  26
           5.1.3       Global interlocks  . . . . . . . . . . . . . .  28
           5.2       Messages . . . . . . . . . . . . . . . . . . . .  29
           5.2.1       Receiving messages . . . . . . . . . . . . . .  29
           5.2.2       Sending messages . . . . . . . . . . . . . . .  29
           5.3       Datagrams  . . . . . . . . . . . . . . . . . . .  29
           5.3.1       Receiving datagrams  . . . . . . . . . . . . .  29
           5.3.2       Sending datagrams  . . . . . . . . . . . . . .  30
           5.4       Named buffers  . . . . . . . . . . . . . . . . .  30
           5.5       Monitor SYSAP interface  . . . . . . . . . . . .  31
           5.5.1       SYSAP to SCA interface . . . . . . . . . . . .  31
           5.5.1.1       Connect (SC.CON) . . . . . . . . . . . . . .  31
           5.5.1.2       Listen (SC.LIS)  . . . . . . . . . . . . . .  32
           5.5.1.3       Accept (SC.ACC)  . . . . . . . . . . . . . .  35
           5.5.1.4       Reject (SC.REJ)  . . . . . . . . . . . . . .  36
           5.5.1.5       Disconnect (SC.DIS)  . . . . . . . . . . . .  37
           5.5.1.6       Abort (SC.ABT) . . . . . . . . . . . . . . .  38
           5.5.1.7       Send datagram (SC.SDG) . . . . . . . . . . .  38
           5.5.1.8       Queue datagram receive buffers (SC.RDG)  . .  40
           5.5.1.9       Send a message (SC.SMG)  . . . . . . . . . .  41
           5.5.1.10      Queue message receive buffers (SC.RMG) . . .  42
           5.5.1.11      Cancel datagram receive buffer (SC.CRD)  . .  43
           5.5.1.12      Cancel message receive buffers (SC.CRM)  . .  43
           5.5.1.13      Map a named buffer (SC.MAP)  . . . . . . . .  44
           5.5.1.14      Unmap a buffer (SC.UMP)  . . . . . . . . . .  46
           5.5.1.15      Send named buffer data (SC.SND)  . . . . . .  47
           5.5.1.16      Request remote named buffer transfer (SC.REQ) 48
           5.5.1.17      Connect state poll (SC.CSP)  . . . . . . . .  49
           5.5.1.18      Return destination connect ID (SC.DCI) . . .  50
           5.5.1.19      Return system configuration data (SC.RCD)  .  51
           5.5.1.20      Reset a remote system (SC.RST) . . . . . . .  52
           5.5.1.21      Start a node (SC.STA)  . . . . . . . . . . .  53
           5.5.1.22      Set port counters (SC.SPC) . . . . . . . . .  54
           5.5.1.23      Read port counters (SC.RPC)  . . . . . . . .  55
   SCA Functional specification                                    Page 4


           5.5.1.24      Maintainance data send (SC.MDS)  . . . . . .  56
           5.5.1.25      Maintainance data read (SC.MDR)  . . . . . .  57
           5.5.1.26      Set online address (SC.SOA)  . . . . . . . .  58
           5.5.1.27      Swap bytes from 11 to 10 format (SC.ISW) . .  59
           5.5.1.28      SC.OSW (Swap word from 10 to 11 forma  . . .  60
           5.5.1.29      Return node number given CID (SC.SBI)  . . .  61
           5.5.1.30      Return credit info (SC.RAC)  . . . . . . . .  62
           5.5.1.31      Return local port number (SC.PRT)  . . . . .  63
           5.5.1.32      Allocate a datagram buffer (SC.ALD)  . . . .  64
           5.5.1.33      Allocate a message buffer (SC.ABF) . . . . .  65
           5.5.1.34      Return a message buffer (SC.RBF) . . . . . .  66
           5.5.1.35      Return a datagram buffer (SC.RLD)  . . . . .  66
           5.5.2       SCA to SYSAP interface . . . . . . . . . . . .  67
           6.0     Writing a JSYS SYSAP . . . . . . . . . . . . . . .  72
           6.1       General rules  . . . . . . . . . . . . . . . . .  72
           6.1.1       Communicating with SCA . . . . . . . . . . . .  72
           6.1.1.1       Using the SCS% with the PSI system . . . . .  72
           6.1.2       Buffer management  . . . . . . . . . . . . . .  72
           6.1.2.1       Incoming buffers . . . . . . . . . . . . . .  72
           6.1.2.2       Outgoing buffers . . . . . . . . . . . . . .  73
           6.1.3       The race condition . . . . . . . . . . . . . .  73
           6.2       JSYS SYSAP interface . . . . . . . . . . . . . .  74
           6.2.1       Connect (.SSCON) . . . . . . . . . . . . . . .  75
           6.2.2       Listen (.SSLIS)  . . . . . . . . . . . . . . .  77
           6.2.3       Accept (.SSACC)  . . . . . . . . . . . . . . .  78
           6.2.4       Reject (.SSREJ)  . . . . . . . . . . . . . . .  79
           6.2.5       Disconnect (.SSDIS)  . . . . . . . . . . . . .  80
           6.2.6       Send a DG (.SSSDG) . . . . . . . . . . . . . .  81
           6.2.7       Queue a DG buffer (.SSQRD) . . . . . . . . . .  82
           6.2.8       Send message (.SSSMG)  . . . . . . . . . . . .  83
           6.2.9       Queue message receive buffers (.SSQRM) . . . .  84
           6.2.10      Cancel DG receive (.SSCRD) . . . . . . . . . .  85
           6.2.11      Cancel receive message (.SSCRM)  . . . . . . .  86
           6.2.12      Connect state poll (.SSCSP)  . . . . . . . . .  87
           6.2.13      Return local node number (.SSGLN)  . . . . . .  88
           6.2.14      Return configuration data (.SSRCD) . . . . . .  89
           6.2.15      Return buffer sizes (.SSRBS) . . . . . . . . .  91
           6.2.16      Return status information (.SSSTS) . . . . . .  92
           6.2.17      Get a queue entry  . . . . . . . . . . . . . .  93
           6.2.17.1      Receive a message (.SSRMG) . . . . . . . . .  93
           6.2.17.2      Receive a datagram (.SSRDG)  . . . . . . . .  94
           6.2.17.3      Get entry from data queue (.SSGDE) . . . . .  95
           6.2.17.4      Get an entry off the event queue (.SSEVT)  .  96
           6.2.18      Named buffer overview  . . . . . . . . . . . .  98
           6.2.19      Map a buffer (.SSMAP)  . . . . . . . . . . . .  99
           6.2.20      Unmap a buffer (.SSUMP)  . . . . . . . . . . . 101
           6.2.21      Send data (.SSSND) . . . . . . . . . . . . . . 102
           6.2.22      Request data (.SSREQ)  . . . . . . . . . . . . 103
           6.2.23      Maintainance data send (.SSMDS)  . . . . . . . 104
           6.2.24      Maintainace data read (.SSMDR) . . . . . . . . 105
           6.2.25      Start a remote system (.SSSRS) . . . . . . . . 106
           6.2.26      Reset a remote system (.SSRRS) . . . . . . . . 107
           6.2.27      Set port counters (.SSSPC) . . . . . . . . . . 108
           6.2.28      Read port counters (.SSRPC)  . . . . . . . . . 109
           6.2.29      Add interrupt channels (.SSAIC)  . . . . . . . 110
   SCA Functional specification                                    Page 5


     3.0  Definitions

          There are a number of terms and concepts vital to  an  understanding
     of SCA.  They are:

     1.  Credit - Credit refers to buffers queued for message (only  messages,
         there  is  no credit system for datagrams) reception or transmission.
         Receive credit is the number  of  buffers  you  have  queued  to  get
         messages  from  a  remote node.  Send credit is the number of buffers
         the remote has queued to receive messages from you.

     2.  Callback - The callback is the mechanism through which SCA interrupts
         a  SYSAP.   For  example,  when a message or datagram has arrived for
         your connection, SCA will PUSHJ to the address given in the  CONNECT,
         LISTEN,  or set online notification address call, with T1-T4 setup to
         point to the new packet.

     3.  Port queues - This refers to the set of queues used by the monitor to
         communicate  with  the  KLIPA.   These queues include the message and
         datagram free queues, into which all inbound packets are placed.

     4.  Packet - Term used to denote any CI packet,  I.E.   a  message  or  a
         datagram.

     5.  Circuit - Virtual communications path layered on top of the  CI  wire
         (I.E.  hardware path) maintained by the port driver.

     6.  Connection - Virtual communications path layered on top  of  circuits
         and maintained by SCA.
   SCA Functional specification                                    Page 6
   Introduction


     4.0  Introduction

     4.1  Related documents

          The reader should at least be familiar with the following  documents
     before  proceeding  with  this  specification.  The corporate SCA spec is
     particularly important as all terminology used in this  document  follows
     standards set in the corporate spec.

     1.  Systems Communications Architecture, Rev 4, 20-July-82 (Strecker)

     2.  LCG CI Port Architecture Specification, 11-July-83 (Dossa/Keenan)

     3.  TOPS-20   KLIPA   Driver    Functional    Specification,    19-Aug-83
         (Grant/Miller)

     4.  TOPS-20 Coding Standard, 23-Mar-83 (Murphy)




     4.2  Scope

          This document will describe the interfaces in and out of the Systems
     Communications  Architecture  (SCA).   This  includes  the user interface
     through the SCS% JSYS.  Some of the functions invisible to  the  rest  of
     the  monitor,  yet important to the overall scheme of the CI software are
     also  covered.   Implementation  details   are   left   to   the   design
     specification however.
   SCA Functional specification                                    Page 7
   Introduction


     4.3  Module interactions

          The following diagram illustrates the layout of the CI software  and
     hardware.



                               --------              ---------
                               ! SCS% !              ! DIAG% !
                               --------              ---------      User mode
                                   !                     /
     -       -       -       -     ! -       -       -  /   -        -       -
                    --------   --------  -------       /             
                    ! MSCP !   !SCSJSY!  ! CFS !      /             Monitor mode
                    --------   --------  -------     /
                         \         !        /       /
                          \        !       /       /
                           \       !      /       /
                           -----------------     /
                           !      SCA      !-----
                           -----------------     
                                   !             
                            ---------------     
                            ! Port driver !
                            ---------------     
                                   !
                                   !                                Software
                                   !
     -       -       -       -       -       -       -       -       -       -
                                   !
                                   !                                Hardware
                            ---------------
                            !    KLIPA    !
                            ---------------
                                   !
                 CI                !             
              ==========================================


          Briefly, these are the functions performed by each of  the  software
     modules listed above.

     The  port  driver  is  the  hardware  controller  for  the   KLIPA.    It
     communicates  with  the  device  through  a queued protocol using KL main
     memory.

     SCA is the CI gateway for the rest of the monitor.  The only exception is
     the  DIAG  JSYS which has the capability of disabling the port driver and
     taking direct control of the hardware.  In general  however  all  monitor
     components access the CI through SCA.

     System applications (SYSAP) are the  end  users  of  the  CI.   The  Mass
     Storage  Control  Protocol  (MSCP)  is a CI disk controller.  Common File
     System (CFS) is the global file lock manager for implementing distributed
   SCA Functional specification                                    Page 8
   Introduction


     access to CI disks and dual ported massbus disks.
   SCA Functional specification                                    Page 9
   Introduction


     4.4  SCA overview

          The overall function of  SCA  can  best  be  described  as  software
     multiplexer,  demultiplexer  for  the CI.  SCA is the module that creates
     the illusion of virtual connections over the circuits established by  the
     port  driver.   A  detailed description of how SCA performs this function
     can be found in [1].  What needs to be detailed here is exactly what  has
     been  done  that is specific to TOPS-20 and hence could never be outlined
     in the corporate specification.



     4.5  General differences

          In general, the corporate specification is considered to be a  model
     in which the seeds of the TOPS-20 implementation may be found.  There are
     a number of global differences that need to be outlined.

     1.  The corporate specification uses polling to determine the  completion
         of a request.  The TOPS-20 implementation is interrupt driven.

     2.  TOPS-20 does not use the suggested format for connection  and  system
         blocks.  Additional words were required and all support locations for
         path blocks were removed.

     3.  The most important difference is the lack of the  "path"  concept  in
         TOPS-20.   The  corporate specification calls for the use of multiple
         paths to a single node.   (Note  that  this  is  not  the  dual  rail
         concept,  I.E.   Path  A  and  Path B) The entire concept of multiple
         paths to a single node is dissallowed  in  TOPS-20.   All  nodes  are
         directly connected to all other nodes by exactly one logical path.  A
         logical path is a port onto a CI, even though the port may have  more
         than one cable on it.

         TOPS-20 does not  support  paths  because  the  KL-10  processor  can
         currently support only one KLIPA.  Since there is one KLIPA there can
         by definition only be one path to a node.  When more than  one  KLIPA
         is supported the issue of paths will be addressed.




     4.5.1  TOPS-20 only functionality

          At present, there is only one function of SCA that is  seen  by  the
     outside  world  and  not  covered  by  the corporate specification.  This
     function is the periodic polling of nodes  with  open  connections.   The
     need  for  this service arises from the fact that the KLIPA answers REQID
     packets without software intervention.  Since port level pollers for most
     machines  use  REQID  packets to test the rails to the other nodes on the
     net, a system could suffer a complete software failure and no  one  would
     detect  it  until the port were reset during the BOOT process.  There are
     SYSAPs that need to see remote software failures much sooner  than  this.
     Hence  SCA  will  send credit requests for zero credit to nodes that have
   SCA Functional specification                                   Page 10
   Introduction


     not sent the local node a message for a  certain  time  period.   If  the
     response  comes  back  within  a certain time then the node is up and SCA
     simply marks the fact the the credit request received a response.  If the
     response  does  not come back within the defined time period, the node is
     declared offline, SCA requests that the port to port virtual  circuit  be
     broken, and all SYSAP's are notified of the remote node failure.
   SCA Functional specification                                   Page 11
   Introduction


     4.6  Service required of PHYKLP

          Since PHYKLP maintains direct control over the hardware,  there  are
     services required of PHYKLP by SCA.  These services are:

     1.  ULNKDG -- Remove a buffer from the datagram free queue.

     2.  ULNKMG -- Remove a buffer from the message free queue.

     3.  SNDDG -- Send a datagram

     4.  SNDMSG -- Send a message

     5.  LNKMFQ -- Link a buffer chain onto the message free queue

     6.  LNKDFQ -- Link a buffer chain onto the datagram free queue

     7.  CLOSVC -- Close a virtual circuit

     8.  MAPBUF -- Map a named buffer

     9.  UMAP -- Unmap a named buffer

    10.  SNDDAT -- Start a named buffer data send

    11.  REQDAT -- Start a named buffer data receive

    12.  LOCPRT -- Return the local node number

    13.  KLPOPN -- Open a circuit

    14.  PPDSRS -- Send a reset or start maintainance packet

    15.  PPDSMD -- Do a maintainance data send

    16.  PPDRMD -- Do a maintainace data read

    17.  PPDRPT -- Read port counters

    18.  PPDSPT -- Set port counters

    19.  STRPOL -- Start the poller

    20.  STPPOL -- Stop the poller

    21.  STRKLP -- Start the KLIPA

    22.  STPKLP -- Stop the KLIPA
   SCA Functional specification                                   Page 12
   Introduction


     4.7  PHYKLP interface

          Direct control over the CI is done  by  the  port  driver  (PHYKLP).
     Hence SCA must interface to the port driver to perform its function.  The
     following is the set of SCA entry points understood by the port driver.

                                 - SC.INT -

          This routine is called when the port driver has  received  a  packet
     bound for SCA.


             Call

             BLCAL. (SC.INT,<SS.PKA,SS.SBA,SS.FLG,SS.LEN>)

             Where:
             SS.PKA - Address of message/datagram/SCA buffer
             SS.SBA - Address system block

             SS.FLG - Flags
                      F.SPM - Packet data mode       0 - Industry compatable mode
                                                     1 - High density mode

                      F.RSP - Local or remote packet 0 - Remote packet
                                                     1 - Localy generated packet

             SS.LEN - Length of packet in bytes (for industry compatible packets)
                    - Length in words for high density packets

             Return (+1)
             T1/     Error code

             Return (+2)
             No data returned, all went well
   SCA Functional specification                                   Page 13
   Introduction


                                 - SC.MDC -

          This routine is called by the port driver when a  maintainance  data
     transfer has completed.

             Call
             BLCAL. (SC.MDC,<SS.ADR,SS.NAM>)

             Where:
             SS.ADR -- Address passed to PHYKLP on SC.MDS/SC.MDR call
             SS.NAM -- Local name for transfer which has completed


             Return (+1)
             T1/     Error code

             Return (+2)
             No data returned
   SCA Functional specification                                   Page 14
   Introduction


                                 - SC.DMA -

          This routine handles the completion of a named buffer transfer.

             Call
             BLCAL. (SC.DMA,<SS.CID,SS.SBA,SS.NAM>)

             Where:
             SS.CID -- CID of connection we did this for
             SS.SBA -- Address of system block
             SS.NAM -- Buffer name for transfer that completed


             Return (+1)
             T1/     Error code

             Return (+2)
             No data returned
   SCA Functional specification                                   Page 15
   Introduction


                                 - SC.ERR -

          This routine is called to notify SCA of a virtual  circuit  closure.
     This includes closures requested by SCA.

             Call

             BLCAL. (SC.ERR,<SS.NOD>)

             Where:
             SS.NOD --> Node number of the system who's VC just went away.

             Return (+1)
             T1/     Error code

             Return (+2)
             No data returned


                                 - SC.ONL -

          This routine is called when a node has come online.

             Call
             BLCAL. (SC.ONL,<SS.NOD>)

             Where:
             SS.NOD -- Node number of system that has come online

             Return (+1)
             T1/     Error code

             Return (+2)
             No data returned


                                 - SC.OFL -

          This routine is called when a system has gone  offline.   Note  that
     SCA  assumes  the  data for this node has not been cleaned up by the port
     driver.

             Call
             BLCAL. (SC.OFL,<SS.NOD>)

             Where:
             SS.NOD -- Node number of the system that has gone offline

             Return (+1)
             T1/     Error code

             Return (+2)
             No data returned
   SCA Functional specification                                   Page 16
   Introduction


                                 - SC.PRC -

          This  routine   is   called   when   the   port   detects   that   a
     READ-PORT-COUNTERS command has completed.

             Call

             BLCAL. (SC.PRC,<SS.CID,SS.ADR>)

             Where:
             SS.CID -- CID for whom the register read was done
             SS.ADR -- Address of counter data packet

             Return (+1)
             T1/     Error code

             Return (+2)
             No data returned
   SCA Functional specification                                   Page 17
   Introduction


     4.8  Data structures

          To perform its function as multiplexer/demultiplexer SCA maintains a
     set  of  connections  over  the  virtual  circuits maintained by the port
     driver.   There  are  two  blocks  basic  to  the  maintenance  of  these
     connections, the system block and the connect block.



     4.8.1  System block

          The system block is a data structure shared with  the  port  driver.
     In fact the port driver owns most of the block.


             !=======================================================!
      .SBANB !             Address of next system block              !
             !-------------------------------------------------------!
      .SBAPB !       Address of associated port control block        !
             !-------------------------------------------------------!
      .SBACD !       Address of associated channel data block        !
             !-------------------------------------------------------!
      .SBVCS !    Path validity info     !    Dest vir cir state     !
             !-------------------------------------------------------!
      .SBDSP !                   Destination port                    !
             !-------------------------------------------------------!
      .SBDRQ !             Datagram return queue header              !
             !-------------------------------------------------------!
      .SBLMB !              Local message buffer header              !  *
             !-------------------------------------------------------!
      .SBFCB !           Pointer to first connection block           !  *
             !-------------------------------------------------------!
      .SBLCB !            Pointer to last connection block           !  *
             !-------------------------------------------------------!
      .SBTWQ !                FLINK for SCA work queue               !  *
             !-------------------------------------------------------!
      .SQBWQ !                BLINK for SCA work queue               !  *
             !-------------------------------------------------------!
      .SBQOR !      Pointer to queue of outstanding requests         !
             !-------------------------------------------------------!
      .SBDSS \                                                       \
             \                  Destination system                   \
             \                                                       \
             !-------------------------------------------------------!
      .SBMMS !   Max mess size (bytes)   !    Max DG size (Bytes)    !
             !-------------------------------------------------------!
      .SBDST !               Destination software type               !
             !-------------------------------------------------------!
      .SBDSV !             Destination software version              !
             !-------------------------------------------------------!
      .SBDSE !           Destination software edit level             !
             !-------------------------------------------------------!
   SCA Functional specification                                   Page 18
   Introduction


             !-------------------------------------------------------!
      .SBDHT !               Destination hardware type               !
             !-------------------------------------------------------!
      .SBDHV !              Destination hardware version             !
             !-------------------------------------------------------!
      .SBDPC \                                                       \
             \           Destination port characteristics            \
             \                                                       \
             !-------------------------------------------------------!
      .SBTIM !        TODCLK at last message from this remote        !  *
             !-------------------------------------------------------!
      .SBFLG !                       Flags                           !  *
             !-------------------------------------------------------!
      .SBTBQ !     Address of first buffer on buffer defer queue     !  *
             !-------------------------------------------------------!
      .SBBBQ !     Address of last buffer on buffer defer queue      !  *
             !=======================================================!


          Most of the cells in this  structure  are  maintained  by  the  port
     driver.   There  are  a few however that are the exclusive domain of SCA.
     These are described below.

     .SBLMB
     The local message buffer header is an interlock location for this remote.
     Since  all SCA messages are flow controled, some method had to be arrived
     at for flow control of SCA overhead messages.  This  is  done  by  always
     having  just one receive credit available for each remote node.  Hence we
     cannot send more than one overhead message at  a  time  to  a  particular
     node.   Hence  this  location is used to flag the fact that a request has
     been sent to the host.  Note that when non-zero, this  location  contains
     the  message  type that is expected in response to the request we believe
     is outstanding.

     .SBFCB/.SBLCB
     The pointer to the first and last connect blocks are the FLINK and  BLINK
     for  one  set  of threads to the connect blocks.  Each connect block is a
     member of two doubly linked lists.  One is the list of connections  to  a
     system,  the  other  is  the list of connects owned by a fork.  Note that
     unless the fork has done an SCS% JSYS, this second list is empty.

     .SBTWQ/.SBBWQ
     Something must be done with the requests that need to be sent to a system
     which  already  has  a request outstanding.  These requests are placed on
     the work queue for that system.  The  work  queue  FLINK  and  BLINK  are
     stored in the system block.

     .SBTIM
     A function performed by SCA is the polling of remote  systems  that  have
     connections  open  to  them.   This  polling  is  done to detect a remote
     software stoppage.  .SBTIM is TODCLK the last time the node talked to us.
     For further details on this process, see the section on SC.CLK.

     .SBFLG
   SCA Functional specification                                   Page 19
   Introduction


     Currently, the only defined flags are the timed  message  flag,  and  the
     circuit  requires  opening  flag.   When the timed message flag is lit in
     .SBFLG, a timed message is outstanding for this node.  SCA uses this flag
     to  help  determine  if  a  node  should  be  declared dead.  The circuit
     requires opening flag indicates that the circuit has been closed and just
     as  soon  as  databases  have  been  cleaned up, SCA should call the port
     driver to open the circuit again.

     .SBTBQ/.SBBBQ
     These words are the head and tail pointers for the queue of buffer  defer
     requests.   This  queue  is  used by SCA to handle the allocation of more
     buffers than it has on hand.
   SCA Functional specification                                   Page 20
   Introduction


     4.8.2  Connect block

          The other data structure used by SCA is the connect block.   As  the
     name  implies  this  block  is the complete set of information maintained
     about an SCA connection.


              !=======================================================!
       .CBANB !     Address of next connection block for this SB      !
              !-------------------------------------------------------!
       .CBAPB !   Address of previous connection block for this SB    !
              !-------------------------------------------------------!
       .CBJNB !     Address of next connection block for this fork    !
              !-------------------------------------------------------!
       .CBJPB !   Address of previous connection block for this fork  !
              !-------------------------------------------------------!
       .CBSTS !        Block state        !       Connect state       !
              !-------------------------------------------------------!
       .CBFLG !                        Flags                          !
              !-------------------------------------------------------!
       .CBSCI !                   Source connect ID                   !
              !-------------------------------------------------------!
       .CBDCI !                Destination connect ID                 !
              !-------------------------------------------------------!
       .CBSPN \                                                       \
              \                  Source process name                  \
              \                                                       \
              !-------------------------------------------------------!
       .CBDPN \                                                       \
              \               Destination process name                \
              \                                                       \
              !-------------------------------------------------------!
       .CBDTA \                                                       \
              \              User supplied connect data               \
              \                                                       \
              !-------------------------------------------------------!
       .CBREA !        Dest reason        !       Source reason       !
              !-------------------------------------------------------!
       .CBMCD !      Min send Credit      !    Min Receive credit     !
              !-------------------------------------------------------!
       .CBRCD !                    Receive Credit                     !
              !-------------------------------------------------------!
       .CBSCD !                     Send credit                       !
              !-------------------------------------------------------!
       .CBNPO !       Number of packets still on port command Q       !
              !-------------------------------------------------------!
       .CBRQC !                   Requeue credit                      !    
              !-------------------------------------------------------!
       .CBPRC !                 Pending rec credit                    !
              !-------------------------------------------------------!
       .CBSBA !      Pointer to system block for this connection      !
              !-------------------------------------------------------!
       .CBADR !      Address to call SYSAP on certain conditions      !
              !-------------------------------------------------------!
   SCA Functional specification                                   Page 21
   Introduction


              !-------------------------------------------------------!
       .CBCDD !             Number of dropped datagrams               !
              !-------------------------------------------------------!
       .CBDGR !           Number of real DG buffers queued            !
              !-------------------------------------------------------!
       .CBDGJ !           Number of JSYS DG buffers queued            !
              !-------------------------------------------------------!
       .CBSBI !               Destination node number                 !
              !-------------------------------------------------------!
       .CBFRK !  Job number of owner job  ! Fork number of owner fork !
              !-------------------------------------------------------!
       .CBTMQ !  Pointer to top of message available queue (for JSYS) !
              !-------------------------------------------------------!
       .CBBMQ !  Pointer to bot of message available queue (for JSYS) !
              !-------------------------------------------------------!
       .CBTDQ !  Pointer to top of datagram available queue (for JSYS)!
              !-------------------------------------------------------!
       .CBBDQ !  Pointer to bot of datagram available queue (for JSYS)!
              !-------------------------------------------------------!
       .CBTXQ !     Pointer to top of the DMA xfer complete queue     !
              !-------------------------------------------------------!
       .CBBXQ !     Pointer to bot of the DMA xfer complete queue     !
              !-------------------------------------------------------!
       .CBTEQ !          Pointer to top of the event queue            !
              !-------------------------------------------------------!
       .CBBEQ !          Pointer to bot of the event queue            !
              !-------------------------------------------------------!
       .CBTBQ !       Pointer to first buffer descriptor block        !
              !-------------------------------------------------------!
       .CBBBQ !       Pointer to  last buffer descriptor block        !
              !-------------------------------------------------------!
       .CBPS0 !  PSI channel for messages ! PSI channel for datagrams !
              !-------------------------------------------------------!
       .CBPS1 !    PSI channel for DMA    !  PSI channel for events   !
              !=======================================================!


          Of the above cells, a few are returned by  SCA  on  certain  routine
     calls.   The  following  is  a  description  of  the  cells  that  are of
     importance to a SYSAP.

     .CBSTS
     If non-zero, the block state indicates the connection is  waiting  for  a
     response  to a request.  The block state also indicates what the response
     will be.  These are the currently defined block states:

             .BSCNP --> Connect pending
             .BSACP --> Accept pending
             .BSCRP --> Credit pending
             .BSRPN --> Reject pending
             .BSDPN --> Disconnect pending

     As the name may indicate, the  connection  state  indicates  the  current
     state of the connect.  The following are the currently defined connection
   SCA Functional specification                                   Page 22
   Introduction


     states.
             .CSDRE --> Disconnect received
             .CSDSE --> Disconnect sent
             .CSDAK --> Disconnect acknowledge
             .CSDMC --> Disconnect match

             .CSCLO --> Closed - by command
             .CSCNM --> Closed - no match
             .CSCRJ --> Closed - rejection
             .CSCNR --> Closed - no resources
             .CSCVC --> Closed - Port virtual circuit error

             .CSLIS --> Listening

             .CSCSE --> Connect sent
             .CSCAK --> Connect acknowledge
             .CSCRE --> Connect received

             .CSOPN --> Connection open


     .CBFLG
     The flags word supports flags for both SCA and the SCS% JSYS.  These  are
     the currently defined flags:

             CBFNNC --> Credit has come available since ntofication of credit low
             CBFJSY --> This is a JSYS initiated connect block
             CBFABT --> CB has been aborted
             CBFRAP --> CB is to be reaped
             CBFDCL --> This was don't care listener
             CBFKIL --> Owning fork has gone away (JSYS connect only)

     .CBSCI
     This is the  source  connect  ID.   This  is  the  local  name  for  this
     connection.

     .CBDCI
     This is the remote connect ID.  This name is what the  remote  calls  the
     connection.

     .CBSPN/.CBDPN
     These are the local and remote process names in 8 bit ASCII.

     .CBDTA
     This is the initial connection data sent during the handshake for opening
     the connection.  It is always the data sent to us by the remote.

     .CBREA
     These are the remote and local disconnect reasons.  When a disconnect  is
     started,  the  local code is transmitted as the cause for the disconnect.
     When the disconnected is initiated remotely, the  destination  reason  is
     stored from the disconnect request packet.

     .CBRCD/.CBSCD
   SCA Functional specification                                   Page 23
   Introduction


     These cells contain the current credit levels for this  connection.   The
     receive  credit  reflects  the number of buffer queued on this system for
     the reception of message from the remote.  The send credit is the  number
     of buffers the remote has queued for receiving localy generated messages.



     4.8.3  Connect ID

          The connect ID is the one word unique identifier for any connection.
     It  is mentioned here because the SYSAP needs to understand the fprmat of
     the connect ID.  The ID is made up of two fields, the SYSAP field and the
     SCA field.  The SYSAP field contains bits defined by the SYSAP and passed
     to SCA when connection blocks area being created (the connect and  listen
     calls).  The SCA field is broken down into fields for use by SCA, but the
     SYSAP only needs to know that the entire field is for  the  use  of  SCA.
     The following is the format of the connect ID:

               0         5 6                                     35
              !====================================================!
              !SYSAP bits !              SCA bits                  !
              !====================================================!

          When the SYSAP field is passed to SCA it is passed  in  bits  thirty
     (30) through thirty-five (35) of the BLCAL.  argument.  SCA will move the
     bits into the correct position for placement into the connect ID.
   SCA Functional specification                                   Page 24
   Writing a monitor SYSAP


     5.0  Writing a monitor SYSAP

     5.1  General rules

          To talk  to  other  processes  on  remote  systems,  SYSAPs  request
     services  of  SCA.   There  are  some  rules that must be followed if the
     conversation is to go smoothly.



     5.1.1  Buffer allocation and management

          There are four buffer types that monitor SYSAPs  may  have  to  deal
     with, messages and datagrams, both of which can be inbound or outbound.
          Rule one, ALL inbound buffers are allocated and controlled  by  SCA.
     When  a SYSAP desires to queue buffers for message or datagram reception,
     call SCA (see calling sequence for SC.RMG and SC.RDG)  and  indicate  how
     many  you desire, or specify the address of a buffer already allocated by
     SCA.  In the normal case, start up by asking for a number of buffers, and
     after  they  have  been returned with text in them, return them to SCA as
     fresh buffers for the port queues.  SYSAPs MUST NOT specify a buffer  not
     allocated by SCA when queueing inbound buffers.
          Rule two deals with outbound buffers.  SYSAPs  may  ask  SCA  for  a
     packet  buffer (see calling sequence for SC.ABF and SC.ALD), fill it with
     data, and ask SCA to send it (see SC.SMG and SC.SDG).  If the SYSAP  uses
     SCA  buffers  for sending packets, the SYSAP may request the buffer go on
     the port free queue on packet send completion.  Hence the SYSAP may do  a
     packet  send and queue a buffer for reception all at the same time.  Note
     that only SCA buffers may end up on the port free queues.   Hence  SYSAPs
     may  not  allocate their own space and ask for these buffers to end up on
     the port free queue.
          If the SYSAP desires to allocate its own send buffers, it may do  so
     but  the  space  allocated  must meet rigid standards.  First, the buffer
     must be contiguous in physical  memory.   Hence  if  a  page  boundry  is
     crossed,  the  two  virtual pages must be physically contiguous.  Second,
     the start of the SYSAP text must be at least .MHUDA words into the  page.
     This  is  used  by  SCA for header space.  Third, when the packet send is
     done the SYSAP must ask for the buffer back.  It MUST NOT end up  on  the
     port free queues.
   SCA Functional specification                                   Page 25
   Writing a monitor SYSAP


          SYSAPs must understand the format of SCA buffers if they are  to  be
     used correctly.  The following is the general format of an SCA buffer:

              !=====================================! 
      .MHISH  \                                     \ \
              \       Invisible SYSAP header        \  \  SYSAP header area
              \                                     \  / --------------------
              \                                     \ /
              !-------------------------------------! 
      0 --->  \                                     \ \
              \             SCA header              \  \
              \                                     \   \ 
              \                                     \   / SCA header area 
              !-------------------------------------!  / --------------------
      .MHPKL  !            Packet length            ! /
              !-------------------------------------! 
      .MHUDA  \                                     \ \
              \             SYSAP text              \  \  SYSAP text area
              \                                     \  / --------------------
              \                                     \ / 
              !=====================================!


     .MHISH - This symbol defines the offset to  the  base  of  the  invisible
     SYSAP header.  It is important to note that this is a negative offset.
          This header is for the exclusive use of the SYSAP.  SCA will zero it
     when the SYSAP requests the buffer but otherwise will not touch it.  This
     means the SYSAP can write data to this area and have  it  survive  across
     port packet transmission.

     0 - This is word zero of the buffer.  It is the  base  address  which  is
     passed  between  SCA  and  te  SYSAP when talking about this buffer.  All
     offsets within the buffer are defined as offsets from this word.

     .MHPKL - This word is used by SCA to describe the length of  an  incoming
     packet.   It  is  always  filled  in by SCA when it is called by the port
     driver for an incoming packet.  This word is not filled in by  the  SYSAP
     on a message send.
          This word is always the length of the SYSAP  text,  I.E.   it  never
     includes  the length of any overhead data.  If the packet was transmitted
     in high density mode, then the length is in words.  If  the  transmission
     mode was industry compatable, then the length is in bytes.

     .MHUDA - This offset defines the first word of the SYSAP text area.   SCA
     will never touch this area except to zero it on buffer allocation.
   SCA Functional specification                                   Page 26
   Writing a monitor SYSAP


     5.1.2  Starting a connection

          Before application packets can be exchanged between processes on two
     systems,  SCA must mediate the opening of a connection.  The following is
     a graphic description of this process.
   SCA Functional specification                                   Page 27
   Writing a monitor SYSAP


                     System A        !         System B
                                     !
                     Active side     !       Passive side
     _____________________________________________________________________________
                                     !                   _____________________
                                     !                   | SYSAP does LISTEN |
                                     !                   ---------------------
                                     !                       \
                                     !             ___________\______
                                     !             | SCA creates CB |
                                     !             ------------------
                                     !
     ______________________          !
     | SYSAP does CONNECT |          !
     ----------------------          !
                 \                   !
           _______\______________    !             ________________________________
           | SCA sends CONN_REQ | ---------------->| SCA gets CONN_REQ and finds  |
           ----------------------    !             |  listener. SCA sends CONN_RSP|
                                     !             |  and gives .SSCTL callback   |
            _____________________ <--------------- |  to listening SYSAP          |
            | SCA gets CONN_RSP |    !             --------------------------------
            ---------------------    !                           /
                                     !                   _______/___________
                                     !                   |SYSAP gets .SSCTL|
                                     !                   -------------------
                                     !                         |
                                     !                         |
                                     !                   ___________________
                                     !                   |SYSAP does ACCEPT|
                                     !                   -------------------
                                     !                               /
        _________________________    !              ________________/__
        |SCA gets ACCP_REQ,sends| <---------------- |SCA sends ACCP_REQ|
        | ACCP_RSP, and issues  |    !              --------------------
        | .SSCRA callback.      |    !
        | Connect is now open,  |    !              ________________________________
        | packets may be sent   | ----------------> |SCA receives ACCP_RSP, issues |
        -------------------------    !              | .SSOSD callback. Connect is  |
                     /               !              | now open, packets may be sent|
                    /                !              --------------------------------
        -------------------          !                                 \
        |SYSAP gets .SSCRA|          !                    --------------------------
        | callback, SYSAP |          !                    |SYSAP gets .SSOSD call  |
        | knows connect is|          !                    | back, SYSAP knowns     |
        | open            |          !                    | connect is open        |
        -------------------          !                    --------------------------


          The diagram above is a typical  connection  opening  sequence.   The
     important  thing to watch is the set of callbacks from SCA.  They are the
     direct indicator of what state the connect is in.  Note  that  there  are
     other  options  than  the  set  indicated  by  the diagram.  The detailed
     SCA/SYSAP interface details these options.
   SCA Functional specification                                   Page 28
   Writing a monitor SYSAP


     5.1.3  Global interlocks

          There are times when a SYSAP desires to insure that  no  further  CI
     traffic  will  be  processed  until  it has completed some piece of code.
     Using PIOFF to accomplish this is undesirable since it does not allow for
     nesting  and  it  turns off more channels than are necessary.  Instead of
     PIOFF/PION, CIOFF/CION should be used.  These  macros  call  routines  in
     SCAMPI  which  will  do  nesting and interrupt level checks.  At present,
     there are 36  bits  of  nesting  counter,  and  code  executed  at  KLIPA
     interrupt  level  will  not  turn  off  the channel.  Since these nesting
     checks are done, the SYSAP is guaranteed that the channel will  stay  off
     until  it does a CION.  Note that one side effect of going CIOFF is being
     NOSKED as well.
   SCA Functional specification                                   Page 29
   Writing a monitor SYSAP


     5.2  Messages

     5.2.1  Receiving messages

          To receive  messages  from  a  remote  node  a  SYSAP  must  do  the
     following:

     1.  Open a connection to the desired remote.

     2.  Queue message buffers.


          The SYSAP will now receive a .SSMGR callback for each  message  that
     arrives for it.



     5.2.2  Sending messages

          To send messages the SYSAP must have the following:

     1.  An open connection with the desired remote.

     2.  Send credit.

     3.  A buffer which meets the  requirements  for  placement  on  the  port
         command queues.


          If the connection has no send credits the remote node has not queued
     any  buffers  for receiving messages from you.  Hence you cannot send any
     and will get the fail return from SC.SMG until  the  remote  queues  some
     buffers.



     5.3  Datagrams

     5.3.1  Receiving datagrams

          Much like messages, datagrams require  an  open  connection  to  the
     remote  and  buffers queued for datagram reception.  The major difference
     is that when the remote does a send, if it fails  because  there  are  no
     buffers  available for your connection, you will get the .SSDDG callback.
     This is mearly an indication that the software  has  detected  a  dropped
     datagram  for  your  connection and you should queue some buffers for it.
     If the hardware drops the datagram because there are no  buffers  on  the
     entire  hardware  queue,  you  will never hear about it.  Hence the SYSAP
     cannot count on being told about dropped datagrams.  Note that SCA  never
     notifies the sender that the datagram was dropped.
   SCA Functional specification                                   Page 30
   Writing a monitor SYSAP


     5.3.2  Sending datagrams

          Sending datagrams requires an open connection to the  remote  and  a
     packet  buffer  that  meets  the  requirements  for placement on the port
     command queues.  (See the section on buffers for more details)



     5.4  Named buffers

          The general procedure for the transfer of data with named buffers is
     as follows:

     1.  Both sides of an open connection do a map call to set up a buffer.

     2.  SYSAP A gives its name for the buffer to SYSAP B.

     3.  The SYSAP B does a request or send data  function  which  starts  the
         data in the desired direction.

     4.  The SYSAP B gets a callback indicating the completion  of  the  named
         buffer transfer.

     5.  Lastly, and optionally, SYSAP B tells the SYSAP A that  the  transfer
         is complete.


          This method implies that each SYSAP has message buffers queued.  The
     data  transfer  functions  require  a buffer from the message free queue.
     The exchange of names should be done with messages or datagrams.
   SCA Functional specification                                   Page 31
   Writing a monitor SYSAP


     5.5  Monitor SYSAP interface

     5.5.1  SYSAP to SCA interface

          SCA provides many services to the SYSAP  though  the  use  of  these
     calling sequences:




     5.5.1.1  Connect (SC.CON)

                            - Connect (SC.CON) -

          This routine requests a connect with a remote process.

             Call
     BLCAL. (SC.CON,<SS.SPN,SS.DPN,SS.NOD,SS.MSC,SS.MRC,SS.ADR,^_
                     SS.SID,SS.DTA,SS.BFR,SS.DGB>)

      Where:
             SS.SPN -- Byte pointer to source process name
             SS.DPN -- Byte pointer to destination process name
             SS.NOD -- Node number of destination system
             SS.MSC -- Minimum send credit (Min for remote receive 
                             credit)
             SS.MRC -- Minimum receive credit, point at which 
                             destination must give more
             SS.ADR -- Address to call on condition changes for 
                             this connection
             SS.SID -- Value to be placed in SYSAP field in CID (right justified)
             SS.DTA -- Address of SYSAP connection data or zero
             SS.BFR -- Number of buffers to queue for message reception
             SS.DGB -- Number of datagram buffers to queue

             Return (+1)
             T1/     Error code

             Return (+2)
             T1/     Connect ID

          The  returned  connect  ID  is  the  unique  identifier   for   this
     connection.   All  further interaction with SCA will include this connect
     ID (CID).
   SCA Functional specification                                   Page 32
   Writing a monitor SYSAP


     5.5.1.2  Listen (SC.LIS)

                            - Listen (SC.LIS) -

          This routine enables the process  to  listen  for  connections  from
     remote processes.

             Call

     BLCAL. (SC.LIS,<SS.SPN,SS.DPN,SS.NOD,SS.ADR,SS.SID,SS.DTA,^_
                     SS.MSC,SS.MRC>)

      Where:
             SS.SPN -- Byte pointer to source process name
             SS.DPN -- Byte pointer to destination process name or 0
             SS.NOD -- Node number or -1
             SS.ADR -- Address to call on connection condition changes
             SS.SID -- Value to be placed in SYSAP field of CID (Right justified)
             SS.MSC -- Minimum send credit 
             SS.MRC -- Minimum receive credit

             Return (+1)
             T1/     Error code

             Return (+2)
             T1/     Connect ID

          When SCA  receives  a  connect  request  from  a  remote  node,  the
     following   algorithm  is  used  when  doing  name  matching  with  local
     listeners:
   SCA Functional specification                                   Page 33
   Writing a monitor SYSAP



























                                  Figure 1
   SCA Functional specification                                   Page 34
   Writing a monitor SYSAP


          A successful return from this call means SCA has a held a connection
     for  you  waiting for connects from remote nodes.  If a remote requests a
     connection with a process, that process will receive the .SSCTL callback.
   SCA Functional specification                                   Page 35
   Writing a monitor SYSAP


     5.5.1.3  Accept (SC.ACC)

                            - Accept (SC.ACC) -

          This routine is used to accept a connect request from a remote node.

             Call

             BLCAL.  (SC.ACC,<SS.CID,SS.DTA,SS.BFR,SS.DGB>)

      Where:
             SS.CID -- Connect ID
             SS.DTA -- Address of initial connection data or zero
             SS.BFR -- Number of buffers to be queued for message reception
             SS.DGB -- Number of buffers to queue for datagram reception

             Return (+1)
             T1/     Failure code

             Return (+2)
             T1/     Address of initial connect data

          The returned address of connect data is a pointer to the  connection
     data sent by the remote on the connect request.  Note that the connection
     is not open until the .SSOSD callback is given.
   SCA Functional specification                                   Page 36
   Writing a monitor SYSAP


     5.5.1.4  Reject (SC.REJ)

                            - Reject (SC.REJ) -

          This routine rejects the connect request of a remote process.

             Call

             BLCAL. (SC.REJ,<SS.CID,SS.RJR>)

      Where:
             SS.CID -- Connect ID
             SS.RJR -- Reject reason code

             Return (+1)
             T1/     Failure code

             Return (+2)
             No data is returned by this routine

          The reject reason may be any  value  the  caller  desires  with  the
     exception  of  those  reserved  to SCA (in the range /TBD/).  The idea is
     that the SYSAP protocol should invent and use  its  own  reject  reasons.
     After  the reject call has been issued, the connection goes back into the
     listen state.
   SCA Functional specification                                   Page 37
   Writing a monitor SYSAP


     5.5.1.5  Disconnect (SC.DIS)

                          - Disconnect (SC.DIS) -

          This routine closes an open connection.  Note that it  may  only  be
     called  if  the connection is open.  No other connection state is allowed
     for a connection that is to be disconnected.

             Call

             BLCAL.  (SC.DIS,<SS.CID,SS.DIR>)

      Where:
             SS.CID -- Connect ID
             SS.DIR -- Disconnect reason

             Return (+1)
             T1/     Failure code

             Return (+2)
             No data is returned by this routine

          The disconnect reason may be any value the caller desires  with  the
     exception  of  those  reserved  to SCA (in the range /TBD/).  The idea is
     that the SYSAP protocol should invent and use its own disconnect reasons.
   SCA Functional specification                                   Page 38
   Writing a monitor SYSAP


     5.5.1.6  Abort (SC.ABT)

                             - Abort (SC.ABT) -

          This routine is called  to  abort,  or  cancel,  a  connection.   It
     differs  from disconnect in that it may be issued for a connection in any
     state.  Whereas disconnect may only be issued for an open connection.

             Call

             BLCAL. (SC.ABT,<SS.CID>)

             Where:
             SS.CID -- Connect ID of the connection to be aborted

             Return (+1)
             T1/     Error code

             Return (+2)
             No data returned, CID is no longer valid, and the connection has been
               aborted.






     5.5.1.7  Send datagram (SC.SDG)

                         - Send datagram (SC.SDG) -

          This routine is called to send a datagram over an open connection.

             Call

             BLCAL.  (SC.SDG,<SS.CID,SS.FLG,SS.LDG,SS.ADG>)

      Where:
             SS.CID -- Connect ID
             SS.FLG -- Flag word
             SS.LDG -- Len of datagram (in bytes)
             SS.ADG -- Address of datagram buffer

             Return (+1)
             T1/     Failure code

             Return (+2)
             No data is returned by this routine, datagram
                      placed on port queue

          The flags word is used to indicate  the  transmission  mode  of  the
     packet,  and  hence the units on the packet size.  It also indicates what
     should be done with the buffer after the message send is  complete.   See
     the section on buffer management for more details.  These are the defined
   SCA Functional specification                                   Page 39
   Writing a monitor SYSAP


     flags for this word:
             F.RTB -- 1 - return message send buffer to SCA
                      0 - return message send buffer to free Q

             F.SPM -- 1 - Send mess/datagram in high den mode
                      0 - Send mess/datagram in industry compat mode
   SCA Functional specification                                   Page 40
   Writing a monitor SYSAP


     5.5.1.8  Queue datagram receive buffers (SC.RDG)

                - Queue datagram receive buffers (SC.RDG) -

          This routine puts buffers onto the port datagram free queue for you.

             Call

             BLCAL.  (SC.RDG,<SS.CID,SS.NUM,SS.ADR>)

      Where:
             SS.CID -- Connect ID

             If SS.ADR is zero then:
             SS.NUM -- Number of buffers to queue

             If SS.ADR is non-zero, then:
             SS.NUM is ignored, and
             SS.ADR -- Address of the buffer to queue. Note that this
                     buffer must be a buffer procured from SCA. This means it has
                     been used as a datagram buffer before. This is handy for those
                     time you are done with an SCA datagram buffer and wish to
                     requeue it. It eliminated the need for two calls to SCA.

             Return (+1)
             T1/     Error code

             Return (+2)
             Buffer(s) have been queued to receive datagrams.
   SCA Functional specification                                   Page 41
   Writing a monitor SYSAP


     5.5.1.9  Send a message (SC.SMG)

                        - Send a message (SC.SMG) -

          This routine sends a message if there are  sends  credits  available
     and the circuit is open.

             Call

             BLCAL.  (SC.SMG,<SS.CID,SS.FLG,SS.LMG,SS.AMG,SS.PRI,SS.TSH>)

      Where:
             SS.CID -- Connect ID
             SS.FLG -- Flag word, see SC.SDG for a definition
             SS.LMG -- Length of message in bytes
             SS.AMG -- Address of message buffer
             SS.PRI -- Priority to give message
             SS.TSH -- Allow send only if more than this many send credits exist

             Return (+1)
             T1/     Error code

             Return (+2)
             No data returned
   SCA Functional specification                                   Page 42
   Writing a monitor SYSAP


     5.5.1.10  Queue message receive buffers (SC.RMG)

                 - Queue message receive buffers (SC.RMG) -

          This routine places buffers onto the port  message  free  queue  and
     reflects these buffers as receive credit for the given connection.

             Call

             BLCAL.  (SC.RMG,<SS.CID,SS.NRB,SS.AMB>)

      Where:
             SS.CID -- Connect ID

             SS.NRB -- If SS.AMB is zero then this is the number of buffers 
                             to be queued for message reception.

             SS.AMB -- Address of message buffer
                       If SS.AMB is zero then a buffer is taken from the SCA
                     message buffer free queue. If it is non-zero, then it
                     is assumed that no problems will arise if the buffer
                     is returned to the SCA pool. Since it may end up in
                     the SCA pool it must be the length of all other buffers
                     in the pool, must have come from the general free
                     pool,and must be resident.

             Return (+1)
             T1/     Error code

             Return (+2)
             Buffer has been queued.
   SCA Functional specification                                   Page 43
   Writing a monitor SYSAP


     5.5.1.11  Cancel datagram receive buffer (SC.CRD)

                - Cancel datagram receive buffer (SC.CRD) -

          This routine will take buffers off the port datagram free queue.  It
     will  not  allow the caller to take more buffers than were queued for the
     given connection.  The buffers are returned to the SCA free pool and  not
     to the caller.

             Call

             BLCAL.  (SC.CRD,<SS.CID,SS.NBF>)

      Where:
             SS.CID -- Connect ID
             SS.NBF -- Number of buffers to dequeue

             Return (+1)
             T1/     Error code

             Return (+2)
             No data returned, buffer dequeued.






     5.5.1.12  Cancel message receive buffers (SC.CRM)

                - Cancel message receive buffers (SC.CRM) -

          This routine will dequeue buffers from the message free queue.  Note
     that  it  will  not  allow  the  caller to dequeue more buffers than were
     queued for the given connection.  The buffers are  returned  to  the  SCA
     free pool and not to the caller.

             Call

             BLCAL. (SC.CRM,<SS.CID>)

             Where:
             SS.CID - The connection ID of connection who's buffer we are canceling
             SS.NBD - The number of buffers to dequeue

             Return (+1)
             T1/     Error code

             Return (+2)
             No data returned, buffer(s) have been returned to the free pool
   SCA Functional specification                                   Page 44
   Writing a monitor SYSAP


     5.5.1.13  Map a named buffer (SC.MAP)

                      - Map a named buffer (SC.MAP) -

          This routine associates memory with  a  named  buffer.   Provided  a
     descriptor  block  (shown  below) it will get the port driver to give the
     buffer to the port.

             Call

             BLCAL. (SC.MAP,<SS.BLK>)

      Where:
             SS.BLK -- Address of the first entry in a chain of buffer
                             descriptor blocks.

             Return (+1)
             T1/     Error code

             Return (+2)
             T1/     Buffer name

             Buffer descriptor blocks have the following format:

              !=======================================================!
     .MDNXT   !    Address of next buffer descriptor (zero if none)   !
              !-------------------------------------------------------!
     .MDFLG   !                         Flags                         !
              !-------------------------------------------------------!
     .MDLEN   !                  Length of segment #0                 !
              !-------------------------------------------------------!
     .MDADR   !                Address of the segment #0              !
              !-------------------------------------------------------!
              \                                                       \
              \                                                       \
              \              segment descriptor pairs                 \
              \                                                       \
              \                                                       \
              !-------------------------------------------------------!
              !               Length of buffer segment #n             !
              !-------------------------------------------------------!
              !                Address of the segment #n              !
              !-------------------------------------------------------!
              !                       0                               !
              !=======================================================!

          The flags word has the following set of flags defined:

     1.  MD%DMD -- Two  bit  field  indicating  buffer  mode.   The  following
         settings are defined:
         MD%DIC -- Industry compatable
         MD%DCD -- Core dump
         MD%DHD -- High density
   SCA Functional specification                                   Page 45
   Writing a monitor SYSAP


     All other values are illegal.

          Note that .MDNXT and .MDFLG are offsets from the start of the  block
     to  the address of the next entry in the chain, but .MDLEN and .MDADR are
     offsets within the words describing a single buffer segment.
   SCA Functional specification                                   Page 46
   Writing a monitor SYSAP


     5.5.1.14  Unmap a buffer (SC.UMP)

                        - Unmap a buffer (SC.UMP) -

          This routine is called to unmap a buffer.  Note  that  this  routine
     must  be  called before the buffer will go away.  Hence if the routine is
     not called after all named buffer transfers are completed the buffer will
     stay  around  forever.   This enables the SYSAP to do multiple operations
     with the same buffer, without having to map the buffer every time.

             Call

             BLCAL. (SS.UMP,<SS.NAM>)

      Where:
             SS.NAM -- Name of buffer to be unmapped

             Return (+1)
             T1/     Error code

             Return (+2)
             No data, buffer name is no longer valid
   SCA Functional specification                                   Page 47
   Writing a monitor SYSAP


     5.5.1.15  Send named buffer data (SC.SND)

                    - Send named buffer data (SC.SND) -

          This routine sends block data from a named buffer.

     Note:
          One receive credit is required to do any named buffer transfer.

             Call
             BLCAL. (SC.SND,<SS.CID,SS.SNM,SS.RNM,SS.SOF,SS.ROF>)

      Where:
             SS.CID -- Connection on which this transfer is being done
             SS.SNM -- Name of the buffer to get data from
             SS.RNM -- Name of buffer to put data into
             SS.SOF -- Byte offset into transmission buffer
             SS.ROF -- Byte offset into reception buffer

             Return (+1)
             T1/     Error code

             Return (+2)
             No data returned.
   SCA Functional specification                                   Page 48
   Writing a monitor SYSAP


     5.5.1.16  Request remote named buffer transfer (SC.REQ)

             - Request remote named buffer transfer (SC.REQ) -

          This routine requests the transfer of data from a remote data buffer
     to  a  local one.  Note that do perform this function the SYSAP must have
     at least one receive credit.  This is due to the ports use of  a  message
     buffer from the message free queue on a named buffer operation.

             Call

             BLCAL. (SS.REQ,<SS.CID,SS.NOD,SS.SNM,SS.RNM,SS.SOF,SS.ROF>)

      Where:
             SS.CID -- Connection on which this transfer is being done
             SS.NOD -- Node number of remote host
             SS.SNM -- Name of remote buffer to get data from
             SS.RNM -- Name of local buffer to put data into
             SS.SOF -- Byte offset into transmission buffer
             SS.ROF -- Byte offset into reception buffer

             Return (+1)
             T1/     Error code

             Return (+2)
             No data returned.
   SCA Functional specification                                   Page 49
   Writing a monitor SYSAP


     5.5.1.17  Connect state poll (SC.CSP)

                      - Connect state poll (SC.CSP) -

          This routine returns information about the state of a connection.

             Call
             BLCAL.  (SC.CSP,<SS.CID,SS.FRE>)

             Where:
             SS.CID -- Connect ID of target connect
             SS.FRE -- Address of a free space block for returned info

             Return (+1)
             T1/     Failure code

             Return (+2)
             T1/     Address of returned data

          Note that it is the SYSAP that  provides  the  free  space  for  the
     return  of  data.   This  free  space  may be from an extended section or
     section zero.  The format of the retutned data is as follows:

              !=======================================================!
       .CDCST !                   Connection state                    !
              !-------------------------------------------------------!
       .CDDCI !                Destination Connect ID                 !
              !-------------------------------------------------------!
       .CDDPN !        Byte pointer to destination process name       !
              !-------------------------------------------------------!
       .CDSBI !                      Node number                      !
              !-------------------------------------------------------!
       .CDACB !              Address of connection block              !
              !-------------------------------------------------------!
       .CDREA ! Source disconnect reasons !  Dest disconnect reasons  !
              !=======================================================!

          The byte pointer to destination process name points to a  string  in
     an  SCA  database.  This is important to realize since the SYSAP must not
     change the indicated string.
   SCA Functional specification                                   Page 50
   Writing a monitor SYSAP


     5.5.1.18  Return destination connect ID (SC.DCI)

                 - Return destination connect ID (SC.DCI) -

          This  routine  returns  the  remotes  identifier   for   the   given
     connection.

             Call
             BLCAL. (SC.DCI,<SS.CID,SS.FRE>)

             Where:
             SS.CID -- Connect ID for target connection
             SS.FRE -- Address of free space into which data is to be returned

             Return (+1)
             T1/     Error code

             Return (+2)
             T1/     Destination connect ID for given connection
   SCA Functional specification                                   Page 51
   Writing a monitor SYSAP


     5.5.1.19  Return system configuration data (SC.RCD)

               - Return system configuration data (SC.RCD) -

          This routine returns information about a system.  To discover who is
     available  on  the  net  simply  call this routine for each possible node
     number.  Node numbers are guarenteed to start at zero and and at

             Call
             BLCAL.  (SC.RCD,<SS.NOD>)

      Where:
             SS.NOD -- Target node number

             Return (+1)
             T1/     Failure code

             Return (+2)
             T1/     Address of configuration data block


          The free space into which data is retuedn  may  be  in  an  extended
     section or section zero, and has the following format:


             !=======================================================!
      .RDSTS !   Virtual circuit state   !        Port number        !
             !-------------------------------------------------------!
      .RDSYS \                                                       \
             \      System address (6 8-bit bytes, word aligned)     \
             \                                                       \
             !-------------------------------------------------------!
      .RDMDG !           Maximum destination datagram size           !
             !-------------------------------------------------------!
      .RDMMS !           Maximum destination message size            !
             !-------------------------------------------------------!
      .RDDST !               Destination software type               !
             !-------------------------------------------------------!
      .RDDSV !             Destination software version              !
             !-------------------------------------------------------!
      .RDDSI !           Destination software incarnation            !
             !-------------------------------------------------------!
      .RDDHT !               Destination hardware type               !
             !-------------------------------------------------------!
      .RDDHV !             Destination hardware version              !
             !-------------------------------------------------------!
      .RDPRT \                                                       \
             \   Port characteristics (6 8-bit bytes, word aligned)  \
             \                                                       \
             !=======================================================!

          The format of the system name and port  characteristics  fields  are
     /TBD/.
   SCA Functional specification                                   Page 52
   Writing a monitor SYSAP


     5.5.1.20  Reset a remote system (SC.RST)

                     - Reset a remote system (SC.RST) -

          This routine sends  a  maintenance  reset  to  a  remote  node.   No
     checking  is done as to the node type.  If the remote does not honor such
     packets then the remote will simply  ignore  the  packet.   There  is  no
     direct  indication  to the local SYSAP as to whether the packet was taken
     or ignored.

             Call

             BLCAL. (SC.RST,<SS.NOD,SS.FRB>)

      Where:
             SS.NOD -- Node number of node to be reset
             SS.FRB -- Force reset bit, if one, reset is forced, if zero,
                          reset will only be done if we are the last node to do
                          a reset for this remote

             Return (+1)
             T1/     Error code

             Return (+2)
             No data returned, reset packet sent
   SCA Functional specification                                   Page 53
   Writing a monitor SYSAP


     5.5.1.21  Start a node (SC.STA)

                         - Start a node (SC.STA) -

          This routine sends a maintainance start a remote node.  No check  of
     remote  node type is done.  If the remote node does not honor this packet
     type then the remote will simply ignore the packet.  No direct indication
     of success or failure of the packet at the remote is provided.

             Call

             BLCAL. (SC.STA,<SS.NOD,SS.DSA,SS.STA>)

      Where:
             SS.NOD -- Node number of target remote
             SS.DSA -- Flag for use of SS.STA, if zero, SS.STA is ignored and
                             the default start address is used. If non-zero, SS.STA
                             is used as the start address of the remote.
             SS.STA -- Start address for the remote node. Only used if SS.DSA is
                             non-zero.

             Return (+1)
             T1/     Error code

             Return (+2)
             No data returned
   SCA Functional specification                                   Page 54
   Writing a monitor SYSAP


     5.5.1.22  Set port counters (SC.SPC)

                       - Set port counters (SC.SPC) -

          This function sets the port counters for a desired function.

             Call
             BLCAL. (SC.SPC,<SS.NOD,SS.CTL>)

             Where:
             SS.NOD -- Node number or 377 for all nodes
             SS.CTL -- Control word for port counters, bits as follows:

                           B0   If on, count ACKs received on Path A.
                           B1   If on, clear the counter.
                           B2   If on, count NAKs received on Path A.
                           B3   If on, clear the counter.
                           B4   If on, count NO_RSPs received on Path A.
                           B5   If on, clear the counter.
                           B6   If on, count ACKs received on Path B.
                           B7   If on, clear the counter.
                           B8   If on, count NAKs received on Path B.
                           B9   If on, clear the counter.
                           B10  If on, count NO_RSPs received on Path B.
                           B11  If on, clear the counter.
                           B12  The count of discarded datagrams because
                                of no DGFree Queue entries.
                           B13  If on, clear the counter.
                           B14  Count  the  packets  transmitted to  the
                                designated port.
                           B15  If on, clear the counter.
                           B16  Count  the  packets  received  from  the
                                designated port.
                           B17  If on, clear the counter.

             Return (+1)
             T1/     Error code

             Return (+2)
             No data retutned, port counters set
   SCA Functional specification                                   Page 55
   Writing a monitor SYSAP


     5.5.1.23  Read port counters (SC.RPC)

                      - Read port counters (SC.RPC) -

          This routine returns the values of the  port  counters.   It  is  an
     asynchronous  event.   The  routine will return immediatly but the answer
     will occur as the .SSRPC callback.


             Call
             BLCAL. (SC.RPC,<SS.ADR>)

             Where:
             SS.ADR -- Address of SCA allocated buffer into 
                               which data is to be returned

             Return (+1)
             T1/     Error code

             Return (+2)
             No data returned, .SSRPC callback will happen 
                                        when data is ready
   SCA Functional specification                                   Page 56
   Writing a monitor SYSAP


     5.5.1.24  Maintainance data send (SC.MDS)

                    - Maintainance data send (SC.MDS) -

     This routine requests a block tranfser write, in maintainance  mode.   No
     SCA  connection  or  port  circuit  are  required for this function.  The
     buffer must have been mapped with the SC.MAP call however.

             Call
             BLCAL. (SC.MDS,<SS.NOD,SS.SNM,SS.RNM,SS.XOF,SS.ROF,SS.ADR>)

             Where:
             SS.NOD -- Node number of target system
             SS.SNM -- Local buffer name for transfer
             SS.RNM -- Remote buffer name for transfer
             SS.XOF -- Transmit offset (in words)
             SS.ROF -- Receive offset (in words)
             SS.ADR -- Address to call when transfer is compelte

             Return (+1)
             T1/     Error code

             Return (+2)
             No data returned, notification by .SSMNT callback when completed
   SCA Functional specification                                   Page 57
   Writing a monitor SYSAP


     5.5.1.25  Maintainance data read (SC.MDR)

                    - Maintainance data read (SC.MDR) -

          This routine requests a block tranfser read, in  maintainance  mode.
     No  SCA  connection  or port circuit are required for this function.  The
     buffer must have been mapped with the SC.MAP call however.

             Call
             BLCAL. (SC.MDR,<SS.NOD,SS.SNM,SS.RNM,SS.XOF,SS.ROF,SS.ADR>)

             Where:
             SS.NOD -- Node number of target node
             SS.SNM -- Remote buffer name for transfer
             SS.RNM -- Local buffer name for transfer
             SS.XOF -- Transmit offset (in words)
             SS.ROF -- Receiver offset (in words)
             SS.ADR -- Address to call when transfer is complete

             Return (+1)
             T1/     Error code

             Return (+2)
             No data returned, .SSMNT callback when complete
   SCA Functional specification                                   Page 58
   Writing a monitor SYSAP


     5.5.1.26  Set online address (SC.SOA)

                      - Set online address (SC.SOA) -

          Notification of a node coming online happens on a  per  SYSAP  basis
     rather  than  on  a per connection basis.  Hence SCA must have an address
     for each SYSAP that wishes to be called when a new VC  has  been  opened.
     This  routine  sets  the  online  address  for the SYSAP.  Note that this
     routine does not know who calls it and will simply add  this  address  to
     the  list  of  notification  addresses.   It  does  not try to delete old
     entries if called twice by the same SYSAP.
          Note that this call will only allow .SSNCO callbacks to occur.   All
     other  callbacks  are  done  through  the address specified at connect or
     listen time.

             Call

             BLCAL. (SC.SOA,<SS.ADR>)

             Return (+1)
             T1/     Error code

             Return (+2)
             No data, address saved
   SCA Functional specification                                   Page 59
   Writing a monitor SYSAP


     5.5.1.27  Swap bytes from 11 to 10 format (SC.ISW)

                - Swap bytes from 11 to 10 format (SC.ISW) -

          This support routine swaps a single PDP-11 format word into a PDP-10
     format word.  Since this is a popular thing to do when talking to the HSC
     and friends this routine is global for access by the rest of the monitor.

             Call

             T1/     Word to be swapped

             Return (+1) Always
             T1/     Byte swapped word

      Input format:
             2 16 bit half words, left justified

      !=======================================================!
      !  B (lsb)  !  B (msb)  !  A (lsb)   !   A (msb)  ! IGN !
      !=======================================================!
      0          7 8        15 16        23 24        31 32  35

      Where A and B are the half words, and (lsb) are the least significant bits 
     and (msb) are the most significant bits.

     The contents of bits 32 thru 35 are ignored.


      Output format:
      2 18 bit half words,

      !=======================================================!
      !X!    Byte A (msb+lsb)     !X!     Byte B (msb +lsb)   !
      !=======================================================!
      0  2                      17    20                      35

      X denotes the 2 bit field within each halfword that 
      will always be zero.
   SCA Functional specification                                   Page 60
   Writing a monitor SYSAP


     5.5.1.28  SC.OSW (Swap word from 10 to 11 forma

                 - SC.OSW (Swap word from 10 to 11 format)

          This routine swaps a  single  word  from  PDP-10  format  to  PDP-11
     format.   Rather  than  be yet another in the long list of byte swappers,
     this routine is globally  available  to  the  rest  of  the  monitor  (in
     particular SYSAPs).

             Call

             T1/     Word to swap

             Return (+1) Always
             T1/     Byte swapped word

     Input format:
      2 18 bit half words,

      !=======================================================!
      !       Byte A (msb+lsb)     !     Byte B (msb +lsb)    !
      !=======================================================!
      0                          17 18                        35




      Output format:
             2 16 bit half words, left justified

      !=======================================================!
      !  B (lsb)  !  B (msb)  !  A (lsb)   !   A (msb)  ! IGN !
      !=======================================================!
      0          7 8        15 16        23 24        31 32  35

      Where A and B are the half words, and (lsb) are the least significant bits 
     and (msb) are the most significant bits.
   SCA Functional specification                                   Page 61
   Writing a monitor SYSAP


     5.5.1.29  Return node number given CID (SC.SBI)

                 - Return node number given CID (SC.SBI) -

          This routine returns the node number of the remote end of the  given
     CID.

             Call
             BLCAL. (SC.SBI,<SS.CID>)

             Where:
             SS.CID -- Connect ID of target connection

             Return (+1) Always
             T1/     Local connect ID
             T2/     Node number of the remote end of the connection specified
   SCA Functional specification                                   Page 62
   Writing a monitor SYSAP


     5.5.1.30  Return credit info (SC.RAC)

                      - Return credit info (SC.RAC) -

          This routine returns the current  credit  levels  for  a  particular
     connection.  This routine is not interlocked, hence the credit counts may
     be incorrect by the time SCAMPI returns from the PUSHJ.  The  usual  case
     is  SCAMPI  is  interrupted  in  the  middle of this routine by a message
     arriving for this connection.  This means the  receive  credits  will  be
     wrong.   If  the  SYSAP sends a reply at interrupt level the send credits
     will be wrong as well.  Since most connections maintain a large number of
     credits  this routine will at least give a ballpark figure.  If the SYSAP
     knows that it will not be getting  any  messages  or  if  it  calls  this
     routine CIOFF then the counts will be correct.

             Call
             BLCAL. (SC.RAC,<SS.CID>)

             Where:
             SS.CID -- Connect ID of connection whose credits
                             are desired

             Return (+1)
             T1/     Error code

             Return (+2)
             T1/     Send credit
             T2/     Receive credit
             T3/     Number of datagram buffers queued
   SCA Functional specification                                   Page 63
   Writing a monitor SYSAP


     5.5.1.31  Return local port number (SC.PRT)

                   - Return local port number (SC.PRT) -

          This routine returns  the  node  number  of  the  local  node.   The
     assumption is made that this is a KL with only one KLIPA.

             Call
             No arguments

             Return (+1)
             Error code

             Return (+2)
             T1/     Local node number
             T2/     Reserved
             T3/     Reserved
             T4/     Reserved
   SCA Functional specification                                   Page 64
   Writing a monitor SYSAP


     5.5.1.32  Allocate a datagram buffer (SC.ALD)

                  - Allocate a datagram buffer (SC.ALD) -

          This routine will allocate datagram buffers from the SCA free  pool.
     It is from this pool that all buffers on the port free queues originated.
     If desired the  SYSAP  can  use  buffers  from  this  pool  for  outgoing
     datagrams  and  have  the  buffer  placed  on  the  port  free  queue  on
     transmission completion.
          When more than one  buffer  has  been  requested,  the  buffers  are
     chained  together  with  the link in the zeroth word of each buffer.  The
     link word always points to word zero of the next buffer.  The last buffer
     has a link word of zero.

             Call
             T1/     Number of buffers desired

             Return (+1)
             T1/     Error code

             Return (+2)
             T1/     Address of first buffer on chain
             T2/     Number of buffers returned
             T3/     Address of routine to return buffers
   SCA Functional specification                                   Page 65
   Writing a monitor SYSAP


     5.5.1.33  Allocate a message buffer (SC.ABF)

                   - Allocate a message buffer (SC.ABF) -

          This routine allocates message buffers from the SCA free  pool.   If
     desired the SYSAP may use these buffers for message transmission and have
     the buffer placed on the port free queue on send completion.   Also  note
     that  these  buffers  have the invisible area described in the section on
     SCA buffers.
          When more than one  buffer  has  been  requested,  the  buffers  are
     chained  together  with  the link in the zeroth word of each buffer.  The
     link word always points to the zeroth word of the next buffer.  The  last
     buffer has a link word of zero.

             Call
             T1/     Number of buffers desired

             Return (+1)
             T1/     Error code (No buffers returned)

             Return (+2)
             T1/     Address of first buffer on chain
             T2/     Number of buffers returned
             T3/     Address of routine to return buffers
   SCA Functional specification                                   Page 66
   Writing a monitor SYSAP


     5.5.1.34  Return a message buffer (SC.RBF)

                    - Return a message buffer (SC.RBF) -

          This routine is  used  to  return  buffers  to  the  SCA  free  pool
     allocated with SC.ABF.  Although buffers can be allocated in chains, they
     may not be returned that way.  A buffer is returned one at a time.  Hence
     the link word of the buffer is ignored.

             Call
             T1/     Address of buffer to be returned

             Return (+1) Always
             No data returned, buffer returned OK







     5.5.1.35  Return a datagram buffer (SC.RLD)

                   - Return a datagram buffer (SC.RLD) -

          Datagram buffer allocated with SC.ALD must be returned  to  the  SCA
     free  pool  with  this  routine.   Although  buffers  may be allocated in
     chains, they must be returned one at a time.  Hence the link word in each
     buffer is ignored.

             Call
             T1/     Address of buffer to be returned

             Return (+1) Always
             No data returned, buffer has been returned
                     to SCA free pool
   SCA Functional specification                                   Page 67
   Writing a monitor SYSAP


     5.5.2  SCA to SYSAP interface

          The following is the complete set of callbacks that  the  SYSAP  can
     expect to see from SCA.

     General format of returned information:
             T1/     Function code
             T2-T4/  Function code dependant additional data

             Context: List of possible contexts for this callback. I.E.
                             the contexts the SYSAP may see during this callback

     -       -       -       -       -       -       -       -       -       -

     .SSDGR
     Datagram received. SCA is indicating that the CI has filled one of the buffers
     queued for datagram reception with a datagram. 
             T1/     .SSDGR
             T2/     Connect ID
             T3/     Address of datagram buffer
             T4/     <FLAGS>B5 ! <Addr of routine to return buffer>B35
                     (See SC.SDG for flag definitions)

      .MHPKL word of datagram buffer/
                     Length of the packet (Bytes for industry compatable, words
                                             for high density)

             Context: Interrupt

     -       -       -       -       -       -       -       -       -       -

     .SSMGR
     Message received. SCA is indicateing that you have received a message from the
     CI.
             T1/     .SSMGR
             T2/     Connect ID
             T3/     Address of message buffer
             T4/     <FLAGS>B5 ! <Addr of routine to return buffer>B35
                     (See SC.SDG for flag definitions)

      .MHPKL word of msg buffer/
                     Length of the packet (Bytes for industry compatable, words
                                             for high density)

             Context: Interrupt
     -       -       -       -       -       -       -       -       -       -

     .SSPBC
     Port broke connection. The port hardware detected a fatal error for the
     port virtual circuit on which you had a connection. Thus it broke your
     connection.
             T1/     .SSPBC
             T2/     Connect ID
             T3/     Unused
   SCA Functional specification                                   Page 68
   Writing a monitor SYSAP


             T4/     Unused

             Context: Interrupt, scheduler

     -       -       -       -       -       -       -       -       -       -

     .SSCTL
     Connection to listen. The listen done for you has been matched to a remote 
     connect request.
             T1/     .SSCTL
             T2/     Connect ID
             T3/     Address to connection data from remote system
             T4/     Unsued

             Context: Interrupt
     -       -       -       -       -       -       -       -       -       -

     .SSCRA
     Connection response available. The system to which you sent a connect message 
     has responded.
             T1/     .SSCRA
             T2/     Connect ID
             T3/     -1 for accepted, 0 for rejected connection
             T4/     Reject code (If rejected), pointer to connect data if accepted

             Context: Interrupt

     -       -       -       -       -       -       -       -       -       -

     .SSMSC
     Message/datagram Send complete. The message/datagram which you requested be 
     sent, has been. The "buffer address" is the address of the buffer you gave 
     SCA to send.
             T1/     .SSMSC
             T2/     Connect ID
             T3/     Address of buffer
             T4/     Length of buffer in bytes for ind. compat/words for high den
                             This is the length of the text portion, and does not
                             include SCA headers.

             Context :Interrupt

     -       -       -       -       -       -       -       -       -       -

     .SSLCL
     Little credit left. You have just received a message that put you under
     receive credit threshold. It is suggested that you queue at least some buffers
     if you expect to get more messages. Note that you will receive one of these
     calls every time you receive a message after which you are under threshold.
             T1/     .SSLCL
             T2/     Connect ID
             T3/     Number of credits needed to get you over threshold
             T4/     Unused
   SCA Functional specification                                   Page 69
   Writing a monitor SYSAP


             Context: Interrupt

     -       -       -       -       -       -       -       -       -       -

     .SSNCO
     Node came online. You requested to be told of nodes coming online.
     It happened and now you're being told.

             T1/     .SSNCO
             T2/     Node number of system that has come online
             T3/     Unused
             T4/     Unused

             Context: Interrupt, scheduler

     -       -       -       -       -       -       -       -       -       -

     .SSOSD
     OK to send data. The connection has been completed to a remote system and is
     now in the OPEN state. Messages and datagram may be sent.

             T1/     .SSOSD
             T2/     Connect ID
             T3/     Unused
             T4/     Unused

             Context: Interrupt

     -       -       -       -       -       -       -       -       -       -

     .SSRID
      Remote initiated disconnect. The host at the other end of your connection
     doesn't want to talk to you anymore and has completed an orderly shutdown of
     your connection.

             T1/     .SSRID
             T2/     Connect ID
             T3/     Unused
             T4/     Unused

             Context: Interrupt

     -       -       -       -       -       -       -       -       -       -

     .SSCIA
     Credit is available. Your message send failed for lack of credit. There is
     now more credit available for your send.

             T1/     .SSCIA
             T2/     Connect ID
             T3/     Current send credit
             T4/     Current receive credit

             Context: Interrupt
   SCA Functional specification                                   Page 70
   Writing a monitor SYSAP



     -       -       -       -       -       -       -       -       -       -

     .SSNWO
      Node went offline. The remote end of your connection has just dropped 
     offline. After this callback, all data about the connection will be deleted.

             T1/     .SSNWO
             T2/     CID for connect you had on offline node
             T3/     Unused
             T4/     Unused

             Context: Interrupt, scheduler

     -       -       -       -       -       -       -       -       -       -

     .SSDMA
      Named buffer operation complete. The named buffer operation you requested 
     has been completed. Note that you will NOT be told about the completion of 
     passive requests. I.E. you will not be notified when a request/send data 
     done by a remote completes.

             T1/     .SSDMA
             T2/     Connect ID of connection tranfers was done for
             T3/     Buffer name of named buffer
             T4/     Unused

             Context: Interrupt

     -       -       -       -       -       -       -       -       -       -

     .SSDDG
      Dropped datagram. SCA received a datagram for this connection and dropped it
     since you had no buffers left. The buffer was returned to the port free queue.
     Note that this is a software detected datagram drop. If the port drops the
     datagram because there are no buffers on the port queue, this call back will
     not happen.

             T1/     .SSDDG
             T2/     Connect ID
             T3/     Unused
             T4/     Unused

             Context: Interrupt

     -       -       -       -       -       -       -       -       -       -

     .SSMNT
     Maintainance data send/receive complete.

             T1/     .SSMNT
             T2/     Buffer name of completed transfer
             T3/     Unused
             T4/     Unused
   SCA Functional specification                                   Page 71
   Writing a monitor SYSAP



             Context: Interrupt

     -       -       -       -       -       -       -       -       -       -

     .SSRPC
     Read port counters response. The request for reading the port counters has
     completed and here is your answer.

             T1/     .SSRPC
             T2/     Connect ID of requesting connect
             T3/     Address of packet containing counter data
             T4/     Unused

             The following is the format of the counter data:

             !=======================================================!
             \                                                       \
             \                      Port header                      \
             \                                                       \
             !-------------------------------------------------------!
     .PCMCV  !                   Microcode version                   !
             !-------------------------------------------------------!
     .PCAAC  !                   Path A ACK count                    !
             !-------------------------------------------------------!
     .PCANC  !                   Path A NAK count                    !
             !-------------------------------------------------------!
     .PCANR  !               Path A no response count                !
             !-------------------------------------------------------!
     .PCBAC  !                   Path B ACK count                    !
             !-------------------------------------------------------!
     .PCBNC  !                   Path B NAK count                    !
             !-------------------------------------------------------!
     .PCBNR  !               Path B no response count                !
             !-------------------------------------------------------!
     .PCDGD  !                  Datagrams discarded                  !
             !-------------------------------------------------------!
     .PCPTX  !                  Packets transmitted                  !
             !-------------------------------------------------------!
     .PCPRX  !                   Packets received                    !
             !-------------------------------------------------------!
     .PCDPT  !                    Designated port                    !
             !-------------------------------------------------------!
             \                                                       \
             \                 Reserved for software                 \
             \                                                       \
             !=======================================================!
   SCA Functional specification                                   Page 72
   Writing a JSYS SYSAP


     6.0  Writing a JSYS SYSAP

          This section is a detailed review of the differences between writing
     monitor  level  SYSAPs and user level SYSAPs.  The concepts are identical
     for the  two  SYSAP  types,  but  the  implementation  details  are  very
     different.   In  the reading of the following sections it is assumed that
     the sections on monitor level SYSAPs has been read.



     6.1  General rules

     6.1.1  Communicating with SCA

          When writing monitor level code SYSAPs communicate with SCA  through
     subroutine  calls.   The  SYSAP  obtains  services  from  SCA  by calling
     routines in SCA, and SCA returns event  information  by  calling  routine
     addresses  specified  by the SYSAP.  When writing JSYS code, services are
     obtained by executing the JSYS, and SCA  communicates  event  information
     through a series of PSIs.  In all there are four PSIs that the JSYS level
     SYSAP may have to handle.  One each  for  incoming  messages,  datagrams,
     named  buffer  completions  and  all other events.  If the SYSAP does not
     require some of these services then the PSI need not be enabled.



     6.1.1.1  Using the SCS% with the PSI system

          When using the PSI system with SCA keep in mind that the  SCS%  call
     to  add  channel must be done in addition to the usual set of JSYS calls.
     The SCS% call simply lets SCA know which channels  are  to  be  used  for
     which  event  types.   The  SIR%,  AIC%,  EIR%  (and their extended third
     cousins) etc.  must still be used to specify and enable the PSI system.



     6.1.2  Buffer management

          Buffer management for the JSYS SYSAP is  very  different  than  that
     done  for  monitor  SYSAPs.   There  are  still  four basic buffer types,
     messages and datagrams, both of which can be incoming or outgoing.



     6.1.2.1  Incoming buffers

          Buffers queued for reception of messages and datagrams must be large
     enough  to  handle  the largest packet possible.  The correct buffer size
     for messages is thirty eight (38) words, for datagrams this size  is  one
     hundred  fifty  two (152) words.  These buffers are queued in chains much
     the way they are in the monitor.  These buffers are  not  placed  on  the
     port  queues  however.   Monitor  internal buffers are placed on the port
     queues and data is BLTed to user space when it  arrives.   When  data  is
     moved  the  length to be BLTed is obtained from the packet.  Hence if the
   SCA Functional specification                                   Page 73
   Writing a JSYS SYSAP


     buffer is to short the end of the buffer will be BLTed over.  This is why
     the buffer must be at least as long as the longest packet possible.



     6.1.2.2  Outgoing buffers

          Buffers used for packets transmission need only be as  long  as  the
     packet text.  There are no other restrictions on these buffers.



     6.1.3  The race condition

          Something which comes  up  when  coding  a  monitor  SYSAP  is  that
     interlocking  further CI traffic is easy.  JSYS SYSAPs do not have things
     quite so simple.  In particular  there  is  a  race  that  a  JSYS  SYSAP
     designer should be aware of.  When a JSYS SYSAP does a listen, he is told
     about a connection to that listen with a PSI.  As soon as the  connection
     comes  in  and  the  match is found, the monitor changes the state of the
     connect to connectreceived rather than listen.  Hence if another  connect
     request  comes  in for that SYSAP before it has been told about the first
     connect request, then the second one will fail at the SCA level since  no
     match  can  be  found even though the SYSAP would likely want to see that
     connect.
          One reasonable solution to this problem is based on an understanding
     of  the  problem  by  both  the  active  and passive sides of the connect
     mechanism.  The listener should open more than  one  listen  (keeping  in
     mind  that  they do use system resources), and the connector should retry
     connect attempts if they fail.
   SCA Functional specification                                   Page 74
   Writing a JSYS SYSAP


     6.2  JSYS SYSAP interface

          The following is the general format of a call to the SCS% JSYS.


             Call
             T1/     Function code
             T2/     Address of arg block


             Return (+1) Always
             T1/     Function code
             T2/     Address of arg block
             
             An error generates an illegal instruction trap.

     General format of the argument block:

              !=======================================================!
     .SQLEN   !      Words processed      !     Length of block       !
              !-------------------------------------------------------!
              \                                                       \
              \             Function dependent arguments              \
              \                                                       \
              !=======================================================!

          Where the "words processed" is the number of words in  the  argument
     block  that the monitor actually looked at and used.  Hence this field is
     returned by the monitor, not supplied by the user.  The "length of block"
     is the total length of the supplied block including the header word.
          Note that this JSYS  requires  one  or  any  combination  of  wheel,
     maintenance, or network wizard.
   SCA Functional specification                                   Page 75
   Writing a JSYS SYSAP


     6.2.1  Connect (.SSCON)

                              Connect (.SSCON)



          This function requests a connection with another process on the  CI.
     The  JSYS  will  return  as soon as the connection request has been sent.
     You are notified that your connection request was granted or failed via a
     PSI interrupt.

     The argument block has the following format:

              !=======================================================!
     .SQLEN   !      Words processed      !     Length of block       !
              !-------------------------------------------------------!
     .SQSPN   !          Byte pointer to source process name          !
              !-------------------------------------------------------!
     .SQDPN   !       Byte pointer to destination process name        !
              !-------------------------------------------------------!
     .SQSYS   !   Node # of destination   !    SYSAP field for CID    !
              !-------------------------------------------------------!
     .SQCDT   !               Pointer to connection data              !
              !-------------------------------------------------------!
     .SQAMC   !    Address of first buffer on message buffer chain    !
              !-------------------------------------------------------!
     .SQADC   !    Address of first buffer on datagram buffer chain   !
              !-------------------------------------------------------!
     .SQRCI   !                  Returned connect ID                  !
              !=======================================================!



     The byte pointer to the source process name is  a  byte  pointer  to  the
     ASCII  string  which  is the name of your process.  Note that this string
     must end on a null byte and may be  a  maximum  of  16  bytes  long,  not
     including the null byte.

     The byte pointer to destination process name is the byte pointer  to  the
     name of the process you wish to connect to.  This name must also end in a
     null byte and may be a maximum of 16 bytes, not including the null byte.

     The node number is the unique  identifier  of  the  system  you  wish  to
     connect to.

     Note that the specified strings may be any valid ASCII  byte  size  (I.E.
     any byte size equal to or larger than 7 bits).  These strings may also be
     generic byte pointers (-1,,STRNG).  If generic byte pointers are given, 7
     bit ASCII terminated by a null byte is assumed.

     The "SYSAP field for CID" is the right justified value to be placed  into
     the SYSAP field of the connect ID created for the connection.  These bits
     are generally used for connection management by the user program.
   SCA Functional specification                                   Page 76
   Writing a JSYS SYSAP


     The pointer to connection data is the address of a block of  data  SQ%CDT
     words  long  to  be  sent as connection data.  Note that the monitor will
     copy SQ%CDT words of data from the users address  space.   Hence  a  full
     block SQ%CDT words long should be allocated for the data.


                              - Error codes -
     SCSNEP,SCSBTS,SCSISB,SCSNSN,SCSENB,SCSIAB,SCSIBP,SCSNBA
   SCA Functional specification                                   Page 77
   Writing a JSYS SYSAP


     6.2.2  Listen (.SSLIS)

                              Listen (.SSLIS)



          This function listens for a connection.  Note that the JSYS does not
     block.   You  will  be  notified  of  a  connect to your listen via a PSI
     interrupt.
          There are a number of options that may be used when doing  a  listen
     for  a  connection.   You  may  listen  for a particular process from any
     system by making the node number -1.  You may listen for any process from
     a particular system by making the byte pointer to the destination process
     name -1.  If the node number and the  byte  pointer  to  the  destination
     process  name  are  both  -1,  then any connect request that is not for a
     particular process name  will  match  your  listen.   Naturally  you  may
     specify  both a node number and a process name and then only that process
     from the named system will be allowed to connect to your listen.



              !=======================================================!
     .SQLEN   !      Processed words     !       Length of block      !
              !-------------------------------------------------------!
     .SQSPN   !          Byte pointer to source process name          !
              !-------------------------------------------------------!
     .SQDPN   !       Byte pointer to destination process name        !
              !-------------------------------------------------------!
     .SQSYS   !  Node # of destination   !    SYSAP field for CID     !
              !-------------------------------------------------------!
     .SQLCI   !                Returned connect ID                    !
              !=======================================================!



          The fields defined here are identical to those used by  the  connect
     call.   The  only difference is the absence of some of the fields used in
     the connect call.


                              - Error codes -
     SCSNBA,SCSNEP,SCSBTS,SCSISB,SCSNSN,SCSENB
   SCA Functional specification                                   Page 78
   Writing a JSYS SYSAP


     6.2.3  Accept (.SSACC)

                        Accept a connection (.SSACC)



          This function tells a remote  process  that  you  are  granting  his
     request for a connection.



             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                      Connect ID                       !
             !-------------------------------------------------------!
      .SQCDA !              Pointer to connection data               !
             !=======================================================!



          The pointer to connection data  is  the  address  of  the  block  of
     connection  data  to be sent to the remote system.  The monitor will copy
     SQ%CDT words of data from the users address space  as  data.   Note  that
     this  data will be sent directly over the CI and hence the low order four
     bits are not sent.


                              - Error codes -
     SCSNEP,SCSBTS,SCSIID,SCSCWS,SCSNBA
   SCA Functional specification                                   Page 79
   Writing a JSYS SYSAP


     6.2.4  Reject (.SSREJ)

                        Reject a connection (.SSREJ)



          This function code tells a remote process that you are not  allowing
     a connection to your process.

     The argument block for this function has this format:

             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                      Connect ID                       !
             !-------------------------------------------------------!
      .SQREJ !                   Rejection reason                    !
             !=======================================================!



          The rejection reason is a code, invented by the SYSAP, (outside  the
     revserved  range  /TBD/  codes)  which  indicates  why the connection was
     rejected.


                              - Error codes -
     SCSBTS,SCSIID,SCSNBA,SCSCWS,SCSNEP
   SCA Functional specification                                   Page 80
   Writing a JSYS SYSAP


     6.2.5  Disconnect (.SSDIS)

                            Disconnect (.SSDIS)



          This function closes a connection.  Note that the connection must be
     open  to  use  disconnect.   The  disconnect  function  code requires the
     following arguments:



             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                      Connect ID                       !
             !-------------------------------------------------------!
      .SQDIS !                   Disconnect reason                   !
             !=======================================================!



          The disconnect reason is a SYSAP invented code (outside the reserved
     range /TBD/) which indicates why the connection was disconnected.


                              - Error codes -
     SCSNEP,SCSBTS,SCSIID,SCSCWS,SCSNBA
   SCA Functional specification                                   Page 81
   Writing a JSYS SYSAP


     6.2.6  Send a DG (.SSSDG)

                          Send a datagram (.SSSDG)



          This function code sends a datagram.

     The following arguments are required:


             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                      Connect ID                       !
             !-------------------------------------------------------!
      .SQAPT !               Address of datagram text                !
             !-------------------------------------------------------!
      .SQLPT ! Len of message,high density (words), industry (bytes) !
             !-------------------------------------------------------!
      .SQFLG !                        Flags                  !  OPS  !
             !=======================================================!


          OPS is the path selection field.  OPS allows the JSYS user to select
     the  path over which the packet is to be sent.  The following setting are
     allowed for OPS:
             0 --> Automatic path selection
             1 --> Use path A
             2 --> Use path B
          If automatic path selection is chosen, the port hardware selects the
     path to use.

     The currently defined flags are:

             SC%MOD --> Packet transmission mode: 0 = industry compatable
                                                  1 = high density

                            *** Restrictions ***

     1.  If the datagram is to be sent in industry compatable mode,  the  text
         must be packed in left justified, word aligned, eight bit bytes.

     2.  The datagram text may not be  longer  than  152  (decimal)  words/608
         bytes  long.   The  byte count is for industry compatable packets and
         the word count for high density packets.



                              - Error codes -
     SCSNEP,SCSBTS,SCSIID,SCSDCB,SCSIAA,SCSNBA,SCSCWS,SCAMTL
   SCA Functional specification                                   Page 82
   Writing a JSYS SYSAP


     6.2.7  Queue a DG buffer (.SSQRD)

               Queue a buffer for datagram reception (.SSQRD)



          This function code queues buffers for datagram reception.
          Note that in each buffer the first word is the address of  the  next
     buffer.   The  last  buffer  has  zero as the address of the next buffer.
     This function requires these arguments:


             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                      Connect ID                       !
             !-------------------------------------------------------!
      .SQAFB !        Address of first buffer on buffer chain        !
             !=======================================================!


                            *** Restrictions ***


     1.  Datagram buffers must be 152 words in length.



                              - Error codes -
     SCSNEP,SCSIID,SCSNBA,SCSBTS
   SCA Functional specification                                   Page 83
   Writing a JSYS SYSAP


     6.2.8  Send message (.SSSMG)

                          Send a message (.SSSMG)



          This function code sends a message to a remote node.

             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                      Connect ID                       !
             !-------------------------------------------------------!
      .SQAPT !                Address of message text                !
             !-------------------------------------------------------!
      .SQLPT !  Len of message,high density (words), industry (bytes)!
             !-------------------------------------------------------!
      .SQFLG !                        Flags                  !  OPS  !
             !=======================================================!


          OPS is the path selection field.  OPS allows the JSYS user to select
     the  path over which the packet is to be sent.  The following setting are
     allowed for OPS:
             0 --> Automatic path selection
             1 --> Use path A
             2 --> Use path B
          If automatic path selection is chosen, the port hardware selects the
     path to use.
          The flags definitions may be found in the section for .SSSDG.


                            *** Restrictions ***

     1.  If this is an industry compatable  message  then  the  text  must  be
         packed in left justified 8 bit bytes.

     2.  Message text may not be longer than 38 36 bit words (152 bytes).



                              - Error codes -
     SCSIID,SCSNEP,SCSNBA,SCSBTS,SCSNSH,SCSDCB,SCSIAA
   SCA Functional specification                                   Page 84
   Writing a JSYS SYSAP


     6.2.9  Queue message receive buffers (.SSQRM)

                   Queue message receive buffers (.SSQRM)



          This function code queues buffers to receive  messages.   Note  that
     the  buffer size is fixed at 38, 36 bit words.  It requires the following
     arguments:


             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                      Connect ID                       !
             !-------------------------------------------------------!
      .SQAFB !            Address of buffer chain to queue           !
             !=======================================================!


                              - Error codes -
     SCSNEP,SCSIID,SCSNBA,SCSBTS
   SCA Functional specification                                   Page 85
   Writing a JSYS SYSAP


     6.2.10  Cancel DG receive (.SSCRD)

                      Cancel datagram receive (.SSCRD)



          This function code removes a buffer queued for  datagram  reception.
     The  address  that  you  specify must be the address of a buffer that was
     previously queued for receiving datagrams (with .SSQRD).  If this address
     is  not  found  by the monitor when it goes to take the buffer out of its
     queue, the JSYS fails with an illegal instruction  trap.   This  function
     requires these arguments:


             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                      Connect ID                       !
             !-------------------------------------------------------!
      .SQADB !             Address of buffer to dequeue              !
             !=======================================================!


                              - Error codes -
     SCSNSC,SCSNEP,SCSBTS,SCSNSB,SCSNEB
   SCA Functional specification                                   Page 86
   Writing a JSYS SYSAP


     6.2.11  Cancel receive message (.SSCRM)

                      Cancel receive message (.SSCRM)



          The  function  dequeues  a  buffer  that  was  queued  for   message
     reception.  The buffer address that is specified must be of a buffer that
     you asked to be queued for  message  reception  (with  .SSQRM).   If  the
     monitor does not find the address specified in the argument block amongst
     the buffers you queued, the JSYS will fail.  This function  requires  the
     following arguments:


             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                      Connect ID                       !
             !-------------------------------------------------------!
      .SQADB !             Address of buffer to dequeue              !
             !=======================================================!



                              - Error codes -
     SCSNSC,SCSNEP,SCSBTS,SCSNSB,SCSNEB
   SCA Functional specification                                   Page 87
   Writing a JSYS SYSAP


     6.2.12  Connect state poll (.SSCSP)

                        Connect state poll (.SSCSP)



          This function returns information about the state of  a  connection.
     The argument block to this function includes space for the returned data.
     The following is the format or the argument block:



             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                      Connect ID                       !
             !-------------------------------------------------------! ------------
      .SQCST !                   Connection state                    !      ^
             !-------------------------------------------------------!      !
      .SQDCI !                Destination connect ID                 !      !
             !-------------------------------------------------------!   Returned
      .SQBDN !       Byte pointer to destination process name        !     data
             !-------------------------------------------------------!      !
      .SQSBI !               Node number of destination              !      !
             !-------------------------------------------------------!      !
      .SQREA ! Source disconnect reasons !  Dest disconnect reasons  !      v
             !=======================================================! ------------


          Note that the byte pointer  to  destination  process  name  must  be
     provided by the caller and may be either a real byte pointer or minus one
     in the left half and the base address of the string in  the  right  half.
     If  the  generic byte pointer is used the monitor assumes the string is 7
     bit ASCII terminted with a null byte, or the  16th  chatacter,  whichever
     comes first.


                              - Error codes -
     SCSNEP,SCSBTS,SCSIID
   SCA Functional specification                                   Page 88
   Writing a JSYS SYSAP


     6.2.13  Return local node number (.SSGLN)

                     Return local node number (.SSGLN)



          This function returns the local node number.  If  the  machine  does
     not  have  a  KLIPA,  then  an  illegal  instruction  is  generated.  The
     following is the argument block format:


             !=======================================================!
      .SQLEN !      Processed words      !      Length of block      !
             !-------------------------------------------------------!
      .SQLNN !                 Local CI node number                  ! Returned data
             !=======================================================!




                              - Error codes -
     SCSBTS,SCSNKP
   SCA Functional specification                                   Page 89
   Writing a JSYS SYSAP


     6.2.14  Return configuration data (.SSRCD)

                     Return configuration data (.SSRCD)



          This function returns data about another  system.   Given  the  node
     number  the  monitor  will  return  data  about that system.  The data is
     returned in the block pointed to by T1 which looks like this:


             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                  Optional connect ID                  !
             !-------------------------------------------------------!
      .SQOSB !                 Optional  node number                 !
             !-------------------------------------------------------!  -----------
      .SQVCS !   Virtual circuit state   !        Port number        !       ^
             !-------------------------------------------------------!       !
      .SQSAD \                                                       \       !
             \     System address (6 8-bit bytes, word aligned)      \       !
             \                                                       \       !
             !-------------------------------------------------------!       !
      .SQMDD !           Maximum destination datagram size           !       !
             !-------------------------------------------------------!       !
      .SQMDM !           Maximum destination message size            !    Returned
             !-------------------------------------------------------!      data
      .SQDST !               Destination software type               !       !
             !-------------------------------------------------------!       !
      .SQDSV !             Destination software version              !       !
             !-------------------------------------------------------!       !
      .SQDSE !            Destination software edit level            !       !
             !-------------------------------------------------------!       !
      .SQDHT !               Destination hardware type               !       !
             !-------------------------------------------------------!       !
      .SQDHV !             Destination hardware version              !       !
             !-------------------------------------------------------!       !
      .SQPCW \               Port characteristics bytes              \       !
             \    6, 8 bit bytes, word aligned in leftmost 32 bits   \       !
             !-------------------------------------------------------!       !
      .SQLPN !                  Local port number                    !       v
             !=======================================================!  ------------


          The connect ID and node number are optional in that one or the other
     must  be  specified,  but  not both.  If the connect ID field is non-zero
     then the node number is ignored and the information returned is  for  the
     system  implied  by the connect ID.  If the connect ID field is zero then
     the node number is used.  Note that this allows the use of node zero.

          If the local port number is not available, -1 will  be  returned  to
     the user in offset .SQLPN.
   SCA Functional specification                                   Page 90
   Writing a JSYS SYSAP


                              - Error codes -
     SCSNEP,SCSBTS,SCSIID,SCSISB
   SCA Functional specification                                   Page 91
   Writing a JSYS SYSAP


     6.2.15  Return buffer sizes (.SSRBS)

                        Return buffer sizes (.SSRBS)



          This function returns the sizes of the various buffers  SCA  expects
     to  see.   In  particular  it  returns  the  size of message and datagram
     buffers.  It requires the following arguments:

             !=======================================================!
     .SQLEN  !       Process words       !       Block length        !
             !-------------------------------------------------------! -------------
     .SQLMG  !          Length in words of message buffers           !       ^
             !-------------------------------------------------------!       !
     .SQLDG  !          Length in words of datagram buffers          !   Returned
             !-------------------------------------------------------!     data
             !                       Reserved                        !       !
             !-------------------------------------------------------!       !
             !                       Reserved                        !       v
             !=======================================================! -------------
   SCA Functional specification                                   Page 92
   Writing a JSYS SYSAP


     6.2.16  Return status information (.SSSTS)

                     Return status information (.SSSTS)



          This function returns status information about a connection.  It  is
     intended  as  a  fast  form  of  the  .SSCSP  function code which returns
     detailed information about a  connection.   This  function  requires  the
     following arguments:

             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                      Connect ID                       !
             !-------------------------------------------------------!
      .SQFST !           Flags          !       Connect state        ! -------------
             !-------------------------------------------------------!    Returned
      .SQSBR !         Reserved         !     Node # of remote       !      data
             !=======================================================! -------------


          The flags which appear in the flags field are:

     1.  Message available (SQ%MGA)- There is at least one  message  available
         for this connection.

     2.  Datagram  available  (SQ%DGA)  -  There  is  at  least  one  datagram
         available for this connection.

     3.  Named buffer transfer complete (SQ%DMA) - At least one  named  buffer
         transfer  has  completed  since  the  last  time  the  SCS%  JSYS was
         performed with this function code.  The bit is cleared in the monitor
         data base when this function code is performed.



                              - Error codes -
     SCSBTS,SCSNEP,SCSIID
   SCA Functional specification                                   Page 93
   Writing a JSYS SYSAP


     6.2.17  Get a queue entry

          There are four functions for removing things from queues.  One  each
     for messages, datagrams, named buffer transfer competions, and "all other
     events".  In each case the monitor will issure a PSI for the  appropriate
     fork  when  when  of  these  queues goes non-empty.  The monitor will not
     issue a PSI for each entry.  It is the responsibility  of  the  SYSAP  to
     empty the queue once it has seen the PSI.



     6.2.17.1  Receive a message (.SSRMG)

                         Receive a message (.SSRMG)



          This function code returns message text for either the calling  fork
     or  the  specified  connection.   If the connect ID field in the argument
     block is minus one, then the first message found for the calling fork  is
     returned.   If the connect ID is anything but minus one (-1), the monitor
     will use this as a connect ID and return the first message found for that
     connection.   Note  that  if  there  is  no  message available an illegal
     instruction is generated.  The following argument block is  required  for
     this function code.


             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------! -----------
      .SQCID !                  Connect ID or -1                     !      ^
             !-------------------------------------------------------!      !
      .SQARB !              Address of returned buffer               !      !
             !-------------------------------------------------------! Returned data
      .SQDFL !          Flags           !       Node # of remote     !      !
             !-------------------------------------------------------!      !
      .SQLRP !               Length of returned packet               !      v
             !=======================================================! -----------


          The address of returned buffer is the address at which  the  monitor
     has  placed  your  data.  This address is one of the addresses previously
     specifed by a .SSQRM call.   If  no  .SSQRM  call  was  done,  then  this
     function code will fail with an illegal instruction trap.  If the address
     is not writable you will also get an illegal instruction trap.
          The flag definitions may be found in the section on SC.SDG.
          The length of the returned  packet  is  in  bytes  for  an  industry
     compatible mode message, and words for a high density mode packet.  It is
     always the length of the packet  text,  and  does  not  include  the  SCA
     headers.


                              - Error codes -
     SCSNEP,SCSBTS,SCSIID,SCSQIE,SCSNUB
   SCA Functional specification                                   Page 94
   Writing a JSYS SYSAP


     6.2.17.2  Receive a datagram (.SSRDG)

                        Receive a datagram (.SSRDG)



     This function code returns datagram text for either the calling  fork  or
     the  specified connection.  If the connect ID field in the argument block
     is minus one, then the first datagram  found  for  the  calling  fork  is
     returned.   If the connect ID is anything but minus one (-1), the monitor
     will use this as a connect ID and return the  first  datagram  found  for
     that connection.  This is the argument block for this function code:


             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------! -----------
      .SQCID !                  Connect ID or -1                     !      ^
             !-------------------------------------------------------!      !
      .SQARB !              Address of returned buffer               !      !
             !-------------------------------------------------------! Returned data
      .SQDFL !          Flags           !      Node # of remote      !      !
             !-------------------------------------------------------!      !
      .SQLRP !              Length of returned packet                !      v
             !=======================================================! -----------


     The address of returned data is one of  the  addresses  provided  to  the
     monitor on a .SSQRD call.  If no .SSQRD was done or if the address is not
     writable, the JSYS will fail with an illegal instruction trap.  If  there
     are no datagrams available, an illegal instruction is generated.
          The flags are returned by the monitor and  currently  only  indicate
     the data packing mode.
          The length of the returned packet is in words  if  this  is  a  high
     density datagram, and bytes if an industry compatible datagram.


                              - Error codes -
     SCSNEP,SCSBTS,SCSIID,SCSQIE,SCSNDQ,SCSNBA
   SCA Functional specification                                   Page 95
   Writing a JSYS SYSAP


     6.2.17.3  Get entry from data queue (.SSGDE)

                     Get entry from data queue (.SSGDE)



          This function code returns the first entry  from  the  data  request
     complete queue.  The argument block follows:

              !=======================================================!
      .SQLEN  !      Words processed      !      Length of block      !
              !-------------------------------------------------------!
      .SQCID  !                    Connect ID or -1                   !
              !-------------------------------------------------------!
      .SQBID  !          Name of buffer whos transfer completed       !
              !=======================================================!

          The buffer name indicates which transfer has completed.


                              - Error codes -
     SCSNEP,SCSIID,SCSBTS,SCSIAB
   SCA Functional specification                                   Page 96
   Writing a JSYS SYSAP


     6.2.17.4  Get an entry off the event queue (.SSEVT)

                 Get an entry off the event queue (.SSEVT)



          This function code retrieves the first entry off  the  event  queue.
     This  queue  is  a  record of events that the JSYS user is to be notified
     about.  The user receives an interrupt on the first  event.   After  this
     events  will  be added to the end of the queue with no further interrupts
     generated.  It is the responsibility of the user to empty this queue upon
     receiving an event interrupt.

          If a  connect  ID  is  specified,  then  the  next  event  for  that
     connection  will  be  returned.  If however the connect ID field is minus
     one, then the next event for the fork is returned.

              !=======================================================!
      .SQLEN  !      Words processed      !      Length of block      !
              !-------------------------------------------------------! -----------
      .SQCID  !                  Connect ID or -1                     !      ^
              !-------------------------------------------------------!      !
      .SQESB  !         Reserved          !      Node # of remote     !      !
              !-------------------------------------------------------!   Returned
      .SQEVT  !                 Returned event code                   !     data
              !-------------------------------------------------------!      !
      .SQDTA  \                                                       \      !
              \                 Returned event data                   \      !
              \                                                       \      v
              !=======================================================! -----------

          The event code describes what event has  occured.   It  is  a  small
     integer  ranging  from  zero  to a maximum value.  Hence it can easily be
     used as an index into an event dispatch table.  The connect ID tells  you
     what  connection this event is relevant to.  The event data is a block of
     data returned for each event type.

          The general format of the event code descriptions is as follows:
     .SExxx -- Text

     The .SExxx is the event code and text desribes the code

     .SQDTA -- Text
     This second line describes the format of the data provided for this event
     code, starting at word .SQDTA of the argument block.


     .SEVCC -- Virtual circuit closure
     .SQDTA -- Contains the pertinant node number

     .SECTL -- Connect to listen
     .SQDTA -- Four words of initial connection data from the remote.

     .SECRA -- Connection was accepted
   SCA Functional specification                                   Page 97
   Writing a JSYS SYSAP


     .SQDTA -- Four words of initial connection data from the remote.

     .SECRR -- Connection was rejected
     .SQDTA -- The reason code

     .SEMSC -- Message/datagram send complete
     .SQDTA -- address of sent buffer

     .SELCL -- Little credit left
     .SQDTA -- number of credits required to get you back over threshold

     .SENWO -- Node went offline
     .SQDTA -- Node number of system which went offline

     .SENCO -- Node came online
     .SQDTA -- Node number of system which came online

     .SEOSD -- OK to send data
     .SQDTA -- not used here

     .SERID -- Remote initiated disconnect
     .SQDTA -- not used here

     .SEPBC -- Port broke connection
     .SQDTA -- not used here

     .SECIA -- Credit is available
     .SQDTA -- unsed here


     .SEMAX is defined to be equal to the largest event code possible.


                              - Error codes -
     SCSNEP,SCSIID,SCSBTS,SCSIAB
   SCA Functional specification                                   Page 98
   Writing a JSYS SYSAP


     6.2.18  Named buffer overview

                           Named buffer overview



          To send data to a remote system, the SYSAP must first declare memory
     to be part of a buffer.  A buffer is made of segments.  Each segment is a
     contiguous set of 36 bit words that DO NOT CROSS A PAGE BOUNDARY and  are
     not  more  than one page long.  Once the buffer has been established, the
     SYSAP must give the remote system the buffer name  obtained.   N.B.   SCA
     does not give the remote the buffer name, it is the responsibility of the
     SYSAP to transmit this information.
   SCA Functional specification                                   Page 99
   Writing a JSYS SYSAP


     6.2.19  Map a buffer (.SSMAP)

                           Map a buffer (.SSMAP)



          This function code associates a portion of memory with an SCA buffer
     name  to  be  used  in  named  buffer transfers.  This function takes the
     following arguments:

             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQXFL !                        Flags                          !
             !-------------------------------------------------------!
      .SQBNA !                 Returned buffer name                  ! (Returned)
             !-------------------------------------------------------!
             /                                                       /
             /           Buffer length and address pairs             /
             /                                                       /
             !=======================================================!

          The current set of flags are as follows:

     1.  SQ%DMD -- Named buffer  mode.   This  two  bit  field  indicates  the
         desired  setting  of  the  mode  bits  for the buffer.  The following
         settings are defined:
         SQ%DIC -- Industry compatable mode
         SQ%DCD -- Core dump
         SQ%DHD -- High density
         Any other value is illegal.



          Buffer length and address pairs have the following format:


             !=======================================================!
     .SQBLN  !               Length of memory block                  !
             !-------------------------------------------------------!
     .SQBAD  !         Address of memory for data transfer           !
             !=======================================================!

          The length word in this block has one of two possible  values  based
     on  the  setting  of  the  mode bits.  If the buffer mode is core dump or
     industry compatable the length is in 8 bit bytes.  If the  mode  is  high
     density, the length is in 36 bit words.
          The address for data transfer is the address where you  expect  data
     from a data transfer to be placed by the CI port microcode.

          The buffer name is the descriptor by which all other  references  to
     this memory is made.
   SCA Functional specification                                  Page 100
   Writing a JSYS SYSAP


                            *** Restrictions ***

     1.  No buffer segment may cross  a  page  boundary.   Hence  the  longest
         possible buffer segment is one page.



                              - Error codes -
     SCSNEP,SCSBTS,SCSNBA,SCSIAB
   SCA Functional specification                                  Page 101
   Writing a JSYS SYSAP


     6.2.20  Unmap a buffer (.SSUMP)

                          Unmap a buffer (.SSUMP)



          This function will remove from  the  monitor  data  base  (unmap)  a
     memory  block  assigned  for  named  buffer transfers.  It requires these
     arguments:

             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQNAM !                     Buffer name                       !
             !=======================================================!


                              - Error codes -
     SCSNEP,SCSBTS
   SCA Functional specification                                  Page 102
   Writing a JSYS SYSAP


     6.2.21  Send data (.SSSND)

                             Send data (.SSSND)



          This  function  transfers  data  to  a  remote  host.   It  is   the
     responsibility  of a higher level protocol to arrange the setup of buffer
     names.  The call requires the following arguments:

             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !       Connect ID for which transfer is to be done     !
             !-------------------------------------------------------!
      .SQSNM !               Buffer name of send buffer              !
             !-------------------------------------------------------!
      .SQRNM !              Buffer name of receive buffer            !
             !-------------------------------------------------------!
      .SQOFS !        Xmit offset       !       Receive offset       !
             !=======================================================!


                              - Error codes -
     SCSNEP,SCSBTS,SCSIID
   SCA Functional specification                                  Page 103
   Writing a JSYS SYSAP


     6.2.22  Request data (.SSREQ)

                           Request data (.SSREQ)



          This function tells SCA and the port  to  get  data  for  the  given
     buffer name.  The following arguments are required:

             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !       Connect ID for which transfer is to be done     !
             !-------------------------------------------------------!
      .SQSNM !              Buffer name of send buffer               !
             !-------------------------------------------------------!
      .SQRNM !             Buffer name of receive buffer             !
             !-------------------------------------------------------!
      .SQOFS !        Xmit offset       !       Receive offset       !
             !=======================================================!

          The "xmit offset" is the number  of  bytes/words  the  sending  port
     should  skip  before  sending  data.  This count is in bytes for industry
     compatable/core dump mode sends and words for high density sends
          The "receive offset" is the number of bytes/words that the  receiver
     should skip before writing data from the wire.  The count is in bytes for
     industry comapatable/core dump and words for high density mode.


                              - Error codes -
     SCSNEP,SCSIID,SCSBTS
   SCA Functional specification                                  Page 104
   Writing a JSYS SYSAP


     6.2.23  Maintainance data send (.SSMDS)

                      Maintainance data read (.SSMDS)



          This function requests a maintainance data send.  It works much  the
     way  named buffer transfers do in that the .SSMAP call must be done first
     to set up a buffer.  The buffer name returned by .SSMAP is used  in  this
     call.  Note that the remote must provide the buffer name it has allocated
     for sending the data as well.


             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQMSS !               Buffer name of send buffer              !
             !-------------------------------------------------------!
      .SQMSR !              Buffer name of receive buffer            !
             !-------------------------------------------------------!
      .SQMOF !        Xmit offset       !       Receive offset       !
             !-------------------------------------------------------!
      .SQMDT !          Unused          !     Target node number     !
             !=======================================================!



          The xmit offset and receive offset are identical to those  used  for
     named buffer transfers.
   SCA Functional specification                                  Page 105
   Writing a JSYS SYSAP


     6.2.24  Maintainace data read (.SSMDR)

                      Maintainance data read (.SSMDR)



          This function requests a maintainance data read.  It works much  the
     way  named buffer transfers do in that the .SSMAP call must be done first
     to set up a buffer.  The buffer name returned by .SSMAP is used  in  this
     call.  Note that the remote must provide the buffer name it has allocated
     for sending the data as well.

             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQMSS !               Buffer name of send buffer              !
             !-------------------------------------------------------!
      .SQMSR !              Buffer name of receive buffer            !
             !-------------------------------------------------------!
      .SQMOF !        Xmit offset       !       Receive offset       !
             !-------------------------------------------------------!
      .SQMDT !          Unused          !     Target node number     !
             !=======================================================!


          The xmit offset and receive offset are identical to those  used  for
     named buffer transfers.
   SCA Functional specification                                  Page 106
   Writing a JSYS SYSAP


|    6.2.25  Start a remote system (.SSSRS)
|  
|                      Start a remote system (.SSSRS)
|  
|  
|  
|         This function will start a remote node.   A  start  address  may  be
|    specified or the default can be used.
|  
|             !=======================================================!
|     .SQLEN  !      Words processed      !      Length of block      !
|             !-------------------------------------------------------!
|     .SQSTN  !              Node number of target node               !
|             !-------------------------------------------------------!
|     .SQSFL  !                         Flags                         !
|             !-------------------------------------------------------!
|     .SQAST  !          Address for starting remote system           !
|             !=======================================================!
|  
|    The currently defined flags are:
|  
|    1.  SQ%DSA -- Use the default start address.  If this  bit  is  lit,  the
|        default address is used to start the target node.  If the bit is off,
|        the the address specified in word .SQAST of the argument block.
|  
   SCA Functional specification                                  Page 107
   Writing a JSYS SYSAP


|    6.2.26  Reset a remote system (.SSRRS)
|  
|                      Reset a remote system (.SSRRS)
|  
|  
|  
|         This function resets a remote node.
|             !=======================================================!
|     .SQLEN  !      Words processed      !      Length of block      !
|             !-------------------------------------------------------!
|     .SQNTN  !              Node number of target node               !
|             !-------------------------------------------------------!
|     .SQRFL  !                         Flags                         !
|             !=======================================================!
|  
|    The currently defined flags are:
|        SQ%FRB -- Force reset.  If this bit is not set,  the  reset  is  only
|        done  if  the  local  host  was  the last host to send a reset to the
|        target node.  If the bit is on, the reset is done no matter who  last
|        reset the target node.
|  
   SCA Functional specification                                  Page 108
   Writing a JSYS SYSAP


     6.2.27  Set port counters (.SSSPC)

                         Set port counters (.SSSPC)



     This function  sets  the  port's  performance  counters.   The  following
     arguments are required:


|             !=======================================================!
|     .SQLEN  ! Number of words processed !      Length of block      !
|             !-------------------------------------------------------!
|     .SQNOD  !                      Node number                      !
|             !-------------------------------------------------------!
|     .SQPCW  !               Port counter control word               !
|             !-------------------------------------------------------!
|     .SQCPC  !   Number of times the counters have been set/cleared  ! (Returned)
|             !=======================================================!
|  
|     Node number:  Node number or 377 for all nodes
|  
|     Port counter control word, bits as follows:
|  
|                       B0   If on, count ACKs received on Path A.
|                       B1   If on, clear the counter.
|                       B2   If on, count NAKs received on Path A.
|                       B3   If on, clear the counter.
|                       B4   If on, count NO_RSPs received on Path A.
|                       B5   If on, clear the counter.
|                       B6   If on, count ACKs received on Path B.
|                       B7   If on, clear the counter.
|                       B8   If on, count NAKs received on Path B.
|                       B9   If on, clear the counter.
|                       B10  If on, count NO_RSPs received on Path B.
|                       B11  If on, clear the counter.
|                       B12  The count of discarded datagrams because
|                            of no DGFree Queue entries.
|                       B13  If on, clear the counter.
|                       B14  Count  the  packets  transmitted to  the
|                            designated port.
|                       B15  If on, clear the counter.
|                       B16  Count  the  packets  received  from  the
|                            designated port.
|                       B17  If on, clear the counter.
|  
|         The count of times the counters have been set/cleared  reflects  the
|    number  of  SCS% JSYS that have been done to set/clear the port counters,
|    not including the current one.  I.E.   the  call  just  executed  is  not
|    included in the returned count.
   SCA Functional specification                                  Page 109
   Writing a JSYS SYSAP


|    6.2.28  Read port counters (.SSRPC)
|  
|                        Read port counter (.SSRPC)
|  
|  
|  
|         This function  reads  the  maintenance  counters  out  of  the  port
|    hardware.  The following argument block is used:
|  
|  
|            !=======================================================!
|     .SQLEN !      Processed words     !       Length of block      !
|            !-------------------------------------------------------!  -----------
|     .SQMCV !                  Microcode version                    !       ^
|            !-------------------------------------------------------!       !
|     .SQPAA !                   Path A ACK count                    !       !
|            !-------------------------------------------------------!       !
|     .SQPAN !                   Path A NAK count                    !       !
|            !-------------------------------------------------------!       !
|     .SQPAR !               Path A no response count                !       !
|            !-------------------------------------------------------!       !
|     .SQPBA !                   Path B ACK count                    !       !
|            !-------------------------------------------------------!    Returned
|     .SQPBN !                   Path B NAK count                    !      data  
|            !-------------------------------------------------------!       !
|     .SQPBR !               Path B no response count                !       !
|            !-------------------------------------------------------!       !
|     .SQNDD !              Number of dropped datagrams              !       !
|            !-------------------------------------------------------!       !
|     .SQNPT !             Number of packets transmitted             !       !
|            !-------------------------------------------------------!       !
|     .SQNPR !              Number of packets received               !       !
|            !-------------------------------------------------------!       !
|     .SQPOR !                    Designated port                    !       !
|            !-------------------------------------------------------!       !
|     .SQNCC !      Number of times counters have been set/cleared   !       v
|            !=======================================================!  -----------


          Only the function code is passed to the monitor.  The rest  of  this
     block is information returned by the monitor.


                              - Error codes -
     SCSNEP,SCSBTS,SCSNBA
   SCA Functional specification                                  Page 110
   Writing a JSYS SYSAP


     6.2.29  Add interrupt channels (.SSAIC)

                      Add interrupt channels (.SSAIC)



          All notifications from SCA  happen  on  five  PSI  channels.   These
     channels  are  set  for:   datagram  available,  message available, named
     buffer transfer complete, events, and configuration change.   The  events
     are  detailed  in  the  section  on  the  .SSEVT  funtion code.  The only
     function performed by the .SSAIC code, is to inform SCA of which channels
     you  wish to use for the variuos interrupts.  It does not activate any of
     the channels, enable the PSI system, or set LEVTAB and CHNTAB for you.
          The argument block used to associate events with  PSI  channels  has
     this format:

             !=======================================================!
      .SQLEN !      Words processed      !      Length of block      !
             !-------------------------------------------------------!
             \                                                       \
             \          Up to four channel descriptor words          \
             \                                                       \
             !=======================================================!

     Where channel descriptor words have the following format:

             !=======================================================!
             !    Interrupt type code    !   Channel for this code   !
             !=======================================================!

     The interrupt type code is a small integer that indicates an event  type.
     The  channel number field allows you to enable and disable interrupts for
     the given event type.  If the channel number is -1  then  interrupts  are
     disabled.   If  it  is an integer between zero and thirty five, then that
     channel will interrupt on the given event  type.   The  next  box  is  an
     example of what the maximum size block would look like.

             !=======================================================!
      .SQLEN !      Words processed      !      Length of block      !
             !-------------------------------------------------------!
             !          .SIDGA           !      Channel number       !
             !-------------------------------------------------------!
             !          .SIMSA           !      Channel number       !
             !-------------------------------------------------------!
             !          .SIDMA           !             -1            !
             !-------------------------------------------------------!
             !          .SIPAN           !      Channel number       !
             !-------------------------------------------------------!
             !          .SICFG           !      Channel number       !
             !=======================================================!

     In this example interrupts for message available, datagram available, and
     all  other events are being enabled.  Interrupts on DMA transfer complete
     are being disabled.  Note that only the first word  of  this  block  need
   SCA Functional specification                                  Page 111
   Writing a JSYS SYSAP


     appear  in this position.  The channel descriptor words may appear in any
     order.  There must be at least one but  not  more  than  four  descriptor
     words in a block.

     To set up the PSI system for use with SCA, the following JSYS's  must  be
     done:

     1.  SIR%/XSIR%

     2.  AIC%

     3.  EIR%

     4.  SCS% with the .SSAIC function code



                              - Error codes -
     SCSBTS,SCSNEP,SCSNSP



















                          Design specification for the
                       Systems Communications Architecture

                                    21-Sep-83
   SCA Design specification                                             Page 1
   Introduction


   1.0  Introduction

   1.1  Scope

        This document is intended as a guide to SCAMPI and SCSJSY, the TOPS-20
   implementation  of  the  Systems Communications Architecture protocol.  Any
   non-obvious code or algorithm used in either the monitor SYSAP support code
   or  JSYS support code is described here.  It is a non-goal to describe each
   routine in detail.  The intent is to provide a map of major highways, not a
   street map.
        The document is broken into two parts, one  for  SCAMPI  and  one  for
   SCSJSY.   Each  could  easily  be  a  stand alone document but are included
   together here for consistency with other SCA documents and convenience.



   1.2  Related documents

   The reader should at least be familiar with the following documents  before
   proceeding with this specification.  The corporate SCA spec is particularly
   important as all terminology used in this document follows standards set in
   the corporate spec.

        1.  SCA Functional Specification, 19-September-83 (CDunn)

        2.  Systems Communications Architecture, 20-July-82 (Strecker)

        3.  LCG CI Port Architecture Specification, 11-July-83 (Dossa/Keenan)

        4.  TOPS-20 Coding Standard, 23-Mar-83 (Murphy)
   SCA Design specification                                             Page 2
   SCAMPI (Monitor SYSAP support)


   2.0  SCAMPI (Monitor SYSAP support)

   2.1  Major data structures

   2.1.1  System block

        The system block is the set of per system data for each  remote  known
   to  the  monitor.   The  set  of  system  blocks  for the local host can be
   accessed through the system block list (SBLIST).  This is the  sparse  list
   of all system block addresses.  Each entry is accessed by indexing into the
   list by node number.  This will yield the address of the system  block  for
   that  node  number.   In addition to SBLIST each system block has a forward
   link to the next block.
        There is a special index into SBLIST.  When -1  is  given  as  a  node
   number  on  a  listen call, the SYSAP is indicating that any remote node is
   acceptable.  Hence -1 is only meaningful when doing a listen call.
        System block data includes the work queue, the  connect  block  queue,
   and  the work queue for this remote.  The system block is mainly maintained
   by the port driver but there are cells maintained by SCA.  These cells  are
   described in [1].



   2.1.2  Connect Block

        The connect block is the  per  connection  database  and  is  entirely
   maintained  by  SCA.   All connect blocks are linked onto two doubly linked
   queues.  One of these lists is the set  of  connections  for  a  particular
   system  block.   The  other  list  is  the  set  of  connections owned by a
   particular fork.  This list and its uses are described in the  second  half
   of  this  document  in  the  section on SCSJSY.  Further description of the
   cells in this block may be found in [1].



   2.1.3  Remote system work queue

        These queues (one per known remote) are used for the stacking  of  SCA
   overhead   messages  to  remotes.   Since  the  protocol  allows  only  one
   outstanding overhead message at any time  for  each  remote,  the  overhead
   messages  which  SCA desires to send while there is one already outstanding
   are placed on this queue.  When the response  to  the  outstanding  message
   comes  in,  the next message on this queue is sent.  Note that the head and
   tail pointers for these queues are stored in  the  system  block  for  each
   node.



   2.2  Overview

        SCAMPI can be broken down into a number of major areas, routines  that
   process   requests  from  SYSAPs,  interrupt  handlers,  periodic  function
   handlers, buffer management routines, and general support routines.
   SCA Design specification                                             Page 3
   SCAMPI (Monitor SYSAP support)


   2.2.1  SYSAP request handlers

        The request handlers are the most simple and straight forward part  of
   SCAMPI.   These  routines  are  most easily understood by reading the code,
   rather than a verbal description here.  There are however some rules  which
   are followed in this set of routines.
        The more important rule is that interrupt level  may  come  along  and
   change connection data out from under the nose of a request handler.  Hence
   an interlock scheme must be arranged for places that cannot tolerate such a
   change.   For  all data except the connect state, the CION/CIOFF macros may
   be used to interlock connection data for periods  of  a  few  instructions.
   Since  the  connection  state needs to be interlocked for very long periods
   (perhaps up to a  millisecond)  another  interlock  scheme  is  used.   The
   SCON/SCOFF  macros  are  used to interlock the connect state.  These macros
   call the routines SC.SOF and SC.SON in SCAMPI which  will  do  nesting  and
   interlock  checking much like that done by CION/CIOFF.  See the sections on
   SC.SON and SC.SOF for more details on these routines.
        There is one other interlock scheme used for single instructions  that
   wish  to  increment  fields  in  the connect block.  In particular when SCA
   wishes to update the credit fields in the connect block, an  ADDM  AC,CBLOC
   is done where AC contains the number of additional credits (or negative for
   returning credit) and CBLOC is the address of the full word credit field in
   the  connect  block.   Since we can be guaranteed that the instruction will
   complete once started we can be sure  that  the  instruction  need  not  be
   interlocked with CION/CIOFF.
        The second rule is that  the  SYSAP  is  trustworthy.   Hence  minimal
   checks  are  done  for SYSAP argument validity.  Only data items over which
   the SYSAP has no direct access (E.G.  connection state) are checked.



   2.2.2  Interrupt handlers

        There are a number of entry points in SCA for the port driver to  call
   at  interrupt  level.   Each  of these entry points makes a few assumptions
   about what has happened and what it can do.
        A common assumption made by all interrupt handling  routines  is  that
   they may change certain data items in the connect block.  In particular the
   the receive credit level may be changed at interrupt level.  The connection
   state on the other hand is a special case.  The problem is that we may very
   well be interrupting a  piece  of  code  that  checked  the  state  of  the
   connection,  saw  that  it  was  open,  and  is  about  to send messages or
   datagrams based on this check.  The connection must  not  be  closed  until
   after  this packet send is complete.  Hence there is an interlock mechanism
   for the connection state.  The SCOFF/SCON macros turn off/on the ability to
   change  the connect state.  When the SCON is done by the sensitive routine,
   a support routine is called to check a connection specific queue for change
   of state request blocks.  A part of this block is the address of a chain of
   packets that needs to be sent along with the change of state.
        A specific case is the sending of a disconnect request.  When a remote
   sends  the  local host a disconnect request, the interrupt handler for this
   message type checks the interlock for the connect block state.   If  it  is
   unlocked  it  proceeds  to send the rest of the handshake.  If it is locked
   however, it puts an entry onto the connection's  block  state  queue  along
   SCA Design specification                                             Page 4
   SCAMPI (Monitor SYSAP support)


   with  the  address  of  the  chain  of  messages to send, (in this case the
   disconnect response followed by the disconnect request) and returns.   When
   the  routine which locked the connection state releases the lock, the queue
   is checked for change of state entries.  From the remotes point of view, an
   application  packet  will  be  received for a connection which has sent the
   first part of the disconnect handshake.  Hence it  must  drop  this  packet
   without closing the VC.



   2.2.2.1  SC.ONL

        At this  entry  point  SCA  assumes  that  a  new  VC  has  just  been
   established.   It may be a reopening of an old VC or the first circuit to a
   new node.  In either case we have the  node  number  of  the  system  newly
   arrived  and  we  may  go  ahead  and  perform  SYSAP notifications.  These
   notifications are different from all others in that it  happens  on  a  per
   SYSAP  basis  rather  than  a per connection basis.  There was no reason to
   notify the same SYSAPs once for each connection it owns about a  new  node.
   Hence  the SYSAP notifies SCA of an address to call when this event occurs.
   Typically  this  address  is  the  same  address  given   for   all   other
   notifications,  but  that is a decision for the SYSAP designer.  Each SYSAP
   notified requires the event code for new circuit and the node number of the
   newly aquired node.



   2.2.2.2  SC.ERR

        This is the entry point for circuit closure.  If a circuit  is  closed
   for any reason, SCA expects the port driver to call this entry point.  This
   includes the case of SCA requesting a circuit closure.  It should be  noted
   here  that  SCA  must  request  the  opening of a circuit after it has been
   closed.  This is accomplished through the use  of  the  SCOFF/SCON  macros.
   Upon  receiving  notification  of  circuit closure, SCA must close all open
   connections on that circuit.  It cannot change the state  of  a  connection
   which  has  the connect state interlocked however.  A circuit wide count of
   interlocked circuit states is maintained.  When a SCON macro is  performed,
   the  count has reached zero and the flag for "VC requires open call" is set
   in the system block, then we may call the port driver to open  the  circuit
   again.   While  SCA is here, we must notify all SYSAPs that the circuit has
   gone away.  This implies that the SYSAP must be able to deal with a circuit
   going away during an SCA call.



   2.2.2.3  SC.OFL

        This entry point is identical to SC.ERR except the code used on  SYSAP
   notification is for node offline rather than circuit closed on error.
   SCA Design specification                                             Page 5
   SCAMPI (Monitor SYSAP support)


   2.2.2.4  SC.DMA

        This entry point is called when a named buffer transfer has completed.
   All  that needs to be done here is notify the connection that requested the
   transfer.



   2.2.2.5  SC.INT

        This is the major interrupt level entry point for  SCA.   It  is  from
   this  point  that  SCA handles all incoming application and SCA packets.  A
   dispatch to the correct routine is done based  on  the  SCA  message  type.
   Other  than  the  general  interrupt level cautions outlined above, nothing
   very special is done here.
   SCA Design specification                                             Page 6
   SCAMPI (Monitor SYSAP support)


   2.3  Periodic function handlers

        Within SCA there are a few functions that are handled on  a  per  time
   basis.   At  present  these  functions  are idle chatter, the management of
   buffer allocation levels, and the deletion of  connection  data.   All  SCA
   time driven activity happens during the one hundred millisecond clock cycle
   of the scheduler.  Hence there  is  a  clock  counter  and  instruction  to
   execute  in STG for the SCA clock.  The instruction is a PUSHJ into SC.CLK.
   This routine then does simple checks to see if  it  is  time  for  any  SCA
   events  to happen, and dispatches to the correct handling routines when the
   events are due.



   2.3.1  Idle chatter

        Idle  chatter  is  defined  as  the  polling  of  remote  nodes   with
   connections   open  to  them.   This  is  done  since  most  port  hardware
   implementations can answer a  request  ID  without  software  intervention.
   Hence the port driver poller will not declare a node offline until it stops
   answering request IDs on both paths.   Since  the  port  can  stay  up  for
   extremely  long  periods afer the software has crashed, detection of remote
   software failure could potentially take a very long time.  Hence  SCA  will
   send  a credit request for zero credit to any remote which has a connection
   open to it.  These credit requests are only sent if the node has  not  sent
   us  a  packet  for  over  five  seconds.   If a credit request is sent, the
   response turn around  is  timed.   If  the  response  arrives  within  five
   seconds,  the node is online and SCA does nothing except turn off the timed
   message flag in the system block.  If the response has  not  arrived  after
   five seconds, the node is declared down and circuit closure is requested.



   2.3.2  Buffer allocation level management

        Buffer levels are handled with a twofold process.  First, a  threshold
   level  is  maintained,  below  which  SYSAPs  may  request  buffers without
   waiting.   If  a  SYSAP  directly  calls  a   buffer   allocation   routine
   (SC.ABF/SC.ALD)  with  a request for more than what is on hand, the failure
   return is taken and no further action is taken by SCA.  In  general  it  is
   assumed  that  for cases other than connection startup and packet reception
   buffers SYSAPs will only make  small  buffer  requests  (between  1  and  3
   buffers).   These  requests  will  generally  present  no  problem,  as the
   threshold level should be well above this.
        Second, if a connect  request,  listen  request,  accept  request,  or
   receive  buffer  request is made with a large numbers of buffers specified,
   SCA will try to fill the request immediately.  If this request would put us
   under  threshold,  then the request is defered until job 0 can allocate the
   buffers.  All of this is transparent to the SYSAP  however.   The  returned
   information (if any) is the same whether the buffers were available or not.
   If the buffers were not available, then whatever the SYSAP  requested  will
   take  longer  to  finish.   Since no SYSAP should time these requests, this
   does not present a problem.
        Internally, SCA notices that the request for buffers will put us under
   SCA Design specification                                             Page 7
   SCAMPI (Monitor SYSAP support)


   threshold  and  hence  this  request  must  be  defered.  Hence the connect
   request message is placed on a queue, hung off the system block.  Note that
   at  this  point  the  connect  request has been completely assembled and is
   ready for transmission.  In addition to the normal connect request data,  a
   short  block  of  data  used  for  creating  the  required buffers has been
   appended to the connect request.  After the entry  has  been  made  to  the
   queue,  job  zero is poked to run and check for this type of request.  Once
   job zero has created the required buffers, it will either  call  SC.SCA  to
   send  a  request,  or will simply return the buffer to the SCA free pool if
   this is a buffer queue request.
        The following is the format of the data block  used  to  describe  the
   allocation of additional buffers:

            !=======================================================!
            \                                                       \
            \        Space for largest SCA overhead message         \
            \                                                       \
            !-------------------------------------------------------!
   .BZNUM   !   # of message buffers    !   # of datagram buffers   !
            !=======================================================!

   .BZNUM
   This word defines the number of buffers to be allocated.


        Note that if there are message  buffers  being  created,  the  message
   being  sent  here  is a credit request.  Hence the count of message buffers
   plus the current pending receive credit must be placed in the credit  field
   of  the  packet.   If  there are datagram buffers being added here then the
   count of datagram buffers in the connect block must be updated  to  include
   these new buffers.



   2.3.3  Connection data deletion (SC.RAP)

        This periodic function is responsible  for  the  return  of  resources
   associated  with  aborted  or disconnected connections.  Once the abort bit
   has been set by some other part of SCA, the next pass of this function will
   light the reap bit.  On the following cycle, SC.RAP will check the count of
   packets outstanding on the KLIPA command queue and delete the connect block
   if the count is zero.  It should be noted that this count of packets on the
   queue only accounts for packets that the software gets  back.   I.E.   only
   those  packets  which  do  not end up on a free queue are counted.  Packets
   which end up on a free queue are not seen by the software  after  the  send
   has  completed  and  hence cannot be counted.  There is a substantial delay
   however (minimum of 15 seconds) between the abort of the connection and the
   deletion  of the data.  This should allow enough time for those packets not
   counted to make it off the KLIPA command queue.
   SCA Design specification                                             Page 8
   SCAMPI (Monitor SYSAP support)


   2.4  Buffer management routines

        These routines handle the allocation  and  return  of  SCA  free  pool
   buffers.   The  SCA  free  pool  is  a  singly  linked  list of the buffers
   available.  There are two  such  pools,  one  for  datagrams  and  one  for
   messages.  The return of buffers to these pools is a simple operation where
   the buffer is placed at the end of the  list  and  the  buffer  pool  count
   incremented  as  necessary.   The  allocation of these buffer is a bit more
   complex however.
        When SCA is called upon to allocate a number of buffers (N)  from  one
   of  the  free  pools,  there  are  a number of checks that need to be done.
   First, if there are not enough buffers to fill the request  (as  determined
   from  the  buffer  count)  the  request is rejected outright.  If there are
   enough buffers but the number of buffers remaining in the pool is less than
   a  threshold value, then the request is granted and flags are lit for job 0
   to add more buffers to the free pool.  The number of buffers added is based
   on  the  number of nodes seen the in network plus a few additional buffers.
   If during the process of allocating the buffers, it is determined that  the
   buffer  count is wrong and there are in fact not enough buffers to fill the
   request, the partial allocation is  returned  to  the  free  pool  and  the
   request  is  rejected.   After  this process the free pool count is correct
   since the allocation kept track of how many buffers  were  in  the  partial
   allocation.



   2.5  General support routines

        These routine perform the common functions required  to  support  SCA.
   In  general  these are very simple routines that need no explanation.  Only
   those which make assumptions that  are  not  obvious,  or  those  that  use
   non-obvious algorithms shall be called out.



   2.5.1  Connection data deletion

        When an open connection has been disconnected or  any  connection  has
   been  aborted, the database for that connect must be deleted.  This is done
   by a number of routines whos' function may not be completely  obvious.   In
   general  the  idea  is  to wait for all outbound traffic to complete before
   deleting connection data.  This can be done since the handling  of  inbound
   packets  is  identical whether the data is around or not.  Outgoing traffic
   is easily handled since there is a count of  outstanding  messages  on  the
   port  queues  in  the  connect  block.   When  this  count goes to zero all
   outgoing traffic has completed.  We are guaranteed that there  will  be  no
   further  traffic  since SCA will not try to send packets on a connection in
   any state but open.  Once this count has gone to  zero,  the  data  may  be
   deleted.
        To insure that the KLIPA has had time to complete transmission of  any
   packets outstanding for this connect, SCA waits a while before checking the
   counts.  The periodic function to check reap and abort bits will then clean
   up  the  connect  data  and all resources associated with the connect.  For
   more detail on this process, see the section on periodic functions.
   SCA Design specification                                             Page 9
   SCAMPI (Monitor SYSAP support)


   2.5.2  SC.SON/SC.SOF

        These routines interlock the connect state of each connection.   There
   is  an  interlock  word  in  the  connection block that when positive is an
   indication that the lock is locked and someone wishes  to  lock  it.   When
   zero  the  lock is locked but there are no other requests to lock it.  When
   -1 the lock is available.  When interrupt level  discovers  that  it  would
   like  to  change the state of the connection but the lock is not available,
   an entry is made to a system wide queue, indicating the  new  state  and  a
   chain  of packets that need to be sent as a result of this new state.  When
   the unlock is done this queue is checked for entries for  this  connection.
   If entries are found they are processed immediately.



   2.5.3  SC.PON/SC.POF

        These two routines are responsible for the turning off and  on  of  CI
   interrupts.   This  is  accomplished  through  the turning off/on of the PI
   channel for the KLIPA.   The  following  algorithm  is  used  to  determine
   whether the channel state should be changed.
   SCA Design specification                                            Page 10
   SCAMPI (Monitor SYSAP support)


                                   - SC.POF -

























                                     Fig. 1
   SCA Design specification                                            Page 11
   SCAMPI (Monitor SYSAP support)


                                   - SC.PON -

























                                     Fig. 2
   SCA Design specification                                            Page 12
   SCSJSY (User mode SYSAP support)


   3.0  SCSJSY (User mode SYSAP support)

   3.1  Overview

        SCSJSY provides a user interface to the CI through SCA.  To do this it
   does  nothing  more  than  translate  user  requests into SCA SYSAP request
   handler calls and turns SCA callbacks into a PSI for a fork.  A major  part
   of  this  job is the careful checking of user arguments.  Since SCA assumes
   that SYSAPs are trustworthy, a bad argument to an  SCA  call  can  cause  a
   system crash or CI failure fatal to a circuit.  Hence SCSJSY must take care
   to insure the integrity of user arguments.
        In  general,  SCSJSY  handles  two  types  of  traffic,  inbound,  and
   outbound.   Inbound  traffic is placed on fork and connection lists and the
   owning fork gets a PSI if the list was empty before  this  packet  arrived.
   Outbound  traffic  is placed on KLIPA command queues through the use of SCA
   calls and blocks until the confirmation of send complete comes up from SCA.
   This  blocking  is  necessitated  by  the  way packet transmission is done.
   Details of this process can be found in the section on  JSYS  level  packet
   transmission.
        The structure of SCSJSY can be broken up into two parts, a  part  that
   handles  service  requests  from  the  user,  and  a  part  to  handle user
   notification of interrupt events.



   3.2  Major data structures

   3.2.1  Connect blocks

        In addition to the data for monitor SYSAP support, the  connect  block
   contains  a  number  of  cells  for JSYS SYSAP support.  These include user
   buffer counts and list head/tail pointers for various per connection lists.
   In  general  these lists are all doublely linked, and each piece of data is
   on two of the lists.  In particular each piece of data is on  a  fork  list
   and  on  a  connection list.  This enables JSYS SYSAPs to request data on a
   fork wide basis or  a  per  connect  basis.   This  is  greatly  simplifies
   management of multiple connections.  It also means that when data items are
   added or removed from its lists, they will very likely be pulled  from  the
   front  of  one  list and the middle of the other.  All support code must be
   prepared to deal with this case.
        A side effect of having data available on a fork wide  basis  is  that
   the  head/tail  pointers  for  the  lists  appear in the PSB.  As a result,
   various places in the code will want to modify the PSB of another fork,  or
   in  the case of interrupt level, modify non-resident memory.  To solve this
   problem a system wide list was created to store data  items  until  process
   level could be summoned to modify non-resident memory.  The details of this
   process can be found in the section on interrupt level processing.
        Connect blocks do not present this kind  of  problem  since  they  are
   always  resident.   They  do  however  appear  on a chain of connect blocks
   available to the fork.  Hence when the first or last connect block  on  the
   list  is  deleted, the PSB of the owning fork will be modified.  Hence this
   process also happens in process context.  The  details  of  the  connection
   block  deletion  process  can  be  found  in  the  section on monitor SYSAP
   support.
   SCA Design specification                                            Page 13
   SCSJSY (User mode SYSAP support)


   3.2.2  SCA data section

        To ease the allocation of memory, SCA has a  virtual  section  all  to
   itself.  This section has two uses, a place to allocate buffer space, and a
   place to map user packets for  transmission.   Buffer  space  is  allocated
   starting  at  the end of the section and grows down into memory a page at a
   time.  User packets being made ready for transmission are mapped  into  the
   begining  of  the  section.   This scheme allows the section to be used for
   both purposes and still have a dense set of pages for each.



   3.3  Service request handlers

        Unless otherwise noted,  service  request  handlers  check  arguments,
   translate  required arguments into format for passing to SCA, call SCA, and
   return.  If any data needs to be passed back to the user  program  that  is
   not  returned  by  the call to SCA, an event is generated and placed on the
   fork/connection event queue.



   3.3.1  Send a packet (SCSSMG/SCSSDG)

        A major consideration in sending packet data was the performance  loss
   caused   by   copying  data  from  user  space  to  monitor  space.   Hence
   SCSSMG/SCSSDG maps the packet into the low end of the SCA section.  This is
   the  why  the  set  of  restrictions  (detailed in [1]) is placed on packet
   sends.  Since the SCA header must be contiguous with the packet text, there
   must  be  room for the header between the page boundry and the start of the
   SYSAP text.  This is why the SYSAP specifies the base address  of  the  SCA
   header  and  not the base of the SYSAP text when talking about buffers.  It
   insures the SYSAP understands that room for the header must be available.



   3.3.2  Read port counters

        To read the port counters the port driver must place a  command  on  a
   KLIPA  command  queue  and  notify  SCA when the response comes back on the
   KLIPA response queue.  Hence the SCA call will not return directly with the
   requested information.  In this case however the JSYS call will block until
   the information has been  returned.   This  alleviates  the  need  for  yet
   another event type, and since this is not really an event but a request for
   information, it returns the data immediately just as the other  information
   calls  do.   It  just  has to wait a while to return the information.  Care
   must be taken however to not be NOINT wile doing this.  This will allow the
   user  to  get  out  of  a hung call to SCS%.  This implies that the routine
   which returns this information must be able to handle the connection  going
   away  when the data actually comes back.  It also means no resources can be
   owned when the dismiss is done.
   SCA Design specification                                            Page 14
   SCSJSY (User mode SYSAP support)


   3.4  Interrupt event handlers

        The operation of the interrupt handlers  is  actually  rather  simple.
   Each  mearly  records  a  small  amount of data into a block and places the
   block onto a system wide list.  It is the handling of this  list  which  is
   rather circuitous:

        1.  Interrupt level places  entry  on  system  wide  queue  and  zeros
            location  SCSTIM.   This location is the clock counter for a 100ms
            scheduler clock.  SCHED will notice that the count is zero and XCT
            a CALL SCSCLK on the next 100ms cycle.

        2.  Upon arrival at SCSCLK the entire system  wide  list  is  scanned.
            The  target  fork number is retrieved from each entry and a bit is
            lit in FKSTAT for this fork.

        3.  The main scheduler loop notices that FKPS1 is  on  in  FKSTAT  and
            will  end up at PIRQ.  PIRQ checks the SCS% bit in FKSTAT and will
            call SCSPSI if the bit is on.  Once we arrived at PIRQ we  are  in
            process  context  for  the  target fork.  Hence we have the PSB we
            will modify locked in core.

        4.  SCSPSI will now scan the system wide queue for entries  bound  for
            the current fork.  The entries it finds are placed on the fork and
            connection queues of the target fork.  If the list in question was
            empty  before  the new entries were added, then a PSI is generated
            on the appropriate channel for the target fork.

        When a user receives a PSI, SCS% functions to retrieve data  are  done
   to  return  information  about  events  or  to  retrieve  data from packets
   received.
SCA-DESIGN-NOTES.TXT

SCAMPI will be changed to conform to the corporate spec as much as
possible. This includes updating the states and following the model of
the spec for sending SCS control messages. The current spec is version
6, and is available on R60SPC:.

See comments in the edit history of SCAMPI for specifics of edits already
made. See also SCA-TABLES.TXT for the tables that represent the state machine.

No attempt will be made in the near future to update the SCA design spec.
Any necessary changes to the functional spec will be reviewed with sysap
writers. No change will be visible to ordinary users.

The following areas must be investigated before the design can be done:

	1. Interlocks

	2. Buffer management

	3. Disconnection

	4. Deletion of connection blocks

	5. When can we safely open a v.c.?

	6. Inconsistencies in the corporate spec regarding states
			SCA Design Notes
			  Judy Hall
			  Dave Lomartire

This is a collection of notes about the changes that have been made to
SCAMPI. It is not intended to be a complete description of the changes,
nor is it in any way a tutorial description of the design. But it does
document the reasons behind some decisions, and may provide some insight
into the assumptions implicit in the code.
		Interactions in SCAMPI
			Judy Hall
			6/14/84

1. System block's list of connection blocks (pointed to by .SBFCB)

NOTE: We assume that the c.b. lock has prevented setting the "reap"
bit until no other code wants to use the c.b. The concern here is only
with keeping the list intact.

Adding - SC.LCB -- CIOFF

Removing -- SC.RCB -- CIOFF

Traversing -- SC.RAP knows it's the only deleter, and uses no
		protection when traversing
	   -- SC.SCM knows it's at interrupt level, uses no protection when
		traversing
	   -- SC.IDL goes NOSKED when traversing to prevent SC.RAP from
		running

Nothing totally eliminates the queue. It may become empty when the
last entry is removed.


2. Don't-care listeners (pointed to by TOPDC)

Adding -- SC.LCB -- CIOFF

Removing -- SC.RCB -- CIOFF
	 -- SC.SCM -- interrupt level

Traversing -- SC.RAP uses CIOFF. WHen it finds an entry to be reaped, it 
		goes CION. When it continues, it returns to the top of
		the list.


3. System block's work queue (pointed to by .SBTWQ)

Adding -- SC.AWQ (from SC.SCA, SC.SNM, SC.DEF) -- CIOFF, checks v.c. before
		returning entry. If closed, doesn't queue the entry
		since SC.ERR has destroyed the queue

Deleting -- SC.RWQ (from SC.SNM, SC.DEF) -- CIOFF

Traversing -- SC.SNM, SC.DEF -- always remove entry while CIOFF, return
		it while CIOFF

Destroying queue -- SC.ERR -- CIOFF when resetting the head and tail

At any time, SC.ERR may destroy the list. Others can't traverse it
CION, or add an entry without verifying that node is still online.
4. System block's address of outbound buffer (pointed to by .SBOBB)

Taking the buffer -- SC.SNM -- uses EXCH with zero; if result is non-zero,
		owns the buffer

Returning buffer to s.b. -- SC.SNM -- while CIOFF, makes sure v.c. is open.
		If open, stores address in s.b.; if closed, returns buffer
		to port queue
			 -- SC.SAR -- knows it's at interrupt level, stores
		address in s.b.

Returning buffer to port or SCA -- 

	SC.ERR -- uses EXCH with zero; if result is non-zero, returns
		 buffer to SCA's pool
	       -- if zero, gets a buffer from the port's queue.

	SC.RIB -- knows that v.c. is already closed,
		returns buffer to port

	SC.SNM -- if PHYKLP refuses to send, returns buffer to port

At any time, SC.ERR may return the buffer to SCA's pool. All code must
test and zero the address in one operation.


5. Connection block

Connection block lock protects against

	A. Reaping

		Makes c.b. address invalid
		Manages buffers according to counts in c.b.
		(Assume reaping can happen as soon as unlock and OKSKED)

	B. Protocol violation

		Disc_req / application message
		Disc_req / disc_req
		Disc_req / credit_req

		(Even if last is not a violation of protocol, we will have
		reaped the block by the time the response arrives. And there
		is no reason to change credit if we are disconnecting.)

	C. Change in connection state or block state

		Protocol is generally synchronous, but

		1. SC.DIS at odd times can be interrupted by incoming
			protocol message. Both change state.

		2. Sysap can do connection management request, interrupt out
			 of it, and do SC.DIS.

		3. Any connection management request can be interrupted by
			node offline.
Events that can't tolerate these changes --anything that believes the
c.b.a. is valid, sets the connection state, sets the block state, or sends
a packet, including

	Calls from the sysap, including
		Connection management requests
		Sending messages and datagrams
		Queueing or canceling buffers for reception
		Sending DMA
	Idle chatter
	Sending connection management requests

These all lock the connection block lock. In the case of sending a packet,
they unlock it only after the packet has been given to PHYKLP.

It is NOT necessary to leave a c.b. locked while it is waiting to send a
connection management request (that is, the buffer is in use). However,
it must be locked while its request is being sent and its state is being
changed.

Some code needs to honor the lock if it's at interrupt level, and lock the
lock if it's not. So there are three kinds of routines:

	A. Lock

		If at interrupt level, do nothing
		If not, AOS the count.

	B. Honor

		Called by code that runs only at interrupt level
		If lock is unlocked, proceed.
		If lock is locked, set a bit to indicate what is deferred,
			and don't proceed.

	C. Lock and honor

		If not at interrupt level, do "lock"
		If at interrupt level, do "honor"

When locking, code goes NOSKED. Therefore, there can be only one locker
at a time.

Events that defer:

	SC.ERR - node offline
	SC.DIS - sysap requests disconnect
	SC.DRQ - remote side initiates disconnect
	SC.SNM - sending a connection management request

Unlock routine processes according to the bits it finds set.
6. Existence of connection block

Only SC.RAP deletes a connection block. Code that sets the "reap"
bit must lock the connection block, which makes it NOSKED. The reaper
won't run until the block has been unlocked.


7. Virtual circuit's state (indicated by SBVCST)

	SC.ERR -- if no c.b. is locked, calls OPENVC
	       -- if a c.b. is locked, increments s.b.'s count of locked c.b.'s

	SC.ULK -- if node offline had been deferred, decrements s.b.'s count
			of locked c.b.'s. If result is zero, calls OPENVC


8. Send credit (indicated by .CBSCD)

Single-instruction AOS or SOS avoids races

Decrement and test -- SC.SMG, SC.SND, SC.REQ -- SOS and load AC

Increase -- SC.DMA increases by 1 -- AOS -- interrupt level
	 -- SC.CRQ and SC.AMG -- ADDM from packet -- interrupt level

Use -- SC.CRQ compares with minimum send credit -- interrupt level

Store initial value -- SC.ORQ and SC.ARQ -- interrupt level


9. Receive credit

CIOFF protects all changes; multiple kinds of credit must be adjusted
without interruption.

Use of return_credit prevents interaction between cancel receive message
and other events. Avoids cases in which the number of buffers queued
differs from receive credit.

Interlock word, .CBPND, prevents conflicts between two contexts that
want to send a credit_request. Prevents an attempt at queueing the c.b.
a second time, and avoids sending a null credit_request. When the
credit_response arrives, we send another credit_request if the need has
arisen since the last one was sent.

SC.CDT (from SC.RMG, SC.CRM, SC.IDL, SC.CRS) -- EXCH of .CBPND with -1.
		If result is 0, send credit_request. If not, return.

SC.CRS -- clear .CBPND and call SC.CDT to send again if necessary.
10. Count of buffers queued for receiving datagrams

Decrement -- SC.CRD -- SOSL once per buffer; AOS if negative

Change -- SC.RDG -- ADDM
       -- SC.ADG -- SOSGE; AOS and drop datagram if negative

Use -- SC.RCB dequeues based on this value; block isn't being used by then
			Why SC.DIS is Special
				6/21/84

SC.DIS uses CIOFF to lock out SC.DRQ, SC.ORQ, SC.ARQ, SC.ARS. If these
were allowed to run, they would have to honor the lock. SC.DRQ already does
honor it, but the other three do not.

The alternative to CIOFF is to make each of these honor the lock. The race
arises only when the sysap has done a disconnect at an unusual time, as
follows:

SC.ORQ - sysap disconnects a listener, and connect_request arrives. SC.DIS
sets new state to closed, but SC.ORQ has already set it to connect_received,
and sent a connect_rsp Match. Its deferred code would have to manufacture
a reject_request if the state had changed to closed. Today it sends
connect_rsp NM if the state is closed.

SC.ARQ - sysap disconnects after initiating a connection, and an accept_request
arrives. SC.DIS sets new state to closed, but SC.ARQ has already set it to
open, and sent an accept_response Match. Its deferred code would have to
manufacture a disconnect_request if the state had changed to closed. Today it
sends an accept_response NM if the state is closed.

SC.ARS - sysap disconnects after accepting a connection for a listener, and
an accept_response Match arrives. SC.DIS sets new state to closed, but SC.ARS
has already set it to open. Its deferred code would have to send a 
disconnect_req, which it does today if the state is closed.

It seems more practical to let SC.DIS be CIOFF until it is ready to send
a message (if that's necessary), and avoid a lot of special-purpose code.
It already needs to be CIOFF for a large fraction of the execution time
anyway. Also, the speed of disconnect doesn't seem terribly critical to the
overall performance of the system.

Since SC.DIS is CIOFF for this purpose, it need not lock the lock. SC.DRQ
and SC.ERR will be held off by CIOFF, so the lock is unnecessary.
		Why Reap in Process Context
			Judy Hall
			6/14/84

1. Allows the return of buffers that the sysap (CFS) has queued for output.
These will be returned at SC.INT, which assumes that the CID is still valid.
That is the only way to identify the sysap to which the buffer is to be
returned.

2. Code that sets the "reap" bit must still unlock the connection block before
the reaper can run. Locking goes NOSKED, which prevents reaping. If we were to
reap immediately, each pass through unlock would have to check for this case.

3. Reaping isn't very urgent, and shouldn't be done at interrupt level.
			Why Stock the Message Free Queue
				Judy Hall
				6/20/84

1. When a node goes offline, the outgoing connection management buffer may be in
use. If so, we try to get a buffer from the port's queue to give back
to SCAMPI. When PHYKLP queues the buffer to the port, the port will return
it with error. PHYKLP will return the buffer to the free queue. Thus there
is a window where the port will be short one buffer.

2. When a node goes offline, the incoming connection management buffer
may be on the response queue. SCAMPI will try to remove a buffer from the
port's queue at SC.ERR. Eventually the connection management buffer will
be given to SCAMPI, which will return it to the free queue. Meanwhile, there
is a window where the port will be short one buffer.

3. When a node goes offline, a sysap may have queued a buffer to go out,
without asking that the buffer be returned. In this case, the sysap's
receive credit includes this buffer. If the reaper runs before the port sees
the buffer, SC.RCB will try to remove a buffer from the port when it hasn't
been queued there yet. As soon as the port rejects the command, PHYKLP will
give the buffer back to the port.
			Incoming Packets on Closed V.C.
				Judy Hall
				6/22/84

An incoming packet may be on the response queue behind a packet that will
cause the v.c. to be closed. SCAMPI will receive a callback at SC.ERR
for the bad packet, followed by a callback at SC.INT for the good one.

SCAMPI used to process this second packet normally, even though the
v.c. was closed. This led to the following problem:

Suppose the second packet is a connect_request. SCAMPI matched the
request with a waiting listener and set the connection state to "connect
received". However, the attempt at sending a connect_response failed
because the v.c. was closed. The sysap was never notified of the change of
state. It believed it had an outstanding listener.

SCAMPI now checks the state of the v.c. for every incoming packet.
Because connect_request isn't associated with a particular connection,
it's not sufficient to check the connection state. Also, handling of
the buffer is different if we know that SC.ERR has already run.
This could be via a separate dispatch table at SC.INT, indexed by op
code and handling only the case of incoming packet on a closed v.c.
Presently, the check on the v.c. is made after the op code is known.

The buffer is handled as follows:

1. Connection management request 

This is the buffer that SCAMPI queued to the port when the node came
online. Normally, the response goes out in this buffer. If the node
is offline, SCAMPI queues the buffer to the port. SC.ERR has already
taken a  buffer from the port and returned it to its pool. THus this
buffer belongs to the port.

2. Connection management response

This is the buffer that is queued to the system block for outgoing
requests. When SC.ERR ran, the pointer was 0, and SCAMPI took a buffer
from the port's queue. Thus SCAMPI now returns this buffer to the port.

3. Application message

SCAMPI gives the buffer to the port. It was included in the sysap's
receive credit, so if the reaper has run, it has already removed an
extra buffer from the port's queue.

4. Application datagram

SCAMPI gives the buffer to the port. It was included in the sysap's
count of queued datagram buffers, so if the reaper has run, it has
already removed an extra buffer from the port's queue.
		The List of Connection Blocks
			Judy Hall
			6/20/84

It's not clear that linking the connection blocks to the system block
is essential. The list is useful for idle chatter, for the reaper,
and for finding the connections when a node goes offline.

Presently, a c.b. remains on the list until the reaper deletes it. This
means that searches through the list will stumble over this block. This
is most likely to be visible after a node goes offline. All its connection
blocks are marked to be reaped, and a whole new set of them is created,
but they are behind the obsolete ones.

One possibility seems to be to remove a c.b. from this list at SC.ERR,
or at SC.PTC, which is reached also when a disconnect sequence completes.
These blocks could be on a special "reap" linked list, which the reaper
would search instead of searching the list for each system block. Since
the reaper runs periodically, and typically searches these lists without
accomplishing anything, this would seem to offer a performance gain.

Other possibilities:

	Set a bit in CIDTAB to indicate that the connection block needs
reaping, and have the reaper scan CIDTAB.

	Set a global flag when the reap bit is set in any c.b., and don't
call the reaper unless this flag is set.
		Opening a V.C.
		   Judy Hall
		   6/20/84

SC.SNM may try to queue a packet after SC.ERR has run. Between getting the
buffer (.SBOBB) and sending, it doesn't check the v.c. We need to be sure
that 1) PHYKLP won't accept the packet if the v.c. is closed, and 2) the
v.c. doesn't get reopened before we queue the packet.

Sequence in PHYKLP should always be:

	1. Mark the state as closed
	2. Tell the port to close the v.c.
	3. Tell SCAMPI the v.c. is closed

SCAMPI should never allow the v.c. to be opened as long as any connection
block is locked. The locker may try to send a packet (SC.SNM, SC.SMG, etc.),
and we want that to fail.
	Closing and Opening V.C.'s (SCAMPI and PHYKLP)
		Judy Hall
		6/10/84

1. SCA makes the decision to close

	SCA calls PHYKLP, which
	  a. marks the state as "closed"
	  b. tells the port to close the v.c.
	  c. calls SC.ERR

2. PHYKLP makes the decision to close

	It follows the same sequence as in #1 above.

3. The port informs PHYKLP of an error

	PHYKLP either does all of #1 above, or leaves out telling the
		port to close the v.c.

If PHYKLP is unable to get a buffer for the SETCKT, it sets a bit in 
RIDSTS (or elsewhere) indicating that the v.c. still needs to be closed.
At this point, the system block has the state as closed, and SENDVC is
refusing to queue packets to the node.

The poller checks this bit, and sends the SETCKT whenever it can.
			- - - - -

SCA decides it can open a v.c. (PHYKLP never decides that if the v.c. has
ever been open before).

SCA calls PHYKLP, which sends a start unless the "need to close" bit is
still on. In that case, or if no buffer is available, it sets a bit in
RIDSTS called "need to open".

The poller always checks "need to close" before it checks "need to open".
When it wants to open, it sends a start.
			- - - - -

Neither routine returns failure. The purpose of SCA's "open" call is to
say "you can open whenever you want to". PHYKLP will notify SCA when the
v.c. has been opened, and SCA is not concerned with the events that prevent
this.

Similarly, when SCA says "close the v.c.", it means "don't queue any more
of my packets". So PHYKLP should mark its data base and act as if the v.c.
is closed, even if it hasn't found a way to tell the port yet.

Multiple attempts at closing, either by SCA or because of the arrival of
bad packets, should be filtered. SCAMPI checks for multiple calls to SC.ERR
for the same system block, but there seems to be no reason to perform
the close function more than once.

			- - - - -

When queueing a START for "open v.c.", PHYKLP should use the lowest possible
priority. THus, if any message has been queued to the port, the port will reject
it before sending the START. Otherwise, stale data might go out on the newly-
opened v.c.
		Handling of Buffers on Error
			Judy Hall
			6/17/84

I believe that PHYKLP should return both message buffers and datagram
buffers to the port's queues when these buffers are locally-generated,
the "response" bit is not on, and an error has occurred. Here is my
reasoning:

1. Message buffers

A. Those sent by a sysap.

	If the sysap doesn't want the buffer back, SCAMPI increments
its receive credit on the assumption that the buffer will be put on
the free queue when the port has finished with it.

	Indeed, if there is no error, the port puts the buffer on the
free queue, where it is available for an incoming message. If there is
an error, the count has still been incremented, so the buffer should
ultimately wind up on the free queue.

	If the node goes offline after the sysap has sent a message,
in theory the reaper could run before the port decides to refuse to send
the message. In this case, SCAMPI would remove "n" buffers from the port's
queue, where "n" includes the 1 that was added to it when the message was
sent. The buffer, then, belongs to the port.

B. Those sent by SCAMPI

	SCAMPI sends its requests in a buffer that has been allocated
especially for the purpose (one buffer per remote node). It assumes that
the remote system will send a response, for which the port will acquire
a buffer from the free queue. Thus it does not set the "response" bit
when it sends a request.

	If the node goes offline, and a request is outstanding, the port
will return the packet with error. Meanwhile, SCAMPI will have been called
at SC.ERR, where it will determine that the buffer is in use, and move
a buffer from the free queue to SCA's pool. When the original buffer is
finally available, it should replenish the free queue.

2. Datagrams

As with messages, the sysap may queue a datagram buffer without asking
for a response. In that case, SCAMPI counts it as being queued to the port
for an incoming datagram. (This accounting is similar to receive credit for
messages, but it is not communicated to the other host.) 

If no error occurs, the port returns this datagram buffer to the port's
free queue. Therefore, if there is an error, PHYKLP should return
such a buffer to the port's queue.
                             SCA Buffer Management
                                David Lomartire
                                   14-Sep-84



o  SC.ALC - Allocate message and datagram buffers for SCA pool

	Called by:	SC.ALM via job 0 when DDCFSF is non-zero

	Calls:		SC.CMG to create message buffers
			SC.CDG to create datagram buffers

   This  routine  is  responsible  for  keeping  the  SCA pool of datagrams and
messages up to the minimum thresholds. Whenever a buffer request is made  which
causes  the buffer count (FQCNT or DFQCNT) to fall below the minimum, DDCFSF is
set. This will make job 0 call SC.ALM which will call SC.ALC.

	For messages - 
	     The  number  of  buffers  in  FQCNT is checked against the minimum
threshold (MINMSG). If it is below, a call to SC.CMG is  made  to  create  more
message buffers to bring us up to the minimum threshold. Upon successful return
from  SC.CMG,  the  buffers  are  linked to BOTFQ, FQCNT is updated, and TOTMGB
(total number of buffers created so far) is updated.

	For datagrams - 
	     The  number  of  buffers  in DFQCNT is checked against the minimum
threshold (MINDG). If it is below, a call to SC.CDG  is  made  to  create  more
datagram  buffers  to  bring  us  up  to the minimum threshold. Upon successful
return from SC.CDG, the buffers are linked to BOTDFQ, DFQCNT  is  updated,  and
TOTDGB (total number of buffers created so far) is updated.


o  SC.DEF - Handle buffer deferral

	Called by:	SC.ALM via job 0 when DDCFSF is non-zero

	Calls:		SC.BF2 to get (and create if necessary) buffers

   This  routine  handles  buffer  deferral.  When  a connect block is stuck on
buffers, the bit corresponding to the node number of its system block is set in
SBSTUK and DDCFSF is set. The connect block is queued to the system block  work
queue.  When  job  0 runs, SC.DEF will run and call SC.BF2 in an attempt to get
the buffers it needs to send the connect_request or accept_request.

   When  run,  SC.DEF  "scans"  SBSTUK  to find the first system block with any
connect blocks which are stuck on buffers. The stuck bit for this system  block
is  cleared in SBSTUK and all the connect blocks which are stuck are processed.
Any connect block that became unstuck are placed on the end of the work  queue.
Once  all  connect  blocks  are done, a call is made to SC.SNM in an attempt to
send out the queued connection management requests for that system block.

   All  system  blocks  which  are  stuck  are  processed  until SBSTUK is zero
(indicating that there are no longer any stuck connect blocks).
o  SC.BUF (SC.BF1 - Allocate buffers from pool; cannot create buffers)
	  (SC.BF2 - Allocate buffers from pool; can create buffers)

	SC.BF1 called:	SC.SNM to get initial buffers for c.b.
	SC.BF2 called: 	SC.DEF when processing stuck connect blocks

	Calls:		SC.ABF to allocate message buffers
			SC.ALD to allocate datagram buffers
			SC.CMG to create message buffers 
			SC.CDG to create datagram buffers
			LNKMFQ to link message buffers to port
			LNKDFQ to link datagram buffers to port
			SC.RBF to return extra message buffers from SC.CMG
			SC.RLD to return extra datagram buffers from SC.CDG

   These routines are called by SC.SNM (SC.BF1) and SC.DEF (SC.BF2) to allocate
buffers for a connect_request or accept_request from the SCA pool.

	For messages - 
	   The  number  of buffers needed in CBIMB is checked to see if any are
required. If so, a call to SC.ABF is made to obtain them.

	   If  this  fails,  (and  if  buffers  cannot  be  created)  DMRCNT is
incremented to indicate this and a failure return results. If  buffers  can  be
created  a  call is made to SC.CMG to create the needed buffers. A failure here
results in a failure return from  SC.BUF.  On  success,  the  total  number  of
buffers created is added to TOTMGB. A check is made to see if more were created
than  were  required  and,  if  so, the extras are returned to the SCA pool via
a call to SCM.RM (which calls SC.RBF once for each extra buffer).

	   Once  the  buffers  have  been obtained, a call is made to SCL.MC to
link each message buffer onto the port message free queue (via call to LNKMFQ).
Pending receive credit (.CBPRC) is updated to reflect these  buffers.  Finally,
the number of buffers to queue (CBIMB) is set to zero.

	For datagrams -
	   The  number  of buffers needed in CBIDB is checked to see if any are
required. If so, a call to SC.ALD is made to obtain them.

	   If  this  fails,  (and  if  buffers  cannot  be  created)  DDRCNT is
incremented to indicate this and a failure return results. If  buffers  can  be
created  a  call is made to SC.CDG to create the needed buffers. A failure here
results in a failure return from  SC.BUF.  On  success,  the  total  number  of
buffers created is added to TOTDGB. A check is made to see if more were created
than  were  required  and,  if  so, the extras are returned to the SCA pool via
a call to SCM.RD (which calls SC.RLD once for each extra buffer).

	   Once  the  buffers  have  been obtained, a call is made to SCL.DC to
link each datagram buffer onto the  port  datagram  free  queue  (via  call  to
LNKDFQ).  The  count  of datagram buffers queued (.CBDGR) is changed to reflect
these buffers. Finally, the number of buffers to queue (CBIDB) is set to zero.
o  SC.SBT - Set buffer thresholds

	Called by:	SCA upon initialization to establish starting levels
			SC.ONL to update levels when node comes online
			SC.ERR to update levels when node goes offline

  This  routine  is  used  to  set  the  value for the minimum level of message
(MINMSG) and datagram buffers (MINDG) to be maintained by SCA.  This  count  is
based on the number of systems currently online (SBCNT). Whenever a request for
a  buffer  forces the count of buffers to fall below the minimum, DDCFSF is set
to signal job 0 to run SC.ALC and allocate more buffers for the SCA pool.

  MINMSG  = (SBCNT*MBPS)+MGTRSH, where MBPS is the number of message buffers to
maintain per online system and MGTRSH is the base value of buffers  which  must
be available.

  MINDG  = (SBCNT*DBPS)+DGTRSH, where DBPS is the number of datagram buffers to
maintain per online system and DGTRSH is the base value of buffers  which  must
be available.

o  SC.ABF - Allocate message buffers from SCA pool

	Called by:	SCA to acquire a buffer for NOTTAB
			SC.SMG to give the port a buffer on send failure
			SC.RMG to get the number of buffers to queue
			SC.ONL to get 2 buffers; 1 for .SBOBB and 1 for port
			SC.ACB to get a buffer to use as the connect block
			SC.BF2 to get buffers requested upon connect or accept

  This  routine  is  used to obtain message buffers from SCA's pool. First, the
number of buffers desired is checked against FQCNT and if greater, the  routine
will return an SCSNBA error. Next, the number of buffers left after the request
is  satisfied  (FQCNT-NUMBUF)  is  checked to see if it falls below the minimum
threshold (MGTRSH). [MGTRSH is used because it is the constant lower  threshold
below which no requests for buffers will be granted unless they are small (less
than LRGREQ). MINMSG is not used because it is a fluctuating value which depends
upon  the  number  of  nodes  up  at  the  moment.] If there are enough buffers
remaining (or if not and the request is small), the request is honored. If  the
request  is  honored  because  it  is  a small request, MBUST is incremented to
record this. To honor the request, the message free queue  (top  is  TOPFQ  and
bottom  is  BOTFQ)  is traversed to insure that there actually are the required
number of buffers.

  If  there  is an inconsistency, a SCAMCR BUGCHK will result and FQCNT will be
recalculated by tracing the free queue again. NMBCNT (the number  of  times  we
ran  out  of  message  buffers)  and RMRCNT (the number of times allocation was
refused) are incremented. DDCFSF is incremented to force SC.ALC to  run.  Also,
ASRMR  is  updated  to  reflect  the average size of refused requests. A SCSNBA
error will be returned.

  If  the  scan  of  the  free queue is successful, TOPFQ, BOTFQ, and FQCNT are
updated. If it is found that FQCNT has fallen below MINMSG, DDCFSF  is  set  to
allow SC.ALC to run.

  If  the  request  is  refused,  RMRCNT is incremented and ASRMR is updated to
reflect the average size of refused requests. A SCSNBA error will be  returned.
This  will occur when there are not enough buffers present to grant the request
or when a large request forces the count below the buffer threshold.
o  SC.ALD - Allocate datagram buffers from SCA pool

	Called by:	SC.SDG to give the port a buffer on send failure
			SC.RDG to acquire the buffers to queue
			SC.BF2 to get buffers requested upon connect or accept

  This  routine  is used to obtain datagram buffers from SCA's pool. First, the
number of buffers desired is checked against DFQCNT and if greater, the routine
will return an SCSNBA error. Next, the number of buffers left after the request
is satisfied (DFQCNT-NUMBUF) is checked to see if it falls  below  the  minimum
threshold  (DGTRSH). [DGTRSH is used because it is the constant lower threshold
below which no requests for buffers will be granted unless they are small (less
than LRGREQ). MINDG is not used because it is a fluctuating value which  depends
upon  the  number  of  nodes  up  at  the  moment.] If there are enough buffers
remaining (or if not and the request is small), the request is honored. If  the
request  is  honored  because  it  is  a small request, DBUST is incremented to
record this. To honor the request, the datagram free queue (top is  TOPDFQ  and
bottom  is  BOTDFQ) is traversed to insure that there actually are the required
number of buffers.

  If there is an inconsistency, DFQCNT will be recalculated by tracing the free
queue  again.  NDBCNT  (the number of times we ran out of datagram buffers) and
RDRCNT (the number of times allocation was refused) are incremented. DDCFSF  is
incremented  to  force  SC.ALC  to  run.  Also, ASRDR is updated to reflect the
average size of refused requests. A SCSNBA error will be returned.

  If  the  scan of the free queue is successful, TOPDFQ, BOTDFQ, and DFQCNT are
updated. If it is found that DFQCNT has fallen below MINDG, DDCFSF  is  set  to
allow SC.ALC to run.

  If  the  request  is  refused,  RDRCNT is incremented and ASRDR is updated to
reflect the average size of refused requests. A SCSNBA error will be  returned.
This  will occur when there are not enough buffers present to grant the request
or when a large request forces the count below the buffer threshold.


o  SC.CMG/SC.CDG - Create message/datagram buffers

	Called by:	SC.ALC to create buffers needed to boost above minimum
			SC.BF2 to create buffers needed by connect or accept

	Calls:		SC.BBF to break memory pages into buffer chain

  These  routines are used to create message and datagram buffers. It is called
when the SCA buffer pool is exhausted (or below minimum values) and needs to be
restocked. The number of buffers returned is rounded up  to  fill  an  integral
number of pages so extra buffers may be provided.

  First  the number of pages required to fill the buffer request is calculated.
For each page required, EPGMAP is searched to locate an empty page. If no empty
pages are found, the routine returns with a SCSNEB error. The search starts  at
offset  LSTEPG  (which is initialized to 777) and decrements towards the top of
the map. When a free page is found, the next lower offset is placed  in  LSTEPG
and  a  call is made to MLKMA to lock down the page. Finally, a call is made to
SC.BBF to break the page into buffers  of  the  appropriate  size  (C%MGSZ  for
messages and C%DGSZ for datagrams).
o  SC.BBF - Break memory page into buffers

	Called by:	SCA to create the initial chain of buffers
			SC.CMG to create chain of message buffers
			SC.CDG to create chain of datagram buffers

  This routine will take a page of memory and break it into a chain of message 
or datagram buffers.  The page is broken up into buffers of C%BINV+C%MGSZ size 
for messages and C%BINV+C%DGSZ for datagrams.  C%BINV is the size of the 
invisible area which is prepended to the top of each buffer for local use (it 
is never sent across the CI).  The FLINKs of each buffer point to the next 
buffer in the chain.


o  SC.RBF - Return a message buffer

	Called by:	SC.ERR to return the two buffers obtained at SC.ONL
			SC.INT to return buffer sent by SCA
			SC.RCB to return buffers queued by connection
			SC.JSY to return buffers queued by JSYS
			SC.GCB to return buffers in RET_CREDIT field (.CBRTC)
			SCM.RM to return one of a chain of message buffers
			SC.ABF to return extra buffers from SC.CMG

  This  routine  will  return  message  buffers  to the SCA message free queue.
First, the entire buffer (C%BINV+C%MGSZ) is zeroed. Then the buffer  is  linked
to  BOTFQ  and  FQCNT is incremented to reflect the additional buffer. Note that
this routine is passed back to the caller by SC.ABF as the routine to  call  to
return the buffer.


o  SC.RLD - Return a datagram buffer

	Called by:	SC.CRD to return buffer which was canceled
			SC.RCB to return buffers queued by connection
			SC.JSY to return buffers queued by JSYS
			SCM.RD to return one of a chain of datagram buffers
			SC.ALD to return extra buffers from SC.CDG

  This  routine  will  return  datagram buffers to the SCA datagram free queue.
First, the entire buffer (C%BINV+C%DGSZ) is zeroed. Then the buffer  is  linked
to  BOTDFQ and DFQCNT is incremented to reflect the additional buffer. Note that
this routine is passed back to the caller by SC.ALD as the routine to  call  to
return the buffer.



                                  The SCS% JSYS

                                    31-Jan-83
   SCS% JSYS                                                            Page 1
   General format of JSYS call


          The following is the general format of a call to the SCS% JSYS.


             Call
             T1/     Function code
             T2/     Address of arg block


             Return (+1) Always
             T1/     Function code
             T2/     Address of arg block
             
             An error generates an illegal instruction trap.

     General format of the argument block:

              !=======================================================!
     .SQLEN   !      Words processed      !     Length of block       !
              !-------------------------------------------------------!
              \                                                       \
              \             Function dependent arguments              \
              \                                                       \
              !=======================================================!

          Where the "words processed" is the number of words in  the  argument
     block  that the monitor actually looked at and used.  Hence this field is
     returned by the monitor, not supplied by the user.  The "length of block"
     is the total length of the supplied block including the header word.
          Note that this JSYS  requires  one  or  any  combination  of  wheel,
     maintainance, or network wizard.
   SCS% JSYS                                                            Page 2
   Connect (.SSCON)


                                Connect (.SSCON)



          This function requests a connection with another  node  on  the  CI.
     The  JSYS  will  return  as soon as the connection request has been sent.
     You are notified that your connection request was granted or failed via a
     PSI interrupt.

     The argument block has the following format:
|  
|             !=======================================================!
|    .SQLEN   !      Words processed      !     Length of block       !
|             !-------------------------------------------------------!
|    .SQSPN   !          Byte pointer to source process name          !
|             !-------------------------------------------------------!
|    .SQDPN   !       Byte pointer to destination process name        !
|             !-------------------------------------------------------!
|    .SQSYS   !    SBI of destination     !   6 bits of connect ID    !
|             !-------------------------------------------------------!
|    .SQCDT   !               Pointer to connection data              !
|             !-------------------------------------------------------!
|    .SQAMC   !    Address of first buffer on message buffer chain    !
|             !-------------------------------------------------------!
|    .SQADC   !    Address of first buffer on datagram buffer chain   !
|             !-------------------------------------------------------!
|    .SQRCI   !                  Returned connect ID                  !
|             !=======================================================!
|  


     The byte pointer to the source process name is  a  byte  pointer  to  the
     ASCII  string  which  is the name of your process.  Note that this string
     must end on a null byte and may be  a  maximum  of  16  bytes  long,  not
     including the null byte.

     The byte pointer to destination process name is the byte pointer  to  the
     name of the process you wish to connect to.  This name must also end in a
     null byte and may be a maximum of 16 bytes, not including the null byte.

     The SBI (system block index) is the unique identifier of the  system  you
     wish to connect to.

     Note that the specified strings may be any vaild ASCII  byte  size  (I.E.
     any byte size equal to or larger than 7 bits).  These strings may also be
     generic byte pointers (-1,,STRNG).  If generic byte pointers are given, 7
     bit ASCII terminated by a null byte is assumed.

     The 6 bits of connect ID is 6 right justified bits which will  be  placed
     in the most significant bits of the connect ID.  These bits are generally
     used for connection managment by the user program.  If  initial  data  is
     not desired then this word is zero.
|  
|    The pointer to connection data is the address of a block of  data  SQ%CDT
   SCS% JSYS                                                            Page 3
   Connect (.SSCON)


|    words  long  to  be  sent as connection data.  Note that the monitor will
|    copy SQ%CDT words of data from the users address  space.   Hence  a  full
|    block SQ%CDT words long should be allocated for the data.
   SCS% JSYS                                                            Page 4
   Listen (.SSLIS)


                                 Listen (.SSLIS)



          This function listens for a connection.  Note that the JSYS does not
     block.   You  will  be  notified  of  a  connect to your listen via a PSI
     interrupt.
          There are a number of options that may be used when doing  a  listen
     for  a  connection.   You  may  listen  for a particular process from any
     system by making the system block index  -1.   You  may  listen  for  any
     process  from  a  particular  system  by  making  the byte pointer to the
     destination process name -1.  If the system  block  index  and  the  byte
     pointer  to  the  destination  process name are both -1, then any connect
     request that is not for a particular process name will match your listen.
     Naturally  you  may  specify both a system block index and a process name
     and then only that process from the  named  system  will  be  allowed  to
     connect to your listen.
|  
|  
|  
|             !=======================================================!
|    .SQLEN   !      Processed words     !       Length of block      !
|             !-------------------------------------------------------!
|    .SQSPN   !          Byte pointer to source process name          !
|             !-------------------------------------------------------!
|    .SQDPN   !       Byte pointer to destination process name        !
|             !-------------------------------------------------------!
|    .SQSYS   !    SBI of destination     !   6 bits of connect ID    !
|             !-------------------------------------------------------!
|    .SQMGA   !    Address of first buffer on message buffer chain    !
|             !-------------------------------------------------------!
|    .SQDGA   !    Address of first buffer on datagram buffer chain   !
|             !-------------------------------------------------------!
|    .SQLCI   !                Returned connect ID                    !
|             !=======================================================!
|  


          See the description of .SSCON for an explanation of  each  field  in
     this block.
   SCS% JSYS                                                            Page 5
   Accept (.SSACC)


                          Accept a connection (.SSACC)



          This function tells a remote node that you are granting his  request
     for a connection.



             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                      Connect ID                       !
             !-------------------------------------------------------!
      .SQCDA !              Pointer to connection data               !
             !=======================================================!



          The pointer to connection data  is  the  address  of  the  block  of
     connection  data  to be sent to the remote system.  The monitor will copy
     SQ%CDT words of data from the users address space  as  data.   Note  that
     this  data will be sent directly over the CI and hence the low order four
     bits are not sent.
   SCS% JSYS                                                            Page 6
   Reject (.SSREJ)


                          Reject a connection (.SSREJ)



          This function code tells a remote node that you are not  allowing  a
     connection to your process.

     The argument block for this function has this format:

             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                      Connect ID                       !
             !-------------------------------------------------------!
      .SQREJ !                   Rejection reason                    !
             !=======================================================!



          The rejection reason is a relativly small integer that indicates  to
     the remote host why you are not allowing the connection.  MONSYM contains
     a list of these codes.
   SCS% JSYS                                                            Page 7
   Disconnect (.SSDIS)


                               Disconnect (.SSDIS)



          This function closes a connection.   The  disconnect  function  code
     requires the following arguments:



             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                      Connect ID                       !
             !-------------------------------------------------------!
      .SQDIS !                   Disconnect reason                   !
             !=======================================================!



          The disconnect reason is a relativly  small  positive  integer  that
     indicates  to  the  remote  system,  why  you are closing the connection.
     MONSYM contains the list of definitions of these codes.
   SCS% JSYS                                                            Page 8
   Send a DG (.SSSDG)


                            Send a datagram (.SSSDG)



          This function code sends a datagram.  The  following  arguments  are
     required:


             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                      Connect ID                       !
             !-------------------------------------------------------!
      .SQADG !               Address of datagram text                !
             !-------------------------------------------------------!
      .SQDGL !        Length in 8 bit bytes of datagram data         !
             !-------------------------------------------------------!
      .SQFLG !                        Flags                  !  OPS  !
             !=======================================================!


          OPS is an  optional  path  specification.   If  specified,  the  OPS
     indicates  that you wish to send this datagram over a particular hardware
     cable (path).  A complete description of  this  field  may  be  found  in
     MONSYM along with the flag definitions for the rest of the word.

                              *** Restrictions ***

     1.  The datagram text may not cross a page boundry.

     2.  A monitor overhead area  of  .SQTXT  words  must  appear  before  the
         message text.

     3.  Swapping of the page will be prevented while it is in the process  of
         being sent.  Hence forcing the page to be swapped before notification
         of message send complete will cause the hardware much grief.

     4.  The datagram text must be packed in  left  justified,  word  aligned,
         eight bit bytes.
   SCS% JSYS                                                            Page 9
   Queue a DG buffer (.SSQRD)


                 Queue a buffer for datagram reception (.SSQRD)



          This function code queues buffers for datagram reception.
          Note that in each buffer the first word is the address of  the  next
     buffer.   The  last  buffer  has  zero as the address of the next buffer.
     This function requires these arguments:


             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                      Connect ID                       !
             !-------------------------------------------------------!
      .SQAFB !        Address of first buffer on buffer chain        !
             !=======================================================!


                              *** Restrictions ***


|    1.  Datagram buffers must be 152 words in length.
   SCS% JSYS                                                           Page 10
   Send message (.SSSMG)


                             Send a message (.SSSMG)



          This function code sends a message to a remote node.


             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                      Connect ID                       !
             !-------------------------------------------------------!
      .SQAMT !                Address of message text                !
             !-------------------------------------------------------!
      .SQLMT !           Length of message in 8 bit bytes            !
             !-------------------------------------------------------!
      .SQFLG !                        Flags                  !  OPS  !
             !=======================================================!


          OPS is an abbreviation for "optional path spec".  If specified,  the
     OPS  indicates  that  you  wish  to  send  this message over a particular
     hardware cable (path).  There are three possible settings of these  bits.
     A  zero or one indicate the path to use, either zero or one.  If all bits
     are 1, then the monitor will select the  path  over  which  to  send  the
     message.  The complete set of flag definitions may be found in MONSYM.
     Note that the length of the message is the number of eight bit  bytes  in
     the message.
                              *** Restrictions ***

     1.  The message text may not cross a page boundry.

     2.  A monitor overhead area  of  .SQTXT  words  must  appear  before  the
         message text.

     3.  Swapping of the page will be prevented while it is in the process  of
         being sent.  Hence forcing the page to be swapped before notification
         of message send complete will cause the hardware much grief.
|  
|    4.  Message text may not be longer than 38 36 bit words (152 bytes).
   SCS% JSYS                                                           Page 11
   Queue message recieve buffers (.SSQRM)


                     Queue message receieve buffers (.SSQRM)



|         This function code queues buffer to receieve  messages.   Note  that
|    the  buffer size is fixed at 38, 36 bit words.  It requires the following
|    arguments:


             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                      Connect ID                       !
             !-------------------------------------------------------!
      .SQAFB !            Address of buffer chain to queue           !
             !=======================================================!
   SCS% JSYS                                                           Page 12
   Cancel DG receive (.SSCRD)


                        Cancel datagram receive (.SSCRD)



          This function code removes a buffer queued for  datagram  reception.
     The  address  that  you  specify must be the address of a buffer that was
     previously queued for receiving datagrams (with .SSQRD).  If this address
     is  not  found  by the monitor when it goes to take the buffer out of its
     queue, the JSYS fails with an illegal instruction  trap.   This  function
     requires these arguments:


             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                      Connect ID                       !
             !-------------------------------------------------------!
      .SQADB !             Address of buffer to dequeue              !
             !=======================================================!
   SCS% JSYS                                                           Page 13
   Cancel receieve message (.SSCRM)


                        Cancel receieve message (.SSCRM)



          The  function  dequeues  a  buffer  that  was  queued  for   message
     reception.  The buffer address that is specified must be of a buffer that
     you asked to be queued for  message  reception  (with  .SSQRM).   If  the
     monitor does not find the address specified in the argumnet block amongst
     the buffers you queued, the JSYS will fail.  This function  requires  the
     following arguments:


             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                      Connect ID                       !
             !-------------------------------------------------------!
      .SQADB !             Address of buffer to dequeue              !
             !=======================================================!
   SCS% JSYS                                                           Page 14
   Connect state poll (.SSCSP)


                           Connect state poll (.SSCSP)



          This function returns information about that state of a  connection.
     The argument block to this function includes space for the returned data.
     The argument block for this function looks like this:



             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                      Connect ID                       !
             !-------------------------------------------------------! ------------
      .SQCST !                   Connection state                    !      ^
             !-------------------------------------------------------!      !
      .SQDCI !                Destination connect ID                 !      !
             !-------------------------------------------------------!   Returned
      .SQBDN !       Byte pointer to destination process name        !     data
             !-------------------------------------------------------!      !
      .SQSBI !           System block index of destination           !      !
             !-------------------------------------------------------!      !
      .SQREA ! Source disconnect reasons !  Dest disconnect reasons  !      v
             !=======================================================! ------------


          Note that the byte pointer  to  destination  process  name  must  be
     provided by the caller and may be either a real byte pointer or minus one
     in the left half and the base address of the string in  the  right  half.
     If  the generic byte pointer is used the monitor will write the string as
     16 word aligned eight bit bytes, not the usual 7 bit bytes!
   SCS% JSYS                                                           Page 15
   Return configuration data (.SSRCD)


                       Return configuration data (.SSRCD)



          This function returns data about another system.  Given  the  system
     block  index the monitor will return data about that system.  The data is
     returned in the block pointed to by T1 which looks like this:


             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                  Optional connect ID                  !
             !-------------------------------------------------------!
      .SQOSB !              Optional system block index              !
             !-------------------------------------------------------!  -----------
      .SQVCS !   Virtual circuit state   !        Port number        !       ^
             !-------------------------------------------------------!       !
      .SQSAD \                                                       \       !
             \     System address (6 8-bit bytes, word aligned)      \       !
             \                                                       \       !
             !-------------------------------------------------------!       !
      .SQMDD !           Maximum destination datagram size           !       !
             !-------------------------------------------------------!       !
      .SQMDM !           Maximum destination message size            !    Returned
             !-------------------------------------------------------!      data
      .SQDST !               Destination software type               !       !
             !-------------------------------------------------------!       !
      .SQDSV !             Destination software version              !       !
             !-------------------------------------------------------!       !
      .SQDSE !            Destination software edit level            !       !
             !-------------------------------------------------------!       !
      .SQDHT !               Destination hardware type               !       !
             !-------------------------------------------------------!       !
      .SQDHV !             Destination hardware version              !       !
             !-------------------------------------------------------!       !
      .SQPCW \               Port characteristics bytes              \       !
             \    6, 8 bit bytes, word aligned in leftmost 32 bits   \       !
             !-------------------------------------------------------!       !
      .SQLPN !                  Local port number                    !       v
             !=======================================================!  ------------


          The symbols which define the various hardware and software types may
     be found in MONSYM.

          The connect ID and system block index are optional in  that  one  or
     the  other  must  be specified, but not both.  If the connect ID field is
     non-zero then the SBI field is ignored and the  information  returned  is
     for  the  system  implied  by the connect ID.  If the connect ID field is
     zero then the SBI field is used.  Note that this allows the  use  of  the
     zero'th system block index.

          If the local port number is not available, -1 will  be  returned  to
   SCS% JSYS                                                           Page 16
   Return configuration data (.SSRCD)


     the user in offset .SQLPN.
   SCS% JSYS                                                           Page 17
   Return status information (.SSSTS)


                       Return status information (.SSSTS)



          This function returns status information about a connection.  It  is
     intended  as  a  fast  form  of  the  .SSCSP  function code which returns
     detailed information about a  connection.   This  function  requires  the
     following arguments:

             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQCID !                      Connect ID                       !
             !-------------------------------------------------------!
      .SQFST !           Flags          !       Connect state        ! -------------
             !-------------------------------------------------------!    Returned
      .SQSBR !         Reserved         !       SBI of remote        !      data
             !=======================================================! -------------


          The flags which appear in the flags field are:

     1.  Message available - There is at least one message avilable  for  this
         connection.

     2.  Datagram available - There is at least  one  datagram  available  for
         this connection.

     3.  DMA transfer complete - At least one DMA transfer has completed since
         the  last  time  the SCS% JSYS was performed with this function code.
         The bit is cleared in the monitor data base when this  function  code
         is performed.


     The complete set of flag symbol definitions may be found in MONSYM.   The
     connect  state  is  provided such that a reasonable interpretation of the
     flags may be made.
   SCS% JSYS                                                           Page 18
   Receive a message (.SSRMG)


                           Receive a message (.SSRMG)



          This function code returns message text for either the calling  fork
     or  the  specified  connection.   If the connect ID field in the argument
     block is minus one, then the first message found for the calling fork  is
     returned.   If the connect ID is anything but minus one (-1), the monitor
     will use this as a connect ID and return the first message found for that
     connection.   Note  that  if  there  is  no  message available an illegal
     instruction is generated.  The following argument block is  required  for
     this function code.


             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------! -----------
      .SQCID !                  Connect ID or -1                     !      ^
             !-------------------------------------------------------!      !
      .SQARB !              Address of returned buffer               !      !
             !-------------------------------------------------------! Returned data
      .SQDFL !          Flags           !        SBI of remote       !      !
             !-------------------------------------------------------!      !
      .SQLRP !             Length of returned packet               !      v
             !=======================================================! -----------


          The address of returned buffer is the address in  your  working  set
     that  the  monitor  has  placed  your  data.   This address is one of the
     addresses previously specifed by a .SSQRM call.  If no  .SSQRM  call  was
     done, then this function code will fail with an illegal instruction trap.
     If the address is not writable you will also get an  illegal  instruction
     trap.
          The flags are returned by the monitor and  currently  only  indicate
     the data packing mode.
          The length of the returned  packet  is  in  bytes  for  an  industry
     compatible mode message, and words for a high density mode packet.
   SCS% JSYS                                                           Page 19
   Receive a datagram (.SSRDG)


                           Receive a datagram (.SSRDG)



     This function code returns datagram text for either the calling  fork  or
     the  specified connection.  If the connect ID field in the argument block
     is minus one, then the first datagram  found  for  the  calling  fork  is
     returned.   If the connect ID is anything but minus one (-1), the monitor
     will use this as a connect ID and return the  first  datagram  found  for
     that connection.  This is the argument block for this function code:


             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------! -----------
      .SQCID !                  Connect ID or -1                     !      ^
             !-------------------------------------------------------!      !
      .SQARB !              Address of returned buffer               !      !
             !-------------------------------------------------------! Returned data
      .SQDFL !          Flags           !        SBI of remote       !      !
             !-------------------------------------------------------!      !
      .SQLRP !            Length of returned packet                !      v
             !=======================================================! -----------


     The address of returned data is one of  the  addresses  provided  to  the
     monitor on a .SSQRD call.  If no .SSQRD was done or if the address is not
     writable, the JSYS will fail with an illegal instruction trap.  Also note
     that if there was no datagram available this address is zero.
          The flags are returned by the monitor and  currently  only  indicate
     the data packing mode.
          The length of the returned packet is in words  if  this  is  a  high
     density datagram, and bytes if an industry compatible datagram.
   SCS% JSYS                                                           Page 20
   .SSGDE (Get entry from data queue)


                       .SSGDE (Get entry from data queue)



          This function code returns the first entry  from  the  data  request
     complete queue.  The argument block follows:

              !=======================================================!
      .SQLEN  !      Words processed      !      Length of block      !
              !-------------------------------------------------------!
      .SQBID  !           Buffer ID whos transfer completed           !
              !=======================================================!

          The buffer ID indicates which DMA transfer has completed.
   SCS% JSYS                                                           Page 21
   .SSEVT (Get an entry off the event queue)


                    .SSEVT (Get an entry off the event queue)



          This function code retrieves the first entry off  the  event  queue.
     This  queue  is  a  record of events that the JSYS user is to be notified
     about.  The user receives an interrupt on the first  event.   After  this
     events  will  be added to the end of the queue with no further interrupts
     generated.  It is the responsibility of the user to empty this queue upon
     receiving an event interrupt.

          If a  connect  ID  is  specified,  then  the  next  event  for  that
     connection  will  be  returned.  If however the connect ID field is minus
     one, then the next event for the fork is returned.

              !=======================================================!
      .SQLEN  !      Words processed      !      Length of block      !
              !-------------------------------------------------------! -----------
      .SQCID  !                  Connect ID or -1                     !      ^
              !-------------------------------------------------------!      !
      .SQESB  !         Reserved          !       SBI of remote       !      !
              !-------------------------------------------------------!   Returned
      .SQEVT  !                 Returned event code                   !     data
              !-------------------------------------------------------!      !
      .SQDTA  \                                                       \      !
              \                 Returned event data                   \      !
              \                                                       \      v
              !=======================================================! -----------

          The event code describes what event has  occured.   It  is  a  small
     integer  ranging  from  zero  to a maximum value.  Hence it can easily be
     used as an index into an event dispatch table.  The connect ID tells  you
     what  connection this event is relevant to.  The event data is a block of
     data returned for each event type.
   SCS% JSYS                                                           Page 22
   DMA overview


                                  DMA overview



|         To send data to a remote system, you must first  declare  memory  in
|    your  working  set to be part of a buffer.  A buffer is made of segments.
|    Each segment is a contiguous set of 36 bit words that DO NOT CROSS A PAGE
|    BOUNDARY  and  are not more than one page long.  Once the buffer has been
|    established, you must tell the remote system the name of the buffer  that
|    you have declared.
   SCS% JSYS                                                           Page 23
   Map a buffer (.SSMAP)


                              Map a buffer (.SSMAP)
|  
|  
|  
|         This function code associates a portion of memory with an SCA buffer
|    name  to  be  used  in  DMA transfers.  This function takes the following
|    arguments:
|  
|            !=======================================================!
|     .SQLEN !      Processed words     !       Length of block      !
|            !-------------------------------------------------------!
|     .SQBNA !             Returned 32 bit buffer name               ! (Returned)
|            !-------------------------------------------------------!
|            /                                                       /
|            /           Buffer length and address pairs             /
|            /                                                       /
|            !=======================================================!
|  
|         Buffer length and address paris have the following format:
|  
|  
|            !=======================================================!
|    .SQBLN  !        Length in 36 bit words of memory block         !
|            !-------------------------------------------------------!
|    .SQBAD  !          Address of memory for DMA transfer           !
|            !=======================================================!
|  
|         The address for DMA transfer is the  address  in  your  working  set
|    where  you  expect  data  from a DMA transfer to be placed by the CI port
|    microcode.  All pages in your working set  that  are  contained  in  this
|    request  will  be locked into resident memory.  They will remain this way
|    until you unmap the buffer.
|  
|         The buffer name is the descriptor by which all other  references  to
|    this memory is made.


                              *** Restrictions ***

     1.  No buffer segment may cross  a  page  boundary.   Hence  the  longest
         possible buffer segment is one page.



                                      Note:
          All pages containing a buffer segment will be locked  into  physical
     memory.  Unlocking these pages behind SCA's back will cause severe system
     problems!!!
   SCS% JSYS                                                           Page 24
   Unmap a buffer (.SSUMP)


                             Unmap a buffer (.SSUMP)



          This function will remove from  the  monitor  data  base  (unmap)  a
     memory block assigned for DMA transfers.  It requires these arguments:

             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!
      .SQNAM !                  32 bit buffer name                   !
             !=======================================================!

          Upon completion of this call the pages in the memory  block  are  no
     longer locked into physical memory.
   SCS% JSYS                                                           Page 25
   Send data (.SSSND)


                               Send data (.SSSND)



|         This  function  transfers  data  to  a  remote  host.   It  is   the
|    responsibility  of a higher level protocol to arrange the setup of buffer
|    names.  The call requires the following arguments:
|  
|            !=======================================================!
|     .SQLEN !      Processed words     !       Length of block      !
|            !-------------------------------------------------------!
|     .SQCID !       Connect ID for which transfer is to be done     !
|            !-------------------------------------------------------!
|     .SQSNM !          32 bit buffer name of send buffer            !
|            !-------------------------------------------------------!
|     .SQRNM !        32 bit buffer name of receive buffer           !
|            !-------------------------------------------------------!
|     .SQOFS !        Xmit offset       !       Receive offset       !
|            !=======================================================!
   SCS% JSYS                                                           Page 26
|  Request data (.SSREQ)


|                             Request data (.SSREQ)
|  
|  
|  
|         This function tells SCA and the port  to  get  data  for  the  given
|    buffer name.  The following arguments are required:
|  
|            !=======================================================!
|     .SQLEN !      Processed words     !       Length of block      !
|            !-------------------------------------------------------!
|     .SQCID !       Connect ID for which transfer is to be done     !
|            !-------------------------------------------------------!
|     .SQSNM !          32 bit buffer name of send buffer            !
|            !-------------------------------------------------------!
|     .SQRNM !        32 bit buffer name of receive buffer           !
|            !-------------------------------------------------------!
|     .SQOFS !        Xmit offset       !       Receive offset       !
|            !=======================================================!
   SCS% JSYS                                                           Page 27
   Read port counters (.SSRPC)


                           Read port counter (.SSRPC)



          This function reads  the  maintainance  counters  out  of  the  port
     hardware.  The following argument block is used:


             !=======================================================!
      .SQLEN !      Processed words     !       Length of block      !
             !-------------------------------------------------------!  -----------
      .SQP0A !                  Path zero ACK count                  !       ^
             !-------------------------------------------------------!       !
      .SQP0N !                  Path zero NAK count                  !       !
             !-------------------------------------------------------!       !
      .SQP0R !              Path zero no response count              !       !
             !-------------------------------------------------------!       !
      .SQP1A !                  Path one ACK count                   !       !
             !-------------------------------------------------------!    Returned
      .SQP1N !                  Path one NAK count                   !      data  
             !-------------------------------------------------------!       !
      .SQP1R !              Path one no response count               !       !
             !-------------------------------------------------------!       !
      .SQNPT !             Number of packets transmitted             !       !
             !-------------------------------------------------------!       !
      .SQNPR !              Number of packets received               !       !
             !-------------------------------------------------------!       !
      .SQPOR !                    Designated port                    !       v
             !=======================================================!  -----------


          Only the function code is passed to the monitor.  The rest  of  this
     block is information returned by the monitor.
   SCS% JSYS                                                           Page 28
   .SSAIC (Add interrupt channels)


                         .SSAIC (Add interrupt channels)



|         All notifications from SCA  happen  on  four  PSI  channels.   These
|    channels  are:   datagram  available,  message  available,  DMA  transfer
|    complete, and all  other  events.   These  other  events  include  vitual
|    circuit  closure,  connection  managment  events,  and  all  port and SCA
|    related errors.  Interrupts will work just as they do now,  add  the  SCA
|    bits  to  the  interrupt  mask,  add  a cooresponding entry to LEVTAB and
|    CHNTAB, and an interrupt service routine.
|         Note that this call  only  tells  SCA  what  channels  to  use  when
|    interrupts  are  to  be given.  It is not a replacement for the AIC JSYS!
|    The argument block used to associate events with PSI  channels  has  this
|    format:

             !=======================================================!
      .SQLEN !      Words processed      !      Length of block      !
             !-------------------------------------------------------!
             \                                                       \
             \          Up to four channel descriptor words          \
             \                                                       \
             !=======================================================!

     Where channel desrciptor words have the following format:

             !=======================================================!
             !    Interrupt type code    !   Channel for this code   !
             !=======================================================!

     The interrupt type code is a small integer that indicates an event  type.
     The  channel number field allows you to enable and disable interrupts for
     the given event type.  If the channel number is -1  then  interrupts  are
     disabled.   If  it  is an integer between zero and thirty five, then that
     channel will interrupt on the given event  type.   The  next  box  is  an
     example of what the maximum size block would look like.

             !=======================================================!
      .SQLEN !      Words processed      !      Length of block      !
             !-------------------------------------------------------!
             !          .SIDGA           !      Channel number       !
             !-------------------------------------------------------!
             !          .SIMSA           !      Channel number       !
             !-------------------------------------------------------!
             !          .SIDMA           !             -1            !
             !-------------------------------------------------------!
             !          .SIPAN           !      Channel number       !
             !=======================================================!

     In this example interrupts for message available, datagram available, and
     all  other events are being enabled.  Interrupts on DMA transfer complete
     are being disabled.  Note that only the first word  of  this  block  need
     appear  in this position.  The channel descriptor words may appear in any
     order.  There must be at least one but  not  more  than  four  descriptor
   SCS% JSYS                                                           Page 29
   .SSAIC (Add interrupt channels)


     words in a block.
SCA-TABLES.TXT

;States of a connection. Names in all caps are from corporate spec.

	.CSCLO==1		;Closed (CLOSED) 
	.CSLIS==2		;Listening (LISTENING)
	.CSCSE==3		;Connect request was sent (CONNECT_SENT)
	.CSCRE==4		;Connect request was received (CONNECT_REC)
	.CSCAK==5		;Connect response was received (CONNECT_ACK)
	.CSACS==6		;Accept request was sent (ACCEPT_SENT)	
	.CSRJS==7		;Reject request was sent (REJECT_SENT)
	.CSOPN==10		;Connection is open (OPEN)
	.CSDSE==11		;Disconnect request was sent (DISCONNECT_SENT)
	.CSDRE==12		;Disconnect request received (DISCONNECT_REC)
	.CSDAK==13		;Disconnect response received (DISCONNECT_ACK)	
	.CSDMC==14		;Waiting for disconnect response (DISCONNECT_MATCH)

;States of a connection block

	.BSFRE==:1		;Free
	.BSALL==:2		;Allocate
	.BSCNP==:3		;Connect pending
	.BSACP==:4		;Accept pending
	.BSRPN==:5		;Reject pending
	.BSCRP==:6		;Credit pending
	.BSDPN==:7		;Disconnect pending


;Messages

	.STORQ==0		;Connect request
		.LNORQ==^D64
	.STORS==1		;Connect response
		.LNORS==^D16
	.STARQ==2		;Accept request
		.LNARQ==^D64
	.STARS==3		;Accept response
		.LNARS==^D16
	.STRRQ==4		;Reject request
		.LNRRQ==^D16
	.STRRS==5		;Reject response
		.LNRRS==^D12
	.STDRQ==6		;Disconnect request
		.LNDRQ==^D16
	.STDRS==7		;Disconnect response
		.LNDRS==^D12
	.STCRQ==10		;Credit request
		.LNCRQ==^D12
	.STCRS==11		;Credit response
		.LNCRS==^D12

	.STAMG==12		;Application message
	.STADG==13		;Application datagram
;Table X - calls from sysap to SCA.
;Note: if new connection state is in <>, it isn't set until the pending
;message has been sent

Routine	State		Legal?		New block	New connection
					State		State

SC.CON	Closed		Y		CONN_PEND	<connect_sent>
	Listening
	Connect_sent
	Connect_rec
	Connect_ACK
	Open
	Accept_sent
	Reject_sent
	Disconnect_sent
	Disconnect_rec
	Disconnect_ACK
	Disconnect_match



Routine	State		Legal?		New block	New connection
					State		State

SC.LIS	Closed		Y		-		Listen
	Listening
	Connect_sent
	Connect_rec
	Connect_ACK
	Open
	Accept_sent
	Reject_sent
	Disconnect_sent
	Disconnect_rec
	Disconnect_ACK
	Disconnect_match

Routine	State		Legal?		New block	New connection
					State		State

SC.ACC	Closed
	Listening
	Connect_sent
	Connect_rec	Y		ACC_PEND	<Accept-sent>
	Connect_ACK
	Open
	Accept_sent
	Reject_sent
	Disconnect_sent
	Disconnect_rec
	Disconnect_ACK
	Disconnect_match

* * Old code didn't change state
Routine	State		Legal?		New block	New connection
					State		State

SC.REJ	Closed
	Listening
	Connect_sent
	Connect_rec	Y		REJ_PEND	<reject_sent>
	Connect_ACK
	Open
	Accept_sent
	Reject_sent
	Disconnect_sent
	Disconnect_rec
	Disconnect_ACK
	Disconnect_match

* * * Old code left state as "listen"



Routine	State		Legal?		New block	New connection
					State		State

SC.DIS	Closed		Y		FREE		closed
	Listening	Y		FREE		closed
	Connect_sent	Y		FREE		closed
	Connect_rec	Y		REJ_PEND	reject_sent
	Connect_ACK	Y		FREE		closed
	Open		Y		DIS_PEND	disconnect_sent
	Accept_sent	Y		FREE		closed
	Reject_sent	Y		FREE		closed
	Disconnect_sent	Y		FREE		closed
	Disconnect_rec	Y		DIS_PEND	disconnect_match
	Disconnect_ACK	Y		FREE		closed
	Disconnect_match Y		FREE		closed
;Table Y -- processing SCS work queue

Block		Op code		New connection
State		to send		State

CONN_PEND	CONNECT_REQ	connect_sent
ACC_PEND	ACCEPT_REQ	accept_sent
REJ_PEND	REJECT_REQ	reject_sent
DIS_PEND	DISCON_REQ	-- (already done)
CREDIT_PEND	CREDIT_REQ	--
;Table Z - sending an SCS message

Name		Code		Length		priority	Response

CONNECT_REQ	.STORQ==0	.LNORQ==^D64	.MPCMM		CONNECT_RSP
CONNECT_RSP	.STORS==1	.LNORS==^D16	.MPCMM
ACCEPT_REQ	.STARQ==2	.LNARQ==^D64	.MPCMM		ACCEPT_RSP
ACCEPT_RSP	.STARS==3	.LNARS==^D16	.MPCMM
REJECT_REQ	.STRRQ==4	.LNRRQ==^D16	.MPCMM		REJECT_RSP
REJECT_RSP	.STRRS==5	.LNRRS==^D12	.MPCMM
DISCONNECT_REQ 	.STDRQ==6	.LNDRQ==^D16	.MPLOW		DISCONNECT_RSP
DISCONNECT_RSP	.STDRS==7	.LNDRS==^D12	.MPCMM
CREDIT_REQ	.STCRQ==10	.LNCRQ==^D12	.MPFLO		CREDIT_RSP
CREDIT_RSP	.STCRS==11	.LNCRS==^D12	.MPCMM
;Table K - receiving a message

Name		Code	Current 	Legal?	Response	New connection
			State					State

CONNECT_REQ	0	Closed		Y	CONNECT_RSP NM
			Listening	Y	CONNECT_RSP	connect_received
			Connect_sent
			Connect_rec
			Connect_ACK
			Open
			Accept_sent
			Reject_sent
			Disconnect_sent
			Disconnect_rec
			Disconnect_ACK
			Disconnect_match



Name		Code	Current 	Legal?	Response	New connection
			State					State

CONNECT_RSP	1	Closed
			Listening
			Connect_sent
			  success	Y	-		Connect_ACK
			  failure	Y	-		Closed
			Connect_rec
			Connect_ACK
			Open
			Accept_sent
			Reject_sent
			Disconnect_sent
			Disconnect_rec
			Disconnect_ACK
			Disconnect_match

* * * Old code set state to "closed no match" if failure
Name		Code	Current 	Legal?	Response	New connection
			State					State

ACCEPT_REQ	2	Closed		Y	ACCEPT_RSP NM	closed
			Listening
			Connect_sent
			Connect_rec
			Connect_ACK	Y	ACCEPT_RSP	Open
			Open
			Accept_sent
			Reject_sent
			Disconnect_sent
			Disconnect_rec
			Disconnect_ACK
			Disconnect_match

* * * * Old code closed v.c. if state was closed; required block state
of connect_pend, too



Name		Code	Current 	Legal?	Response	New connection
			State					State

ACCEPT_RSP			Closed
			Listening
			Connect_sent
			Connect_rec
			Connect_ACK
			Open
			Accept_sent
			  Match		Y	-		Open
			  No match	Y	-		closed
			Reject_sent
			Disconnect_sent
			Disconnect_rec
			Disconnect_ACK
			Disconnect_match

* * * * Old code expected state to be connect_received; set new state
to closed; required block state of accept_pend
Name		Code	Current 	Legal?	Response	New connection
			State					State

REJECT_REQ		Closed
			Listening
			Connect_sent
			Connect_rec
			Connect_ACK	Y	REJECT_RSP	Closed
			Open
			Accept_sent
			Reject_sent
			Disconnect_sent
			Disconnect_rec
			Disconnect_ACK
			Disconnect_match


* * * Old code set new state to closed-rejected
* * * Why not treat "closed" as legal as in accept_request



Name		Code	Current 	Legal?	Response	New connection
			State					State

REJECT_RSP		Closed
			Listening
			Connect_sent
			Connect_rec
			Connect_ACK
			Open
			Accept_sent
			Reject_sent	Y	-		closed
			Disconnect_sent
			Disconnect_rec
			Disconnect_ACK
			Disconnect_match


* * * Old code expected state to be "listen"; left it as "listen"
Name		Code	Current 	Legal?	Response	New connection

DISCONNECT_REQ		Closed
			Listening
			Connect_sent
			Connect_rec
			Connect_ACK
			Open		Y	DISCONNECT_RSP	disconnect_received
			Accept_sent
			Reject_sent
			Disconnect_sent	Y	DISCONNECT_RSP	disconnect_match
			Disconnect_rec
			Disconnect_ACK	Y	DISCONNECT_RSP	closed
			Disconnect_match




Name		Code	Current 	Legal?	Response	New connection
			State					State

DISCONNECT_RSP		Closed
			Listening
			Connect_sent
			Connect_rec
			Connect_ACK
			Open
			Accept_sent
			Reject_sent
			Disconnect_sent	Y	-		Disconnect_ACK
			Disconnect_rec
			Disconnect_ACK
			Disconnect_match Y	-		closed


+---------------+
! d i g i t a l !   I N T E R O F F I C E  M E M O R A N D U M
+---------------+

TO:  Distribution
                                       DATE:  10 May 83

                                       FROM:  Clair Grant

                                       DEPT:  LCG Software
                                              Engineering

                                       LOC:   MRO1-2/L10

                                       EXT:   6877


SUBJ:  TOPS-20 Systems Communications Service Tester

This is a description of the SCSTST  project,  the  test  vehicle  for
TOPS-20's  implementation  of  the  corporate  Systems  Communications
Acrhitecture being used on the CI.  It is believed that such a  tester
is  a  necessity  for  the  ultimate  success of the project, not just
initial debug and release, but for  future  development,  maintenance,
and performance measurement.

Both  DECnet  and  ARPANET   have   testers,   DTR/DTS   and   TRAFIC,
respectively;  they have been invaluable in recent TOPS-20 development
efforts and the same need exists for SCS.
                                                                Page 2


1.0  PROJECT GOALS

The project goals for the TOPS-20 System Communication  Service  (SCS)
test package are to provide:

     1.  a comprehensive tester for the SCS% JSYS, the  SCA  protocol,
         and the CI device driver

     2.  a quick and reliable means of  determining  that  SCS  is  in
         working order

     3.  a tool for performance comparison between different  versions
         of TOPS-20

     4.  a command file which, when TAKEn by  SCSTST,  will  tell  the
         user that SCS is functioning properly




2.0  RESTRICTIONS/DEFICIENCIES

The SCS tester will have the following restrictions:

     1.  it will not test every invalid way in which the SCS% JSYS can
         be called but will do some fault insertion

     2.  it will be used between TOPS-20 systems only




3.0  FUTURE CONSIDERATIONS

Any developer working on the TOPS-20 SCS  implementation  should  view
the  tester  as  an  integral part of the product.  An SCS development
project should not be considered complete until the  tester  has  been
modified,  if  necessary,  and  run  to  verify  that  SCS  is working
properly.  For example, SCSTST will look for specific error returns in
certain situations;  if someone changes the way the monitor handles an
error condition it must be verified that SCSTST is  not  effected,  or
SCSTST must be modified to handle the new situation.

Also, the design of the SCS tester could be used  by  other  operating
systems  to  provide  a  model  by which inter-system testing could be
done, e.g., DECnet's DTR/DTS.



4.0  GENERAL DESIGN

There will be 1 source file SCSTST.MAC.  It will use the  CMD  package
to  implement  the  command interface;  all functions of the SCS% JSYS
will be used.  SCSTST can be run in  either  "server"  or  "initiator"
mode.   Server  mode responds to incoming test requests, and initiator
                                                                Page 3


mode generates test requests.

SCSTST creates a multi-forking  environment.   The  top  fork  is  the
command   processor;    it   creates   test   streams  (sub-forks)  as
necessitated by the user's command selection.   Also,  a  sub-fork  is
created  which  performs the logging function.  As tests run, they log
information into a buffer which is periodically emptied to a  file  by
the logging fork.

In server mode, it starts  a  sub-fork  and  opens  an  SCS  listener;
whenever  an  incoming  connection  arrives,  that  fork processes the
connection attempt (and subsequent test messages) and another sub-fork
is established as the listener.  When a test finishes, the sub-fork is
killed.  Thus, multiple tests can  be  directed  at  a  single  node's
server  as  long  as  the  maximum  number  of  sub-forks has not been
exceeded.  Likewise, in initiator mode, SCSTST creates a sub-fork  for
each  test called for by the user.  When a test finishes, the sub-fork
is killed.  The user can create multiple tests, possibly to  different
nodes,  simultaneously, as long as the maximum number of sub-forks has
not been exceeded.



5.0  RECORDING OF RESULTS

An entry will be made in a log file for each incoming test request and
its  results.   Counters  will  be maintained by the program and their
values will be entered, as appropriate, in the log.

There will also be a trace  mode.   It  will  provide  a  blow-by-blow
account of each SCS% function performed and the results.  Logging must
be enabled for tracing to occur.



6.0  SCS% FUNCTION TESTING

SCSTST will use the SCS% options in the following tests:

.SSCON          all tests

.SSLIS          declaring SCSTST as the server

.SSACC          all tests except REJECT

.SSREJ          REJECT test

.SSDIS          all tests except REJECT

.SSSDG          DATAGRAM test

.SSQRD          DATAGRAM test

.SSSMG          MESSAGE test
                                                                Page 4


.SSQRM          MESSAGE test

.SSCRD          DATAGRAM test

.SSCRM          MESSAGE test

.SSCSP          IDLE test

.SSRCD          SCSTST initialization, all tests

.SSSTS          IDLE, DATAGRAM, MESSAGE, and DMA tests

.SSRMG          MESSAGE test

.SSRDG          DATAGRAM test

.SSGDE          DMA test

.SSEVT          all tests

.SSMAP          DMA test

.SSUMP          DMA test

.SSSND          DMA test

.SSREQ          DMA test

.SSRPC          all tests

.SSAIC          SCSTST initialization, all tests



7.0  USER INTERFACE

This section defines the command language of SCSTST.



7.1  DECLARE

The DECLARE command has  2  options  -  initiator  and  server;   this
establishes  SCSTST  as  either  the initiator or the server.  You can
only run the program in 1 of the 2 modes;  also, you can't switch from
one mode to the other.  If you are running as an initiator and want to
be a server, you must restart the program.  Example:

SCSTST>DECLARE (SCSTST TO BE THE) INITIATOR
                                                                Page 5


7.2  DISABLE

The DISABLE command directs SCSTST to stop performing  some  function;
there are 2 options - logging and tracing.

SCSTST>DISABLE (TEST FEATURE) TRACING



7.3  ENABLE

The ENABLE command directs SCSTST to start performing  some  function;
there  are  2  options  -  logging  tracing.   When SCSTST is started,
tracing is off and logging goes to the TTY.  Example:

SCSTST>ENABLE (TEST FEATURE) LOGGING (OUTPUT TO) FOO.LOG



7.4  EXIT

The EXIT command returns the  user  to  TOPS-20  command  level.   The
program is continuable, with no change to test parameters.  Example:

SCSTST>EXIT (TO TOPS-20 COMMAND LEVEL)



7.5  HELP

The HELP command prints out text which describes the  general  use  of
the   program.    It  does  not  provide  specific  information  about
individual commands.  Example:

SCSTST>HELP (WITH SCSTST)



7.6  SHOW

The SHOW command displays the current status of SCSTST.   The  current
status  of  logging,  tracing,  and  all  test streams (including test
parameters) are shown.  The output  from  SHOW  always  for  to  TTY:.
Example:

SCSTST>SHOW (CURRENT TEST PARAMETERS)



7.7  STOP

The STOP command is use to ternminate a running test stream.  Example:

SCSTST>STOP (TEST #) 2
                                                                Page 6


7.8  TAKE

The TAKE command is used to execute SCSTST commands from a file.   The
default file is SCSTST.CMD.  Example;

SCSTST>TAKE (COMMANDS FROM) FOO.CMD



7.9  TEST

The TEST command defines the remote node and the test to be run.   The
test options are:

     1.  IDLE - the idle test causes the initiator to send  a  connect
         with  optional  data.   The  server  reads  the first byte of
         optional data, finds the idle code, verifies that the rest of
         the  optional data bytes are null, and accepts the connection
         supplying the same optional data it received in the  connect.
         When  the server is notified that it is ok to send, it simply
         goes  to  sleep,  periodically  waking  to  check  that   the
         connection  is  still  there.   Meanwhile,  the initiator was
         notified that its connection was accepted and checked for the
         optional data it sent in the connect.  It then goes to sleep,
         waking periodically to check that connection is still  there.
         The initiator sends a disconnect when the time period is up.

SCSTST>TEST (TO NODE) 3 (FEATURE) IDLE-CONNECTION (FOR TIME
PERIOD) 00:02:00

    2.  CONNECT - the connect test has 2  options,  with  and  without
        optinal   data.   The  "no  optional  data"  test  causes  the
        initiator to send a connect request  with  no  optional  data.
        The  server  reads  the  first  byte  of  optional data, finds
        nothing and verifies that the rest of the optional data  block
        is empty;  it then does an accept with no optional data.  When
        the server  is  notified  that  it  is  OK  to  send  on  this
        connection,   it   does   a   disconnect   with   reason  code
        connect-with-no-optional-data-ok.   Meanwhile,  the  initiator
        was  notified  that  its  connection  had  been  accepted, and
        checked for no optional data.  When the initiator receives the
        disconnect, it verifies the reason code.

        The "optional data"  test  causes  the  initiator  to  send  a
        connect  request  with  optional  data.   The server reads the
        first     byte     of     optional     data,     finds     the
        connect-no-optional-data  code  and  verifies that the rest of
        the  optional  data  block  has  a  program-specified  set  of
        characters;   it  then  does  an  accept  with  the  identical
        optional data it received in the connect.  When the server  is
        notified  that  it  is  OK  to send, it does a disconnect with
        reason code connect-with-no-optional-data-ok.  Meanwhile,  the
        initiator  was notified that its connection had been accepted,
        and checked for optional data matching what  it  sent  in  the
        connect.   When  the  initiator  receives  the  disconnect, it
                                                                Page 7


        verifies the reason code.

        Example:

SCSTST>TEST (TO NODE) 3 (FEATURE) CONNECT (WITH) NO-OPTIONAL-DATA 

    3.  REJECT - the reject test  has  2  options,  with  and  without
        reason  code.   The "reason code" test causes the initiator to
        send a connect request with optional data.  The  server  reads
        the   first   byte  of  optional  data,  finds  the  code  for
        reject-reason code, verifies that the  rest  of  the  optional
        data   is   null,   and   does   a  reject  with  reason  code
        reject-reason-ok.  When the initiator  is  notified  that  the
        connection attempt was rejected, it verifies the reason code.

        The "no reason code" test  causes  the  initiator  to  send  a
        connect  request  with  optional  data.   The server reads the
        first  byte   of   optional   data,   finds   the   code   for
        reject-no-reason,  verifies that the rest of the optional data
        is null, and does a reject with  no  reason  code.   When  the
        initiator   is   notified  that  the  connection  attempt  was
        rejected, it verifies that no reason code was returned.

        Example:

SCSTST>TEST (TO NODE) 3 (FEATURE) REJECT (WITH) REASON-CODE 

    4.  DISCONNECT - the disconnect  test  has  2  options,  with  and
        without  reason  code.   The  "reason  code"  test  causes the
        initiator to send a connect with optional  data.   The  server
        reads   the   first   byte   of   optional   data,  finds  the
        disconnect-reason code and  verifies  that  the  rest  of  the
        optional data block is empty;  it then does an accept with the
        identical optional data it received in the connect.  When  the
        server is notified that it is OK to send, it does a disconnect
        with  reason  code   disconnect-reason-ok.    Meanwhile,   the
        initiator  was notified that its connection had been accepted,
        and checked for optional data matching what was  sent  in  the
        connect.   When  the  initiator  receives  the  disconnect, it
        verifies the reason code.

        The "no reason code" test sends a connect with optional  data.
        The  server  reads  the first byte of optional data, finds the
        reject-no-reason code  and  verifies  that  the  rest  of  the
        optinal  data  is  null;   it  then  does  and accept with the
        optional data it received on the connect.  When the server  is
        notified  that  it  ok  to  send, it does a disconnect with no
        reason code.  Meanwhile, the initiator has been notified  that
        the  connect  was  accepted,  and  verifies the optional data.
        When the initiator receives the disconnect, it checks  for  no
        reason code.

        Example:

SCSTST>TEST (TO NODE) 3 (FEATURE) DISCONNECT (WITH) NO-REASON-CODE 
                                                                Page 8


    5.  DATAGRAM - the datagram test has  3  options:   a)  number  of
        bytes  per  datagram, b) duration of the test, and c) transfer
        mode.  The initiator sends a connect with optional data.   The
        server  reads  the  optional  data and finds the datagram-mode
        code and the  byte  count,  verifies  that  the  rest  of  the
        optional  data is null, and does and accept with optional data
        matching what it received in the connect.  When it is notified
        that  it  is  OK to send, it simply waits for the datagrams to
        arrive.  Meanwhile, the initiator has been notified  that  its
        connect  has  been  accepted,  verifies the optional data, and
        begins sending datagrams.  The server verifies  each  datagram
        (the byte pattern is predefined in the program) and returns it
        to the initiator who also verifies the byte pattern.  When the
        time period runs out the initiator sends a disconnect.

        Example:

SCSTST>TEST (TO NODE) 3 (FEATURE) DATAGRAMS (OF BYTE COUNT) 200 (FOR
TIME PERIOD) 00:02:00 (IN MODE) HIGH-DENSITY

    6.  MESSAGE - analogous to DATAGRAM

        Example:

SCSTST>TEST (TO NODE) 3 (FEATURE) MESSAGES (OF BYTE COUNT) 200 (FOR
TIME PERIOD) 00:02:00 (IN MODE) INDUSTRY-COMPATIBLE

    7.  DMA-TRANSFERS - analogous to DATAGRAM

        Example:

SCSTST>TEST (TO NODE) 3 (FEATURE) DMA-TRANSFERS (OF BUFFER SIZE) 50
(WITH BUFFER POOL OF) 10 (FOR TIME PERIOD) 00:02:00




7.10  WAIT

The WAIT command directs SCSTST to wait for all current  test  streams
to stop before executing the next SCSTST command.

SCSTST>WAIT (FOR ALL TESTS TO STOP)
                                                                Page 9


8.0  VERIFICATION COMMAND SET

The following command set should be used to verify that TOPS-20's  SCS
is  in  basic  working  order.  It assumes a 2 node configuration;  if
more nodes are available, a similar command set would  be  appropriate
for  each  node.   The  test  should  take  about 20 minutes to run to
completion.

DECLARE INITIATOR

!Part 1 - individual connection management tests
!
TEST 1 CONNECT NO-OPTIONAL-DATA
WAIT
TEST 1 CONNECT OPTIONAL DATA
WAIT
TEST 1 DISCONNECT NO-REASON
WAIT
TEST 1 DISCONNECT REASON
WAIT
TEST 1 REJECT NO-REASON
WAIT
TEST 1 REJECT REASON
WAIT
!
!Part 2 - simultaneous connection management tests
!
TEST 1 CONNECT NO-OPTIONAL-DATA
TEST 1 CONNECT OPTIONAL DATA
TEST 1 DISCONNECT NO-REASON
TEST 1 DISCONNECT REASON
TEST 1 REJECT NO-REASON
TEST 1 REJECT REASON
TEST 1 CONNECT NO-OPTIONAL-DATA
TEST 1 CONNECT OPTIONAL DATA
TEST 1 DISCONNECT NO-REASON
TEST 1 DISCONNECT REASON
TEST 1 REJECT NO-REASON
TEST 1 REJECT REASON
!
!Part 3 - individual data tests, 2 minutes each
!
TEST DATAGRAM 10 2 INDUSTRY-COMPATIBLE
WAIT
TEST 1 DAAGRAM 10 2 HIGH-DENSITY
WAIT
TEST 1 MESSAGE 10 2 INDUSTRY-COMPATIBLE
WAIT
TEST 1 MESSAGE 10 2 HIGH-DENSITY
WAIT
TEST 1 DMA-TRANSFERS 10 5 2
WAIT
!
!Part 4 - multiple datagram test, 1 minute each
!
                                                               Page 10


TEST 1 DATAGRAM 0 1 INDUSTRY-COMPATIBLE         ;an empty datagram
TEST 1 DATAGRAM 1 1 HIGH-DENSITY                ;a small datagram
TEST 1 DATAGRAM 200 1 INDUSTRY-COMPATIBLE       ;a medium datagram
TEST 1 DATAGRAM 604 1 HIGH-DENSITY              ;the biggest datagram
!
!Part 5 - multiple message test, 1 minute each
!
TEST 1 MESSAGE 0 1 INDUSTRY-COMPATIBLE          ;an empty message
TEST 1 MESSAGE 1 1 HIGH-DENSITY                 ;a small message
TEST 1 MESSAGE 50 1 INDUSTRY-COMPATIBLE         ;a medium message
TEST 1 MESSAGE 148 1 HIGH-DENSITY               ;the biggest message
!
!Part 6 - multiple DMA test, 1 minute each
!
TEST 1 DMA-TRANSFERS 0 3 1                      ;an empty transfers
TEST 1 DMA-TRANSFERS 1 3 1                      ;a small transfer
TEST 1 DMA-TRANSFERS 100 3 1                    ;a medium transfer
TEST 1 DMA-TRANSFERS 512 3 1                    ;the biggest transfer
!
!Part 7 - mixed data test, 5 minutes each
!
TEST 1 IDLE-CONNECTION
TEST 1 DATAGRAM 10 5 INDUSTRY-COMPATIBLE
TEST 1 DATAGRAM 10 5 HIGH-DENSITY
TEST 1 MESSAGE 10 5 INDUSTRY-COMPATIBLE
TEST 1 MESSAGE 10 5 HIGH-DENSITY
TEST 1 DMA-TRANSFERS 10 5 5

[END OF SCA-INFO.MEMOS]