23 MISCELLANEOUS FACILITIES

23.1 Restricting Access via NDF Identifiers

Access restrictions may be imposed on any NDF identifier in order to constrain the operations which can be performed by NDF_ routines via that identifier. The act of disabling a particular type of access is performed by the routine NDF_NOACC. For instance:

would disable delete access for the identifier INDF. As a result, any subsequent attempt to delete the NDF via that identifier would fail, and the resulting error message would indicate that access had been disabled. Access restrictions imposed on NDF identifiers are propagated to all new identifiers derived from them (e.g. by cloning or creation of an NDF section). Once imposed, they cannot be revoked.

The following types of access may be disabled, either singly or in combination (by means of repeated calls to NDF_NOACC), in order to impose the corresponding restriction on NDF access:

‘BOUNDS’ – Disabling bounds access prevents the pixel-index bounds of a base NDF from being altered (e.g. with the routine NDF_SBND – §21.1). The pixel-index bounds of an NDF section can always be altered regardless of this access restriction, but the restriction will be propagated to any new identifier obtained from an NDF section via the routine NDF_BASE.

‘DELETE’ – Disabling delete access prevents the NDF from being deleted (e.g. with the routine NDF_DELET – §20.11).

‘SHIFT’ – Disabling shift access prevents pixel-index shifts from being applied to a base NDF (e.g. with the routine NDF_SHIFT – §21.2). Pixel-index shifts may always be applied to an NDF section regardless of this access restriction, but the restriction will be propagated to any new identifier obtained from an NDF section via the routine NDF_BASE.

‘TYPE’ – Disabling type access prevents the type of any NDF component from being altered (e.g. with the routine NDF_STYPE – §7.4).

‘WRITE’ – Disabling write access prevents new values from being written to any of the NDF’s components. It also prevents the state of any of its components from being reset (e.g. with the routine NDF_RESET – §5.3).

In addition, specifying an access type of ‘MODIFY’ in a call to NDF_NOACC will disable all the forms of access described above.

You can enquire whether a specified type of access is available via any identifier by using the routine NDF_ISACC. For instance:

will return a logical value ISACC indicating whether write access is available for the identifier INDF.

23.2 Message System Routines

Several of the NDF_ routines are dedicated to generating components of messages, either for information or as part of an error report. These routines use the error and message reporting system (and the ERR_ and MSG_ routines) described in SUN/104.

The routine NDF_MSG may be used to assign the name of an NDF to a message token, so that references to NDFs can form part of a message, as follows:

Here, ‘NAME’ is the message token name.

The routine NDF_CMSG may be used in a similar way to assign the value of an NDF character component to a message token, while NDF_ACMSG may be used to assign the value of an axis character component (such as an axis label) to a message token. Their use is illustrated in §6.1 and §19.6 respectively.

23.3 Tuning the NDF_ System

The routine NDF_TUNE is provided to allow various features of the NDF_ system to be configured for individual needs if the default behaviour is not appropriate. This process is referred to as tuning the system, and is performed as follows:

Here, a new value of zero is specified for the tuning parameter called ‘WARN’. The current setting of a tuning parameter may be determined using the related routine NDF_GTUNE which returns the parameter’s value via its VALUE argument, as follows:

By using these two routines in pairs it is possible to determine the original setting of a tuning parameter, modify it locally, and then return it to its original value if necessary.

Each tuning parameter controls one aspect of the NDF_ system’s behaviour according to the value which has been set for it. The tuning parameters currently available are as follows:

AUTO_HISTORY:

Controls whether to include an empty History component in NDFs created using NDF_NEW or NDF_CREAT. If the tuning parameter is zet to zero (the default), no History component will be included in the new NDFs. If the tuning parameter is zet non-zero, a History component will be added automatically to the new NDFs.

DOCVT:

Controls whether to convert foreign format data files to and from native NDF format for access (using the facilities described in SSN/20). If DOCVT is set to 1 (the default), and the other necessary steps described in SSN/20 have been taken, then such conversions will be performed whenever they are necessary to gain access to data stored in a foreign format. If DOCVT is set to 0, no such conversions will be attempted and all data will be accessed in native NDF format only.

The value of DOCVT may be changed at any time. It is the value current when a dataset is acquired by the NDF_ library (or a placeholder for a new dataset is created) which is significant.

KEEP:

Controls whether to retain a native format NDF copy of any foreign format data files which are accessed by the NDF_ library (and automatically converted using the facilities described in SSN/20). If KEEP is set to 0 (the default), then the results of converting foreign format data files will be stored in scratch filespace and deleted when no longer required. If KEEP is set to 1, the results of the conversion will instead be stored in permanent NDF data files in the default directory (such files will have the same name as the foreign file from which they are derived and a file type of ‘.sdf’). Setting KEEP to 1 may be useful if the same datasets are to be re-used, as it avoids having to convert them on each occasion.

The value of KEEP may be changed at any time. It is the value current when a foreign format file is first accessed by the NDF_ library which is significant.

ROUND:

Specifies the way in which floating-point values should be converted to integer during automatic type conversion. If ROUND is set to 1, then floating-point values are rounded to the nearest integer value. If ROUND is set to 0 (the default), floating-point values are truncated towards zero.

SECMAX:

Specifies the maximum number of pixels allowed in an NDF section, in units of mega-pixels. An error will be reported if an attempt is made to create a section containing more than this number of pixels. The primary purpose of this tuning parameter is to guard against accidental use of incorrect WCS units within a user-supplied section specified, that may result in huge sections being requested. The default value is 2147 mega-pixels, which is the largest value that can be held by a four byte integer.

SHCVT:

Controls whether diagnostic information is displayed to show the actions being taken to convert to and from foreign data formats (using the facilities described in SSN/20). If SHCVT is set to 1, then this information is displayed to assist in debugging external format conversion software whenever a foreign format file is accessed. If SHCVT is set to 0 (the default), this information does not appear and format conversion proceeds silently unless an error occurs.

TRACE:

Controls the reporting of additional error messages which may occasionally be useful for diagnosing internal problems within the NDF_ library. If TRACE is set to 1, then any error occurring within the NDF_ system will be accompanied by error messages indicating which internal routines have exited prematurely as a result. If TRACE is set to 0 (the default), this internal diagnostic information will not appear and only standard error messages will be produced.

WARN:

Controls the issuing of warning messages when certain non-fatal errors in the structure of NDF data objects are detected. If WARN is set to 1 (the default), then a warning message is issued. If WARN is set to 0, then no message is issued. In both cases normal execution continues and no STATUS value is set.

The value of tuning parameters may also be set by the user of NDF_ applications independently of the application itself. This is accomplished by defining an environment variable whose name is constructed by prefixing ‘NDF_’ to the name of the tuning parameter to be set. Thus, the shell command:

would set the ‘TRACE’ tuning parameter to 1 by default for all subsequent NDF_ applications (i.e. over-riding the default described above). The application may, however, still modify the value itself.

Note that all tuning parameters set in this way must be given valid integer values. If the associated environment variable does not translate to a valid value, the default will remain unchanged.