<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html><head><title>ExternalLinking.radi</title>

<base href="file:///afs/psi.ch/user/k/koennecke/tmp/">

</head><body>

<h2>NAPI-4.* External Linking </h2>

<p>As of version 4.0 of the NeXus-API external linking is supported. External linking means

the transparent access to further files from within a given NeXus file. This can be 

useful for accessing shared calibration files.

</p></p><h3>External Linking API </h3>

<p>In order to support external linking three new NeXus-API functions have been defined:

<dl></p><dt>NXstatus NXinquirefile(NXhandle handle, char *filename, int fileNameLen)

<dd>

 This is an inquiry function which allows to find out which file is currently being accessed.  

 At max fileNameLen bytes of filename information is copied into filename.

<dt>NXstatus NXlinkexternal(NXhandle, char *name, char *nxclass, char *nxurl)

<dd> This function creates an 

 external link. The group name with class nxclass will be linked to the external file characterized

 through the URL nxurl. The group must exits before this call. It should be empty as well. Nxurl 

 can currently only have the form: <b>nxfile://path-to-file#path-infile</b>. For example: nxfile://data/dmc01.hdf#/entry1.

 With this URL all accesses to name. nxclass will be redirected to /entry1 in dmc01.hdf.

<dt>NXstatus NXisexternalgroup(NXhandle handle, char *name, char *nxclass, char *nxurl, int nxurlLen)

<dd> This function allows

 to query if a group is externally linked or not. If the group is not externally linked, NX_ERROR will be returned. If the group

 is externally linked, NX_OK will be returned and nxurlLen bytes of URL information will be copied into nxurl.

<p></dl>Here is an example for creating external links:

<pre>

NXhandle fileId;

NXopen("extest.hdf",NXACC_CREATE,&fileId);

NXmakegroup(fileId,"entry1","NXentry");

NXlinkexternal(fileId,"entry1","NXentry","nxfile://data/dmc01.hdf#/entry1");

NXmakegroup(fileId,"entry2","NXentry");

NXlinkexternal(fileId,"entry2","NXentry","nxfile://data/dmc02.hdf#/entry1");

NXclose(&fileId);

</pre>

</p></p><p>Now, when navigating this file, opening entry1 will automatically cause entry1 to be 

 replaced with the content of dmc01.hdf, /entry1! Navigating back, dmc01,hdf will be closed and 

 when accessing entry2, dmc02.hdf, /entry1 will be accessed. Amazing and confusing! Please note, that

 there is read-only access to external files only. 

</p></p><hr>

<h3>NX_LOAD_PATH </h3>

<p>In  order to make the handling of external linking easier, NXopen has been modified to search for NeXus files 

 in a path specified through the environment variable NX_LOAD_PATH. This is a colon separated list of search 

 path in unix and in windows it is a semicolon separated list. When NXopen tries to access a file it first tries to open 

 the filename given to it as is. If this fails, all the search paths entries from NX_LOAD_path will be tried. Only then

NXopen gives up. 

</p></p><hr>

<h3>Group Attributes </h3>

<p>NAPI-4.* also brings group attributes. Group attributes can now be created and accessed just like dataset attributes. This implementation

brings a small backwards incompatible change: Global attributes will now only be written at root level. Before, global attributes 

 were written whenever no dataset was open. 

</p></p>   

</body></html>