The NeXus Application Program Interface Routines

[Core API | API Data Types | API Constants | Return to API | NeXus Site Map]

List of NeXus Core API Routines

General Initialization and Shutdown
NXopen Opens NeXus file and returns file id
NXclose Closes NeXus file
NXmakegroup Creates NeXus group
NXopengroup Opens existing NeXus group for input/output
NXclosegroup Closes NeXus group
NXmakedata Creates NeXus data set
NXcompmakedata Creates compressed NeXus data set
NXopendata Opens existing NeXus data set for input/output
NXcompress Marks the NeXus data set for compression
NXclosedata Closes NeXus data set
Reading and Writing
NXgetdata Reads data from currently open data set
NXgetslab Reads a subset of the currently open data set
NXgetattr Reads sdata attribute from open data set
NXputdata Writes data into the currently open data set
NXputslab Writes a subset of data into the currently open data set
NXputattr Writes an attribute of the currently open data set
NXflush Flushes output to a data file
Meta-Data Routines
NXgetinfo Gets rank, dimensions and type of currently open data set
NXgetgroupinfo Returns the number of items, and the name and class of the current group
NXinitgroupdir Initializes a group's directory search
NXgetnextentry Implements a directory search of the currently open group
NXgetattrinfo Returns the number of attributes of the current data set
NXinitattrdir Initializes a data set's attribute search
NXgetnextattr Implements a search of all the attributes of the currently open data set
Linking and Group Hierarchy
NXgetgroupID Returns the identifier of the currently open group as an NXlink structure
NXgetdataID Returns the identifier of the currently open data set
NXmakelink Links a data item (group or set) to another group

[Return to API | Top | NeXus Site Map]

NeXus API Datatypes

Name Description Current Default Value
NX_CHAR Data type for character string 4
NX_FLOAT32 Data type for 4-byte floating point 5
NX_FLOAT64 Data type for 8-byte floating point 6
NX_INT8 Data type for 1-byte signed integer 20
NX_UINT8 Data type for 1-byte unsigned integer 21
NX_INT16 Data type for 2-byte signed integer 22
NX_UINT16 Data type for 2-byte unsigned integer 23
NX_INT32 Data type for 4-byte signed integer 24
NX_UINT32 Data type for 4-byte unsigned integer 25

[Return to API | Top | NeXus Site Map]

NeXus API Constants

Name Description Current Default Value
NX_OK Success return status 1
NX_ERROR Failed return status 0
NX_EOD End of record return status -1
NX_COMP_NONE Parameter defining no compression 100
NX_COMP_LZW Parameter defining LZW compression 200
NX_COMP_RLE Parameter defining run-length encoding compression 300
NX_COMP_HUF Parameter defining Skipping Huffman compression 400

[Return to API | Top | NeXus Site Map]

NeXus Core API Routines

NXopen (file_name, access_method, file_id)

Opens the NeXus file, and creates and initializes the NeXus file structure. The returned handle is a pointer to this structure.

Name Type Description
Return Value status int Error status
Input Arguments file_name char * Name of NeXus file to be opened
access_method int NXACC_READ - read only access
NXACC_RDWR - read and write access
NXACC_CREATE - create (HDF4) access
NXACC_CREATE4 - create HDF4 access
NXACC_CREATE5 - create HDF5 access
Output Arguments file_id NXhandle * Identifier of NeXus file

[Return to API | Top | NeXus Site Map]

NXclose (file_id)

Closes NeXus file and deletes all associated data structures from memory.

Name Type Description
Return Value status int Error status
Input Arguments file_id NXhandle * Identifier of NeXus file

[Return to API | Top | NeXus Site Map]

NXmakegroup (file_id, group_name, group_class)

Creates a NeXus group at the current level in the group hierarchy, defining its name and class. This does not open the new group automatically.

Name Type Description
Return Value status int Error status
Input Arguments file_id NXhandle Identifier of NeXus file
group_name char * Name of NeXus group
group_class char * Class of NeXus group

[Return to API | Top | NeXus Site Map]

NXopengroup (file_id, group_name, group_class)

Opens an existing NeXus group for input and output of data.

Name Type Description
Return Value status int Error status
Input Arguments file_id NXhandle Identifier of NeXus file
group_name char * Name of NeXus group
group_class char * Class of NeXus group

[Return to API | Top | NeXus Site Map]

NXclosegroup (file_id)

Closes the currently open group. If this group is a top-level group (i.e. with class NXentry), no groups are left open. Otherwise, the next group up in the hierarchy (i.e. the group containing the currently open group) is left open.

Name Type Description
Return Value status int Error status
Input Arguments file_id NXhandle Identifier of NeXus file

[Return to API | Top | NeXus Site Map]

