next up previous 193
Next: gsdItem - Get GSD item by number
Up: Routine Descriptions
Previous: gsdGet1<t> - Get an array from a GSD file


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.


next up previous 193
Next: gsdItem - Get GSD item by number
Up: Routine Descriptions
Previous: gsdGet1<t> - Get an array from a GSD file

The Global Section Datafile (GSD) access library
Starlink User Note 229
Tim Jenness, Remo Tilanus,
Horst Meyerdierks, Jon Fairclough
16 December 1999
E-mail:ussc@star.rl.ac.uk