HSET

Description

The HSET command exists to change various settings of e.g. files, sockets, communication ressources at runtime.

HSET requires three arguments. The first one is a handle number that must either refer to an open handle, a file or socket, or it can be a magic number that identifys a communication ressource, such as -4 for the second RS232 interface.

Using HSET on open sockets

If the first one is a handle, the second argument is called the "option number" that is, which aspect of the given handle HSET should modify. The third and last argument is the new value to be set. These options are currently defined:

0 - Set maximum number of packets that socket's receive list can accumulate.
1 - Set maximum number of packets that socket's transmit list can accumulate.

In both cases, the third argument is the number of packets for this option. This value can be any number from 0 to 2147483647. Although, there are fewer packet buffers in the system (see SSTAT command output), any greater value permits a socket to consume all packet buffers. On the other hand, a value of 0 completely disables the specified direction.

The new values come into effect immediately if the specific list currently holds exactly the same or fewer packets. If any socket list has more packets before a new value is applied, no more packets are added to the list until it reaches the defined level.

Using HSET to set buffer size of communication channels

If the first one is a magic, negative number, the second argument denotes the size of the receive buffer, and the second one the size of the transmit buffer of a communication channel. Currently, these magic numbers are defined:

-4 The second RS232 interface (RX and TX buffer)
-5 The IIC interface (RX and TX buffer)
-8 The second CAN interface (RX buffer only)
-10 The SPI master channel (RX buffer only)

The maximum size of any buffer is 4096, the minimum size is 2. Values outside this range are forced to the next valid value. For interfaces that have only one buffer, the other value does not have any effect.

To set the buffer size properly, HSET must be called before AUXOPEN is called.

Example

Set max. sizes of RX list on socket handle #198 to 0 and TX list to 3

HSET 198, 0, 0
HSET 198, 1, 3

Sets the RX FIFO of the auxilliary RS232 to 1024 and the TX FIFO to 32 bytes

HSET -4, 1024, 32

Remarks

HSET is a generic command that will be extended in the future. Currently, HSET is able to modify the number of packet buffers that a socket is allowed to keep in its receive and transmit lists, and to modify buffer sizes of communication ressources.

What happens with receive functions if RX list maximum is set to zero:

- A program reading from that UDP socket will not receive anything.

- Incoming packets are silently thrown away.

- A program reading from that TCP socket will not receive anything.

- Incoming packets are thrown away but acknowledged to keep the sender happy.

- BYTESREAD will always be zero.

- LASTERR will always be ERR_NO_DATA.

What happens with transmit functions if TX list maximum is set to zero:

- An attempt trying to transmitting over that UDP socket will fail.

- An attempt trying to transmitting over that TCP socket will fail.

- LASTERR will always be ERR_FR_DENIED.

What happens with receive functions if RX list reaches maximum:

- Received UDP packets are thrown away until the program frees space by reading packets from the socket.

- Received TCP packets are thrown away and not acknowledged until the program frees space by reading packets from the socket.

- The remote sender must (and will) retransmit lost packets.

What happens with transmit functions if TX list reaches maximum:

- The program will not be able to send over that UDP socket and LASTERR will  be ERR_FR_DENIED until the network task has sent at least one packet.

- The program will not be able to send over that TCP socket and LASTERR will be ERR_FR_DENIED until the network task has sent at least one packet and got an ACK from the remote station.