The CONNECT macro is used by a client to establish a connection
between a local socket and a remote socket.
For stream sockets, the CONNECT macro:
- Completes the binding process for a stream socket if BIND has
not been previously issued.
- Attempts connection to a remote socket. This connection must be
completed before data can be transferred.
For datagram sockets, CONNECT is not essential, but you
can use it to send messages without specifying the destination.
For both types of sockets, the following CONNECT macro
sequence applies:
- The server issues BIND and LISTEN (stream sockets only) to create
a passive open socket.
- The client issues CONNECT to request a connection.
- The server creates a new connected socket by accepting the connection
on the passive open socket.
If the socket is in blocking mode, CONNECT 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 the success of the connection request.
- A 0 RETCODE indicates that the connection was completed.
- A nonzero RETCODE with an ERRNO of 36 (EINPROGRESS) indicates
that the connection could not be completed, but since the socket is
nonblocking, the CONNECT macro completes its processing.
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.
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.
|
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. |
>>-EZASMI--TYPE=CONNECT--,S--=--+-number---+-------------------->
+-address--+
+-*indaddr-+
'-(reg)----'
>--,NAME--=--+-address--+--,ERRNO--=--+-address--+-------------->
+-*indaddr-+ +-*indaddr-+
'-(reg)----' '-(reg)----'
>--,RETCODE--=--+-address--+--+---------------------------+----->
+-*indaddr-+ +-,ECB--=--+-address--+-----+
'-(reg)----' | +-*indaddr-+ |
| '-(reg)----' |
'-,REQAREA--=--+-address--+-'
+-*indaddr-+
'-(reg)----'
>--+-------------------------+--+------------------------+-----><
'-,ERROR--=--+-address--+-' '-,TASK--=--+-address--+-'
+-*indaddr-+ +-*indaddr-+
'-(reg)----' '-(reg)----'
- Keyword
- Description
- S
- Input parameter. A value or the
address of a halfword binary number specifying the socket descriptor.
- NAME
-
Input parameter. The NAME parameter for CONNECT specifies
the IPv4 or IPv6 socket address of the IPv4 or IPv6 IP connection
peer. Include the SYS1.MACLIB(BPXYSOCK) 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 structure
must specify the following fields:
- Field
- Description
- FAMILY
- A halfword binary field specifying the IPv4 addressing family.
For IPv4 the value is always a decimal 2, indicating AF_INET.
- PORT
- A halfword binary field that is set to the server port number
in network byte order. For example, if the port number is 5000 in
decimal, it is set to X'1388'.
- IPv4-ADDRESS
- A fullword binary field specifying the 32-bit IPv4 Internet Protocol address, in network byte order, of the server host
machine. For example, if the Internet Protocol
address is 129.4.5.12 in dotted decimal notation, it is set to X'8104050C'.
- RESERVED
- Specifies 8 bytes of binary zeros. This field is required, but
not used.
The IPv6 socket structure must specify the following
fields:
- Field
- Description
- NAMELEN
- A 1-byte binary field specifying the length of this IPv6 socket
address structure. Any value specified by the use of this field is
ignored when processed as input and the field is set to 0 when processed
as output.
- FAMILY
- A 1-byte binary field specifying the IPv6 addressing family. For
IPv6 the value is a decimal 19, indicating AF_INET6.
- PORT
- A halfword binary field that is set to the port number in network
byte order. For example, if the port number is 5000 in decimal, it
is set to X'1388'.
- FLOW-INFO
- A fullword binary field specifying the traffic class and flow
label. This field must be set to 0.
- IPv6-ADDRESS
- A 16-byte binary field that is set to the 128-bit IPv6 Internet Protocol address, in network byte order, of the client
host machine. For example, if the IPv6 Internet Protocol
address is 12ab:0:0:cd30:123:4567:89AB:cedf in colon-hexadecimal
notation, it is set to X'12AB00000000CD300123456789ABCDEF'.
- 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. A value of 0 indicates the SCOPE-ID field does not identify the set of interfaces
to be used, and can be specified for any address types and scopes.
For a link scope IPv6-ADDRESS, SCOPE-ID can specify a link index which identifies
a set of interfaces. For all other address scopes, SCOPE-ID must be set to 0.
- ERRNO
- Output parameter. A fullword binary
field. If RETCODE is negative, ERRNO contains a valid error number. Otherwise, ignore ERRNO.
See Socket call error return codes for information
about ERRNO return codes.
- RETCODE
- Output parameter. A fullword binary
field that returns one of the following values:
- Value
- Description
- 0
- Successful call.
- -1
- Check ERRNO for an error code.
- ECB or REQAREA
- Input parameter. This parameter is required if you are
using APITYPE=3. It points to a 104-byte field containing:
- For ECB
- A 4-byte ECB posted by TCP/IP when the
macro completes.
- For REQAREA
- A 4-byte user token (set by you) that is presented to your exit
when the response to this function request is complete.
- For ECB/REQAREA
- The last 100 bytes is a storage field used by the interface to
save the state information.
Note: This storage must not be modified until the
macro function has completed and the ECB has
been posted, or the asynchronous exit has been driven.
- ERROR
- Input parameter. The location in your program to receive
control when the application programming interface (API) processing
module cannot be loaded.
- TASK
- Input parameter. The location of the task storage area in your
program.