.
Eloquence B.07.10 contact contact

Documentation / The Eloquence Net.DLL

The Eloquence Net.DLL

 
.
  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.

Contents


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


 
 
.
 
 
  Privacy | Webmaster | Terms of use | Impressum Revision:  2006-01-10  
  Copyright © 2006 Marxmeier Software AG