Receive (Socket function) - Revision history

JAL: /* Effective values of max_recv and min_recv */

2013-10-21T19:19:42Z

Effective values of max_recv and min_recv

← Older revision		Revision as of 19:19, 21 October 2013
Line 115:		Line 115:
	they are coded as 0, their effective values are shown here:		they are coded as 0, their effective values are shown here:
	<table>		<table>
	<tr><th>Item</th>		<tr class="head"><th>Item</th>
	<th>Value when argument is 0 </th></tr>		<th>Value when argument is 0 </th></tr>
	<tr><th><i>max_recv</i></th>		<tr><th><i>max_recv</i></th>

Dme at 15:10, 11 November 2012

2012-11-11T15:10:21Z

New page

{{Template:Socket:Receive subtitle}}

==Syntax==
{{Template:Socket:Receive syntax}}

===Syntax terms===
<table class="syntaxTable">
<tr><th>%BytesReceived</th>
<td>A numeric string to contain the count of the number of bytes received, or to contain 0, if the operation cannot be performed.</td></tr>

<tr><th>socket</th>
<td>A variable or an expression that is a reference to a <var>Socket</var> object.</td></tr>

<tr><th><var>Target</var></th>
<td>This [[Notation conventions for methods#Named parameters|name allowed]] parameter is a %variable or an <var>IMAGE</var> 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 <var class="term">%BytesReceived</var> value.</td></tr>

<tr><th><var>MaxBytes</var></th>
<td>This optional, name allowed, parameter is the maximum number of bytes of data to receive; a positive integer no greater than 2,147,483,647. The default is 0, which means limit the received data to the larger of the <var>Minbytes</var> value and the declared length of <var>Target</var> value. If the <var>Maxbytes</var> argument is 0 and the <var>Target</var> argument is a <var>Longstring</var>, the received data is limited to 2,147,483,647 bytes.</td></tr>

<tr><th><var>MinBytes</var></th>
<td>This optional, name allowed, parameter is the minimum number of bytes of data to receive before the operation completes, unless the input stream ends (a Close operation by the remote), or <var>[[#Lengths: maximum, minimum, truncation, RECVLIM|RECVLIM]]</var> is encountered. It only needs to be specified for a variable-length receive, which is fairly unusual. The default is 0, which means use the effective value of the <var>Maxbytes</var> argument.
<p>The <var>Minbytes</var> argument must be a positive integer no greater than 2,147,483,647, and it must not exceed the effective value of the <var>Maxbytes</var> argument. </p></td></tr>

<tr><th><var>Options</var></th>
<td>This optional, name allowed, parameter is an option string, which can contain either of the following:
<table class="syntaxTable">
<tr><th><var>BINARY</var> </th>
<td>Regardless of the socket's <var>[[BINARY]]</var> or <var>[[CHAR]]</var> parameter, data <b>is not translated</b> when saved in the receive target. The received string can be translated later in the program using the <var>[[TranIn (Socket function)|TranIn]]</var> method. </td></tr>

<tr><th><var>CHAR</var> </th>
<td>Regardless of the socket's <var>BINARY</var> or <var>CHAR</var> parameter, data <b>is translated</b> when saved in the receive target. The translation is specified by the input table defined by the socket's <var>[[XTAB]]</var> parameter. </td></tr></table>
</td></tr></table>

==Usage notes==
<ul>
<li><var>Receive</var> method return values:
<ul>
<li><var>Receive</var> returns the value <code>-1</code> if the socket is not <var>OPEN</var>
and <code>ONRESET CONTINUE</code> is in effect for the socket.
<li><var>Receive</var> returns a number greater than 0 — the
number of bytes received from the socket stream —
if at least the <var>Minbytes</var> <var class="term">number</var> get stored in the target.
[[#Lengths: maximum, minimum, truncation, RECVLIM|"Lengths: maximum, minimum, truncation, RECVLIM"]], below,
explains the use of the term
<b>number of bytes received</b>, and it discusses the <var>Maxbytes</var>
and <var>Minbytes</var> arguments and other values affecting the received string.
<li>The return value from <var>Receive</var>
can be less than the <var>Minbytes</var> argument value.
This happens, for example, if there is no data remaining to be received on
the connection, that is, if <var>FIN</var> has been received.
<li><var>Receive</var> returns 0 to indicate that there is no more data to be received.
Calling <var>Receive</var> (or <var>[[ReceiveAndParse (Socket function)|ReceiveAndParse]]</var>) again in this situation, without at the very least setting <var>RECVLIM</var> to a new value, results in request cancellation.
</ul>

<li>In general, you use <var>Receive</var> when the protocol in use establishes the
length of a data item before it appears in the socket stream.
The simplest case is receiving the next <var class="term">n</var> bytes, where <var class="term">n</var>
is the size of the target (as shown in [[#Examples|"Examples"]], below).
<p>
You can use an alternative receive operation,
<var>[[ReceiveAndParse (Socket function)|ReceiveAndParse]]</var>, for a data item whose length is unknown beforehand,
but rather is terminated by a known string (or one of a known set of strings). </p>
<p>
You can use <var>[[ReceiveAsynchronous (Socket function)|ReceiveAsynchronous]]</var> for data for which you may have to wait as long as the timeout time before returning. </p>
</ul>

===Lengths: maximum, minimum, truncation, RECVLIM===
The <var>[[Receive (Socket function)|Receive]]</var> method allows you to receive either a fixed length
string of bytes, or to receive some minimum length
and also any additional bytes that may already be available in the
socket's TCP/IP input buffer; this latter capability we call a "variable length receive."

It is important to understand that when we say
"the string that is received in a call to <var>Receive</var>,"
it may be more than the string that <var>Receive</var> stores in the receive target.
Therefore, data in the input stream that exceeds the size
of the target can be discarded (or "truncated").
References to the string received by <var>Receive</var> are to the
string stored in the target plus any subsequent bytes that are discarded.
Under <var class="product">Sirius Mods</var> 6.3 and later, if the target is a <var>Longstring</var>, no bytes
would ever be discarded, since the maximum size of a <var>Longstring</var> is the
same as the greatest number of bytes <var>Receive</var> will ever receive.

There are several values that control the length of the string received.
They will be discussed in this section, using the following terms:

<table class="syntaxTable">
<tr><th><var>RECVLIM</var></th>
<td>This specifies the number of bytes remaining in the "receive window." A value of zero means there is no limit to the window. The purpose of this window is to allow you to limit a series of receive operations (using, if you want, a mixture of <var>Receive</var> and <var>ReceiveAndParse</var>) to a predetermined total number of bytes.

<var>RECVLIM</var> can be set in a <var>[[Set (Socket function)#recvlim|Set]]</var> call, and subsequent receive operations decrement from <var>RECVLIM</var> the number of bytes received, until it reaches zero (at which point a <var>Receive</var> call will return a 0, just as if a <code>FIN</code> had been received). Another <var>Receive</var> call after one returns a 0 will result in request cancellation unless <var>RECVLIM</var> is reset.

When <var>RECVLIM</var> has been set, no receive operation will use any bytes beyond the window.

A good example of the use of <var>RECVLIM</var> is obtaining a web page, whose length is (usually) specified in the <code>Content-length</code> field of the HTTP response header. </td></tr>

<tr><th>len_to_end</th>
<td>When a receive operation is performed, the received string is of course limited to the total remaining bytes in the stream that the remote end sent before issuing a close operation. Although this value is not known ahead of time, when describing the operation of receive we use this term to indicate various cases. </td></tr>

<tr><th>max_recv</th>
<td>This corresponds to the <var>Maxbytes</var> argument of the <var>Receive</var> function call. It needs to be specified only if you wish to allow truncation, or if you wish to limit the received string to a length shorter than the size of the receive target. The number of bytes received by <var>Receive</var> will not exceed the effective value of this argument. The effective value of <var class="term">max_recv</var>, if <var>Maxbytes</var> is 0 (its default), is discussed below in [[#Effective values of max_recv and min_recv|"Effective values of max_recv and min_recv"]].</td></tr>

<tr><th>min_recv</th>
<td>This corresponds to the <var>Minbytes</var> argument of the <var>Receive</var> function call. You only need to provide this argument for a variable length receive. The receive initiated by <var>Receive</var> will only complete if <var class="term">min_recv</var> bytes are received, or if the limit to the stream (<var>RECVLIM</var> or <var class="term">len_to_end</var>) is reached. The effective value of min_recv, if <var>Minbytes</var> is 0 (its default), is discussed below. </td></tr>

<tr><th>targ_size</th>
<td>The size of the target is used in calculating various defaults of the other values here, and it also obviously limits the number of bytes stored in the target and so affects the number of bytes discarded. </td></tr>

<tr><th>discard_len</th>
<td>This is the number of bytes received minus <var class="term">targ_size</var>. It will always be zero, unless <var class="term">max_recv</var> is greater than <var class="term">targ_size</var>. </td></tr>
</table>

====Effective values of max_recv and min_recv====
The <var>Maxbytes</var> and <var>Minbytes</var> arguments of <var>Receive</var> both default to 0; if they are omitted, or if
they are coded as 0, their effective values are shown here:
<table>
<tr><th>Item</th>
<th>Value when argument is 0 </th></tr>
<tr><th><i>max_recv</i></th>
<td>Larger of <var>Receive</var> argument <var>Minbytes</var> and <var class="term">targ_size</var> </td></tr>
<tr><th><i>min_recv</i></th>
<td>The effective value of <var class="term">max_recv</var> </td></tr>
</table>

'''Truncation''' can only occur if <var class="term">max_recv</var> > <var class="term">targ_size</var>, which
cannot happen if the target is a <var>Longstring</var>.

A '''variable length''' receive, which is a fairly unusual operation,
is only possible if <var class="term">min_recv</var> differs from <var class="term">max_recv</var>; therefore, you will
generally not code the <var>Minbytes</var> argument of <var>Receive</var>.

====Less than Minbytes available====
Before <var class="product">Sirius Mods</var> version 6.3, if <var>Receive</var> was called and the number of bytes
remaining on the connection within the remaining <var>RECVLIM</var> was
less than the effective value of the <var>Minbytes</var> argument,
<var>Receive</var> returned 0 to indicate this, but the receive target
was set to any partial string remaining, or to the null string if there
were none remaining (that is, <code>FIN</code> has been received).
The 0 return code indicated unsuccessful completion because the
function wasn't able to do all it was asked to do (that is, return a
fixed number of bytes or a specified minimum number of bytes).
Depending on your application, this may be an error or the partial
string may be valid data.
If no bytes were discarded, you could determine the number of
bytes received by the length of the string stored in the receive target.

In <var class="product">Sirius Mods</var> version 6.3 and later, if <var>Receive</var> is called and the number of
bytes remaining on the connection within the remaining <var>RECVLIM</var> is
less than the effective value of <var>Minbytes</var>,
<var>Receive</var> returns the number of bytes read.
In such a case, if the application determines that the number of bytes
returned is less than <var>Minbytes</var>, it knows that either <var>RECVLIM</var>
must have been hit or a <code>FIN</code> must have been received.
Alternatively, the application can forego checking for this case and
simply wait until <var>Receive</var> returns a zero.
This allows a simple receive loop structure like
<p class="code"> do while %sock:receive(target=%targ)
...
end do
</p>
Though with the use of <var>Longstrings</var>, an application can simply receive
everything up to <var>RECVLIM</var> or the end of a stream with a simple
<p class="code"> %rc = %sock:receive(target=%target)
</p>
where <var class="term">%target</var> is a <var>Longstring</var>.

==Examples==
In this example, exactly 5 data items of 100 bytes each are retrieved:
<p class="code">%grabit is string len 100 array(5)
For %x from 1 to 5
%len = %sock:Receive(%grabit(%x))
If %len ne 100 then
Print 'Invalid number of bytes received.'
Print 'Last string received=' %grabit(%x)
Print 'Partial length=' With $LEN(%grabit(%x))
End If
End For
</p>

==See also==
<ul>
<li><var>[[ReceiveAndParse (Socket function)|ReceiveAndParse]]</var>
<li><var>[[ReceiveAsynchronous (Socket function)|ReceiveAsynchronous]]</var>
</ul>
{{Template:Socket:Receive footer}}

JAL2: /* Usage notes */

2012-06-11T16:39:45Z

Usage notes

← Older revision		Revision as of 16:39, 11 June 2012
Line 58:		Line 58:
	is the size of the target (as shown in [[#Examples\|"Examples"]], below).		is the size of the target (as shown in [[#Examples\|"Examples"]], below).
	<p>		<p>
	You use an alternative receive operation,		You can use an alternative receive operation,
	<var>[[ReceiveAndParse (Socket function)\|ReceiveAndParse]]</var>, for a data item whose length is unknown beforehand,		<var>[[ReceiveAndParse (Socket function)\|ReceiveAndParse]]</var>, for a data item whose length is unknown beforehand,
	but rather is terminated by a known string (or one of a known set of strings). </p>		but rather is terminated by a known string (or one of a known set of strings). </p>
			<p>
			You can use <var>[[ReceiveAsynchronous (Socket function)\|ReceiveAsynchronous]]</var> for data for which you may have to wait as long as the timeout time before returning. </p>
	</ul>		</ul>

JAL2: /* Usage notes */

2012-06-11T16:06:29Z

Usage notes

← Older revision		Revision as of 16:06, 11 June 2012
Line 58:		Line 58:
	is the size of the target (as shown in [[#Examples\|"Examples"]], below).		is the size of the target (as shown in [[#Examples\|"Examples"]], below).
	<p>		<p>
	You use ~~the alternate~~ receive operation,		You use an alternative receive operation,
	<var>[[ReceiveAndParse (Socket function)\|ReceiveAndParse]]</var>, for a data item whose length is unknown beforehand,		<var>[[ReceiveAndParse (Socket function)\|ReceiveAndParse]]</var>, for a data item whose length is unknown beforehand,
	but rather is terminated by a known string (or one of a known set of strings). </p>		but rather is terminated by a known string (or one of a known set of strings). </p>

JAL2: /* Usage notes */

2012-06-11T16:05:28Z

Usage notes

← Older revision		Revision as of 16:05, 11 June 2012
Line 50:		Line 50:
	the connection, that is, if <var>FIN</var> has been received.		the connection, that is, if <var>FIN</var> has been received.
	<li><var>Receive</var> returns 0 to indicate that there is no more data to be received.		<li><var>Receive</var> returns 0 to indicate that there is no more data to be received.
	Calling <var>Receive</var> (or <var>[[ReceiveAndParse (Socket function)\|ReceiveAndParse</var>) again in this situation, without at the very least setting <var>RECVLIM</var> to a new value, results in request cancellation.		Calling <var>Receive</var> (or <var>[[ReceiveAndParse (Socket function)\|ReceiveAndParse]]</var>) again in this situation, without at the very least setting <var>RECVLIM</var> to a new value, results in request cancellation.
	</ul>		</ul>

JAL2: /* See also */

2012-06-08T21:16:09Z

JAL2 at 19:42, 8 June 2012

2012-06-08T19:42:19Z

@@ Line 6: / Line 6: @@
 ===Syntax terms===
 <table class="syntaxTable">
-<tr><th>%BytesReceived</th><td>number</td></tr>
+<tr><th>%BytesReceived</th>
 <tr><th>socket</th>
-<td>Socket object</td></tr>
+<td>A variable or an expression that is a reference to a <var>Socket</var> object.</td></tr>
 <tr><th><var>Target</var></th>
-<td>string</td></tr>
+<td>This [[Notation conventions for methods#Named parameters|name allowed]] parameter is a %variable or an <var>IMAGE</var> 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 <var class="term">%BytesReceived</var> value.</td></tr>
 <tr><th><var>MaxBytes</var></th>
-<td>number</td></tr>
+<td>This optional, name allowed, parameter is the maximum number of bytes of data to receive; a positive integer no greater than 2,147,483,647. The default is 0, which means limit the received data to the larger of the <var>Minbytes</var> value and the declared length of <var>Target</var> value. If the <var>Maxbytes</var> argument is 0 and the <var>Target</var> argument is a <var>Longstring</var>, the received data is limited to 2,147,483,647 bytes.</td></tr>
 <tr><th><var>MinBytes</var></th>
-<td>number</td></tr>
+<td>This optional, name allowed, parameter is the minimum number of bytes of data to receive before the operation completes, unless the input stream ends (a Close operation by the remote), or <var>[[#Lengths: maximum, minimum, truncation, RECVLIM|RECVLIM]]</var> is encountered. It only needs to be specified for a variable-length receive, which is fairly unusual. The default is 0, which means use the effective value of the <var>Maxbytes</var> argument.
 <tr><th><var>Options</var></th>
-<td>string</td></tr>
+<td>This optional, name allowed, parameter is an option string, which can contain either of the following:
-</table>
+<table class="syntaxTable">
 ==Usage notes==
 ===Lengths: maximum, minimum, truncation, RECVLIM===
@@ Line 121: / Line 164: @@
 ==Examples==
 ==See also==
 {{Template:Socket:Receive footer}}

JAL2: /* Lengths: maximum, minimum, truncation, RECVLIM */

2011-12-09T22:35:28Z

Lengths: maximum, minimum, truncation, RECVLIM

← Older revision		Revision as of 22:35, 9 December 2011
Line 57:		Line 57:

	<tr><th>min_recv</th>		<tr><th>min_recv</th>
	<td>This corresponds to the <var>Minbytes</var> argument of the <var>Receive</var> function call. You only need to provide this argument for a variable length receive. The receive initiated by <var>Receive</var> will only complete if <var class="term">min_recv</var> bytes are received, or if the limit to the stream (<var>RECVLIM</var> or <var class="term">len_to_end</var>) is reached. The effective value of min_recv, if ~~argument 4~~ is 0 (its default), is discussed		<td>This corresponds to the <var>Minbytes</var> argument of the <var>Receive</var> function call. You only need to provide this argument for a variable length receive. The receive initiated by <var>Receive</var> will only complete if <var class="term">min_recv</var> bytes are received, or if the limit to the stream (<var>RECVLIM</var> or <var class="term">len_to_end</var>) is reached. The effective value of min_recv, if <var>Minbytes</var> is 0 (its default), is discussed below. </td></tr>
	below. </td></tr>

	<tr><th>targ_size</th>		<tr><th>targ_size</th>

JAL2 at 22:13, 9 December 2011

2011-12-09T22:13:20Z

← Older revision		Revision as of 22:13, 9 December 2011
Line 54:		Line 54:

	<tr><th>max_recv</th>		<tr><th>max_recv</th>
	<td>This corresponds to argument 3 of the <var>Receive</var> function call. It needs to be specified only if you wish to allow truncation, or if you wish to limit the received string to a length shorter than the size of the receive target. The number of bytes received by <var>Receive</var> will not exceed the effective value of this argument. The effective value of <var class="term">max_recv</var>, if ~~argument 3~~ is 0 (its default), is ~~discus~~ </td></tr>		<td>This corresponds to the <var>Maxbytes</var> argument of the <var>Receive</var> function call. It needs to be specified only if you wish to allow truncation, or if you wish to limit the received string to a length shorter than the size of the receive target. The number of bytes received by <var>Receive</var> will not exceed the effective value of this argument. The effective value of <var class="term">max_recv</var>, if <var>Maxbytes</var> is 0 (its default), is discussed below in [[#Effective values of max_recv and min_recv\|"Effective values of max_recv and min_recv"]].</td></tr>

	<tr><th>min_recv</th>		<tr><th>min_recv</th>
	<td>This corresponds to argument 4 of the <var>Receive</var> function call. You only need to provide this argument for a variable length receive. The receive initiated by <var>Receive</var> will only complete if <var class="term">min_recv</var> bytes are received, or if the limit to the stream (<var>RECVLIM</var> or <var class="term">len_to_end</var>) is reached. The effective value of min_recv, if argument 4 is 0 (its default), is discussed		<td>This corresponds to the <var>Minbytes</var> argument of the <var>Receive</var> function call. You only need to provide this argument for a variable length receive. The receive initiated by <var>Receive</var> will only complete if <var class="term">min_recv</var> bytes are received, or if the limit to the stream (<var>RECVLIM</var> or <var class="term">len_to_end</var>) is reached. The effective value of min_recv, if argument 4 is 0 (its default), is discussed
	below. </td></tr>		below. </td></tr>

Line 67:		Line 67:
	</table>		</table>

	~~Arguments three~~ and ~~four~~ both default to 0; if they are omitted, or if		<h4>Effective values of max_recv and min_recv</h4>
			The <var>Maxbytes</var> and <var>Minbytes</var> arguments of <var>Receive</var> both default to 0; if they are omitted, or if
	they are coded as 0, their effective values are shown here:		they are coded as 0, their effective values are shown here:

	~~<h4>Effective values of <i>max_recv</i> and <i>min_recv</i></h4>~~
	<table>		<table>
	<tr><th>Item</th>		<tr><th>Item</th>

JAL2: /* Usage notes */

2011-12-09T21:59:41Z

Usage notes

@@ Line 19: / Line 19: @@
 </table>
 ==Usage notes==
 ==Examples==
 ==See also==
 {{Template:Socket:Receive footer}}

← Older revision		Revision as of 21:16, 8 June 2012
Line 177:		Line 177:

	==See also==		==See also==
			<ul>
			<li><var>[[ReceiveAndParse (Socket function)\|ReceiveAndParse]]</var>
			<li><var>[[ReceiveAsynchronous (Socket function)\|ReceiveAsynchronous]]</var>
			</ul>
	{{Template:Socket:Receive footer}}		{{Template:Socket:Receive footer}}