z/OS Communications Server: IP Sockets Application Programming Interface Guide and Reference
Previous topic | Next topic | Contents | Contact z/OS | Library | PDF


SETSOCKOPT

z/OS Communications Server: IP Sockets Application Programming Interface Guide and Reference
SC27-3660-00

Use the SETSOCKOPT command to set socket options.

Format

Read syntax diagramSkip visual syntax diagram
>>-SOCKET--(--"SETSOCKOPT"--,--socketid--,--levelname----------->

>--,--optname--,--optvalue--)----------------------------------><

Parameters

socketid
The socket descriptor.
levelname
The protocol level. The following protocol levels are supported:
IPPROTO_TCP
Set socket options at the TCP layer
IPPROTO_IP
Set IPv4 socket options at the IP layer
IPPROTO_IPV6
Set IPv6 socket options at the IP layer
SOL_SOCKET
Set socket options at the socket layer
optname
The option or options. 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.
  • Options that begin with MCAST require the IPPROTO_IP or IPPROTO_IPV6 protocol level.
The following values are supported for the optname parameter:
IP_ADD_MEMBERSHIP
(IPV4-only) Enables an application to join a multicast group on a specific interface. Applications in a multicast group can receive multicast datagrams. An application can join multiple multicast groups on the same interface or the same multicast group on multiple interfaces, but only one interface address can be specified with a single command. The optvalue parameter must be a string that contains the multicast address followed by the interface address on which the application wants to receive multicast datagrams, for example, "224.224.224.1 10.11.13.4". This command returns the return code or error number.
Tip: Use the IOCTL command with the SIOCGIFADDR option to determine the interface address.
IP_ADD_SOURCE_MEMBERSHIP
(IPV4-only) Enables an application to join a multicast group on a specific interface and a specific source address. The optvalue parameter must be a string that contains the multicast address, the interface address, and the source address, for example, "224.224.224.1 10.11.16.103 10.11.107.1". The source address represents a filter; the application receives multicast packets only if the source address matches the source address filter for the multicast group.

This command returns the return code or error number.

Restrictions:
  • Only one interface address can be specified with a single call.
  • The stack supports up to 64 source address filters for each multicast-group interface pair. If the number of filters exceeds the maximum, ENOBUFS is returned.
  • You can specify only a single source address with each call. If you want to join a multicast group and receive data from two different source addresses, then issue the SETSOCKOPT command twice.
