$Sock Recv - Revision history

JALWiccan: Automatically generated page update

2018-09-21T00:00:34Z

Automatically generated page update

← Older revision		Revision as of 00:00, 21 September 2018
Line 1:		Line 1:
	{{DISPLAYTITLE:$Sock_Recv}}		{{DISPLAYTITLE:$Sock_Recv}}
	<span class="pageSubtitle">Receive string based on count</span>		<span class="pageSubtitle">Receive string based on count</span>
	<p class="warn"><b>Note: </b>~~Most Sirius~~ $functions have been deprecated in favor of Object Oriented		<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented
	methods. The OO equivalent for <var>$Sock_Recv</var> is the <var>[[Receive (Socket function)\|Receive]]</var> method.</p>		methods. The OO equivalent for <var>$Sock_Recv</var> is the <var>[[Receive (Socket function)\|Receive]]</var> method.</p>

JAL at 23:44, 22 October 2013

2013-10-22T23:44:19Z

Show changes

JAL at 21:50, 23 July 2013

2013-07-23T21:50:16Z

← Older revision		Revision as of 21:50, 23 July 2013
Line 2:		Line 2:
	<span class="pageSubtitle">Receive string based on count</span>		<span class="pageSubtitle">Receive string based on count</span>
	<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented		<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented
	methods. ~~There is currently no direct~~ OO equivalent for ~~this~~ $function.</p>		methods. The OO equivalent for <var>$Sock_Recv</var> is the <var>[[Receive (Socket function)\|Receive]]</var> method.</p>

	<var>$Sock_Recv</var> receives a string of bytes on a <var class="product">Janus Sockets</var> connection, typically		<var>$Sock_Recv</var> receives a string of bytes on a <var class="product">Janus Sockets</var> connection, typically

JALWiccan: Automatically generated page update

2013-07-19T18:59:26Z

Automatically generated page update

← Older revision		Revision as of 18:59, 19 July 2013
Line 1:		Line 1:
	{{DISPLAYTITLE:$Sock_Recv}}		{{DISPLAYTITLE:$Sock_Recv}}
	<span class="pageSubtitle">Receive string based on count</span>		<span class="pageSubtitle">Receive string based on count</span>
	<p class="~~warning~~">Most Sirius $functions have been deprecated in favor of Object Oriented		<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented
	methods. There is currently no direct OO equivalent for this $function.</p>		methods. There is currently no direct OO equivalent for this $function.</p>

JAL2 at 03:32, 20 January 2012

2012-01-20T03:32:23Z

← Older revision		Revision as of 03:32, 20 January 2012
Line 10:		Line 10:

	==Syntax==		==Syntax==
	<p class="syntax"><span class="squareb">[</span><span class="term">%num</span><span class="literal"> =</span><span class="squareb">]</span><span class="literal"> $Sock_Recv(</span><span class="term">~~sockno~~</span><span class="literal">,</span> <span class="term">%recv_targ</span><span class="literal">,</span> <span class="squareb">[</span><span class="term">opts</span><span class="squareb">]</span><span class="literal">)</span> </p>		<p class="syntax"><span class="squareb">[</span><span class="term">%num</span><span class="literal"> =</span><span class="squareb">]</span><span class="literal"> $Sock_Recv(</span><span class="term">sockNum</span><span class="literal">,</span> <span class="term">%recv_targ</span><span class="literal">,</span> <span class="squareb">[</span><span class="term">opts</span><span class="squareb">]</span><span class="literal">)</span> </p>

	===Syntax terms===		===Syntax terms===
	<table class="syntaxTable">		<table class="syntaxTable">
	<tr><th>%num</th>		<tr><th>%num</th>
	<td>A numeric value that is the number of bytes received, or, if the operation could not be performed as requested, a 0 value. ~~</td></tr>~~ For more details, see [[#$Sock_Recv return values\|"$Sock_Recv return values"]]. <tr><th>~~sockno~~</th> <td>The socket number. </td></tr> <tr><th>%recv_targ</th> <td>A %variable or an <var>IMAGE</var> item (and '''never''' a <var class="product">[[Janus SOAP User Language Interface\|Janus SOAP ULI]]</var> class variable). This argument is the target of the receive operation, and is referred to as the "receive target." You may request that some bytes from the socket stream can be discarded, so the length of the string stored in this target may be less than the value returned by <var>$Sock_Recv</var>. </td></tr> <tr><th>maxbytes</th> <td>This optional argument, the maximum number of bytes of data to receive, must be from 0 to 2,147,483,647. The default is 0, which means limit the received data to the larger of the value of the <var class="term">minbytes</var> argument and the declared length of the receive target.		<td>A numeric value that is the number of bytes received, or, if the operation could not be performed as requested, a 0 value. For more details, see [[#$Sock_Recv return values\|"$Sock_Recv return values"]]. </td></tr>
	Under <var class="product">Sirius Mods</var> version 6.3 and later, if this argument is 0 and the receive argument is a <var>Longstring</var>, the received data is limited to 2,147,483,647 bytes. </td></tr> <tr><th>minbytes</th> <td>This optional argument 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 <code>RECVLIM</code> is encountered. The argument only needs to be specified for a variable length receive, which is fairly unusual.		<tr><th>sockNum</th>
	The default is 0, which means use the effective value of the <var class="term">maxbytes</var> argument. Valid values must be from 0 to 2,147,483,647, and must not exceed the effective value of <var class="term">maxbytes</var>. </td></tr> <tr><th>opts</th> <td>This optional argument is an option string which can contain any of the following: <table class="syntaxTable"> <tr><th><var>BINARY</var> </th> <td>This indicates that regardless of the socket's <var>[[BINARY (JANUS DEFINE parameter)\|BINARY]]</var> or <var>[[CHAR (JANUS DEFINE parameter)\|CHAR]]</var> parameter, data '''is not translated''' when saved in the receive target. The received string <tr><th><var>CHAR</var> </th> <td>This indicates that regardless of the socket's <var>[[BINARY (JANUS DEFINE parameter)\|BINARY]]</var> or <var>[[CHAR (JANUS DEFINE parameter)\|CHAR]]</var> parameter, data '''is translated''' when saved in the receive target. The translation is ~~speci~~		<td>The socket number. </td></tr>
	</td></tr></table>
			<tr><th>%recv_targ</th>
			<td>A %variable or an <var>IMAGE</var> item (and '''never''' a <var class="product">[[Janus SOAP User Language Interface\|Janus SOAP ULI]]</var> class variable). This argument is the target of the receive operation, and is referred to as the "receive target." You may request that some bytes from the socket stream can be discarded, so the length of the string stored in this target may be less than the value returned by <var>$Sock_Recv</var>. </td></tr>

			<tr><th>maxbytes</th>
			<td>This optional argument, the maximum number of bytes of data to receive, must be from 0 to 2,147,483,647. The default is 0, which means limit the received data to the larger of the value of the <var class="term">minbytes</var> argument and the declared length of the receive target.
			<p>
			Under <var class="product">Sirius Mods</var> version 6.3 and later, if this argument is 0 and the receive argument is a <var>Longstring</var>, the received data is limited to 2,147,483,647 bytes. </p></td></tr>

			<tr><th>minbytes</th>
			<td>This optional argument 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 <code>RECVLIM</code> is encountered. The argument only needs to be specified for a variable length receive, which is fairly unusual.
			<p>
			The default is 0, which means use the effective value of the <var class="term">maxbytes</var> argument. Valid values must be from 0 to 2,147,483,647, and must not exceed the effective value of <var class="term">maxbytes</var>. </p></td></tr>

			<tr><th>opts</th>
			<td>This optional argument is an option string which can contain any of the following:
			<table class="syntaxTable">
			<tr><th><var>BINARY</var> </th>
			<td>This indicates that regardless of the socket's <var>[[BINARY (JANUS DEFINE parameter)\|BINARY]]</var> or <var>[[CHAR (JANUS DEFINE parameter)\|CHAR]]</var> parameter, data '''is not translated''' when saved in the receive target. The received string can be translated later in the program using the <var>[[$Sock_Tran_In]]</var> function. </td></tr>
			<tr><th><var>CHAR</var> </th>
			<td>This indicates that regardless of the socket's <var>[[BINARY (JANUS DEFINE parameter)\|BINARY]]</var> or <var>[[CHAR (JANUS DEFINE parameter)\|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> parameter. </td></tr></table>
	</td></tr>		</td></tr>
	</table>		</table>

	===~~<var>~~$Sock_Recv~~</var>~~ return values===		===$Sock_Recv return values===
	<ul>		<ul>
	<li><var>$Sock_Recv</var> returns the value -1 if the socket is not <var>OPEN</var>		<li><var>$Sock_Recv</var> returns the value -1 if the socket is not <var>OPEN</var>

Admin: 1 revision

2012-01-20T02:53:46Z

1 revision

← Older revision	Revision as of 02:53, 20 January 2012
(No difference)

JAL at 17:21, 19 January 2012

2012-01-19T17:21:57Z

New page

{{DISPLAYTITLE:$Sock_Recv}}
Receive string based on count
Most Sirius $functions have been deprecated in favor of Object Oriented
methods. There is currently no direct OO equivalent for this $function.

<var>$Sock_Recv</var> receives a string of bytes on a <var class="product">Janus Sockets</var> connection, typically
to obtain a fixed-length string, and also to allow receipt of additional "already-buffered" bytes.

<var>$Sock_Recv</var> is also a [[Notation conventions for methods#Callable functions|callable]] function.

==Syntax==
[%num =] $Sock_Recv(sockno, %recv_targ, [opts]) 

===Syntax terms===
<table class="syntaxTable">
<tr><th>%num</th>
<td>A numeric value that is the number of bytes received, or, if the operation could not be performed as requested, a 0 value. </td></tr> For more details, see [[#$Sock_Recv return values|"$Sock_Recv return values"]]. <tr><th>sockno</th> <td>The socket number. </td></tr> <tr><th>%recv_targ</th> <td>A %variable or an <var>IMAGE</var> item (and '''never''' a <var class="product">[[Janus SOAP User Language Interface|Janus SOAP ULI]]</var> class variable). This argument is the target of the receive operation, and is referred to as the "receive target." You may request that some bytes from the socket stream can be discarded, so the length of the string stored in this target may be less than the value returned by <var>$Sock_Recv</var>. </td></tr> <tr><th>maxbytes</th> <td>This optional argument, the maximum number of bytes of data to receive, must be from 0 to 2,147,483,647. The default is 0, which means limit the received data to the larger of the value of the <var class="term">minbytes</var> argument and the declared length of the receive target.
Under <var class="product">Sirius Mods</var> version 6.3 and later, if this argument is 0 and the receive argument is a <var>Longstring</var>, the received data is limited to 2,147,483,647 bytes. </td></tr> <tr><th>minbytes</th> <td>This optional argument 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 <code>RECVLIM</code> is encountered. The argument 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 class="term">maxbytes</var> argument. Valid values must be from 0 to 2,147,483,647, and must not exceed the effective value of <var class="term">maxbytes</var>. </td></tr> <tr><th>opts</th> <td>This optional argument is an option string which can contain any of the following: <table class="syntaxTable"> <tr><th><var>BINARY</var> </th> <td>This indicates that regardless of the socket's <var>[[BINARY (JANUS DEFINE parameter)|BINARY]]</var> or <var>[[CHAR (JANUS DEFINE parameter)|CHAR]]</var> parameter, data '''is not translated''' when saved in the receive target. The received string <tr><th><var>CHAR</var> </th> <td>This indicates that regardless of the socket's <var>[[BINARY (JANUS DEFINE parameter)|BINARY]]</var> or <var>[[CHAR (JANUS DEFINE parameter)|CHAR]]</var> parameter, data '''is translated''' when saved in the receive target. The translation is speci
</td></tr></table>
</td></tr>
</table>

===<var>$Sock_Recv</var> return values===
<ul>
<li><var>$Sock_Recv</var> returns the value -1 if the socket is not <var>OPEN</var>
and <var>ONRESET CONTINUE</var> is in effect for the socket.
<li><var>$Sock_Recv</var> returns a number greater than 0
(which is the number of bytes received from the socket stream)
if at least <var class="term">minbytes</var> are stored in the target.
[[#Lengths: maximum, minimum, truncation, RECVLIM|Lengths: maximum, minimum, truncation, RECVLIM]] explains how the term
'''number of bytes received''' is used, and it discusses the <var class="term">maxbytes</var>
and <var class="term">minbytes</var> arguments and other values affecting the received string.

In <var class="product">Sirius Mods</var> version 6.3 and later, the return value from <var>$Sock_Recv</var>
can be less than the value of <var class="term">minbytes</var>.
<li>Before <var class="product">Sirius Mods</var> version 6.3, <var>$Sock_Recv</var> would return 0 to indicate
that the length of the received
string is less than <var class="term">minbytes</var>. [[#Less than minbytes available|"Less than minbytes available"]] explains the 0 return code.
One case of this is if there is no data remaining to be received on
the connection, that is, if <code>FIN</code> has been received.

In <var class="product">Sirius Mods</var> version 6.3 and later, <var>$Sock_Recv</var> returns 0 to indicate
that there is no more data to be received.
Calling <var>$Sock_Recv</var> (or <var>[[$Sock_RecvPrs]]</var>) again in this situation, without
at the very least setting <var>RECVLIM</var> to a new value, will result in request cancellation.
</ul>

==Usage notes==
In general, you use <var>$Sock_Recv</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 n bytes, where n
is the size of the target, as shown in the following example to receive
5 strings of 100 bytes each.
You use the alternate receive operation,
<var>$Sock_RecvPrs</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).

%GRABIT IS STRING LEN 100 ARRAY(5)
For %x From 1 To 5
%len = $Sock_Recv(%socket, %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


==Lengths: maximum, minimum, truncation, RECVLIM==
The <var>$Sock_Recv</var> function 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 is called a "variable length receive."

It is important to understand that a string referred to as
"the string that is received in a call to <var>$Sock_Recv</var>"
may be more than the string that <var>$Sock_Recv</var> stores in the receive target.
Therefore, data in the input stream that exceeds the size
of the target can be discarded (or "truncated").
The "string received by <var>$Sock_Recv</var>," is a reference 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>$Sock_Recv</var> will ever receive.

The several values that control the length of the string received
are 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>$Sock_Recv</var> and <var>$Sock_RecvPrs</var>) to a predetermined total number of bytes.
<var>RECVLIM</var> can be set in a <var>$Sock_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>$Sock_Recv</var> call will return a 0, just as i
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 "Content-length" 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, the <var class="term">len_to_end</var> term is used to indicate various cases.
</td></tr>

<tr><th>max_recv </th>
<td>This corresponds to the <var class="term">maxbytes</var> argument of the <var>$Sock_Recv</var> function call. It needs to be specified only if you want to allow truncation, or if you want to limit the received string to a length shorter than the size of the receive target. The number of bytes received by <var>$Sock_Recv</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 discussed [[#maxmin|below]].</td></tr>

<tr><th>min_recv </th>
<td>This corresponds to the <var class="term">minbytes</var> argument of the <var>$Sock_Recv</var> function call. You only need to provide this argument for a variable length receive. The receive initiated by <var>$Sock_Recv</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 <var class="term">min_recv</var>, if <var class="term">minbytes</var> is 0 (its default), is discussed [[#maxmin|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>

<div id="maxmin"></div>
Arguments <var class="term">max_recv</var> and <var class="term">min_recv</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>max_recv</th>
<td>larger of <var class="term">min_recv</var> and <var class="term">targ_size</var></td></tr>
<tr><th>min_recv</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 class="term">minbytes</var> argument of <var>$Sock_Recv</var>.
===Less than minbytes available===
Before <var class="product">Sirius Mods</var> version 6.3, if <var>$Sock_Recv</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 class="term">minbytes</var> argument,
<var>$Sock_Recv</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>$Sock_Recv</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 the <var class="term">minbytes</var> argument,
<var>$Sock_Recv</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 class="term">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>$Sock_Recv</var> returns a zero.
This allows a simple receive loop structure like:
Do While $Sock_Recv(%sock, %str)
...
End Do

However, with the use of <var>Longstring</var>s, an application can simply receive
everything up to <var>RECVLIM</var> or the end of a stream with a simple call like:
%rc = $Sock_Recv(%sock, %longstr)


[[Category: Janus Sockets $functions]]