Search Method

Description

Receive data up to and including a terminating sequence. The data stream is searched for the specified Token, and the specified string, byte array, or DartStream object is filled with the data stream up to and including the specified Token.

This method is useful for processing variable-length records or lines that are defined by known delimiter strings.

Syntax

Visual Basic
Public Function Search( _ ByRef Data As Variant, _ ByRef Token As Variant _ ) As Long

Parameters

Data: String, Byte array, or DartStream object. Received bytes are copied into this variable.
Token: String, Byte array, or DartStrings object. If Token is a string or byte array Data captures all bytes up to and including Token. If Token is a DartStrings object, each string is checked and Data is copied when the first match occurs.

Return Value

The number of Unicode characters or bytes copied into Data.

Remarks

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

If the specified Token is found, then the string, byte array, or DartStream object is always resized to the length needed to hold all the data received, up to and including the token. Count returns the length of the string or size of the byte array. When using a DartStream object, Count returns the Size of the DartStream minus the Position of the DartStream when it was passed in. Be aware that if you keep passing a DartStream, it will keep growing in Size. To keep this from happening, the DartStream object Clear method should be used before passing it in. If the specified token is not found, then the string or byte array is not altered in any way, and Count is 0. When Data is a string, all bytes are converted to 16-bit Unicode characters according to the default ANSI code page installed on the system (this is not as efficient as receiving into a Byte array). If the code page is not ASCII, multi-byte characters may convert to single Unicode characters. It is possible that ReceiveBufferCount will indicate that data is available while this method fails to return data because Token is not seen.

Token defines a terminating character sequence. Token must be an initialized string, byte array, or DartStrings object. You may specify Token as a byte array for those environments that do not allow strings with embedded Null characters.

If Timeout is 0, then available data is searched for the terminating Token, and the method immediately returns a Count value of either 0 (Token was not found) or the number of bytes returned. If Timeout is greater than 0, the method blocks and waits for the Token, and no error is generated if the Token arrives within the timeout period. If the timeout period is exceeded, a ptTimeout error is generated, the session is aborted, and all system resources are released.

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

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 (see the ReadString method Remarks section for a JavaScript sample).

Error Codes
The Search method may generate the following error codes (refer to the ErrorConstants topic for a complete list of error codes):

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

Example

Search Method Example (Visual Basic)

Function FetchNextLine() As String
On Error GoTo OnError ' use intrinsic error handling
	Dim Line As String
	Dim LineLength As Long
	' Get the next line from server, which ends with a carriage-return, line-feed
	Tcp1.Timeout = 1000
	LineLength = Tcp1.Search(Line, vbCrLf)
	FetchNextLine = Line
	' if no error generated, Line is guaranteed to have the next line
	Exit Sub
OnError: ' Any error jumps here
	Debug.Print "Error #" + CStr(Err.Number) + ": " + Err.Description
End Sub