READ( ) method (Socket)

Reads data from the socket.

Return type: LOGICAL

Applies to: Socket object handle

Syntax

READ ( buffer , position , bytes-to-read , [ mode ] )

buffer

A MEMPTR expression that identifies where the data which is read from the socket should be stored.

position

An integer expression greater than 0 that indicates the starting byte position within buffer into which information should be written.

bytes-to-read

An integer expression that specifies the number of bytes to be read from the socket.

mode

An optional integer expression that specifies how bytes-to-read should be interpreted. The following table shows the valid values for this parameter. The default value is READ-EXACT-NUM (2).

Valid read modes for the READ( ) method

Compiler constant	Value	Description
READ-AVAILABLE	1	The READ( ) method will block until at least one byte has been read on the socket. It will read up to bytes-to-read bytes.
READ-EXACT-NUM	2	The READ( ) method will block until bytes-to-read bytes have been read from the socket.

READ( ) returns TRUE if the read operation succeeded normally and returns FALSE otherwise. An error can occur if:

• The position parameter is not greater than 0.
• Amount of information requested to read exceeds the size of buffer.
• Reading from the socket fails.

This read statement is a blocking read. If mode is READ-EXACT-NUM, this method returns when it has either read the requested number of bytes from the socket or an error occurs. If mode is READ-AVAILABLE, this method returns when it has read as many bytes as are currently available on the socket, up to the requested number of bytes, or an error occurs.

If the READ( ) method succeeds, the variable buffer contains the data which is read from the socket. It is possible that the socket will not contain the specified number of bytes of data which were requested. The BYTES-READ attribute can be used to determine the number of bytes read from the socket.

This method expects buffer to identify a MEMPTR variable which already has a region of memory associated with it. The developer must call the SET-SIZE statement to allocate memory and associate it with a MEMPTR variable. It is the responsibility of the developer to free this memory, also via the SET-SIZE statement. The READ method will fail if the size of buffer is less than bytes-to-read.