Changeset 1230

Timestamp:

14/04/09 18:56:40 (3 years ago)

Author:

Freddie Akeroyd

Message:

Merg in r1212:r1222 from trunk. Refs #115.

Location:

branches/4.2

Files:

• Windows_extra/libNeXus-0.def (modified) (2 diffs)
• bindings/cpp/NeXusFile.hpp (modified) (4 diffs)
• bindings/cpp/NeXusStream.cpp (modified) (2 diffs)
• bindings/cpp/NeXusStream.hpp (modified) (7 diffs)
• bindings/idl/NXtest.h5 (modified) (previous)
• bindings/idl/NXtest.hdf (modified) (previous)
• bindings/idl/NXtest.xml (modified) (1 diff)
• bindings/idl/data/dmc01.hdf (modified) (previous)
• bindings/idl/nxext.h5 (modified) (previous)
• bindings/idl/nxext.hdf (modified) (previous)
• bindings/idl/nxext.xml (modified) (previous)
• bindings/python/nxs/napi.py (modified) (22 diffs)
• bindings/python/nxstest.py (modified) (4 diffs)
• doc/doxygen/Doxyfile.in (modified) (2 diffs)
• include/napi.h (modified) (41 diffs)
• src/napi.c (modified) (2 diffs)
• src/napi4.c (modified) (1 diff)
• src/napi5.c (modified) (1 diff)
• src/napi_exports.h (modified) (1 diff)
• src/nexus_symbols_win.txt (modified) (1 diff)

branches/4.2/Windows_extra/libNeXus-0.def

@@ -22 +22 @@
 _NXIGETGROUPINFO@16
 _NXIGETINFO@16
+_NXIGETRAWINFO@16
 _NXIGETNEXTATTR@16
 _NXIGETNEXTENTRY@16
@@ -81 +82 @@
 nxigetgroupid_
 nxigetgroupinfo_
+nxigetrawinfo_
 nxigetinfo_
 nxigetnextattr_

branches/4.2/bindings/cpp/NeXusFile.hpp

@@ -22 +22 @@
  * Documentation for the NeXus C++ API.
  * 2000-2008 the NeXus group.
+ * \defgroup cpp_types C++ Types
+ * \ingroup cpp_main
+ * \defgroup cpp_core C++ Core
+ * \ingroup cpp_main
  */
 
@@ -37 +41 @@
    * \li INT64 int8_t if available on the machine
    * \li UINT64 uint8_t if available on the machine
+   * \ingroup cpp_types
    */
   enum NXnumtype {
@@ -60 +65 @@
    * \li RLE Run length encoding (only HDF-4)
    * \li HUF Huffmann encoding (only HDF-4)
+   * \ingroup cpp_types
    */
   enum NXcompression {
@@ -90 +96 @@
   /**
    * The Object that allows access to the information in the file.
+   * \ingroup cpp_core
    */
   class NXDLL_EXPORT File

branches/4.2/bindings/cpp/NeXusStream.cpp

@@ -30 +30 @@
 // Revision of last commit $LastChangedRevision$ 
 // Date of last commit     $LastChangedDate$
-// Author of last commit   $LastChangedBy$
+// Last changed by         $LastChangedBy$
 //////////////////////////////////////////////////////////////////////////
 
@@ -36 +36 @@
  * \file NeXusStream.cpp
  * Implementation of IOStream like interface to NeXus files
+ * \author Freddie Akeroyd, STFC ISIS Facility, GB
  * \version $LastChangedRevision$
  * \date    $LastChangedDate$

branches/4.2/bindings/cpp/NeXusStream.hpp

@@ -31 +31 @@
 // Revision of last commit $LastChangedRevision$ 
 // Date of last commit     $LastChangedDate$
-// Author of last commit   $LastChangedBy$
+// Last changed by         $LastChangedBy$
 //////////////////////////////////////////////////////////////////////////
 
@@ -37 +37 @@
  * \file NeXusStream.hpp
  * Header for IOStream like interface to NeXus files
+ * \author Freddie Akeroyd, STFC ISIS Facility, GB
  * \version $LastChangedRevision$
  * \date    $LastChangedDate$
+ * \defgroup cpp_stream IOstream like interface
+ * \ingroup cpp_main
  */
 
@@ -57 +60 @@
     };
 
+    /// \ingroup cpp_stream
     enum StreamModifier { Close=0 };
 
@@ -95 +99 @@
     };
 
+    /// \ingroup cpp_stream
     class NXDLL_EXPORT Attr : public ISerialisable
     {
@@ -164 +169 @@
     };
     
+    /// \ingroup cpp_stream
     class NXDLL_EXPORT Group : public ObjectWithAttr
     {
@@ -214 +220 @@
     };
 
