5 GENERAL PROPERTIES OF NDF COMPONENTS

This section describes how to refer to the components of an NDF and outlines the general concept of a component’s state.

5.1 Specifying Component Names

Many NDF_ routines are capable of operating on more than one NDF component and use a character string holding one of the component names given in §2.1 to identify the component to be used. If required, these names may be abbreviated (to no less than 3 characters) and may be written using both upper- and lower-case characters. Thus:

could all be passed to NDF_ routines as valid component names. To avoid confusion between component names and other character strings which may occasionally have the same value, all component names in programming examples in this document are given with a capitalised first letter followed by lower-case, e.g. ‘Quality’.

Some NDF_ routines will also accept a list of components, in which the component names should be separated by commas, for instance:

Spaces may be included before and after component names, but may not be embedded within them.

5.2 Component State

Although the state of an NDF component is strictly an attribute of each individual component, it is nevertheless convenient to discuss it here because all components behave similarly in this respect, and the descriptions of component access which follow depend on understanding it.

A component’s state is a logical value which indicates whether or not that component has a value or is available for use. If a component’s state is .TRUE., then the component is said to be defined or in a defined state, whereas if its state is .FALSE., it is undefined or in an undefined state.⁴ The state of any NDF component can be determined from its identifier by specifying the component name in a call to the routine NDF_STATE. For example:

will return a .TRUE. value if the NDF’s variance component is defined, i.e. if there are variance values available in the NDF which could be read into an application and used if required. An attempt to read values from an undefined component can result in an error, although the NDF_ system may take other appropriate action in some circumstances, depending on the component.

In common with most NDF_ routines which take a component name as an input argument, a list of components may also be supplied to NDF_STATE, for example:

In this case, the routine will return the logical “AND” of the values which would have been obtained for each component alone, so in this example a .TRUE. value will be returned via the STATE argument only if all three of the data, variance and label components are available.

5.3 Factors Determining a Component’s State

When an NDF is first created, all its components start out in an undefined state and they become defined only when values have been assigned to them. Note that with the exception of the history component (see §22.3), there is no separate concept of component “creation” in the NDF_ system – i.e. there is no need to “create” a component before assigning a value to it, and a component cannot “exist” without also having a value. The method by which values are assigned depends on the individual component, and is discussed in later sections.

The opposite process, i.e. of resetting a component to become undefined, is more straightforward and is the same for all components. It is performed by the routine NDF_RESET, which takes the name of a component or a list of components in the same way as NDF_STATE. For example:

would reset the state of the three named components, making their values unavailable and therefore effectively erasing them.

5.4 Restrictions on the Data Component’s State

So long as an NDF data structure is accessible to the NDF_ system (i.e. so long as at least one valid NDF identifier still refers to it) the state of its components can be manipulated freely by assigning values and making calls to NDF_RESET. However, when the final identifier referring to an NDF is annulled, that NDF is released from the NDF_ system. At this point, the resulting data structure must be a valid NDF if it is subsequently to be accessed by other applications.

This requires that at least the data component should be in a defined state at this point (all other NDF components are optional, but the data component must be present if the data structure as a whole is to be valid). An error will result if this is not the case, since this probably indicates a programming fault which has resulted in failure to assign values to the data component. However, this error will not result if the NDF_ system does not have the right to modify the data structure (i.e. if it was accessed only for reading) because the fault could not then have been in the current application.