Data

String, Byte array, or DartStream Object. Bytes from the network are copied into this variable.

You can use this method only when the State property is tcpConnected or tcpClosing; otherwise, a ptNotConnected error is generated. When the State is tcpClosing, you can use the Receive, Fill, or Search methods to flush the buffer and cause the State property to change to tcpClosed.

Data can be specified as a dimensioned or undimensioned String, Byte array, or DartStream Object:

• A String of length greater than 0 or a dimensioned Byte array of length greater than 0 indicates that the existing contents should be overwritten with received bytes. The String or Byte array is not resized. When receiving data, the actual amount transferred never exceeds the size of the Data parameter, but the Count returned may indicate that only part of the String or Byte array contains received bytes. Note Count should always be checked because the size of the Data parameter does not indicate how many bytes or characters were actually received.
• A String of length 0 or an un-dimensioned Byte array is resized to the length of the available data before received bytes are copied into it. The returned Count matches the new size of the String or Byte array. If the same Data variable is used on a successive call, the variable is considered to be of size greater than 0 and is not resized.

When Data is specified as a String, all bytes are converted to 16-bit Unicode characters according to the default ANSI code page specified on the system. If the code page is not ASCII, multi-byte characters convert to single Unicode characters. This is not as efficient as receiving into a large Byte array. The most efficient transfer is possible when a large global Byte array is allocated once, and all network data is repeatedly read into the same array (a single memory transfer takes place directly from the system buffers into the global Byte array allocated in the user's application).

If Timeout is greater than 0, the method completes without error if at least 1 byte is received (a positive Count is returned) or the remote host closes the connection (a 0 Count is returned). A ptTimeout error is generated if at least 1 byte cannot be received within the Timeout period and the connection is still ptConnected. If Timeout is 0, then Count indicates the length of the actual data received, and may be 0 if no data was immediately available (this does not indicate a closed connection). If a ptTimeout error is generated, the session is aborted, and all system resources are released.

The remote host can close the connection at any time. If the remote host closes the connection and there is still data in the system to receive, then the State property changes to ptClosing to indicate this condition. You can safely use this method to receive data when the State is either ptConnected or ptClosing. You may call this method with Timeout greater than 0 and the remote host closes the connection while you are waiting for Data. In this case no error is generated, but a 0 Count is returned and State will be ptClosed when the method returns.

The Blocked property returns True while performing a blocking method (Timeout is greater than 0).

Use the Send method with Urgent set to True to send Out-of-band data. PowerTCP uses the SO_OOBINLINE socket option to always receive out-of-band data "in-line". In other words, all out-of-band data is received as normal data. It is up the user to correctly process this data.

Note Some environments, such as JavaScript, do not support the passing of parameters by reference. Consequently, such methods as Receive cannot be used by passing in a String. You can use the DartStream Object to circumvent this limitation.

Error Codes

This method may generate the following error code (refer to ErrorConstants for a complete list of error codes):

• ptAbort
• ptBlocked
• ptConnectionAborted
• ptConnectionReset
• ptInvalidParam1 (Data is not a String or Byte array)
• ptNetworkDown
• ptNetworkReset
• ptNotConnected
• ptTimeout

SecureTcp Object  | SecureTcp Members