ReceiveAsynchronous (Socket function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
Line 15: Line 15:
<tr><th><var>MaxBytes</var></th>
<tr><th><var>MaxBytes</var></th>
<td>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.
<td>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 <var class="term">maxrecvp</var> is 0 and <var class="term">target</var> is a <var>Longstring</var>, the received data is limited to 2,147,483,647 bytes. The <var>MaxBytes</var> argument value must not exceed 2,147,483,647.
<p>If the <var>MaxBytes</var> argument value is 0, and the <var>Target</var> argument is a <var>Longstring</var>, the received data is limited to 2,147,483,647 bytes. The <var>MaxBytes</var> argument value must not exceed 2,147,483,647.
<var>MaxBytes</var> may have the special value <code>-1</code> to indicate there is no limit to the number of bytes received.
<var>MaxBytes</var> may have the special value <code>-1</code> to indicate there is no limit to the number of bytes received.
</td></tr>
</p></td></tr>


<tr><th><var>Options</var></th>
<tr><th><var>Options</var></th>
Line 26: Line 26:
<tr><th><var>CHAR</var> </th><td>Regardless of the socket's <var>BINARY</var> or <var>CHAR</var> parameter, data '''is translated''' when saved in the receive target. The translation is specified by the input table defined by the socket's <var>[[XTAB (JANUS DEFINE parameter)|XTAB]]</var> port parameter.
<tr><th><var>CHAR</var> </th><td>Regardless of the socket's <var>BINARY</var> or <var>CHAR</var> parameter, data '''is translated''' when saved in the receive target. The translation is specified by the input table defined by the socket's <var>[[XTAB (JANUS DEFINE parameter)|XTAB]]</var> port parameter.
</td></tr>
</td></tr>
<tr><th>PRSTOK [AMBIG|]<i>hexstr</i>[|<i>hexstr</i>]...
<tr><th nowrap><var>PRSTOK [AMBIG|]</var>hexstr<var>[|</var>hexstr<var>]...</var>
</th><td>A set of parse tokens that override the current parse tokens on the socket.
</th><td>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 <var>[[Set (Socket function)|Set]]</var> or <var>ReceiveAndParse</var> methods, <var>PRSTOK</var> must '''not''' be <code>NONE</code> or <var>ReceiveAndParse</var> will fail.
Whether it is set on the port definition or by the <var>[[Set (Socket function)|Set]]</var> or <var>ReceiveAndParse</var> methods, <var>PRSTOK</var> must '''not''' be <code>NONE</code>, or <var>ReceiveAndParse</var> will fail.
</td></tr></table>
</td></tr></table>


<tr><th><var>Wait</var></th>
<tr><th><var>Wait</var></th>
<td><var>Boolean</var> value
<td>This name allowed, optional, <var>[[Boolean enumeration|Boolean]]</var> value indicates whether the method should wait until the timeout time before returning, if <var>MaxBytes</var> bytes are not immediately available.  
 
<p>
that indicates whether it should wait the timeout time before returning if MaxBytes    
If <code>Wait=True</code> and the request for <var>MaxBytes</var> times out, the conection is not closed, and some number of bytes between 0 and <code>MaxBytes-1</code> is returned. If <code>Wait=False</code>, <var>ReceiveAsynchronous</var> returns  immediately with whatever number of input bytes are available. </p></td></tr>
bytes weren't immediately available. Note that 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
would be returned. If Wait=False, ReceiveAsynchronous will returned immediately with  
whatever number of input bytes are available.                                          
</td></tr>
</table>
</table>


Line 53: Line 48:
</ul>
</ul>


A returned o is not ambiguous with the <var>Receive</var> and       
A returned o is not ambiguous with the <var>[[Receive (Socket function)|Receive]]</var> and       
<var>ReceiveAndParse</var> methods, because they only return a 0 when a FIN was received.  
<var>[[ReceiveAndParse (Socket function)|ReceiveAndParse]]</var> methods, because they only return a 0 when a FIN was received. But if a 0 is returned from <var>ReceiveAsynchronous</var>, you must determine if it is   
But if a 0 is returned from <var>ReceiveAsynchronous</var>, you must determine if it is   
caused by a FIN or not: If <var>ReceiveAsynchronous</var> returns a 0 because a FIN was received, and you call it     
caused by a FIN or not: If <var>ReceiveAsynchronous</var> returns a 0 because a FIN was received, and you call it     
(or <var>Receive</var>) again, you will get a request cancellation. So when <var>ReceiveAsynchronous</var>     
(or <var>Receive</var>) again, you will get a request cancellation. So when <var>ReceiveAsynchronous</var>     

Revision as of 21:52, 8 June 2012

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

[Introduced in Sirius Mods 7.9]


Syntax

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

Syntax terms

%BytesReceivednumber
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 o 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