DVS::IQuery Class Reference

Add a URI for the reader API to iterate over.

This method will only "set" the current URI. In the future we will support multiple URIs queried at once.

IMPORTANT: Calling this will invalidate any objects returned from the query and any chained queries.

Errors:

• DVS_NONE: Success
• DVS_PARAM_NULL: uri passed in was nullptr
• DVS_QUERY_HAS_CHILDREN: Cannot add a uri to a query which already has children
• DVS_QUERY_INVALID_URI: URI passed in did not parse, invalid uri
• DVS_QUERY_INVALID_FILTER: Filter in URI did not parse, invalid filter

Parameters

[in]

uri

URI of a cache. See Cache URIs

Returns

dvs_ret DVS_NONE on success, otherwise see method description

The filter method will allocate a new chained query with the passed in filter appended to it.

The filter method allocates a new chained query with the passed in filter appended to it. The current query is not modified. This query however is a chained child of the current query meaning that any changes to the parent will invalidate the objects of the child. IQuery::release() will release any child chained queries created from the it.

This lets a user create a top level query, say for a specific dataset name. Then have multiple chained queries that filter for specific parts etc which can be iterated over in parallel.

IMPORTANT: Chained queries will have all of their objects destroyed when a parent query changes.

Parameters

[in]

filter

the filter to append to the new chained child query. See Query Stanzas.

Returns

DVS::IQuery* a pointer to a newly allocated chained child query

Get an array of the number of chunks for every rank for this query.

This method will return an array of max number of chunks for every rank. The size of the buffer needed can be retrieved from IQuery::get_num_chunks_per_rank(). These values correspond to the ranks returned from IQuery::get_ranks(). Since there might be multiple datasets in the query this will return the max for each rank across the datasets and parts.

This call will return all of the chunk information for every rank returned from IQuery::get_ranks().

Errors:

• DVS_NONE: Success
• DVS_PARAM_NULL: chunks passed in is nullptr
• DVS_INVALID_CACHE: Problem accessing cache
• DVS_DATA_FAILED_LOAD: Problem reading cache, data bad/corrupt

Parameters

[out]

chunks

buffer to save chunk information in, an array of the chunks for each rank

Returns

dvs_ret DVS_NONE if success, otherwise see method description

Get the dataset object.

IMPORTANT: This object will be destroyed if this query or parent queries' filters are modified.

Parameters

[in]

index

index of the dataset to retrieve

Returns

DVS::IDataset* dataset for the index, or nullptr if not found

Get if the hash is available in the blobstore.

Checks the blobstore to see if the hash is available or not. This is mainly used for validation purposes.

Errors:

• DVS_NONE: Success
• DVS_PARAM_NULL: hash passed in nullptr
• DVS_INVALID_CACHE: Invalid cache, bad data
• DVS_INVALID_HASH: Hash passed in invalid

Parameters

[in]	hash	hash to check availability of, retrieved via DVS::IHash::get_hash() or DVS::IVarHash::get_var_hash()
[out]	available	if success, returns true if found in blobstore, else false

Returns

dvs_ret DVS_NONE on success, else see method description

Get the mesh chunk based on the index.

IMPORTANT: This object will be destroyed if this query or parent queries' filters are modified.

Parameters

[in]

index

the index of the mesh chunk to retrieve

Returns

DVS::IMeshChunk* the mesh chunk for the index, or nullptr if not found

Get the number of chunks for each rank.

This method returns the size of the buffer needed to pass in for get_chunks_per_rank. This will be of the same size as IQuery::get_num_ranks().

This call will return all of the chunk information for every rank returned from IQuery::get_ranks().

Errors:

• DVS_NONE: Success
• DVS_INVALID_CACHE: Problem accessing cache
• DVS_DATA_FAILED_LOAD: Problem reading cache, data bad/corrupt

Parameters

[out]

num_chunks

if success returns the size of the buffer to allocate for IQuery::get_chunks_per_rank()

Returns

dvs_ret DVS_NONE on success, otherwise see method description

Get the number of datasets objects.

IMPORTANT: The number of datasets will be invalid if this query or any parent queries' filters are modified.

Errors:

• DVS_NONE: Success
• DVS_INVALID_CACHE: Problem accessing cache
• DVS_DATA_FAILED_LOAD: Problem reading cache, data bad/corrupt

Parameters

[out]

num_datasets

if success, returns the number of datasets for this query

Returns

DVS_NONE on success, else see method description

Get the number of mesh chunks for this query.

NOT YET IMPLEMENTED

IMPORTANT: The number of mesh chunks will be invalid if this query or any parent queries' filters are modified.

