Cogent CIF Driver for Hilscher Fieldbus CIF Cards : Version 6.4
	Command Reference

`cifTelegramFmt`

cifTelegramFmt — creates a named format string for cifTelgram.

Synopsis

(cifTelegramFmt fmt_name fmt_string)

Parameters

fmt_name

Any valid variable name, not already in use.

fmt_string

Any sequence of the following:

%arg_specifier | #num_specifier | any_valid_char

%arg_specifier

Formats ASCII encoded argument(s) which are always treated as decimal. Of the form:

(%[offset][.length][fmt_flags])({fmt_name}|fmt_type)

where

offset

The byte index into the target or source binary array.

length

Overrides the natural width of the fmt_type.

On conversion to binary: if length exceeds width of fmt_type, data is placed into lower (left justified) address.
On conversion to ASCII: length is the # bytes skipped in a repeating argument.

length is ABSOLUTELY required when using the {fmt_name} specifier, and it must be > 0.

fmt_flags

Any combination of:

`x`	Treat as hex.
`u`	Treat as unsigned.
`~`	Treat a 16-bit value as Motorola (big endian, high - low) byte ordering, instead of the 'standard' Intel (little endian, low - high) byte ordering. Since internal types are Intel format, the bytes are swapped prior to conversion.
`[n]`	Repeat conversion for `n` times.
`*`	Repeat conversion for remaining available args.
`[*]`	Repeat conversion for remaining available args.

[%arg_specifier]	Repeat conversion for the number of times contained in the specified area of the buffer (i.e., the repeat factor is specified by a field in the response buffer).
`(printf_fmt)`	On binary to ASCII conversion only, specifies how to format the extracted value, where `printf_fmt` is a valid C language `printf`-style format.

fmt_type

One of:

`c`	8-bit byte.
`w`	16-bit word.
`l`	32-bit long.
`s`	A string (null terminated sequence of bytes).
`h`	A sequence of ASCII-encoded hex bytes.

#num_specifier

Inserts a specified number as byte (truncates to byte).

#[conversion_flag]number

where conversion_flag is one of:

