|
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
>>-SOCKET--(--"CONNECT"--,--socketid--,--name--)---------------><
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"
where - 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
- 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 exampleFigure 1. CONNECT command 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;
|