NXmakedata (file_id, data_name, data_type, rank, dimensions[])

Creates a new NeXus data set with the specified name, type, rank and dimensions.

Name Type Description
Return Value status int Error status
Input Arguments file_id NXhandle Identifier of NeXus file
data_name char * Name of NeXus data set
data_type int Type of data (see list of valid data types)
rank int Rank of data
dimensions int[] Dimensions of data. The array is of size 'rank'

[Return to API | Top | NeXus Site Map]

NXcompmakedata (file_id, data_name, data_type, rank, dimensions[], compress_type)

Creates a new NeXus data set with the specified name, type, rank and dimensions, compressed using the specified protocol.

Name Type Description
Return Value status int Error status
Input Arguments file_id NXhandle Identifier of NeXus file
data_name char * Name of NeXus data set
data_type int Type of data (see list of valid data types)
rank int Rank of data
dimensions int[] Dimensions of data. The array is of size 'rank'
compress_type int Compression algorithm to be used :
NX_COMP_LZW - GZIP
NX_COMP_HUF - Skipping Huffman
NX_COMP_RLE - Run Length Encoding

[Return to API | Top | NeXus Site Map]

NXopendata (file_id, data_name)

Opens an existing NeXus data set for further processing i.e. reading and writing data or attributes, defining compression algorithms, and obtaining data set information.

Name Type Description
Return Value status int Error status
Input Arguments file_id NXhandle Identifier of NeXus file
data_name char * Name of NeXus data set

[Return to API | Top | NeXus Site Map]

NXcompress (file_id, compress_type)

Defines a compression algorithm for subsequent calls to NXputdata. This routine is now deprecated; please use NXcompmakedata instead.

Name Type Description
Return Value status int Error status
Input Arguments file_id NXhandle Identifier of NeXus file
compress_type int Compression algorithm to be used :
NX_COMP_LZW - GZIP
NX_COMP_HUF - Skipping Huffman
NX_COMP_RLE - Run Length Encoding

[Return to API | Top | NeXus Site Map]

NXclosedata (file_id)

Ends access to the currently active data set

Name Type Description
Return Value status int Error status
Input Arguments file_id NXhandle Identifier of NeXus file

[Return to API | Top | NeXus Site Map]

NXgetdata (file_id, data)

Reads data values from the currently open data set. Please note that memory overwrite occurs if the caller has not allocated enough memory to hold all the data available. Call NXgetinfo to determine the required dimension sizes. The data set must have been opened by NXopendata.

Name Type Description
Return Value status int Error status
Input Arguments file_id NXhandle Identifier of NeXus file
Output Arguments data void * Data values

[Return to API | Top | NeXus Site Map]

NXgetslab (file_id, data, start[], size[])

Reads a subset of the data in the current data set specifying the starting indices and size of each dimension. The caller is responsible for allocating enough memory for the data.

Name Type Description
Return Value status int Error status
Input Arguments file_id NXhandle Identifier of NeXus file
start[] int Indices of starting values in each dimension
size[] int Length of slab in each dimension
Output Arguments data void * Data values

[Return to API | Top | NeXus Site Map]

NXgetattr (file_id, attr_name, value, length, type)

Reads attribute values associated with the currently open data set. The attribute is defined by its name. Attributes are meta-data; data that provides information on the associated data set such as units, long names etc. If no data set is open, it looks for a global attribute i.e. attributes of the NeXus file. The caller is responsible for allocating enough memory for the attribute values. Note, however, that only the first 'length' bytes of the attribute are read to prevent memory overwrite.

Name Type Description
Return Value status int Error status
Input Arguments file_id NXhandle Identifier of NeXus file
attr_name char * Name of attribute
length int * Length of buffer for storing attribute data
type int * Type of attribute data (see list of valid data types)
Output Arguments value void * Value of attribute
length int * Actual length of attribute data

[Return to API | Top | NeXus Site Map]

NXputdata (file_id, data[])

Writes data into the specified data set.

Name Type Description
Return Value status int Error status
Input Arguments file_id NXhandle Identifier of NeXus file
data void * Data values

[Return to API | Top | NeXus Site Map]

NXputslab (file_id, data, start[], size[])

Writes a subset of a multidimensional data array, specified by the starting indices and size of each dimension, into the currently open dataset.

Name Type Description
Return Value status int Error status
Input Arguments file_id NXhandle Identifier of NeXus file
data void * Data values
start[] int Indices of starting values in each dimension
size[] int Length of slab in each dimension

[Return to API | Top | NeXus Site Map]

NXputattr (file_id, attr_name, value, length, type)

Writes an attribute of the currently open data set. If no data set is open, a global attribute is generated. The attribute has both a name and a value.

