Buffer Memory Status
You cannot effectively use a buffer without knowing what its status is. Is it overflowing? Can you add more data? Etc. Thus, each of the serial buffers has certain properties that allow you to monitor them:
The RX Buffer
You can check the total capacity of the RX buffer with the ser.rxbuffsize property. You can also find out how much committed data the RX buffer currently contains with the ser.rxlen property (see Serial Settings for an explanation of committed data).
Sometimes you need to clear the RX buffer without actually extracting the data. In such cases, ser.rxclear comes in handy.
The TX Buffer
Similarly to the RX buffer, the TX buffer also has a ser.txbuffsize property that lets you discover its capacity.
Unlike the RX buffer, the TX buffer has two "data length" properties: ser.txlen and ser.newtxlen. The ser.txlen property returns the amount of committed data waiting to be sent from the buffer (you commit the data by using the ser.send method). The ser.newtxlen property returns the amount of data that has entered the buffer, but has not yet been committed for sending.
The TX buffer also has a ser.txfree property, which directly tells you how much space is left in it. This does not take into account uncommitted data in the buffer — actual free space is ser.txfree - ser.newtxlen!
ser.txlen + ser.txfree = ser.txbuffsize.
When you want to clear the TX buffer without sending anything, use the ser.txclear method.
Here is an example illustrating the difference between ser.txlen and ser.newtxlen:
dim x,y as word ' declare variables
ser.rxbuffrq(1) ' Request one page for the RX buffer.
ser.txbuffrq(5) ' Request 5 pages for the TX buffer (which we will use).
sys.buffalloc ' Actually allocate the buffers.
ser.setdata("foofoo") ' Set some data to send.
ser.setdata("bar") ' Some more data to send.
ser.send ' Start sending the data (commit).
ser.setdata("baz") ' Some more data to send.
x = ser.txlen ' Check total amount of data in the TX buffer.
y = ser.newtxlen ' Check length of data not yet committed. Should be 3.
end sub 'Set up a breakpoint HERE.
Don't step through the code. The sending is fast — by the time you reach x and y by stepping one line at a time, the buffer will be empty and x and y will be 0. Set a breakpoint at the end of the code, and then check the values for the variables (by using the Watch pane).