NAPI Routines¶

OUT OF DATE¶

This page is now out of date and has been replaced by Doxygen generated documentation

General Initialization and Shutdown¶

NXopen¶

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

;Usage:

status = NXopen (file_name, access_method, file_id)

File Access:NXACC_READ - read only
NXACC_RDWR - read and write access

NXACC_CREATE - create (HDF4) file

NXACC_CREATE4 - create HDF4 file

NXACC_CREATE5 - create HDF5 file

NXACC_CREATEXML - create XML file

|- ! | Output Arguments | file_id | NXhandle * | Identifier of NeXus file |}

NXclose¶

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

;Usage:

status = NXclose (file_id)

|- ! | Input Arguments | file_id | NXhandle * | Identifier of NeXus file |}

NXmakegroup¶

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.

;Usage:

status = NXmakegroup (file_id, group_name, group_class)

|- ! rowspan=“3” | Input Arguments | file_id | NXhandle | Identifier of NeXus file |- | group_name | char * | Name of NeXus group |- | group_class | char * | Class of NeXus group |}

NXopengroup¶

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

;Usage:

status = NXopengroup (file_id, group_name, group_class)

|- ! rowspan=“3” | Input Arguments | file_id | NXhandle | Identifier of NeXus file |- | group_name | char * | Name of NeXus group |- | group_class | char * | Class of NeXus group |}

NXopenpath¶

Opens a NeXus group or dataset from a path string. The NeXus item must exist for NXopenpath to work correctly. The path string for NXopenpath has the same form as a unix path string: /group1/group/group2/dataset. Both absolute and relative path are supported.

;Usage:

status = NXopenpath(file_id, path_string)

|- | rowspan=“3” | Input Arguments | file_id | NXhandle |Identifier of NeXus file |- | path_string | char* | path to dataset or group in NeXus file |}

NXopengrouppath¶

Opens a NeXus group from a path string. This function is subtly different from NXopenpath in that it only opens the path to the last group; it does not open datasets. The NeXus item must exist for NXopengrouppath to work correctly. The path string for NXopengrouppath has the same form as a unix path string: /group1/group/group2/dataset. Both absolute and relative path are supported.

;Usage:

status = NXopengrouppath(file_id, path_string)

|- | rowspan=“3” | Input Arguments | file_id | NXhandle |Identifier of NeXus file |- | path_string | char* | path to dataset or group in NeXus file |}

NXclosegroup¶

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.

;Usage:

status = NXclosegroup (file_id)

|- ! | Input Arguments | file_id | NXhandle | Identifier of NeXus file |}

NXmakedata¶

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

;Usage:

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

Data Type:NX_CHAR - Character string
NX_FLOAT32 - 4-byte real

NX_FLOAT64 - 8-byte real

NX_INT8 - 1-byte integer

NX_UINT8 - unsigned 1-byte integer

NX_INT16 - 2-byte integer

NX_UINT16 - unsigned 2-byte integer

NX_INT32 - 4-byte integer

NX_UINT32 - unsigned 4-byte integer

|- | rank | int | Rank of data |- | dimensions | int[] | Dimensions of data. The array is of size ‘rank’ |}

NXcompmakedata¶

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

;Usage:

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

Data Type:NX_CHAR - Character string
NX_FLOAT32 - 4-byte real

NX_FLOAT64 - 8-byte real

NX_INT8 - 1-byte integer

NX_UINT8 - unsigned 1-byte integer

NX_INT16 - 2-byte integer

NX_UINT16 - unsigned 2-byte integer

NX_INT32 - 4-byte integer

NX_UINT32 - unsigned 4-byte integer

|- | rank | int | Rank of data |- | dimensions | int[] | Dimensions of data. The array is of size ‘rank’ |- | compress_type | int |

Compression algorithm:NX_COMP_LZW - GZIP
NX_COMP_HUF - Skipping Huffman

NX_COMP_RLE - Run Length Encoding

|- | bufsize | int[] | The typical buffersize for writing. |} The buffersize requires further explanation. HDF-5 compresses data in chunks. And the buffersize is this chunksize. If data is written in one go with a NXputdata, this is the dimensions of the data. If data is written in slabs, this is the preferred size of the slabs. Please note, that this has only a performance impact when writing, it is no show stopper. Please note that HDF-4 does not support compression on data sets written in slabs: If you want compression with HDF-4, data must be written with one call to NXputdata. Compression is ignored for XML-NeXus files.

NXopendata¶

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.

;Usage:

status = NXopendata (file_id, data_name)

|- ! rowspan=“2” | Input Arguments | file_id | NXhandle | Identifier of NeXus file |- | data_name | char * | Name of NeXus data set |}

NXcompress¶

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

;Usage:

status = NXcompress (file_id, compress_type)