Name Type Description
Return Value status int Error status
Input Arguments file_id NXhandle Identifier of NeXus file
attr_name char * Name of attribute
value void * Value of attribute
length int Length of data
type int Type of attribute data (see list of valid data types)

[Return to API | Top | NeXus Site Map]

NXflush (file_id)

Flushes all data to the NeXus file. Since this command closes and reopens the file, a new file handle is returned. The command leaves the program in the same state, i.e. with the same group and/or data set open.

Name Type Description
Return Value status integer Error status
Input Arguments file_id NXhandle * Identifier of NeXus file
Output Arguments file_id NXhandle * Identifier of NeXus file

[Return to API | Top | NeXus Site Map]

NXgetinfo (file_id, rank, dimensions[], data_type)

Gets the rank, dimensions and data type of the currently open data set.

Name Type Description
Return Value status int Error status
Input Arguments file_id NXhandle Identifier of NeXus file
Output Arguments rank int * Rank of data
dimensions int[] Dimensions of data
data_type int * Type of data (see list of valid data types)

[Return to API | Top | NeXus Site Map]

NXgetgroupinfo (file_id, item_number, group_name, group_class)

Returns the number of items in the current group, and the name and class of the current group.

Name Type Description
Return Value status integer Error status
Input Arguments file_id NXhandle Identifier of NeXus file
Output Arguments item_number int * Number of NeXus data items in the current group
group_name char * Name of currently open NeXus group
group_class char * Class of currently open NeXus group

[Return to API | Top | NeXus Site Map]

NXinitgroupdir (file_id)

Initializes directory searches of the currently open group. This is required to reset searches using NXgetnextentry that may have been interrupted before completion.

Name Type Description
Return Value status integer Error status
Input Arguments file_id NXhandle Identifier of NeXus file

[Return to API | Top | NeXus Site Map]

NXgetnextentry (file_id, name, class, data_type)

Implements a directory search facility on the current group level. The first call initializes the search and returns information on the first data item in the list. Subsequent calls yield information about the remaining items. If the item is a group, its name and class is returned. If it is a data set, its name and type is returned with a class of "SDS."

Name Type Description
Return Value status int Error status
Input Arguments file_id NXhandle Identifier of NeXus file
Output Arguments name char * Name of NeXus data item (group or set)
class char * Class of NeXus group
data_type int * Type of data set (see list of valid data types)

[Return to API | Top | NeXus Site Map]

NXgetattrinfo (file_id, attr_number)

Returns the number of attributes in the current data set.

Name Type Description
Return Value status integer Error status
Input Arguments file_id NXhandle Identifier of NeXus file
Output Arguments attr_number int * Number of attributes in the current data set

[Return to API | Top | NeXus Site Map]

NXinitattrdir (file_id)

Initializes attribute searches of the currently open data set. This is required to reset searches using NXgetnextattr that may have been interrupted before completion.

Name Type Description
Return Value status integer Error status
Input Arguments file_id NXhandle Identifier of NeXus file

[Return to API | Top | NeXus Site Map]

NXgetnextattr (file_id, attr_name, length, type)

Implements a search facility of the attributes of the currently open data set. The first call initializes the search and returns information on the first attribute in the list. Subsequent calls yield information about the remaining attributes. This routine returns global attributes if no data set is open.

Name Type Description
Return Value status int Error status
Input Arguments file_id NXhandle Identifier of NeXus file
Output Arguments attr_name char * Name of next attribute
length int * Length of next attribute
type int * Type of next attribute (see list of valid data types)

[Return to API | Top | NeXus Site Map]

NXgetgroupID (file_id, group_id)

Returns the identifier of the currently open group as an NXlink structure.

Name Type Description
Return Value status int Error status
Input Arguments file_id NXhandle Identifier of NeXus file
Output Arguments group_id NXlink * Identifier of NeXus group

[Return to API | Top | NeXus Site Map]

NXgetdataID (file_id, data_id)

Gets the identifier of the currently open data set as an NXlink structure. Returns NX_ERROR if there is no open data set.

Name Type Description
Return Value status int Error status
Input Arguments file_id NXhandle Identifier of NeXus file
Output Arguments data_id NXlink * Identifier of NeXus data set

[Return to API | Top | NeXus Site Map]

NXmakelink (file_id, link)

Links a data item (group or set) to a NeXus group. Returns NX_ERROR if the current group level is the root level, since no data item can be linked here.

Name Type Description
Return Value status int Error status
Input Arguments file_id NXhandle Identifier of NeXus file
Output Arguments link NXlink * Identifier of linked group

[Return to API | Top | NeXus Site Map]

Comments to: Ray Osborn <ROsborn@anl.gov>
Revised: Saturday, September 14, 2002

Copyright © 1996-2002 NeXus Design Team. All rights reserved.