TcpFSend, TcpSend, and TcpWaitSend

The examples in this material illustrate TcpFSend, TcpSend, and TcpWaitSend.

TcpFSend and TcpSend are the asynchronous ways of sending data on a TCP connection. Both procedures return to your program immediately (do not wait under any circumstance).

TcpWaitSend is a simple synchronous method of sending data on a TCP connection. It does not return immediately if the TCPIP address space has insufficient space to accept the data being sent.

In the case of insufficient buffer space, when space becomes available a BUFFERspaceAVAILABLE notification is received.

Your program can issue successive TcpWaitSend calls. Buffer shortage conditions are handled transparently. Errors at this point are most likely unable to recover or are caused by a terminated connection.

If you receive any of the codes listed for Reason in the CONNECTIONstateCHANGED notification, except for OK, the connection was terminated for the indicated reason. Your program should not issue a TcpClose, but the connection is not completely terminated until your program receives a NONEXISTENT notification for the connection.

Figure 1. TcpFSend example

   procedure TcpFSend
            (
                 Connection: ConnectionType;
                 Buffer: Address31Type;
                 BufferLength: integer;
                 PushFlag: Boolean;
                 UrgentFlag: Boolean;
        var     ReturnCode: integer
            );
            external;

Figure 2. TcpSend example

   procedure TcpSend
         (
                 Connection: ConnectionType;
                 Buffer: Address31Type;
                 BufferLength: integer;
                 PushFlag: Boolean;
                 UrgentFlag: Boolean;
            var  ReturnCode: integer
         );
         external;

Figure 3. TcpWaitSend example

   procedure TcpWaitSend
            (
                 Connection: ConnectionType;
                 Buffer: Address31Type;
                 BufferLength: integer;
                 PushFlag: Boolean;
                 UrgentFlag: Boolean;
        var      ReturnCode: 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 containing the data to send.

BufferLength

The size of the buffer.

PushFlag

Set to force the data, and previously queued data, to be sent immediately to the foreign application.

UrgentFlag

Is set to mark the data as urgent. The semantics of urgent data depends on your application.

Note: Use urgent data with caution. If the foreign application follows the Telnet-style use of urgent data, it might flush all urgent data, until a special character sequence is encountered.

ReturnCode

Indicates success or failure of call:

OK
ABNORMALcondition
BADlengthARGUMENT
CANNOTsendDATA
FATALerror
NObufferSPACE (TcpSend and TcpFSend)
NOsuchCONNECTION
NOTyetBEGUN
NOTyetOPEN
TCPipSHUTDOWN
INVALIDvirtualADDRESS
SOFTWAREerror
REMOTEreset

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

Notes:

A successful TcpFSend, TcpSend, and TcpWaitSend means that TCP has received the data to be sent and stored it in its internal buffers. TCP then puts the data in packets and transmits it when the conditions permit.
Data sent in a TcpFSend, TcpSend, or TcpWaitSend request can be split into numerous packets by TCP, or the data can wait in TCP’s buffer space and share a packet with other TcpFSend, TcpSend, or TcpWaitSend requests.
The PushFlag is used to expedite when TCP sends the data.
Setting the PushFlag to FALSE allows TCP to buffer the data and wait until it has enough data to transmit so as to use the transmission line more efficiently. There can be some delay before the foreign host receives the data.

Setting the PushFlag to TRUE instructs TCP to put data into packets and transmit any buffered data from previous Send requests along with the data in the current TcpFSend, TcpSend, or TcpWaitSend request without delay or consideration of transmission line efficiency. A successful send does not imply that the foreign application has actually received the data, only that the data will be sent as soon as possible.
TcpWaitSend is intended for programs that manage a single TCP connection. It is not suitable for use by multiple connection servers.