SetSockOpt

Purpose

Use the SetSockOpt function to set the options associated with an AF_INET socket.

The optvalue parameter is used to pass data used by the particular set command. The optvalue parameter points to a buffer containing the data needed by the set command. The optvalue parameter is optional and can be set to 0, if data is not needed by the command.

Parameters

socketid

is the identifier of the socket.

level

is the protocol level for which the socket option is being set. SOL_SOCKET and IPPROTO_TCP are supported. All optname values beginning with SO_ are for protocol level SOL_SOCKET and are interpreted by the general socket code. All optname values beginning with TCP_ are for protocol level IPPROTO_TCP and are interpreted by the TCP/IP internal code.

optname

is the socket option to be set:

Option

Description

SO_ASCII

Controls the translation of data to ASCII. When SO_ASCII is On, data is translated to ASCII. When SO_ASCII is Off, data is not translated to or from ASCII. Following the setting in the optvalue parameter, you can specify the name of the translation table used, if translation is applied to the data. This option is ignored by ASCII hosts.

SO_BROADCAST

Controls the ability to send broadcast messages over the socket. This option does not apply to stream sockets. The initial setting is Off.

SO_DEBUG

Controls the recording of debug information. The initial setting is Off.

SO_EBCDIC

Controls the translation data to EBCDIC. When SO_EBCDIC is On, data is translated to EBCDIC. When SO_EBCDIC is Off, data is not translated to or from EBCDIC. Following the setting in the optvalue parameter, you can specify the name of the translation table used, if translation is applied to the data. This option is ignored by EBCDIC hosts.

SO_KEEPALIVE

Controls whether a datagram is periodically sent on an idle connection. If the remote TCP/IP does not respond to this datagram or to retransmissions of this datagram, the connection ends with error code 60 (ETIMEDOUT). The initial setting is Off.

SO_LINGER

Controls whether the Close function will linger if data is present:

• If SO_LINGER is On and there is unsent data present when Close is called, the calling application is blocked until the data transmission completes or the connection times out.
• If SO_LINGER is Off, a call to Close returns without blocking the caller. TCP/IP still tries to send the data. Although this transfer is usually successful, it cannot be guaranteed, because TCP/IP repeats the Send request for only a specified period of time.

This option applies only to stream sockets. The initial setting is Off.

SO_OOBINLINE

Controls how out-of-band data is to be received:

• When SO_OOBINLINE is On, out-of-band data is placed in the normal data input queue as it is received. The Recv and RecvFrom functions can then receive the data without enabling the the MSG_OOB flag.
• When SO_OOBINLINE is Off, out-of-band data is placed in the priority data input queue as it is received. The Recv and RecvFrom functions must enable the MSG_OOB flag to receive the data.

This option applies only to stream sockets. The initial setting is Off.

SO_REUSEADDR

Controls whether local addresses can be reused. When SO_REUSEADDR is On, local addresses that are already in use can be bound. Instead of the usual algorithm of checking at Bind time, TCP/IP checks at Connect time to ensure that the local address and port are not the same as the remote address and port. If the address and port are duplicated at Connect time, Connect returns error code 48 (EADDRINUSE) and the connect request fails.

The initial setting is Off.

TCP_NODELAY

Controls the do-not-delay-the-send flag, which indicates whether TCP/IP can send small packets as soon as possible.

optvalue

is the option setting.

For all options except SO_LINGER, you can specify On, Off, or a number (0 = Off, nonzero = On).

For the SO_LINGER option, you can specify On n, n, or Off. If you specify only n, On is implied. The value n is the number of seconds that TCP/IP should continue trying to send the data after the Close function is called.

Return Values

If successful, this function returns a string containing only return code 0. If unsuccessful, this function returns a string containing a nonzero return code, an error name, and an error message.

Messages and Return Codes

For a list of REXX Sockets system messages, see REXX Sockets System Messages. For a list of REXX Sockets return codes, see REXX Sockets Return Codes.