ReceiveAndParse (Socket function)

<section begin=dpl_desc/><section end=dpl_desc/>

ReceiveAndParse is a member of the Socket class.

This method receives a string over a Janus Sockets connection. It is designed for 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. The ReceiveAndParse function has an effect similar to $Sock_Recvprs.

Syntax

%len = %socko:ReceiveAndParse(%target, [maxrecvp], [%prsindx], [opts])

Syntax terms

%len	A numeric string to contain the count of the number of bytes received, or to contain 0, if the operation cannot be performed.
%socko	A variable or an expression that is a reference to a Socket object.
%target	A %variable or an IMAGE 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 %len value.
maxrecvp	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 maxrecvp is 0 and target is a Longstring, the received data is limited to 2,147,483,647 bytes. The maxrecvp value must not exceed 2,147,483,647. maxrecvp may have the special value -1 to indicate there is no limit to the number of bytes received.
%prsindx	This optional argument is a %variable or IMAGE item to store the index number (positive integer) of the parse token found in the received data. %prsindx 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 maxrecvp.
opt	An option string, which can contain either of the following: BINARY 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 CHAR 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]... 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 Set or ReceiveAndParse methods, PRSTOK must not be NONE or ReceiveAndParse will fail.

Usage notes

• ReceiveAndParse return values:
  • ReceiveAndParse returns the value -1 if the socket is not open and ONRESET CONTINUE is in effect for the socket.
  • ReceiveAndParse returns a number greater than 0 which is the number of bytes received from of the socket stream. "Lengths: maximum, truncation, RECVLIM" explains the use of the term number of bytes received, and it discusses the maxrecvp argument and other values affecting the received string.
  • ReceiveAndParse 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.
• In general, you use ReceiveAndParse 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). You use the alternate receive operation, Receive, when the protocol in use establishes the length of a data item before it appears in the socket stream.
• The %prsindx argument is used if there is more than one alternative in the PRSTOK set, and you need to distinguish which alternative 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.

  %sk:ReceiveAndParse(%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 %sok:Set('PRSTOK', '0D|1B') Repeat %r = %sok:ReceiveAndParse(%targ, %sep) If %sep eq 2 then %r = %sok:Receive(%junk) %targ = %targ With %junk End If ...

Example

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 second argument to ReceiveAndParse 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 User Language program.

%s = %sock:Set('PRSTOK', '0D0A|0A|0D') Repeat %rc = %sock:ReceiveAndParse(%s, -1) Print %s If %rc le 0 then Loop End End If End Repeat %rc = %sock:Close