In file Connect.h:

class Connect

Holds information about the link from a DODS client to a dataset.

Public Methods

Connect(string name, bool www_verbose_errors = false, bool accept_deflate = true)
Create an instance of Connect.
Connect(const Connect ©_from)
The Connect copy construtor
bool get_www_errors_to_stderr()
Gets the state of the #www_errors_to_stderr# property
void set_www_errors_to_stderr(bool state)
Sets the #www_errors_To_stderr# property
string get_accept_types()
Gets the current string of `accepted types'
void set_accept_types(const string &types)
Sets the list of accepted types
bool fetch_url(string &url, bool async = false)
Dereference a URL.
FILE* output()
Access the information contained in this Connect instance.
XDR* source()
Access the XDR input stream (source) for this connection.
bool is_local()
Does this object refer to a local file?
string URL(bool CE = true)
Get the object's URL.
string CE()
Get the Connect's constraint expression.
ObjectType type()
What type is the most recent object sent from the server?
EncodingType encoding()
What type of encoding was used on the data in the stream?
string server_version()
Returns a string containing the version of DODS used by the server
DAS& das()
Return a reference to the Connect's DAS object.
DDS& dds()
Return a reference to the Connect's DDS object.
Error& error()
Get a reference to the last error.
Gui* gui()
Returns a pointer to a Gui object.
bool request_das(bool gui = false, const string &ext = "das")
Get the DAS from a server.
bool request_dds(bool gui = false, const string &ext = "dds")
Get the DDS from a server.
DDS* request_data(string expr, bool gui = false, bool async = false, const string &ext = "dods")
Reads data from the Connect object's server
DDS* read_data(FILE *data_source, bool gui = false, bool async = false)
This function reads cached data from a disk file

Documentation

Connect objects are used as containers for information pertaining to the connection a user program makes to a dataset. The dataset may be either local (for example, a file on the user's own computer) or a remote dataset. In the latter case a DODS URL will be used to reference the dataset, instead of a filename. Connect contains methods which can be used to read the DODS DAS and DDS objects from the remote dataset as well as reading data. The class understands in a rudimentary way how DODS constraint expressions are formed and how to manage them. Connect also provides additional services such as automatic decompression of compressed data, transmission progress reports and error processing. Refer to the Gui and Error classes for more information about these features. See the DODSFilter class for information on servers that compress data. The Connect class must be specialized for each different. client-library. Connect is only used on the client-side of a DODS client-server connection. The Connect class contains a linked list of #constraint# objects. These are simple C structures containing a constraint expression and a DDS object. The DDS object contains data received from the server, and the accompanying constraint expression was a part of the data request. To support multiple connections to a single DODS server, you can use either one Connect object with many entries in the #constraint# list, or multiple Connect objects.
Connect(string name, bool www_verbose_errors = false, bool accept_deflate = true)
The Connect constructor requires a #name#, which is the URL to which the connection is to be made. You can specify that you want to see the #verbose# form of any WWW library errors. This can be useful for debugging. The default is to suppress these errors. Callers can use the #accept_deflate# parameter to request that servers are told the client (caller of Connect ctor) \em{can} process return documents that are compressed with gzip.

Connect(const Connect ©_from)
The Connect copy construtor

bool get_www_errors_to_stderr()
Gets the state of the #www_errors_to_stderr# property. If TRUE this means that http errors will be printed to stderr in addition to being reported in the Error object. If FALSE only the Error object will be used.
Returns:
TRUE if WWW errors should got to stderr, FALSE if only the Error object should be used.

void set_www_errors_to_stderr(bool state)
Sets the #www_errors_To_stderr# property.
Parameters:
state - The state of the property.
See Also:
is_www_errors_to_stderr

string get_accept_types()
Gets the current string of `accepted types'. This string lists all of the DODS datatypes that the client can grok.
Returns:
A string listing the types this client declares to servers it can understand.
See Also:
set_accepted_types