+    /// \ingroup cpp_stream
     class NXDLL_EXPORT Data : public ObjectWithAttr
     {
@@ -245 +252 @@
     };
 
+    /// \ingroup cpp_stream
    NXDLL_EXPORT File& operator<<(File& nf, const ISerialisable& obj);
+    
+    /// \ingroup cpp_stream
    NXDLL_EXPORT File& operator>>(File& nf, const ISerialisable& obj);
 
+    /// \ingroup cpp_stream
    NXDLL_EXPORT File& operator<<(File& nf, const StreamModifier sm);
+ 
+    /// \ingroup cpp_stream
    NXDLL_EXPORT File& operator>>(File& nf, const StreamModifier sm);
 

branches/4.2/bindings/idl/NXtest.xml

@@ -4 +4 @@
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://definition.nexusformat.org/schema/3.0 http://definition.nexusformat.org/schema/3.0/BASE.xsd"
-file_time="2009-01-20T08:33:43+01:00">
+file_time="2009-02-20T10:05:53+01:00">
     <NXentry name="entry" hugo="namenlos" cucumber="passion">
       <ch_data NAPItype="NX_CHAR[10]">NeXus Data</ch_data>

branches/4.2/bindings/python/nxs/napi.py

@@ -419 +419 @@
         Corresponds to NXmakegroup(handle, name, nxclass)
         """
+        #print "makegroup",self._loc(),name,nxclass
         status = nxlib.nximakegroup_(self.handle, name, nxclass)
         if status == ERROR:
@@ -556 +557 @@
         Corresponds to NXopengroup(handle, name, nxclass)
         """
-        #print "open group",nxclass,name
+        #print "opengroup",self._loc(),name,nxclass
         if nxclass is None:
             nxclass = self.__getnxclass(name)
@@ -575 +576 @@
         Corresponds to NXclosegroup(handle)
         """
-        #print "close group"
+        #print "closegroup"
+        if self._indata:
+            raise NeXusError, "Close data before group at %s"%(self._loc())
         status = nxlib.nxiclosegroup_(self.handle)
         if status == ERROR:
-            raise NeXusError, "Could not close group at %s"%(name,self._loc())
+            raise NeXusError, "Could not close group at %s"%(self._loc())
         self._path.pop()
 
@@ -603 +606 @@
         if status == ERROR:
             raise ValueError, "Could not get group info: %s"%(self._loc())
-        #print "group info",nxclass.value,name.value,n.value
+        #print "getgroupinfo",self._loc(),nxclass.value,name.value,n.value
         name = path.value.split('/')[-1]  # Protect against HDF5 returning path
         return n.value,name,nxclass.value
@@ -655 +658 @@
         #if nxclass == 'SDS':
         #    dtype = _pytype_code(storage.value)
-        #print "group next",nxclass.value, name.value, storage.value
+        #print "nextentry",nxclass.value, name.value, storage.value
         return name.value,nxclass.value
 
@@ -728 +731 @@
 
     # ==== Data ====
-    nxlib.nxigetinfo_.restype = c_int
-    nxlib.nxigetinfo_.argtypes = [c_void_p, c_int_p, c_void_p, c_int_p]
-    def getinfo(self):
+    nxlib.nxigetrawinfo_.restype = c_int
+    nxlib.nxigetrawinfo_.argtypes = [c_void_p, c_int_p, c_void_p, c_int_p]
+    def getrawinfo(self):
         """
         Returns the tuple dimensions,type for the currently open dataset.
@@ -740 +743 @@
         complex values.
 
+        Unlike getinfo(), the size of the string storage area is
+        returned rather than the length of the stored string.
+
+        Raises NeXusError if this fails.
+
+        Corresponds to NXgetrawinfo(handle, &rank, dims, &storage),
+        but with storage converted from HDF values to numpy compatible
+        strings, and rank implicit in the length of the returned dimensions.
+        """
+        rank = c_int(0)
+        shape = numpy.zeros(MAXRANK, 'i')
+        storage = c_int(0)
+        status = nxlib.nxigetrawinfo_(self.handle, _ref(rank), shape.ctypes.data,
+                                     _ref(storage))
+        if status == ERROR:
+            raise NeXusError, "Could not get data info: %s"%(self._loc())
+        shape = shape[:rank.value]+0
+        dtype = _pytype_code[storage.value]
+        #print "getrawinfo",self._loc(),"->",shape,dtype
+        return shape,dtype
+
+    nxlib.nxigetinfo_.restype = c_int
+    nxlib.nxigetinfo_.argtypes = [c_void_p, c_int_p, c_void_p, c_int_p]
+    def getinfo(self):
+        """
+        Returns the tuple dimensions,type for the currently open dataset.
+        Dimensions is an integer array whose length corresponds to the rank
+        of the dataset and whose elements are the size of the individual
+        dimensions.  Storage type is returned as a string, with 'char' for
+        a stored string, '[u]int[8|16|32]' for various integer values or
+        'float[32|64]' for floating point values.  No support for
+        complex values.
+
+        Unlike getrawinfo(), the length of the stored string is
+        returned rather than the size of the string storage area.
+
         Raises NeXusError if this fails.
 
