=pod

=head1 The Virtual Solar Observatory API

=head2 Purpose

This document will attempt to provide the necessary information for a
programmer to write applications that interact with the Virtual Solar
Observatory (VSO).

We will explain the Application Program Interface (API), and attempt
to provide insight into the design of the VSO in an attempt for
programmers to understand the logic that resulted in the interface.

Programmers should ensure that they are reading the most current
version of this document.  They will also need the corresponding
WSDL document to describe the structure of the messages exchanged 
between clients and the VSO.

=head2 Version

This document describes VSO 0.8, and was last updated 2004/Nov/16.

This document describes the inner communications with VSO, and it is
possible that there may be alternative APIs available that provide
translation sevices or otherwise are less strict in their requirements
on interaction.

=head2 VSO Overview

The VSO is an interconnected system of software to permit consumers to
easily find and request data products of interest. As of this writing,
there are two main functions of the VSO -- finding data products (acting
as an Access Aid), and negotiating for the delivery of data products
(acting as an Ordering Aid).

The architecture of the VSO attempts to place a minimal burden on Data
Providers, by proving abstraction layers to tie into functionality they
already have.  This permits Data Providers to continue to use their
existing delivery mechanisms and data catalogs, without the need for
them to recatalog their data according to a new data model, or
supporting a data transfer mechanism that might not be ideal for their
organization.

Although there many goals and objectives for this project, the API and
general architecture of the VSO is primarily driven by the following
requirements:

=over 4

=item *

The system should be able to adapt to changes in the data model.

=item *

The system should require a minimum of maintenance.

=item *

The system should not place an undue burden on Data Providers who wish
to join the project.

=item *

The system should be extensible by data providers who wish to provide
additional services beyond those supported by VSO.

=item *

The system should allow solar researchers to do their job more
efficiently and effectively.

=back

=head2 Design of the VSO

The VSO has been designed in such a way as to make it possible for there
to be any number of User Interfaces which may serve the wide community,
or be specifically tailored to serve a niche group.  For sake of
discussing the API, we will consider User Interfaces and other
autonomous clients to be outside of the VSO.

We will look at a common user driven search scenario, from the
standpoint of the User Interface:

Please note that the platform does not matter, as the User Interface may
be web based, command line, a desktop application, or some other
platform that has yet to be realized at this time.

=over 4

=item 1

The User Interface (UI) presents search options to the User.

=item 2

The User enters their search preferences into the User Interface.

=item 3

The UI asks VSO for the records that match the search request. (Query)

=item 4

The VSO returns to the UI a list of appropriate records.  (Query
Response)

=item 5

The UI presents the list of records to the User.

=item 6

The User informs the UI which Data Products they would like to retrieve
from the list.

=item 7

The UI asks VSO for the Data Products, along with specifying the
acceptable transfer methods. (GetData)

=item 8

The VSO responds to the UI appropriately based on the data transfer
method (GetData Response)

=item 9

The UI contacts the individual Data Providers to obtain the Data
Products.

=back

Although this particular example does not show all of the complexities
that may occur, such as error handling at the various levels, it
provides a representative example to describe the intentional decoupling
of the searching for data products of interest, and the out-of-band
retrieval of those products.

In some cases, it may make sense for each each data product to have a
one-to-one relationship with URLs to retrieve that product.  The GetData
function exists to provide for Data Providers who may package their data
in compressed archives to reduce network bandwidth, or for them to
provide alternative handling of excessive requests.

It has the additional benefit of permitting to Data Providers to
reorganize their data archives without the need to contact the
maintainers of various UIs with the new procedures for requesting data,
and enables new data transfer methods to be added in the future.

As explained in the above example, there is a need for two distinct
functions to be available in the VSO API:

=over 4

=item Query

A method to discover Data Products of interest.

=item GetData

A method to determine how to obtain Data Products of interest.

=back

The intricacies of the two methods are described in more detail in later
sections.

=head2 Query

The current Query API functionality is particularly simplistic,
to reduce the amount of code required by each of the Data Providers.
More complex query formats are currently in various stages of planning,
and will be available sometime in the future, along with the current
simple format.

Please see the VSO WSDL for the basic structure of a B<Query> request, which
is available from the VSO website:

  http://www.virtualsolar.org/

=head3 Input

Queries are C<RPC/encoded> SOAP with the following provisions:

The first and only argument is a B<Query> object, which contains a
B<QueryRequest> object, containing two elements:

=over 4

=item Version

The B<Version> element should be a 

=item QueryRequestBlock



An array of B<QueryRequestBlock>s may be sent to VSO.  Each query will be
individually searched, and returned.  Returned values will not be
returned in a manner that can associate each record to the individual
query that it matched.  If the User Interface requires this level of
granularity in the returned values, it should issue multiple calls to B<Query>,
rather than a single invocation with an array of B<QueryRequestBlock>s.

Each parameter may contain only one value, and a Data Provider will
attempt to limit responses to those that match all parameters. Please
note that if a Data Provider cannot provide matching on a particular
parameter, as they do not have that particular level of granularity in
their system, they will return all probable or possible matches, rather
than being overly restrictive in their returned values.

If a User Interface is attempting to query for multiple values for given
parameters, it should break the query down into all possible
permutations.

If you wish to ask for something similar to the following:

  (A1 or A2) and (B1 or B2)

You should instead organize the query like the following:

  (A1 and B1) or (A1 and B2) or (A2 and B1) or (A2 and B2)

A translation service with the ability to handle requests in a more
permissive manner will be coming in the near future.

The following elements may occur within a B<QueryRequestBlock>:

=over 4

=item Time

A B<Time> element is a complex type, with both B<start> and B<end> elements.
Both start and end are serialized as strings, 14 characters wide, with
each character being a number.  All times are in UTC.  The characters
represent the following:

=over 4

=item characters 1-4

Four digit year, zero padded if before 1000CE.  [no provisions have been
made for dates before 0CE.]

=item characters 5-6

Two digit month, zero padded, with January being '01'.

=item characters 7-8

Two digit day of the month, zero padded.

=item characters 9-10

Two digit hour of the day, zero padded, based on a 24 hour clock.

=item characters 11-12

Two digit minute of the hour, zero padded.

=item characters 13-14

Two digit second of the minute, zero padded.

=back

For instance, the time range for the day of
January 5th, 2003, from 6:02AM and 4:27PM UTC would be serialized as:

  <Time>
    <start>20030105060200</start>
    <end>20050105162700</end>
  </Time>

=item Wave

A B<Wave> element is a complex type, with B<wavemin>, B<wavemax> and B<waveunit>
elements.  Both B<wavemin> and B<wavemax> are serialized as floating point, with
the waveunit being a string.  The VSO Core is rather restrictive in
the units it will accept, and must be one of the following:

