You can specify multiple options with this command; however, at least one option is required.

Format

>>-SOCKET--(--"GETSOCKOPT"--,--socketid--,--levelname----------->

      .---------.      
      V         |      
>--,----optname-+--)-------------------------------------------><

Parameters

socketid

The local socket descriptor.

levelname

The protocol level. The following protocol levels are supported:

IPPROTO_TCP

Retrieve the socket options that are set at the TCP layer

IPPROTO_IP

Retrieve the IPv4 socket options that are set at the IP layer

IPPROTO_IPV6

Retrieve the IPv6 socket options that are set at the IP layer

SOL_SOCKET

Retrieve the socket options that are set at the socket layer

optname

The option to be retrieved. The options that can be retrieved depend on the value of the levelname parameter.

The following rules apply:

• Options that begin with SO_ require the SOL_SOCKET protocol level.
• Options that begin with TCP_ require the IPPROTO_TCP protocol level.
• Options that begin with IP_ require the IPPROTO_IP protocol level.
• Options that begin with IPV6_ require the IPPROTO_IPV6 protocol level.

The following values are supported for the optname parameter:

IP_MULTICAST_IF

(IPv4-only) Retrieves the IPv4 interface address that is used to send outbound multicast datagrams from the socket application. When you specify this option, the GETSOCKOPT command returns a string that contains the return code and interface address, for example, 0 10.11.103.1.

IP_MULTICAST_LOOP

(IPv4-only) Determines what occurs when datagrams are sent to a group to which the sending host belongs. If this option is enabled, the IP layer loops back a copy of multicast datagrams for local delivery. By default, this option is enabled. When you specify this option, the GETSOCKOPT command returns either 1 (enabled) or 0 (disabled).

IP_MULTICAST_TTL

(IPv4-only) Retrieves the IP time-to-live of outgoing multicast datagrams. By default, this option is set to the binary value '01'x, which means that multicast is available to the local subnet only. When you specify this option, the GETSOCKOPT command returns a string that contains the return code and a value in the range 0-255, for example, 0 227.

IPV6_ADDR_PREFERENCES

(AF_INET6 only) Retrieves the IPv6 address preferences to be used when selecting the source address.The IPV6_ADDR_PREFERENCES flags that are returned can be one or more of the following values:

IPV6_PREFER_SRC_HOME

A home IPv6 address is preferred over a care-of IPv6 address.

IPV6_PREFER_SRC_COA

A care-of IPv6 address is preferred over a home IPv6 address.

IPV6_PREFER_SRC_TMP

A temporary IPv6 address is preferred over a public IPv6 address.

IPV6_PREFER_SRC_PUBLIC

A public IPv6 address is preferred over a temporary IPv6 address.

IPV6_PREFER_SRC_CGA

A cryptographically generated IPv6 address is preferred over a non-cryptographically generated IPv6 address.

IPV6_PREFER_SRC_NONCGA

A non-cryptographically generated IPv6 address is preferred over a cryptographically generated IPv6 address.

IPV6_MULTICAST_HOPS

(IPv6-only) Retrieves the hop limit used for outgoing multicast packets. When you specify this option, the GETSOCKOPT command returns a string that contains the return code and the hop limit, which is a number in the range 0-255.

IPV6_MULTICAST_IF

(IPv6-only) Retrieves the index of the IPv6 interface that is used to send outbound multicast datagrams from the socket application. When you specify this option, the GETSOCKOPT command returns a string that contains the return code and the IPv6 interface index, for example, 0 1523.

IPV6_MULTICAST_LOOP

(IPv6-only) Determines what occurs when datagrams are sent to a group to which the sending host belongs. If this option is enabled, the IP layer loops back a copy of multicast datagrams for local delivery. By default, this option is enabled. When you specify this option, the GETSOCKOPT command returns either 1 (enabled) or 0 (disabled).

IPV6_UNICAST_HOPS

(IPv6-only) Retrieves the hop limit used for outgoing unicast IPv6 packets. When you specify this option, the GETSOCKOPT command returns a string that contains the return code and the hop limit, which is a number in the range 0-255.

IPV6_V6ONLY

(IPv6-only) Determines whether the socket is restricted to sending or receiving IPv6 packets only. By default, a socket is not restricted. When you specify this option, the GETSOCKOPT command returns a string that contains the return code and a number: 1 (enabled) or 0 (disabled).

