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.