=over 4

=item *

Angstrom

=item *

GHz

=item *

keV

=back

A translation service with the ability to handle units in a more
permissive manner will be coming in the near future.

=item Extent

An Extent element is a complex type, with the following elements, each
of which is serialized as a string:

=over 4

=item *

x

=item *

y

=item *

width

=item *

length

=item *

type

=back

It is still under discussion as to how to best handle transformations
from different coordinate systems, but plan on providing a translation
service to handle alternative systems once it has been decided.

For the time being, you may specify any of the following values for
type:

=over 4

=item *

FULLDISK

=item *

CORONA

=item *

LIMB

=back

For the most current list of keywords, please see the VSO website:

  http://www.virtualsolar.org/

=item provider

A provider element is a string that contains the registered identifier
for a particular Data Provider.  For a listing of all current Data
Providers, please see the VSO website:

  http://www.virtualsolar.org/

=item source

A source elements is a string that contains the registered identifier
for the source of an observation.  The source may be an observatory or a
network of observatories.  For a listing of all current Data Sources,
please see the VSO website:

  http://www.virtualsolar.org/

=item instrument

An instrument element is a string that contains the specific instrument
name that obtained the data.  For a listing of all instruments with data
sets currently searched by VSO, please see the VSO website:

  http://www.virtualsolar.org/

=item physobs

A physobs element is a string that contains one of the physical
observable identifiers used by VSO.  The current list of recognized
keywords includes:

=over 4

=item *

LOS_velocity

=item *

vector_velocity

=item *

LOS_magnetic_field

=item *

vector_magnetic_field

=item *

intensity

=item *

equivalent_width

=item *

wave_power

=item *

wave_phase

=item *

oscillation_mode_parameters

=item *

polarization_vector

=item *

number_density

=item *

particle_flux

=item *

particle_velocity

=item *

thermal_velocity

=item *

composition

=back

For the most current list of keywords, please see the VSO website:

  http://www.virtualsolar.org/

=item nickname

Please note that the nickname element is currently in testing, and may
be reworked in later versions.

The nickname element is a string of space separated words.  This may be
used to pass additional parameters to a specific Data Provider. Please
note that the VSO Registry does not maintain information on how to route
queries based on this element, and so would require the User Interface
to specify which provider this query is intended for.

The same words used as nicknames may be translated differently by each
Data Provider, as they are terms that have been defined outside of the
VSO Data Model.

=back

=back

Please note that the terms defined above are standardizations for
building a query.  They do not represent the full set of terms defined
with the VSO Data Model, and they do not define the full interchange
format for the transfer of metadata.

=head3 Output

A B<Query> request will return a B<QueryResponse> object, which contains
an array of B<VSOiQueryResponse> objects.

Messages are returned as an array of SOAP-encoded B<VSOiQueryResponse> objects.

Additional terms are included in a B<VSOiQueryResponse> object, but it is
otherwise similar to a B<QueryRequestBlock>.  Refer to the
WSDL document for the structure of the returned data.

Please note that it is likely probable that the metadata will not be
fully populated, and the values may not directly match queried values. 
Data Providers are requested to return any probable match to the query,
and if they are unable to filter their results on particular values,
they may return information about Data Products which may not be of
interest.  It is believed that returning extraneous data is more
beneficial to the science community than excluding those items which may
have been of interest.

It is also possible that a data provider may not be able to map their
returned values back to the same values as used in a QueryRequest. it
may be that their value falls into more than one category, and they are
unable to place the value into a single container. The following items
provide examples of some of the values that may cause confusion:

=over 4

=item *

An image that has not been occulted, that includes the limb may be
appropriate for both C<FULLDISK> and C<LIMB> observations.

=item *

A Data Product may be packaged such that it contains data from a single
instrument with a varied collection of detectors, which results in data
that corresponds to multiple physical observable classifications.

=back

The response to a VSO Query is a B<VSOiResultArray>, which contains one or
more VSOiResult objects.  The B<VSOiResult> object contains the following
elements:

=over 4

=item version

The version of the VSO protocol that this response conforms to. This
element is serialized as a floating point number.

=item no_of_records_returned

An integer that describes the total number of records returned in this
result object.

=item no_of_records_found

An integer that describes the total number of records found by the data
provider for the query.

Please note that Data Providers may set limits to the number of records
returned per query.  If this value does not match the value in
no_of_records_returned, the Data Provider has additional records that
may be of interest that were not returned.  If this value is not
defined, it means that the Data Provider has reached its limit, but that
calculating the number of remaining products that match would be cost
prohibitive.

=item status

The status element is a string that contains information
about the completion state of the response.  More details about the
format of this string is described in the section L</VSO Messages>.

=item error

The error element has been deprecated as of VSO 0.8, and should be
encoded as a status element.

=item debug

The debug element may be used by programmers to return additional
information that may assist them in debugging their programs, but
would not be beneficial to typical consumers of applications.

Client software should not tie any application logic to this value,
as its existance, formatting and contents are solely at the whim of
programmer who set the value.  Its contents may be useful when
Client programmers are coordinating with Data Providers to identify
quirks or other debugging processes.

=item record

The record element is a complex data type which contains an array of
B<QueryResponseBlock> elements.  A B<QueryResponseBlock> contains all of
the elements previously defined as being valid within a
B<QueryRequestBlock>.  It also defines the following additional
elements:

=over 4

=item fileid

The fileid is a string containing a data provider assigned identifier.
The fileid should point to a specific data product offered by the
provider, however, there may not always be a one-to-one correlation
between the two in some situations:

=over 4

=item *

The Data Provider may maintain an archive of calibrated or other higher
level data products.  Data Providers may have a fileid that points to
the most current calibrated data, and may no longer have the
previous version available.

=back

The B<fileid> value should provide enough information for a Data Provider
to retrieve the Data Product that they are describing in the
record.

Data Providers are free to use whatever is approrpriate to their
archive to generate their fileids.  They may correspond to 
filepaths, URIs, or database keys, and not assumptions should be
made by the client about the value of this element.  Client
software should call the VSO L</GetData> method to request the 
transfer of a particular Data Product that corresponds to a B<fileid>.

=item size

The size element contains a floating point value corresponding to
the size of the Data Product in kilobytes.

=item info

The info element contains a human readable string describing the
Data Product.  Data Providers may place whatever they feel
is appropriate in this string to describe their Data Product,
although they are requested to  keep it relatively short.

=back

=back

=head2 GetData

Once a User Interface has a list of data products that it wishes
to aquire, it should call the B<GetData> method to order the 
products. 

This function handles L</Negotiation> of transfer method, and will
provide enough information to an interested party to obtain the data
sets that they desire.

=head3 Input

