gsdInqSize - Inquire array size

Description:

This routine returns information about the specified array. Returned are the names and units of each dimension, the size along each dimension, and the overall size.

Invocation:

int gsdInqSize( void $*$file_dsc, void $*$item_dsc, char $*$data_ptr, int itemno, int maxdims, char $*$$*$dimnames, char $*$$*$dimunits, int $*$dimvals, int $*$actdims, int $*$size );

Arguments:

void $*$file_dsc (Given)

The GSD file descriptor.

void $*$item_dsc (Given)

The array of GSD item descriptors related to the GSD file.

char $*$data_ptr (Given)

The buffer with all the data from the GSD file.

int itemno (Given)

The number of the item in the GSD file.

int maxdims (Given)

The number of dimensions required and accommodated by the calling routine.

char $*$$*$dimnames (Returned)

The names for each dimension. The calling routine must provide maxdims pointers to strings. It must also provide the space for the strings, 16 bytes. See Notes for how to declare and pass dimnames.

char $*$$*$dimunits (Returned)

The units for each dimension. The calling routine must provide maxdims pointers to strings. It must also provide the space for the strings, 11 bytes. See Notes for how to declare and pass dimunits.

int $*$dimvals (Returned)

The values for each dimension. The calling routine must provide an array of maxdims integers. This would probably be declared as int dimvals[MAXDIMS];

int $*$actdims (Returned)

The actual number of dimensions. If actdims is less than maxdims, then only actims elements are returned in dimnames, dimunits, dimvals. Further elements declared by the caller are unchanged by this routine.

int $*$size (Returned)

The total number of elements in the array.

Returned Value:

int gsdInqSize();

Status.

1:

Failed to get a dimension value and name.

2:

Numbered item does not exist.

3:

Array has more dimensions than accommodated by calling routine.

0:

Otherwise.

Prototype

available via #include "gsd.h"

Note

The calling routine will probably allocate storage for dimension names by declaring a two-dimensional array. That is not suitable for passing to this routine though. The pointers to each string must be copied into an array of pointers. For example:

char actual_space[MAXDIMS][16];
char $*$pointr_array[MAXDIMS];
for ( i = 0; i $<$ MAXDIMS; i$++$ ) pointr_array[i] = actual_space[i];
status = gsdInqSize( ..., pointr_array, ... );

The reason why this call works but passing actual_space does not work, is that gsdInqSize uses the given value as a char $*$$*$. So in this routine given[1] goes forward in memory by the size of a char $*$ or the number of bytes needed to store a pointer. actual_space would need a step in memory by 16 bytes, i.e. the distance from one string to the next. The main routine knows about this, because it declared actual_space _and_ pointr_array.

Copyright

Copyright (C) 1986-1999 Particle Physics and Astronomy Research Council. All Rights Reserved.