rfc120.txt

著名的RFC文档,其中有一些文档是已经翻译成中文的的.

                        NETWORK PL1 SUBPROGRAMS















                             April 21, 1971

                            Mark Krilanovich

                         Computer Research Lab

                        University of California

                       Santa Barbara, California


























                                                                [Page 1]

RFC 120                 NETWORK PL1 SUBPROGRAMS


                                PREFACE

   The subroutines described in this document have been implemented at UCSB
   and make the Network (via the NCP) accessible to PL1 programs executing
   in the 360/75.  They are callable from within any PL1 main program or
   subroutine compiled at UCSB.


   A  set  of  assembly-language  written  subprograms  is  provided  to
   facilitate  the use of the Network by PL1 programmers.  They serve as
   an interface between the user and the Network Control Program  (NCP),
   which supervises all Network operations at this site.


   A concept  fundamental  to  PL1  Network  operations  is  that  of  a
   completion code variable.  Associated with each socket that is not in
   the closed state is a  unique  variable,  called  a  completion  code
   variable.   This  variable  serves  two  purposes:  it identifies the
   local socket referenced, and upon  completion  of  the  operation  it
   contains  a  completion code to indicate the outcome of the operation
   to the programmer.  It may be used at any time for any purpose  other
   than  Network  operations.   Its  value at the beginning of a Network
   operation is immaterial;  rather, it is the variable itself  that  is
   important.   In  all  Network  operations, whenever a completion code
   variable is called  for,  the  only  acceptable  attributes  for  the
   variable are BINARY FIXED(31,0)ALIGNED.

   In general, the subprograms will initiate the  operation,  and  enter
   the WAIT state (consume no CPU time) until notified by the NCP of the
   completion of the operation.  For  such  operations,  the  programmer
   supplies  a  time  limit,  with  attributes BINARY FIXED(31,0), which
   specifies, in tenths of a second, the  maximum  length  of  time  the
   subprogram  is  to  wait for the operation to complete.  If this time
   limit is exceeded, a completion code  is  supplied  to  indicate  the
   error,  and  control  is  returned  to  the calling program, with the
   operation still pending.

   In those operations requiring a socket to be specified by its  socket
   identifier,   the  following  format  is  used.   The  identifier  is
   specified as a BINARY FIXED(31,0) array, singly dimensioned  with  at
   least  two  elements,  and  with a lower subscript bound of one.  The
   first element is taken to be the site number, and the second  element
   the  socket  number.   A  socket number may have any value, positive,
   negative, or zero.  Since negative numbers are represented internally
   in two's complement form, for the purposes of the gender of a socket,
   a socket number is even or odd  according  to  whether  its  absolute
   value is even or odd, respectively.




                                                                [Page 2]

RFC 120                 NETWORK PL1 SUBPROGRAMS


   Following is a description  of  each  subprogram,  its  function  and
   calling sequence.

(1)  OPEN

     By invoking this subprogram, the user requests that  the  specified
     local  socket be removed from the closed state and thus be prepared
     to  participate  in  data  transfer.   There  are  three   distinct
     operations  that can be performed by this subprogram, and these are
     described below:

     (A)  CONNECT

          By initiating this  operation,  the  user  requests  that  the
          specified local socket be logically connected to the specified
          foreign socket, and that data transfer between the two sockets
          be enabled.  The subprogram will wait until the foreign socket
          either  accepts  or  rejects  the  connection  attempt.   This
          operation  is  valid  only  when  the  socket is in the closed
          state.

          The calling sequence is as follows:

               CALL @OPEN(cmpcd, time,lclsck,fgnsck,ws);

          where

               'cmpcd' is the completion code variable to be associated
                    with the local socket.
               'time' is the length of time the subprogram is to wait
                    for the completion of the operation.
               'lclsck' is the socket identifier of the local socket.
               'fgnsck' is the socket identifier of the foreign socket.
               'ws' is a workspace which has the same attributes as a
                    socket identifier, and, if the operation if
                    successful, will become associated with the local
                    socket for the life of the connection.  In response
                    to certain future operations, information may be
                    returned to the programmer in this workspace.

          The  following  completion  codes  are   possible   for   this
          operation:

               0,  The operation was successful and the connection has
                   been established
               4,  The specified completion code variable is already
                   assigned to a socket;  the operation was suppressed
               8,  The specified local socket is not in the closed



                                                                [Page 3]