Compression algorithm:NX_COMP_LZW - GZIP
NX_COMP_HUF - Skipping Huffman

NX_COMP_RLE - Run Length Encoding

|}

NXclosedata¶

Ends access to the currently active data set

;Usage:

status = NXclosedata (file_id)

|- ! | Input Arguments | file_id | NXhandle | Identifier of NeXus file |- |}

NXsetnumberformat¶

Sets the number format when writing to ASCII files. When serializing NeXus file to ASCII-XML files a format for printing numbers is required. The NeXus-API has reasonable defaults for this. However, with this function a desired format can be choosen for special cases. Please note that calls to this function will be silently ignored for the binary NeXus formats HDF-4 and HDF-5.

;Usage:

status = NXsetnumberformat(file_id,data_type,format_string

Data Type:NX_CHAR - Character string
NX_FLOAT32 - 4-byte real

NX_FLOAT64 - 8-byte real

NX_INT8 - 1-byte integer

NX_UINT8 - unsigned 1-byte integer

NX_INT16 - 2-byte integer

NX_UINT16 - unsigned 2-byte integer

NX_INT32 - 4-byte integer

NX_UINT32 - unsigned 4-byte integer

|- | format_string | char* | A ANSI-C language style format string |- |}

Reading and Writing¶

NXgetdata¶

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.

;Usage:

status = NXgetdata (file_id, data)

|- ! | Input Arguments | file_id | NXhandle | Identifier of NeXus file |- ! | Output Arguments | data | void * | Data values |}

NXgetslab¶

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.

;Usage:

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

|- ! rowspan=“3” | 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 |}

NXgetattr¶

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.

;Usage:

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

Attribute Data Type:NX_CHAR - Character string
NX_FLOAT32 - 4-byte real

NX_FLOAT64 - 8-byte real

NX_INT8 - 1-byte integer

NX_UINT8 - unsigned 1-byte integer

NX_INT16 - 2-byte integer

NX_UINT16 - unsigned 2-byte integer

NX_INT32 - 4-byte integer

NX_UINT32 - unsigned 4-byte integer

|- ! rowspan=“2” | Output Arguments | value | void * | Value of attribute |- | length | int * | Actual length of attribute data |}

NXputdata¶

Writes data into the specified data set.

;Usage:

status = NXputdata (file_id, data[])

|- ! rowspan=“2” | Input Arguments | file_id | NXhandle | Identifier of NeXus file |- | data | void * | Data values |}

NXputslab¶

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

;Usage:

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

|- ! rowspan=“4” | 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 |}

NXputattr¶

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.

;Usage:

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

Data Type:NX_CHAR - Character string
NX_FLOAT32 - 4-byte real

NX_FLOAT64 - 8-byte real

NX_INT8 - 1-byte integer

NX_UINT8 - unsigned 1-byte integer

NX_INT16 - 2-byte integer

NX_UINT16 - unsigned 2-byte integer

NX_INT32 - 4-byte integer

NX_UINT32 - unsigned 4-byte integer

|}

NXflush¶

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.

;Usage:

status = NXflush (file_id)

|- ! | Input & Output Argument | file_id | NXhandle * | Identifier of NeXus file |}

Meta-Data Routines¶

NXgetinfo¶

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

;Usage:

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

Data Type:NX_CHAR - Character string
NX_FLOAT32 - 4-byte real

NX_FLOAT64 - 8-byte real

NX_INT8 - 1-byte integer

NX_UINT8 - unsigned 1-byte integer

NX_INT16 - 2-byte integer

NX_UINT16 - unsigned 2-byte integer

NX_INT32 - 4-byte integer

NX_UINT32 - unsigned 4-byte integer

|}

NXgetgroupinfo¶

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

;Usage:

status = NXgetgroupinfo (file_id, item_number, group_name, group_class)

|- ! | Input Arguments | file_id | NXhandle | Identifier of NeXus file |- ! rowspan=“3” | 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 |}

NXinitgroupdir¶

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

;Usage:

status = NXinitgroupdir (file_id)

|- ! | Input Arguments | file_id | NXhandle | Identifier of NeXus file |}

NXgetnextentry¶

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

;Usage:

status = NXgetnextentry (file_id, name, class, data_type)

Data Type:NX_CHAR - Character string
NX_FLOAT32 - 4-byte real

NX_FLOAT64 - 8-byte real

NX_INT8 - 1-byte integer

NX_UINT8 - unsigned 1-byte integer

NX_INT16 - 2-byte integer

NX_UINT16 - unsigned 2-byte integer

NX_INT32 - 4-byte integer

NX_UINT32 - unsigned 4-byte integer

|}

NXgetattrinfo¶

Returns the number of attributes in the current data set.

;Usage:

status = NXgetattrinfo (file_id, attr_number)