Please see the VSO WSDL for the basic structure of a B<Query> request, which
is available from the VSO website:

  http://www.virtualsolar.org/

Requests are C<RPC/encoded> SOAP with the following provisions:

=over 4

=item version

The VSO version that you have formatted your request in.
The VSO core will handle translation of requests to alternative
versions as necessary to communicate with a particular Data
Provider.  As such, both a User Interface and a Data Provider
are only required to support a single version of VSO.  It is
possible that some features may not be available in Data
Providers that support older VSO protocols.

=item request

A request is a container to isolate a single request.  Although
multiple requests may be made to the VSO core, VSO will only send
one request to each Data Provider per communication.  If there
are multiple requests intended for a Data Provider, VSO will
call a Data Provider's B<GetData> function once for each request
element.

=item method

Each request should contain the method by which the user or agent
desires to obtain data sets.  If there is no method provided,
or the method is empty, it is assumed that this is a request to
obtain the list of methods that a Data Provider may support.
If there are multiple methods listed, it is assumed that they
are in a priority order, with the first element being the most
desired method.

Please see L</Negotiation> for a complete explaination of how
ths element is used, and for information about valid values
for this element.

=item info

The B<info> element contains extra information about the user. The
information required for each request may vary by Data Provider and/or
Request Method.  If a request requires additional information, a message
to that effect will be generated, as explained in L</Negotiation>.  The
Info element must contain an Apache-stype mapping, which is an array of
struct items with key/value pairs corresponding to the field names
required by the Data Provider. More information about the valid values
for the field names may be found under L</User Information>.

Please note: although field names will typically be returned as all
upper, the client should serialize its request as all lower case.

=item data

The B<data> elemement provides a container for Provider and
FileID groupings.  There should only be one Data element in
a request, but it may generate multiple Data elements in
response.

=item provider

All requests for data must include the Data Provider's 
common abbreviation as used within VSO, so that the data
may be readily identified.  Please see L</Data Provider IDs> for
information about obtaining an ID and obtaining a list of 
valid ProviderIDs.

=item fileid

All requests for information must include the B<fileids>s of the
data sets to be downloaded.  These FileIDs may be obtained
using the L</Query> functionality of VSO.  Each Data Provider
may have their own format for identifying their data, and it
is possible that the data associated with a particular ID
may change as instruments are recalibrated and/or alternative
data transformations are performed.

=back

=head3 Output

Messages are returned as an array of SOAP-encoded B<VSOiQueryResponse>
objects.

Refer to the WSDL document for the structure of the returned data.

=over 4

=item version

This element must contain the version of the VSO protocol in
which this message is encoded.

=item status

This element is a string, containing a a VSO Status Message.  Please see
L</VSO Messages> for more information.

=item response

From a Data Provider, there will be only one
B<response> element, however, they will be aggregated by
the VSO Core, and as such, there may be more than one returned
from a request sent to a VSO Instance.

Note -- if a Data Provider has data products which are available
under different transfer methods, the currently supported mechanism
is to create break the data repository into multiple VSO Data Providers,
which each have homogeneous delivery mechanisms.  This may change
in later versions of the VSO protocol.

=item info

The B<info> element is an array of strings, with the strings
being keywords that were sent in the request, to permit a 
client to recreate the request, or in the case of an error
requiring additional information, supplies a list of information
keywords that are required to process the request.

Please note -- as a returned value, the B<info> element is an
array of strings, whereas, in the request, it is an Apache
style mapping, being an array containing
key/value pairs.

More information about the valid
values for field names may be found under L</User Information>.

Please note -- this is a change from 0.7, where the B<info> field
was only returned when the request was not successful, and required
information to be specified.  In 0.8, the inclusion of items in the B<info>
element may only be an indication that they were sent with the request,
not that they were actually necessary.

[yes, I know it's odd.  It's a quirk in how I kept the data providers
from needing to recode between 0.7 and 0.8 -Joe]

=item method

The b<method> element is a string of arrays, which contain the methods
to send to repeat the request, or a list of the acceptable methods
that the data provider supports.  The client should examine the
L<status code/Status Codes> to determine if they need to continue with L</Negotiation>.

If negotiation is completed, this will contain one element, which
contains the negotiated method.

=item data

The B<data> element is a container for returned information.
There may be more than one element returned if there are multiple
B<url>s, to download the information.

=item provider

The B<provider> element will contain the common abbreviation for
the Data Provider as used within VSO.  Please see L</Data Provider IDs>
for information about obtaining an ID.

=item fileid

The Data Provider will attempt to return an arroy of strings,
containing the list of B<fileid>s that were requested, so that
you can re-create the request, if there is a need to complete
negotiation or other handling.

With some errors, particularly if the error occurs at some place
other than a Data Provider, this may not be possible.

Please note -- this is a change from 0.7, which stated:

=over 4
If the B<Data Request> may be fulfilled with one B<Data> block, or
with one B<Status> message, there is no need to return a list of FileIDs
with the response.  If there are multiple B<Data> blocks, or there 
is a reason to return separate status messages for a subset of the 
data, the Data Provider should return a list of FileIDs to which the
B<Status Message> or B<URL> pertains.

=back

=item url

The B<url> element contains a URL to obtain the data requested.
If it is an B<HTTP> or B<HTTPS> address, it should be assumed to
use B<GET>, provided there is not an accompanying B<content> element.

=item content

The B<content> element contains the string necessary to send as
the content of an B<HTTP> B<POST> request using the B<url> element
provided.  Inclusion of this element suggests that the B<url>
should use a B<POST> method to retrieve the data products.

=item details

The B<details> element is a string that should be presented to
the user about the status of the data request.  The content and
format is up to the individual data providers, and as such, may
change, and is not recommended for parsing by User Interface clients.

This field may give information about the timeliness of asyncronous
requests, or if there are cost recovery mechanisms for exceptionally
large requests.

=back

=head2 Negotiation

In the process of negotiating what methods a Data Provider should
use to transfer the data products, a client should send a list of 
of methods they wish to use to download the files, as described in the
B<method> element.


The methods are broken into the following basic types:

=head3 URL

There is a URL that can be followed to get to the data of interest.

=head3 STAGING

The data must be processed by the data provider before it is made
available for download.  Typically, for C<STAGING> transfers, the Data Provider
will request an e-mail address that they can send notification to
when the process is complete.

C<STAGING> responses should contain B<Detail> elements that give
an indication as to how long the request will take to complete.

=head3 OFFLINE

The data can be sent encoded on physical media, and sent through
parcel post.  Typically, for C<OFFLINE> transfers, the Data Provider
will request an e-mail address or phone number to coordinate the
process.  The Data Provider may request information for shipping
the products, such as the recipient's name and shipping address.