Guideline: Applications that want to receive multicast datagrams need to join multicast groups. Use this option when the application wants to receive multicast packets on a specific group from one or more senders
IP_BLOCK_SOURCE
(IPV4-only) Enables an application to block multicast packets that are sent from a specific address. The application must have previously joined the multicast group. The optvalue parameter must be a string that contains the multicast address, source address, and interface address, for example, "224.224.224.1 10.11.16.103 10.11.107.1". This option returns 0 if it is successfully completed; otherwise, it returns the error number.
IP_DROP_MEMBERSHIP
(IPV4-only) Enables an application to exit a multicast group. If source filtering is enabled, all source filters are deleted. The optvalue parameter must be a string that contains the multicast address and the interface address, for example, "224.224.224.1 10.11.13.4". This option returns 0 if it is successfully completed; otherwise, it returns the error number.
IP_DROP_SOURCE_MEMBERSHIP
(IPV4-only) Enables an application to leave a multicast-source multicast group. The application will no longer receive multicast packets from the group. The optvalue parameter must be a string that contains the multicast address, source address, and interface address, for example, "224.224.224.1 10.11.13.4 10.11.107.1". This option returns 0 if it is successfully completed; otherwise, it returns the error number.
IP_MULTICAST_IF
(IPV4-only) Sets the IPv4 interface address that is used to send outbound multicast datagrams. Multicast datagrams can be sent only on one interface at a time. The optvalue parameter is the IP address of the interface. This option returns 0 if it is successfully completed; otherwise, it returns the error number.
IP_MULTICAST_LOOP
(IPV4-only) Controls whether a multicast datagram is looped back on the outgoing interface by the IP layer for local delivery when datagrams are sent to a group to which the sending host belongs. By default, loopback is enabled. The optvalue parameter must be one of the following values: 0 (disabled) or 1 (enabled). This option returns 0 if it is successfully completed; otherwise, it returns the error number.
IP_MULTICAST_TTL
(IPV4-only) Sets the IP time-to-live of outgoing multicast datagrams. By default, this is set to 1; multicast is available only to the local subnet. The optvalue parameter must be an integer in the range 1 - s255.
IP_UNBLOCK_SOURCE
(IPV4-only) Enables an application to unblock a previously blocked source address for an IPv4 multicast group. Only one interface address can be specified with a single call. The optvalue parameter must be a string that contains the multicast address, source address, and interface address, for example, "224.224.224.1 10.11.103.1 10.11.107.1". This option returns 0 if it is successfully completed; otherwise, it returns the error number.
IPV6_ADDR_PREFERENCES
(AF_INET6 only) Sets the IPv6 address preferences to be used when selecting the source address. The following are the valid IPV6_ADDR_PREFERENCES flags:
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.
You can specify a single flag or multiple flags that are separated by blanks.
Results:
  • Combining contradictory flags, such as IPV6_PREFER_SRC_CGA and IPV6_PREFER_SRC_NONCGA, results in error code 2020 (EINVALIDCOMBINATION).
  • The stack could assign a source IP address that does not conform to one or more of the IPV6_ADDR_PREFERENCES flags that you have set.
IPV6_JOIN_GROUP
(IPv6-only) Enables an application to join a multicast group on a specific interface. Only applications that want to receive multicast datagrams need to join multicast groups. An application can join multiple multicast groups on the same interface, or it can join the same multicast group on multiple interfaces. The optvalue parameter must be a string that contains the multicast address and the index of the interface on which the application wants to receive multicast datagrams, for example, "FF02:225:9:10::11 3". If the interface index is set to 0, the stack will chose the local address. This option returns 0 if it is successfully completed; otherwise, it returns the error number.
Guideline: Use the SIOCGIFNAMEINDEX function of the IOCTL command to determine the index number for an interface.
Restriction: Only one interface address can be specified in a single call. A multicast address can be associated with a real interface only.
IPV6_LEAVE_GROUP
(IPv6-only) Enables an application to leave a multicast group. The optvalue parameter must be a string that contains the multicast address and the interface address, for example, "FF02:225:9:10::11 3". The optvalue parameter must match the original IPV6_JOIN_GROUP parameters; for example, if the interface index specified for the IPV6_JOIN_GROUP was 0, then 0 also must be specified as the interface index for IPV6_LEAVE_GROUP command. This option returns 0 if it is successfully completed; otherwise, it returns the error number.
IPV6_MULTICAST_HOPS
(IPv6-only) Sets the hop limit that is used for outgoing multicast packets. The optvalue parameter is optional; if it is not issued, the hop limit is set to 1.
The optvalue parameter can have the following values:
-1
The default value for the stack is used.
0-255
The hop limit.
This option returns 0 if it is successfully completed; otherwise, it returns the error number.
Restriction: To set the hop limit value to be greater than the TCP/IP default value, a REXX-application user ID must have superuser authority.
IPV6_MULTICAST_IF
(IPv6-only) Sets the index of the IPv6 interface that is used to send outbound multicast datagrams from the socket application. The optvalue parameter must specify the interface index number, for example, 34. This option returns 0 if it is successfully completed; otherwise, it returns the error number.
IPV6_MULTICAST_LOOP
(IPv6-only) Controls whether a multicast datagram is looped back on the outgoing interface by the IP layer for local delivery when datagrams are sent to a group to which the sending host belongs. By default, multicast datagrams are looped back. The optvalue parameter must be one of the following values: 0 (disabled) or 1 (enabled). This option returns 0 if it is successfully completed; otherwise, it returns the error number.
IPV6_UNICAST_HOPS
(IPv6-only) Sets the hop limit that is used for outgoing unicast IPv6 packets. The optvalue parameter is optional; if it is not issued, the hop limit is set to 1.
The optvalue parameter can have the following values:
-1
The default value for the stack is used.
0-255
The hop limit.
This option returns 0 if it is successfully completed; otherwise, it returns the error number.
Restriction: An application must be APF authorized to set the hop limit value to be greater than the TCP/IP default value. This option is not valid when used in CICS® applications. CICS applications cannot run as APF authorized.
IPV6_V6ONLY
(IPv6-only) Restricts a socket to sending and receiving IPv6 packets only. By default, a socket is not restricted. The optvalue parameter must be one of the following values: 0 (disabled) or 1 (enabled). This option returns 0 if it is successfully completed; otherwise, it returns the error number.
MCAST_BLOCK_SOURCE
Enables an application to block multicast packets from a specific source address. The multicast group must have been previously joined. The optvalue parameter must be a string that contains the interface index, the multicast address, and the source address. Specify the multicast address and source address using the NAME string. The following string is an example of what might be coded for the optvalue parameter: 
"45 AF_INET6 54666 0 FF02::32:1 0 AF_INET6 0 0 2001:10:11:107::1 0"

