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 0 RETCODE indicates that the connection was completed.
- A nonzero RETCODE with an ERRNO of 36 (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.

The following requirements apply to this call:

Authorization:

Supervisor state or problem state, any PSW key.

Dispatchable unit mode:

Task.

Cross memory mode:

PASN = HASN.

Amode:

31-bit or 24-bit.

Note: See "Addressability mode (Amode) considerations" under CALL instruction API environmental restrictions and programming requirements.

ASC mode:

Primary address space control (ASC) mode.

Interrupt status:

Enabled for interrupts.

Locks:

Unlocked.

Control parameters:

All parameters must be addressable by the caller and in the primary address space.

Figure 1 shows an example of CONNECT call instructions.

Figure 1. CONNECT call instruction example

    WORKING-STORAGE SECTION.
        01  SOC-FUNCTION    PIC X(16)  VALUE IS 'CONNECT'.
        01  S               PIC 9(4) BINARY.

    * IPv4 socket address structure.
        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).

    * IPv6 socket address structure.
        01  NAME.
            03  FAMILY      PIC 9(4) BINARY.
            03  PORT        PIC 9(4) BINARY.
            03  IP-ADDRESS  PIC 9(8) BINARY.
            03  FLOWINFO    PIC 9(8) BINARY.
            03  IP-ADDRESS.
                10 FILLER   PIC 9(16) BINARY.
                10 FILLER   PIC 9(16) BINARY.
            03  SCOPE-ID    PIC 9(8) BINARY.
        01  ERRNO           PIC 9(8) BINARY.
        01  RETCODE         PIC S9(8) BINARY.
 
 
   PROCEDURE DIVISION.
 
    CALL 'EZASOKET' USING SOC-FUNCTION S NAME ERRNO RETCODE.

For equivalent PL/I and assembler language declarations, see Converting parameter descriptions.