NDF_XIARY - Obtain access to an array stored in an NDF extension

Description:

The routine locates an array stored in an NDF extension and imports it into the ARY_ system, returning an array identifier for it. If necessary, a section of the array will be selected so that it matches pixel-for-pixel with the main data array of the NDF (or NDF section) supplied. The returned array identifier may be used to manipulate the array using the ARY_ routines (see SUN/11).

Invocation:

CALL NDF_XIARY( INDF, XNAME, CMPT, MODE, IARY, STATUS )

Arguments:

INDF = INTEGER (Given)

NDF identifier.

XNAME = CHARACTER $*$ ( $*$ ) (Given)

Name of the extension.

CMPT = CHARACTER $*$ ( $*$ ) (Given)

Name of the array component within the extension.

MODE = CHARACTER $*$ ( $*$ ) (Given)

Mode of access required: 'READ', 'UPDATE' or 'WRITE'.

IARY = INTEGER (Returned)

Array identifier.

STATUS = INTEGER (Given and Returned)

The global status.

Notes:

• The value given for the CMPT argument may be an HDS path name, consisting of several fields separated by '.', so that an object can be accessed in a sub-component (or a sub-sub-component...) of an NDF extension. Array subscripts may also be included. Thus a string such as 'FILTER(3).FLATFIELD' could be used as a valid CMPT value.

• This routine will normally generate an array section. However, if the input NDF is a base NDF and the requested array has the same pixel-index bounds, then there is no need to generate a section in order to access the required part of the array. In this case, a base array identifier will be issued instead.

• It is the caller's responsibility to annul the ARY_ system identifier returned by this routine (e.g. by calling ARY_ANNUL) when it is no longer required. The NDF_ system will not perform this task itself.

• The array associated with the returned identifier will have the same number of dimensions as the base array from which it is derived. If the input NDF has fewer dimensions than this, then the pixel-index bounds of the extra array dimensions are preserved unchanged. If the NDF has more dimensions, then the extra ones are ignored.

• This routine takes account of the transfer window of the NDF supplied and will restrict the transfer window of the new array section so as not to grant access to regions of the base array which are not accessible in the input NDF.

• If this routine is called with STATUS set, then a value of ARY__NOID will be returned for the IARY argument, although no further processing will occur. The same value will also be returned if the routine should fail for any reason.

• The ARY__NOID constant is defined in the include file ARY_PAR.