$Sock RecvPrs: Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Automatically generated page update)
(Automatically generated page update)
 
(3 intermediate revisions by one other user not shown)
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. 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
Line 16: Line 16:
<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. 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>sockNum</th>  
<tr><th>sockNum</th>  
Line 22: Line 22:


<tr><th>%recv_targ</th>  
<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>  
<td>A %variable or an <var>IMAGE</var> item (and '''never''' a <var class="product">SOUL</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>  
<tr><th>maxrecvp</th>  
Line 28: Line 28:
<p>
<p>
The default is 0, which means limit the received data (less separator) to to the declared length of the receive target.
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. </p></td></tr>  
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>prsindx</th>  
<tr><th>prsindx</th>  
Line 36: Line 36:
<td>This optional argument is an option string which can contain any of the following:
<td>This optional argument is an option string which can contain any of the following:


<table class="syntaxTable">  
<table class="thJustBold">  


<tr><th><var>BINARY</var> </th>  
<tr><th>BINARY </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>
<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>  
<tr><th>CHAR </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>   
<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><i>hexstr</i>[|<i>hexstr</i>]...  </th>  
<tr><th nowrap>PRSTOK [AMBIG<tt>|</tt>]<i>hexstr</i>[<tt>|</tt><i>hexstr</i>]...  </th>  
<td>This is a set of parse tokens which override the parse tokens set on the socket.
<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>
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>
Line 53: Line 53:
<ul>  
<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 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 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.  
<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>
</ul>
Line 63: Line 63:
<p class="code">$Sock_RecvPrs(%sk, %str, , %prs, 'PRSTOK AMBIG|0D0A|0D|0A') </p>
<p class="code">$Sock_RecvPrs(%sk, %str, , %prs, 'PRSTOK AMBIG|0D0A|0D|0A') </p>


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"]].
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]].
<p>
<p>
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. </p>
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. </p>
Line 81: Line 81:
==Examples==  
==Examples==  
The following example shows part of a program that communicates with a remote web server and which parses and prints the  
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.
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">SOUL</var> program.


A complete version of this program is shown in [[Sample Janus Sockets Programs#Simple echo of HTTP/HTML|"Simple echo of  
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  
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.  
program, which does not discard any received data.  


Line 107: Line 107:
discarded, plus the separator string.
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:  
Several of the values that control the length of the string received are discussed in this section, using the following terms:  
<table class="syntaxTable">  
<table>  
<tr><th><var>RECVLIM</var> </th>  
<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.
<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.
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>
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>
<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>
<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>
<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.
<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.
Line 122: Line 124:
<td>The size of the target is used in calculating various defaults of the other values here, and it also obviously limits the  
<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>
number of bytes stored in the target and so affects the number of bytes discarded. </td></tr>
<tr><th>discard_len </th>
<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>
<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>
</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><th><i>Item</i></th>
<tr class="head"><th>Item</th>
<th><i>Value when argument is 0</i></th></tr>
<th>Value when argument is 0</th></tr>
<tr><th>max_recvp (of $Sock_RecvPrs)
 
</th><td><var class="term">targ_size</var>
<tr><td><var class="term">maxrecvp</var> argument of <var>$Sock_RecvPrs</var></td>
</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]]

Latest revision as of 00:00, 21 September 2018

Receive parsed string

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for $Sock_RecvPrs is the ReceiveAndParse method.

$Sock_RecvPrs receives, over a Janus Sockets 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.

$Sock_RecvPrs is also callable.

Syntax

[%num =] = $Sock_RecvPrs(sockNum, %recv_targ, [maxrecvp], [prsindx], [opts])

Syntax terms

