Detailed Description

A DRAMA 2 C++ Interface to the DRAMA Simple DITS Parameter System (SDP).

This class provides an interfaces to constructing, putting and fetching data from simple the SDP parameter system.

The only context kept in the object is a pointer to the DRAMA task, to allow the methods to take the DRAMA lock as needed.

#include "parsys.hh"

Public Member Functions
	ParSys (std::weak_ptr< Task > dramaTask)
	Create an object to access the parameter system. More...

void	CreateItem (sds::Id &item)
	Create a new parameter by inserting an SDS item. More...

template<typename T >
void	Get (const std::string &name, T *value)
	Fetch primitive value from parameter. More...

double	GetDouble (const std::string &name)
	If the Parameter contains scalar value, convert it to a double. More...

int	GetInt (const std::string &name)
	If the Parameter contains scalar value, convert it to integer. More...

long	GetLong (const std::string &name)
	If the Parameter contains scalar value, convert it to long integer. More...

std::string	GetString (const std::string &name)
	If the Parameter contains scalar value or a character string convert it to a string. More...

unsigned int	GetUInt (const std::string &name)
	If the Parameter contains scalar value, convert it to an unsigned integer. More...

unsigned long	GetULong (const std::string &name)
	If the Parameter contains scalar value, convert it to an unsigned long integer. More...

template<typename T >
void	Put (const std::string &name, T value)
	Update parameter from primitive value. More...

void	Put (const std::string &name, const std::string &value)
	Insert a string value into the parameter. More...

void	PutSdsCvt (const std::string &name, const sds::Id &value)
	Put an SDS item a named parameter. More...

void	PutSdsReplaceByCopy (const std::string &name, const sds::Id &value, const bool create=true)
	Put a SDS item a named parameter - replacing the existing item. More...

void	PutSdsReplaceByInsert (const std::string &name, sds::Id *value, const bool create=true)
	Put a SDS item a named parameter - replacing the existing value. More...

void	Update (const std::string &name)
	Indicate a parameter value has been updated by other means. More...

Constructor & Destructor Documentation

drama::ParSys::ParSys ( std::weak_ptr< Task > dramaTask )

inline

Create an object to access the parameter system.

Parameters

dramaTask The DRAMA Task we are part of. This is passed by pointer, but ParSys is not taking ownership of the subject object, which must continue to exist until the ParSys object is destroyed.

Member Function Documentation

void drama::ParSys::CreateItem ( sds::Id & item )

inline

Create a new parameter by inserting an SDS item.

The supplied SDS item is inserted into the specified parameter system. Any existing item of the same name is deleted.

See also: SdpCreateItem(); SdpInit(); SdsInsert()

Parameters

item	The Id of the SDS item to be inserted into the parameter system. This will be inserted using SdsInsert() so the name of the parameter will be the top level name and the structure must not be an external SDS structure.

References DramaTHROW.

template<typename T >

void drama::ParSys::Get	(	const std::string &	name,
		T *	value
	)

inline

Fetch primitive value from parameter.

If the named item exists within the parameter system, then fetch its value and convert it to the type of the template argument, if possible.

Supports the various primitive types - bool, char, short, unsigned short, INT32, UINT32, INT64, UINT64, float and double. Also the string representations char* and std::string.

Note - to access a parameter via an SDS Id, see the ParId class.

See also: ParId

Parameters

name	The name of the parameter to fetch
value	The value is returned here.

References DramaTHROW_S.

double drama::ParSys::GetDouble ( const std::string & name )

If the Parameter contains scalar value, convert it to a double.

Parameters

name	The name of the parameter to fetch

Returns: The converted value is returned here.

int drama::ParSys::GetInt ( const std::string & name )

If the Parameter contains scalar value, convert it to integer.

Parameters

name	The name of the parameter to fetch

Returns: The converted value is returned here.

long drama::ParSys::GetLong ( const std::string & name )

If the Parameter contains scalar value, convert it to long integer.

Parameters

name	The name of the parameter to fetch

Returns: The converted value is returned here.

std::string drama::ParSys::GetString ( const std::string & name )

If the Parameter contains scalar value or a character string convert it to a string.