For more information about the format of the NAME string, see How structures are represented. This option returns 0 if it is successfully completed; otherwise, it returns the error number.

Tip: This option is valid for both IPv4 and IPv6.
MCAST_JOIN_GROUP
Enables an application to join a multicast group on a specific interface. Only applications that want to receive multicast datagrams need to join multicast groups. The optvalue parameter must be a string that contains the interface index and a multicast address. Specify the multicast address using the socket address name format. The following string is an example of what you can code for the optvalue parameter:

"45 AF_INET 1234 224.224.224.1"

For more information about the format of the NAME string, see How structures are represented. This option returns 0 if it is successfully completed; otherwise, it returns the error number.

Tip: This option is valid for both IPv4 and IPv6.
MCAST_JOIN_SOURCE_GROUP
Enables an application to join a source multicast group on a specific interface and source address. Only applications that want to receive multicast datagrams need to join source multicast groups. The optvalue parameter must be a string that contains the interface index, the multicast address, and the source address. Specify the multicast address and source address the using socket address name format. The following string is an example of what you can code for the optvalue parameter: 
"45 AF_INET6 1234 0 FF02::123:1 0 AF_INET6 0 0 2001:10:11:107::1 0"

For more information about the format of the NAME string, see How structures are represented. This option returns 0 if it is successfully completed; otherwise, it returns the error number.

Tip: This option is valid for both IPv4 and IPv6.
MCAST_LEAVE_GROUP
Enables an application to leave a multicast group or to leave all source multicast groups. The optvalue parameter must be a string that contains the interface index and the multicast address; specify the multicast address using the socket address name format. The following string is an example of what you can code for the optvalue parameter: 
"45 AF_INET6 1234 0 FF02::123:1 0"

For more information about the format of the NAME string, see How structures are represented. This option returns 0 if it is successfully completed; otherwise, it returns the error number.

Tip: This option is valid for both IPv4 and IPv6.
MCAST_LEAVE_SOURCE_GROUP
Enables an application to leave a source multicast group. The optvalue parameter must be a string that contains the interface index, the multicast address, and the source address. Specify the multicast address and source address using the socket address name format. The following string (all on one line) is an example of what you can code for the optvalue parameter: 
"45 AF_INET6 1234 0 FF02::123:1 0 AF_INET6 1234 0 
		2001:10:11:103::1 0"

For more information about the format of the NAME string, see How structures are represented. This option returns 0 if it is successfully completed; otherwise, it returns the error number.

