$Sock RecvPrs - Revision history

JALWiccan: Automatically generated page update

2018-09-21T00:00:35Z

Automatically generated page update

← Older revision		Revision as of 00:00, 21 September 2018
Line 1:		Line 1:
	{{DISPLAYTITLE:$Sock_RecvPrs}}		{{DISPLAYTITLE:$Sock_RecvPrs}}
	<span class="pageSubtitle">Receive parsed string</span>		<span class="pageSubtitle">Receive parsed string</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_RecvPrs</var> is the <var>[[ReceiveAndParse (Socket function)\|ReceiveAndParse]]</var> method.</p>		methods. The OO equivalent for <var>$Sock_RecvPrs</var> is the <var>[[ReceiveAndParse (Socket function)\|ReceiveAndParse]]</var> method.</p>

JAL at 19:43, 23 September 2014

2014-09-23T19:43:24Z

← Older revision		Revision as of 19:43, 23 September 2014
Line 129:		Line 129:
	</table>		</table>

	Argument <var class="term">max_recvp</var> defaults to 0; if they are omitted, or if it is coded as 0, its effective value is		Argument <var class="term">max_recvp</var> defaults to 0; if they are omitted, or if it is coded as 0, its effective value is shown here:
	shown here:
	<table>		<table>
	<tr class="head"><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>~~max_recvp (~~of $Sock_RecvPrs)</th>		<tr><td><var class="term">maxrecvp</var> argument of <var>$Sock_RecvPrs</var></td>
	<td><var class="term">targ_size</var> </td></tr>		<td><var class="term">targ_size</var> </td></tr>
	</table>		</table>

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

	If a separator string is not found due to a limit imposed by <var>RECVLIM</var>,		If a separator string is not found due to a limit imposed by <var>RECVLIM</var>,
	<var class="term">len_to_end</var>, or <var class="term">max_recvp</var>, then zero is stored in the parse index target		<var class="term">len_to_end</var>, or <var class="term">max_recvp</var>, then zero is stored in the parse index target (the <var class="term">%prsindx</var> argument).
	(the <var class="term">%prsindx</var> argument).

	[[Category: Janus Sockets $functions]]		[[Category: Janus Sockets $functions]]

JAL at 00:07, 23 October 2013

2013-10-23T00:07:18Z

Show changes

JAL at 21:51, 23 July 2013

2013-07-23T21:51:45Z

← Older revision		Revision as of 21:51, 23 July 2013
Line 2:		Line 2:
	<span class="pageSubtitle">Receive parsed string</span>		<span class="pageSubtitle">Receive parsed string</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_RecvPrs</var> is the <var>[[ReceiveAndParse (Socket function)\|ReceiveAndParse]]</var> method.</p>

	<var>$Sock_RecvPrs</var> receives, over a <var class="product">Janus Sockets</var> connection, a string whose length		<var>$Sock_RecvPrs</var> receives, over a <var class="product">Janus Sockets</var> connection, a string whose length

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_RecvPrs}}		{{DISPLAYTITLE:$Sock_RecvPrs}}
	<span class="pageSubtitle">Receive parsed string</span>		<span class="pageSubtitle">Receive parsed string</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:40, 20 January 2012

2012-01-20T03:40:09Z

← Older revision		Revision as of 03:40, 20 January 2012
Line 11:		Line 11:

	==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_RecvPrs(</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_RecvPrs(</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">maxrecvp</span><span class="squareb">]</span><span class="literal">,</span> <span class="squareb">[</span><span class="term">prsindx</span><span class="squareb">]</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===
Line 18:		Line 18:
	<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_RecvPrs return values\|"$Sock_RecvPrs return values"]]. </td></tr>		<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_RecvPrs return values\|"$Sock_RecvPrs return values"]]. </td></tr>

	<tr><th>~~sockno~~</th>		<tr><th>sockNum</th>
	<td>The socket number. </td></tr>		<td>The socket number. </td></tr>

