BLib.Net - Network Communication Library Routines ================================================= File: Net - Update: 1.02 Author: J.G.Harston - Date: 12-Feb-1992 The Net library provides network communication functions to allow a program to communicate with other machines via a connected network. The physical network link or links used by the transmitted messages is irrelevant, as long as the link is accessed through the standard Acorn Networking system calls. Requirements and Dependancies ============================= The library requires a global control block of at least 32 bytes in length to be accessible with X% holding the address of this block, and Y% holding X% DIV 256. This can easily be set up with DIM ctrl% 31 near the start of the program and X%=ctrl%:Y%=X%DIV256 at the begining of the major program code and at the start of any main program loop. Routine Summary =============== FNNet_Tx() - transmit data with default timeouts FNNet_TxCount() - transmit data FNNet_RxOpen() - open a receive block FNNet_Rx() - poll an open receive block FNNet_RxRead - read and close an open receive block PROCNet_RxKill() - abandon an open receive block FNNet_Err() - translate network error FNNet_Stn() - format station number FNNet_StnFixed() - format station number FNNet_Info() - read and write various network information Definitions =========== Stn% - station number, formed by station+256*network for Econet Ctrl% - one-byte control byte, must have bit seven set Port% - one-byte port number to communicate on Addr% - start address of data to use Len% - length of any data to use RAddr% - remote address for some immediate operations Try% - maximum number of retries to attempt Delay% - delay between retries to wait, in centiseconds Transmission ============ DEFFNNet_Tx(Stn%,Ctrl%,Port%,Addr%,Len%,RAddr%) DEFFNNet_TxCount(Stn%,Ctrl%,Port%,Addr%,Len%,RAddr%,Try%,Delay%) The functions Net_Tx() and Net_TxCount() transmit a quantity of data over the network to the specified station. Net_TxCount() allows the count and delay between retries to be specified, whereas Net_Tx() uses the default of 10 retries with a 50cs delay between. The functions return the result of the transmission. This will be 0 for all ok, or &4x for a transmission error. Error codes returned are: &40 Line jammed &41 Net error &42 Not listening &43 No clock &44 Bad Tx block The function Net_Err() will convert this value into a string for display. Net_Err() returns a null string if the passed value is zero, otherwise a string containing the specified error message. Broadcasts ---------- If station &FFFF is specified, a global broadcast will be sent. Only 8 bytes can be sent in a global broadcast. This is the data at the specified address, which is transfered into the control block by Net_Tx(). Broadcasts return immediately as there is no way of knowing if the destination machines have received them, as more than one machine may be receptive, so you should just call Net_Tx() and ignore the result. Immediates ---------- When Port% is zero, an immediate operation is performed. This does not require an open receive block on the destination machine as the required action is performed by the network firmware. Some immediates return immediately, and so Net_TxCount() with Try% and Delay% set to zero can be used. Some immediates use the RAddr% parameter. The following is a list of currently defined immediate operations and the values to pass to Net_Tx() or Net_TxCount(): Peek Net_Tx(Stn%,&81,0,MyAddr, MyLen, RemoteAddr) Poke Net_Tx(Stn%,&82,0,MyAddr, MyLen, RemoteAddr) Remote JSR Net_Tx(Stn%,&83,0,ArgAddr,ArgLen,RemoteCallDest) Remote PROC Net_Tx(Stn%,&84,0,ArgAddr,ArgLen,ProcNumber) Remote OS PROC Net_Tx(Stn%,&85,0,ArgAddr,ArgLen,OSProcNumber) Halt Net_Tx(Stn%,&86,0,0, 0, 0) Continue Net_Tx(Stn%,&87,0,0, 0, 0) Machine Peek Net_Tx(Stn%,&88,0,ArgAddr,4, 0) Read Registers Net_Tx(Stn%,&89,0,ArgAddr,80, 0) Read Registers is only supported between ARM-based machines. Reception ========= DEFFNNet_RxOpen(Stn%,Port%,Addr%,Len%) The function Net_RxOpen() opens a receive block to recieve data from a network transmission on the specified port from the specified station. Up to Len% bytes is received into memory pointed to by Addr%. Net_RxOpen() returns the handle of the opened receive block, or zero if there is insufficient space to create any more. If Stn% is 0, then transmissions from any station are received. If Port% is 0, then transmissions on any port are received. Polling Reception ----------------- DEFFNNet_Rx(RxNum%) Net_Rx() returns TRUE if a reception has occured in the receive block specified by RxNum%. Once a reception has occured, it can be read using Net_RxRead(). Reading a Receive Block ----------------------- DEFFNNet_RxRead(RxNum%) Net_RxRead() deletes the specified receive block and updates the control block with the station and port actually received on. The number of bytes received is returned and the control is updated to hold the station and port actually received from: X%?1 - Control byte X%?2 - Port X%!3 - Station received from Abandoning a Receive Block -------------------------- DEFPROCNet_RxKill(RxNum%) Net_RxKill() abandons and deletes a receive block. Networking Support Functions ============================ Various support functions are provided that convert values into human- readable strings. Communication Results --------------------- DEFFNNet_Err(A%) Net_Err() returns the english error string corresponding to the network status code. If A% is 0, a null string is returned, otherwise one of the following strings is returned: &40 Line jammed &41 Net error &42 Not listening &43 No clock &44 Bad Tx block &45 No reply Station number display ---------------------- DEFFNNet_Stn(A%) DEFFNNet_StnFixed(A%) Net_StnFixed() and Net_Stn() returns a string containing the dotted network and station number. If the network is 0, then Net_Stn() returns the three-digit string stn. Net_StnFixed() always returns the full seven-character string net.stn Station number input -------------------- DEFFNNet_StnNum(A$) Net_StnNum() converts the dotted network/station string into a station number. Network Information =================== DEFFNNet_Info(function%, data%) The Net_Info() function reads and sets various network filing system information, such as the file or printer server station and the client station number. Read file server station station%=FNNet_Info(0,0) Set file server station dummy%=FNNet_Info(1,station%) Read printer server station station%=FNNet_Info(2,0) Set printer server station dummy%=FNNet_Info(3,station%) Read protection mask mask%=FNNet_Info(4,0) Set protection mask dummy%=FNNet_Info(5,mask%) Read context context%=FNNet_Info(6,0) Set context dummy%=FNNet_Info(7,context%) Read station number station%=FNNet_Info(8,0) Read arguments args%=FNNet_Info(9,0) Read error info error%=FNNet_Info(10,0) Read channel error occured on channel%=FNNet_Info(11,0) Read printer server name A%=FNNet_Info(12,0):X%?7=13:name$=$(X%+1) Set printer server name $(X%+1)=name$:A%=FNNet_Info(13,X%!1) Read space in NetPrint buffer space%=FNNet_Info(14,0) Read file server retries retries%=FNNet_Info(15,0) Write file server retries dummy%=FNNet_Info(16,retries%) Get network number thisnet%=FNNet_Info(17,0)