z/OS Communications Server: IP Sockets Application Programming Interface Guide and Reference
Previous topic | Next topic | Contents | Contact z/OS | Library | PDF


RECV

z/OS Communications Server: IP Sockets Application Programming Interface Guide and Reference
SC27-3660-00

Use the RECV command to receive data on a specified socket. The RECV command can be issued only against connected sockets.

Consider the following additional information:
  • If the socket is in blocking mode and data is not available, the command blocks until data arrives. If the socket is in nonblocking mode and data is not available, the command returns the 35 EWOULDBLOCK error code.
  • 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 connected datagram socket, the command returns data up to the length specified by the maxlength parameter. The remainder of the datagram is discarded. To ensure that the entire datagram is received, set the maxlength parameter to 65535 or greater.
Guidelines:
  • For stream sockets, data is processed as streams of information with no boundaries separating the data. The application provides record management. Applications should place the command in a loop until all the data has been received.
  • For nonblocking sockets, 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

Read syntax diagramSkip visual syntax diagram
                                   .-,--10 000----.   
>>-SOCKET--(--"RECV"--,--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, the maximum length of the data returned, and the data, for example, 0 19 This is sample 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.

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 recv(int socket, char *buffer, int length, int flags);

Code example

See ACCEPT or READ. To use the RECV command, substitute the command RECV for the command READ.

Go to the previous page Go to the next page




Copyright IBM Corporation 1990, 2014