TAKESOCKET

The TAKESOCKET macro acquires a socket from another program and creates a new socket. Typically, a subtask issues this macro using client ID and socket descriptor data that it obtained from the concurrent server.

Notes:

When TAKESOCKET is issued, a new socket descriptor is returned in RETCODE. You should use this new socket descriptor in later macros such as GETSOCKOPT, which require the S (socket descriptor) parameter.
Both concurrent servers and iterative servers use this interface. An iterative server handles one client at a time. A concurrent server receives connection requests from multiple clients and creates subtasks that process the client requests. When a subtask is created, the concurrent server gets a new socket, passes the new socket to the subtask, and dissociates itself from the connection. The TCP⁄IP Listener program is an example of a concurrent server.

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.


>>-EZASMI--TYPE=TAKESOCKET--,CLIENT--=--+-address--+------------>
                                        +-*indaddr-+   
                                        '-(reg)----'   

>--,SOCRECV--=--+-address--+--,ERRNO--=--+-address--+----------->
                +-*indaddr-+             +-*indaddr-+   
                '-(reg)----'             '-(reg)----'   

>--,RETCODE--=--+-address--+--+----------------------+---------->
                +-*indaddr-+  '-,NS--=--+-number---+-'   
                '-(reg)----'            +-address--+     
                                        +-*indaddr-+     
                                        '-(reg)----'     

>--+---------------------------+--+-------------------------+--->
   +-,ECB--=--+-address--+-----+  '-,ERROR--=--+-address--+-'   
   |          +-*indaddr-+     |               +-*indaddr-+     
   |          '-(reg)----'     |               '-(reg)----'     
   '-,REQAREA--=--+-address--+-'                                
                  +-*indaddr-+                                  
                  '-(reg)----'                                  

>--+------------------------+----------------------------------><
   '-,TASK--=--+-address--+-'   
               +-*indaddr-+     
               '-(reg)----'

Keyword

Description

CLIENT

Input parameter. The client data returned by the GETCLIENTID macro.

Field: Description
DOMAIN: Input parameter. A fullword binary number set to the domain of the program that is giving the socket. For TCP⁄IP the value is a decimal 2, indicating AF_INET, or a decimal 19, indicating AF_INET6.
Note: The TAKESOCKET can only acquire a socket of the same address family from a GIVESOCKET.
NAME: An 8-byte character field set to the MVS™ address space identifier of the program giving the socket.
TASK: Input parameter. Specifies an 8-byte field. This field must match the value of the SUBTASK parameter on the INITAPI for the MVS task that issued the GIVESOCKET request.
RESERVED: Input parameter. A 20-byte reserved field. This field is required, but not used.

SOCRECV

Input parameter. A halfword binary field containing the socket descriptor number assigned by the application that called GIVESOCKET.

ERRNO

Output parameter. A fullword binary field. If RETCODE is negative, this field contains an error number. See Socket call error return codes for information about ERRNO return codes.

RETCODE

Output parameter. A fullword binary field.

Value: Description
0 or >0: Contains the new socket descriptor.
-1: Check ERRNO for an error code.

NS

Input parameter. A value or a halfword binary number specifying the socket descriptor number for the new socket. If a number is not specified, the interface assigns a socket number.

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.