GetHigh16 / CRC16 functions do not return 32-bit values

[garysdickinson]

You should correct the documentation for GetHigh16():

This function returns the upper 16-bit of a 32-bit integer variable v. This can be used to break the value of a 32-bit integer data or variable into two 16-bit values so that they can be saved to the EEPROM or to the 16-bit DM[n].[/color]

The following code:
A  = GetHigh16(&H89ABCDEF)

Assigns &HFFFF89AB to A rather than &H000089AB.  I believe that GetHigh16() returns an Int16 and the assignment to a 32 bit integer, A, results in sign extension.  This behavior is consistent with TBASIC.

I think that fact that the return type for GetHigh16() should be documented as a 16-bit signed integer.  I think that it would be good to remind the uses that this will result in sign extension when the return value of the function is assigned to a 32-bit variable.

By the same token the documentation for CRC16 does not mention that the return type from this function is a 16-bit signed integer and the output of this function will be signed extended when assigned to a 32-bit variable.

The documentation for CRC16() fails to mention that it only uses the least significant 8 bits of the "range of integers":

This function returns the computed CRC16 for a range of integers starting from variable "var" with the range indicated in the parameter "count". CRC16 is a 16-bit version of "Cyclic Redundancy Check" - a popular mathematical formula for checking error in a data stream.


One of the examples in the documentation assigns the value returned the the CRC16() function to a 32 bit value:

X = CRC16(RELAY[2],4)


The example is misleading as only the lower 16 bits of "X" hold the CRC value and the most significant 16 bits will be either &H0000 or &HFFFF as a result of sign extension.  This return type of CRC16() should be documented. And it would be nice to remind the user that assignment of the return value from this function to a 32-bit variable will result in sign extension.

I am not trying to be a "whiner" but I have stumbled onto these old issues, recently, and they caused me some real grief. Just add them to the list of things that could be better documented.

Gary D*ickinson

[support]

Thank you for your feedback. We will update the documentation to highlight some of these potential "gotcha" the system auto-converting from 16 to 32-bit integers that involve negative numbers (and therefore sign extension).

The most effective and consistent way is to use an "AND mask" to zero out the upper 16-bit when using the GETHIGH16


A  = GetHigh16(&H89ABCDEF) & &HFFFF  

The above ensure that sign extension will not cause a problem and therefore A will only get the lower 16-bit of the resulting number.

Thank you.