next up previous 193
Next: gsdInqSize - Inquire array size
Up: Routine Descriptions
Previous: gsdGet0<t> - Get a scalar value from a GSD file


gsdGet1<t> - Get an array from a GSD file

Description:
This routine returns the value of a scalar GSD item. The item must be specified by the file desciptor, item descriptor array, data array and item number.

<t> <type> Fortran GSD
b char byte byte
l char logical*1 logical
w short integer*2 word
i int integer*4 integer
r float real*4 real
d double real*8 double
c char[16] character*16 char

This routine does not convert between types. If the type of the GSD item does not match the type of the routine, then it returns with an error.

It is possible to get only part of the array. Although the part can be specified in terms of an N-dimensional array, this routine does not take a proper N-D section of the array. The caller can specify the start pixel in N dimensions and the end pixel in N dimensions. These two pixels will be converted to memory locations and all memory between the two is returned. This emulates the old GSD library. It is useful really only for parts of 1-D arrays, parts of rows, or single pixels.


Invocation:
int gsdGet1{blwird}( void *file_dsc, void *item_dsc, char *data_ptr, int itemno, int ndims, int *dimvals, int *start, int *end, <type> *values, int *actvals );

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 ndims (Given)
The dimensionality the calling routine uses to specify the start and end elements.
int *dimvals (Given)
The array of ndims dimensions (array sizes along each axis).
int *start (Given)
The array indices for the first element.
int *end
The array indices for the last element.
<type> *value (Returned)
The data values. The calling routine must make sure that sufficient memory is provided. Thus it must find out the data type and array size before calling this routine. If the data type is character, then the routine returns a byte buffer with all strings concatenated. There are no string terminators in the buffer and there is none at the end. Each string is 16 byte long and immediately followed by the next string.
int *actvals (Returned)
The number of array values returned. This saves the caller to work out how many array elements correspond to start and end given the dimvals.

Returned Value:

int gsdGet1<t>();
Status.

1:
Failure to read the item values.

2:
Numbered item cannot be found.

4:
Given start and end are inconsistent.

0:
Otherwise.


Prototype
available via #include "gsd.h"
Copyright
Copyright (C) 1986-1999 Particle Physics and Astronomy Research Council. All Rights Reserved.


next up previous 193
Next: gsdInqSize - Inquire array size
Up: Routine Descriptions
Previous: gsdGet0<t> - Get a scalar value 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