Release 10.1A: OpenEdge Development:
Programming Interfaces

> ## Reading data on a socket

> To read data from a connected TCP/IP socket, you invoke the `READ( )` method on the corresponding socket object (`SELF:READ( )` within the corresponding `READ-RESPONSE` event procedure). You can invoke this method on a connected socket at any time to read data. However, the method blocks depending on the amount of data available on the socket, the reading mode that you use, and the timeout value (set by the `SO-RCVTIMEO` option of the `SET-SOCKET-OPTION()` method).

> The syntax of the `READ( )` method follows:

> Syntax
>     READ(
>           memptr-expression
>         , position
>         , bytes-to-read
>           [ , mode ]
>         )

> The `READ( )` method transfers data from the socket to the specified `MEMPTR` variable, `memptr-expression`, at the byte position in the `MEMPTR` region specified by the `INTEGER` expression, `position`. Exactly how much data the `READ( )` method blocks to read depends on:

> - The number of bytes specified by the `INTEGER` `bytes-to-read.`

> - The reading mode specified by the `INTEGER` `mode.`

> - The timeout value, set by the `SO-RCVTIMEO` option of the `SET-SOCKET-OPTION()` method.

> ##### Specifying the read mode

> You can specify `mode` using a compiler constant as shown in Table 17–3.

> Table 17–3: Socket reading modes
> Compiler constant | Value | Description
> --- | --- | ---
> `READ-AVAILABLE` | 1 | The `READ( )` method blocks until at least one (1) byte is available on the socket and reads the number of bytes that are available up to a maximum of `bytes-to-read` bytes.
> `READ-EXACT-NUM` | 2 | (Default) The `READ( )` method blocks until `bytes-to-read` bytes are available to read from the socket.

> Thus, you can have the `READ( )` method block until exactly the specified number of bytes are read (the default), or until all available bytes are read up to a maximum number allowed.

> The appropriate reading mode to use depends on your application requirements. Note, however, that if you specify `READ-EXACT-NUM`, the `READ( )` method blocks until it reads the specified number of bytes (no matter how long it takes) or until the socket is disconnected (whatever happens first).

> ##### Specifying the timeout length

> Besides setting the read mode, you can also set the amount of time `READ()` waits before timing out. To do so, use the `SO-RCVTIMEO` option of the `SET-SOCKET-OPTION()` method. If you do not set a timeout value, the default is for `READ()` to wait forever.

> `READ()`’s timeout behavior is affected by the interaction of the read mode and the timeout value, as Table 17–4 illustrates.

> Table 17–4: Effect of read mode and timeout value on READ()’s
> timeout behavior
> Read mode | With a timeout value | Without a timeout value
> --- | --- | ---
>     READ-AVAILABLE
> | Assuming there are no connection failures, `READ()` blocks until one for the following occurs: The timeout expires. There is at least one byte available to read on the socket. | Assuming there are no connection failures, `READ()` blocks until there is at least one byte available to read on the socket.
>     READ-EXACT-NUM
> | Assuming there are no connection failures: If there is any data on the socket, `READ()` blocks until there are `bytes-to-read` bytes available to read on the socket. Else, `READ()` blocks until the timeout expires. | Assuming there are no connection failures, `READ()` blocks until there are `bytes-to-read` bytes available to read on the socket.

> ##### Verifying the number of bytes actually read

> You can verify the number of bytes actually read by the `READ( )` method. The number of bytes read by the last `READ( )` method invoked on a socket object is equal to the value of the `BYTES-READ` attribute invoked on the same socket object.

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