| |
The Eloquence Net.DLL provides a simple interface to TCP and UDP client
networking functionality. This includes connecting and disconnecting as
well as sending and receiving data.
Using the Net.DLL
The Net.DLL must be loaded before it can be used in a program:
LOAD DLL Net,1024
This loads the Net.DLL from its default location and establishes
a communication buffer of 1024 bytes.
For details about the Eloquence LOAD DLL statement please refer to the
Eloquence documentation.
The DEL DLL statement may be used to unload the DLL:
DEL DLL Net
The following procedures are available to return information
on the Net.DLL or enable logging.
Programming interface
The Eloquence Net.DLL implements the following procedures:
-
CALL DLL Net("Connect",Server$,Service$)
This connects to a TCP server. Server$ is the host name or IP address
of the server to connect. Service$ is the TCP service name or port number.
The Net.DLL manages one active TCP or UDP connection. If the Net.DLL is
already connected an error 2002 is returned.
Errors: 2002, 2003, 2004, 2005
-
CALL DLL Net("ConnectUDP",Server$,Service$[,Source$])
This connects to an UDP server. Server$ is the host name or IP address
of the server to connect. Service$ is the UDP service name or port number.
Source$ may optionally be used to specify the source service name or port
number. If omitted, an available source port number is allocated by the
operating system.
The Net.DLL manages one active TCP or UDP connection. If the Net.DLL is
already connected an error 2002 is returned.
Errors: 2002, 2003, 2004, 2005
-
CALL DLL Net("Disconnect")
This closes the active connection. If the Net.DLL is not connected
an error 2006 is returned.
Errors: 2006, 2007
-
CALL DLL Net("Send",Buf$)
This transmits the data contained in Buf$ to the server.
Errors: 2006, 2008
-
CALL DLL Net("Recv",Buf$,Cnt,Timeout)
This tries to receive Cnt bytes of data from the server. The received
data is put into Buf$. If Recv returns with an empty Buf$ an end-of-file
condition was encountered.
If Timeout is zero, Recv blocks until Cnt bytes have been received.
If Timeout is a positive nonzero value, Recv blocks until either Cnt bytes
have been received or the specified number of milliseconds have elapsed.
If Timeout is -1 or Recv is used with the UDP protocol then as much data
(up to Cnt bytes) is put into Buf$ as is available without blocking.
If a timeout is encountered an error 2010 is returned.
Errors: 18, 2006, 2009, 2010
Eloquence error codes
In case of a failure, the Net.DLL issues the following
error codes:
| 18 |
Receive buffer is too small.
|
| 2001 |
Log file cannot be opened.
|
| 2002 |
Already conected to server.
|
| 2003 |
Bad service name or port number.
|
| 2004 |
Bad host name or IP address.
|
| 2005 |
Unable to connect to host.
|
| 2006 |
Not connected to server.
|
| 2007 |
Close on socket failed.
|
| 2008 |
Send failed.
|
| 2009 |
Receive failed.
|
| 2010 |
Receive timed out.
|
To obtain details about the cause of the specific failure, a
log file should be configured.
Example programs
The following examples document how the Net.DLL could be used in a program,
including a demonstration of error handling.
The first example illustrates a TCP communication. It connects to a web
server on TCP port 80 and fetches the root document.
This example is installed as TCPDEMO.PROG in the Eloquence
share/example installation subdirectory.
! RE-STORE "TCPDEMO,EXAMPLE"
!
! This is a sample application using the Net.DLL.
! It fetches the index.html page from the server using the
! HTTP protocol and displays the HTML source code on screen.
!
DIM Server$[80],Uri$[80],Buf$[1024]
INTEGER Timeout
ON ERROR GOTO Failed
!
Server$="eloquence.marxmeier.com" ! Server to connect
Uri$="/" ! Document on server
Timeout=10000 ! Receive timeout
!
! LOAD DLL and display version/build date
!
LOAD DLL Net,1024
CALL DLL Net("dll_Revision",Rev$)
CALL DLL Net("dll_Compiled",Build$)
DISP "Loaded Net.DLL v"&Rev$&" ("&Build$&")"
!
! Connect to server
!
DISP "Connecting to "&Server$
CALL DLL Net("Connect",Server$,"80")
!
DISP "Sending request for "&Uri$
Buf$="GET "&Uri$&" HTTP/1.0"&CHR$(10)&CHR$(10)
CALL DLL Net("Send",Buf$)
!
DISP "--- Server Response ---"
LOOP
CALL DLL Net("Recv",Buf$,1024,Timeout)
EXIT IF NOT LEN(Buf$)
LOOP
P=POS(Buf$,CHR$(10))
EXIT IF NOT P
LDISP Buf$[1,P]
Buf$=Buf$[P+1]
END LOOP
IF LEN(Buf$) THEN LDISP Buf$;
END LOOP
DISP "--- End of Data ---"
!
DISP "Disconnecting"
CALL DLL Net("Disconnect")
DISP "Done."
DEL DLL Net
STOP
!
Failed: !
DISP LIN(1);"-- Program failed --"
DISP ERRM$
IF (ERRN<2001) OR (ERRN>2010) THEN
DISP ERRMSG$(ERRN)
ELSE
DATA 2001,"Log file cannot be opened"
DATA 2002,"Already conected to server"
DATA 2003,"Bad service name or port number"
DATA 2004,"Bad host name or ip address"
DATA 2005,"Unable to connect to host"
DATA 2006,"Not connected to server"
DATA 2007,"Close on socket failed"
DATA 2008,"Send failed"
DATA 2009,"Receive failed"
DATA 2010,"Receive timed out"
DATA -1,"Error message not found"
!
RESTORE Failed
REPEAT
READ Err,Buf$
UNTIL (Err=ERRN) OR (Err=-1)
DISP "Net.DLL: "&Buf$
END IF
STOP
The second example illustrates an UDP communication. It uses the UDP echo
protocol (UDP port 7) which responds by simply sending back the exact data
it received.
This example is installed as UDPDEMO.PROG in the Eloquence
share/example installation subdirectory.
! RE-STORE "UDPDEMO,EXAMPLE"
!
! This is a sample application using the Net.DLL.
! It uses the UDP echo protocol (port 7) to send a datagram
! and then expects a reply datagram with the same contents.
! Note: This program won't work unless you change the server
! address below to the address of one of your machines and
! change the (x)inetd configuration so that this machine
! answers to incoming UDP echo requests.
!
DIM Server$[80],Buf$[80]
INTEGER Timeout
ON ERROR GOTO Failed
!
Server$="server.domain.com" ! Server to connect
Timeout=1000 ! Receive timeout
!
! LOAD DLL and display version/build date
!
LOAD DLL Net,1024
CALL DLL Net("dll_Revision",Rev$)
CALL DLL Net("dll_Compiled",Build$)
DISP "Loaded Net.DLL v"&Rev$&" ("&Build$&")"
!
! Connect to server
!
DISP "Connecting to "&Server$
CALL DLL Net("ConnectUDP",Server$,"7")
!
DISP "Sending echo request"
Buf$="A TEST MESSAGE"
CALL DLL Net("Send",Buf$)
!
DISP "Waiting for echo response"
Buf$="WILL BE OVERWRITTEN"
CALL DLL Net("Recv",Buf$,80,Timeout)
DISP "Response: ["&Buf$&"]"
!
DISP "Disconnecting"
CALL DLL Net("Disconnect")
DISP "Done."
DEL DLL Net
STOP
!
Failed: !
DISP LIN(1);"-- Program failed --"
DISP ERRM$
IF (ERRN<2001) OR (ERRN>2010) THEN
DISP ERRMSG$(ERRN)
ELSE
DATA 2001,"Log file cannot be opened"
DATA 2002,"Already conected to server"
DATA 2003,"Bad service name or port number"
DATA 2004,"Bad host name or ip address"
DATA 2005,"Unable to connect to host"
DATA 2006,"Not connected to server"
DATA 2007,"Close on socket failed"
DATA 2008,"Send failed"
DATA 2009,"Receive failed"
DATA 2010,"Receive timed out"
DATA -1,"Error message not found"
!
RESTORE Failed
REPEAT
READ Err,Buf$
UNTIL (Err=ERRN) OR (Err=-1)
DISP "Net.DLL: "&Buf$
END IF
STOP
|
|
