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
NXopenOpens NeXus file and returns file id
NXcloseCloses NeXus file
NXmakegroupCreates NeXus group
NXopengroupOpens existing NeXus group for input/output
NXclosegroupCloses NeXus group
NXmakedataCreates NeXus data set
NXcompmakedataCreates compressed NeXus data set
NXopendataOpens existing NeXus data set for input/output
NXcompressMarks the NeXus data set for compression
NXclosedataCloses NeXus data set
Reading and Writing
NXgetdataReads data from currently open data set
NXgetslabReads a subset of the currently open data set
NXgetattrReads sdata attribute from open data set
NXputdataWrites data into the currently open data set
NXputslabWrites a subset of data into the currently open data set
NXputattrWrites an attribute of the currently open data set
NXflushFlushes output to a data file
Meta-Data Routines
NXgetinfoGets rank, dimensions and type of currently open data set
NXgetgroupinfoReturns the number of items, and the name and class of the current group
NXinitgroupdirInitializes a group's directory search
NXgetnextentryImplements a directory search of the currently open group
NXgetattrinfoReturns the number of attributes of the current data set
NXinitattrdirInitializes a data set's attribute search
NXgetnextattrImplements a search of all the attributes of the currently open data set
Linking and Group Hierarchy
NXgetgroupIDReturns the identifier of the currently open group as an NXlink structure
NXgetdataIDReturns the identifier of the currently open data set
NXmakelinkLinks a data item (group or set) to another group

[Return to API | Top | NeXus Site Map]


NeXus API Datatypes

NameDescriptionCurrent Default Value
NX_CHARData type for 8-byte signed integer4
NX_FLOAT32Data type for 8-byte signed integer5
NX_FLOAT64Data type for 8-byte signed integer6
NX_INT8Data type for 1-byte signed integer20
NX_UINT8Data type for 1-byte unsigned integer21
NX_INT16Data type for 2-byte signed integer22
NX_UINT16Data type for 2-byte unsigned integer23
NX_INT32Data type for 4-byte signed integer24
NX_UINT32Data type for 4-byte unsigned integer25

[Return to API | Top | NeXus Site Map]


NeXus API Constants

NameDescriptionCurrent Default Value
NX_OKSuccess return status1
NX_ERRORFailed return status0
NX_EODEnd of record return status-1
NX_COMP_NONEParameter defining no compression100
NX_COMP_LZWParameter defining LZW compression200
NX_COMP_RLEParameter defining run-length encoding compression300
NX_COMP_HUFParameter defining Skipping Huffman compression400

