ReceiveAsynchronous (Socket function)

Receive zero or more bytes on this socket (Socket class)

[Introduced in Sirius Mods 7.9]

Unlike the Receive and ReceiveAndParse methods, if ReceiveAsynchronous receives fewer than the requested number of bytes, it will return, either immediately or after a timeout, according to your specification.

Syntax

%bytesReceived = socket:ReceiveAsynchronous( [Target=] string, - [[MaxBytes=] number], - [[Options=] string], - [Wait= boolean])

Syntax terms

%BytesReceived	A numeric string to contain the count of the number of bytes received, or to contain 0, if the operation cannot be performed.
socket	A variable or an expression that is a reference to a Socket object.
Target	This name allowed parameter is a %variable or an IMAGE item that is the target of the receive operation. It is referred to as the "receive target." Since you may request that some bytes from the socket stream be discarded, the length of the string stored in this target may be less than the %BytesReceived value.
MaxBytes	This optional, name allowed, parameter is the maximum number of bytes of data to receive, less the length of the separator string. This optional argument defaults to 0, which means limit the received data (less separator) to the declared length of the receive target. If the MaxBytes argument value is 0, and the Target argument is a Longstring, the received data is limited to 2,147,483,647 bytes. The MaxBytes argument value must not exceed 2,147,483,647. MaxBytes may have the special value -1 to indicate there is no limit to the number of bytes received.
Options	This optional, name allowed, parameter is an option string, which can contain either of the following: BINARY Regardless of the socket's BINARY or CHAR port parameter, data is not translated when saved in the receive target. The received string can be translated later in the program using the TranIn method. CHAR Regardless of the socket's BINARY or CHAR parameter, data is translated when saved in the receive target. The translation is specified by the input table defined by the socket's XTAB port parameter. PRSTOK [AMBIG|]hexstr[|hexstr]... A set of parse tokens that override the current parse tokens on the socket. Whether it is set on the port definition or by the Set or ReceiveAndParse methods, PRSTOK must not be NONE, or ReceiveAndParse will fail.
Wait	This name allowed, optional, Boolean value indicates whether the method should wait until the timeout time before returning, if MaxBytes bytes are not immediately available. If Wait=True and the request for MaxBytes times out, the conection is not closed, and some number of bytes between 0 and MaxBytes-1 is returned. If Wait=False, ReceiveAsynchronous returns immediately with whatever number of input bytes are available.

Usage notes

• If ReceiveAsynchronous returns a 0 indicating that no bytes were returned, it means either of these:
  • No bytes were available at the instant the method was called or after the timeout time.
  • No data will ever be returned on the socket, because we a FIN was returned from the other side.

  A returned 0 is not ambiguous with the Receive and ReceiveAndParse methods, because they only return a 0 when a FIN was received. But if a 0 is returned from ReceiveAsynchronous, you must determine if it is caused by a FIN or not: If ReceiveAsynchronous returns a 0 because a FIN was received, and you call it (or Receive) again, you will get a request cancellation. So when ReceiveAsynchronous returns a 0, call the ReceivedFin method to check if a FIN has been received — unless you "know" the other side will never close the connection nicely (with a FIN) and that the only way the connection can be closed is with a reset.

See also

• Receive
• ReceiveAndParse

Socket class	List of Socket methods	Socket methods syntax
Notation conventions for methods