VDS_OPEN(3)



NAME

     vds_open



     SYNOPSIS
          #include <soi_vds.h>

          VDS *vds_open (KEY *keylist, char *root_key);



     DESCRIPTION

     This function creates a vds data structure to  be  used  for
     reading  or  appending  to an external dataset.  The keylist
     argument must contain the results of parsing a dataset  name
     with the root_key.  Keylists passed to strategy modules meet
     this requirement.

     vds_open calls vds_create_std to  partially  initialize  the
     vds  structure,  including  determing  the  directory of the
     external dataset and initializing the global  attributes  of
     the  dataset  by reading the overview file if one exists. It
     calls vds_conform_type to determine the conformance type  of
     the  dataset  which  depends on the global "CONFORMS" attri-
     bute. Conformance types are enumerated in soi_vds.h and some
     examples  are VDS_NO_PROTOCOL, VDS_FITS, and VDS_FITS_MERGE.
     vds_open then  determines  whether  the  dataset  is  stored
     externally  in  a  single fits file (named explicitly in the
     input arguments), a directory (without an overview file), or
     is a conforming dataset.

     If the dataset is conforming, all per record information  is
     initialized from the info file (*record.rdb). If the dataset
     is stored externally in  a  directory  without  an  overview
     file,  find_vds_info  examines  the  directory  and tries to
     deduce from the file names the external structure. If a sin-
     gle  fits  file  was named explicitly as the input argument,
     the per record information is taken from  the  fits  header,
     even if an info file exists.

     NOTE: Specifying a single fits file is useful for some test-
     ing  but  to process a single file from a conforming dataset
     using  the  per  record  information  from  the  info   file
     (*record.rdb)  use  the  datset  names  selection  mechanism
     rather than just naming the file. For  example,  to  process
     foo.0033.fits      specify      dataset_name,sel:[33]     or
     your_directory/[33] see the module man page for more detail.

     When  the   function   has   completed   successfully,   the
     vds_pointer,  vds_extern_type, vds_intern_type, last_record,
     and state are initialized and  the  vds  is  ready  for  vds
     select  operations.   If the external dataset is stored in a
     single file, the filename is set.  No data  has  been  read.
     The  mode  is  VDS_READ.  (To append to an external dataset,
     the mode must be changed to VDS_APPEND  after  vds_open  has
     completed successfully).



     RETURN VALUES

     The return value is a pointer to the created vds or NULL  if
     an  error occurred.  If the return value is NULL, the global
     soi_errno contains an error code. Error codes are defined in
     soi_error.h.  The errstk may also contain messages.



     EXAMPLES

     There  many   examples   of   the   use   of   vds_open   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



     FILES

     ~soi/CM/include/soi_vds.h
     ~soi/CM/src/libvds.d/vds_open.c



     BUGS




     RESTRICTIONS

     The only supported external protocol types are VDS_FITS  and
     VDS_FITS_MERGE.   The only supported internal protocol types
     are VDS_FILE and VDS_FILES.



     PLANNED IMPROVEMENTS