SO_ASCII

(REXX only) Determines whether all incoming data is translated from ASCII to EBCDIC, and whether all outgoing data is translated from EBCDIC to ASCII. This option returns a string that contains the error code and either ON (enabled) or OFF (disabled). If the option is enabled, the name of the translation table is returned also. The following string is an example of what might be returned: 0 ON MYTRANTB.

The translation tables are searched in the following order:

1. user_prefix.subtaskid.TCPXLBIN
2. user_prefix.userid.TCPXLBIN
3. system_prefix.STANDARD.TCPXLBIN
4. system_prefix.RXSOCKET.TCPXLBIN
5. Internal tables

The following descriptions apply:

• The user_prefix value is either the user ID or the job name of the REXX program.
• The system_prefix value is either TCPIP or the DATASETPREFIX value from the hlq.TCPIP.DATA. You can change the system_prefix value to match your site convention.
• The subtaskid value is the name of the socket set.
• The userid value is the user ID under which the REXX EXEC is running.

When the internal tables are used, the data is converted in the following way:

Figure 1. ASCII to EBCDIC

-------------------------------------------------------------- 
| ASCII      | second hex digit of byte of ASCII data        | 
| to         |-----------------------------------------------| 
| EBCDIC     | 0| 1| 2| 3| 4| 5| 6| 7| 8| 9| A| B| C| D| E| F| 
|------------+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | 0 |00|01|02|03|37|2D|2E|2F|16|05|25|0B|0C|0D|0E|0F| 
|        |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | 1 |10|11|12|13|3C|3D|32|26|18|19|3F|27|1C|1D|1E|1F| 
|        |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | 2 |40|4F|7F|7B|5B|6C|50|7D|4D|5D|5C|4E|6B|60|4B|61| 
|        |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | 3 |F0|F1|F2|F3|F4|F5|F6|F7|F8|F9|7A|5E|4C|7E|6E|6F| 
|        |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | 4 |7C|C1|C2|C3|C4|C5|C6|C7|C8|C9|D1|D2|D3|D4|D5|D6| 
|        |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | 5 |D7|D8|D9|E2|E3|E4|E5|E6|E7|E8|E9|4A|E0|5A|5F|6D| 
|        |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
| first  | 6 |79|81|82|83|84|85|86|87|88|89|91|92|93|94|95|96| 
| hex    |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
| digit  | 7 |97|98|99|A2|A3|A4|A5|A6|A7|A8|A9|C0|6A|D0|A1|07| 
| of     |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
| byte   | 8 |20|21|22|23|24|15|06|17|28|29|2A|2B|2C|09|0A|1B| 
| of     |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
| ASCII  | 9 |30|31|1A|33|34|35|36|08|38|39|3A|3B|04|14|3E|E1| 
| data   |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | A |41|42|43|44|45|46|47|48|49|51|52|53|54|55|56|57| 
|        |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | B |58|59|62|63|64|65|66|67|68|69|70|71|72|73|74|75| 
|        |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | C |76|77|78|80|8A|8B|8C|8D|8E|8F|90|9A|9B|9C|9D|9E| 
|        |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | D |9F|A0|AA|AB|AC|AD|AE|AF|B0|B1|B2|B3|B4|B5|B6|B7| 
|        |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | E |B8|B9|BA|BB|BC|BD|BE|BF|CA|CB|CC|CD|CE|CF|DA|DB| 
|        |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | F |DC|DD|DE|DF|EA|EB|EC|ED|EE|EF|FA|FB|FC|FD|FE|FF| 
-------------------------------------------------------------- 

Figure 2. EBCDIC to ASCII

