Table Of Contents
Previous topic
Next topic
4.3.1. NAPI C and C++ Interface
4.3.1. NAPI C and C++ Interface
This application program interface (API) was developed to support the reading and writing of NeXus files through unified function calls, regardless of the physical data format (XML, HDF4, HDF5).
In the meantime it has been decided that active development of NeXus definitions and tools will concentrate on HDF5 as the only supported physical data format. It is expected that most application developers will use standard HDF5 tools to read and write NeXus. Two examples are provided in Example NeXus C programs using native HDF5 commands.
Therefore, the decision has been taken to freeze the NAPI. Maintenance is reduced to bug fixes.
The core routines have been written in C but wrappers are available for a number of other languages including C++, Fortran 77, Fortran 90, Java, Python and IDL. The API makes the reading and writing of NeXus files transparent; the user doesn’t even need to know the underlying format when reading a file since the API calls are the same.
More in-depth and up-to-date information about the NeXus Application Programming Interface for the various language backends is available on-line from http://download.nexusformat.org.
The NeXusIntern.pdf document (http://svn.nexusformat.org/code/trunk/doc/api/NeXusIntern.pdf) describes the internal workings of the NeXus-API. You are very welcome to read it, but it will not be of much use if all you want is to read and write files using the NAPI.
The NeXus Application Program Interface call routines in the appropriate backend (HDF4, HDF5 or XML) to read and write files with the correct structure. The API serves a number of purposes:
The core API provides the basic routines for reading, writing and navigating NeXus files. Operations are performed using a handle that keeps a record of its current position in the file hierarchy. All are read or write requests are then implicitly performed on the currently open entity. This limits number of parameters that need to be passed to API calls, at the cost of forcing a certain mode of operation. It is very similar to navigating a directory hierarchy; NeXus groups are the directories, which can contain data sets and/or other directories.
The core API comprises the following functional groups:
The NeXus F90 Utility API provides a number of routines that combine the operations of various core API routines in order to simplify the reading and writing of NeXus files. At present, they are only available as a Fortran 90 module but a C version is in preparation.
The utility API comprises the following functional groups:
line required for use with F90 API
Any program using the F90 Utility API needs to put the following line near the top of the program:
use NXUmodule
Note
Do not put USE statements for both NXmodule and NXUmodule. The former is included in the latter
| name | description |
|---|---|
| Reading and Writing | |
| NXUwriteglobals | Writes all the valid global attributes of a file. |
| NXUwritegroup | Opens a group (creating it if necessary). |
| NXUwritedata | Opens a data item (creating it if necessary) and writes data and its units. |
| NXUreaddata | Opens and reads a data item and its units. |
| NXUwritehistogram | Opens one dimensional data item (creating it if necessary) and writes histogram centers and their units. |
| NXUreadhistogram | Opens and reads a one dimensional data item and converts it to histogram bin boundaries. |
| NXUsetcompress | Defines the compression algorithm and minimum dataset size for subsequent write operations. |
| Finding Groups, Data, and Attributes | |
| NXUfindclass | Returns the name of a group of the specified class if it is contained within the currently open group. |
| NXUfinddata | Checks whether a data item of the specified name is contained within the currently open group. |
| NXUfindattr | Checks whether the currently open data item has the specified attribute. |
| NXUfindsignal | Searches the currently open group for a data item with the specified SIGNAL attribute. |
| NXUfindaxis | Searches the currently open group for a data item with the specified AXIS attribute. |
| Finding Linked Groups | |
| NXUfindlink | Finds another link to the specified NeXus data item and opens the group it is in. |
| NXUresumelink | Reopens the original group from which NXUfindlink was used. |
Currently, the F90 utility API will only write character strings, 4-byte integers and reals, and 8-byte reals. It can read other integer sizes into four-byte integers, but does not differentiate between signed and unsigned integers.
The install kit provides a utility call nxbuild that can be used to build simple programs:
nxbuild -o test test.c
This script links in the various libraries for you and reading its contents would provide the necessary information for creating a separate Makefile. You can also use nxbuild with the example files in the NeXus distribution kit which are installed into /usr/local/nexus/examples
Note that the executable name is important in this case as the test program uses it internally to determine the NXACC_CREATE* argument to pass to NXopen.
building and running a simple NeXus program
# builds HDF5 specific test
nxbuild -o napi_test-hdf5 napi_test.c
# runs the test
./napi_test-hdf5
NeXus is also set up for pkg-config so the build can be done as:
gcc `pkg-config --cflags` `pkg-config --libs` -o test test.c
If you encounter any bugs in the installation or running of the NeXus API, please report them online using our Issue Reporting system. (http://www.nexusformat.org/IssueReporting)