H CHANGES AND NEW FEATURES

H.1 Changes Introduced in V1.3

The following describes the most significant changes which occurred in the NDF_ system between versions V1.2 and V1.3 (not the current version):

(1)

New facilities have been added for handling NDF history information (see §22).

(2)

New facilities have been added to allow the automatic reading and writing of data files written in a variety of “foreign” (i.e. non-NDF) formats. These are described in a separate document (SSN/20).

(3)

A new routine NDF_OPEN has been added to provide a general means of accessing NDF datasets by name, locator, or a combination of both. It is modelled on the Fortran OPEN statement (see §20.10) and provides flexible NDF access for programmers who do not wish to use the ADAM parameter system.

(4)

The symbolic constant DAT__ROOT provided by HDS is now supported by all NDF_ routines which accept HDS locators (see §20). Use of this constant in place of an HDS locator indicates that the associated component name is in fact the full name of the HDS object (or NDF). This allows access to HDS objects by name as an alternative to using locators. The name of a foreign format data file may also be supplied using this mechanism (SSN/20).

(5)

All routines that accept the names of pre-existing NDF datasets now support subscripting, and will return an appropriate NDF section.

(6)

A new selective copy routine NDF_SCOPY has been added (see §20.9) which performs component propagation in a similar manner to NDF_PROP but does not depend on the ADAM parameter system.

(7)

The two sets of routines NDF_XGT0x and NDF_XPT0x (where “x” is I, R, D, L or C) will now accept compound component names when reading or writing the values of objects in NDF extensions. This allows direct access to values stored within nested structures or arrays in extensions (see §§11.4 & 11.5). The routine NDF_XIARY has also been similarly enhanced.

(8)

The routine NDF_TUNE has been extended to support new tuning parameters, most of which are associated with the facilities for accessing foreign data formats (see above).

(9)

Tuning parameters now acquire their default values from environment variables (see §23.3).

(10)

Due to changes in the underlying data system (HDS), locators to data objects may now be annulled freely without risk of affecting the operation of the NDF_ library.

(11)

There is no longer any need to call the routine HDS_START in standalone programs which use the NDF_ library (previously this was required), although doing so will do no harm.

(12)

Instructions for compiling and linking NDF applications on UNIX have been added to the documentation.

(13)

On UNIX systems where shareable libraries are supported, these are now installed in a separate .../share directory (rather than alongside the non-shareable libraries in the .../lib directory). You should include the appropriate .../share directory (normally /star/share on Starlink systems) in your library search path if you wish to use shareable libraries on UNIX.

(14)

The routine NDF_XNUMB now returns a guaranteed value of zero if it is called with STATUS set, or if it should fail for any reason.

(15)

A number of new error codes associated with the NDF history component and with access to foreign data formats have been added to the include file NDF_ERR.

(16)

The routine NDF_IMPRT has been documented as obsolete. Its function is now performed by NDF_FIND by specifying a blank second argument.

(17)

The routine NDF_TRACE has been documented as obsolete. Its function is now performed by NDF_TUNE via the tuning parameter ‘TRACE’.

H.2 Changes Introduced in V1.4

The following describes the most significant changes which occurred in the NDF_ system between versions V1.3 and V1.4 (not the current version):

(1)

The routines NDF_TUNE and NDF_GTUNE have been extended to support the new DOCVT tuning parameter. This allows automatic conversion of foreign format data files (SSN/20) to be disabled when not required.

(2)

The maximum number of foreign data formats that can be recognised by the NDF_ library (SSN/20) has been increased from 20 to 50.

(3)

Two new routines NDF_GTWCS and NDF_PTWCS have been provided to read and write World Coordinate System (WCS) information to an NDF. These WCS facilities are implemented using the new AST library (see SUN/210). NDF_GTWCS returns an AST pointer to a FrameSet and NDF_PTWCS expects a similar pointer to be supplied.

Note that this constitutes only a preliminary introduction of WCS facilities to the NDF library, mainly to permit the writing of data format conversion applications that support WCS information. Descriptions of the new routines are included in this document, but the main text does not yet contain an overview of the WCS facilities, for which you should consult SUN/210 at present. Further recommendations on the use of AST with the NDF_ library will be given in future, once experience with the new facilities has been gained.

(4)

The new “WCS” component is now supported by other NDF_ routines, where appropriate (e.g. NDF_PROP, NDF_RESET, NDF_SCOPY, NDF_SECT and NDF_STATE).

(5)

A bug has been fixed in the NDF_SBB routine which could occasionally cause it to access the bad-bits value for the wrong NDF.

(6)

A bug has been fixed which could result in failure to access a named NDF data structure comprising one of the AXIS components of another NDF (for example, “NDF.AXIS(2)”).

(7)

The documentation (SUN/33 and SSN/20) has been updated to reflect these changes.

H.3 Changes Introduced in V1.5

The following describes the most significant changes which occurred in the NDF_ system between versions V1.4 and V1.5:

(1)

An interface to the library has been added which is callable from C (see Appendices E and F).

(2)

A new include file “ndf.h” has been added to support the C interface.

(3)

Several new error codes have been introduced to support the C interface.

(4)

