In file DDS.h:

class DDS

Holds a DODS Data Descriptor Structure.

Inheritance:


Public Methods

DDS(const string &n = "")
Creates a DDS with the given string for its name
DDS(const DDS &dds)
The DDS copy constructor
void append_constant(BaseType *btp)
Append a constant to the list of constants generated by the constraint expression parser.
bool send(const string &dataset, const string &constraint, FILE *out, bool compressed = true, const string &cgi_ver = DVR)
Sends the data described by the DDS to a client.
void mark_all(bool state)
Mark the member variable #send_p# flags to {\it state}
bool mark(const string &name, bool state)
Mark the #send_p# flag of the named variable to {\it state}
bool check_semantics(bool all = false)
Check member variable semantics.

Public

Dataset Name Accessors
Get and set the dataset's name
string get_dataset_name()
Returns the dataset's name
void set_dataset_name(const string &n)
Sets the dataset name
File Name Accessor
Get and set the dataset's filename
string filename()
Gets the dataset file name
void filename(const string &fn)
Set the dataset's filename
Variable Methods
Methods for manipulating the variables in a DDS.
void add_var(BaseType *bt)
Adds a variable to the DDS
void del_var(const string &n)
Removes a variable from the DDS
var()
Returns a pointer to a variable from the DDS
BaseType* var(const string &n)
Returns a pointer to the named variable
BaseType* var(const char *n)
Returns a pointer to the named variable
BaseType* var(const string &n, btp_stack &s)
Search for for variable {\it n} as above but record all compound type variables which ultimately contain {\it n} on {\it s}
BaseType* var(Pix p)
Returns a pointer to the indicated variable
Pix first_var()
Returns the first variable in the DDS
void next_var(Pix &p)
Increments the DDS variable counter to point at the next variable
int num_var()
Returns the number of variables in the DDS
External Function Accessors
Manipulate the list of external functions.
template void add_function(const string &name, FUNC_T f)
Add a function to the list
void add_function(const string &name, bool_func f)
Add a boolean function to the list
void add_function(const string &name, btp_func f)
Add a BaseType function to the list
void add_function(const string &name, proj_func f)
Add a projection function to the list
bool find_function(const string &name, bool_func *f) const
Find a Boolean function with a given name in the function list
bool find_function(const string &name, btp_func *f) const
Find a BaseType function with a given name in the function list
bool find_function(const string &name, proj_func *f) const
Find a projection function with a given name in the function list
Constraint Expression
Constraint expression manipulators and accessors.
Pix first_clause()
Returns a pointer to the first clause in a parsed constraint expression
void next_clause(Pix &p)
Increments a pointer to indicate the next clause in a parsed constraint expression
Clause& clause(Pix p)
Returns a clause of a parsed constraint expression
bool clause_value(Pix p, const string &dataset)
Returns the value of the indicated clause of a constraint expression
append\_clause()
Adds a clause to a constraint expression
void append_clause(int op, rvalue *arg1, rvalue_list *arg2)
Adds an operator clause to the constraint expression.
void append_clause(bool_func func, rvalue_list *args)
Adds a boolean function clause to the constraint expression.
void append_clause(btp_func func, rvalue_list *args)
Adds a real-valued function clause to the constraint expression.
bool functional_expression()
Does the current constraint expression return a BaseType pointer?
bool boolean_expression()
Does the current constraint expression return a boolean value?
BaseType* eval_function(const string &dataset)
Evaluate a function-valued constraint expression
bool eval_selection(const string &dataset)
Evaluate a boolean-valued constraint expression
parse\_constraint
Parse a constraint expression
bool parse_constraint(const string &constraint, ostream &os = cout, bool server = true)
Parse a constraint expression .
bool parse_constraint(const string &constraint, FILE *out, bool server = true)
Read Methods
Read a DDS from an external source.
bool parse(string fname)
Parse a DDS from a file with the given name
bool parse(int fd)
Parse a DDS from a file indicated by the input file descriptor
bool parse(FILE *in=stdin)
Parse a DDS from a file indicated by the input file descriptor
Print Methods
Creates an ASCII representation of the DDS.
bool print(ostream &os = cout)
Print the entire DDS on the specified output stream
bool print(FILE *out)
Print the entire DDS to the specified file
bool print_constrained(ostream &os = cout)
Print the constrained DDS to the specified file
bool print_constrained(FILE *out)
Print a constrained DDS to the specified file

Documentation

