2 Bounds, Dimensions and Pixel Counts

 2.1 The Fortran API
 2.2 The C API

The API for version 2.0 of the ARY system has been changed to allow very large arrays to be handled - that is, arrays that have more elements than can be counted in a single 4-byte integer. This has been achieved in different ways in the C and Fortran interfaces.

2.1 The Fortran API

Routines that have integer arguments that represent either the index of a pixel along a pixel axis or the number of elements in an array now have two APIs - one that supports use with very large arrays and a legacy API that does not (included for the benefit of old code). The “large array” and “legacy” routines have the same names except that the “large array” versions have the character “K” appended to the end. For instance, the legacy API includes ARY_DIM, which returns the number of pixels along each pixel axis of an array:

        INTEGER STATUS
        INTEGER IARY
        INTEGER NDIM
        INTEGER DIM( 3 )
        ...
        CALL ARY\_DIM( IARY, 3, DIM, NDIM, STATUS )

The ‘large array” API includes ARY_DIMK, which behaves exactly like ARY_DIM, but returns the pixel counts in 8 byte integers:

        INTEGER STATUS
        INTEGER IARY
        INTEGER NDIM
        INTEGER*8 DIM( 3 )
        ...
        CALL ARY\_DIMK( IARY, 3, DIM, NDIM, STATUS )

The list of routines for which “K” versions exist is as follows:

2.2 The C API

The C API does not include alternate functions for the two APIS. Instead, all arguments that refer to pixel indices or counts are declared with a special data type of "hdsdim" (defined in include file “star/hds.h”). The particular form of integer corresponding to “hdsdim” is determiend by the version fo the HDS library with which the application is linked. Local variables used to store pixel indices or counts should also be declared with type “hdsdim”:

        Ary *ary;
        int status;
        int ndim;
        hdsdim dim[ 3 ];
        ...
        aryDim( ary, 3, dim, ndim, &status );