Release 10.1A: OpenEdge Development:
Progress 4GL Reference

> ## READ( ) method

> 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. Table 77 shows the valid values for this parameter. The default value is READ-EXACT-NUM (2).

> Table 77: 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`.

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095