-------------------------------------------------------------- 
| EBCDIC     | second hex digit of byte of EBCDIC data       | 
| to         |-----------------------------------------------| 
| ASCII      | 0| 1| 2| 3| 4| 5| 6| 7| 8| 9| A| B| C| D| E| F| 
|------------+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | 0 |00|01|02|03|9C|09|86|7F|97|8D|8E|0B|0C|0D|0E|0F| 
|        |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | 1 |10|11|12|13|9D|85|08|87|18|19|92|8F|1C|1D|1E|1F| 
|        |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | 2 |80|81|82|83|84|0A|17|1B|88|89|8A|8B|8C|05|06|07| 
|        |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | 3 |90|91|16|93|94|95|96|04|98|99|9A|9B|14|15|9E|1A| 
|        |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | 4 |20|A0|A1|A2|A3|A4|A5|A6|A7|A8|5B|2E|3C|28|2B|21| 
|        |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | 5 |26|A9|AA|AB|AC|AD|AE|AF|B0|B1|5D|24|2A|29|3B|5E| 
|        |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
| first  | 6 |2D|2F|B2|B3|B4|B5|B6|B7|B8|B9|7C|2C|25|5F|3E|3F| 
| hex    |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
| digit  | 7 |BA|BB|BC|BD|BE|BF|C0|C1|C2|60|3A|23|40|27|3D|22| 
| of     |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
| byte   | 8 |C3|61|62|63|64|65|66|67|68|69|C4|C5|C6|C7|C8|C9| 
| of     |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
| EBCDIC | 9 |CA|6A|6B|6C|6D|6E|6F|70|71|72|CB|CC|CD|CE|CF|D0| 
| data   |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | A |D1|7E|73|74|75|76|77|78|79|7A|D2|D3|D4|D5|D6|D7| 
|        |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | B |D8|D9|DA|DB|DC|DD|DE|DF|E0|E1|E2|E3|E4|E5|E6|E7| 
|        |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | C |7B|41|42|43|44|45|46|47|48|49|E8|E9|EA|EB|EC|ED| 
|        |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | D |7D|4A|4B|4C|4D|4E|4F|50|51|52|EE|EF|F0|F1|F2|F3| 
|        |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | E |5C|9F|53|54|55|56|57|58|59|5A|F4|F5|F6|F7|F8|F9| 
|        |---+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--| 
|        | F |30|31|32|33|34|35|36|37|38|39|FA|FB|FC|FD|FE|FF| 
-------------------------------------------------------------- 

SO_BROADCAST

(REXX only) Determines whether a program can send broadcast messages over the socket to destinations that can receive datagram messages. By default, this option is disabled. When you specify this option, the GETSOCKOPT command returns a string that contains the return code and a number: 1 (enabled) or 0 (disabled).

Restriction: This option has no meaning for stream sockets. It is valid only for datagram sockets.

SO_DEBUG

(REXX only) Determines whether debug information is recorded. By default, this option is disabled. When you specify this option, the GETSOCKOPT command returns a string that contains the return code and a number: 1 (enabled) or 0 (disabled).

Restriction: This option is valid only for stream sockets.

SO_DONTROUTE

Determines whether normal routing determination is bypassed for outgoing packets on the socket. When you specify this option, the GETSOCKOPT command returns a string that contains the return code and a number: 1 (enabled) or 0 (disabled).

Restriction: When a packet is sent, if the local interface cannot be determined from the destination address, the 51 ENETUNREACH error message is returned.

SO_EBCDIC

(REXX only) Determines whether data is translated to and from EBCDIC. This option is ignored by EBCDIC hosts. When you specify this option, the GETSOCKOPT command returns a string that contains the return code and either ON (enabled) or OFF (disabled). If the option is enabled, the name of the translation table is returned also.

Restriction: This option has no effect on the data that is processed by the socket library.

SO_ERROR

Retrieves information about pending errors on the socket or other errors that are not explicitly returned by any socket commands. The error status is cleared after each call. When you specify this option, the GETSOCKOPT command returns a string that contains the return code and the most recent error, for example, 0 36.

SO_KEEPALIVE

Determines if the keep alive mechanism periodically sends a packet on an otherwise idle connection for a stream socket. When enabled, if the remote TCP/IP does not respond to the packet or to retransmissions of the packet, the connection is terminated with the ETIMEDOUT error . By default, this option is disabled. When you specify this option, the GETSOCKOPT command returns a string that contains the return code and a number: 1 (enabled) or 0 (disabled).

Tip: The site administrator can enable the global keep-alive mechanism by modifying the TCPIP.PROFILE file. To modify the TCPIP.PROFILE file, use the TCPCONFIG INTERVAL statement.

SO_LINGER

