VDS_SELECT_VARS(3)
NAME
vds_select
SYNOPSIS
#include <soi_vds.h>
SDS *vds_select (VDS *vds, int var_number,
int recStart, int recCount, int recIn-
terval,
int *indices, int *counts, int *inter-
vals);
SDS *vds_select_hdr (VDS *vds, int var_number, int
rec_number);
SDS *vds_select_rec (VDS *vds, int var_number, int
rec_number);
SDS *vds_select_drec(VDS *vds, int var_number, int
rec_number);
SDS *vds_select_frec(VDS *vds, int var_number, int
rec_number);
SDS *VDS_select_hdr (VDS *vds, int var_number, int
rec_number);
SDS *VDS_select_rec (VDS *vds, int var_number, int
rec_number);
SDS *VDS_select_drec(VDS *vds, int var_number, int
rec_number);
SDS *VDS_select_frec(VDS *vds, int var_number, int
rec_number);
SDS *vds_select_vars (VDS *vds, int n_vars, int
*var_numbers);
DESCRIPTION
This set of functions gives users access to data in a vir-
tual dataset (vds). If the data which is requested is not
in memory it is read at this time. All of these select
functions return pointers to SDS data structures which can
then be manipulated using operations from the sds library.
In general, functions beginning with (lower case) vds return
pointers to copies of structures and those beginning with
(upper case) VDS return pointers to structures which belong
to the vds structure. Calling VDS_select functions saves
time and space but improper use of the pointer can damage
the vds structure and cause subsequent vds operations on the
vds to fail in unpredictable ways. Do not free pointers
returned by VDS_select functions. Pointers returned by
vds_select functions should be freed by the user by a call
to sds_free.
The argument vds in all the select functions is a pointer to
a vds data structure which has been returned from a success-
ful call to vds_open.
The syntax of vds_select is copied directly from the CDF
hyperget function call.
var_number is the index of the variable to be selected.
recStart is the first record number.
recCount is the number of records to be selected.
recInterval is the interval between selected records.
indices is an array of starting indices along each
axis.
counts is the array of number of values to read along
each axis.
intervals is the array of values to skip along each
axis.
vds_select_hdr and VDS_select_hdr return pointers to SDS
structures which contain dimension and attribute information
but do not contain data.
vds_select_rec and VDS_select_rec return pointers to SDS
structures which contain the data for the vds record speci-
fied by rec_number.
vds_select_frec, vds_select_drec (and the corresponding
VDS_select functions) return pointers to SDS structures
which contain the data for the vds record specified by
rec_number. The data in the SDS structures has been con-
verted to FLOAT or DOUBLE respectively. Do not mix calls to
VDS_select_frec and VDS_select_drec.
RETURN VALUES
The return value is a pointer to the requested sds or NULL
if an error occurred. If the return value is NULL, the glo-
bal soi_errno contains an error code. Error codes are
defined in soi_error.h. The errstk may also contain mes-
sages.
EXAMPLES
There are many examples of the use of vds_select* in
~soi/CM/src/modules/*.c
SEE ALSO
~soi/CM/man/man3/vds.3
~soi/CM/man/man3/errstk.3
~soi/CM/include/soi_error.h
~soi/CM/include/soi_sds.h
FILES
~soi/CM/include/soi_vds.h
~soi/CM/src/libvds.d/vds_select.c
BUGS
RESTRICTIONS
Internal data protocol types which are supported are
VDS_FILE, VDS_CUBE, and VDS_FILES.
multi variables are not supported so var_number must be 0.
recStart in vds_select must be 0. recInterval in vds_select
must be 1. all intervals values in vds_select must be 1.
vds_select_vars is not implemented.
PLANNED IMPROVEMENTS