Errors:

• DVS_NONE: Success
• DVS_INVALID_CACHE: Problem accessing cache
• DVS_DATA_FAILED_LOAD: Problem reading cache, data bad/corrupt
• DVS_QUERY_INVALID_FILTER: Invalid filter for query
• DVS_METADATA_ERROR: Error loading metadata

Parameters

[out]

num_mesh_chunks

if success, returns the number of mesh chunks for this query

Returns

dvs_ret dvs_ret DVS_NONE on success, else see method description

Get the number of parts for this query.

IMPORTANT: The number of parts will be invalid if this query or any parent queries' filters are modifed.

Errors:

• DVS_NONE: Success
• DVS_INVALID_CACHE: Problem accessing cache
• DVS_DATA_FAILED_LOAD: Problem reading cache, data bad/corrupt

Parameters

[out]

num_parts

if success, returns the number of parts for this query

Returns

dvs_ret DVS_NONE on success, else see method description

Get the number of plot chunks for this query.

NOT YET IMPLEMENTED

IMPORTANT: The number of plot chunks will be invalid if this query or any parent queries' filters are modified.

Errors:

• DVS_NONE: Success
• DVS_INVALID_CACHE: Problem accessing cache
• DVS_DATA_FAILED_LOAD: Problem reading cache, data bad/corrupt
• DVS_QUERY_INVALID_FILTER: Invalid filter for query
• DVS_METADATA_ERROR: Error loading metadata

Parameters

[out]

num_plot_chunks

if success, returns the number of plot chunks for this query

Returns

dvs_ret dvs_ret DVS_NONE on success, else see method description

Get the number of plots for this query.

IMPORTANT: The number of plots will be invalid if this query or any parent queries' filters are modifed.

Errors:

• DVS_NONE: Success
• DVS_INVALID_CACHE: Problem accessing cache
• DVS_DATA_FAILED_LOAD: Problem reading cache, data bad/corrupt

Parameters

[out]

num_plots

if success, returns the number of plots for this query

Returns

dvs_ret dvs_ret DVS_NONE on success, else see method description

Get the number of ranks for this filtered query.

This call will return all of the unique ranks across all datasets. I.E. if you are loading 2 datasets one with ranks: 0, 1, 2 and one with 0, 1, 2, 3, 4, this will return 5 representing 0,1,2,3,4.

Errors:

• DVS_NONE: Success
• DVS_INVALID_CACHE: Problem accessing cache
• DVS_DATA_FAILED_LOAD: Problem reading cache, data bad/corrupt

Parameters

[out]

num_ranks

the size of the buffer to allocate for IQuery::get_ranks()

Returns

dvs_ret DVS_NONE on success, otherwise see method description

Get the num servers object.

Get the number of servers the cache in the uri was written with.

Errors:

• DVS_NONE: Success
• DVS_PARAM_NULL: uri passed in was nullptr
• DVS_INVALID_CACHE: uri passed in was invalid or cache isn't accessible
• DVS_CACHE_MISSING_SERVERS: Cache has a gap in the number of servers, bad cache?
• DVS_CACHE_EMPTY: No server folders in cache
• DVS_UNKNOWN: Internal unhandled case

Parameters

[in]	uri	URI of a cache. See Cache URIs
[out]	num_servers	number of servers this cache was written with

Returns

dvs_ret DVS_NONE on success, otherwise see method description

Get the number of timesteps.

NOT YET IMPLEMENTED

IMPORTANT: The number of timesteps will be invalid if this query or any parent queries' filters are modified.

Errors:

• DVS_NONE: Success
• DVS_INVALID_CACHE: Problem accessing cache
• DVS_DATA_FAILED_LOAD: Problem reading cache, data bad/corrupt
• DVS_QUERY_INVALID_FILTER: Invalid filter for query
• DVS_METADATA_ERROR: Error loading metadata

Parameters

[out]

num_timesteps

if success, returns the number of timesteps to allocate for IQuery::get_timesteps()

Returns

dvs_ret dvs_ret DVS_NONE on success, else see method description

Get the number of variables for this query.

IMPORTANT: The number of variables will be invalid if this query or any parent queries' filters are modifed.

Errors:

• DVS_NONE: Success
• DVS_INVALID_CACHE: Problem accessing cache
• DVS_DATA_FAILED_LOAD: Problem reading cache, data bad/corrupt

Parameters

[out]

num_vars

if success, returns the number of variables for this query

Returns

dvs_ret dvs_ret DVS_NONE on success, else see method description

Get the part based on the index.

IMPORTANT: This object will be destroyed if this query or parent queries' filters are modified.