void set_accept_types(const string &types)
Sets the list of accepted types. This string is meant to list all of the DODS datatypes that the client can grok and is sent to the server using the XDODS-Accept-Types MIME header. The server will try to only send back to the client datatypes that are listed. If the value of this header is `All', then the server assumes that the client can process all of the DODS datatypes. If only one or two types are \emph{not} understood, then they can be listed, each one prefixed by `!'. Thus, if a client does not understand `Sequences', it could set types to `!Sequences' as opposed to listing all of the DODS datatypes. Multiple values are separated by commas (,). Not all servers will honor this and some requests may not be possible to express with a very limited set of datatypes. NB: By default, the value `All' is used.
Parameters:
types - The string listing datatypes understood by this client.

bool fetch_url(string &url, bool async = false)
Fetch the contents of the indicated URL and put its contents into an output file. A pointer to this file can be retrieved with the #output()# function. If {\it async} is true, then the operation is asynchronous, and the function returns before the data transfer is complete. Note that the asynchronous transfer feature of DODS is not currently enabled. All invocations of this function will be synchronous, no matter what the value of the {\it async} parameter.
Returns:
Returns false if an error is detected, otherwise returns true.
Parameters:
url - A string containing the URL to be dereferenced. The data referred to by this URL will wind up available through a file pointer retrieved from the #output()# function.
async - If true, the read operation will proceed asynchronously. In other words, the function may return before the read is complete.
See Also:
Connect::output

FILE* output()
Returns a file pointer which can be used to read the data fetched from a URL. Note that occasionally this may be directed to #stdout#. If this is the case, users should avoid closing it.
Returns:
A #(FILE *)# indicating a file containing the data received from a dereferenced URL.
See Also:
Connect::fetch_url

XDR* source()
The data retrieved from a remote DODS server will be in XDR format. Use this function to initialize an XDR decoder for that data and to return an XDR pointer to the data.
Returns:
Returns a XDR pointer tied to the current output stream.
See Also:
Connect::output

bool is_local()
The Connect class can be used for ``connections'' to local files. This means that local files can continue to be accessed with a DODS-compliant API.
Returns:
Return TRUE if the Connect object refers to a local file, otherwise returns FALSE.

string URL(bool CE = true)
Return the Connect object's URL in a string. The URL was set by the class constructor, and may not be reset. If you want to open another URL, you must create another Connect object. There is a Connections class created to handle the management of multiple Connect objects.
Returns:
A string containing the URL of the data to which the Connect object refers. If the object refers to local data, the function returns the null string.
Parameters:
CE - If TRUE, the returned URL will include any constraint expression enclosed with the Connect object's URL (including the #?#). If FALSE, any constraint expression will be removed from the URL. The default is TRUE.
See Also:
Connections

string CE()
Return the constraint expression (CE) part of the Connect URL. Note that this CE is supplied as part of the URL passed to the Connect's constructor. It is not the CE passed to the #request_data()# function.
Returns:
A string containing the constraint expression (if any) submitted to the Connect object's constructor.

ObjectType type()
During the parse of the message headers returned from the dereferenced URL, the object type is set. Use this function to read that type information. This will be valid {\it before} the return object is completely parsed so it can be used to decide which parser to call to read the data remaining in the input stream. The object types are Data, DAS, DDS, Error, and undefined.
Returns:
The type of the object.
See Also:
ObjectType

