$Sock_Recv
Receive string based on count
Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for $Sock_Recv is the Receive method.
$Sock_Recv receives a string of bytes on a Janus Sockets connection, typically to obtain a fixed-length string, and also to allow receipt of additional "already-buffered" bytes.
$Sock_Recv is also a callable function.
Syntax
[%num =] $Sock_Recv(sockNum, %recv_targ, [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_Recv 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_Recv. | ||||
| maxbytes | 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 minbytes argument and 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. | ||||
| minbytes | 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 RECVLIM 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 maxbytes argument. Valid values must be from 0 to 2,147,483,647, and must not exceed the effective value of maxbytes. | ||||
| opts | This optional argument is an option string which can contain any of the following:
|
$Sock_Recv return values
- $Sock_Recv returns the value -1 if the socket is not OPEN and ONRESET CONTINUE is in effect for the socket.
- $Sock_Recv returns a number greater than 0 (which is the number of bytes received from the socket stream) if at least minbytes are stored in the target. Lengths: maximum, minimum, truncation, RECVLIM explains how the term number of bytes received is used, and it discusses the maxbytes and minbytes arguments and other values affecting the received string. The return value from $Sock_Recv can be less than the value of minbytes.
- Formerly, $Sock_Recv would return 0 to indicate that the length of the received
string is less than minbytes. 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
FINhas been received.$Sock_Recv now returns 0 to indicate that there is no more data to be received. Calling $Sock_Recv (or $Sock_RecvPrs) again in this situation, without at the very least setting RECVLIM to a new value, will result in request cancellation.
Usage notes
In general, you use $Sock_Recv 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, $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).
%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 $Sock_Recv 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 $Sock_Recv" may be more than the string that $Sock_Recv 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 $Sock_Recv," is a reference to the string stored in the target plus any subsequent bytes that are discarded. If the target is a Longstring, no bytes would ever be discarded, since the maximum size of a Longstring is the same as the greatest number of bytes $Sock_Recv will ever receive.
The several 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 i When RECVLIM has been set, 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, the len_to_end term is used to indicate various cases. |
| max_recv | This corresponds to the maxbytes argument of the $Sock_Recv 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 $Sock_Recv will not exceed the effective value of this argument. The effective value of max_recv if argument 3 is 0 (its default), is discussed below. |
| min_recv | This corresponds to the minbytes argument of the $Sock_Recv function call. You only need to provide this argument for a variable length receive. The receive initiated by $Sock_Recv will only complete if min_recv bytes are received, or if the limit to the stream (RECVLIM or len_to_end) is reached. The effective value of min_recv, if minbytes 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 targ_size. It will always be zero, unless max_recv is greater than targ_size. |
Arguments max_recv and min_recv both default to 0; if they are omitted, or if they are coded as 0, their effective values are shown here:
| Item | Value when argument is 0 |
|---|---|
| max_recv | larger of min_recv and targ_size |
| min_recv | the effective value of max_recv |
Truncation can only occur if max_recv > targ_size, which cannot happen if the target is a Longstring.
A variable length receive, which is a fairly unusual operation, is only possible if min_recv differs from max_recv; therefore, you will generally not code the minbytes argument of $Sock_Recv.
Less than minbytes available
Formerly, if $Sock_Recv was called and the number of bytes
remaining on the connection within the remaining RECVLIM was
less than the effective value of the minbytes argument,
$Sock_Recv 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, FIN 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.
It is now the case that if $Sock_Recv is called and the number of bytes remaining on the connection within the remaining RECVLIM is less than the effective value of the minbytes argument, $Sock_Recv returns the number of bytes read.
In such a case, if the application determines that the number of bytes
returned is less than minbytes,
it knows that either RECVLIM
must have been hit or a FIN must have been received.
Alternatively, the application can forego checking for this case and
simply wait until $Sock_Recv returns a zero.
This allows a simple receive loop structure like:
Do While $Sock_Recv(%sock, %str) ... End Do
However, with the use of Longstrings, an application can simply receive everything up to RECVLIM or the end of a stream with a simple call like:
%rc = $Sock_Recv(%sock, %longstr)