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