EncodingType encoding()
During the parse of the message headers returned from the dereferenced URL, the encoding type is set. Use this function to read that type information. This will be valid {\it before} the return object is completely parsed so it can be used to decide which decoder to call (if any) to read the data remaining in the input stream. The encoding types are currently limited to x-plain (no special decoding required) and x-gzip (compressed using GNU's gzip).
Returns:
The type of the compression.
See Also:
EncodingType

string server_version()
Returns a string containing the version of DODS used by the server

DAS& das()
All DODS datasets define a Data Attribute Structure (DAS), to hold a variety of information about the variables in a dataset. This function returns the DAS for the dataset indicated by this Connect object.
Returns:
A reference to the DAS object.
See Also:
DAS

DDS& dds()
All DODS datasets define a Data Descriptor Structure (DDS), to hold the data type of each of the variables in a dataset. This function returns the DDS for the dataset indicated by this Connect object.
Returns:
A reference to the DDS object.
See Also:
DDS

Error& error()
The DODS server uses Error objects to signal error conditions to the client. If an error condition has occurred while fetching a URL, the Connect object will contain an Error object with information about that error. The Error object may also contain a program to run to remedy the error. This function returns the latest Error object received by the Connect object.
Returns:
The last Error object sent from the server. If no error has been sent from the server, returns a reference to an empty error object.
See Also:
Error

Gui* gui()
The DODS client can display graphic information to a user with the DODS Graphical User Interface (GUI). Typically used for a progress indicator, the GUI is simply a shell capable of interpreting arbitrary graphical commands (with tcl/tk). The Gui object is created anew when the Connect object is first created. This function returns a pointer to the Gui object, so you can modify the GUI as desired.
Returns:
a pointer to the Gui object associated with this connection.
See Also:
Gui

bool request_das(bool gui = false, const string &ext = "das")
Reads the DAS corresponding to the dataset in the Connect object's URL.
Returns:
TRUE if the DAS was successfully received. FALSE otherwise.
Parameters:
gui - If TRUE, use the client GUI. Most DAS's are too small to make this worthwhile.
ext - The extension to append to the URL to retrieve the dataset DAS. This parameter is included for compatibility with future versions of the DODS software. It currently defaults to the only possible working value, ``das''.

bool request_dds(bool gui = false, const string &ext = "dds")
Reads the DDS corresponding to the dataset in the Connect object's URL.
Returns:
TRUE if the DDS was successfully received. FALSE otherwise.
Parameters:
gui - If TRUE, use the client GUI. Most DDS's are too small to make this worthwhile.
ext - The extension to append to the URL to retrieve the dataset DDS. This parameter is included for compatibility with future versions of the DODS software. It currently defaults to the only possible working value, ``dds''.

DDS* request_data(string expr, bool gui = false, bool async = false, const string &ext = "dods")
Reads data from the Connect object's server. This function sets up the BaseType variables in a DDS, and sends a request using #fetch_url()#. Upon return, it caches the data on a disk, then unpacks it into the DDS storage.
Returns:
A reference to the DataDDS object which contains the variables (BaseType pointers) generated from the DDS sent with the data. These variables are guaranteed to be large enough to hold the data, even if the constraint expression changed the type of the variable from that which appeared in the original DDS received from the dataset when this connection was made.
Parameters:
expr - A string containign a constraint expression. The function adds the clauses of this constraint expression to the Connect object's original CE. If the constraint expression contains one or more Sequences, these must be the {\it last} objects specified in the projection clause. If you request N variables and M of them are Sequences, all the M sequences must follow the N-M other variables.
gui - If this is TRUE, use the DODS client GUI. See the Gui class for a description of this feature.
async - If this is TRUE, this function reads data asynchronously, returning before the read completes. Synchronous reads are the default, and the only possible action as of DODS version 2.15.
ext - The extension to append to the URL to retrieve the dataset data. This parameter is included for compatibility with future versions of the DODS software. It currently defaults to the only possible working value, ``dods''.
See Also:
DataDDS
Gui

DDS* read_data(FILE *data_source, bool gui = false, bool async = false)
This function reads cached data from a disk file.
Returns:
A reference to the DataDDS object which contains the variables (BaseType pointers) generated from the DDS sent with the data.
Parameters:
gui - If this is TRUE, use the DODS client GUI. See the Gui class for a description of this feature.
async - If this is TRUE, this function reads data asynchronously, returning before the read completes. Synchronous reads are the default, and the only possible action as of DODS version 2.15.
ext - The extension to append to the URL to retrieve the dataset data. This parameter is included for compatibility with future versions of the DODS software. It currently defaults to the only possible working value, ``dods''.
See Also:
DataDDS
Gui


This class has no child classes.
Author:
jhrg
See Also:
DDS
DAS
DODSFilter
Error
Gui

alphabetic index hierarchy of classes


generated by doc++