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.
|
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.