Tip: This option is valid for both IPv4 and IPv6.
MCAST_UNBLOCK_SOURCE
Enables an application to unblock multicast packets that are sent from a specific address. The multicast group must have been previously blocked. The optvalue parameter must be a string that contains the interface index, the multicast address, and the source address. Specify the multicast address and source address using the socket address name format. The following string is an example of what you can code for the 
optvalue
parameter:

"45 AF_INET6 1234 0 FF02::123:1 0 AF_INET6 1234 0 2001:10:11:103::1 0"

For more information about the format of the NAME string, see How structures are represented. This option returns 0 if it is successfully completed; otherwise, it returns the error number.

Tip: This option is valid for both IPv4 and IPv6.
Restriction: Only one source address can be specified in a call.
SO_ASCII
(REXX only) Enables all incoming data to be translated from ASCII to EBCDIC, and all outgoing data to be translated from EBCDIC to ASCII. The optvalue parameter must be one of the following values: 0 (disabled) or 1 (enabled). 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
Enables a program to send broadcast messages over the socket to destinations that can receive datagram messages. By default, this option is disabled. The optvalue parameter must be one of the following values: 0 (disabled) or 1 (enabled). This option returns 0 if it is successfully completed; otherwise, it returns the error number.
Restriction: This option is not valid for stream sockets.
SO_DEBUG
(REXX only) Control whether debugging information is recorded. By default, this option is disabled. The optvalue parameter must be either ON (enabled) or OFF (disabled). This option returns 0 if it is successfully completed; otherwise, it returns the error number. This option is valid only for stream sockets.
SO_DONTROUTE
Bypasses normal routing algorithms for outgoing packets on the socket. If the local interface cannot be determined, when a packet is sent using one of the SEND commands, then the 51 ENETUNREACH error number is returned. This option returns either 1 (enabled) or 0 (disabled).
SO_EBCDIC
(REXX only) Enables data to be translated to and from EBCDIC. This option is ignored by EBCDIC hosts. The optvalue parameter must be either ON (enabled) or OFF (disabled). 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
SO_KEEPALIVE
Sets the keep alive mechanism to periodically send a packet on an otherwise idle connection for a stream socket. By default, this option is disabled. When enabled, if the remote TCP/IP does not respond to the packet or to retransmissions of the packet, then the connection is terminated with the ETIMEDOUT error. The optvalue parameter must be one of the following values: 0 (disabled) or 1 (enabled). This option returns 0 if it is successfully completed; otherwise, it returns the error number.
Tip: You also can enable the keep alive mechanism by modifying the TCPIP.PROFILE file.
SO_LINGER
Specifies 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.
The optvalue parameter is a string in the following format:
linger = "onoff lingertime"
where
  • The onoff value is either 0 (disabled) or 1 (enabled).
  • The lingertime value is the number of seconds that TCP/IP tries to send data after the CLOSE command is issued.
This option returns 0 if it is successfully completed; otherwise, it returns the error number.
Restrictions:
  • Using the SO_LINGER option does not guarantee that a data transfer will be completed, because TCP/IP waits only the amount of time that is specified.
  • This option is valid only for stream sockets.
Guidelines:
  • Avoid setting a linger time of 0. If you set the linger time to 0, the connection stops rather than closing in an orderly manner. This results in a RESET segment being sent to the connection partner. If the aborting socket is in nonblocking mode, the CLOSE command is processed as though no linger option is set.
  • Enable the SO_LINGER option only when necessary.
