Accessing annotations

Annotations can be retrieved from the model itself during its execution or before/after execution from the calling program (using the Mosel libraries). The following example annottest.mos shows how to retrieve an annotation that is defined in the same model. The subroutine getannotations is defined by mmjobs, it takes an additional first argument of type Model if it is to be applied to a submodel and not the model itself.

model "Using annotations"
 uses "mmjobs"

 public declarations
(!@.
  @value.first 5
  @value.second 0
  @descr A scalar value
 !)
  myint: integer
  AnnNames: set of string          !@descr Set of annotation names
  Ann: array(string) of string     !@descr Annotation values
  mytxt: text                      !@descr Default input data file
 end-declarations

 !@descr Annotations test
 !@furtherinfo Simply displays all defined global or specific annotations

 ! Get all global annotations defined in this model:
 getannotations("", "", AnnNames, Ann)
 writeln("Global annotations:")
 forall(a in AnnNames) writeln("  ", a, " = ", Ann(a))

 ! Get all annotations for "myint":
 getannotations("myint", "", AnnNames, Ann)
 writeln("Annotations defined for 'myint':")
 forall(a in AnnNames) writeln("  ", a, " = ", Ann(a))

 ! Retrieve all annotations starting with 'value.' and that are
 ! associated to 'myint'
 getannotations("myint", "value.", AnnNames, Ann)
 writeln("'value' annotations for 'myint':")
 forall(a in AnnNames) writeln("  ", a, " = ", Ann(a))
end-model 

Running this model produces output like the following:

Global annotations:
  .descr = Annotations test
  .furtherinfo = Simply displays all defined global or specific annotations
Annotations defined for 'myint':
  .descr = A scalar value
  value.first = 5
  value.second = 0
'value' annotations for 'myint':
  value.first = 5
  value.second = 0

And here is an example how to retrieve annotations into a C program (file annotdisplay.c):

#define MAXANN 100

int main()
{
 XPRMmodel mod;
 void *ref;
 const char *symb;                    /* A model object name */
 const char *ann[MAXANN*2];           /* List of annotations */
 int i,n;

 if(XPRMinit()) return 1;             /* Initialize Mosel */
 if((mod=XPRMloadmod("annottest.bim",NULL))==NULL)  /* Load a BIM file */
  return 2;

/* Retrieve and display global annotations */
 n=XPRMgetannotations(mod,NULL,NULL,ann,MAXANN*2);
 printf("Global annotations (total: %d):\n", n/2);
 for(i=0;i<n && i<MAXANN;i+=2)
  printf("   %s:%s\n",ann[i],(ann[i+1]!=NULL)?ann[i+1]:"");

/* Retrieve and display all annotations associated with model objects */
 printf("Annotations associated with objects:\n");
 ref=NULL;
 while((symb=XPRMgetnextanident(mod,&ref))!=NULL)
 {
  n=XPRMgetannotations(mod,symb,NULL,ann,MAXANN*2);
  printf(" %s->\n",symb);
  for(i=0;i<n && i<MAXANN;i+=2)
   printf("   %s:%s\n",ann[i],(ann[i+1]!=NULL)?ann[i+1]:"");
 }

/* Retrieve and display annotations for model object 'myint' */
 n=XPRMgetannotations(mod,"myint",NULL,ann,MAXANN*2);
 printf("Annotations defined for 'myint' (total: %d):\n", n/2);
 for(i=0;i<n && i<MAXANN;i+=2)
  printf("   %s:%s\n",ann[i],(ann[i+1]!=NULL)?ann[i+1]:"");

 return 0;
}

The corresponding Java code looks as follows:

public class annotdisplay
{
 public static void main(String[] args) throws Exception
 {
  XPRM mosel;
  XPRMModel mod;
  XPRMAnnotation ann[];                         // List of annotations

  mosel = new XPRM();                           // Initialize Mosel
  mod = mosel.loadModel("annottest.bim");       // Load a BIM file

// Retrieve and display global annotations
  ann=mod.getAnnotations("");
  System.out.println("Global annotations (total: "+ ann.length +"):");
  for(int i=0;i<ann.length;i++) System.out.println("   "+ann[i]);

// Retrieve and display all annotations associated with model objects
  System.out.println("Annotations associated with objects:");
  for(XPRMIdentifiers ids=mod.annotatedIdentifiers(); ids.hasNext();)
  {
   XPRMIdentifier id=(XPRMIdentifier)ids.next();
   ann=mod.getAnnotations(id,"");
   System.out.println(" "+id.getName()+"->");
   for(int i=0;i<ann.length;i++) System.out.println("   "+ann[i]);
  }

// Retrieve and display annotations for model object 'myint'
  ann=mod.getAnnotations("myint","");
  System.out.println("Annotations defined for 'myint' (total: "+ ann.length +"):");
  for(int i=0;i<ann.length;i++) System.out.println("   "+ann[i]);
 }
}

Notice that the host application only needs to load the BIM file (and not necessarily run a model) in order to be able to retrieve the annotations.