The DODS Data Descriptor Object (DDS) is a data structure used by the DODS software to describe datasets and subsets of those datasets. The DDS may be thought of as the declarations for the data structures that will hold data requested by some DODS client. Part of the job of a DODS server is to build a suitable DDS for a specific dataset and to send it to the client. Depending on the data access API in use, this may involve reading part of the dataset and inferring the DDS. Other APIs may require the server simply to read some ancillary data file with the DDS in it. \label{api:dds} On the server side, in addition to the data declarations, the DDS holds the clauses of any constraint expression that may have accompanied the data request from the DODS client. The DDS object includes methods for modifying the DDS according to the given constraint expression. It also has methods for directly modifying a DDS, and for transmitting it from a server to a client. For the client, the DDS object includes methods for reading the persistent form of the object sent from a server. This includes parsing the ASCII representation of the object and, possibly, reading data received from a server into a data object. Note that the class DDS is used to instantiate both DDS and DataDDS objects. A DDS that is empty (contains no actual data) is used by servers to send structural information to the client. The same DDS can becomes a DataDDS when data values are bound to the variables it defines. For a complete description of the DDS layout and protocol, please refer to {\it The DODS User Guide}. The DDS has an ASCII representation, which is what is transmitted from a DODS server to a client. Here is the DDS representation of an entire dataset containing a time series of worldwide grids of sea surface temperatures: \begin{verbatim} Dataset { Float64 lat[lat = 180]; Float64 lon[lon = 360]; Float64 time[time = 404]; Grid { ARRAY: Int32 sst[time = 404][lat = 180][lon = 360]; MAPS: Float64 time[time = 404]; Float64 lat[lat = 180]; Float64 lon[lon = 360]; } sst; } weekly; \end{verbatim} If the data request to this dataset includes a constraint expression, the corresponding DDS might be different. For example, if the request was only for northern hemisphere data at a specific time, the above DDS might be modified to appear like this: \begin{verbatim} Dataset { Grid { ARRAY: Int32 sst[time = 1][lat = 90][lon = 360]; MAPS: Float64 time[time = 1]; Float64 lat[lat = 90]; Float64 lon[lon = 360]; } sst; } weekly; \end{verbatim} Since the constraint has narrowed the area of interest, the range of latitude values has been halved, and there is only one time value in the returned array. Note that the simple arrays (#lat#, #lon#, and #time#) described in the dataset are also part of the #sst# Grid object. They can be requested by themselves or as part of that larger object. See the {\it The DODS User Guide}, or the documentation of the BaseType class for descriptions of the DODS data types.
DDS(const string &n = "")
Creates a DDS with the given string for its name

DDS(const DDS &dds)
The DDS copy constructor

Dataset Name Accessors
Get and set the dataset's name. This is the name of the dataset itself, and is not to be confused with the name of the file or disk on which it is stored.

string get_dataset_name()
Returns the dataset's name

void set_dataset_name(const string &n)
Sets the dataset name

File Name Accessor
Get and set the dataset's filename. This is the physical location on a disk where the dataset exists. The dataset name is simply a title.
See Also:
Dataset Name Accessors

string filename()
Gets the dataset file name

void filename(const string &fn)
Set the dataset's filename

Variable Methods
Methods for manipulating the variables in a DDS.

void add_var(BaseType *bt)
Adds a variable to the DDS

void del_var(const string &n)
Removes a variable from the DDS

var()
Returns a pointer to a variable from the DDS.

BaseType* var(const string &n)
Returns a pointer to the named variable. If the name contains one or more field separators then the function looks for a variable whose name matches exactly. If the name contains no field separators then the mfunc looks first in the top level and then in all subsequent levels and returns the first occurrence found. In general, this function searches constructor types in the order in which they appear in the DDS, but there is no requirement that it do so. \note{If a dataset contains two constructor types which have field names that are the same (say point.x and pair.x) you should always use fully qualified names to get each of those variables.}
Returns:
A pointer to the variable or null if not found.

BaseType* var(const char *n)
Returns a pointer to the named variable
Returns:
A pointer to the variable or null if not found.

BaseType* var(const string &n, btp_stack &s)
Search for for variable {\it n} as above but record all compound type variables which ultimately contain {\it n} on {\it s}. This stack can then be used to mark the contained compound-type variables as part of the current projection.
Returns:
A BaseType pointer to the variable {\it n} or 0 if {\it n} could not be found.

BaseType* var(Pix p)
Returns a pointer to the indicated variable

Pix first_var()
Returns the first variable in the DDS

void next_var(Pix &p)
Increments the DDS variable counter to point at the next variable

int num_var()
Returns the number of variables in the DDS

External Function Accessors
Each DDS carries with it a list of external functions it can use to evaluate a constraint expression. If a constraint contains any of these functions, the entries in the list allow the parser to evaluate it. The functions are of two types: those that return boolean values, and those that return real (also called BaseType) values. These methods are used to manipulate this list of known external functions.

template void add_function(const string &name, FUNC_T f)
Add a function to the list

void add_function(const string &name, bool_func f)
Add a boolean function to the list

void add_function(const string &name, btp_func f)
Add a BaseType function to the list

void add_function(const string &name, proj_func f)
Add a projection function to the list

bool find_function(const string &name, bool_func *f) const
Find a Boolean function with a given name in the function list

bool find_function(const string &name, btp_func *f) const
Find a BaseType function with a given name in the function list

bool find_function(const string &name, proj_func *f) const
Find a projection function with a given name in the function list

Constraint Expression
These member functions are used to access and manipulate the constraint expression that may be part of a DDS. Most of them are only used by the constraint expression parser. Refer to {\it The DODS User Manual} for a complete description of constraint expressions.
See Also:
Clause

Pix first_clause()
Returns a pointer to the first clause in a parsed constraint expression

void next_clause(Pix &p)
Increments a pointer to indicate the next clause in a parsed constraint expression

Clause& clause(Pix p)
Returns a clause of a parsed constraint expression

bool clause_value(Pix p, const string &dataset)
Returns the value of the indicated clause of a constraint expression

append\_clause()
Adds a clause to a constraint expression.

void append_clause(int op, rvalue *arg1, rvalue_list *arg2)
This function adds an operator clause to the constraint expression.
Parameters:
op - An integer indicating the operator in use. These values are generated by {\tt bison}.
arg1 - A pointer to the argument on the left side of the operator.
arg2 - A pointer to a list of the arguments on the right side of the operator.

void append_clause(bool_func func, rvalue_list *args)
This function adds a boolean function clause to the constraint expression.
Parameters:
func - A pointer to a boolean function from the list of supported functions.
args - A list of arguments to that function.
See Also:
External Function Accessors

void append_clause(btp_func func, rvalue_list *args)
This function adds a real-valued (BaseType) function clause to the constraint expression.
Parameters:
func - A pointer to a boolean function from the list of supported functions.
args - A list of arguments to that function.
See Also:
External Function Accessors

bool functional_expression()
Does the current constraint expression return a BaseType pointer?

bool boolean_expression()
Does the current constraint expression return a boolean value?

BaseType* eval_function(const string &dataset)
Evaluate a function-valued constraint expression

bool eval_selection(const string &dataset)
Evaluate a boolean-valued constraint expression

parse\_constraint
Parse a constraint expression.

bool parse_constraint(const string &constraint, ostream &os = cout, bool server = true)
Parse the constraint expression given the current DDS.
Returns:
Returns true if the constraint expression parses without error, otherwise false.
Parameters:
constraint - A string containing the constraint expression.
os - The output stream on which to write error objects and messages.
server - If true, send errors back to client instead of displaying errors on the default output stream.

bool parse_constraint(const string &constraint, FILE *out, bool server = true)
Parameters:
out - A FILE pointer to which error objects should be wrtten.

void append_constant(BaseType *btp)
The DDS maintains a list of BaseType pointers for all the constants that the constraint expression parser generates. These objects are deleted by the DDS destructor. Note that there are no list accessors; these constants are never accessed from the list. The list is simply a convenient way to make sure the constants are disposed of properly.

Read Methods
Read a DDS from a file. This method calls a generated parser, #ddsparse()#, to interpret an ASCII representation of a DDS, and regenerate that DDS in memory.
See Also:
Print Methods

bool parse(string fname)
Parse a DDS from a file with the given name

bool parse(int fd)
Parse a DDS from a file indicated by the input file descriptor

bool parse(FILE *in=stdin)
Parse a DDS from a file indicated by the input file descriptor

Print Methods
These methods create an ASCII representation of the DDS. This is the form in which the DDS is transmitted to the client process. A DDS can be output entire, or subject to the constraint of a constraint expression. In most cases, a constrained DDS will be smaller than the original, since the purpose of the expression is to discard some of the data in the dataset.
See Also:
Read Methods

bool print(ostream &os = cout)
Print the entire DDS on the specified output stream

bool print(FILE *out)
Print the entire DDS to the specified file

bool print_constrained(ostream &os = cout)
Print the constrained DDS to the specified file

bool print_constrained(FILE *out)
Print a constrained DDS to the specified file

bool send(const string &dataset, const string &constraint, FILE *out, bool compressed = true, const string &cgi_ver = DVR)
This function sends the variables described in the constrained DDS to the output described by the FILE pointer. This function calls #parse_constraint()#, #BaseType::read()#, and #BaseType::serialize()#.
Returns:
True if successful.
Parameters:
dataset - The name of the dataset to send.
constraint - A string containing the entire constraint expression received in the original data request.
out - A pointer to the output buffer for the data.
compressed - If true, send compressed data.
cgi_ver - version information from the caller that identifies the server sending data.
See Also:
parse_constraint
BaseType::read
BaseType::serialize

void mark_all(bool state)
Mark the member variable #send_p# flags to {\it state}

bool mark(const string &name, bool state)
Mark the #send_p# flag of the named variable to {\it state}

bool check_semantics(bool all = false)
Check the semantics of each of the variables represented in the DDS.
Returns:
True if all the members are correct.
Parameters:
all - If true, recursively check the individual members of compound variables.
See Also:
BaseType::check_semantics


Direct child classes:
DataDDS
See Also:
BaseType
DAS

alphabetic index hierarchy of classes


generated by doc++