The NeXus F90 Application Program Interface Routines

List of NeXus Core API F90 Routines

List of NeXus Utility API Routines

NeXus API Datatypes

NeXus API Constants

NeXus F90 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.

NXclose (file_id)

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

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.

NXopengroup (file_id, group_name, group_class)

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

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.

NXmakedata (file_id, data_name, data_type, rank, dimensions, compress_type, chunk_size)

Creates a new NeXus data set with the specified name, type, rank and dimensions. The data compression parameter and chunk size are optional.

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.

NXcompress (file_id, compress_type)

Defines a compression algorithm for subsequent calls to NXputdata.

NXclosedata (file_id)

Ends access to the currently active data set

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. NXgetdata assumes that "data" is a one-dimensional array (unless it's a character string). If the requested data has more than one dimension, read it into a one-dimensional buffer and then copy it to an array of the correct dimension using the Fortran 90 RESHAPE intrinsic function.e.g.

   status = NXgetinfo (file_id, rank, dims, datatype)
   allocate (buffer(PRODUCT(dims(1:rank))))
   status = NXgetdata (file_id, buffer)
   data = RESHAPE(buffer,dims(1:rank))

NXgetslab (file_id, data, start, size)

Reads a subset of the data in the current data set specifying the starting indices and size of slab for each dimension. The caller is responsible for allocating enough memory for the data. NXgetslab assumes that "data" is a one-dimensional array (unless it's a character string). If the requested data has more than one dimension, read it into a one-dimensional buffer and then copy it to an array of the correct dimension using the Fortran 90 RESHAPE intrinsic function (see NXgetdata)

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 length and type arguments are optional.

NXputdata (file_id, data)

Writes data into the specified data set. NXputdata assumes that "data" is a one-dimensional array (unless it's a character string). If the data has more than one dimension, copy it first into a one-dimensional buffer using the Fortran 90 RESHAPE intrinsic function e.g.

   status = NXputdata (file_id, RESHAPE(data,(/size(data)/))

NXputslab (file_id, data, start, size)

Writes a subset of a multidimensional data array, specified by the starting indices and size of slab for each dimension, into the currently open dataset. If the data has more than one dimension, copy it first into a one-dimensional buffer using the Fortran 90 RESHAPE intrinsic function (see NXputdata).

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. The length and type arguments are optional.

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.

NXgetinfo (file_id, rank, dimensions, data_type)

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

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. "group_name" and "group_class" are optional arguments.

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.

NXgroupdir (file_id, item_number, item_name, item_class)

Returns a directory of items in the current group as an array of character strings. Note that if the item is a data set, its class is "SDS". The user must ensure that the arrays are large enough to contain the results (call NXgetgroupinfo first).

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

NXgetattrinfo (file_id, attr_number)

Returns the number of attributes in the current data set.

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.

NXattrdir (file_id, attr_number, attr_name)

Returns a directory of attributes in the current data set as an array of character strings. The user must ensure that the array is large enough to contain the results (call NXgetattrinfo first).

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.

NXgetgroupID (file_id, group_id)

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

NXgetdataID (file_id, data_id)

Gets the identifier of the currently open data set as an NXlink structure (which contains the HDF tag/reference pair). Returns NX_ERROR if there is no open data set.

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.

NeXus F90 Utility API Routines

NXUwriteglobals (file_id, user, affiliation, address, phone, fax, email)

Writes the global attributes defined in the NeXus standard. Note that NeXus_version, file_name and file_time are written automatically by the NeXus API. The attribute arguments are optional, so the F90 keyword syntax can be used for all of them, e.g.

   status = NXUwriteglobals (file_id, user="Joe Bloggs", email="JB@some.where")

NXUwritegroup (file_id, group_name, group_class)

Creates a NeXus group leaving it open for subsequent data output.

NXUwritedata (file_id, data_name, data, units, data_start, data_size)

Creates, opens and writes a NeXus data set in the current group. "data" can be a scalar value, or a one-, two-, or three-dimensional array. If higher dimensions are required, use the core API (see NXputdata). "units", "data_start" and "data_size" are optional parameters. If you want the data set to be compressed, set default compression parameters in NXUsetcompress.

NXUreaddata (file_id, data_name, data, units, data_start, data_size)

Opens and reads a NeXus data set in the current group. "data" can be a scalar value, or a one-, two-, or three-dimensional array. If higher dimensions are required, use the core API (see NXgetdata). "units", "data_start" and "data_size" are optional parameters.

NXUwritehistogram (file_id, data_name, data, units)

Creates, opens and writes a one dimensional NeXus data item with units. The input "data" are assumed to be histogram bin boundaries, and the stored data contains the histogram centers, i.e. the stored array has a dimension one less than the "data". The "histogram_offset" attribute is automatically set to half the width of the first bin, which allows the regeneration of the bin boundaries by NXUreadhistogram.

NXUreadhistogram (file_id, data_name, data, units)

Opens and reads a one dimensional real data set in the current group. The data are assumed to be histogram bin boundaries, which are stored in NeXus files as bin centers with the first bin offset defined as the attribute "histogram_offset", i.e. the returned array has a dimension one greater than the stored array (see NXUwritehistogram). If the "histogram_offset" attribute is not present, it is assumed that the first bin width equals the separation of the first two bin centers.

NXUsetcompress (file_id, compress_type, compress_size)

Sets the compression type to be used in subsequent calls to NXUwritedata. The second parameter, which is optional, sets the minimum number of elements in a data set before any compression is performed. This is to prevent inefficient compression of small data sets. The default value is 100.

NXUfindgroup (file_id, group_name, group_class)

Finds if NeXus group exists in the current group and returns its class.

NXUfindclass (file_id, group_class, group_name, find_index)

Finds if a NeXus group of the requested class exists in the current group and returns its name. "find_index" is used when there is more than one group of the required class; find_index = 3 returns the name of the third group found.

NXUfinddata (file_id, data_name)

Finds if a NeXus data set of the requested name exists in the current group.

NXUfindattr (file_id, attr_name)

Finds if a NeXus attribute of the current data set exists.

NXUfindsignal (file_id, signal, data_name, data_rank, data_type, data_dimensions)

Finds the NeXus data set in the current group with the required signal attribute, and returns its name, rank, type and dimensions.

NXUfindaxis (file_id, axis, primary, data_name, data_rank, data_type, data_dimensions)

Finds the NeXus data set in the current group with the required axis and primary attributes, and returns its name, rank, type and dimensions. Note that the axis data set should be one-dimensional.

NXUfindlink (file_id, group_id, group_class)

Finds another group to which the currently open data set is linked and leaves it open for getting associated data. "group_id" stores the ID of the original group to enable a subsequent return (see NXUresumelink). "group_class" is an optional argument which restricts the search to the specified group class.

NXUresumelink (file_id, group_id)

Returns to the original group from which an NXfindlink call was issued.

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

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