Determines how TCP/IP processes data that has not been transmitted when the CLOSE command is issued for the socket. When this option is enabled and the CLOSE command is issued, the calling program is blocked until either the data is successfully transmitted or the connection times out. When this option is disabled and the CLOSE command is issued, the CLOSE command returns without blocking the caller; then TCP/IP continues to attempt to send data for a specified time, which usually provides sufficient time to complete the data transfer. By default, this option is disabled. When you specify this option, the GETSOCKOPT command returns a string that contains the return code and either 1 (enabled) or 0 (disabled), for example, 0 1.

Restrictions:

• Using the SO_LINGER option does not guarantee that a data transfer will be completed, because TCP/IP waits only for the amount of time that is specified by SETSOCKOPT command.
• This option is valid only for stream sockets.

SO_OOBINLINE

Determines whether out-of-band data is available to the RECV or RECVFROM commands. When this option is enabled, out-of-band data is placed in the normal data input queue as it is received; this data is then available to RECV or RECVFROM commands, even if the OOB flag is not set. When this option is disabled, out-of-band data is placed in the priority data input queue as it is received; this data is then available to RECV or RECVFROM commands only if the OOB flag is set. When you specify this option, the GETSOCKOPT command returns a string that contains the return code and a number: 1 (enabled) or 0 (disabled).

Restriction: This option is valid only for stream sockets.

SO_RCVBUF

Retrieves the size of the data portion of the TCP/IP receive buffer. The size of the receive buffer is protocol specific and is based on the following values:

• (TCP socket) The TCPRCVBufrsize keyword on the TCPCONFIG statement in the PROFILE.TCPIP data set.
• (UDP socket) The UDPRCVBufrsize keyword on the UDPCONFIG statement in the PROFILE.TCPIP data set.
• (Raw socket) The default size of 65535.

When you specify this option, the GETSOCKOPT command returns a string that contains the return code and either the size of the receive buffer or 0 (disabled).

SO_RCVTIMEO

Reports the timeout value for receive-type functions. This option returns a string that contains the number of seconds followed by the number of microseconds. These values specify the length of time to wait for a receive-type function to complete. Returns a value in the range 0 – 2 678 400 (equal to 31 days) for the number of seconds. Returns a value in the range 0 – 1 000 000 (equal to 1 second) for the number of microseconds. If a receive-type function has blocked for this length of time without receiving data, it returns with an errno set to EWOULDBLOCK. The value 0 (the default) indicates that a receive-type function does not time out.

The following receive-type commands are supported:

• READ
• RECV
• RECVFROM

SO_REUSEADDR

Determines whether local addresses are reused. Enabling this option alters the normal algorithm that is used with the BIND command. The normal BIND algorithm permits each Internet address and port combination to be bound only once. If the address and port already have been bound, a subsequent BIND command fails with the 48 EADDRINUSE error message . When this option is enabled, the following situations are supported:

• A server can bind the same port multiple times. Each invocation either must use a different local IP address, or it must use a wildcard address (INADDR_ANY or in6addr_any) only one time for each port.
• A server with active client connections can be restarted and can bind to its port without having to close all of the client connections.
• For datagram sockets, multicasting is supported so that multiple BIND commands can be made to the same class D address and port number.

By default, this option is disabled. When you specify this option, the GETSOCKOPT command returns a string that contains the return code and a number: 1 (enabled) or 0 (disabled).

Tip: If you want multiple servers that bind to INADDR_ANY or IN6ADDR_ANY to listen on the same port number, use the SHAREPORT option on the PORT statement in TCPIP.PROFILE.

SO_SNDBUF

Determines the size of the data portion of the TCP/IP send buffer. The size of the send buffer is protocol specific and is based on the following values:

• (TCP socket) The TCPRCVBufrsize keyword on the TCPCONFIG statement in the PROFILE.TCPIP data set.
• (UDP socket) The UDPRCVBufrsize keyword on the UDPCONFIG statement in the PROFILE.TCPIP data set.
• (Raw socket) The default size of 65535.

When you specify this option, the GETSOCKOPT command returns a string that contains the return code and either the size of the send buffer or 0 (disabled).

SO_SNDTIMEO

Reports the timeout value for send-type functions. This option returns a string that contains the number of seconds followed by the number of microseconds. These values specify the length of time to wait for a send-type function to complete. Returns a value in the range 0 – 2 678 400 (equal to 31 days) for the number of seconds. Returns a value in the range 0 – 1 000 000 (equal to 1 second) for the number of microseconds. If a send-type function has blocked for this length of time without receiving data, it returns with an errno set to EWOULDBLOCK. The value 0 (the default) indicates that a send-type function does not time out.