@@ -758 +797 @@
         shape = shape[:rank.value]+0
         dtype = _pytype_code[storage.value]
-        #print "data info",shape,dtype
+        #print "getinfo",self._loc(),"->",shape,dtype
         return shape,dtype
 
@@ -771 +810 @@
         Corresponds to NXopendata(handle, name)
         """
-        #print "opening data",name
-        status = nxlib.nxiopendata_(self.handle, name)
+        #print "opendata",self._loc(),name
+        if self._indata:
+            status = ERROR
+        else:
+            status = nxlib.nxiopendata_(self.handle, name)
         if status == ERROR:
             raise ValueError, "Could not open data %s: %s"%(name, self._loc())
@@ -789 +831 @@
         Corresponds to NXclosedata(handle)
         """
-        #print "closing data"
+        #print "closedata"
         status = nxlib.nxiclosedata_(self.handle)
         if status == ERROR:
             raise NeXusError,\
-                "Could not close data at %s"%(name,self._loc())
+                "Could not close data at %s"%(self._loc())
         self._path.pop()
         self._indata = False
@@ -815 +857 @@
         # TODO: With keywords for value and attr, this can be used for
         # TODO: makedata, opendata, putdata, putattr, putattr, ..., closedata
-        #print "Data",name,dtype,shape
+        #print "makedata",self._loc(),name,shape,dtype
         storage = _nxtype_code[str(dtype)]
         shape = numpy.array(shape,'i')
@@ -865 +907 @@
         Return the data.  If data is a string (1-D char array), a python
         string is returned.  If data is a scalar (1-D numeric array of
-        length 1), a python numeric scalar is returned.
+        length 1), a python scalar is returned.  If data is a string 
+        array, a numpy array of type 'S#' where # is the maximum string
+        length is returned.  If data is a numeric array, a numpy array
+        is returned.
 
         Raises ValueError if this fails.
@@ -873 +918 @@
         # TODO: consider accepting preallocated data so we don't thrash memory
         shape,dtype = self.getinfo()
-        datafn,pdata,size = self._poutput(dtype,shape)
+        data,pdata,size,datafn = self._poutput(dtype,shape)
         status = nxlib.nxigetdata_(self.handle,pdata)
         if status == ERROR:
             raise ValueError, "Could not read data: %s"%(self._loc())
-        #print "data",ret()
+        #print "getdata",self._loc(),shape,dtype
         return datafn()
 
@@ -894 +939 @@
         """
         # TODO: consider accepting preallocated data so we don't thrash memory
-        shape,dtype = self.getinfo()
-        datafn,pdata,size = self._poutput(dtype,slab_shape)
+        shape,dtype = self.getrawinfo()
+        data,pdata,size,datafn = self._poutput(dtype,slab_shape)
         slab_offset = numpy.array(slab_offset,'i')
         slab_shape = numpy.array(slab_shape,'i')
@@ -916 +961 @@
         Corresponds to NXputdata(handle, data)
         """
-        shape,dtype = self.getinfo()
+        shape,dtype = self.getrawinfo()
+        #print "putdata",self._loc(),shape,dtype
         data,pdata = self._pinput(data,dtype,shape)
         status = nxlib.nxiputdata_(self.handle,pdata)
@@ -935 +981 @@
         Corresponds to NXputslab(handle,data,offset,shape)
         """
-        shape,dtype = self.getinfo()
+        shape,dtype = self.getrawinfo()
         data,pdata = self._pinput(data,dtype,slab_shape)
         slab_offset = numpy.array(slab_offset,'i')
@@ -1011 +1057 @@
             raise NeXusError, "Could not get next attr: %s"%(self._loc())
         dtype = _pytype_code[storage.value]
-        #print "next attr",name.value,length.value,dtype
+        #print "getnextattr",name.value,length.value,dtype
         return name.value, length.value, dtype
 
@@ -1027 +1073 @@
         """
         if dtype is 'char': length += 1  # HDF4 needs zero-terminator
-        datafn,pdata,size = self._poutput(str(dtype),[length])
+        data,pdata,size,datafn = self._poutput(str(dtype),[length])
         storage = c_int(_nxtype_code[str(dtype)])
