NeXus F77 Application Program Interface Routines

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
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 numeric data from the currently open data set
NXgetchardata	Reads character data from the currently open data set
NXgetslab	Reads a subset of the currently open data set
NXgetattr	Reads a numeric attribute from open data set
NXgetcharattr	Reads a character attribute from open data set
NXputdata	Writes numeric data into the currently open data set
NXputchardata	Writes character data into the currently open data set
NXputslab	Writes a subset of data into the currently open data set
NXputattr	Writes a numeric attribute of the currently open data set
NXputcharattr	Writes a character 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]

Name	Description	Current Default Value
NX_CHAR	Data type for 8-byte signed integer	4
NX_FLOAT32	Data type for 8-byte signed integer	5
NX_FLOAT64	Data type for 8-byte signed integer	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

Name	Description	Current Default Value
NXHANDLESIZE	Size of integer array required to hold NeXus file handle	1200
NXLINKSIZE	Size of integer array to hold a NeXus group or data link	4
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

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.

	Name	Type	Description
Return Value	status	integer	Error status
Input Arguments	file_name	character()	Name of NeXus file to be opened
	access_method	integer	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	integer(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.

	Name	Type	Description
Return Value	status	integer	Error status
Input Arguments	file_id	integer(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.

	Name	Type	Description
Return Value	status	integer	Error status
Input Arguments	file_id	integer(NXHANDLESIZE)	Identifier of NeXus file
	group_name	character()	Name of NeXus group
	group_class	character()	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	integer	Error status
Input Arguments	file_id	integer(NXHANDLESIZE)	Identifier of NeXus file
	group_name	character()	Name of NeXus group
	group_class	character()	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	integer	Error status
Input Arguments	file_id	integer(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.

	Name	Type	Description
Return Value	status	integer	Error status
Input Arguments	file_id	integer(NXHANDLESIZE)	Identifier of NeXus file
	data_name	character()	Name of NeXus data set
	data_type	integer	Type of data (see list of valid data types)
	rank	integer	Rank of data
	dimensions	integer(*)	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	integer	Error status
Input Arguments	file_id	integer(NXHANDLESIZE)	Identifier of NeXus file
	data_name	character()	Name of NeXus data set
	data_type	integer	Type of data (see list of valid data types)
	rank	integer	Rank of data
	dimensions	integer(*)	Dimensions of data. The array is of size 'rank'
	compress_type	integer	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	integer	Error status
Input Arguments	file_id	integer(NXHANDLESIZE)	Identifier of NeXus file
	data_name	character()	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.

	Name	Type	Description
Return Value	status	integer	Error status
Input Arguments	file_id	integer(NXHANDLESIZE)	Identifier of NeXus file
	compress_type	integer	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	integer	Error status
Input Arguments	file_id	integer(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.

	Name	Type	Description
Return Value	status	integer	Error status
Input Arguments	file_id	integer(NXHANDLESIZE)	Identifier of NeXus file
Output Arguments	data	integer() 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.

	Name	Type	Description
Return Value	status	integer	Error status
Input Arguments	file_id	integer(NXHANDLESIZE)	Identifier of NeXus file
Output Arguments	data	character()	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.

	Name	Type	Description
Return Value	status	integer	Error status
Input Arguments	file_id	integer(NXHANDLESIZE)	Identifier of NeXus file
	start	integer(*)	Indices of starting values in each dimension
	size	integer(*)	Length of slab in each dimension
Output Arguments	data	integer() 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.

	Name	Type	Description
Return Value	status	integer	Error status
Input Arguments	file_id	integer(NXHANDLESIZE)	Identifier of NeXus file
	attr_name	character()	Name of attribute
	length	integer	Length of buffer for storing attribute data
	type	integer	Type of attribute data (see list of valid data types)
Output Arguments	value	integer() real()	Value of attribute
	length	integer	Actual 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.

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

[Return to API | Top | NeXus Site Map]

NXputdata (file_id, data)

Writes numeric data into the specified data set.

	Name	Type	Description
Return Value	status	integer	Error status
Input Arguments	file_id	integer(NXHANDLESIZE)	Identifier of NeXus file
	data	integer() real()	Data values

[Return to API | Top | NeXus Site Map]

NXputchardata (file_id, data)

Writes character data into the specified data set.

	Name	Type	Description
Return Value	status	integer	Error status
Input Arguments	file_id	integer(NXHANDLESIZE)	Identifier of NeXus file
	data	character()	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.

	Name	Type	Description
Return Value	status	integer	Error status
Input Arguments	file_id	integer(NXHANDLESIZE)	Identifier of NeXus file
	data	integer() real()	Data values
	start	integer(*)	Indices of starting values in each dimension
	size	integer(*)	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.

	Name	Type	Description
Return Value	status	integer	Error status
Input Arguments	file_id	integer(NXHANDLESIZE)	Identifier of NeXus file
	attr_name	character()	Name of attribute
	value	integer() real()	Value of attribute
	length	integer	Length of data
	type	integer	Type 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.

	Name	Type	Description
Return Value	status	integer	Error status
Input Arguments	file_id	integer(NXHANDLESIZE)	Identifier of NeXus file
	attr_name	character()	Name of attribute
	value	character()	Value of attribute
	length	integer	Length of data
	type	integer	Type 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.

	Name	Type	Description
Return Value	status	integer	Error status
Input Arguments	file_id	integer(NXHANDLESIZE)	Identifier of NeXus file
Output Arguments	file_id	integer(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.

	Name	Type	Description
Return Value	status	integer	Error status
Input Arguments	file_id	integer(NXHANDLESIZE)	Identifier of NeXus file
Output Arguments	rank	integer	Rank of data
	dimensions	integer(*)	Dimensions of data
	data_type	integer	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	integer(NXHANDLESIZE)	Identifier of NeXus file
Output Arguments	item_number	integer	Number of NeXus data items in the current group
	group_name	character()	Name of currently open NeXus group
	group_class	character()	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	integer(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."

	Name	Type	Description
Return Value	status	integer	Error status
Input Arguments	file_id	integer(NXHANDLESIZE)	Identifier of NeXus file
Output Arguments	name	character()	Name of NeXus data item (group or set)
	class	character()	Class of NeXus group
	data_type	integer	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 currently open data set.

	Name	Type	Description
Return Value	status	integer	Error status
Input Arguments	file_id	integer(NXHANDLESIZE)	Identifier of NeXus file
Output Arguments	attr_number	integer	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	integer(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.

	Name	Type	Description
Return Value	status	integer	Error status
Input Arguments	file_id	integer(NXHANDLESIZE)	Identifier of NeXus file
Output Arguments	attr_name	character()	Name of next attribute
	length	integer	Length of next attribute
	type	integer	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	integer	Error status
Input Arguments	file_id	integer(NXHANDLESIZE)	Identifier of NeXus file
Output Arguments	group_id	integer(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.

	Name	Type	Description
Return Value	status	integer	Error status
Input Arguments	file_id	integer(NXHANDLESIZE)	Identifier of NeXus file
Output Arguments	data_id	integer(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.

	Name	Type	Description
Return Value	status	integer	Error status
Input Arguments	file_id	integer(NXHANDLESIZE)	Identifier of NeXus file
Output Arguments	link	integer(NXLINKSIZE)	Identifier of linked group

[Return to API | Top | NeXus Site Map]

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

The NeXus F77 Application Program Interface Routines

List of NeXus Core API F77 Routines

NeXus API Datatypes

NeXus API Constants

NeXus F77 Core API Routines