TCPReceive

Command group Flag affected Reversible Execute on client Platform(s)
External commands YES NO NO All

Syntax

TCPReceive (socket,buffer[,maxbytes]) Returns received-byte-count

Description

Note: The flag is set according to whether Omnis was able to make a call to this external command.

This Web command is multi-threaded, allowing another thread to execute in the multi-threaded server while it runs. Note that the same socket cannot safely be used concurrently by more than one thread.

TCPReceive receives data on a connected socket.

Socket is a long integer field containing the socket number of a connected socket.

Buffer is a character or binary field into which TCPReceive places the received data. If the field is character, then the response must be encoded in UTF-8; in this case, TCPReceive converts the received data from UTF-8 to character.

Maxbytes is an optional parameter which indicates the maximum number of bytes to be received. If you omit this parameter the command receives available data with no practical limit.

TCPReceive receives data into the buffer, and then returns the number of received bytes to the long integer Received-byte-count. If an error occurs, TCPReceive returns a negative error code. Note that zero can be returned to Received-byte-count when graceful closure of the connection is initiated by the remote application, and there is no more data to receive. See TCPClose for details.

Notes

Non-blocking sockets return an error code of -10035 if no data is available. Some implementations of socket libraries may have limits on the number of bytes you can receive at one time. Consult the documentation for your installed sockets libraries. You may have to read data in multiple chunks to assemble an entire message. Always check the number of bytes returned to make sure there was no error.

Using TCPReceive to receive into a character field will not produce sensible results if the end of the received data stops part way through a UTF-8 encoded character.

Example

; Listen for incoming connections, if a connection is made get the
; message sent
Calculate iPort as 6000
TCPSocket Returns iSocket
TCPBind (iSocket,iPort) Returns lStatus
TCPListen (iSocket) Returns lStatus
If lStatus=0
  Repeat
    TCPAccept (iSocket) Returns lConnectedSocket
  Until lConnectedSocket>=0
  ; client connected, get the whole message sent
  Calculate lMessage as ''
  Repeat
    Calculate lBuffer as ''
    TCPReceive (iSocket,lBuffer) Returns lMessageLength
    Calculate lMessage as con(lMessage,lBuffer)
  Until lMessageLength<=0
End If
TCPClose (iSocket) Returns lStatus