C<OFFLINE> responses should contain B<Detail> elements that give
an indication as to how long it will take for the Data Provider
to respond to the request, to work out necessary details, such as
the possibilility of cost-recovery.

=head3 PUSH

The data will transfer the data to you, if you give them the
appropriate connection information for them to do so.  Typically,
for C<PUSH> transfers, the Data Provider
will request an e-mail address that they can send notification to
when the process is complete, or to work out any difficulties that
may occur.  They will also require connection information so they
can transfer the data to the requesting user.

C<PUSH> responses should contain B<Detail> elements that give
an indication as to how long the request may take to process.  The
time is typically an indicaton as to when the process may start,
as the Data Provider would have no knowledge of the transfer rate
to the user's system as this time.

Please check with your local information or network security office
before coordinating a C<PUSH> of data, as it will often times be
blocked a border router or firewall, or it may fall under specific
security policies within your organization.

=head3 Subtypes

A Data Provider may support multiple methods, of one or more
basic types.  Specific methods are specified by giving a basic
type, a hypen, and a sub-type.

Subtypes vary by basic types, but for the most part, specify
the method of encoding the data:

=over 4

=item URL

The sub-type for C<URL> specifies the compression and packaging of the data.  For example,

=over 4

=item URL-FILE

A single file available for each URL.

=item URL-packaged

A special case, requesting few URLs to download all of the
requested files.  (ie, C<URL>, but not C<URL-FILE>)

=item URL-TAR

Each URL points to a C<tar>'d group of files.

=item URL-TAR_GZ

Each URL points to a C<tar>'d group of files, which has been C<gzip>'d.

=item URL-ZIP

Each URL points to a group of files in a C<ZIP> archive.

=back

=item STAGING

The sub-type for C<STAGING> specifies the compression and 
packaging of the data.  For example,

=over 4

=item STAGING-TAR

The files are archived using the unix C<tar> command or its equivalent.

=item STAGING-TAR_GZ

The files are archived using the unix C<tar> command, and then
compressed using C<gzip>.

=item STAGING-GZ_TAR

The individual files are compressed using the C<gzip> command, and 
then archived into a tarball.

=item STAGING-ZIP

The files are archived using C<ZIP> compression.

=back

=item OFFLINE

The sub-type for C<OFFLINE> specifies the type of media that the
Data Products should be written to for shipment.  For example,

=over 4

=item OFFLINE-CD

The data will be written out to a Compact Disc.

=item OFFLINE-DAT

The data will be written out to a 4mm Digital Audio Tape.
(yes, I know, it's technically not a DAT when it's not
holding audio information, but it's what people are used to
calling it)

=item OFFLINE-EXABYTE8200

The data will be written out to an Exabyte model 8200 tape.

=item OFFLINE-EXABYTE8500

The data will be written out to an Exabyte model 8500 tape.

=back

=item PUSH

The sub-type for C<PUSH> specifies the protocol that will be used to
transfer the data.  For example,

=over 4

=item PUSH-RCP

The data will be transfered using the Remote Copy Protocol.
This will typically require the requesting user to configure
an appropriate C<rhosts> file, and the Data Provider should 
specify their server's name in the B<details> element of 
their response.

=item PUSH-FTP

The data will be transfered using the File Transfer Protocol.
Please note that many places may prefer anonymous FTP, where no
password is used, to prevent it from being sniffed while in transit,
while others prefer that anonymous FTP not be used due to the 
potential for unauthorized parties to gain access to place files
on the system.

=item PUSH-SCP

The data will be transfered using the Secure Copy Protocol.

=item PUSH-SFTP1

The data will be transfered using the Secure File Transfer Protocol,
version 1.  Please note that a system that supports SFTP2 may not
also support SFTP1, although it is designed to degrade gracefully should
SFTP1 also be installed.

=item PUSH-SFTP2

The data will be transfered using the Secure File Transfer Protocol,
version 2.  Please note that a system that supports SFTP2 may not
also support SFTP1, although it is designed to degrade gracefully should
SFTP1 also be installed.

=back

Please note that this is not a complete list of available transfer
methods, and that as of this writing, at least one of them isn't
currently being used by any Data Providers.  The list of transfer methods
used by VSO Data Providers may change as new Data Providers are
added, or demand for other transfer types are identified.  Please
see one of the central VSO servers, at L<http://www.virtualsolar.org/>
for the most current list.

=back

=head2 User Information

With some transfer methods, Data Providers may request or require 
information about the user who is requesting their Data Products.
It is possible that the Data Providers may use this information
for metrics, such as determining the number of unique users of their
Data Repository, so they can justify budgetary increases to better
serve the Solar Physics community.

The L</Privacy Policy> for components associated with NASA is contained below,
however you should check the VSO Central Servers at L<http://www.virtualsolar.org/>
for the most current revision, and for links to other Data Provider's
privacy policies.

User Information is requested by a series of keywords.  As of the 
time of this writing, the keywords in use are as follows:

=over 4

=item EMAIL

The e-mail address of the person requesting the data to be transfered.
This is typically used to notify the requestor of completion or
problems, or to coordinate cost recovery and other such details.  Some
Data Providers may use this or other information to identify unique
users to their site to justify their budget.  Please see L</Privacy
Policy>, above.

=item HOST

Either the fully qualified domain name, or a routable IP
address of the system to transfer the Data Products to.
Used by C<PUSH>.

=item USER

The user name that should be used to login to the system.
If you wish to use anonymous FTP, please specify 'C<anonymous>'
or 'C<ftp>' as appropriate to your system, and a suitable
corresponding password.

=item PASSWORD

The password that should be used to login to the system.
Used by C<PUSH>.

=item DIRECTORY

The system directory that files should be saved to.  Some
Data Providers may create sub-directories below this point.
If the directory is root relative, it should be preceeded with
a slash C</>.  Used by C<PUSH>.

=item ADDRESS

The postal mailing address to send physical media to you.
Used by C<OFFLINE>.

=back

Please see the VSO Central Servers at L<http://www.virtualsolar.org/>
for the most current list of keywords.

=head3 Privacy Policy

As each Data Provider is a seperate organizational entity from VSO,
you should be aware of a particular Data Provider's privacy policies
before giving them your personal information.  Links to Data Provider's
privacy policies is available from the VSO Central Servers, available
at L<http://www.virtualsolar.org>.

VSO as an orgainization, being funded through NASA, is specifically
restricted in the type of information that it may collect, and the
duration for which it may keep it.  Any User Information passed through
a VSO Instance to a Data Provider will B<not> be logged by VSO, although
it is possible that it may be stored in memory during the transaction,
and that it may be seen in the process of debugging any problems that
may arise in the future.

Records will be kept of the quantity and nature of the requests made
through VSO, in an attempt to perform system monitoring, capacity
planning, and to use these metrics in an attempt to persuade additional
data providers to join the VSO project or to provide insight into
features that may be of use to the user community. Metrics will also be
used to justify our budget at necessary reviews.