Parameters

name	The name of the parameter to fetch

Returns: The converted value is returned here.

unsigned int drama::ParSys::GetUInt ( const std::string & name )

If the Parameter contains scalar value, convert it to an unsigned integer.

Parameters

name	The name of the parameter to fetch

Returns: The coverted value is returned here.

unsigned long drama::ParSys::GetULong ( const std::string & name )

If the Parameter contains scalar value, convert it to an unsigned long integer.

Parameters

name	The name of the parameter to fetch

Returns: The coverted value is returned here.

template<typename T >

void drama::ParSys::Put	(	const std::string &	name,
		T	value
	)

inline

Update parameter from primitive value.

If the named item exists within the parameter system, then convert the supplied value to the type of the parameter (if possible) and insert the value into the parameter.

Supports the various primitive types - bool, char, short, unsigned short, INT32, UINT32, INT64, UINT64, float and double. Also the string representations char* and std::string.

There are specific implementations (PutSds...()) for the various SDS cases, for cases where using ParSys is not appropriate.

Parameters

name	The name of the parameter to fetch
value	The new value for the parameter.

References DramaTHROW_S.

void drama::ParSys::Put	(	const std::string &	name,
		const std::string &	value
	)

inline

Insert a string value into the parameter.

Specialization for putting an std::string item into a structure Needed because we can't get this right using the Put template.

Parameters

name	The value to be inserted.
value	The new value for the parameter.

References DramaTHROW_S.

void drama::ParSys::PutSdsCvt	(	const std::string &	name,
		const sds::Id &	value
	)

Put an SDS item a named parameter.

An SDS item is written into a named parameter. Conversion is carried out using ArgCvt. This means that if both input and output items are scalar or strings, they will be converted if possible. Otherwise, a conversion error will occur.

If you are actually intending to update the value of a structured SDS item, you may instead want to use Get() to get an id for it and then write the value using drama::sds methods of that id. You must follow your update by a call to Update() to ensure parameter monitors are triggered.

See also: SdpPutSds(); SdpPutStruct(); ArgCvt()

Parameters

name	The name of the parameter.
value	The value to be inserted. T

void drama::ParSys::PutSdsReplaceByCopy	(	const std::string &	name,
		const sds::Id &	value,
		const bool	create = `true`
	)

Put a SDS item a named parameter - replacing the existing item.

An SDS item is written into a named parameter. Rather then convering the value with ArgCvt(), the supplied value will replace the existing parameter entirely.

In this version (const sds::Id & value) the value is copied using Id.Copy() and then the copy is inserted into the parameter system.

See also: SdpPutSds(); SdpPutStruct(); ArgCvt()

Parameters

name	The name of the parameter.
value	The value to be inserted.
create	If true, then the parameter is created if it does not already exist. Otherwise it must exist.

void drama::ParSys::PutSdsReplaceByInsert	(	const std::string &	name,
		sds::Id *	value,
		const bool	create = `true`
	)

Put a SDS item a named parameter - replacing the existing value.

An SDS item is written into a named parameter. Rather then converting the value with ArgCvt(), the supplied value will replace the existing parameter entirely.

In this version (sds::Id *value) the value SDS item passed in is inserted directly into the parameter, after being renamed to the specified name. It must not be an external SDS item.

See also: SdpPutSds(); SdpPutStruct(); ArgCvt()

Parameters

name	The name of the parameter.
value	The value to be inserted. Must not be an external item.
create	If true, then the parameter is created if it does not already exist. Otherwise it must exist.

void drama::ParSys::Update ( const std::string & name )

Indicate a parameter value has been updated by other means.

This method should be invoked if a parameter value has been updated using SDS directly. It tells the DRAMA Parameter monitoring system that the parameter has been updated and sends appropiate messages to all tasks which are monitoring the parameter. Use this if the ID is not available, but the name is known. Typically if the item was updated by Pointer.

Note that the best way to access parameters via SDS would normally be via the ParId class

See also: Sdp::GetSds; SdpUpdate(); ParId

Parameters

name	The name of the parameter.

The documentation for this class was generated from the following file:

parsys.hh

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation