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

Read syntax diagramSkip visual syntax diagramEZASMITYPE=GIVESOCKET ,S= numberaddress*indaddr(reg) ,CLIENT= address*indaddr(reg) ,ERRNO= address*indaddr(reg) ,RETCODE= address*indaddr(reg) ,ECB=address* indaddr( reg),ERROR=address*indaddr(reg),TASK=address*indaddr(reg)

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.