In file DODSFilter.h:

class DODSFilter

Common functions for DODS server filter programs.

Public Methods

DODSFilter(int argc, char *argv[])
DODSFilter constructor.
bool OK()
Check whether the DODSFilter was initialized with valid arguments.
bool version()
Should the filter send version information to the client program?
string get_cgi_version()
Return the version information passed to the instance when it was created
string get_ce()
Get the constraint expression.
string get_dataset_name()
Get the dataset name.
virtual string get_dataset_version()
Get the version information for the dataset.
virtual string get_cache_dir()
Get the cache directory.
string get_accept_types()
Get the list of accepted datatypes sent by the client
bool read_ancillary_das(DAS &das, string anc_location = "")
Test if ancillary data must be read.
bool read_ancillary_dds(DDS &dds, string anc_location = "")
Test if ancillary data must be read.
void print_usage()
Print usage information for a filter program.
void send_version_info()
Send version information back to the client program.
bool send_das(DAS &das)
Transmit a DAS.
bool send_dds(DDS &dds, bool constrained = false)
Transmit a DDS.
bool send_data(DDS &dds, FILE *data_stream)
Transmit data.

Documentation

When a DODS server receives a request from a DODS client, the server CGI script dispatches the request to one of several ``filter'' programs. Each filter is responsible for returning a different aspect of the dataset information: one is for data, one is for the dataset DDS, one is for the dataset DAS, and a fourth is for a usage message describing the server itself. Some installations may have additional optional filters. The filter program receives a data request from the dispatch script. It receives its operating parameters from the command line, like any UNIX command, and it returns its output to standard output, which the httpd server packages up into a reply to the client. This class contains some common functions for the filter programs used to make up the DODS data servers. The filter programs do not {\it have} to be called by a CGI program, but that is the normal mechanism by which they are invoked.
DODSFilter(int argc, char *argv[])
Create an instance of DODSFilter using the command line arguments passed by the CGI (or other) program. The default constructor is private; this and the copy constructor (which is just the default constructor) are the only way to create an instance of DODSFilter. These are the valid options: \begin{description} \item[{\it filename}] The name of the file on which the filter is to operate. Usually this would be the file whose data has been requested. \item[#-c#] Send compressed data. Data are compressed using the deflate program. The W3C's libwww will recognize this and automatically decompress these data. \item[#-e# {\it expression}] This option specifies a non-blank constraint expression used to subsample a dataset. \item[#-v# {\it cgi-version}] Specifies that this request is just for version information. The {\it cgi-version} is the version of the CGI (i.e., server). \item[#-V#] When given set the #version request# flag to TRUE. Servers should check this flag with the #version()# mfunc and call #send_version_info()# if it is TRUE. Note that -v used to be used for this, but -v is now used to pass into the server from the CGI the server's version number. \item[#-d# {\it ancdir}] Specifies that ancillary data be sought in the {\it ancdir} directory. \item[#-f# {\it ancfile}] Specifies that ancillary data may be found in a file called {\it ancfile}. \item[#-t# {\it list of types}] Specifies a list of types accepted by the client. This information is passed to a server by a client using the XDODS-Accept-Types header. The comma separated list contains each type the client can understand \emph{or}, each type the client does \emph{not} understand. In the latter case the type names are prefixed by a {\tt !}. If the list contains only the keyword `All', then the client is declaring that it can understand all DODS types. \end{description}

bool OK()
Use this function to test whether the options passed via argc and argv are valid.
Returns:
True if the class state is OK, false otherwise.

bool version()
Use this function to check whether the client requested version information. In addition to returning version information about the DODS software, the server can also provide version information about the dataset itself.
Returns:
TRUE if the -v option was given indicating that the filter should send version information back to the client, FALSE otherwise.
See Also:
DODSFilter::send_version_info

string get_cgi_version()
Return the version information passed to the instance when it was created. This string is passed to the DODSFilter ctor using the -v option.
Returns:
The version string supplied at initialization.

string get_ce()
Return the entire constraint expression in a string. This includes both the projection and selection clauses, but not the question mark.
Returns:
A string object that contains the constraint expression.

string get_dataset_name()
The ``dataset name'' is the filename or other string that the filter program will use to access the data. In some cases this will indicate a disk file containing the data. In others, it may represent a database query or some other exotic data access method.
Returns:
A string object that contains the name of the dataset.

virtual string get_dataset_version()
To read version information that is specific to a certain dataset, override this method with an implementation that does what you want. By default, this returns an empty string.
Returns:
A string object that contains the dataset version information.

virtual string get_cache_dir()
The #cache_dir# is used to hold the cached .dds and .das files. By default, this returns an empty string (store cache files in current directory.
Returns:
A string object that contains the cache file directory.

string get_accept_types()
Get the list of accepted datatypes sent by the client. If no list was sent, return the string `All'. NB: The funny spelling `accept types' instead of `accepted types' mirrors the name of the HTTP request header field name which in turn mirrors the common practice of using `accept' over `accepted'.
Returns:
A string containing a list of the accepted types.
See Also:
DODSFilter

bool read_ancillary_das(DAS &das, string anc_location = "")
Read the ancillary DAS information and merge it into the input DAS object.
Returns:
TRUE if an ancillary DAS was found, FALSE otherwise.
Parameters:
das - A DAS object that will be augmented with the ancillary data attributes.
See Also:
DAS

bool read_ancillary_dds(DDS &dds, string anc_location = "")
Read the ancillary DDS information and merge it into the input DDS object.
Returns:
TRUE if an ancillary DDS was found, FALSE otherwise.
Parameters:
dds - A DDS object that will be augmented with the ancillary data properties.
See Also:
DDS

void print_usage()
This message is printed when the filter program is incorrectly invoked by the dispatch CGI. This is an error in the server installation or the CGI implementation, so the error message is written to stderr instead of stdout. A server's stderr messages show up in the httpd log file. In addition, an error object is sent back to the client program telling them that the server is broken.

void send_version_info()
This function formats and sends to stdout version information from the httpd server, the server dispatch scripts, the DODS core software, and (optionally) the dataset.

bool send_das(DAS &das)
This function formats and prints an ASCII representation of a DAS on stdout. This has the effect of sending the DAS object back to the client program.
Returns:
TRUE if the operation succeeded, FALSE otherwise. If the send fails, an error object may still be sent.
Parameters:
das - The DAS object to be sent.
See Also:
DAS

bool send_dds(DDS &dds, bool constrained = false)
This function formats and prints an ASCII representation of a DDS on stdout. When called by a CGI program, this has the effect of sending a DDS object back to the client program. Either an entire DDS or a constrained DDS may be sent.
Returns:
TRUE if the operation succeeded, FALSE otherwise. If the send fails, an error object may still be sent.
Parameters:
dds - The DDS to send back to a client.
constrained - If this argument is true, evaluate the current constraint expression and send the `constrained DDS' back to the client.
See Also:
DDS

bool send_data(DDS &dds, FILE *data_stream)
Send the data in the DDS object back to the client program. The data is encoded in XDR format, and enclosed in a MIME document which is all sent to stdout. This has the effect of sending it back to the client.
Returns:
TRUE if the operation succeeded, FALSE otherwise. If the send fails, an error object may still be sent.
Parameters:
dds - A DDS object containing the data to be sent.
data_stream - A pointer to the XDR sink into which the data is to be put for encoding and transmission.
See Also:
DDS


This class has no child classes.
Author:
jhrg 8/26/97

alphabetic index hierarchy of classes


generated by doc++