RECVFROM

Use the RECVFROM command to receive data on the specified socket.

If the number of bytes is less than the number of bytes requested, the command returns the number of bytes that are available. If the socket is in blocking mode and data is not available on the socket, the command blocks until data arrives. When the socket is in nonblocking mode and data is not available, the command returns the 35 EWOULDBLOCK return code .

Consider the following additional information:

If the socket is a stream socket and the length of the data returned is 0, the remote peer has closed its side of the connection.
If the socket is a datagram socket, the command returns data up to the length specified by the maxlength parameter. The remainder of the datagram is discarded. If the socket is a datagram socket and the amount of data returned is 0, a datagram packet was received with no data.

Guidelines:

Use the RECV command for stream and connected UDP sockets. For stream sockets, data is processed as streams of information with no boundaries separating the data. Applications should place the RECVFROM command in a loop until all the data has been received.
If the socket is a datagram socket, the RECVFROM command returns the name of the remote partner. If the socket is a stream socket, use the command GETPEERNAME to determine the name of the remote partner.
Use the SELECT command to determine whether there is data to be read on the socket.

Tip: If the SO_ASCII socket option is enabled, then the data received is translated from EBCDIC to ASCII.

Format


                                       .-,--10 000----.   
>>-SOCKET--(--"RECVFROM"--,--socketid--+--------------+--------->
                                       '-,--maxlength-'   

>--+--------------+--)-----------------------------------------><
   '-,--recvflags-'

Parameters

socketid

The socket descriptor.

maxlength

The maximum amount of data (in bytes) to be returned. The maxlength parameter can be a number in the range 0-100 000. By default, this parameter is set to 10 000.

recvflags

An optional parameter. Specifies the following receive flags:

MSG_OOB, OOB: Receive out-of-band data (stream sockets only). Even if the OOB flag is not set, out-of-band data can be read if the SO_OOBINLINE option is set for the socket.
MSG_PEEK, PEEK: Peek at the data, but do not destroy data. If the peek flag is set, the next receive operation will read the same data.
MSG_WAITALL, WAITALL: Requests that the function block until the full amount of data requested can be returned (stream sockets only). The function may return a smaller amount of data if the connection is terminated, an error is pending, or SO_RCVTIMEO is set and the timer expired for the socket.

Returned value

The command returns a string that contains the return code, a NAME string, the maximum length of the data returned, and the data. The return code can be 0, a REXX socket API error number, or the REXX TCP/IP error number that is set by the socket command. The return code 0 indicates that the requested socket command was completed successfully.

The following list are examples of what is returned by the RECVFROM command.

IPv4 socket: 0 AF_INET 54004 10.1.2.3 19 This is sample data
IPv6 socket: 0 AF_INET6 54004 0 2001:10:1:2::3 0 19 This is sample data

In the examples, 0 is the return code, AF_INET 54004 10.11.103.1 or AF_INET6 54004 0 2001:10:1:2::3 0 is the socket name of the remote partner, 19 is the length of the data received, and This is sample data is the data that was received on the socket.

For information about the format of the NAME string, see How structures are represented. See Socket call error return codes for additional information about the numeric error codes that are returned by this command.

The following REXX TCP/IP error numbers can be returned:

4 EITNR
5 EIO
9 EBADF
22 EINVAL
35 EWOULDBLOCK
38 ENOTSOCK
45 EOPNOTSUPP
54 ECONNRESET
57 ENOTCONN
60 ETIMEDOUT

The following REXX socket API error numbers can be returned:

2001 EINVALIDRXSOCKETCALL
2005 ESUBTASKNOTACTIVE
2009 ESOCKETNOTDEFINED

LE C/C++ equivalent

int recvfrom(int socket, char *buffer, int length, int flags,
struct sockaddr *address, int *address_length);

Code example

/* REXX EZARXR21 */
/*
 * This sample demonstrates the use of the READ and RECV
 * socket commands.
 *
 * To use the READ command, set the variable g_RECVCMD equal to "READ"
 * to use the RECV command, set the variable g_RECVCMD equal to "RECV"
 *
 * The program creates a listening socket and then goes into a
 * loop and blocks on the accept command. When a new connection is
 * ACCEPTED the program will issue the READ or RECV command until
 * the connection is terminated.
 *
 * If the data received is the string "DONE", then the
 * program will close the accepted socket and wait for a new
 * connection request.
 */
g_RECVCMD = "READ"
src = socket("INITIALIZE","MYSET01",10);
if perror(src,"INITIALIZE") = 0 then do
   src = socket("SOCKET","AF_INET6","STREAM");
   if perror(src,"SOCKET") = 0 then do
      parse var src . l_sockid
      l_name6 = "AF_INET6 54004 0 ::0 0";
      src = socket("BIND", l_sockid, l_name6);
      if perror(src,"BIND") = 0 then do
         src = socket("LISTEN", l_sockid);
         if perror(src,"LISTEN") = 0 then do
            say "Listening on socket "l_sockid;
            do forever
               src = socket("ACCEPT", l_sockid );
               if perror(src,"ACCEPT") = 0 then do
                  parse var src . l_newsockid . ;
                  l_datalen = -1;
                  l_Done = "FALSE";
                  l_totallen = 0;
                  l_packet = "";
                  /* **********************************************
                   * Loop around RECV|READ command until all data has
                   * has been received and the client closes the
                   * connection.
                   * **********************************************/
                  do until l_datalen = 0 | l_done = "TRUE"
                     src = socket(g_RECVCMD,l_newsockid,512);
                     if perror(src,g_RECVCMD) = 0 then do
                        parse var src l_retcode l_datalen l_data
                        if l_datalen > 0 then do
                           l_totallen = l_totallen + l_datalen;
                           if l_packet = "" then do
                              l_packet = l_data;
                              if l_packet = "DONE" then
                                 l_done = "TRUE";
                           end;
                           else l_packet = l_packet||l_data;
                        end;
                        else do

                        /* ***************************************
                         * A data length of zero indicates the
                         * connection has been closed by the
                         * remote side
                         * ***************************************/
                            Say "Connection has been closed",
                                "received "l_totallen" bytes";
                            l_done = "TRUE";
                        end;
                     end;
                     else do
                        l_done = "TRUE";
                     end;
                  end; /* DO READ */
                  src = socket("CLOSE",l_newsockid);
                  src = perror(src,"CLOSE");
               end; /* ACCEPT */
            end; /* DO FOREVER */
         end;
      end;
   end;
end; /* INITIALIZE */
src = perror(socket("TERMINATE","MYSET01"),"TERMINATE");
exit 0;

/* This routine returns -1 if the first word if arg 1 is not zero */
perror: if word(arg(1),1) = 0 then return 0; else
    Say arg(2) "Error : "arg(1);
    return -1;

Figure 1. READ command example