Nexus-API IDL - README

Contents

Overview

NeXus IDL Api binds the NeXus libraries to IDL (Interactive Data Language). It brings functionality of the NeXus API to IDL for reading, writing and modifying NeXus Files. IDL NeXus API imitates the functionality NeXus API with few exeptions discussed later.

Information on NeXus Dataformat: http://www.nexusformat.org/Introduction.

Information on IDL: http://www.nexusformat.org/Introduction.


Installation

Requirements

Precompiled versions of the DLM (Dynamic Link Module) for Windows (NeXusIDL-API.dll) and Linux (NeXusIDL-API.so) are included in the package. If you want to build the DLM a C compiler is required. GCC for Linux and Microsoft Visual C++ version 6 have been tested. IDL (ver 6) and the latest NeXus API are required.

The NeXus packages and installation instructions are available at http://www.nexusformat.org/Download.

Microsoft offers a free Microsoft C Compiler Toolkit to Compile DLMs for IDL on Windows http://msdn.microsoft.com/visualc/vctoolkit2003/

For Windows the NeXus Data Format Windows Installer Kit, which includes the necessary hdf5, hdf4 and xml libraries, is recommended. http://download.nexusformat.org/kits/windows/

If the NeXus API header file napi.h is not installed in path you have to edit the correct path to #include list in NeXusIDL-API.c

For linux:
#include "Nexus path/include/napi.h"
For windows:
#include "C:\Program Files\NeXus Data Format\include\napi.h"

Linux

Edit correct IDL, HDF libraries and NeXus Library paths to Makefile.

#Configure these directories:

IDL_DIR = /usr/pack/idl-6.3-vm/idl/

HDFROOT=/afs/psi.ch/project/sinq/sl-linux

LIBNEXUS = ../../src/trunk/src/.libs/libNeXus.a

Compile with 'make'.

Windows

Edit buildwin.bat and change the correct IDL and NeXus directories.

REM Configure these directories:

SET IDL_DIR=c:\rsi\idl63

SET NXS_DIR= "C:\Program Files\NeXus Data Format"

The compiler and linker have to be set to a path. In Visual C++ they can be set with running the batch file in "Microsoft Visual C Directory\VC98\bin\vcvars32.bat". Run buildwin.bat to run build the API.


Using API from IDL

Installing a New DLM File To IDL

Recommeneded way to install the DLM file (NeXusIDL-API.dlm) and the library (NeXusIDL-API.so or NeXusIDL-API.dll) is to copy them to one of the directories IDL searches at startup (and contained in the !IDL_PATH system variable). NOTE: The DLM file and the library must excist in the same directory.

DLM's can be also loaded with the DLM_REGISTER command in IDL. Also IDL registeres all the DLM files that are located in the directory where it was started in. These options are only preferred for testing.

new_dlm_file = '/home/scratch/lns/kauppila/temp/IDLNeXus-API/IDLNeXus-API.dlm'

DLM_REGISTER, new_dlm_file

Test Files

The IDLNeXus-API includes IDL files for testing write and read functions of the API. write_test.pro and read_test.pro provide identical functionality as in the orginal C api napi_test.h

Testfiles write_test.pro and read_test.pro are included. After registering the DLM run in IDL:

write_test.pro: Writes a test NeXus file. Accessmethod can be assigned with parameters hdf5, hdf4 and xml. The error codes returned by the routines are printed to IDL console. 1 = NX_OK, 0 = NX_ERROR

write_test (Uses NeXus accessmode HDF5 for default. Writes NXtest.h5)

write_test, hdf5 ;(Writes HDF5 file NXtest.h5)

write_test, hdf4 ;(Writes HDF4 file NXtest.hdf)

write_test, xml ;(Writes XML file NXtest.xml)


read_test: reads the NXtest file produced by write_test and tests the reading functions. Results are printed to IDL console.

read_test ;(Uses NeXus accessmode HDF5 for default. Reads NXtest.h5)

read_test, hdf5 ;(Reads HDF5 file NXtest.h5)

read_test, hdf4 ;(Reads HDF4 file NXtest.hdf)

read_test, xml ;(Reads XML file NXtest.xml)

recursiveread.pro: Takes a NeXus supported file as a parameter and prints all the data and attributes of the file to IDL console.

recursiveread ;(Prints default file Nxtest.h5)

recursiveread, nexusfile.nxs ;(Prints nexusfile.nxs)

