Wavetronix Click 500 (programmable controller) (CLK-500) - Developer Guide - Manual (Page 86)

CHAPTER 8 • SERIAL MESSAGE SUPPORT 85
Using Variable-Length Variables in Messages
The message library supports two types of variable-length fields:
˽ Variable-length fields with the size embedded in a preceding length-byte.
˽ Variable-length fields that terminate in a literal-value footer.
The first method uses a single-byte to specify the length of the subsequent variable length
field. The %L indicates the size of the variable-length field as a number of bytes. It is not
necessary to precede the L with a number since its length is fixed at one.
The number of bytes can vary from 1 to 256, assuming the total message is less than or equal
to 256 bytes. Before transmission, use the function ClickMsgSetVarSize to set the number
of bytes. However, ClickMsgReadVar and ClickMsgWriteVar will only support variables up
to the length limit set by the pre-compiler directive MAX_VAR_LEN_ARRAY_SIZE. By
default, the MAX_VAR_LEN_ARRAY_SIZE is 200, so if you need to handle variable byte
fields longer than this length, consider using ClickMsgGetRxSnapshot or change MAX_
VAR_LEN_ARRAY_SIZE. By default, up to 10 variable length variables are supported.
The %V marks the position of the variable-length field. The %L and %V do not need to be
back-to-back fields in the ClickMsgString. They can be separated by variables, checksums
and literals. It is not necessary to precede the V with a number, since its byte-length is not
fixed.
A second way to receive variable length fields involves the use of a termination field with a
fixed pattern. The fixed pattern, or footer, is preceded by the “*” wildcard indicator. The data
received by the wildcard is only available using ClickMsgGetRxSnapshot.
Using Checksums in Messages
Since there are many different ways to calculate a checksum, the serial protocol parser pro-
vides you with significant flexibility, allowing you to control and manage the checksum
functionality. The ClickMsgAddChecksumTask and ClickMsgStoreChecksum functions
are functions you can use to incorporate checksums in the messaging protocol.
The ClickMsgAddChecksumTask function allows you to add a checksum calculation func-
tion to the checksum table. The ClickMsgAddChecksumTask function also takes a function
pointer and an index byte as its parameters. The function pointer is a pointer to the callback
function that has been created to calculate the checksum. The checksum index references
the callback function pointer in the checksum table. The current implementation supports
10 unique checksum algorithms (table entries 0 to 9).
Each callback function must accept four input parameters and return a status condition.
The three input parameters include:
1 A pointer to the input data.