-        #print "retrieving",name,length,dtype,size
+        #print "getattr",self._loc(),name,length,size,dtype
         size = c_int(size)
         status = nxlib.nxigetattr_(self.handle,name,pdata,_ref(size),_ref(storage))
         if status == ERROR:
             raise ValueError, "Could not read attr %s: %s" % (name,self._loc())
-        #print "attr",name,datafn(),size
+        #print "getattr",self._loc(),name,datafn()
         return datafn()
 
@@ -1304 +1350 @@
         """
         Build space to collect a nexus data element.
-        Returns datafn,data,size where
-        - datafn is a lamba expression to extract the value out of the element.
-        - pdata is the value to pass to C (effectively a void *)
+        Returns data,pdata,size,datafn where
+        - data is a python type to hold the returned data
+        - pdata is the pointer to the start of the data
         - size is the number of bytes in the data block
-        Note that ret can return a string, a scalar or an array depending
+        - datafn is a lamba expression to extract the return value from data
+        Note that datafn can return a string, a scalar or an array depending
         on the data type and shape of the data group.
         """
@@ -1314 +1361 @@
             # string - use ctypes allocator
             size = int(shape[0])
-            pdata = ctypes.create_string_buffer(size)
-            datafn = lambda: pdata.value
+            data = ctypes.create_string_buffer(size)
+            pdata = data
+            datafn = lambda: data.value
         else:
-            # numeric - use numpy array
-            if dtype=='char': dtype = 'uint8'
-            data = numpy.zeros(shape,dtype)
+            # scalar, array or string list - use numpy array
+            if dtype=='char': 
+                data = numpy.zeros(shape[:-1], dtype='S%i'%shape[-1])
+            else:
+                data = numpy.zeros(shape, dtype)
             if len(shape) == 1 and shape[0] == 1:
                 datafn = lambda: data[0]
@@ -1326 +1376 @@
             pdata = data.ctypes.data
             size = data.nbytes
-        return datafn,pdata,size
+        return data,pdata,size,datafn
 
     def _pinput(self, data, dtype, shape):
         """
-        Convert an input array to a C pointer to a dense array.  This may
-        require conversion of the array, so the new array is returned along
-        with its pointer.
+        Convert an input array to a C pointer to a dense array.
+
+        Returns data, pdata where 
+        - data is a possibly new copy of the array
+        - pdata is a pointer to the beginning of the array.  
+        Note that you must hold a reference to data for as long 
+        as you need pdata to keep the memory from being released to the heap.
         """
         if dtype == "char":
-            # Character data - pad with zeros to the right length
-            if not _is_string_like(data):
-                raise ValueError,"Expected character data: %s"%(self._loc())
-            if len(data) < shape[0]:
-                data += '\000'*(shape[0]-len(data))
+            data = numpy.asarray(data, dtype='S%d'%(shape[-1]))
         else:
             # Convert scalars to vectors of length one
             if numpy.prod(shape) == 1 and not hasattr(data,'shape'):
-                data = numpy.array([data],dtype=dtype)
+                data = numpy.array([data], dtype=dtype)
             # Check that dimensions match
             # Ick! need to exclude dimensions of length 1 in order to catch
@@ -1349 +1399 @@
             input_shape = numpy.array([i for i in data.shape if i != 1])
             target_shape = numpy.array([i for i in shape if i != 1])
-            if len(input_shape) != len(target_shape) or (input_shape != target_shape).any():
+            if len(input_shape) != len(target_shape) \
+                    or (input_shape != target_shape).any():
                 raise ValueError,\
-                    "Shape mismatch %s!=%s: %s"%(data.shape,shape,self.filename)
+                    "Shape mismatch %s!=%s: %s"%(data_shape,shape,self._loc())
+            # Check data type
             if str(data.dtype) != dtype:
                 raise ValueError,\
                     "Type mismatch %s!=%s: %s"%(dtype,data.dtype,self._loc())
 
-        if dtype == 'char':
-            # String: hand it over as usual for strings.  Assumes the string
-            # is the correct length for the storage area.
-            pdata = data
-        else:
-            # Vector: assume it is of the correct storage class and size
-            data = numpy.ascontiguousarray(data)
-            pdata = data.ctypes.data
-
+        data = numpy.ascontiguousarray(data)
+        pdata = data.ctypes.data
+            
         return data,pdata
 

branches/4.2/bindings/python/nxstest.py

@@ -132 +132 @@
     # .. demonstrate extensible data
     file.makedata('flush_data','int32',[nxs.UNLIMITED])
+    file.opendata('flush_data')
     for i in range(7):
-        file.opendata('flush_data')
         file.putslab(i,[i],[1])
-        file.flush()
-        # Oops... why isn't there a closedata()?
+    file.closedata()
+    file.flush()
     file.closegroup()
 
@@ -142 +142 @@
     file.makegroup('sample','NXsample')
     file.opengroup('sample','NXsample')
