NAPI Example

[Ray Osborn]

I received e-mail from Chris Moreton-Smith about problems he has had
explaining the NeXus API to others.  With his permission, I am forwarding
it to the NeXus mailing list, since it might reflect fairly general
concerns.   If you have any similar problems understanding what we have
written, please write to the list, so that we can clear them up.

Chris Moreton-Smith <C.Moreton-Smith at rl.ac.uk> wrote:

>Over the last two or three days I've had a fairly interesting time explaining
>what is going on to someone who is trying to construct their first NeXus
>file.
> I think there are a few points which should be made here.
>
>The example rather focuses on the NXdata vgroup at the expense of the others,
>unfortunately this seems to have had a rather misleading effect on the
>interpretation of how the standard works.  Here are a few of the confusions
>that have come up.
>
>1) As the NXdata vgroup is almost unique in its use of attributes.  The first
>conclusion drawn is that all the dictionary entries are added as
>attributes to
>the respective groups - oops.

I'm not sure I fully understand how this misunderstanding arises.  The
attribute section is completely separate from the rest of the glossary.
However, if others share this confusion, I might add some comments to make
clear the distinction between data items and their attributes.

For the record, NeXus files consist of only data items (implemented as HDF
SDSs) and data groups (implemented as HDF Vgroups).  However, data items
can have some extra information or annotation, such as their units,
attached to them as attributes.  So far, there are only a very limited
number of attributes defined in the NeXus standard.

>
>2) NXEntry gets missed out almost altogether (not helped by the fact that
>Nxclose is only called once in the example and not twice to return to the top
>level before closing the file!). The absence of other Vgroups and single
>valued
>entries in Nxentry rather helps with this.

I have now corrected the web example to close both groups correctly and
added some extra comments.

>
>3) MakeDATA gets associated with NXDATA  and not with any other item (quite
>naturally !).
>

I'm not sure what we can do about this, unless we change NXmakedata to some
neutral name such as NXmakeitem.

>
>Has anyone else found these interpretation problems?  If so could we
>improve or
>extend the examples to make the usage a bit clearer.  Any volunteers?
>
>	Chris

I have been reluctant to expand the example until the helper routines are
complete.  These will significantly reduce the number of API calls
necessary to write the data; without them, a more complex example would
become tiring to read.

If others agree that the documentation does not make this clear enough,
please let us know.  If you have time, it would be helpful to know which
section of the web pages could do with changing.

Thanks,
Ray Osborn

------------------------------------------------------
Dr Ray Osborn                  Tel: +1 (630) 252-9011
Materials Science Division     Fax: +1 (630) 252-7777
Argonne National Laboratory    E-mail: ROsborn at anl.gov
Argonne, IL 60439-4845


--------------------------------------------------------------------------------
Return-Path: <owner-nexus at anpns1.pns.anl.gov>
Received: from dns2.anl.gov by ipns.pns.anl.gov (MX V4.2 AXP) with SMTP; Wed,
          03 Sep 1997 12:30:06 CST
Received: from ANPNS6.PNS.ANL.GOV (anpns6.pns.anl.gov [146.139.156.97]) by
          dns2.anl.gov (8.6.11/8.6.11) with SMTP id MAA29122; Wed, 3 Sep 1997
          12:30:04 -0500
Received: from dns2.anl.gov by ANPNS1.PNS.ANL.GOV (MX V4.2 AXP) with SMTP; Wed,
          03 Sep 1997 12:29:59 CST
Received: from osborn.msd.anl.gov (osborn.msd.anl.gov [146.139.244.39]) by
          dns2.anl.gov (8.6.11/8.6.11) with ESMTP id MAA29114 for
          <NeXus at anl.gov>; Wed, 3 Sep 1997 12:29:53 -0500
Received: from [146.139.244.39] by osborn.msd.anl.gov with ESMTP (Eudora
          Internet Mail Server 1.1.2); Wed, 3 Sep 1997 12:29:37 -0500
Message-ID: <l03102805b0334960c572@[146.139.244.39]>