VDS_SELECT_FREC(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