[Return | NeXus Site Map]

The IDL-NeXus Interface

Introduction

NeXus is an attempt to define a common data format for neutron and X-ray scattering. More information about NeXus can be found at http://www.neutron.anl.gov/NeXus/. NeXus is based on the Hierarchical Data Format (HDF) developed by the National Center for Supe Computing Applications, NCSA in USA. HDF-files are accessed through a C language interface library. This library is fairly complex. Therefore a set of API functions was developed for NeXus which simplify the access to the HDF-library. This NeXus-API was written in C and has a Fortran77 binding.

IDL is an interactive data evaluation environment developed by research systems. It is an interpreted language for data manipulation and visualisation. Part of IDL is an HDF-interface. In order to facilitate the import of NeXus files into this popular data manipulation package, the NeXus-API was reimplemented in the IDL language. This document describes this port. The package may be downloaded as a tar file from <ftp://ftp.neutron.anl.gov/nexus/nidl.tar>.

General Notes

In general the notation of the C-language NeXus routines was followed as closely as possible. However, there are a few differences: As IDL does not support symbolic constants as C does the return values of the NeXus functions differ. IDL NeXus functions return a 1 on success, and a 0 on failure. All error messages are printed through a special function, NXprinterror. Modify this function if the NeXus error output should not be printed to the IDL command line but should go somewhere else. The other change is with the directory search functions, NXgetnextentry and NXgetnextattr. These have been completely replaced by NXgroupdir and NXattdir. Due to the dynamic and garbage collected nature of the IDL language it is not necessary to retrieve directory entries one by one, but it is easier to return arrays of strings with the necessary information.

All functions require as a parameter the name of a NeXus internal structure. This structure is initialised in the call to nxopen. This structure has to be passed as a parameter with each IDL-NeXus-API call. Never, ever tamper with this structure. Otherwise the results will be undefined.

Prerequisites

In order to use the IDL-NeXus API functions you need to have a version of IDL with HDF library support. The NeXus-IDL API was developed under version 5.1 of IDL. Earlier versions may do the trick as well.

Furthermore you need to include and compile the functions in the file nidl.pro into your IDL system.

IDL-NeXus-API Function Description

ret=nxopen(filename,access,handle)

This call opens a NeXus file. The parameter filename is the filename of the NeXus file. The parameter access is a string defining the access method to the file. Possible values are: 'read', 'write' and 'create'. Their meaning should be clear. handle is just a named variable which will ne filled with NeXus internal information during this call. This handle will be passed along with every other request to the NeXus routines. Never ever tamper with this structure or the results may be disastrous.

ret=nxclose(handle)

Closes the NeXus file.

ret=nxmakegroup(handle,groupname,groupclass)

Creates a new NeXus group. The name of this group will be groupname, the class will be groupclass. Note, that all NeXus class names begin with NX.

ret=nxopengroup(handle,gname,gclass)

Opens the NeXus group gname of class gclass. Corresponds to a cd gname in a file system.

ret=nxclosegroup(handle)

Closes the access to the current NeXus group. Corresponds to a cd .. in a file system.

ret=nxmakedata(handle,dname,datatype, rank, dimensions)

Creates a new NeXus dataset. The new dataset will have the name gname. rank denotes the number of dimensions the dataset is going to have. dimensions is an array of integers which give the size of the dataset in each dimension. It must have at least rank values. datatype is a string describing the datatype for the dataset. The following values are currently recognized:

• NX_CHAR
• NX_INT8
• NX_UINT8
• NX_INT16
• NX_UINT16
• NX_INT32
• NX_UINT32
• NX_FLOAT32
• NX_FLOAT64

ret=nxopendata(handle,gname)

Opens the dataset gname for access. This call corresponds to a fopen in a file system.

ret=nxclosedata(handle)

Closes the access to the current dataset. In a file system this call would correspond to a fclose.

ret=nxgetdata(handle,data)

Reads NeXus data from a NeXus dataset opened with nxopendata. The data is returned in the array data.

ret=nxgetslab(handle,data,start,count)

Reads a subset of data from a NeXus dataset opened with nxopendata. The data is returned in the array data. start is an integer array giving the start indices of the subset to read. count is another integer array giving the number of data items to read in each dimension. The arrays start and count must be at least as long as the rank of the dataset. Due to a glitch in IDL, the arrays have to be at least 2 elements long, otherwise they are not recognized as arrays.

ret=nxgetattr(handle,aname,data,typ)

This call reads the value of the attribute aname. If a NeXus dataset had been opened previously with nxopendata, the attribute is read from the dataset. Else the functions tries to find a global attribute aname. When found, the value of the attribute is returned in data and its type in the variable typ.

ret=nxgetinfo(handle,rank,dim,typ)

NXgetinfo requests information about a NeXus dataset previously opened with nxopendata. After a successful return, the variable rank will hold the rank of the dataset, dim will be an integer array with the size of the dataset in each dimension and type will be the number type of the dataset.

ret=nxputdata(handle,data)

Writes data to a NeXus dataset opened with nxopendata. The data is taken from the the array data.

ret=nxputslab(handle,data,start,count)

Writes a subset of data to a NeXus dataset opened with nxopendata. The data is taken from the array data. start is an integer array giving the start indices of the subset to read. count is another integer array giving the number of data items to read in each dimension. The arrays start and count must be at least as long as the rank of the dataset. Due to a glitch in IDL, the arrays have to be at least 2 elements long, otherwise they are not recognized as arrays.

ret=nxputattr(handle,aname,data)

This call writes an attribute of name aname. If a NeXus dataset had been opened previously with nxopendata, the attribute is written to the dataset. Else the functions creates a global attribute aname. The value of the attribute is taken from data. Type conversions are performed as necessary.

ret=nxgroupdir(handle,names, classes)

NXgroupdir requests the names of NeXus datasets and groups at the current level in the hierarchy. In a filesystem it corresponds to a ls or dir. After a successful return, names will be a string array holding the names of all items at the current level. Class will be a string array holding the class names for NeXus groups and the string SDS for NeXus datasets.

ret=nxattdir(handle,names)

NXattdir returns a list of attributes at the current level. If a NeXus dataset had been opened previously with nxopendata the attributes of the dataset are returned. Otherwise a list of global attributes is returned in the string array names.

ret=nxgetgroupid(handle,id)

NXgetgroupid retrieves all information necessary for linking a NeXus group to another NeXus group. The requested group must have been opened with nxopengroup before this call can be issued. The information is returned in the variable id. Never tamper with the data in there.

ret=nxgetdataid(handle,id)

NXgetgroupid retrieves all information necessary for linking a NeXus dataset into a NeXus group. The requested datset must have been opened with nxopendata before this call can be issued. The information is returned in the variable id. Never tamper with the data in there.

ret=nxmakelink(handle,id)

NXmakelink links a NeXus dataset or group into the current group level. A NeXus group must have been opened with nxopengroup before this call can be issued. id must be an id variable as returned by either a call to nxgetgroupid or nxgetdataid.