Parameters

[in]

index

index of the part to retrieve

Returns

DVS::IObject* part based on the index, or nullptr if not found

Get the plot object based on the index.

IMPORTANT: This object will be destroyed if this query or parent queries' filters are modified.

Parameters

index

index of the plot to retrieve

Returns

DVS::IObject* plot based on the index, or nullptr if not found

Get the plot chunk based on the index.

IMPORTANT: This object will be destroyed if this query or parent queries' filters are modified.

Parameters

[in]

index

index of the plot chunk to retrieve

Returns

DVS::IPlotChunk* the plot chunk based on the index, or nullptr if not found

Get the unique ranks for this filtered query.

This call will return all of the unique ranks across all datasets. I.E. if you are loading 2 datasets one with ranks: 0, 1, 2 and one with 0, 1, 2, 3, 4, this will return 5 representing 0,1,2,3,4.

Errors:

• DVS_NONE: Success
• DVS_PARAM_NULL: ranks passed in is nullptr
• DVS_INVALID_CACHE: Problem accessing cache
• DVS_DATA_FAILED_LOAD: Problem reading cache, data bad/corrupt

Parameters

[out]

ranks

an array of the unique ranks for this query, call IQuery::get_num_ranks() for buffer size to allocate

Returns

dvs_ret DVS_NONE on success, otherwise see method description

Get the timesteps object.

NOT YET IMPLEMENTED

IMPORTANT: The timesteps will be invalid if this query or any parent queries' filters are modified.

Errors:

• DVS_NONE: Success
• DVS_PARAM_NULL: timesteps param is nullptr
• DVS_INVALID_CACHE: Problem accessing cache
• DVS_DATA_FAILED_LOAD: Problem reading cache, data bad/corrupt
• DVS_QUERY_INVALID_FILTER: Invalid filter for query
• DVS_METADATA_ERROR: Error loading metadata

Parameters

[out]

timesteps

buffer for timesteps to be saved in, call IQuery::get_num_timesteps() to determine size

Returns

dvs_ret DVS_NONE on success, else see method description

Get the variable object based on the index.

IMPORTANT: This object will be destroyed if this query or parent queries' filters are modified.

Parameters

[in]

index

index of the variable to retrieve

Returns

DVS::IVar* variable based on the index, or nullptr if not found

Get variable values for dataset and part objects.

Dataset (Case) or part objects can have variable values per timestep. This method retrieves those values or returns if they do not exist. There does not need to be a value set for every part variable on every part. DVS_NO_DATA will be returned in this case.

Error Codes:

• DVS_NONE: No error
• DVS_PARAM_NULL: Null param passed in
• DVS_PARAM_INVALID_VAR: Invalid variable passed in, should not be possible
• DVS_PARAM_INVALID_VAR_LOC: Variable passed in not a case or part variable
• DVS_PARAM_INVALID_OBJECT_TYPE: Object passed in not a case or part object
• DVS_PARAM_INVALID_OBJECT: Invalid object passed in, should not be possible
• DVS_PARAM_INVALID_TIME: Timestep does not exist for the dataset the object belongs to
• DVS_PARAM_OBJECT_DATASET_MISMATCH: Object and variable are from different datasets

Parameters

[in]	object	The case/dataset or part object to find values for
[in]	var	the variable to retrieve the data for
[in]	time	the time value to retrieve the variable data for
[out]	values	the array of data to return, should be of size DVS::IVar::get_float_count_per_value()

Returns

dvs_ret DVS_NONE if no errors, DVS_NO_DATA if no data found, otherwise see method description

Release the memory of the query.

This will release the memory of the query, any objects returned from it (i.e. parts/plots/variables) and release the memory of any chained queries.

Set the logger object.

Set a logger interface for the client to use. This object will have DVS::ILogger::release() invoked on it. If release() is not implemented the memory should be destroyed by the caller after the query is released.

Parameters

[in]

logger

logger to use, will be released if DVS::ILogger::release() is implemented

Set a filter based on the server number and a modulus.

Data in DVS is normally splitup between multiple servers. This method lets you setup the parallelism paradigm for reading in the server data. I.E. if the data was written with 4 servers but you want to read it back in with 2 servers you should have one reader use set_server_mod(0, 2) and the other use set_server_mod(1, 2). This will round robin the data so reader "0" will reader the data from 0 and 2 and server "1" will read the data from 1 and 3. To set it so that a server will read only its data set server_mod=0.

Use get_num_servers() to determine the number of servers to use

Parameters

[in]	server_num	the base server number to read from the cache
[in]	server_mod	the modulus for round-robining server data between queries/readers