6 Replies Latest reply on Nov 26, 2013 4:23 PM by lZheng

    PI file annotation




      I need to add annotations to PI values.


      I tried to add String annotations and it works fine. Here is the code line used :


      spPIAnns->Add(L"Point State", L"StringAnnotation", L"INVALID", false, VT_BSTR);


      Now I want to add file annotations. What would be the matching code line for that ?




      Thank you for your help.



        • Re: PI file annotation

          Hello Cyril,


          Sorry but storing files in PI Annotations is not a good idea. I recall that Annotations records have a size of 1024 bytes, similar to PI Archive records. I am not saying it's impossible to store files within Annotations but you would need to expect significant performance impact. We rather suggest storing the path / link to files as string within Annotations.

            • Re: PI file annotation

              Hello Cyril,


              One of our PI Server developers contacted me and asked me to clarify:


              In recent versions of the PI Server, the default annotation size limit is 1024 KB (not bytes). PI Server 2012 even has a Tuning Parameter "Snapshot_AnnotationSizeLimit" that allows to control the size limit. (In prior version, the event queue page size was controlling how big annotations could be.)

              Tuning Parameter









              Maximum allowed size of an annotation. Setting to a value of 0 disables this check.

              Value units are in kb. Parameter takes effect at startup only.

              Annotations were (and are still) designed to store occasional operator comments, not very large blobs or continuous data.

                • Re: PI file annotation

                  Hello Gregor,


                  thank you for your help.


                  I need to investigate more on this subject to know what I'm going to do.


                  But I would like the code line to add file annotations to do some test.





                    • Re: PI file annotation

                      Hi Cyril,


                      Gregor's idea is good to store the path of the file which you need.  However, if you need to store the whole content in the file into Annotation, the only way is to convert the content into a string object, then store this string into Annotation.  In spite of this, we strong suggest you not to do this.  PI Data Archive system is used to store the time-serial data, and the Annotation is just use to store some key comment for the specific data.  Could you please tell us if all your time-serial data will include the different large comment?


                      Xi Wang


                      v-Campus team

                        • Re: PI file annotation

                          Hi Xi,


                          Not all time serial data will include the large comment.


                          You said that "if you need to store the whole content in the file into Annotation, the only way is to convert the content into a string object, then store this string into Annotation".


                          But in annotations, there is a file type. And in PI SDK Help, I found that :


                          IsFile Property (PIAnnotation object)


                          The PIAnnotation’s IsFile parameter is true if the Value of the annotation is a file. It is returned as a read-only Boolean.






                          The object placeholder is an object expression that evaluates to a PIAnnotation object.




                          This is a read only property. It is set when you Import a file to the annotation.


                          You can use this property to determine whether or not an annotation's Value is a file. If it is, you can use the Export method to restore the file.



                          I don't understand. Is it possible or not to to store a file into Annotations ?




                          Thank you for your help ...





                            • Re: PI file annotation

                              Hi Cyril,


                              It is possible to store a file into Annotations. In fact annotation maintenance is supported in ProcessBook. 


                              It's also possible to add an annotation file programmatically, please see this post:




                              I have tested following code, a text file was successfully added to the event as annotation.  

                               PISDK.PIPoint point = _server.PIPoints["Anntag"];
                                          // Prepare retrieval of Annotations when reading data from this PI Point
                                          NamedValues retrievalAttributes = new NamedValues();
                                          object oAnnotationsString = "Annotated";
                                          retrievalAttributes.Add("Annotated", ref oAnnotationsString);
                                          point.Data.RetrievalAttributes = retrievalAttributes;
                                          PIAnnotations annAnnotations = new PIAnnotations();
                                          // Read a value in the archive
                                         PISDK.PIValue value = point.Data.ArcValue("*", PISDK.RetrievalTypeConstants.rtAuto, null);
                                          //annAnnotations.Add("myfirstAnnotation", "This is my annotation file", "C:\\Myfile.txt", true, null);
                                          // Update the value in the archive
                                          //point.Data.UpdateValue(value, 0, PISDK.DataMergeConstants.dmReplaceDuplicates, null);
                                              // Try to obtain current annotation(s) on the value
                                              PISDKCommon.NamedValue nvAnnotations = value.ValueAttributes.get_Item(ref oAnnotationsString);
                                              // There is one of more annotation(s)
                                              if (nvAnnotations.Value != null)
                                                  // If annotation is structured
                                                  if (nvAnnotations.Value is PISDK.PIAnnotations)
                                                      // Hold a reference to the current structured annotation(s)
                                                      annAnnotations = (PISDK.PIAnnotations)nvAnnotations.Value;
                                                  // If annotation is unstructured (old style)
                                                      // Convert the old style annotation into a structured one
                                                      annAnnotations.Add("Converted Annotation", "Converted Annotation", nvAnnotations.Value.ToString(), false, null);
                                                      nvAnnotations.Value = annAnnotations;
                                          catch (Exception ex)
                                              object oAnnotations = annAnnotations;
                                              value.ValueAttributes.Add("Annotations", ref oAnnotations);
                                              // Add the desired annotation
                               annAnnotations.Add("myfirstAnnotation", "This is my annotation file", "C:\\Myfile.txt", true, null);
                                              // Update the value in the archive
                                              point.Data.UpdateValue(value, 0, PISDK.DataMergeConstants.dmReplaceDuplicates, null);

                               However I would again recommend you to be careful with storing file in annotations, as Gregor mentioned before, it will impact the performance, also it can cause archive shift when archive file is barely full but annotation file reaches its maximum size.