ReceiveAndParse (Socket function) - Revision history

JAL at 20:43, 23 September 2014

2014-09-23T20:43:54Z

← Older revision		Revision as of 20:43, 23 September 2014
Line 5:		Line 5:
	is not known beforehand but which is terminated by a known string or by		is not known beforehand but which is terminated by a known string or by
	one of a known set of strings.		one of a known set of strings.
	The <var>ReceiveAndParse</var> function has an effect similar to <var>[[$~~Sock_Recvprs~~]]</var>.		The <var>ReceiveAndParse</var> function has an effect similar to <var>[[$Sock_RecvPrs]]</var>.

	==Syntax==		==Syntax==

JAL2: /* See also */

2012-06-08T21:15:24Z

JAL2: /* Example */

2012-06-08T21:12:01Z

Example

← Older revision		Revision as of 21:12, 8 June 2012
Line 199:		Line 199:
	</p>		</p>

			==See also==
	{{Template:Socket:ReceiveAndParse footer}}		{{Template:Socket:ReceiveAndParse footer}}

JAL2 at 21:11, 8 June 2012

2012-06-08T21:11:12Z

← Older revision		Revision as of 21:11, 8 June 2012
Line 26:		Line 26:
	<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.		If the <var>MaxBytes</var> argument is 0 and the <var>Target</var> argument value 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>		</td></tr>

	<tr><th><var>ParseTokenIndex</var></th>		<tr><th><var>ParseTokenIndex</var></th>
	<td>This optional, name allowed, parameter is a %variable or <var>IMAGE</var> item to store the index number (positive integer) of the parse token found in the received data. <var ~~class="term"~~>~~%prsindx~~</var> 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 <var ~~class="term"~~>~~maxrecvp~~</var>.		<td>This optional, name allowed, parameter is a %variable or <var>IMAGE</var> item to store the index number (positive integer) of the parse token found in the received data. The <var>ParseTokenIndex</var> value is set to 0 if no token is found ''within'' <var>[[#Lengths: maximum, truncation, RECVLIM\|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>MaxBytes</var> argument.
	</td></tr>		</td></tr>

	<tr><th><var>Options</var></th>		<tr><th><var>Options</var></th>
	<td>This optional, name allowed, parameter is an option string, which can contain either of the following:		<td>This optional, name allowed, parameter is an option string, which can contain either of the following:

	<table class="syntaxTable">		<table class="syntaxTable">
	<tr><th><var>BINARY</var></th>		<tr><th><var>BINARY</var></th>
	<td>Regardless of the socket's <var>[[BINARY (JANUS DEFINE parameter)\|BINARY]]</var> or <var>[[CHAR (JANUS DEFINE parameter)\|CHAR]]</var> port parameter, data '''is not translated''' 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>		<td>Regardless of the socket's <var>[[BINARY (JANUS DEFINE parameter)\|BINARY]]</var> or <var>[[CHAR (JANUS DEFINE parameter)\|CHAR]]</var> port parameter, data '''is not translated''' 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 '''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>
	</td></tr></table>		</td></tr></table>

JAL2: /* Syntax terms */

2012-06-08T20:05:45Z

Syntax terms

← Older revision		Revision as of 20:05, 8 June 2012
Line 31:		Line 31:

	<tr><th><var>ParseTokenIndex</var></th>		<tr><th><var>ParseTokenIndex</var></th>
	<td>This optional, name allowed, ~~parameteris~~ a %variable or <var>IMAGE</var> item to store the index number (positive integer) of the parse token found in the received data. <var class="term">%prsindx</var> 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 <var class="term">maxrecvp</var>.		<td>This optional, name allowed, parameter is a %variable or <var>IMAGE</var> item to store the index number (positive integer) of the parse token found in the received data. <var class="term">%prsindx</var> 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 <var class="term">maxrecvp</var>.
	</td></tr>		</td></tr>

JAL2 at 20:02, 8 June 2012

2012-06-08T20:02:48Z

← Older revision		Revision as of 20:02, 8 June 2012
Line 15:		Line 15:
	<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>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>		</td></tr>

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

	<tr><th><var>Target</var></th>		<tr><th><var>Target</var></th>
	<td>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">%~~len~~</var> value.		<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>		</td></tr>

	<tr><th><var>MaxBytes</var></th>		<tr><th><var>MaxBytes</var></th>
	<td>~~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 ~~class="term"~~>~~maxrecvp~~</var> value must not exceed 2,147,483,647.		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.
	<var ~~class="term"~~>~~maxrecvp~~</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>		</td></tr>

	<tr><th><var>ParseTokenIndex</var></th>		<tr><th><var>ParseTokenIndex</var></th>
	<td>This optional ~~argument is~~ a %variable or <var>IMAGE</var> item to store the index number (positive integer) of the parse token found in the received data. <var class="term">%prsindx</var> 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 <var class="term">maxrecvp</var>.		<td>This optional, name allowed, parameteris a %variable or <var>IMAGE</var> item to store the index number (positive integer) of the parse token found in the received data. <var class="term">%prsindx</var> 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 <var class="term">maxrecvp</var>.
	</td></tr>		</td></tr>

	<tr><th><var>Options</var></th>		<tr><th><var>Options</var></th>
	<td>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 BINARY or CHAR parameter ~~(see [[??~~]] ~~refid=binary.)~~, data '''is not translated''' when saved in the receive target. The received string can be translated later in the program using the TranIn method. ~~:Ih1.BINARY key~~</td></tr> <tr><th><var>CHAR</var> </th><td>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 <var>[[XTAB]]</var> parameter.		<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 (JANUS DEFINE parameter)\|BINARY]]</var> or <var>[[CHAR (JANUS DEFINE parameter)\|CHAR]]</var> port parameter, data '''is not translated''' 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 '''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>PRSTOK [AMBIG\|]<i>hexstr</i>[\|<i>hexstr</i>]...
	</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</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>

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

JAL2 at 23:18, 9 December 2011

2011-12-09T23:18:57Z

← Older revision		Revision as of 23:18, 9 December 2011
Line 92:		Line 92:
	</ul>		</ul>

			==Lengths: maximum, truncation, RECVLIM==

			The <var>ReceiveAndParse</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>ReceiveAndParse</var>",
			it may be more than the string that <var>ReceiveAndParse</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 <var>ReceiveAndParse</var> are to the
			string stored in the target plus any subsequent bytes that are discarded,
			plus the separator string.

			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 desired, 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)\|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> 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 <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_recvp</th>
			<td>This corresponds to the <var>Maxbytes</var> argument of the <var>ReceiveAndParse</var> function call.
			It needs to be specified only if you wish to allow truncation,
			or if you wish to limit the string stored in the received
			target to less than the declared the size of the target.
			You can specify that an unlimited number of bytes can be discarded
			by specifying -1 as the <var>Maxbytes</var> argument, making the effective value "infinite".

			The number of bytes received by <var>ReceiveAndParse</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 <var>Maxbytes</var> is 0 (its default) or omitted,
			is <var class="term">targ_size</var>.

			'''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 either <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>ParseTokenIndex</var> argument).
			</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 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>

	==Example==		==Example==

