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.0 ORDER OF OPERATIONS FOR SOURCE TASK
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
established.(S2)
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
done.(S4)
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/]
GTJFN
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
DISMS
MOVE T1,OURJFN ;Go check link status
MOVX T2,.MORLS
MTOPR
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
SOUTR
ERJMP NOGOOD ;Network went away
;Step S5 - CLOSF to disconnect logical link
MOVE T1,OURJFN
CLOSF
ERJMP [ MOVE T1,OURJFN ;Failed, use CZ%ABT
TXO T1,CZ%ABT ; to close link
CLOSF
JFCL ;Don't care if it fails
JRST .+1]
HALTF ;Stop source task
2.0 ORDER OF OPERATIONS FOR TARGET 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/]
GTJFN
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
AIC
EIR
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)>
MTOPR
PAUSE: WAIT
LEVTAB: PC
0
0
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
MTOPR
ERJMP NOGOOD ;Something blew up
DEBRK ;Done, wait some more
;T5 - Process interrupt on Data channel
READIT: MOVE T1,OURJFN ;Any data?
SIBE
JRST READ ;Yes, process it
MOVX T2,.MORLS ;No, make sure link still connected
MTOPR
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
CLOSF
ERJMP [ MOVE T1,OURJFN ;Try close with abort
TXO T1,CZ%ABT
CLOSF
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
3.0 COMMON AREAS OF CONFUSION
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.
4.0 USEFUL FLAGS RETURNED WHEN READING LINK STATUS
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.