|- ! | Input Arguments | file_id | NXhandle | Identifier of NeXus file |- ! | Output Arguments | attr_number | int * | Number of attributes in the current data set |}

NXinitattrdir¶

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

;Usage:

status = NXinitattrdir (file_id)

|- ! | Input Arguments | file_id | NXhandle | Identifier of NeXus file |}

NXgetnextattr¶

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.

;Usage:

status = NXgetnextattr (file_id, attr_name, length, attr_type)

Data type of next attribute:NX_CHAR - Character string
NX_FLOAT32 - 4-byte real

NX_FLOAT64 - 8-byte real

NX_INT8 - 1-byte integer

NX_UINT8 - unsigned 1-byte integer

NX_INT16 - 2-byte integer

NX_UINT16 - unsigned 2-byte integer

NX_INT32 - 4-byte integer

NX_UINT32 - unsigned 4-byte integer

|}

NXgetgroupID¶

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

;Usage:

status = NXgetgroupID (file_id, group_id)

|- ! | Input Arguments | file_id | NXhandle | Identifier of NeXus file |- ! | Output Arguments | group_id | NXlink * | Identifier of NeXus group |}

NXgetdataID¶

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

;Usage:

status = NXgetdataID (file_id, data_id)

|- ! | Input Arguments | file_id | NXhandle | Identifier of NeXus file |- ! | Output Arguments | data_id | NXlink * | Identifier of NeXus data set |}

NXmakelink¶

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.

;Usage:

status = NXmakelink (file_id, link)

|- ! | Input Arguments | file_id | NXhandle | Identifier of NeXus file |- ! | Output Arguments | link | NXlink * | Identifier of linked group |}

NXsameID¶

Tests if two data items are the same, i.e. one is linked to the other.

;Usage:

status = NXsameID (file_id, link1, link2)

|- ! rowspan=“3”| Input Arguments | file_id | NXhandle | Identifier of NeXus file |- | link1 | NXlink * | Identifier of first item |- | link2 | NXlink * | Indentifier of second item |- |}

NXopensourcegroup¶

Opens the group from which a linked dataset was linked. This is useful for accessing auxiliary information related to the dataset. This works only if the linked dataset is currently open.

;Usage:

status = NXopensourcegroup (file_id)

|- ! | Input Arguments | file_id | NXhandle | Identifier of NeXus file |- |}

Memory Allocation¶

NXmalloc¶

Allocates memory to the specified data pointer according to the specifed data type, rank and dimensions.

;Usage:

status = NXmalloc (void** data, int rank, int dimensions[], int datatype)

Data Type:NX_CHAR - Character string
NX_FLOAT32 - 4-byte real

NX_FLOAT64 - 8-byte real

NX_INT8 - 1-byte integer

NX_UINT8 - unsigned 1-byte integer

NX_INT16 - 2-byte integer

NX_UINT16 - unsigned 2-byte integer

NX_INT32 - 4-byte integer

NX_UINT32 - unsigned 4-byte integer

|}

NXfree¶

Frees memory allocated to the specified data pointer.

;Usage:

status = NXfree (data)

|- ! | Input Arguments | data | void ** | Pointer to the allocated memory |}

External Linking¶

NXinquirefile¶

Queries which file is really active.

;Usage:

status = NXinquirefile(handle,filename, filenameLength);

|- ! rowspan=“2” | Input Arguments | handle | NXhandle | handle to a currently open NeXus file. |- | filenameLength | int | length of filename buffer |- ! |Output Arguments | filename | char* | buffer to receive filename |}

NXlinkexternal¶

Links an external file. This happens by creating a group which points to an external file. Navigating into such a group automatically opens the external file.

;Usage:

status = NXlinkexternal(handle,name, nxclass, nxurl);

|- ! rowspan=“4” | Input Arguments | handle | NXhandle | handle to a currently open NeXus file. |- | name | NXname | The name of the group to link the file to. |- | nxclass | NXname | The NeXus class of the group to which the external file is to be linked. |- | nxurl | NXURL | An URL of a format which the NeXus-API understands. The only URL format so far is: nxfile://path-to-file#path-to-group-in-file. This consistes of two parts: The file path and a path to a group in the file which is to be mapped into the source file. |}

NXisexternalgroup¶

Tests in the group is an external group. If not, NX_ERROR is returned. If yes, NX_OK is returned and the URL of the external file is copied into nxurl.

;Usage:

status = NXisexternalgroup(handle,name, nxclass, nxurl,nxurllen);

|- ! rowspan=“4” | Input Arguments | handle | NXhandle | handle to a currently open NeXus file. |- | name | NXname | The name of the group to test. |- | nxclass | NXname | The NeXus class of the group to test. |- | nxurllen | int | length of the nxurl buffer |- ! rowspan=“4” | Output Arguments | nxurl | char * | buffer to copy the URL, too. |}