SOCKET

The SOCKET macro creates an endpoint for communication and returns a socket descriptor representing the endpoint.

Different types of sockets provide different communication services.

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.

Format

Read syntax diagramSkip visual syntax diagramEZASMITYPE=SOCKET ,AF= 'INET''INET6'address*indaddr(reg) ,SOCTYPE= 'STREAM''DATAGRAM'address*indaddr(reg) ,ERRNO= address*indaddr(reg) ,RETCODE= address*indaddr(reg) ,PROTO=address*indaddr(reg),ECB=address* indaddr( reg),ERROR=address*indaddr(reg),TASK=address*indaddr(reg)

Parameters

AF
Input parameter. Specifies the literal INET or INET6, which indicates the internet or TCP⁄IP. Specify one of the following:
'INET’ or a decimal ’2’
Indicates the address being converted is an IPv4 address.
’INET6’ or a decimal ’19’
Indicates the address being converted is an IPv6 address.
AF can also indicate a fullword binary number specifying the address family.
SOCTYPE
Input parameter. A fullword binary field set to the type of socket required. The types are:
1 or 'STREAM'
Stream sockets provide sequenced, two-way byte streams that are reliable and connection-oriented. They support a mechanism for out-of-band data. This is the normal type for TCP/IP.
2 or 'DATAGRAM'
Datagram sockets provide datagrams, which are connectionless messages of a fixed maximum length whose reliability is not guaranteed. Datagrams can be corrupted, received out of order, lost, or delivered multiple times. This type is supported only in the AF_INET domain.
Note: RAW sockets are not supported.
ERRNO
Output parameter. A fullword binary field. If RETCODE is negative, this field contains an error number. See ERRNO Values for information about ERRNO return codes.
RETCODE
Output parameter. A fullword binary field that returns one of the following:
Value
Description
> or = 0
Contains the new socket descriptor
-1
Check ERRNO for an error code
PROTO
Input parameter. A fullword binary number specifying the protocol supported.
ECB
Input parameter. It points to a 160-byte field containing:
  • A four-byte ECB posted by TCP/IP when the macro completes.
  • A 156-byte 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 .
ERROR
Input parameter. The location in your program to receive control, if the application programming interface (API) processing module cannot be loaded.
TASK
Input parameter. The location of the task storage area in your program.

PROTO specifies a particular protocol to be used with the socket. If PROTO is set to 0, the system selects the default protocol number for the domain and socket type requested. The PROTO defaults are TCP for stream sockets and UDP for datagram sockets. If PROTO is set to 17, the UDP Protocol is used. If it is set to 6, the TCP protocol is used.

SOCK_STREAM sockets model duplex byte streams. They provide reliable, flow-controlled connections between peer applications. Stream sockets are either active or passive. Active sockets are used by clients who initiate connection requests with CONNECT. By default, SOCKET creates active sockets. Passive sockets are used by servers to accept connection requests with the CONNECT macro. An active socket is transformed into a passive socket by binding a name to the socket with the BIND macro and by indicating a willingness to accept connections with the LISTEN macro. Once a socket is passive, it cannot be used to initiate connection requests.

In the AF_INET domain, the BIND macro, applied to a stream socket, lets the application specify the networks from which it is willing to accept connection requests. The application can fully specify the network interface by setting the internet address field in the address structure to the internet address of a network interface. Alternatively, the application can set the address in the name structure to zeros to indicate that it wants to receive connection requests from any network.

Once a connection has been established between stream sockets, the data transfer macros READ, WRITE, SEND, RECV, SENDTO, and RECVFROM can be used. Usually, the READ-WRITE or SEND-RECV pairs are used for sending data on stream sockets.

SOCK_DGRAM sockets are used to model datagrams. They provide connectionless message exchange without guarantees of reliability. Messages sent have a maximum size.

The active or passive concepts for stream sockets do not apply to datagram sockets. Servers must still call BIND to name a socket and to specify from which network interfaces it wants to receive datagrams. Wildcard addressing, as described for stream sockets, also applies to datagram sockets. Because datagram sockets are connectionless, the LISTEN macro has no meaning for them and must not be used.

After an application receives a datagram socket, it can exchange datagrams using the SENDTO and RECVFROM macros. If the application goes one step further by calling CONNECT and fully specifying the name of the peer with which all messages are exchanged, then the other data transfer macros READ, WRITE, SEND, and RECV can be used as well. For more information about placing a socket into the connected state, see CONNECT.

Datagram sockets allow message broadcasting to multiple recipients. Setting the destination address to a broadcast address depends on the network interface (address class and whether subnets are used).

Outgoing datagrams have an IP header prefixed to them. Your program receives incoming datagrams with the IP header intact. You can set and inspect IP options by using the SETSOCKOPT and GETSOCKOPT macros.

Use the CLOSE macro to deallocate sockets.