JAL2 at 02:00, 15 November 2011

2011-11-15T02:00:00Z

← Older revision		Revision as of 02:00, 15 November 2011
Line 12:		Line 12:
	===Syntax terms===		===Syntax terms===
	<table class="syntaxTable">		<table class="syntaxTable">
	<tr><th>%~~len~~</th>		<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>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>		</td></tr>
Line 18:		Line 18:
	<td>A variable or an expression that is a reference to a <var>Socket</var> object.		<td>A variable or an expression that is a reference to a <var>Socket</var> object.
	</td></tr>		</td></tr>
	<tr><th>~~%target~~</th>		<tr><th><var>Target</var></th>
	<td>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">%len</var> value.		<td>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">%len</var> value.
	</td></tr>		</td></tr>
	<tr><th>~~maxrecvp~~</th>		<tr><th><var>MaxBytes</var></th>
	<td>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>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 class="term">maxrecvp</var> value must not exceed 2,147,483,647.		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 class="term">maxrecvp</var> value must not exceed 2,147,483,647.
	<var class="term">maxrecvp</var> may have the special value <code>-1</code> to indicate there is no limit to the number of bytes received.		<var class="term">maxrecvp</var> may have the special value <code>-1</code> to indicate there is no limit to the number of bytes received.
	</td></tr>		</td></tr>
	<tr><th>~~%prsindx~~</th>		<tr><th><var>ParseTokenIndex</var></th>
	<td>This optional argument is a %variable or <var>IMAGE</var> item to store the index number (positive integer) of the parse token found in the received data. <var class="term">%prsindx</var> 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 <var class="term">maxrecvp</var>.		<td>This optional argument is a %variable or <var>IMAGE</var> item to store the index number (positive integer) of the parse token found in the received data. <var class="term">%prsindx</var> 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 <var class="term">maxrecvp</var>.
	</td></tr>		</td></tr>
	<tr><th>~~opt~~</th>		<tr><th><var>Options</var></th>
	<td>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 BINARY or CHAR parameter (see [[??]] refid=binary.), data '''is not translated''' when saved in the receive target. The received string can be translated later in the program using the TranIn method. :Ih1.BINARY key</td></tr> <tr><th><var>CHAR</var> </th><td>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 <var>[[XTAB]]</var> parameter.		<td>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 BINARY or CHAR parameter (see [[??]] refid=binary.), data '''is not translated''' when saved in the receive target. The received string can be translated later in the program using the TranIn method. :Ih1.BINARY key</td></tr> <tr><th><var>CHAR</var> </th><td>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 <var>[[XTAB]]</var> parameter.
	</td></tr>		</td></tr>

JALWiccan: 1 revision

2011-11-15T01:23:46Z

1 revision

← Older revision	Revision as of 01:23, 15 November 2011
(No difference)

JAL2 at 01:23, 15 November 2011

2011-11-15T01:23:45Z

← Older revision		Revision as of 01:23, 15 November 2011
Line 15:		Line 15:
	<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>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>		</td></tr>
	<tr><th>~~%socko~~</th>		<tr><th>socket</th>
	<td>A variable or an expression that is a reference to a <var>Socket</var> object.		<td>A variable or an expression that is a reference to a <var>Socket</var> object.
	</td></tr>		</td></tr>

← Older revision		Revision as of 21:15, 8 June 2012
Line 200:		Line 200:

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