CONNECT

The CONNECT call is issued by a client to establish a connection between a local socket and a remote socket.

Stream Sockets

For stream sockets, the CONNECT call is issued by a client to establish connection with a server. The call performs two tasks:

It completes the binding process for a stream socket if a BIND call has not been previously issued.
It attempts to make a connection to a remote socket. This connection is necessary before data can be transferred.

UDP Sockets

For UDP sockets, a CONNECT call need not precede an I/O call, but if issued, it allows you to send messages without specifying the destination.

The call sequence issued by the client and server for stream sockets is:

The server issues BIND and LISTEN to create a passive open socket.
The client issues CONNECT to request the connection.
The server accepts the connection on the passive open socket, creating a new connected socket.

The blocking mode of the CONNECT call conditions its operation.

If the socket is in blocking mode, the CONNECT call blocks the calling program until the connection is established, or until an error is received.
If the socket is in nonblocking mode the return code indicates whether the connection request was successful.
- A zero RETCODE indicates that the connection was completed.
- A nonzero RETCODE with an ERRNO EINPROGRESS indicates that the connection is not completed but since the socket is nonblocking, the CONNECT call returns normally.
The caller must test the completion of the connection setup by calling SELECT and testing for the ability to write to the socket.

The completion cannot be checked by issuing a second CONNECT. For more information, see SELECT.

Important: IPv6 support is not available with TCP/IP for z/VSE. Any reference to IPv6 addresses or address structures do not apply, if this program is used.

Example in COBOL

    WORKING STORAGE
        01  SOC-FUNCTION    PIC X(16)  VALUE IS 'CONNECT'.
        01  S               PIC 9(4) BINARY.
        01  NAME.
            03  FAMILY      PIC 9(4) BINARY.
            03  PORT        PIC 9(4) BINARY.
            03  IP-ADDRESS  PIC 9(8) BINARY.
            03  RESERVED    PIC X(8).
        01  ERRNO           PIC 9(8) BINARY.
        01  RETCODE         PIC S9(8) BINARY.


    CALL 'EZASOKET' USING SOC-FUNCTION S NAME ERRNO RETCODE.

For equivalent PL⁄I and assembler language declarations, see Converting Parameter Descriptions.

Parameter Values Set by the Application

SOC-FUNCTION

A 16-byte field containing CONNECT. Left justify the field and pad it on the right with blanks.

S

A halfword binary number specifying the socket descriptor of the socket that is to be used to establish a connection.

NAME

Input parameter. The NAME parameter for CONNECT specifies the IPv4 or IPv6 socket address of the target to which the local, client socket is to be connected. Include the PRD1.MACLIB(EZBREHST) macro to get the assembler mappings for the socket address structure. The socket address structure mappings begin at the SOCKADDR label. The AF_INET socket address structure fields start at the SOCK_SIN label. The AF_INET6 socket address structure fields start at the SOCK_SIN6 label.

The IPv4 socket address structure contains the following fields:

Field: Description
FAMILY: A halfword binary field specifying the IPv4 addressing family. For TCP/IP the value is a decimal 2, indicating AF_INET.
PORT: A halfword binary field specifying the client's port number.
IPv4-ADDRESS: A fullword binary field specifying the 32-bit IPv4 Internet address.
RESERVED: Specifies eight bytes of binary zeros. This field is required, but is not used.

The IPv6 socket address structure contains the following fields:

Field: Description
NAMELEN: A 1-byte binary field that specifies the length of the IPv6 socket address structure. Any value specified by the use of this field is ignored, if processed as input. The field is set to 0, if processed as output.
FAMILY: A 1-byte binary field that specifies the IPv6 addressing family. For TCP/IP the value is a decimal 19, indicating AF_INET6.
PORT: A halfword binary field that is set to the client port number.
FLOW-INFO: A fullword binary field specifying the traffic class and flow label. This value of this field is undefined.
IPv6-ADDRESS: A 16-byte binary field that is set to the 128-bit IPv6 Internet address, in network byte order, of the client machine.
SCOPE-ID: A fullword binary field which identifies a set of interfaces as appropriate for the scope of the address carried in the IPv6-ADDRESS field. For a link scope IPv6-ADDRESS, SCOPE-ID contains the link index for the IPv6-ADDRESS. For all other address scopes, SCOPE-ID is undefined.

Parameter Values Returned to the Application

ERRNO

A fullword binary field. If RETCODE is negative, this field contains an error number. See ERRNO Values for information about ERRNO return codes.

RETCODE

A fullword binary field that returns one of the following:

Value: Description
0: Successful call
-1: Check ERRNO for an error code