NDF_ZSCAL - Create a compressed copy of an NDF using SCALE compression

Description:

The routine creates a new NDF holding a compressed copy of the supplied NDF. The compression is performed by scaling the DATA and VARIANCE arrays using a simple linear scaling, and then casting the scaled values into the specified data type. The amount of compression, and the amount of information lost, is thus determined by the input and output data types. For instance, if the input NDF is of type _DOUBLE (eight bytes) and the output is of type _WORD (two bytes), the compression ratio for each array component will be four to one.

Invocation:

CALL NDF_ZSCAL( INDF1, TYPE, SCALE, ZERO, PLACE, INDF2, STATUS )

Arguments:

INDF1 = INTEGER (Given)

Identifier for the input NDF.

TYPE = CHARACTER $*$ ( $*$ ) (Given)

Numeric type of the output NDF's DATA component (e.g. '_REAL' or '_INTEGER').

SCALE( 2 ) = DOUBLE PRECISION (Given and Returned)

The scale factors to use when compressing the array components in the supplied NDF. The DATA array will be scaled using SCALE( 1 ) and the VARIANCE array - if present - will be scaled using SCALE( 2 ). If either of these is set to VAL__BADD, then a suitable value will be found automatically by inspecting the supplied array values. The values actually used will be returned on exit. See "Notes:" below. On exit, any supplied values will be rounded to values that can be represented accurately in the data type of the input NDF.

ZERO( 2 ) = DOUBLE PRECISION (Given and Returned)

The zero offsets to use when compressing the array components in the supplied NDF. The DATA array will be offset using ZERO( 1 ) and the VARIANCE array - if present - will be offset using ZERO( 2 ). If either of these is set to VAL__BADD, then a suitable value will be found automatically by inspecting the supplied array values. The values actually used will be returned on exit. See "Notes:" below. On exit, any supplied values will be rounded to values that can be represented accurately in the data type of the input NDF.

PLACE = INTEGER (Given and Returned)

An NDF placeholder (e.g. generated by the NDF_PLACE routine) which indicates the position in the data system where the new NDF will reside. The placeholder is annulled by this routine, and a value of NDF__NOPL will be returned (as defined in the include file NDF_PAR).

INDF2 = INTEGER (Returned)

Identifier for the new NDF.

STATUS = INTEGER (Given and Returned)

The global status.

Notes:

• The compressed data may not be of type _DOUBLE. An error will be reported if TYPE is '_DOUBLE'.

• Only arrays that are stored in SIMPLE or PRIMITIVE form can be compressed. An error is reported if any other storage form is encountered whilst compressing the input NDF.

• The uncompressed array values are obtained by multiplying the compressed values by SCALE and then adding on ZERO.

• The default scale and zero values (used if VAL__BADD values are supplied for SCALE and/or ZERO) are chosen so that the extreme array values will fit into the dynamic range of the output data type, allowing a small safety margin.

• Complex arrays cannot be compressed using this routine. An error will be reported if the input NDF has a complex type, or if "TYPE" represents a complex data type.

• The resulting NDF will be read-only. An error will be reported if an attempt is made to map it for WRITE or UPDATE access.

• When the output NDF is mapped for READ access, uncompression occurs automatically. The pointer returned by NDF_MAP provides access to the uncompressed array values.

• The result of copying a compressed NDF (for instance, using NDF_PROP, etc.) will be an equivalent uncompressed NDF. SCALE( 2 ) = DOUBLE PRECISION (Given)

• When applied to a compressed NDF, the NDF_TYPE and NDF_FTYPE routines return information about the data type of the uncompressed NDF.

• If this routine is called with STATUS set, then a value of NDF__NOID will be returned for the INDF2 argument, although no further processing will occur. The same value will also be returned if the routine should fail for any reason. In either event, the placeholder will still be annulled. The NDF__NOID constant is defined in the include file NDF_PAR.