-    file.makedata('ch_data','char',[12])
+    file.makedata('ch_data','char',[20])
     file.opendata('ch_data')
     file.putdata('NeXus sample')
@@ -231 +231 @@
             fail("%s retrieved %s"%(dtype,get))
 
+
     # Check attribute types
     file.opendata('r8_data')
@@ -255 +256 @@
     for i in range(100): comp_array[i,:] *= i
     expected = comp_array
-    file.opengroup('data','NXdata')
-    file.opendata('comp_data')
+    file.opengroup('data','NXdata') #/entry/data
+    file.opendata('comp_data')      #/entry/data/comp_data
     get = file.getdata()
-    file.closedata()  #/entry/data/comp_data
-    file.closegroup() #/entry/data
+    file.closedata()                #/entry/data/comp_data
+    file.closegroup()               #/entry/data
     if not (get == expected).all():
         fail("compressed data differs")
         print get
+        
+    # Check strings
+    file.opengroup('sample','NXsample') #/entry/sample
+    file.opendata('ch_data')            #/entry/sample/ch_data
+    rawshape,rawdtype = file.getrawinfo()
+    shape,dtype = file.getinfo()
+    get = file.getdata()
+    file.closedata()                    #/entry/sample/ch_data
+    file.closegroup()                   #/entry/sample
+    if not (shape[0]==12 and dtype=='char'):
+        fail("returned string info is incorrect")
+        print shape,dtype
+    if not (rawshape[0]==20 and rawdtype=='char'):
+        fail("returned string storage info is incorrect")
+        print shape,dtype
+    if not (get == "NeXus sample"):
+        fail("returned string is incorrect")
+        print shape,dtype
+
+
     file.closegroup() #/entry
-        
+
     # Check read slab (e.g., from extensible)
 

branches/4.2/doc/doxygen/Doxyfile.in

@@ -407 +407 @@
 # by doxygen. Possible values are YES and NO. If left blank NO is used.
 
-QUIET                  = NO
+QUIET                  = YES
 
 # The WARNINGS tag can be used to turn on/off the warning messages that are 
@@ -1007 +1007 @@
 
 PREDEFINED             = \
-        HDF4 \
-        HDF5 \
-        NXXML
+        HDF4=1 \
+        HDF5=1 \
+        NXXML=1 \
+        NXDLL_EXPORT=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then 

branches/4.2/include/napi.h

@@ -27 +27 @@
 /** \file 
  * Documentation for the NeXus-API version 4.2
- * 2000-2007, the NeXus group 
+ * 2000-2007, the NeXus group
+ * \defgroup c_main C API 
+ * \defgroup c_types Data Types
+ * \ingroup c_main
+ * \defgroup c_init General Initialisation and shutdown
+ * \ingroup c_main
+ * \defgroup c_readwrite Reading and Writing
+ * \ingroup c_main
+ * \defgroup c_metadata Meta data routines
+ * \ingroup c_main
+ * \defgroup c_linking Linking and Group hierarchy
+ * \ingroup c_main
+ * \defgroup c_memory Memory allocation
+ * \ingroup c_main
+ * \defgroup c_external External linking
+ * \ingroup c_main
+ * \defgroup cpp_main C++ API
  */
   
@@ -95 +111 @@
 
 /** \var NeXus data types
+ * \ingroup c_types
  * \li NX_FLOAT32     32 bit float
  * \li NX_FLOAT64     64 nit float == double
@@ -182 +199 @@
 
 #    define NXgetinfo           MANGLE(nxigetinfo)
+#    define NXgetrawinfo        MANGLE(nxigetrawinfo)
 #    define NXgetnextentry      MANGLE(nxigetnextentry)
 #    define NXgetdata           MANGLE(nxigetdata)
@@ -243 +261 @@
    * \param pHandle A file handle which will be initialized upon successfull completeion of NXopen.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_init
    */
 extern  NXstatus  NXopen(CONSTCHAR * filename, NXaccess access_method, NXhandle* pHandle);
+
   /**
    * close a NeXus file
@@ -250 +270 @@
    * call.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_init
    */
 extern  NXstatus  NXclose(NXhandle* pHandle);
+
   /**
    * flush data to disk
    * \param pHandle A NeXus file handle as initialized by NXopen. 
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXflush(NXhandle* pHandle);
@@ -266 +289 @@
    * \param NXclass the class name of the group. Should start with the prefix NX
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_init
    */
 extern  NXstatus  NXmakegroup (NXhandle handle, CONSTCHAR *name, CONSTCHAR* NXclass);
+
   /**
    * Step into a group. All further access will be within the opened group.
@@ -274 +299 @@
    * \param NXclass the class name of the group. Should start with the prefix NX
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_init
    */
 extern  NXstatus  NXopengroup (NXhandle handle, CONSTCHAR *name, CONSTCHAR* NXclass);
