takesocket (BPX1TAK, BPX4TAK) — Acquire a socket from another program

Function

The takesocket callable service acquires a specified socket from the program that is identified in the Clientid parameter.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1TAK):	31-bit
AMODE (BPX4TAK):	64-bit
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 BPX1TAK,(Clientid,
              Socket_Id,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4TAK with the same parameters.

Parameters

Clientid

Supplied parameter

Type:: Structure
Length:: Length of BPXYCID

The name of a structure that contains Clientid information that identifies the (server) program from which the socket is to be taken. This information is typically obtained with the getclientid (BPX1GCL, BPX4GCL) service, issued by the server and passed to the slave. See BPXYCID — Map the returning structure for getclientid() for more information about the format of this field. Clientid input may be as follows:

CIdDomain

Domain of the socket that is to be taken. See BPXYSOCK — Map SOCKADDR structure and constants for more information about the values that are defined for this field.

CIdName

One of the following:

The server program's address space name
A fullword of binary zeros followed by the server program's process id.

CIdTask

The server program's subtask identifier (supplied only if the address space name was supplied in the CIdName field).

CIdReserved

Binary zeros.

Socket_Id

Supplied parameter

Type:: Integer
Length:: Fullword

An identifier for the socket that is being taken. This is supplied by the server program, and is either the socket descriptor obtained from an accept, or the socket token returned on a givesocket (BPX1GIV, BPX4GIV) service if givesocket was invoked with CIdType=CId#Close.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the takesocket service returns one of the following:

-1 if the request is not successful.
If not -1, the return value is the new socket descriptor.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the takesocket service stores the return code. The takesocket 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 takesocket service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EBADF	The Socket_Id does not specify a valid socket that is owned by the other application; or the socket has already been taken.
EACCES	The other application did not give the socket to your application.
EFAULT	Using the Clientid parameter as specified would result in an attempt to access storage that is outside the caller's address space.
EINVAL	The Clientid parameter does not specify a valid client identifier: either the client's process cannot be found, or the client's process was found, but it has no outstanding givesockets.
EMFILE	The socket descriptor table is already full.
EPERM	The givesocket security label does not match the takesocket security label (JrUserNotAuthorized).

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the takesocket service stores the reason code. The takesocket 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

The takesocket callable service used to be an MVS™ TCP/IP API, and was added to the z/OS UNIX callable services to allow migration of applications to a single library.
The Clientid output of getclientid (BPX1GCL, BPX4GCL) that is issued by the server program and passed to the slave is intended to be used as the input Clientid of the takesocket service. This identifies the program from which the socket is to be taken. By using a FunctionCode of 2 on the getclientid service to obtain Clientid information that is to be used as the Clientid input of the takesocket service, the best performance of the takesocket service is achieved.

Related services

Characteristics and restrictions

There are no restrictions on the use of the takesocket service.