GIVESOCKET
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.
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 CICS Listener program is
an example of a concurrent server.
Important: IPv6
support is not available with TCP/IP for z/VSE. Any reference
to IPv6 addresses or address structures do not apply, if this program
is used.
Format
Parameters
- S
- Input parameter. A value, or the address of a halfword binary number specifying the descriptor of the socket to be given.
- CLIENT
- A structure containing the identifier of the application to which
the socket should be given.
- 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
- Specifies an 8-character field, left-justified, padded to the right with blanks set to the address space name of the application (partition ID) going to take the socket. If this field is left blank, any z/VSE partition can take the socket.
- TASK
- Specifies an eight-character field that can be set to blanks, or to the identifier of the socket-taking VSE subtask. If this field is set to blanks, any subtask in the partition specified in the NAME field can take the socket.
- RESERVED
- A 20-byte reserved field. This field is required, but only used internally.
- ERRNO
- Output parameter. A fullword binary field. If RETCODE is negative,
ERRNO contains a valid error number. Otherwise, ignore ERRNO.
See ERRNO Values for information about ERRNO return codes.
- RETCODE
- Output parameter. A fullword binary field that returns one of
the following:
- Value
- Description
- 0
- Successful call
- -1
- Check ERRNO for an error code
- ECB
- Input parameter. It points to a 160-byte field containing:
- A four-byte ECB posted by TCP/IP when the macro completes.
- A 156-byte 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. - ERROR
- Input parameter. The location in your program to receive control, if the application programming interface (API) processing module cannot be loaded.
- TASK
- Input parameter. The location of the task storage area in your program.