+
   /**
    * Open the NeXus object with the path specified
@@ -283 +310 @@
    * Example: /entry1/sample/name 
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_init
    */
 extern  NXstatus  NXopenpath (NXhandle handle, CONSTCHAR *path);
+
   /**
    * Opens the group in which the NeXus object with the specified path exists
@@ -292 +321 @@
    * Example: /entry1/sample/name 
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXopengrouppath (NXhandle handle, CONSTCHAR *path);
+
   /**
    * Closes the currently open group and steps one step down in the NeXus file 
    * hierarchy.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_init
    */
 extern  NXstatus  NXclosegroup(NXhandle handle);
+
   /**
    * Create a multi dimensional data array or dataset. The dataset is NOT opened. 
@@ -309 +342 @@
    * can be NX_UNLIMITED. Data can be appended to such a dimension using NXputslab. 
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_init
    */
 extern  NXstatus  NXmakedata (NXhandle handle, CONSTCHAR* label, int datatype, int rank, int dim[]);
+
   /**
    * Create a compressed dataset. The dataset is NOT opened. Data from this set will automatically be compressed when 
@@ -329 +364 @@
    * should be the same as the data dimension. If you write it in slabs, this is your preferred slab size. 
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_init
    */
 extern  NXstatus  NXcompmakedata (NXhandle handle, CONSTCHAR* label, int datatype, int rank, int dim[], int comp_typ, int bufsize[]);
+
   /**
    * Switch compression on. This routine is superseeded by NXcompmakedata and thus 
@@ -340 +377 @@
    * \li NX_COMP_RLE run length encoding (only HDF-4)
    * \li NX_COMP_HUF Huffmann encoding (only HDF-4)
+   * \ingroup c_init
    */
 extern  NXstatus  NXcompress (NXhandle handle, int compr_type);
+
   /**
    * Open access to a dataset. After this call it is possible to write and read data or 
@@ -348 +387 @@
    * \param label The name of the dataset
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_init
    */
 extern  NXstatus  NXopendata (NXhandle handle, CONSTCHAR* label);
+
   /**
    * Close access to a dataset. 
    * \param handle A NeXus file handle as initialized by NXopen. 
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXclosedata(NXhandle handle);
+
   /**
    * Write data to a datset which has previouly been opened with NXopendata. 
@@ -363 +406 @@
    * \param data Pointer to data to write.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_init
    */
 extern  NXstatus  NXputdata(NXhandle handle, void* data);
+
   /**
    * Write an attribute. The kind of attribute written depends on the  
@@ -376 +421 @@
    * \param iType The NeXus data type of the attribute. 
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXputattr(NXhandle handle, CONSTCHAR* name, void* data, int iDataLen, int iType);
+
   /**
    * Write  a subset of a multi dimensional dataset.
@@ -385 +432 @@
    * \param size An array holding the size of the data subset to write in each dimension.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXputslab(NXhandle handle, void* data, int start[], int size[]);    
+
   /**
    * Retrieve link data for a dataset. This link data can later on be used to link this 
@@ -394 +443 @@
    * for linking. 
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXgetdataID(NXhandle handle, NXlink* pLink);
+
   /**
    * Create a link to the group or dataset described by pLink in the currently open 
@@ -403 +454 @@
    * by either a call to NXgetdataID or NXgetgroupID.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXmakelink(NXhandle handle, NXlink* pLink);
+
   /**
    * Create a link to the group or dataset described by pLink in the currently open 
@@ -413 +466 @@
    * by either a call to NXgetdataID or NXgetgroupID.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_linking
    */
 extern  NXstatus  NXmakenamedlink(NXhandle handle, CONSTCHAR* newname, NXlink* pLink);
+
   /**
    * Open the source group of a linked group or dataset. Returns an error when the item is 
@@ -420 +475 @@
    * \param handle A NeXus file handle as initialized by NXopen.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_linking
    */
 extern  NXstatus  NXopensourcegroup(NXhandle handle);
+
   /**
    * Read a complete dataset from the currently open dataset into memory. 
@@ -429 +486 @@
    * and unwelcome ways.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXgetdata(NXhandle handle, void* data);
+
   /**
    * Retrieve information about the curretly open dataset.
@@ -440 +499 @@
    * \param datatype A pointer to an integer which be set to the NeXus data type code for this dataset.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_metadata
    */
 extern  NXstatus  NXgetinfo(NXhandle handle, int* rank, int dimension[], int* datatype);