Using The API And An Example

The API's functions aim to reproduce the funtionality of the C API closely. Some low level functionality has been hidden from the user. Memory allocation functions NXmalloc and NXfree are done automatically in the API when needed. In the spirit of IDL, variables or arrays retrieved with nxgetdata, nxgetslab or nxgetattr don't have to be datatyped beforehand. However when inputting data or attributes with nxputdata, nxputslab or nxputattr the datatypes in IDL have to match with the datatype of the dataset which is declared with nxmakedata or in the nxputattr parameters. The matching datatypes are:

NeXus Datatype Idl Datatype
NX_CHAR IDL_STRING
NX_FLOAT32 float
NX_FLOAT64 double
NX_UINT8 IDL_CHAR
NX_INT16 IDL_INT
NX_UINT16 IDL_UINT
NX_INT32 IDL_LONG
NX_UINT32 IDL_ULONG


Here is simple example program that demonstrates the basic functions and most important differences between the C Nexus Api and the IDL Nexus API.
1. Creates a NeXus file with access method HDF5
2. adds datagroups
3. makes a data array of data type NX_INT32
4. puts data to the array
5. reads the data and attributes
6. prints data and attribute value
7.closes the groups and the file.
pro simpletest
; Accessmethod accepts strings or integer
S = nxopen("test.h5","NXACC_CREATE5",fileid)
S = nxmakegroup(fileid, "testgroup", "NXentry")
S = nxopengroup(fileid, "testgroup", "NXentry")
S = nxmakegroup(fileid, "anothergroup", "NXentry")

;Only type Long arrays are accepted for declaring dimensions with nxmakedata or nxputslab
array =[4L,4L] ; Array Dimensions
rank = 2 ; Array rank
;Datatype long data array
data =[[0L,1L,2L,3L],[4L,5L,6L,7L],[8L,9L,10L,11L],[12L,13L,14L,15L] ]

; Make a data set for the array with 4x4 elements, rank 2 and data type NX_INT32, which matches the IDL data type Long
; Data type accepts strings or integer values.
S = nxmakedata(fileid, 'data1', 'NX_INT32', rank, array)
S = nxopendata(fileid, "data1")
S = nxputdata(fileid, data)

; IDL data type of the attribute has to match the NeXus data type assigned with parameter datatype
; Here IDL UINT and NX_UINT16
attributevalue = 42UINT
S = nxputattr(fileid,'test-attribute', attributevalue, 1, 'NX_UINT16')
S = nxclosedata(fileid)
S = nxopendata(fileid, "data1")
S = nxgetdata(fileid, getdata)
print, 'data : ',getdata
S = nxgetnextattr (fileid, attrname, lenght, attr_type)
S = nxgetattr(fileid, attrname, value, lenght,attr_type)
print, 'attribute value: ', value
S = nxclosedata(fileid)
S = nxclosegroup(fileid)
S = nxclose(fileid)
end

NeXus IDL API Routines

Here's the list of functions in the NeXus IDL API.
(Limitatins 8 dimensions data max 8192 handles and 200 links per handle, NXINT8 not supported in data)

General Initialization and Shutdown

NXopen

Opens the NeXus file, and creates and initializes the NeXus file structure. The returned handle is integer assosiated with a pointer structure, do not modify it.

Usage
status = NXopen (file_name, access_method, file_id)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_name string Name of NeXus file to be opened
access_method int or string
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 int Identifier of NeXus file

NXclose

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

Usage
status = NXclose (file_id)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int 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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int Identifier of NeXus file
group_name string Name of NeXus group
group_class string 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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int Identifier of NeXus file
group_name string Name of NeXus group
group_class string 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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int Identifier of NeXus file
path_string string 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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int Identifier of NeXus file
path_string string 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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int Identifier of NeXus file

NXmakedata

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

NeXus IDL API NOTE: The data type for the dimensions array must be type long.

Usage
status = NXmakedata (file_id, data_name, data_type, rank, dimensions[])
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int Identifier of NeXus file
data_name string Name of NeXus data set
data_type int or 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
rank int Rank of data
dimensions Array of IDL type Long 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.

NeXus IDL API NOTE: The data type for the dimensions array and bufsize array must be type long in IDL.

