The GIVESOCKET macro makes the socket available for a
TAKESOCKET macro issued by another program. The GIVESOCKET macro can
specify any connected stream socket. Typically, the GIVESOCKET macro
is issued by a concurrent server program that creates sockets to be
passed to a subtask.
After a program has issued a GIVESOCKET macro for a socket,
it can only issue a CLOSE macro for the same socket. Sockets which
are given but not taken for a period of four days will be closed and
will no longer be available for taking. If a select for the socket
is outstanding, it is posted.
Note: 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=GIVESOCKET--,S--=--+-number---+----------------->
+-address--+
+-*indaddr-+
'-(reg)----'
>--,CLIENT--=--+-address--+--,ERRNO--=--+-address--+------------>
+-*indaddr-+ +-*indaddr-+
'-(reg)----' '-(reg)----'
>--,RETCODE--=--+-address--+--+---------------------------+----->
+-*indaddr-+ +-,ECB--=--+-address--+-----+
'-(reg)----' | +-*indaddr-+ |
| '-(reg)----' |
'-,REQAREA--=--+-address--+-'
+-*indaddr-+
'-(reg)----'
>--+-------------------------+--+------------------------+-----><
'-,ERROR--=--+-address--+-' '-,TASK--=--+-address--+-'
+-*indaddr-+ +-*indaddr-+
'-(reg)----' '-(reg)----'
- Keyword
- Description
- S
- Input parameter. A value or
the address of a halfword binary number specifying the descriptor
of the socket to be given.
- CLIENT
- Input parameter. The client
ID for this application.
- Field
- Description
- DOMAIN
- Input parameter. A fullword binary number specifying the domain
of the client. For TCP⁄IP the value
is a decimal 2, indicating AF_INET, or a decimal 19, indicating AF_INET6.
Note: A socket given by GIVESOCKET can only be taken by a TAKESOCKET with
the same DOMAIN, address family (AF_INET or AF_INET6).
- NAME
- An 8-character field, left-aligned, padded to the right with blanks.
On completion of the call, this field contains the MVS™ address space name of the application that
is going to take the socket. If the socket-taking application is in
the same address space as the socket-giving application, NAME can be obtained using the GETCLIENTID call. If
this field is set to blanks, any MVS address space requesting a socket can take this socket.
- TASK
- Specifies an 8-byte field that is set to the MVS subtask identifier of the socket-taking task
(specified on the SUBTASK parameter on its INITAPI macro). If this
field is set to blanks, any subtask in the address space specified
in the NAME field can take the socket.
- RESERVED
- Input parameter. A 20-byte reserved field. This field is required,
but not used.
- ERRNO
- Output parameter. A fullword
binary field. If RETCODE is negative, ERRNO contains a valid error number. Otherwise,
ignore ERRNO.
See Socket call error return codes for information about ERRNO return codes.
- RETCODE
- Output parameter. A fullword
binary field that returns one of the following values:
- Value
- Description
- 0
- Successful call.
- -1
- Check ERRNO for an error code.
- 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.