The following send-type commands are supported:

• SEND
• SENDTO
• WRITE

SO_TYPE

Retrieves the socket type. When you specify this option, the GETSOCKOPT command returns a string that contains the return code and a number: 1 (SOCK_STREAM), 2 (SOCK_DATAGRAM), or 3 (SOCK_RAW).

TCP_KEEPALIVE

Determines whether a socket-specific timeout value (in seconds) is used instead of a configuration-specific value, when keep alive timing is active for the socket. When enabled, the socket-specific timeout value remains in effect until either the socket is closed or it is reset by a SETSOCKOPT command. When you specify this option, the GETSOCKOPT command returns a string that contains the return code and either the timeout value or 0 (disabled).

Tip: The site administrator can enable the global keep-alive mechanism by modifying the TCPIP.PROFILE file. To modify the TCPIP.PROFILE file, use the TCPCONFIG INTERVAL statement.

TCP_NODELAY

Determines whether the data that is sent over the socket is subject to the Nagle algorithm (RFC 896). When this option is enabled, TCP waits to send small amounts of data until the acknowledgment for the previous data sent is received. When this option is disabled, TCP sends data when it is presented. When you specify this option, the GETSOCKOPT command returns a string that contains the return code and a number: 1 (enabled) or 0 (disabled).

TCP_MAXSEG

(IPPROTO_TCP protocol only) Retrieves the maximum segment size for a TCP send. When you specify this option, the GETSOCKOPT command returns a string that contains the return code and either the maximum segment size or 0 (disabled).

Returned value

The command returns a string that contains the return code and the option value. 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.

LE C/C++ equivalent

int getsockopt(int socket, int level, int option_name, char 
	*option_value, int *option_len);

Code example

/* REXX EZARXR20 */
/*
 * This sample demonstrates the use of the GETSOCKOPT
 * and SETSOCKOPT commands.
 *
 * The program opens a STREAM socket and connects to port 7
 * (echo server) using the loop back address.  Before sending
 * data the program issues the SETSOCKOPT command to set the
 * sockets send buffer to 32000 bytes. Data is then sent to
 * and recevied. After the data is received the GETSOCKOPT
 *
 * GUIDELINE: It is generally recommended that a program loop around
 *            the RECV command to ensure that all data is read off
 *            the socket. This sample does not follow the guideline.
 *
 */
src = socket("INITIALIZE","MYSET01");
if perror(src,"INITIALIZE") \= 0 then signal ENDPROGRAM;
src = socket("SOCKET","AF_INET","STREAM");
if perror(src,"SOCKET") = 0 then do
   l_socketid = WORD(src,2);
   src = socket("GETSOCKOPT",l_socketid,"SOL_SOCKET",,
                "SO_SNDBUF");
   if perror(src,"GETSOCKOPT") = 0 then do
      Say "Current socket send buffer size is",
          word(src,2);
      if word(src,2) < 32000 then do
         Say "Increasing the socket send buffer size",
             "to 320000";
         src = socket("SETSOCKOPT",l_socketid,,
                      "SOL_SOCKET","SO_SNDBUF",32000);
         /* ******************************************
         * Data can be sent even if command fails
         * so just post an message if an error occurs.
         * ******************************************/
         src = perror(src,"SETSOCKOPT");
      end;
      l_RMTname = "AF_INET 7 127.0.0.1";
      src = socket("CONNECT",l_socketid,l_RMTname);
      if perror(src,"CONNECT") = 0 then do
         src = socket("SEND",l_socketid,"*******");
         if perror(src,"RECV","SEND") = 0 then do
            src = socket("RECV",l_socketid);
            if perror(src,"RECV") = 0 then
            Say "Echoed data: " word(src,3);
      end;
   end;
   src = perror(socket("CLOSE",l_socketid),"CLOSE");
end;
end;
ENDPROGRAM:
src = perror(socket("TERMINATE","MYSET01"),"CLOSE");
exit 0;

/* This routine returns -1 if the first word if arg 1 is not zero */
perror: if word(arg(1),1) = 0 then return 0; else
    Say arg(2) "Error : "arg(1);
    return -1;