socket or socketpair (BPX1SOC, BPX4SOC) — Create a socket or a pair of sockets

Function

The socket or socketpair callable service creates a socket or a pair of sockets for communication.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task or SRB
Cross memory mode:	PASN = HASN
AMODE (BPX1SOC):	31-bit task or SRB mode
AMODE (BPX4SOC):	64-bit task mode only
ASC mode:	Primary mode
Interrupt status:	Enabled for interrupts
Locks:	Unlocked
Control parameters:	All parameters must be addressable by the caller and in the primary address space.

Format

CALL BPX1SOC,(Domain,
              Type,
              Protocol,
              Dimension,
              Socket_vector,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4SOC with the same parameters.

Parameters

Domain

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a field that contains the address domain requested. See BPXYSOCK — Map SOCKADDR structure and constants for more information about the values that are defined for this field.

Type

Supplied and returned parameter

Type:: Integer
Length:: Fullword

The name of a field that contains the type of socket that is to be created. Some of the socket types are:

Sock#_Stream: Provides sequenced, two-way byte streams that are reliable and connection-oriented. They support out-of-band data.
Sock#_Dgram: Provides 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.
Sock#_Raw: Supports AF_INET and AF_INET6. You must be a superuser to use this type.

See BPXYSOCK — Map SOCKADDR structure and constants for more information about the values that are defined for this field.

Protocol

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a field that contains the protocol requested. See BPXYSOCK — Map SOCKADDR structure and constants for more information about the values that are defined for this field.

Dimension

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a field that contains the number of sockets to be returned. The value of this field determines whether the service performed is socket or socketpair. See BPXYSOCK — Map SOCKADDR structure and constants for more information about the values that are defined for this field.

Socket_vector

Supplied parameter

Type:: Integer
Length:: Doubleword

The name of a doubleword field into which a socket descriptor or pair of socket descriptors is to be stored.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the socket or socketpair service returns one of the following:

0, if the request is successful.
-1 if the request is not successful.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the socket or socketpair service stores the return code. The socket or socketpair service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The socket or socketpair service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EACCES	Permission is denied.
EAFNOSUPPORT	The address family that was specified with the Domain parameter is not supported.
EAGAIN	The resource is temporarily unavailable. The following reason code can accompany the return code: JRTcpNotActive.
EINVAL	Dimension is not a valid value. Only 1 or 2 can be specified for this parameter. The following reason code can accompany the return code: JRInvalidParms.
EIO	There has been a network or transport failure. The following reason code can accompany the return code: JRPFSdead.
ENOBUFS	A buffer could not be obtained. The following reason code can accompany the return code: JROutofSocketCells.
EPROTONOSUPPORT	The Protocol parameter is incorrect. It is not 0. The following reason code can accompany the return code: JRSocketProtocolInvalid.
EPROTOTYPE	The socket type is not supported by the protocol.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the socket or socketpair service stores the reason code. The socket or socketpair service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.

Usage notes

See Callable services available to SRB mode routines for more information about programming considerations for SRB mode.
The socket callable service is invoked by specifying 1 (Sock#dim_socket) for the Dimension parameter.
The socketpair callable service is invoked by specifying 2 (Sock#dim_socketpair) for the dimension parameter. Socketpair returns 2 socket descriptors in the socket_vector parameter. The sockets are unnamed and connected.
These usage notes apply for IPv6 sockets:
- An AF_INET6 socket may be opened only if there is at least one IPv6-capable stack active at the time of the call.
- If a process has stack affinity under CINET, and that single stack is not IPv6-capable, the call will fail.
- When an IPv6 socket is created through CINET, CINET creates AF_INET6 subsockets to IPv6 stacks and IPv4 sockets to IPv4 stacks.
Creating a socket with stack affinity:
You can use SOCK#DIM_SOCKETWAFFINITY and SOCK#DIM_SOCKETPAIRWAFFINITY to create a socket or a socket pair with affinity to one specific stack under Common INET. The stack name is passed in the Socket_vector parameter, and this field is overlaid with the output socket descriptor or descriptors when the call is successful. The name is in upper case, left-justified, and padded with blanks. This is the same name that was specified on the SUBFILESYSTYPE NAME() statement that defined this stack in BPXPRMxx.

If Common INET is not installed, the stack name is ignored. If Common INET is installed and the stack name does not match any stack configured under CINET, the call fails with a return code of EIBMBADTCPNAME.

This affinity overrides any process-level stack affinity for this one socket only.

Note to PFS implementers: This option is not available for the Master Socket opened as part of stack initialization.
UNIX domain sockets (AF_UNIX) do not support being called in SRB-mode.

Related services

None.

Characteristics and restrictions

There are no restrictions on the use of socket or socketpair.

Examples

For an example using this callable service, see BPX1SOC (socket or socketpair) example.