SO_OOBINLINE
Controls whether out-of-band data is received. 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. By default, this option is disabled. The optvalue parameter must be one of the following values: 0 (disabled) or 1 (enabled). This option returns 0 if it is successfully completed; otherwise, it returns the error number.
Restriction: This option is valid only for stream sockets.
SO_RCVBUF
Controls 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 65535.
The optvalue parameter must be either 0 (disabled) or a positive integer that specifies the size of the TCP/IP receive buffer. If you disable this option, the default system setting is used.This option returns 0 if it is successfully completed; otherwise, it returns the error number.
SO_RCVTIMEO
Sets the maximum length of time that a receive-type function can wait before it completes You can specify the number of seconds and microseconds that indicate the length of time to wait for a receive-type function to complete. If a receive-type function has blocked for this much time without receiving data, it returns with the errno EWOULDBLOCK. The value 0 (the default) indicates that a receive-type function does not time out. The optvalue parameter must be a string that contains the number of seconds followed by the number of microseconds. The GETSOCKOPT command returns the return code or error number. Specify a value in the range 0 – 2 678 400 (equal to 31 days) for the number of seconds. Specify a value in the range 0 – 1 000 000 (equal to 1 second) for the number of microseconds. Although you can specify the number of microseconds, the internal TCP/IP timers that are used to implement this function have a granularity of approximately 100 milliseconds. The following receive type commands are supported:
  • READ
  • RECV
  • RECVFROM
SO_REUSEADDR
Controls 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. When this option is enabled, the following situations are supported:
  • A server can bind the same port multiple times, if each invocation uses a different local IP address and the wildcard address INADDR_ANY is used 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. The optvalue parameter must be one of the following values: 0 (disabled) or 1 (enabled). This option returns 0 if it is successfully completed; otherwise, it returns the error number.
Tip: If you want to permit multiple servers to bind to INADDR_ANY or IN6ADDR_ANY and listen on the same port, use the SHAREPORT option on the PORT statement in TCPIP.PROFILE.
SO_SNDBUF
Controls 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 65535.
The optvalue parameter must be either 0 (disabled) or a positive integer that specifies the size of the TCP/IP send buffer. If you disable this option, the default system setting is used. This option returns 0 if it is successfully completed; otherwise, it returns the error number.
SO_SNDTIMEO
Sets the maximum length of time that a send-type function can remain blocked before it completes. You can specify the number of seconds and microseconds that indicate the length of time to wait for a send-type function to complete. If a send-type function has blocked for this length of time, the function returns with a partial count or with an errno set to EWOULDBLOCK if no data is sent. The value 0 (the default) indicates that a send type function does not time out. The optvalue parameter must be a string that contains the number of seconds followed by the number of microseconds. The GETSOCKOPT command returns the return code or error number. Specify a value in the range 0 – 2 678 400 (equal to 31 days) for the number of seconds. Specify a value in the range 0 – 1 000 000 (equal to 1 second) for the number of microseconds. While the number of microseconds can be specified, the internal TCP/IP timers that are used to implement this function have a granularity of approximately 100 milliseconds. The following send-type commands are supported:
  • SEND
  • SENDTO
  • WRITE
TCP_KEEPALIVE
Specifies 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. The optvalue parameter must be either 0 (disabled) or the keep alive value. This option returns a string that contains the return code and the keep alive value. If the option is disabled, the keep alive value is 0.
TCP_NODELAY
Specifies 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. The optvalue parameter must be one of the following values: 0 (disabled) or 1 (enabled). This option returns 0 if it is successfully completed; otherwise, it returns the error number.
optvalue
Additional information that is needed to run the requested command.

Returned 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.

The following REXX TCP/IP error numbers can be returned:
  • 9 EBADF
  • 22 EINVAL
  • 38 ENOTSOCK
  • 42 ENOPROTOOPT
  • 45 EOPNOTSUPP
  • 60 ETIMEDOUT
The following REXX socket API error numbers can be returned:
  • 2001 EINVALIDRXSOCKETCALL
  • 2005 ESUBTASKNOTACTIVE
  • 2009 ESOCKETNOTDEFINED
  • 2012 EINVALIDNAME

LE C/C++ equivalent

int setsockopt(int socket, int level, int option_name, char *option_value,
	int *option_length);

Code example

See the EZARXS01 REXX sample in the SEZAINST file for an example of using the SETSOCKOPT command.

Go to the previous page Go to the next page

Notices | Terms of use | Support | Contact z/OS | zFavorites



Copyright IBM Corporation 1990, 2014