TcpFReceive, TcpReceive, and TcpWaitReceive

The examples in this material illustrate TcpFReceive, TcpReceive, and TcpWaitReceive.

TcpFReceive and TcpReceive are the asynchronous ways of specifying a buffer to receive data for a given connection. Both procedures return to your program immediately. The return code OK means that the request has been accepted. When received data has been placed in your buffer, your program receives a DATAdelivered notification.

TcpWaitReceive is the synchronous interface for receiving data from a TCP connection. TcpWaitReceive does not return to your program until data has been received into your buffer or until an error occurs. Therefore, it is not necessary that TcpWaitReceive receive a notification when data is delivered. The BytesRead parameter is set to the number of bytes received by the data delivery, but if the number is less than 0, the parameter indicates an error.

Figure 1. TcpFReceive example

   procedure TcpFReceive
            (
                 Connection: ConnectionType;
                 Buffer: Address31Type;
                 BytesToRead: integer;
           var   ReturnCode: integer
            );
            external;

Figure 2. TcpReceive example

   procedure TcpReceive
            (
                 Connection: ConnectionType;
                 Buffer: Address31Type;
                 BytesToRead: integer;
        var     ReturnCode: integer
            );
            external;

Figure 3. TcpWaitReceive example

   procedure TcpWaitReceive
            (
                 Connection: ConnectionType;
                 Buffer: Address31Type;
                 BytesToRead: integer;
        var     BytesRead: integer
            );
            external;

Parameter

Description

Connection

The connection number, as returned by TcpOpen or TcpWaitOpen in the Connection field of the StatusInfoType record.

Buffer

The address of the buffer to contain the received data.

BytesToRead

The size of the buffer. TCP/IP usually buffers the incoming data until this many bytes are received. Data is delivered sooner if the sender specified the PushFlag, or if the sender does a TcpClose or equivalent.

Note: The order of TcpFReceive or TcpReceive calls on multiple connections and the order of DATAdelivered notifications among the connections are not necessarily related.

BytesRead

Set when TcpWaitReceive returns. If it is greater than 0, it indicates the number of bytes received into your buffer. If it is less than or equal to 0, it indicates an error. Possible BytesRead values are:

OK+
ABNORMALcondition
FATALerror
TIMEOUTopen+
UNREACHABLEnetwork+
BADlengthARGUMENT
NOsuchCONNECTION
NOTyetBEGUN
NOTyetOPEN
OPENrejected+
RECEIVEstillPENDING
REMOTEreset+
TCPipSHUTDOWN+
REMOTEclose

ReturnCode

Indicates success or failure of call. Possible return values are:

OK
ABNORMALcondition
BADlengthARGUMENT
FATALerror
NOsuchCONNECTION
NOTyetBEGUN
NOTyetOPEN
RECEIVEstillPENDING
REMOTEclose
TCPipSHUTDOWN
INVALIDvirtualADDRESS
SOFTWAREerror

For a description of Pascal return codes, see Table 1.

(TcpWaitReceive):

For BytesRead OK, the function was initiated, but the connection is no longer receiving for an unspecified reason. Your program does not have to issue TcpClose, but the connection is not completely terminated until a NONEXISTENT notification is received for the connection.
For BytesRead REMOTEclose, the foreign host has closed the connection. Your program should respond with TcpClose.
If you receive any of the codes marked with (+), the function was initiated but the connection has now been terminated (see 2). Your program should not issue TcpClose, but the connection is not completely terminated until NONEXISTENT notification is received for the connection.
TcpWaitReceive is intended to be used by programs that manage a single TCP connection. It is not suitable for use by multiple connection servers.
A return code of TCPipSHUTDOWN can be returned either because the connection initiation has failed, or because the connection has been terminated because of shutdown. In either case, your program should not issue any more TCP/IP calls.