Trailing-Edge - PDP-10 Archives - BB-H348C-RM_1982 - swskit-v21/documentation/user-programming.mem
There are no other files named user-programming.mem in the archive.

      |d|i|g|i|t|a|l|                   INTEROFFICE MEMORANDUM

      TO: DECnet Users                  DATE: 26-Feb-80
                                        FROM: NCSS
                                        EXT: HOTLINE (5911)
                                        LOC/MAIL STOP: MR1-2/H22

      SUBJ:  Writing DECnet Applications

      This memo gives the general  order  of  JSYS's  to  be  used  when
      writing  simple  DECnet  applications.   As  examples,  two simple
      programs which communicate with each other over a logical link are
      included.   This memo also includes some common areas on confusion
      to watch out for when writing  DECnet  programs,  as  well  as  an
      explanation of the link status bits returned by the MTOPR JSYS.


      1.  GTJFN of DCN:  specification.(S1)

      2.  OPENF to establish  the  link.   The  OPENF  sends  a  connect
          initiate;   success  of  the  OPENF  does  not  mean  link  is

      3.  Use interrupt system or use .MORLS function of MTOPR  to  read
          link status to wait for connect confirm or reject.(S3)

      4.  Transfer data with SOUT, BOUT, SIN, SINR, BIN, or SOUTR  until

      5.  Use CLOSF to break the logical link.  Note that  if  the  link
          was  aborted, data transfer was not guaranteed.  Consequently,
          the CLOSF will notify you of this possibility by failing.   To
          close  the  link  if this should occur, you must first set the
          CZ%ABT bit and then execute another CLOSF.(S5)

      Here's some sample code.

      ;Step S1 - get JFN for network connection

               MOVX    T1,GJ%SHT
                                                                  Page 2

               HRROI   T2,[ASCIZ/DCN:node-TASK-TARGET.SOURCE/]
                 ERJMP NOGOOD          ;Failed, maybe out of resources
               MOVEM   T1,OURJFN       ;Successful, save our JFN

      ;Step S2 - OPENF to create the Logical Link

               MOVX    T2,<FLD(^D7,OF%BSZ)+OF%WR+OF%RD>
               OPENF                   ;Open for read and write
                 ERJMP NOGOOD          ;Sorry...

      ;Step S3 - Wait for network connect to succeed or fail

      S3:      MOVX    T1,^D1000       ;Wait before checking status
               MOVE T1,OURJFN          ;Go check link status
               MOVX    T2,.MORLS
                 ERJMP NOGOOD
               TXNE    T3,MO%CON       ;Are we connected?
                 JRST  S4              ;Yes, go on to step 4
               TXNE    T3,MO%WCC       ;No, are we still waiting?
                 JRST  S3              ;Yes, wait some more
      ;If we get here, target process or network has rejected
      ;  the connect attempt.
               JRST    NOGOOD          ;We lose

      ;Step S4 -- Send data to target task

      S4:      MOVE    T1,OURJFN
               HRROI   T2,[ASCIZ/ HELLO TARGET!
               SETZM   T3
                 ERJMP NOGOOD          ;Network went away

      ;Step S5 - CLOSF to disconnect logical link

               MOVE    T1,OURJFN
                 ERJMP [ MOVE  T1,OURJFN ;Failed, use CZ%ABT
                         TXO   T1,CZ%ABT ;  to close link
                           JFCL        ;Don't care if it fails
                         JRST  .+1]
               HALTF                   ;Stop source task


      1.  GTJFN of SRV:  specification.(T1)
                                                                  Page 3

      2.  OPENF to become part of network.(T2)

      3.  Do IO JSYSs immediately to implicitly  accept  connections  or
          set up interrupt system.  This is done with SIR, AIC, EIR, and
          MTOPR (.MOACN) in that order!  If  the  MTOPR  to  assign  the
          channels  is not done last, interrupts may be lost.  Then wait
          for interrupts.(T3)

      4.  Process interrupts on the connect channel.(T4)

      5.  Process interrupts on the data channel.  If input  is  waiting
          (check with SIBE), read all of it.  You must always do another
          SIBE before the DEBRK, as data  that  arrives  while  you  are
          processing  an  interrupt will not generate another interrupt!
          If no data is waiting,  but  yet  you  have  received  a  data
          interrupt, there may be a disconnect event pending (or you may
          have received a spurious interrupt).  Check to see if the link
          is  still  connected (use .MORLS of MTOPR again, and check for
          MO%CON).  If it is, go back to your wait state;  if it is not,
          go to step T6.(T5)

      6.  The link is disconnected.  CLOSF the JFN and either  halt  the
          program or go to step 1.(T6)

      Two words of caution:

      1.  See item 5 from the previous section.  The same caution  holds
          true for target programs.

      2.  If an interrupt occurs while the mainline code is performing a
          SINR/SOUTR, and your program wishes to do something other than
          continue the SINR/SOUTR, you must set the user mode bit in the
          PC before you dismis the interrupt.  Also note that if you set
          the user mode bit and interrupt a SOUTR, register  3  reflects
          how  much  data was sent and the SOUTR can be started again to
          continue the transfer of the record.

      Here is a sample target program.

      START:   RESET

      ;T1 - Get JFN for network connection

               MOVX    T1,GJ%SHT
               HRROI   T2,[ASCIZ/SRV:.TARGET/]
                ERJMP  NOGOOD          ;Failed, out of resources maybe
               MOVEM   T1,OURJFN

      ;T2 - OPENF to make us available to the network

               MOVX    T2,<FLD(^D7,OF%BSZ)+OF%WR+OF%RD>
               OPENF                   ;Open for read/write
                                                                  Page 4

                ERJMP  NOGOOD          ;Failed

      ;T3 - Setup interrupt system for network JFN

               MOVX    T1,.FHSLF       ;Setup interrupt system first
               MOVE    T2,[LEVTAB,,CHNTAB]
               SIR                     ;Set interrupt system tables
               MOVX    T2,3B1          ;Enable channels 0 and 1
               MOVE    T1,OURJFN       ;Setup connect and data interrupts
               MOVEI   T2,.MOACN
               MOVX    T3,<FLD(0,MO%CDN)+FLD(1,MO%DAV)+FLD(.MONCI,MO%INA)>

      PAUSE:   WAIT

      LEVTAB:  PC
      CHNTAB:  1,,HELLO                ;On connect go to HELLO
               1,,READIT               ;On data interrupt try to read it

      PC:      BLOCK   1               ;Level 1 PC save location

      ;T4 - Process interrupt on Connect channel

      HELLO:   MOVE    T1,OURJFN
               MOVX    T2,.MOCC
               SETZB   T3,T4           ;No optional data
                ERJMP  NOGOOD          ;Something blew up
               DEBRK                   ;Done, wait some more

      ;T5 - Process interrupt on Data channel

      READIT:  MOVE    T1,OURJFN       ;Any data?
                JRST   READ            ;Yes, process it
               MOVX    T2,.MORLS       ;No, make sure link still connected
                ERJMP  NOGOOD          ;An error here is unlikely, but...
               TXNN    T3,MO%CON       ;Link still connected?
                JRST   T6              ;No, process link down
               DEBRK                   ;Yes, wait for another interrupt

      READ:    HRROI   T2,BUFFER       ;Put data into buffer
               MOVNI   T3,^D1000       ; - size of buffer
               SINR                    ;Read the data
                ERJMP  NOGOOD          ; Shouldn't happen
               SETZM   T1              ;Store a zero byte
               IDPB    T1,T2
               HRROI   T1,BUFFER
               PSOUT                   ;Output the message
               JRST    READIT          ;Process more input
                                                                  Page 5

      ;T6 - Process disconnect on link

      T6:      MOVE    T1,OURJFN       ;Close our JFN
                ERJMP  [ MOVE  T1,OURJFN ;Try close with abort
                         TXO   T1,CZ%ABT
                          JFCL         ;Who cares
                         JRST  .+1]
               MOVX    T1,1B5          ;Force user mode on
               HRRI    T1,START        ;Start the program over
               MOVEM   T1,PC           ;Store this new PC
               DEBRK                   ;Return to START


      1.  Data channel interrupts require processing of data, disconnect
          events,  or  NOTHING!   An  interrupt on a data channel can be
          indicative of one of four states:

          A) Data available, disconnect event (disconnect initiate)
          B) Data available, no disconnect event (so-called normal case)
          C) No data, disconnect event (disconnect initiate)
          D) No data, no disconnect event (spurious interrupt)

          All four states must be handled in the user  code.   Use  SIBE
          and  .MORLS  function  of  MTOPR  freely,  but as shown in the
          example above.

      2.  Processing of disconnect events require  special  handling  if
          interrupted out of SINR or SOUTR on the same link.

          If you have enabled a channel for data interrupts, a  SINR  or
          SOUTR will block forever if it is interrupted and a disconnect
          initiate has arrived.  You cannot simply dismiss the interrupt
          with  DEBRK,  because the SOUTR or SINR will not fail, it will
          hang.  You must force  the  SOUTR(SINR)  to  be  done  by  (1)
          Setting  the  user mode bit (bit 5) of the return PC word, and
          (2) Modifying the PC word's  return  address.   You  can  then
          safely dismiss the interrupt.

          A user program can determine if it was interrupted out of user
          code or monitor code by examining bit 5 of the PC word.  If it
          is on, it was user code, if off, monitor code.   (The  address
          indicated by the PC word is always in user code, however.)

          If you wind up modifying the PC word, you probably  will  also
          want to set some other flag so that your program knows that an
          abnormal branch has occurred.  It may also be useful to  check
          T3 for the count of bytes remaining after the SOUTR.
                                                                  Page 6

      3.  Connect channel interrupts mean different events for DCN:  and
          SRV:  tasks.

          A source (DCN:) task that has executed an OPENF on the network
          JFN  has implicitly performed a connect initiate and is in the
          connect initiate sent state (CIS).  Receipt of an event on the
          connect  channel  will  change  the  state  to  RUN if it is a
          connect confirm, or to IDLE if it is a connect reject.

          A target (SRV:) task waits in the IDLE state for something  to
          happen.  When it receives an interrupt on the connect channel,
          it goes into connect initiate receive state (CIR).

      4.  A CLOSF on a link that has been aborted requires CZ%ABT to  be
          set  for  the  CLOSF  to succeed.  This was described above in
          step 5 of the source task.

      5.  Only one interrupt message can be sent  over  a  link  at  any
          time.   Attempting  to send another before the current one has
          been acked by the remote node will result in a failure of  the
          MTOPR   .MOSIM   function.    Interrupt   messages   are   for
          extraordinary events.  This should not pose any undue hardship
          on your coding.

      6.  BPASSWORD and BDATA only allow 13 bytes of information  to  be
          included instead of the 16 bytes allowed for PASSWORD or DATA.
          This is not a new feature, just a correction of  the  existing
          documentation.  The code has always worked this way.


      The .MORLS function of MTOPR is  invaluable  for  determining  the
      state  of  the  link  at any given time.  Some of the more helpful
      flags to check, who usually checks them (DCN:  or SRV:)  and  what
      they tell you are listed below.

          FLAG    WHO                 WHAT

          MO%CON  DCN:    Set when the connect confirm is received.
                  SRV:    Indicates that the link is connected.

          MO%WCC  DCN:    Set after the  OPENF  (connect  initiate)  and
                          indicates that no connect confirm has yet been
                          returned from the target.

          MO%WFC  SRV:    Indicates that  the  task  is  waiting  for  a
                          connect  initiate message and that the link is
                          in the IDLE state.
                                                                  Page 7

          MO%LWC  DCN:    Indicates that  the  link  was  at  some  time
                          connected, regardless of its current state.

          MO%SYN  Both    Indicates a normally  closed  link.   May  use
                          normal CLOSF to close other end.

          MO%ABT  Both    Indicates an abnormally closed link.  Delivery
                          of  data  being  transferred at time link went
                          away  is  not  guaranteed.   Must  set  CZ%ABT
                          before CLOSF will succeed.

      If  more  detailed  information  regarding  the  link  status   is
      required, you must look at the running monitor.  The procedure for
      doing this is described elsewhere in this SWSkit.