6 ACCESSING CHARACTER COMPONENTS

The NDF character components, title, label and units, are all accessed through the same set of routines, which are described in this section.

6.1 Reading and Displaying Character Values

The routine NDF_CGET may be used to obtain the values of NDF character components. For instance:

will obtain the value of the label component, if defined, and return it via the VALUE argument. If the component is undefined, then no value will be returned so the default value established before the subroutine call would be used instead.

If the value of a character component is needed as part of a message, then it may be assigned directly to an MSG_ message token using the NDF_CMSG routine. Thus an application might generate a message about the title of an NDF as follows:

Here, ‘TITLE’ is the name of a message token (see SUN/104).

6.2 Writing Character Values

The routine NDF_CPUT may be used to assign new values to character components. For instance:

will assign the value ‘Surface Brightness’ to the label component, overwriting any previous value which this component had. Note that the entire character string (including trailing blanks if present) will be assigned, and the length of the NDF’s character component will be adjusted to match the new value. After a successful call to NDF_CPUT, the character component’s state becomes defined.

It is quite common for an application to obtain a new value for a character component via a parameter and then to store this value in an NDF. The routine NDF_CINP is therefore provided to do this directly. For instance, the following will obtain new values for all three character components via suitable parameters and write the values to an NDF:

The first argument to NDF_CINP specifies the parameter to be used, while the third argument is the name of the NDF character component whose value is to be replaced. If a null parameter value is specified (by the user entering ‘!’ in response to a prompt, for instance), then NDF_CINP will return without action, i.e. without setting a new value for the character component. A suitable default value for the component should therefore be established before NDF_CINP is called.

An example of an ADAM interface file parameter entry suitable for use with NDF_CINP can be found in §A.2.

6.3 Character Component Length

The length of an NDF character component (i.e. the number of characters it contains) is determined by the last assignment made to it, e.g. by NDF_CPUT, and may be obtained using the routine NDF_CLEN. For instance:

will return the number of characters in the units component via the LENGTH argument. If the specified component is undefined, then a value of zero will be returned.

6.4 Resetting Character Components

As described in §5.3, the value of a character component may be reset, thereby causing it to become undefined, by using the routine NDF_RESET. This routine will also accept a list of components. For instance:

will reset all three character components, effectively erasing them.