BACnetStack_ReadTrendLogRecord

uint32_t BACnetStack_ReadTrendLogRecord(
  const uint32_t deviceInstance,
  const uint32_t objectInstance,
  const uint32_t offset,
  CASBACnetTime * timestamp,
  uint8_t * datumType,
  char * datumAsString,
  uint32_t * datumLength,
  const uint32_t maxDatumStringLength,
  bool * statusFlags,
  uint32_t * statusFlagsLength,
  const uint32_t maxStatusFlagsLength,
  bool * more);

Gets a record from the Trend Log in a string format that can be used to backup the record.

Returns true if successful or false if failed. Can fail for the following reasons:

Object doesn’t exist
Device doesn’t exist
If required parameters are NULL or invalid
If polling for an offset that doesn’t exist.

BACnet reference: ANSI/ASHRAE 135-2024 clause 12.25 (Trend Log Object Type).

Parameters

Parameter	Direction	Description
`deviceInstance`	in	The instance of the device that contains the trend log object
`objectInstance`	in	The instance of the trend log object.
`offset`	in	The record number to retrieve. 0 is the first record. timestamp, datumType, datumLength and more are required: passing NULL for any of them fails the call (it returns 0) and nothing is written. datumAsString is required too, unless maxDatumStringLength is 0, and then the call fails because no datum string fits in it.
`timestamp`	out	The parameter to store the timestamp of the record, in UTC epoch seconds: the stored local time converted with the UTC_Offset (and Daylight_Savings_Status) your application serves for the Device at the time of this call - the conversion BACnetStack_InsertTrendLogRecord() applies, so the value can be inserted back unchanged. A record stored under the other Daylight_Savings_Status reads out one hour off.
`datumType`	out	The parameter to store the datum type of the record. Valid values: 0 = Log Status, 1 = Boolean, 2 = Real, 3 = Enumerated, 4 = Unsigned, 5 = Integer, 6 = Bitstring, 7 = Null, 8 = Error, 9 = Time Change, 10 = Any Value (a logged value of any other datatype, such as a Double or a CharacterString). (BACnetStack_InsertTrendLogRecord() above accepts the identical set, so a record read out here can be written back with the same value.) Each value is the tag of a log-datum CHOICE arm of BACnetLogRecord (cl. 12.25, cl. 21): Log Status is a BACnetLogStatus BIT STRING, and Error is the failure arm.
`datumAsString`	out	The char array parameter to store the record, in string form matching datumType: Log Status “b101”, Boolean “true”/“false”, Real “123.45”, Enumerated “10”, Unsigned “25”, Integer “-10”, Bitstring “b10101” (an empty bitstring is “b”), Null “null”, Error “1-31” (a HYPHEN, per `<errorClass>-<errorCode>`), Time Change “3600.0”, Any Value the encoded value in hex, two digits per octet, e.g. “720041” for the CharacterString “A”, or “x” for a value with no elements. Every datum has a non-empty string, so a successful read never returns 0. NOT NUL-TERMINATED - use datumLength, never strlen.
`datumLength`	out	The parameter to store the length of the datum string.
`maxDatumStringLength`	in	The max length possible for the datum string. A datum string longer than this fails the read; it is not truncated.
`statusFlags`	out	The bool array that receives the record’s status flags, a BACnetStatusFlags BIT STRING (cl. 21) as one bool per bit in bit order (in-alarm, fault, overridden, out-of-service). Optional for a record without status flags: NULL is accepted there. For a record that carries them, NULL fails the read (it returns 0), so pass an array of at least 4 bools if any record might.
`statusFlagsLength`	out	Receives the number of flags written, 0 for a record without status flags. Written on every successful read. Optional: pass NULL if you do not need it.
`maxStatusFlagsLength`	in	The capacity of statusFlags, in bools. Pass at least 4. Passing 0 does not mean “skip the status flags”; it makes the ENTIRE record read fail (return 0) for every record that carries them, because the copy is refused when the bitstring is longer than the capacity given.
`more`	out	Flag that when true means there is more data to get, otherwise it is set to false when reporting the last record.

Returns

The number of bytes written to datumAsString (matching the value written to datumLength) if successful, 0 if failed.

Topic: Schedules, calendars, trend logs and other object configuration. Declared in CASBACnetStackDLL.h.