Line 131:		Line 131:
	<tr><th><i>Item</i></th>		<tr><th><i>Item</i></th>
	<th><i>Value when argument is 0</i></th></tr>		<th><i>Value when argument is 0</i></th></tr>
	<tr><th>max_recvp (of ~~<var>~~$Sock_RecvPrs~~</var>~~)		<tr><th>max_recvp (of $Sock_RecvPrs)
	</th><td><var class="term">targ_size</var>		</th><td><var class="term">targ_size</var>
	</td></tr>		</td></tr>

Admin: 1 revision

2012-01-20T02:53:46Z

1 revision

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

JAL at 16:53, 19 January 2012

2012-01-19T16:53:25Z

New page

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

<var>$Sock_RecvPrs</var> receives, over a <var class="product">Janus Sockets</var> connection, a string whose length
is not known beforehand but which is terminated by a known string or by
one of a known set of strings.

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

==Syntax==
[%num =] = $Sock_RecvPrs(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. For more details, see [[#$Sock_RecvPrs return values|"$Sock_RecvPrs return values"]]. </td></tr>

<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_RecvPrs</var>. </td></tr>

<tr><th>maxrecvp</th>
<td>This optional argument, the maximum number of bytes of data to receive, '''less''' the '''length of the separator''' string, must be from 0 to 2,147,483,647, or must be the special value -1, which indicates there is no limit to the number of bytes received.

The default is 0, which means limit the received data (less separator) to to 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>prsindx</th>
<td>This optional argument is is a %variable or <var>IMAGE</var> item in which the index number (> 0) of the parse token found is stored. This variable is set to 0 if no token is found '''within''' <var>RECVLIM</var> bytes or if it is not found '''after''' more than the number of data bytes specified by the effective value of the <var class="term">maxrecvp</var> argument. </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>

<tr><th><var>PRSTOK [AMBIG|]</var>hexstr[|hexstr]... </th>
<td>This is a set of parse tokens which override the parse tokens set on the socket.
Whether it is set on the port definition, via <var>[[$Sock_Set]]</var>, or as an argument on the <var>$Sock_RecvPrs</var> function, <var>PRSTOK</var> must not be <code>NONE</code> when using <var>$Sock_RecvPrs</var>. </td></tr></table>

</td></tr> </table>

===$Sock_RecvPrs return values===
<ul>
<li><var>$Sock_RecvPrs</var> returns the value -1 if the socket is not open and <code>ONRESET CONTINUE</code> is in effect for the socket.
<li><var>$Sock_RecvPrs</var> returns a number greater than 0 which is the number of bytes received from of the socket stream. [[#Lengths: maximum, truncation, RECVLIM|"Lengths: maximum, truncation, RECVLIM"]] explains how the term '''number of bytes received''' is used, and discusses the <var class="term">maxrecvp</var> argument and other values affecting the received string.
<li><var>$Sock_RecvPrs</var> returns zero to indicate there is no data remaining to be received on the connection, that is, if <code>FIN</code> has been received or the <var>RECVLIM</var> has been reached.
</ul>

==Usage notes==
<ul>
<li>You use <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). In general, you use the alternate receive operation, <var>[[$Sock_Recv]]</var>, when the protocol in use establishes the length of a data item before it appears in the socket stream.
<li>The <var class="term">prsindx</var> argument is used in case there is more than one alternative in the <var>PRSTOK</var> setting, and you need to distinguish which one of them terminated the received value. For example, with the input stream of <code>X'36370D38390D'</code>, the following expression will store the value 2 in the variable <code>%prs</code>.
$Sock_RecvPrs(%sk, %str, , %prs, 'PRSTOK AMBIG|0D0A|0D|0A') 

Note that this example uses ambiguous <var>PRSTOK</var> strings (<code>0D</code> is a prefix of <code>0D0A</code>). Considerations for this are discussed in [[Sample Janus Sockets Programs#Ambiguous PRSTOK strings|"Ambiguous PRSTOK strings"]].

The <var>PRSTOK</var> separators are chosen to match the protocol and data streams that are used with your application. One of the considerations, of course, is that a separator should not occur in the "normal" data received by your application. If that is unavoidable, you will need to use an "escaping" mechanism; for example, you could use the ASCII <code>ESC</code> character (hexadecimal <code>1B</code>) to indicate that it precedes a character that is to be taken literally. 

For example, if the data contains non-separator instances of <code>CR</code> and <code>ESC</code>: 
%junk String Len 1
%r = $Sock_Set(%sok, 'PRSTOK', '0D|1B')
Repeat
%r = $Sock_RecvPrs(%sok, %targ, %sep)
If %sep Eq 2 Then
%r = $Sock_Recv(%sok, %junk)
%targ = %targ With %junk
End If
... 
</ul>

==Examples==
The following example shows part of a program that communicates with a remote web server and which parses and prints the
returned HTML stream. Note that the third argument to <var>$Sock_RecvPrs</var> is -1, which means that there is no limit to the length of each line parsed, hence no limit to the number of bytes discarded at the end of the line; only the first 78 bytes (the size of <code>%s</code>) of each line of HTML is examined by the <var class="product">User Language</var> program.

A complete version of this program is shown in [[Sample Janus Sockets Programs#Simple echo of HTTP/HTML|"Simple echo of
HTTP/HTML"]]. See [[Sample Janus Sockets Programs#Simple echo of HTTP/HTML|"Simple echo of HTTP/HTML"]] for another complete
program, which does not discard any received data.

%s = $Sock_Set(%socket, 'PRSTOK', '0D0A|0A|0D')
Repeat
%rc = $Sock_RecvPrs(%socket, %s, -1)
Print %s
If %rc LE 0 Then
Loop End
End If
End Repeat
%rc = $Sock_Close(%socket) 

==Lengths: maximum, truncation, RECVLIM==
The <var>$Sock_RecvPrs</var> function allows you to locate a separator string, and to store all or part of the string before
the separator into the receive target. It is important to understand that when we say "the string that is received in a call to <var>$Sock_RecvPrs</var>", it may be more than the string that <var>$Sock_RecvPrs</var> stores in the receive target. This is for the following two reasons:
<ol>
<li>The separator string is part of the string received, but it is not stored in the receive target.
<li>The string before the separator may exceed the size of the target, and thus can be partially discarded (or "truncated").
</ol>
References to the string received by $Sock_RecvPrs are to the string stored in the target plus any subsequent bytes that are
discarded, plus the separator string.
Several of the 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 if a <code>FIN</code> had been received.
When <var>RECVLIM</var> is greater than zero, 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, this term is used to indicate various cases. </td></tr>
<tr><th>max_recvp</th>
<td>This corresponds to the <var class="term">maxrecvp</var> argument of the <var>$Sock_RecvPrs</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 less than the declared size of the target.

You can specify that an unlimited number of bytes can be discarded by specifying -1 as the <var class="term">maxrecvp</var> argument of <var>$Sock_RecvPrs</var>, making the effective value "infinite." The number of bytes received by <var>$Sock_RecvPrs</var> will not exceed the effective value of this argument plus the length of the separator string. The effective value of <var class="term">max_recvp</var> if the <var class="term">maxrecvp</var> argument of <var>$Sock_RecvPrs</var> is 0 (its default), is discussed below. 

<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 the length of the separator string, minus <var class="term">targ_size</var>. It will always be zero, unless <var class="term">max_recvp</var> is greater than <var class="term">targ_size</var>. </td></tr>
</table>

Argument <var class="term">max_recvp</var> defaults to 0; if they are omitted, or if it is coded as 0, its effective value is
shown here:
<table>
<tr><th>Item</th>
<th>Value when argument is 0</th></tr>
<tr><th>max_recvp (of <var>$Sock_RecvPrs</var>)
</th><td><var class="term">targ_size</var>
</td></tr>
</table>

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

If a separator string is not found due to a limit imposed by <var>RECVLIM</var>,
<var class="term">len_to_end</var>, or <var class="term">max_recvp</var>, then zero is stored in the parse index target
(the <var class="term">%prsindx</var> argument).

[[Category: Janus Sockets $functions]]