`d`	Treat the number as a decimal.
`b`	Treat the number as a binary (->binary only.
`o`	Treat the number as an octal (->binary only)
`x`	Treat the number as a hex (the default).

Returns

OK if successful, otherwise

(error "cifTelegramFmt -1 (time) createBinFormat format_error_msg")

Description

This command creates a named format control string that can be referenced by the cifTelegram command. Format control strings are used to build the binary message buffer from the supplied parameters, as well as to parse the binary result message back into ASCII parameters.

Examples

Define a format to convert two bytes of a response message into an ASCII space followed by the converted integer value.
```
(cifTelegramFmt fmtSpaceWord " %w")
```
Define a format to build a specific 8-byte message block that takes as parameters the buffer (0 or 1), the offset address, and the number of words. The format string builds the following sequence:
- A byte value of 0.
- The next parameter converted to a byte (either 1 for input or 2 for output ).
- The next parameter converted to a 16-bit word (the offset address).
- A byte value of 0.
- The next parameter converted to a byte (the number of words).
- A byte value 6.
- A byte value of 1.
Note that the parameters are consumed sequentially, and must therefore be provided in the required order.
```
(cifTelegramFmt fmtReadWordCmd "#0%c%w#0%c#6#1")
```
Define a format to parse a returned message block back into a series of ASCII parameters. The sequence is interpreted as follows:
- The first two bytes are ignored.
- The 3rd and 4th bytes are treated as a 16-bit value, %2w, and converted (the echoed address offset).
- From the 9th byte onwards (byte offset %8 ...), the data is repeatedly converted two packed bytes at a time (%8.2* ...), using the format described in Example 1, until the end of the message.
  A length must be specified, otherwise the parser will not index through the message, resulting in an infinite application of the repetition control.
  Each parameter to be extracted specifically addresses a location in the block, and can extract the required bytes from the block in any sequence.
```
(cifTelegramFmt fmtReadWordParse "%2w %8.2*{fmtSpaceWord}" )
```
In the following example, a specific cifTelegram command sequence is defined using the type command. cifReadWords will read from the specified card and buffer, the specified number of 16-bit values, starting at the specified offset. Note that
```
(type cifReadWords cifTelegram %1 2 16 17 0
      "#0%c%w#0%c#6#1"
      "%2w %8.2*{fmtSpaceWord}" %2 %4 %3)
(typeDesc cifReadWords "(cifReadWords card_id
      1=input|2=output length offset)")
```
The request message is sent to the card specified by the first parameter, %1, to task 2, from task 16 (the user), specifying command 17, sub-command 0 (see the parameters to cifTelegram). The command-specific content of the message is an 8-byte block created by the same format string as that defined for fmtReadWordCmd defined in the example above, and the results are parsed by the format string defined as fmtReadWordParse, also in the example above. Note that we chose to define the cifReadWords command with the word length parameter before the offset parameter. Therefore the three parameters consumed by the command format string are %2 %4 %3, so that:
- The 2nd parameter of cifReadWords will be converted to a byte (either 1 for input or 2 for output).
- The 4th parameter of cifReadWords will be converted to a 16-bit word (the offset address).
- The 3rd parameter of cifReadWords will be converted to a byte (the number of words).
The result of the command will be the echoed address offset, followed by a series of integer values (as many as requested by the 3rd parameter.)
Define a format to convert a binary response message containing 4 values into an ASCII string as follows:
- The first byte, %c, is output as a hex value, %xc, preceded by 0x, followed by a space.
- The second byte, %1c, is converted to an integer, followed by a space.
- Same for the third byte, %2c.
- The fourth and fifth bytes are treated as a 16-bit word, %3w, treated as unsigned, %3uw, treated as big-endian (high-low byte sequence), %3~uw, converted using a printf-style format of %X to generate a capitalized hex string, and preceded by 0x.
```
(cifTelegramFmt configItem " (0x%xc %1c %2c 0x%3~u(%X)w)")
```
In the following example, a specific cifTelegram command sequence is defined using the type command. cifReadConfig will read the fieldbus device configuration data from the specified card.
```
(type cifReadConfig cifTelegram %1 3 16 15 0 "%c%h"
      "idCode %9~u(0x%X)w lengthCode %11~u(0x%02X)w vendor
      \"%13.32(%.32s)s\" device \"%45.32(%.32s)s\"
      description \"%77.32(%.32s)s\" masterAddr %109c
      settings %110c nModules %125c
      %126.5[%125c]{configItem}"
      %2 "00000000000000")
(typeDesc cifReadConfig "(cifReadConfig card_id
      station_address)")
```
The request message is sent to the card specified by the first parameter, %1, to task 3, from task 16 (the user), specifying command 15, sub-command 0. The command-specific content of the message is an 8-byte block created by the format string "%c%h" which builds a byte sequence as follows:
- The 2nd parameter converted to a byte (the station address ).
- 7 bytes of value 0, created from the hex string, supplied as a constant parameter.
The complex parse_string is then used to convert the binary response message into a series of ASCII parameters, as follows:
- The label idCode is followed by the 16-bit value, offset by 9 bytes from the start, treated as unsigned and big-endian, and printed with a hex format.
- The label lengthCode is followed by the 16-bit value, offset by 11 bytes from the start, treated as unsigned and big-endian, and printed with a two-digit hex format.
- The label vendor is followed by the 32 byte string value, starting at an offset of 13 bytes from the start of message (note that the extra characters and the print format create a 32-byte string enclosed in quotes).
- The label device is followed by the 32 byte string value, starting at an offset of 45 bytes from the start of message.
- The label description is followed by the 32 byte string value, starting at an offset of 77 bytes from the start of message.
- The labels masterAddr, settings, and nModules are followed by the byte values offset by 109, 110 and 125 bytes from the start respectively.
- Repeated application of the 5-byte sequence defined by the configItem format defined above, starting at a byte offset of 126 bytes. The sequence is specified as having a repeat length of 5 (%126.5) to index the parser along the message every 5 bytes.
  A length must be specified, otherwise the parser will not index correctly through the message. In this case, the number of repetitions is specified by the message itself at the 126th byte, [%125c].


cifTelegramBinSend		cycle