+
   /**
    * Get the next entry in the currently open group. This is for retrieving infromation about the 
@@ -451 +512 @@
    * \param datatype The NeXus data type if the item is a SDS. 
    * \return NX_OK on success, NX_ERROR in the case of an error, NX_EOD when there are no more items.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXgetnextentry(NXhandle handle, NXname name, NXname nxclass, int* datatype);
+
   /**
    * Read a subset of data from file into memory. 
@@ -461 +524 @@
    * \param size An array holding the size of the data subset to read for each dimension.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXgetslab(NXhandle handle, void* data, int start[], int size[]);
+
   /**
    * Iterate over global, group or dataset attributes depending on the currently open group or 
@@ -472 +537 @@
    * \param iType A pointer to an integer which be set to the NeXus data type of the attribute.
    * \return NX_OK on success, NX_ERROR in the case of an error, NX_EOD when there are no more items.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXgetnextattr(NXhandle handle, NXname pName, int *iLength, int *iType);
+
   /**
    * Read an attribute.
@@ -482 +549 @@
    * \param iType A pointer to an integer which will had been set to the NeXus data type of the attribute.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXgetattr(NXhandle handle, char* name, void* data, int* iDataLen, int* iType);
+
   /**
    * Get the count of attributes in the currently open dataset, group or global attributes when at root level.
@@ -489 +558 @@
    * \param no_items A pointer to an integer which be set to the number of attributes available.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXgetattrinfo(NXhandle handle, int* no_items);
+
   /**
    * Retrieve link data for the currently open group. This link data can later on be used to link this 
@@ -498 +569 @@
    * for linking. 
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXgetgroupID(NXhandle handle, NXlink* pLink);
+
   /**
    * Retrieve information about the currently open group.
@@ -509 +582 @@
    * \param nxclass The NeXus class name of the group.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXgetgroupinfo(NXhandle handle, int* no_items, NXname name, NXname nxclass);
+
   /**
    * Tests if two link data structures describe the same item.
@@ -517 +592 @@
    * \param pSecondID The second link data structure.
    * \return NX_OK when both link data structures describe the same item, NX_ERROR else.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXsameID(NXhandle handle, NXlink* pFirstID, NXlink* pSecondID);
@@ -524 +600 @@
    * \param handle A NeXus file handle as initialized by NXopen.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXinitgroupdir(NXhandle handle);
+
   /**
    * Resets a pending attribute search to the start again. To be called in a Nxgetnextattr loop when 
@@ -531 +609 @@
    * \param handle A NeXus file handle as initialized by NXopen.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXinitattrdir(NXhandle handle);
+
   /**
    * Sets the format for number printing. This call has only an effect when using the XML physical file 
@@ -540 +620 @@
    * \param format The C-language format string to use for this data type.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXsetnumberformat(NXhandle handle, int type, char *format);
+
   /**
    * Inquire the filename of the currently open file. FilenameBufferLength of the file name 
@@ -549 +631 @@
    * \param  filenameBufferLength The length of the filename buffer.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXinquirefile(NXhandle handle, char *filename, int filenameBufferLength);
+
   /**
    * Test if a group is actually pointing to an external file. If so, retrieve the URL of the 
@@ -560 +644 @@
    * \param urlLen The length of the Url buffer. At maximum urlLen bytes will be copied to url.
    * \return NX_OK when the group is pointing to an external file, NX_ERROR else.
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXisexternalgroup(NXhandle handle, CONSTCHAR *name, CONSTCHAR *nxclass, char *url, int urlLen); 
+
   /**
    * Create a link to an external file. This works by creating a NeXus group under the current level in 
@@ -572 +658 @@
    * path to the group in the external file which appears in the first file.  
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_readwrite
    */
 extern  NXstatus  NXlinkexternal(NXhandle handle, CONSTCHAR *name, CONSTCHAR *nxclass, CONSTCHAR *url);
+
   /**
    * Utility function which allocates a suitably sized memory area for the dataset characteristics specified.
@@ -581 +669 @@
    * \param datatype The NeXus data type of the data.
    * \return NX_OK when allocation succeeds, NX_ERROR in the case of an error.   
+   * \ingroup c_memory
    */ 
 extern  NXstatus  NXmalloc(void** data, int rank, int dimensions[], int datatype);
+
   /**
    * Utility function to release the memory for data.
    * \param data A pointer to a pointer to free.
    * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_memory
    */
 extern  NXstatus  NXfree(void** data);
@@ -594 +685 @@
     NAPI internals 
 ------------------------------------------------------------------------*/
