TCPReceive

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