The parameters class holds the configuration for a connection. This includes gap handling strategy and server connection information. More...

#include <nds_connection.hh>

Public Member Functions
DLL_EXPORT connection::host_type	host () const
	Return the host that is currently connected/configured. More...

DLL_EXPORT connection::port_type	port () const
	Return the port number that is currently connected/configured. More...

DLL_EXPORT connection::protocol_type	protocol () const
	Return the protocol version configured/in use. More...

DLL_EXPORT std::string	get (const std::string &key) const
	Retreive the current parameter setting on a connection. More...

DLL_EXPORT bool	set (const std::string &key, const std::string &value)
	Change the default behavior of the connection. More...

DLL_EXPORT connection::parameters_type	parameter_list () const
	Return a list of supported parameters. More...

Detailed Description

The parameters class holds the configuration for a connection. This includes gap handling strategy and server connection information.

Member Function Documentation

std::string NDS::abi_0::parameters::get ( const std::string & key ) const

Retreive the current parameter setting on a connection.

Retreive the current value set for parameter. See set for documentation on the available parameters.

Parameters

[in] key Parameter name, as a string.

Returns: The parameter value, or "" if an invalid parameter is found.

connection::host_type NDS::abi_0::parameters::host ( ) const

Return the host that is currently connected/configured.

Returns: The hostname

NDS::connection::parameters_type NDS::abi_0::parameters::parameter_list ( ) const

Return a list of supported parameters.

Returns: a list of parameter names that may be used with set or get

connection::port_type NDS::abi_0::parameters::port ( ) const

Return the port number that is currently connected/configured.

Returns: The connection port number.

connection::protocol_type NDS::abi_0::parameters::protocol ( ) const

Return the protocol version configured/in use.

Returns: The protocol version (PROTOCOL_ONE|PROTOCOL_TWO)

bool NDS::abi_0::parameters::set	(	const std::string &	key,
		const std::string &	value
	)

Change the default behavior of the connection.

The connection object has a series of parameters that can be set. Currently the parameters that can be set are "ALLOW_DATA_ON_TAPE", "GAP_HANDLER", "ITERATE_USE_GAP_HANDLERS", "HOSTNAME", "PORT", "PROTOCOL_VERSION"

Parameters

The parameters can be broken down into multiple types. Those dealing with data access and those dealing with server selection.

"Parameters for data access"

ALLOW_DATA_ON_TAPE

NDS2 only. The NDS2 server may serve data that resides on a high latency storage layer, such as a tape system. This may lead to data requests taking minutes or hours to complete, depending on the load on the storage system. As of version 0.12 of the client the default is to raise an error when accessing data that is on a high latency storage layer. This allows the application to provide feedback (if needed) to a users regarding amount of time that a request may take. If this parameter is set to a true value ("True", "1", "yes") then an error will not be raised when requesting data on a high latency storage.

GAP_HANDLER

For a given request there may not be be data available to fill the request completely. This happens due to issues upstream of the NDS server. How this is handled is application specific. Setting the "GAP_HANDLER" parameter allows the application to specify what to do. This includes options such as abort, zero fill the data, ...

The gap handler will attempt to always return data if at all possible. You can detect the gaps by either using the "ABORT_HANDLER" which will raise an error on the presence of a gap, or by setting a gap handling policy that makes the "gap filled" data obvious (ie STATIC_HANDLER_NAN). The times where data is not returned should be limited to requesting a channel with a bad name (ie H1:THIS-CHANNEL_NEVER_EXISTED_ANYWHERE) or an I/O error.

Available GAP_HANDLERS

"ABORT_HANDLER" This aborts the request when a gap is found in the data.
"STATIC_HANDLER_ZERO" This zero fills any missing data.
"STATIC_HANDLER_ONE" This fills any missing data with ones.
"STATIC_HANDLER_NAN" This fills any missing data with NaN values (or zero for integer channels).
"STATIC_HANDLER_POS_INF" This fills any missing data with +infinity (or the maximum integer value for integer channels).
"STATIC_HANDLER_NEG_INF" This fills any missing data with -infinity (or the minimum integer value for integer channels).

ITERATE_USE_GAP_HANDLERS

The iterate methods have a special case. Unlike fetch operations which work on a single block, the iterate methods retrieve chunks of data that may not need to be contigous. Setting ITERATE_USE_GAP_HANDLERS to "false" configures the connection to simply skip any gaps in the data and only return the data that is available.

Please note that if you are asking for multiple channels that do not have identical gaps the NDS servers will return a data not found error if ITERATE_USE_GAP_HANDLERS is set to false.

the server

"Server Selection"

The follow parameters are used to help select the server. These are only used by the connection when a connection is made. Changes to these parameters after a connection is made do not change which server it is connected to. The connection object will update these fields if it makes a change (ie resolving PROTOCOL_TRY to a specific version).

Hostname

The host to connect to. If not specified this defaults to localhost.

Port

The port number to connect to. If not specified this defaults to NDS::connection::DEFAULT_PORT

PROTOCOL_VERSION

The protocol version to connect as. If not specified this defaults to NDS::connection::PROTOCOL_TRY