%num 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.
sockNum The socket number.
%recv_targ A %variable or an IMAGE item (and never a SOUL 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 $Sock_RecvPrs.
maxrecvp 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. If this argument is 0 and the receive argument is a Longstring, the received data is limited to 2,147,483,647 bytes.

prsindx This optional argument is is a %variable or IMAGE 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 RECVLIM bytes or if it is not found after more than the number of data bytes specified by the effective value of the maxrecvp argument.
opts This optional argument is an option string which can contain any of the following:
BINARY This indicates that regardless of the socket's BINARY or CHAR parameter, data is not translated when saved in the receive target. The received string can be translated later in the program using the $Sock_Tran_In function.
CHAR This indicates that 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 parameter.
PRSTOK [AMBIG|]hexstr[|hexstr]... 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 $Sock_Set, or as an argument on the $Sock_RecvPrs function, PRSTOK must not be NONE when using $Sock_RecvPrs.

$Sock_RecvPrs return values

  • $Sock_RecvPrs returns the value -1 if the socket is not open and ONRESET CONTINUE is in effect for the socket.
  • $Sock_RecvPrs returns a number greater than 0 which is the number of bytes received from of the socket stream. Lengths: maximum, truncation, RECVLIM explains how the term number of bytes received is used, and discusses the maxrecvp argument and other values affecting the received string.
  • $Sock_RecvPrs returns zero to indicate there is no data remaining to be received on the connection, that is, if FIN has been received or the RECVLIM has been reached.

Usage notes

  • You use $Sock_RecvPrs 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, $Sock_Recv, when the protocol in use establishes the length of a data item before it appears in the socket stream.
  • The prsindx argument is used in case there is more than one alternative in the PRSTOK setting, and you need to distinguish which one of them terminated the received value. For example, with the input stream of X'36370D38390D', the following expression will store the value 2 in the variable %prs.

    $Sock_RecvPrs(%sk, %str, , %prs, 'PRSTOK AMBIG|0D0A|0D|0A')

    Note that this example uses ambiguous PRSTOK strings (0D is a prefix of 0D0A). Considerations for this are discussed in Ambiguous PRSTOK strings.

    The PRSTOK 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 ESC character (hexadecimal 1B) to indicate that it precedes a character that is to be taken literally.

    For example, if the data contains non-separator instances of CR and ESC:

    %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 ...

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 $Sock_RecvPrs 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 %s) of each line of HTML is examined by the SOUL program.

A complete version of this program is shown in Simple echo of HTTP/HTML. See 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 $Sock_RecvPrs 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 $Sock_RecvPrs", it may be more than the string that $Sock_RecvPrs stores in the receive target. This is for the following two reasons:

  1. The separator string is part of the string received, but it is not stored in the receive target.
  2. The string before the separator may exceed the size of the target, and thus can be partially discarded (or "truncated").

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:

RECVLIM 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 $Sock_Recv and $Sock_RecvPrs) to a predetermined total number of bytes. RECVLIM can be set in a $Sock_Set call, and subsequent receive operations decrement from RECVLIM the number of bytes received, until it reaches zero (at which point a$Sock_Recv call will return a 0, just as if a FIN had been received.

When RECVLIM is greater than zero, no receive operation will use any bytes beyond the window.

A good example of the use of RECVLIM is obtaining a web page, whose length is (usually) specified in the "Content-length" field of the HTTP response header.
len_to_end 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.
max_recvp This corresponds to the maxrecvp argument of the $Sock_RecvPrs 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 maxrecvp argument of $Sock_RecvPrs, making the effective value "infinite." The number of bytes received by $Sock_RecvPrs will not exceed the effective value of this argument plus the length of the separator string. The effective value of max_recvp if the maxrecvp argument of $Sock_RecvPrs is 0 (its default), is discussed below.

targ_size 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.
discard_len This is the number of bytes received minus the length of the separator string, minus targ_size. It will always be zero, unless max_recvp is greater than targ_size.

Argument max_recvp defaults to 0; if they are omitted, or if it is coded as 0, its effective value is shown here:

Item Value when argument is 0
maxrecvp argument of $Sock_RecvPrs targ_size

Truncation can only occur if max_recvp > targ_size, which cannot happen if the target is a Longstring.

If a separator string is not found due to a limit imposed by RECVLIM, len_to_end, or max_recvp, then zero is stored in the parse index target (the %prsindx argument).