SOCKET_READ Function

Reads data from a socket connection.

Usage

nbytes = SOCKET_READ(connection, data)

Input Parameters

connection—A socket handle (usually returned by either SOCKET_ACCEPT or SOCKET_CONNECT).

Output Parameters

data—A pre-allocated byte array to read into.

Keywords

None.

Returned Value

nbytes—The number of bytes read from the socket or a negative value indicating an error.

Discussion

This function can be used in both client and server programs. If used in a client program, it retrieves data sent (using SOCKET_WRITE) from the server. If used in a server program, it retrieves data sent from the client.

Before calling SOCKET_READ, you must initialize data to be a byte array of sufficient size to hold the data sent from the client. It is up to the programmer to convert the data in the byte array into whatever form the server or client expects to process. PV‑WAVE provides several routines for converting data from one type to another, including BYTE, BYTEORDER, COMPLEX, DOUBLE, FLOAT, LONG, and STRING.

Note:

The SOCKET_READ Function is blocking and does not return until the byte array passed to it is full or a problem occurs with the connection.

Example

In this example, a client program uses SOCKET_READ to retrieve a byte array sent from the server. Note that the STRING function is used to convert the byte array to a string before the data is printed.

PRO CLIENT

   host = 'localhost'

   port = 1500

   socket = SOCKET_CONNECT(host,port)

   IF socket EQ -1 OR socket EQ -2 THEN BEGIN

      PRINT, 'SOCKET_CONNECT failed with return code: ', socket

      RETURN

   ENDIF

   data = BYTARR(15)

   nbytes = SOCKET_READ(socket,data)

   PRINT, 'CLIENT received: ', STRING(data)

   SOCKET_CLOSE, socket

END