Usage
status = NXcompmakedata (file_id, data_name, data_type, rank, dimensions[], compress_type, bufsize[])
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int Identifier of NeXus file
data_name string Name of NeXus data set
data_type int or 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
rank int Rank of data
dimensions Array of IDL type Long Dimensions of data. The array is of size 'rank'
compress_type int or string
Compression algorithm
NX_COMP_LZW - GZIP
NX_COMP_HUF - Skipping Huffman
NX_COMP_RLE - Run Length Encoding
bufsize Array of IDL type Long 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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int Identifier of NeXus file
data_name string 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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int Identifier of NeXus file
compress_type int or string
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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int 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
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int Identifier of NeXus file
data_type int or string The NeXus data type for which to change the print format.
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 string 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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int Identifier of NeXus file
Output Arguments data equivalent IDL data type of the NeXus data 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.

NeXus IDL API NOTE: The data type for the slab start and slab size arrays must be type long in IDL.

Usage
status = NXgetslab (file_id, data, start[], size[])
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int Identifier of NeXus file
start[] Array of IDL type Long Indices of starting values in each dimension
size[] Array of IDL type Long Length of slab in each dimension
Output Arguments data equivalent IDL data type of the NeXus data 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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int Identifier of NeXus file
attr_name string Name of attribute
length int Length of buffer for storing attribute data
type int or string
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
Output Arguments value equivalent IDL data type of the NeXus data Value of attribute
length int Actual length of attribute data

NXputdata

Writes data into the specified data set. Datatype of the dataset and the IDL data type of the input data must be of equivalent data type. Refer to the chart: 3.3 Using The API And An Example

Usage
status = NXputdata (file_id, data[])
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int Identifier of NeXus file
data equivalent IDL data type of the prepared NeXus data 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.

Datatype of the dataset and the IDL data type of the input data must be of equivalent data type. Refer to the chart: 3.3 Using The API And An Example

NeXus IDL API NOTE: The data type for the slab start and slab size arrays must be type long in IDL.

Usage
status = NXputslab (file_id, data, start[], size[])
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int Identifier of NeXus file
data equivalent IDL data type of the NeXus data Data values
start[] Array of IDL type Long Indices of starting values in each dimension
size[] Array of IDL type Long 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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Return Value status int Error status
Input Arguments file_id int Identifier of NeXus file
attr_name string Name of attribute
value equivalent IDL data type of the prepared NeXus data Value of attribute
length int Length of data
type int or 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

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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input & Output Argument file_id int 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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int Identifier of NeXus file
Output Arguments rank int Rank of data
dimensions int[] Dimensions of data
data_type int
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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int Identifier of NeXus file
Output Arguments item_number int Number of NeXus data items in the current group
group_name string Name of currently open NeXus group
group_class string 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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int 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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR, NX_EOD)
Input Arguments file_id int Identifier of NeXus file
Output Arguments name string Name of NeXus data item (group or set)
class string Class of NeXus group
data_type int
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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int 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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int 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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR, NX_EOD)
Input Arguments file_id int Identifier of NeXus file
Output Arguments attr_name string Name of next attribute
length int Length of next attribute
attr_type int
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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int Identifier of NeXus file
Output Arguments group_id int 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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int Identifier of NeXus file
Output Arguments data_id int 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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int Identifier of NeXus file
link int Identifier of linked group

NXmakenamedlink

Links a data item (group or set) to a named NeXus group. Returns NX_ERROR if the current group level is the root level, since no data item can be linked here.

Usage
status = NXmakenamedlink (file_id, linkname, link)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int Identifier of NeXus file
linkname string Name of the link to be created
link int 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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int Identifier of NeXus file
link1 int Identifier of first item
link2 int 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)
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments file_id int Identifier of NeXus file

External Linking

Nxinquirefile

Queries which file is really active.

Usage
status = NXinquirefile(handle,filename, filenameLength);
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments handle int handle to a currently open NeXus file.
filenameLenght int length of filename buffer
Output Arguments filename string 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);
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments handle int handle to a currently open NeXus file.
name string (NXname) The name of the group to link the file to.
nxclass string (NXname) The NeXus class of the group to which the external file is to be linked.
nxurl string (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);
  Name Type Description
Return Value status int Error status (NX_OK, NX_ERROR)
Input Arguments handle int handle to a currently open NeXus file.
name string (NXname) The name of the group to test.
nxclass string (NXname) The NeXus class of the group to test.
nxurllen int length of the nxurl buffer
Output Arguments nxurl string buffer to copy the URL, too.