[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.

NameTypeDescription
Return ValuestatusintError status
Input Argumentsfile_namechar *Name of NeXus file to be opened
access_methodintNXACC_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 Argumentsfile_idNXhandle *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.

NameTypeDescription
Return ValuestatusintError status
Input Argumentsfile_idNXhandle *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.

NameTypeDescription
Return ValuestatusintError status
Input Argumentsfile_idNXhandleIdentifier of NeXus file
group_namechar *Name of NeXus group
group_classchar *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.

NameTypeDescription
Return ValuestatusintError status
Input Argumentsfile_idNXhandleIdentifier of NeXus file
group_namechar *Name of NeXus group
group_classchar *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.

NameTypeDescription
Return ValuestatusintError status
Input Argumentsfile_idNXhandleIdentifier 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.

NameTypeDescription
Return ValuestatusintError status
Input Argumentsfile_idNXhandleIdentifier of NeXus file
data_namechar *Name of NeXus data set
data_typeintType of data (see list of valid data types)
rankintRank of data
dimensionsint[]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.

NameTypeDescription
Return ValuestatusintError status
Input Argumentsfile_idNXhandleIdentifier of NeXus file
data_namechar *Name of NeXus data set
data_typeintType of data (see list of valid data types)
rankintRank of data
dimensionsint[]Dimensions of data. The array is of size 'rank'
compress_typeintCompression 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.

NameTypeDescription
Return ValuestatusintError status
Input Argumentsfile_idNXhandleIdentifier of NeXus file
data_namechar *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.

NameTypeDescription
Return ValuestatusintError status
Input Argumentsfile_idNXhandleIdentifier of NeXus file
compress_typeintCompression 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

NameTypeDescription
Return ValuestatusintError status
Input Argumentsfile_idNXhandleIdentifier 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.

NameTypeDescription
Return ValuestatusintError status
Input Argumentsfile_idNXhandleIdentifier of NeXus file
Output Argumentsdatavoid *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.

NameTypeDescription
Return ValuestatusintError status
Input Argumentsfile_idNXhandleIdentifier of NeXus file
start[]intIndices of starting values in each dimension
size[]intLength of slab in each dimension
Output Argumentsdatavoid *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.

NameTypeDescription
Return ValuestatusintError status
Input Argumentsfile_idNXhandleIdentifier of NeXus file
attr_namechar *Name of attribute
lengthint *Length of buffer for storing attribute data
typeint *Type of attribute data (see list of valid data types)
Output Argumentsvaluevoid *Value of attribute
lengthint *Actual length of attribute data

[Return to API | Top | NeXus Site Map]


NXputdata (file_id, data[])

Writes data into the specified data set.

NameTypeDescription
Return ValuestatusintError status
Input Argumentsfile_idNXhandleIdentifier of NeXus file
datavoid *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.

NameTypeDescription
Return ValuestatusintError status
Input Argumentsfile_idNXhandleIdentifier of NeXus file
datavoid *Data values
start[]intIndices of starting values in each dimension
size[]intLength 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.

NameTypeDescription
Return ValuestatusintError status
Input Argumentsfile_idNXhandleIdentifier of NeXus file
attr_namechar *Name of attribute
valuevoid *Value of attribute
lengthintLength of data
typeintType 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.

NameTypeDescription
Return ValuestatusintegerError status
Input Argumentsfile_idNXhandle *Identifier of NeXus file
Output Argumentsfile_idNXhandle *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.

NameTypeDescription
Return ValuestatusintError status
Input Argumentsfile_idNXhandleIdentifier of NeXus file
Output Argumentsrankint *Rank of data
dimensionsint[]Dimensions of data
data_typeint *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.

NameTypeDescription
Return ValuestatusintegerError status
Input Argumentsfile_idNXhandleIdentifier of NeXus file
Output Argumentsitem_numberint *Number of NeXus data items in the current group
group_namechar *Name of currently open NeXus group
group_classchar *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.

NameTypeDescription
Return ValuestatusintegerError status
Input Argumentsfile_idNXhandleIdentifier 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."

NameTypeDescription
Return ValuestatusintError status
Input Argumentsfile_idNXhandleIdentifier of NeXus file
Output Argumentsnamechar *Name of NeXus data item (group or set)
classchar *Class of NeXus group
data_typeint *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.

NameTypeDescription
Return ValuestatusintegerError status
Input Argumentsfile_idNXhandleIdentifier of NeXus file
Output Argumentsattr_numberint *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.

NameTypeDescription
Return ValuestatusintegerError status
Input Argumentsfile_idNXhandleIdentifier 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.

NameTypeDescription
Return ValuestatusintError status
Input Argumentsfile_idNXhandleIdentifier of NeXus file
Output Argumentsattr_namechar *Name of next attribute
lengthint *Length of next attribute
typeint *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.

NameTypeDescription
Return ValuestatusintError status
Input Argumentsfile_idNXhandleIdentifier of NeXus file
Output Argumentsgroup_idNXlink *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.

NameTypeDescription
Return ValuestatusintError status
Input Argumentsfile_idNXhandleIdentifier of NeXus file
Output Argumentsdata_idNXlink *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.

NameTypeDescription
Return ValuestatusintError status
Input Argumentsfile_idNXhandleIdentifier of NeXus file
Output ArgumentslinkNXlink *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.