Overview
C API (Component Interface)
struct EventLog { UINT32 flags; INT32 precision; const char* filename; UINT64 count; void* source; Symbol result; };

This event is a request from the system telling a component that it will be expected to log its outputs during the execution period that follows. It should prepare the log, and put in a header if appropriate. A Component receiving this event will also receive EVENT_LOG_TERM; a Data object receiving this event will also receive EVENT_LOG_SERVICE.

Encapsulation

Logs can either be "encapsulated" or "unencapsulated". Encapsulated logs must be self-contained in the XML that the component returns to the system whilst servicing EVENT_LOG_TERM. Unencapsulated logs may contain references in that XML to files that the component has written. Unencapsulated logs can, thus, be written faster if there is a large amount of data to log, since the data does not have to be converted to XML and can be written instead as raw binary direct to file. Encapsulated logs, conversely, are neatly packaged in single files, and may be requested by the user for easy archival or distribution. Components need not ever write unencapsulated logs, but they must comply with F_ENCAPSULATED if it is set.

Context

This event is fired once during initialisation, but only on components that are logging.

Fields

Other fields are described in the relevant events, EVENT_LOG_SERVICE or EVENT_LOG_TERM.

UINT32 flags IN
See "Flags", below.
INT32 precision IN
The precision to which the data should be logged (meaning is dependent on data-type, but might be significant figures for numeric data, for instance). See "Constants", below.
const char* filename IN
A suggested filename if the object logs unencapsulated.

Flags

F_ENCAPSULATED
If set, the data object may not log unencapsulated.

Constants

PRECISION_NOT_SET
Store at maximal precision (no loss of information).

Action

  • Set an internal state to indicate that you are supposed to be storing your outputs.
  • Make preparations for storage (reserve memory, open a file).

Example

See the source code for std/2009/data/numeric.