RFC 120                 NETWORK PL1 SUBPROGRAMS


                   state;  the operation was suppressed
              12,  All communication paths to the specified foreign site
                   are in use;  the operation was suppressed
              16,  Local resources are insufficient to support another
                   connection;  the operation was suppressed
              20,  The connection attempt was rejected by the foreign
                   process
              24,  The specified local socket is not local to UCSB;  the
                   operation was suppressed
              28,  The specified foreign site is invalid;  the operation
                   was suppressed
              32,  An addressing or protection exception was encountered
                   with respect to the specified workspace;  the
                   operation was suppressed
              36,  Either hardware at the foreign site is inoperative or
                   the NCP's counterpart at the foreign site does not
                   exist or has failed
              40,  Local and foreign sockets are both either send or
                   receive sockets;  the operation was suppressed
              44,  By operator command, all Network operations were
                   terminated;  the socket will be closed
              60,  An NCP control transmission error occured;  the
                   operation was suppressed
             252,  The specified time limit was exceeded;  the operation
                   was initiated but not completed

     (B)  LISTEN

          This operation is a request for notification of any connection
          attempt  directed  toward  the  specified  local  socket.  The
          subprogram waits until such a call is received, at which  time
          the  calling  process'  socket  identifier  is returned to the
          calling program.   This  operation  is  valid  only  when  the
          designated  local  socket is in the closed state.  The calling
          sequence is as follows:

               CALL @OPEN(cmpcd, time,lclsck,ws);

          where

               'cmpcd' is the completion code variable to be associated
                    with the local socket.
               'time' is the length of time the subprogram is to wait
                    for the completion of the operation.
               'lclsck' is the socket identifier of the local socket.
               'ws' is a workspace which, if the operation is
                    successful, will contain the socket identifier of
                    the calling socket, and will become associated with



                                                                [Page 4]

RFC 120                 NETWORK PL1 SUBPROGRAMS


                    the local socket for the life of the connection.
                    'ws' has the same attributes as a socket identifier.

          The  following  completion  codes  are   possible   for   this
          operation:

               0,  The operation was successful and a call has been
                   received
               4,  The specified completion code variable is already
                   assigned to a socket;  the operation was suppressed
               8,  The specified local socket is not in the closed
                   state;  the operation was suppressed
              12,  Local resources are insufficient to support another
                   connection;  the operation was suppressed
              16,  The specified local socket is not local to UCSB;  the
                   operation was suppressed
              20,  An addressing or protection exception was encountered
                   with respect to the specified workspace;  the
                   operation was suppressed
              44,  By operator command, all Network operations were
                   terminated;  the socket will be closed
             252,  The specified time limit was exceeded;  the operation
                   was initiated but not completed

     (C)  ACCEPT

          This operation accepts  connection  with  the  foreign  socket
          whose  call  caused successful completion of a previous LISTEN
          operation by the specified local socket.  After completion  of
          this  operation,  data may be transferred to or from the local
          socket, depending on its gender.  This operation is valid only
          when  the  last  operation  referencing the local socket was a
          LISTEN  operation.   The  subprogram  will  wait   until   the
          operation is completed.

          The calling sequence is as follows:

               CALL @OPEN(cmpcd, time);

          where

               'cmpcd' is the completion code variable associated with
                    the local socket by a previous LISTEN operation.
                'time' is the length of time the subprogram is to wait
                    for the completion of the operation.

          The  following  completion  codes  are   possible   for   this
          operation:



                                                                [Page 5]

RFC 120                 NETWORK PL1 SUBPROGRAMS


               0,  The operation was successful, and the connection is
                   established
               4,  The specified local socket is in the closed state
                   (the NCP may have received an abort notification from
                   the foreign process);  the operation was suppressed
               8,  The previous operation specifying the designated
                   local socket was not a LISTEN;  the operation was
                   suppressed
              12,  All communication paths to the specified foreign site
                   are in use;  the socket has been returned to the
                   closed state
             252,  The specified time limit was exceeded;  the operation
                   was initiated but not completed