These records and metrics will be kept in such a way as to not identify
individual persons, but instead to record trends and similar behaviour
of the system.

The following policy is current as of the time of this writing,
however you should check the VSO Central Servers at L<http://www.virtualsolar.org/>
for the most current revision.


=head2 Data Provider IDs

All data providers must be uniquely identified within VSO.  Those
persons wishing to establish their organization as a VSO Data Provider
should visit one of the VSO Central Servers at L<http://www.virtualsolar.org>
for information about becoming a registered Data Provider.

All Data Providers are identified by a unique ID, which is most
typically an abbreviation or acronym for the organization which
controls the Data Archive.  Identifiers are given on a first come,
first served basis, as there may be more than one organization
with the same common abbreviation, or there may be more than one
Data Archive maintained by different groups within an
organization.

=head2 VSO Messages

In the process of interacting with VSO, there will be times when
various requests cannot be fulfilled.  There are a number of 
situations in which problems can occur with a distributed system
such as VSO, but we hope to provide information to the user so
they can determine how they should proceed to obtain the 
information that they desire in a time-efficient manner.

VSO Messages are typically composed of two parts.  The first
part is an alphanumeric string, followed by a space, and then
followed by a freeform string that may contain any character
that is not a line feed or carriage return.

=begin comment

(need to better define the list of acceptable characters -- Joe)

=end comment

The first part
is a status code, which is the letter C<V>, followed by three
digits.  Please note that the letter C<V> was introduced in 0.7,
and that 0.6 servers will return a three digit status code, which
follows the same conventions as explained below.  The status code
is intended to be processed by automated methods.  If a status code
is not understood, any user agents should handle the error as if
the last two digits were replaced with C<00>, that is to say that
if they encounter a C<V194>, it should be treated as a C<V100>
status message.

The second part of the message is a short descriptive string
of information.  It may contain a short message for the user, and
may also include debugging information from a programmer about
the exact source or nature of the message.  The short message
should give the user a clue as to the source of the error,
and how they should attempt to continue, without needing
to look up the status code.  Please note that Data Providers
may write multiple messages for the same status code, if 
they believe it would be of a benefit to the user, or for them
to provide assistance in the future.

VSO messages may be found in either B<Error> or B<Status>
elements in the various VSO responses.  For the most part,
the only difference is in their location in the returned
data structure.  There is only one B<Error> element per
data strucutre, but there may be a number of identical
or different B<Status> elements.

=over 4

=item Error Messages

An error message should only be present when something has
gone wrong.  It may indicate a complete, or a partial failure.
In the case of a complete failure, the error message would be
indicative of the entire return response.

=item Status Messages

The status message gives an indication if the request was successful.
The message is composed of a three digit status code, a space, and a
longer human-readable status message which may give additional detail to
the user.  The status may indicate that the request was successful,
cannot be completed, requires a change to the request, or will
have to be completed out-of-band.

The format of the string returned varies slightly dependant upon the
version of VSO that the message is encapsulated as:

=over 4

=item VSO 0.6 Format

I<code> I<message>

=item VSO 0.7 Format

VI<code> I<message>

=item VSO 0.8 Format

VSO-I<X>I<code> I<message>

In the case of 0.8 messages, a letter preceeds the status code to
inform the client as to which module generated the status message:

=over 4

=item V

A VSO Core

=item R

A VSO Registry

=item D

A VSO Data Provider

=back

=back

By the time the VSO is released to the general public, we hope to
upgrade all elements to the 0.8 format, but this documentation 
will remain until such time as that has occured.

=item Detail Information

In some situations, there is the need for more detailed information
about the current status of the transaction which should be sent
directly to the user, and should not attempt to be handled through
automation.  If such an event arises, the human-readable messasge
is placed in the B<Details> element at the same level as the B<Status>
message to which it corresponds.

=item Status Codes

=over 4

=item 200 Success

The request has been completed without any errors occuring.

=item 202 Accepted

The request has been accepted for processing.  This is not an error,
but an indication that the request will take time to process.  Additional
information should be contained in the B<Detail> element, explaining
what time frame a user should expect to wait for the request to complete.

=item 300 Multiple Choices

The system has received an ambiguous request, and needs further
clarification.  This is typically used in conjunction with requests
for transfering Data Products.  The user should review what their 
options are in the response returned, and resend with one, and only
one of those choices.

=item 400 Bad Request

An attempt to communicate with a VSO Instance or Data Provider was
improperly formatted.  There may be a missing element, or an element
may not be correctly structured.

The message component should contain a hint as to which field
the problem occured.

=item 405 Unknown Method Supplied

There was a request for a transfer method that a Data Provider does
not support.  Please note that a Data Provider may also return a V300
status for this situation, in which case they will also return a list
of acceptable transfer methods.

=item 412 Missing Required Information

Some piece of User Information was missing from the request, and the
Data Provider is unable to process the request because of it.

=item 500 Server Error

An error that seems to be an issue with the configuration of the 
Data Provider or VSO Instance has occurred.  As such, there is
nothing that the user can do to fix the error, and should either
wait before trying again, or should contact the server administrator
to notify them of the problem.

=item 505 Version not supported

There has been an attempt to communicate with a VSO Instance or 
Data Provider with a version of the VSO API that is not compatible.

=back

=back

=head2 TO DO

Additional functionality has been discussed, and some has been designed,
but it not currently implemented within VSO.  Such items include:

=over 4

=item Complex Queries

The ability to send more complex queries to a VSO Instance.  The
current restrictions require User Interfaces to generate a series
of more simple queries.

=item Joined Queries

The ability to generate a subsequent request based on the results of an
initial query.  This can currently been done through logic within a User
Interface, and multiple queries.

=item Negated Queries

The ability to specify that there is a particular parameter that you
wish to use to exclude data sets of interest.  This can currently be
done through logic within a User Interface.

=item Registry Queries

The ability to query the VSO Registry for metadata about the instruments
or datasets that it contains.

=item Registry Item Details

The ability to gain additional information about a data provider,
observatory, instrument, or other such item that may assist 

=item Record Count Queries

The ability to request a count of how many records match a query. This
information is currently returned, but not without returning metadata of
individual records.

=item Summary Queries

The ability to request statistics of how many records match a query,
based on independent parameters.  This can currently be done through
logic within a User Interface.

=item Alternative Range Matching

The ability to specify a method of range matching other than a
non-vanishing intersection, the current default.  This filtering would
currently have to be done by the User Interface.

=item Additional Query Parameters

The inclusion of additional parameters to be searched on in a 
standardized format.  Data Providers may currently add additional
hooks to their data through the 'L<nickname>' element.

