Annotation files

You can annotate every value in the snapshot or the archive. An annotation can be of any data type. An annotation file stores annotations. Each archive file has a single associated annotation file, with an .ann extension. You can use the piconfig utility to add and edit text annotations.

Note: Any operation on annotation translates into an actual I/O, bypassing archive caching. Thus it is much less efficient than non-annotated events. Be aware of this when using annotations.

The archive-listing command, piartool -al, shows annotation file statistics. The following is output from an archive listing:

Archive[0]: c:\pi\dat\testarc.dat (256MB, Used: 0.0%)
PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 142 $]::
Version: 8 Path: c:\pi\dat\testarc.dat
State: 4 Type: 0 (fixed) Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 262144 Add Rate/Hour: 2.4
Offsets: Primary: 17/131072 Overflow: 262055/262144
Annotations: 5541/65535 Annotation File Size: 1491116
Start Time: 27-Jul-10 17:29:30
End Time: Current Time
Backup Time: 29-Jul-10 03:15:24
Last Modified: 29-Jul-10 13:28:56

In the above listing, the archive file is c:\pi\dat\testarc.dat. The corresponding annotation file is c:\pi\dat\testarc.dat.ann. There are 5,541 annotations with space for a total of 65,535 and the annotation file is 1,491,116 bytes (1.42 MB).

The annotation file is created if it does not exist. The archive and annotation files must remain together, especially when restoring a backed-up archive file. PI SDK supplies a programmatic interface for creating, accessing, and editing annotations. The PI SDK User Guide is the best source for details on valid variants for annotations.