References to the VMS operating system have been removed from the documentation (VMS is no longer supported by the current version of the NDF_ library).

(5)

This document (SUN/33) has been updated to reflect recent changes to the library.

H.4 Changes Introduced in V1.6

The following describes the most significant changes which occurred in the NDF_ system between versions V1.5 and V1.6:

(1)

Limited support for NDF array components stored in “scaled” form has been introduced. The new routine NDF_PTSZx will associate scale and zero values with an existing array component, thus converting it into a scaled array. See §12.4.

H.5 Changes Introduced in V1.7

The following describes the most significant changes which occurred in the NDF_ system between versions V1.6 and V1.7:

(1)

NDF sections expressions can now include WCS axis values. See §16.3.

(2)

New tuning parameters (“PXT...”) can be used to supress the default propagation of named NDF extensions by NDF_PROP and NDF_SCOPY. See NDF_TUNE.

H.6 Changes Introduced in V1.8

The following describes the most significant changes which occurred in the NDF_ system between versions V1.7 and V1.8:

(1)

The routine NDF_HSDAT has been added. This allows history records to be created with a specified date.

H.7 Changes Introduced in V1.9

The following describes the most significant changes which occurred in the NDF_ system between versions V1.8 and V1.9:

(1)

A new standard WCS Frame called FRACTION has been introduced, This Frame is created automatically by the NDF library in the same that the GRID, PIXEL and AXIS Frames are created. The FRACTION Frame represents normalised pixel coordinates within the array - each pixel axis spans the range 0.0 to 1.0 in the FRACTION Frame.

(2)

NDF sections specifiers can now use the “%” character to indicate that a value is a percentage of the entire pixel axis. Thus “m31($\sim$50%,)” will create a section covering the central 50 percent of the NDF on the first pixel axis.

(3)

A history component will now be added automatically to the NDFs created by NDF_CREAT and NDF_NEW if the “NDF_AUTO_HISTORY” environment variable, or “AUTO_HISTORY” tuning parameter, is set to a non-zero integer.

H.8 Changes Introduced in V1.10

The following describes the most significant changes which occurred in the NDF_ system between versions V1.9 and V1.10:

(1)

A new function NDF_ISIN has been added, which determines if one NDF is contained within another NDF.

(2)

The NDF_SCOPY and NDF_PROP functions now allow an asterisk to be used within the CLIST argument as a wild card to match all extension names.

H.9 Changes Introduced in V1.11

The following describes the most significant changes which occurred in the NDF_ system between versions V1.10 and V1.11:

(1)

Limited support for NDF array components stored in “delta’ compressed form has been introduced. The new routine NDF_ZDELT will create a delta compressed copy of an input NDF, and the new routine NDF_GTDLT will return details of the compression of a delta compressed NDF. See §12.5.

(2)

A new function NDF_ZSCAL has been added, which creates a SCALED copy of an input NDF with SIMPLE or PRIMITIVE array components.

(3)

A new function NDF_CREPL has been added, which allows an NDF placeholder to be created via a specified environment parameter.

H.10 Changes Introduced in V1.12

The following describes the most significant changes which occurred in the NDF_ system between versions V1.11 and V1.12:

(1)

Support for 64 bit integer data values added.

(2)

A new tuning parameter SECMAX has been aded, which allows the maximum number of pixels within an NDF section to be specified. See §23.3.

(3)

A new routine NDF_CANCL can be used to cancel the association between an environment parameter and an NDF. This is identical to calling PAR_CANCL, except that NDF_CANCL provides an option to cancel all NDF parameters in a single call, without needing to know their names.

H.11 Changes Introduced in V1.13

The following describes the most significant changes that occurred in the NDF_ system between versions V1.12 and V1.13 (the current version):

(1)

A new routine NDF_HCOPY has been added to copy history information from one NDF to another.

No changes to existing applications should be required, nor is any re-compilation or re-linking essential.

H.12 Changes Introduced in V2.0

The following describes the most significant changes that occurred in the NDF_ system between versions V1.13 and V2.0:

(1)

The NDF library is now written entirely in C. However, the Fortran interface has not changed and is provided by a thin layer on top of the C library.

(2)

The only change to the C interface is that there is now no need to call ndfInit to initialise the library. This is done automatically when an application first calls an NDF function.

(3)

The C interface is now thread safe.

(4)

New functions are provided in the C interface to allow each NDF to be locked for exclusive access by a single thread.

H.13 Changes Introduced in V2.1

The following describes the most significant changes that occurred in the NDF_ system between versions V2.0 and V2.1:

(1)

A new tuning parameter called ROUND has been added that controls how floating-point values are converted to integer during automatic type conversion.

(2)

The behaviour of ndfUnlock has changed. Previously, calling ndfUnlock would automatically annull all other identifiers associated with the same base NDF. This no longer happens. Such identifiers can now be used safely once the original thread has regained the lock on the base NDF.

H.14 Changes Introduced in V2.2

The following describes the most significant changes that occurred in the NDF_ system between versions V2.1 and V2.2 (the current version):

(1)

It is now possible to specifiy the extent of an NDF section using arc-distance values (see §??).

Existing applications should be re-compiled and re-linked.