=item Additional Return Fields

The ability to request additional metadata be returned from a Data Provider
in response to a query.

=back

=head2 SEE ALSO

Additional information about the Virtual Solar Observatory Project, the
architecture of the VSO, including the interaction between other parts
within VSO is available from the VSO website:

  http://www.virtualsolar.org/

=head2 APPENDIX

=head3 Examples

Please note -- some serialization issues remain in these examples.
They are a by product of the tools being used, but are fully functional
requests, and do show valid responses.  Efforts to serialize responses

The following is an example B<Query> for the following information:

  Time between 2004/Jan/01 00:00:00 and 2004/Jan/02 00:00:00
  Instrument EIT

Query:

  POST http://localhost/cgi-bin/vsoi08.cgi HTTP/1.1
  Accept: text/xml
  Accept: multipart/*
  Content-Length: 823
  Content-Type: text/xml; charset=utf-8
  SOAPAction: "http://virtualsolar.org/VSO/VSOi#Query"
  
  <?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/1999/XMLSchema" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:VSO="http://virtualsolar.org/VSO/VSOi" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"><SOAP-ENV:Body><namesp1:Query xmlns:namesp1="http://virtualsolar.org/VSO/VSOi"><VSO:request xsi:type="VSO:QueryRequest"><block><VSO:instrument xsi:type="xsd:string">EIT</VSO:instrument><time><VSO:start xsi:type="xsd:string">20040101000000</VSO:start><VSO:end xsi:type="xsd:string">20040102000000</VSO:end></time></block><VSO:version xsi:type="xsd:float">0.6</VSO:version></VSO:request></namesp1:Query></SOAP-ENV:Body></SOAP-ENV:Envelope>

Query Response:

  HTTP/1.1 200 OK
  Connection: close
  Date: Tue, 16 Nov 2004 17:53:49 GMT
  Server: Apache/1.3.29 (Darwin) mod_perl/1.29
  Content-Length: 2093
  Content-Type: text/xml; charset=utf-8
  Client-Date: Tue, 16 Nov 2004 17:53:52 GMT
  Client-Peer: 127.0.0.1:80
  Client-Response-Num: 1
  SOAPServer: SOAP::Lite/Perl/0.60
  
  <?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:VSO="http://virtualsolar.org/VSO/VSOi" xmlns:namesp3="http://namespaces.soaplite.com/perl" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema"><SOAP-ENV:Body><namesp2:QueryResponse xmlns:namesp2="http://virtualsolar.org/VSO/VSOi"><SOAP-ENC:Array SOAP-ENC:arrayType="namesp3:QueryResponse[1]" xsi:type="SOAP-ENC:Array"><item xsi:type="namesp3:QueryResponse"><record SOAP-ENC:arrayType="xsd:ur-type[1]" xsi:type="SOAP-ENC:Array"><item><wave><VSO:wavemax xsi:type="xsd:float">195.00</VSO:wavemax><VSO:waveunit xsi:type="xsd:string">Angstrom</VSO:waveunit><VSO:wavemin xsi:type="xsd:float">195.00</VSO:wavemin></wave><VSO:instrument xsi:type="xsd:string">EIT</VSO:instrument><VSO:info xsi:type="xsd:string">FULL SUN 171 (SUBMODE 2)</VSO:info><VSO:size xsi:type="xsd:float">2108160</VSO:size><time><VSO:end xsi:type="xsd:string">20040101190507</VSO:end><VSO:start xsi:type="xsd:string">20040101190507</VSO:start></time><extent><VSO:x xsi:null="1"/><VSO:width xsi:null="1"/><VSO:y xsi:null="1"/><VSO:type xsi:null="1"/><VSO:length xsi:null="1"/></extent><VSO:fileid xsi:type="xsd:string">/archive/4/private/data/processed/eit/lz/2004/01/efz20040101.190507</VSO:fileid><VSO:source xsi:type="xsd:string">SOHO</VSO:source><VSO:provider xsi:type="xsd:string">SDAC</VSO:provider><VSO:physobs xsi:type="xsd:string">intensity</VSO:physobs></item></record><VSO:no_of_records_returned xsi:type="xsd:int">1</VSO:no_of_records_returned><VSO:version xsi:type="xsd:float">0.7</VSO:version><VSO:debug xsi:type="xsd:string">and ob.date_end >= ? and ob.date_obs &lt;= ? and ob.id_instrume in ( ? ) </VSO:debug><VSO:no_of_records_found xsi:type="xsd:int">1</VSO:no_of_records_found><VSO:provider xsi:type="xsd:string">SDAC</VSO:provider></item></SOAP-ENC:Array></namesp2:QueryResponse></SOAP-ENV:Body></SOAP-ENV:Envelope>

GetData Request, no method specified:

  POST http://localhost/cgi-bin/vsoi08.cgi HTTP/1.1
  Accept: text/xml
  Accept: multipart/*
  Content-Length: 1241
  Content-Type: text/xml; charset=utf-8
  SOAPAction: "http://virtualsolar.org/VSO/VSOi#GetData"
  
  <?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/1999/XMLSchema" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:namesp3="http://namespaces.soaplite.com/perl" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:VSO="http://virtualsolar.org/VSO/VSOi" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:apachens="http://xml.apache.org/xml-soap"><SOAP-ENV:Body><namesp2:GetData xmlns:namesp2="http://virtualsolar.org/VSO/VSOi"><VSO:request xsi:type="VSO:VSOiGetDataRequest"><VSO:version xsi:type="xsd:float">0.6</VSO:version><request xsi:type="namesp3:GetDataRequest"><info xsi:type="apachens:Map"/><method xsi:type="namesp3:Method" SOAP-ENC:arrayType="xsd:ur-type[0]"/><data xsi:type="namesp3:DataRequest" SOAP-ENC:arrayType="xsd:ur-type[1]"><item><fileid xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="xsd:string[1]"><item xsi:type="xsd:string">/archive/4/private/data/processed/eit/lz/2004/01/efz20040101.190507</item></fileid><VSO:provider xsi:type="xsd:string">SDAC</VSO:provider></item></data><VSO:sc_id xsi:null="1"/></request></VSO:request></namesp2:GetData></SOAP-ENV:Body></SOAP-ENV:Envelope>

GetData Response, listing acceptable methods:

  HTTP/1.1 200 OK
  Connection: close
  Date: Tue, 16 Nov 2004 17:53:52 GMT
  Server: Apache/1.3.29 (Darwin) mod_perl/1.29
  Content-Length: 1481
  Content-Type: text/xml; charset=utf-8
  Client-Date: Tue, 16 Nov 2004 17:53:55 GMT
  Client-Peer: 127.0.0.1:80
  Client-Response-Num: 1
  SOAPServer: SOAP::Lite/Perl/0.60
  
  <?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/1999/XMLSchema" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:namesp4="http://namespaces.soaplite.com/perl" xmlns:VSO="http://virtualsolar.org/VSO/VSOi" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"><SOAP-ENV:Body><namesp3:GetDataResponse xmlns:namesp3="http://virtualsolar.org/VSO/VSOi"><SOAP-ENC:Array SOAP-ENC:arrayType="VSO:GetDataResponse[1]" xsi:type="SOAP-ENC:Array"><VSO:response xsi:type="VSO:GetDataResponse"><status xsi:type="xsd:string">VSO-D300 Multiple Choices</status><info SOAP-ENC:arrayType="xsd:ur-type[0]" xsi:type="SOAP-ENC:Array"/><VSO:provider xsi:type="xsd:string">SDAC</VSO:provider><method SOAP-ENC:arrayType="xsd:string[3]" xsi:type="SOAP-ENC:Array"><item xsi:type="xsd:string">URL-FILE</item><item xsi:type="xsd:string">STAGING-ZIP</item><item xsi:type="xsd:string">STAGING-TAR_GZ</item></method><data SOAP-ENC:arrayType="xsd:ur-type[1]" xsi:type="namesp4:DataResponse"><item><fileid SOAP-ENC:arrayType="xsd:string[1]" xsi:type="SOAP-ENC:Array"><item xsi:type="xsd:string">/archive/4/private/data/processed/eit/lz/2004/01/efz20040101.190507</item></fileid></item></data><VSO:version xsi:type="xsd:float">0.7</VSO:version></VSO:response></SOAP-ENC:Array></namesp3:GetDataResponse></SOAP-ENV:Body></SOAP-ENV:Envelope>

GetData Request, URL-FILE method:

  POST http://localhost/cgi-bin/vsoi08.cgi HTTP/1.1
  Accept: text/xml
  Accept: multipart/*
  Content-Length: 1291
  Content-Type: text/xml; charset=utf-8
  SOAPAction: "http://virtualsolar.org/VSO/VSOi#GetData"
  
  <?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/1999/XMLSchema" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:namesp3="http://namespaces.soaplite.com/perl" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:VSO="http://virtualsolar.org/VSO/VSOi" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:apachens="http://xml.apache.org/xml-soap"><SOAP-ENV:Body><namesp4:GetData xmlns:namesp4="http://virtualsolar.org/VSO/VSOi"><VSO:request xsi:type="VSO:VSOiGetDataRequest"><VSO:version xsi:type="xsd:float">0.6</VSO:version><request xsi:type="namesp3:GetDataRequest"><info xsi:type="apachens:Map"/><method xsi:type="namesp3:Method" SOAP-ENC:arrayType="xsd:string[1]"><item xsi:type="xsd:string">URL-FILE</item></method><data xsi:type="namesp3:DataRequest" SOAP-ENC:arrayType="xsd:ur-type[1]"><item><fileid xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="xsd:string[1]"><item xsi:type="xsd:string">/archive/4/private/data/processed/eit/lz/2004/01/efz20040101.190507</item></fileid><VSO:provider xsi:type="xsd:string">SDAC</VSO:provider></item></data><VSO:sc_id xsi:null="1"/></request></VSO:request></namesp4:GetData></SOAP-ENV:Body></SOAP-ENV:Envelope>

GetData Response, with URLs:

  HTTP/1.1 200 OK
  Connection: close
  Date: Tue, 16 Nov 2004 17:54:11 GMT
  Server: Apache/1.3.29 (Darwin) mod_perl/1.29
  Content-Length: 1517
  Content-Type: text/xml; charset=utf-8
  Client-Date: Tue, 16 Nov 2004 17:54:14 GMT
  Client-Peer: 127.0.0.1:80
  Client-Response-Num: 1
  SOAPServer: SOAP::Lite/Perl/0.60
  
  <?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:VSO="http://virtualsolar.org/VSO/VSOi" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:namesp4="http://namespaces.soaplite.com/perl" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/1999/XMLSchema"><SOAP-ENV:Body><namesp3:GetDataResponse xmlns:namesp3="http://virtualsolar.org/VSO/VSOi"><SOAP-ENC:Array SOAP-ENC:arrayType="VSO:GetDataResponse[1]" xsi:type="SOAP-ENC:Array"><VSO:response xsi:type="VSO:GetDataResponse"><VSO:version xsi:type="xsd:float">0.7</VSO:version><method SOAP-ENC:arrayType="xsd:string[1]" xsi:type="SOAP-ENC:Array"><item xsi:type="xsd:string">URL-FILE</item></method><data SOAP-ENC:arrayType="xsd:ur-type[1]" xsi:type="namesp4:DataResponse"><item><VSO:url xsi:type="xsd:string">http://sohodata.nascom.nasa.gov//archive/4/private/data/processed/eit/lz/2004/01/efz20040101.190507</VSO:url><VSO:provider xsi:type="xsd:string">SDAC</VSO:provider><fileid SOAP-ENC:arrayType="xsd:string[1]" xsi:type="SOAP-ENC:Array"><item xsi:type="xsd:string">/archive/4/private/data/processed/eit/lz/2004/01/efz20040101.190507</item></fileid></item></data><VSO:provider xsi:type="xsd:string">SDAC</VSO:provider><info SOAP-ENC:arrayType="xsd:ur-type[0]" xsi:type="SOAP-ENC:Array"/></VSO:response></SOAP-ENC:Array></namesp3:GetDataResponse></SOAP-ENV:Body></SOAP-ENV:Envelope>

GetData Request, STAGING-TAR_GZ:

  POST http://localhost/cgi-bin/vsoi08.cgi HTTP/1.1
  Accept: text/xml
  Accept: multipart/*
  Content-Length: 1297
  Content-Type: text/xml; charset=utf-8
  SOAPAction: "http://virtualsolar.org/VSO/VSOi#GetData"
  
  <?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/1999/XMLSchema" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:namesp3="http://namespaces.soaplite.com/perl" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:VSO="http://virtualsolar.org/VSO/VSOi" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:apachens="http://xml.apache.org/xml-soap"><SOAP-ENV:Body><namesp4:GetData xmlns:namesp4="http://virtualsolar.org/VSO/VSOi"><VSO:request xsi:type="VSO:VSOiGetDataRequest"><request xsi:type="namesp3:GetDataRequest"><data SOAP-ENC:arrayType="xsd:ur-type[1]" xsi:type="namesp3:DataRequest"><item><VSO:provider xsi:type="xsd:string">SDAC</VSO:provider><fileid SOAP-ENC:arrayType="xsd:string[1]" xsi:type="SOAP-ENC:Array"><item xsi:type="xsd:string">/archive/4/private/data/processed/eit/lz/2004/01/efz20040101.190507</item></fileid></item></data><method SOAP-ENC:arrayType="xsd:string[1]" xsi:type="namesp3:Method"><item xsi:type="xsd:string">STAGING-TAR_GZ</item></method><info xsi:type="apachens:Map"/><VSO:sc_id xsi:null="1"/></request><VSO:version xsi:type="xsd:float">0.6</VSO:version></VSO:request></namesp4:GetData></SOAP-ENV:Body></SOAP-ENV:Envelope>

GetData Response, listing required information:

  HTTP/1.1 200 OK
  Connection: close
  Date: Tue, 16 Nov 2004 18:09:08 GMT
  Server: Apache/1.3.29 (Darwin) mod_perl/1.29
  Content-Length: 1449
  Content-Type: text/xml; charset=utf-8
  Client-Date: Tue, 16 Nov 2004 18:09:11 GMT
  Client-Peer: 127.0.0.1:80
  Client-Response-Num: 1
  SOAPServer: SOAP::Lite/Perl/0.60
  
  <?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:VSO="http://virtualsolar.org/VSO/VSOi" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/1999/XMLSchema" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:namesp4="http://namespaces.soaplite.com/perl"><SOAP-ENV:Body><namesp3:GetDataResponse xmlns:namesp3="http://virtualsolar.org/VSO/VSOi"><SOAP-ENC:Array SOAP-ENC:arrayType="VSO:GetDataResponse[1]" xsi:type="SOAP-ENC:Array"><VSO:response xsi:type="VSO:GetDataResponse"><info SOAP-ENC:arrayType="xsd:string[1]" xsi:type="SOAP-ENC:Array"><item xsi:type="xsd:string">EMAIL</item></info><method SOAP-ENC:arrayType="xsd:string[1]" xsi:type="SOAP-ENC:Array"><item xsi:type="xsd:string">STAGING-TAR_GZ</item></method><status xsi:type="xsd:string">VSO-D412 Missing Required Information</status><VSO:version xsi:type="xsd:float">0.7</VSO:version><VSO:provider xsi:type="xsd:string">SDAC</VSO:provider><data SOAP-ENC:arrayType="xsd:ur-type[1]" xsi:type="namesp4:DataResponse"><item><fileid SOAP-ENC:arrayType="xsd:string[1]" xsi:type="SOAP-ENC:Array"><item xsi:type="xsd:string">/archive/4/private/data/processed/eit/lz/2004/01/efz20040101.190507</item></fileid></item></data></VSO:response></SOAP-ENC:Array></namesp3:GetDataResponse></SOAP-ENV:Body></SOAP-ENV:Envelope>

GetData Request, with user information:

  POST http://localhost/cgi-bin/vsoi08.cgi HTTP/1.1
  Accept: text/xml
  Accept: multipart/*
  Content-Length: 1420
  Content-Type: text/xml; charset=utf-8
  SOAPAction: "http://virtualsolar.org/VSO/VSOi#GetData"
  
  <?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/1999/XMLSchema" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:namesp3="http://namespaces.soaplite.com/perl" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:VSO="http://virtualsolar.org/VSO/VSOi" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:apachens="http://xml.apache.org/xml-soap"><SOAP-ENV:Body><namesp5:GetData xmlns:namesp5="http://virtualsolar.org/VSO/VSOi"><VSO:request xsi:type="VSO:VSOiGetDataRequest"><request xsi:type="namesp3:GetDataRequest"><data SOAP-ENC:arrayType="xsd:ur-type[1]" xsi:type="namesp3:DataRequest"><item><VSO:provider xsi:type="xsd:string">SDAC</VSO:provider><fileid SOAP-ENC:arrayType="xsd:string[1]" xsi:type="SOAP-ENC:Array"><item xsi:type="xsd:string">/archive/4/private/data/processed/eit/lz/2004/01/efz20040101.190507</item></fileid></item></data><method SOAP-ENC:arrayType="xsd:string[1]" xsi:type="namesp3:Method"><item xsi:type="xsd:string">STAGING-TAR_GZ</item></method><info xsi:type="apachens:Map"><item><key xsi:type="xsd:string">email</key><value xsi:type="xsd:string">oneiros@grace.nascom.nasa.gov</value></item></info><VSO:sc_id xsi:null="1"/></request><VSO:version xsi:type="xsd:float">0.6</VSO:version></VSO:request></namesp5:GetData></SOAP-ENV:Body></SOAP-ENV:Envelope>

GetData Response, with status message:

  HTTP/1.1 200 OK
  Connection: close
  Date: Tue, 16 Nov 2004 18:09:16 GMT
  Server: Apache/1.3.29 (Darwin) mod_perl/1.29
  Content-Length: 1592
  Content-Type: text/xml; charset=utf-8
  Client-Date: Tue, 16 Nov 2004 18:09:20 GMT
  Client-Peer: 127.0.0.1:80
  Client-Response-Num: 1
  SOAPServer: SOAP::Lite/Perl/0.60
  
  <?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:VSO="http://virtualsolar.org/VSO/VSOi" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/1999/XMLSchema" xmlns:namesp4="http://namespaces.soaplite.com/perl" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"><SOAP-ENV:Body><namesp3:GetDataResponse xmlns:namesp3="http://virtualsolar.org/VSO/VSOi"><SOAP-ENC:Array SOAP-ENC:arrayType="VSO:GetDataResponse[1]" xsi:type="SOAP-ENC:Array"><VSO:response xsi:type="VSO:GetDataResponse"><info SOAP-ENC:arrayType="xsd:string[1]" xsi:type="SOAP-ENC:Array"><item xsi:type="xsd:string">email</item></info><method SOAP-ENC:arrayType="xsd:string[1]" xsi:type="SOAP-ENC:Array"><item xsi:type="xsd:string">STAGING-TAR_GZ</item></method><VSO:provider xsi:type="xsd:string">SDAC</VSO:provider><VSO:version xsi:type="xsd:float">0.7</VSO:version><data SOAP-ENC:arrayType="xsd:ur-type[1]" xsi:type="namesp4:DataResponse"><item><status xsi:type="xsd:string">VSO-D202 Accepted</status><fileid SOAP-ENC:arrayType="xsd:string[1]" xsi:type="SOAP-ENC:Array"><item xsi:type="xsd:string">/archive/4/private/data/processed/eit/lz/2004/01/efz20040101.190507</item></fileid><VSO:provider xsi:type="xsd:string">SDAC</VSO:provider><details xsi:type="xsd:string">Request Accepted.  Packaging should be completed within 15 minutes.</details></item></data></VSO:response></SOAP-ENC:Array></namesp3:GetDataResponse></SOAP-ENV:Body></SOAP-ENV:Envelope>

=cut