GIVESOCKET

Use the GIVESOCKET command to transfer a socket descriptor to another application that is running on the same host.

The other application can use the TAKESOCKET command to take the socket. If the socket is closed before an application can take it, then the socket is reset. Any stream socket can be given.

Restriction: A socket given by the GIVESOCKET command can be taken only by a process that issues the TAKESOCKET command with the same address family.

Guideline: The application that issues the GIVESOCKET command can use the SELECT command to test for a socket exception condition. The exception condition indicates that the socket has been successfully taken by another application. After the socket has been successfully taken, the application that issued the GIVESOCKET command can safely close the socket. For example, when a server accepts a new connection, the server issues the GIVESOCKET command and then monitors the socket for an exception condition using the SELECT command. The server subtask issues the TAKESOCKET command. After the subtask takes the socket, the server issues the CLOSE command and waits for a new connection request.

Format


>>-SOCKET--(--"GIVESOCKET"--,--socketid--,--clientid--)--------><

Parameters

socketid

The socket descriptor.

clientid

The client ID of the application. The clientid parameter uses the following format:

"domain jobname subtaskid"

where:

domain

The address family of the socket. The following domains are supported:

AF_INET or 2
AF_INET6 or 19

jobname

This optional field specifies the name of the address space that will issue the TAKESOCKET command. If this field is not specified, any address space can take the socket.

Guideline: To prevent possible security exposures, always specify the jobname field.

subtaskid

This optional field specifies the name of the active socket set. It can be specified only if the jobname field is specified also. If the subtaskid field is specified but the value is not the name of the active socket set, then the name of the active socket set is used. If the subtaskid field is not specified, by default the name of the active socket set is used.

Consider the following situation: The GETCLIENTID command returns the following string: AF_INET RUNC1 TTLSCXXX. If the application issues the GIVESOCKET command using the clientid parameter value of "AF_INET RUNC1 BBBB", BBBB is replaced with TTLSCXXXX, because TTLSCXXXX is the name of the active socket set .

Returned value

The command returns a string that contains the return code. The return code can be 0, a REXX socket API error number, or the REXX TCP/IP error number that is set by the socket command. The return code 0 indicates that the requested socket command was completed successfully.

See Socket call error return codes for additional information about the numeric error codes that are returned by this command.

The following REXX socket API error number can be returned:

9 EBADF

The following REXX socket API error numbers can be returned:

2001 EINVALIDRXSOCKETCALL
2005 ESUBTASKNOTACTIVE
2009 ESOCKETNOTDEFINED
2012 EINVALIDNAME

LE C/C++ equivalent

int givesocket(int d, struct clientid *clientid);

Code example

See the EZARXS04 REXX sample in the SEZAINST file for an example of using the GIVESOCKET command.