CONNECT
A client application uses the CONNECT command to establish a connection between a local socket and a remote socket.
The command supports both blocking and nonblocking sockets. When the socket is in blocking mode, the function does not return until a connection with the remote peer is established or until an error is received. When the socket is in nonblocking mode, the function returns immediately with either the 36 EINPROGRESS return code or an error.
The CONNECT command performs differently depending on
the socket type:
- Stream (TCP) sockets
- If the application has not already issued an explicit bind, the CONNECT command completes the bind of the socket. The API then attempts to establish a connection to the remote socket that is specified by the name parameter. You can call the CONNECT command only once. Issuing additional CONNECT commands results in a 56 EISCONN error.
- Datagram (UDP) sockets
- The CONNECT command enables an application to associate a socket with the socket name of a peer. The socket then is considered to be a connected UDP socket. You can call the CONNECT command multiple times with different peer names to change the socket association.
Rules:
- Using the CONNECT command on a UDP socket does not change the UDP protocol from a connectionless to a connection-based protocol. The UDP socket remains connectionless. The primary benefit of using connected UDP sockets is to limit communication with a single remote application.
- When a UDP socket becomes a connected UDP socket, it can no longer use the SENDTO and RECVFROM commands. Connected UDP sockets use the socket commands READ, WRITE, SEND, or RECV to communicate with the remote peer, instead of using the SENTO and RECVFROM commands.
Tips:
- For nonblocking sockets, use the SELECT command to determine when a connection has been established. Test for the ability to write to the socket.
- A connected UDP socket can revert back to an unconnected UDP socket by calling CONNECT with 0 or AF_UNSPEC specified in the domain field of the name parameter.
Format
Parameters
- socketid
- The descriptor of the local socket.
- name
- Identifies the remote socket. The format for the name parameter depends on the socket type:
- AF_INET sockets (IPv4)
- name = "domain portid ipaddress"
- AF_INET6 sockets (IPv6)
- name = "domain portid flowinfo ipaddress scopeid"
- The domain value is the decimal number 2 for AF_INET and the decimal number 19 for AF_INET6.
- The portid value is the port number.
- The ipaddress value is the IP address of the remote host. It must be an IPv4 address for AF_INET and an IPv6 address for AF_INET6.
- The flowinfo value must be 0.
- The scopeid value identifies the interfaces that are applicable for the scope of the address that is specified in the ipaddress field. For a link-local IP address, the scopeid field can specify a link index, which identifies a set of interfaces. For all other scopes, the scopeid field must be set to 0. Setting the scopeid field to 0 indicates that any address type and scope can be specified.
Returned value
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.
Tip: When a connection attempt is made with
a nonblocking socket, the string 36 EINPROGRESS is
returned to the application. The program should check for this condition
when using nonblocking sockets.
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:
- 1 EPERM
- 9 EBADF
- 35 EWOULDBLOCK
- 36 EINPROGRESS
- 37 EALREADY
- 47 EAFNOSUPPORT
- 48 EADDRINUSE
- 49 EADDRNOTAVAIL
- 51 ENETUNREACH
- 56 EISCONN
- 60 ETIMEDOUT
- 61 ECONNREFUSED
The following REXX socket API error numbers can be returned:
- 2001 EINVALIDRXSOCKETCALL
- 2009 ESOCKETNOTDEFINED
LE C/C++ equivalent
int connect(int socket, struct sockaddr *address, int address_len);Code example
/* REXX EZARXR03 */
/*
* This sample demonstrates the use of the INITIALIZE, SOCKET,
* CONNECT, GETSOCKNAME, SEND, RECV, CLOSE and TERMINATE
* socket commands.
*
* The program will INITIALIZE a socket set and create a STREAM
* socket. If successful an attempt will be made to connect to
* port 7 using the loopback address and 7 bytes of data will be
* sent. The program will then wait for the data to be echoed
* back.
*
* Port 7 is the well known port for the ECHO server. The ECHO
* Server for the z/OS Communication Server is the MISCSERV. For
* Information on setting up the MISCSERV see the IP Configuration
* Reference.
*
* The example EZARXR01 can be modified to echo data back by adding
* a SEND command after the RECV command. This is left as an exercise.
*
* GUIDELINE: It is generally recommended that a program loop around
* the RECV command to ensure that all data is read off
* the socket.
*/
src = socket("INITIALIZE","MYSET01");
if perror(src,"INITIALIZE") = 0 then do
src = socket("SOCKET","AF_INET","STREAM");
if perror(src,"SOCKET") = 0 then do
l_socketid = WORD(src,2);
l_RMTname = "AF_INET 7 127.0.0.1";
src = socket("CONNECT",l_socketid,l_RMTname);
if perror(src,"CONNECT") = 0 then do
src = socket("GETSOCKNAME",l_socketid);
if perror(src,"GETSOCKNAME") = 0 then do
l_LOCname = SUBWORD(src,2);
Say "The local socket name is: "l_LOCName;
src = socket("SEND",l_socketid,"*******");
if perror(src,"SEND") = 0 then do
src = socket("RECV",l_socketid);
if perror(src,"RECV") = 0 then
Say "Echoed data: " word(src,3);
end; /* SEND*/
end; /* GETSOCKNAME*/
end; /* CONNECT */
end; /* SOCKET */
src = socket("CLOSE",l_socketid);
src = perror(src,"CLOSE");
end; /* INITIALIZE */
src = socket("TERMINATE","MYSET01");
src = perror(src,"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;