+  /**
+   * Retrieve information about the currently open dataset. In contrast to the main function below, 
+   * this function does not try to find out about the size of strings properly. 
+   * \param handle A NeXus file handle as initialized by NXopen.
+   * \param rank A pointer to an integer which will be filled with the rank of 
+   * the dataset.
+   * \param dimension An array which will be initialized with the size of the dataset in any of its 
+   * dimensions. The array must have at least the size of rank.
+   * \param datatype A pointer to an integer which be set to the NeXus data type code for this dataset.
+   * \return NX_OK on success, NX_ERROR in the case of an error.   
+   * \ingroup c_metadata
+   */
+extern  NXstatus  NXgetrawinfo(NXhandle handle, int* rank, int dimension[], int* datatype);
+
 /** \typedef void (*ErrFunc)(void *data, char *text)
  * All NeXus error reporting happens through this special function, the 
@@ -603 +708 @@
  */
 typedef void (*ErrFunc)(void *data, char *text);
+
   /**
    * Set an error function.
@@ -610 +716 @@
    */
 extern  void  NXMSetError(void *pData, ErrFunc newErr);
+
   /**
    * Retrieve the current error display function
@@ -615 +722 @@
    */
 extern ErrFunc NXMGetError();
+
   /**
    * Suppress error reports from the NeXus-API
    */
 extern  void  NXMDisableErrorReporting();
+
   /**
    * Enable error reports from the NeXus-API

branches/4.2/src/napi.c

@@ -35 +35 @@
 #include "napi.h"
 #include "nxstack.h"
+
+/**
+ * \mainpage NeXus API documentation
+ * \section sec_purpose Purpose of API
+ * The NeXus Application Program Interface is a suite of subroutines, written in C but with wrappers in Fortran 77 and 90. 
+ *  The subroutines call HDF routines to read and write the NeXus files with the correct structure. 
+ * An API serves a number of useful purposes: 
+ * - It simplifies the reading and writing of NeXus files. 
+ * - It ensures a certain degree of compliance with the NeXus standard. 
+ * - It allows the development of sophisticated input/output features such as automatic unit conversion. This has not been implemented yet. 
+ * - It hides the implementation details of the format. In particular, the API can read and write HDF4, 
+     HDF5 (and shortly XML) files using the same routines. 
+ * For these reasons, we request that all NeXus files are written using the supplied API. We cannot be 
+ * sure that anything written using the underlying HDF API will be recognized by NeXus-aware utilities. 
+ *
+ * \section sec_core Core API
+ * The core API provides the basic routines for reading, writing and navigating NeXus files. It is designed to be modal; 
+ * there is a hidden state that determines which groups and data sets are open at any given moment, and 
+ * subsequent operations are implicitly performed on these entities. This cuts down the number of parameters 
+ * to pass around in API calls, at the cost of forcing a certain pre-approved mode d'emploi. This mode d'emploi 
+ * will be familiar to most: it is very similar to navigating a directory hierarchy; in our case, NeXus groups are the 
+ * directories, which contain data sets and/or other directories. 
+ *
+ * The core API comprises several functional groups which are listed on the \b Modules tab 
+ *
+ * C programs that call the above routines should include the following header file: 
+ * \code
+ * #include "napi.h"
+ * \endcode
+ */
+
+
 
 /*---------------------------------------------------------------------
@@ -825 +857 @@
     return status;
   }
-    
+/*---------------------------------------------------------------------------*/
+  NXstatus  NXgetrawinfo (NXhandle fid, int *rank, 
+                                    int dimension[], int *iType)
+  {
+    int status;
+    char *pPtr = NULL;
+
+    pNexusFunction pFunc = handleToNexusFunc(fid);
+    status = pFunc->nxgetinfo(pFunc->pNexusData, rank, dimension, iType);
+    return status;
+  }
   /*-------------------------------------------------------------------------*/
  

branches/4.2/src/napi4.c

@@ -1145 +1145 @@
     iRet = SDwritedata (pFile->iCurrentSDS, iStart, iStride, iSize, data);
     if (iRet < 0) {
+      /* HEprint(stdout,0); */
       sprintf (pError, "ERROR: failure to write data to %s", pBuffer);
       NXIReportError (NXpData, pError);

branches/4.2/src/napi5.c

@@ -1798 +1798 @@
      vid = getAttVID(pFile);
 
+     pName[0] = '\0';
      idx=pFile->iAtt5.iCurrentIDX;
      iRet=0;

branches/4.2/src/napi_exports.h

@@ -256 +256 @@
     return NXmakenamedlink(fid, newname, pLink);
 }
+
+NXstatus CALL_MODE NXIGETRAWINFO(NXhandle handle, int* rank, int dimension[], int* datatype)
+{
+    return NXgetrawinfo(handle, rank, dimension, datatype);
+}
+

branches/4.2/src/nexus_symbols_win.txt

@@ -22 +22 @@
 NXIGETNEXTATTR@16
 NXIGETNEXTENTRY@16
+NXIGETRAWINFO@16
 NXIGETSLAB@16
 NXIINITATTRDIR@4