The NeXus F77 Application Program Interface Routines


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

List of NeXus Core API F77 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 numeric data from the currently open data set
NXgetchardataReads character data from the currently open data set
NXgetslabReads a subset of the currently open data set
NXgetattrReads a numeric attribute from open data set
NXgetcharattrReads a character attribute from open data set
NXputdataWrites numeric data into the currently open data set
NXputchardataWrites character data into the currently open data set
NXputslabWrites a subset of data into the currently open data set
NXputattrWrites a numeric attribute of the currently open data set
NXputcharattrWrites a character 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
NXHANDLESIZESize of integer array required to hold NeXus file handle1200
NXLINKSIZESize of integer array to hold a NeXus group or data link4
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 F77 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 ValuestatusintegerError status
Input Argumentsfile_namecharacter*(*)Name of NeXus file to be opened
access_methodintegerNXACC_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_idinteger(NXHANDLESIZE)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 ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)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 ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file
group_namecharacter*(*)Name of NeXus group
group_classcharacter*(*)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 ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file
group_namecharacter*(*)Name of NeXus group
group_classcharacter*(*)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 ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)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.

NameTypeDescription
Return ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file
data_namecharacter*(*)Name of NeXus data set
data_typeintegerType of data (see list of valid data types)
rankintegerRank of data
dimensionsinteger(*)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 ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file
data_namecharacter*(*)Name of NeXus data set
data_typeintegerType of data (see list of valid data types)
rankintegerRank of data
dimensionsinteger(*)Dimensions of data. The array is of size 'rank'
compress_typeintegerCompression 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 ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file
data_namecharacter*(*)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.

NameTypeDescription
Return ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file
compress_typeintegerCompression 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 ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file

[Return to API | Top | NeXus Site Map]


NXgetdata (file_id, data)

Reads numeric 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 check that the dimension sizes are adequate. The data set must have been opened by NXopendata.

NameTypeDescription
Return ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file
Output Argumentsdatainteger(*)
real(*)
Data values

[Return to API | Top | NeXus Site Map]


NXgetchardata (file_id, data)

Reads character data values from the currently open data set. Please note that memory overwrite occurs if the caller has not allocated enough memory to hold the character string. Call NXgetinfo to check that the size is adequate. The data set must have been opened by NXopendata.

NameTypeDescription
Return ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file
Output Argumentsdatacharacter*(*)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 slab for each dimension. The caller is responsible for allocating enough memory for the data.

NameTypeDescription
Return ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file
startinteger(*)Indices of starting values in each dimension
sizeinteger(*)Length of slab in each dimension
Output Argumentsdatainteger(*)
real(*)
Data values

[Return to API | Top | NeXus Site Map]


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

Reads numeric attribute 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 ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file
attr_namecharacter*(*)Name of attribute
lengthintegerLength of buffer for storing attribute data
typeintegerType of attribute data (see list of valid data types)
Output Argumentsvalueinteger(*)
real(*)
Value of attribute
lengthintegerActual length of attribute data

[Return to API | Top | NeXus Site Map]


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

Reads character attribute 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 ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file
attr_namecharacter*(*)Name of attribute
lengthintegerLength of buffer for storing attribute data
typeintegerType of attribute data (see list of valid data types)
Output Argumentsvaluecharacter*(*)Value of attribute
lengthintegerActual length of attribute data

[Return to API | Top | NeXus Site Map]


NXputdata (file_id, data)

Writes numeric data into the specified data set.

NameTypeDescription
Return ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file
datainteger(*)
real(*)
Data values

[Return to API | Top | NeXus Site Map]


NXputchardata (file_id, data)

Writes character data into the specified data set.

NameTypeDescription
Return ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file
datacharacter*(*)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 slab for each dimension, into the currently open dataset.

NameTypeDescription
Return ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file
datainteger(*)
real(*)
Data values
startinteger(*)Indices of starting values in each dimension
sizeinteger(*)Length of slab in each dimension

[Return to API | Top | NeXus Site Map]


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

Writes a numeric 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 ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file
attr_namecharacter*(*)Name of attribute
valueinteger(*)
real(*)
Value of attribute
lengthintegerLength of data
typeintegerType of attribute data (see list of valid data types)

[Return to API | Top | NeXus Site Map]


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

Writes a character 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 ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file
attr_namecharacter*(*)Name of attribute
valuecharacter*(*)Value of attribute
lengthintegerLength of data
typeintegerType of attribute data

[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_idinteger(NXHANDLESIZE)Identifier of NeXus file
Output Argumentsfile_idinteger(NXHANDLESIZE)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 ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file
Output ArgumentsrankintegerRank of data
dimensionsinteger(*)Dimensions of data
data_typeintegerType 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_idinteger(NXHANDLESIZE)Identifier of NeXus file
Output Argumentsitem_numberintegerNumber of NeXus data items in the current group
group_namecharacter*(*)Name of currently open NeXus group
group_classcharacter*(*)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_idinteger(NXHANDLESIZE)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."

NameTypeDescription
Return ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file
Output Argumentsnamecharacter*(*)Name of NeXus data item (group or set)
classcharacter*(*)Class of NeXus group
data_typeintegerType 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 currently open data set.

NameTypeDescription
Return ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file
Output Argumentsattr_numberintegerNumber 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_idinteger(NXHANDLESIZE)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.

NameTypeDescription
Return ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file
Output Argumentsattr_namecharacter*(*)Name of next attribute
lengthintegerLength of next attribute
typeintegerType 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 ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file
Output Argumentsgroup_idinteger(NXLINKSIZE)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 ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file
Output Argumentsdata_idinteger(NXLINKSIZE)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 ValuestatusintegerError status
Input Argumentsfile_idinteger(NXHANDLESIZE)Identifier of NeXus file
Output Argumentslinkinteger(NXLINKSIZE)Identifier of linked group

[Return to API | Top | NeXus Site Map]


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

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