A set of utility functions for manipulating optional static metadata. More...

Functions
XCoordinateSystem *	smaxCreateCoordinateSystem (int nAxis)
void	smaxDestroyCoordinateSystem (XCoordinateSystem *coords)
XCoordinateAxis *	smaxGetCoordinateAxis (const char *id, int n)
XCoordinateSystem *	smaxGetCoordinateSystem (const char table, const char key)
char *	smaxGetDescription (const char table, const char key)
char *	smaxGetUnits (const char table, const char key)
char *	smaxPullMeta (const char meta, const char table, const char key, int len)
double	smaxPullTime (const char table, const char key)
XType	smaxPullTypeDimension (const char table, const char key, int ndim, int sizes)
int	smaxPushMeta (const char meta, const char table, const char key, const char value)
int	smaxSetCoordinateAxis (const char id, int n, const XCoordinateAxis axis)
int	smaxSetCoordinateSystem (const char table, const char key, const XCoordinateSystem *coords)
int	smaxSetDescription (const char table, const char key, const char *description)
int	smaxSetUnits (const char table, const char key, const char *unit)

Detailed Description

A set of utility functions for manipulating optional static metadata.

Date: Mar 24, 2020

Author: Attila Kovacs

Function Documentation

◆ smaxCreateCoordinateSystem()

XCoordinateSystem * smaxCreateCoordinateSystem ( int nAxis )

Creates a coordinate system with the desired dimension, and standard Cartesian coordinates with no labels, or units specified (NULL).

Parameters

nAxis Dimension of the coordiante system, i.e. number of axes.

Returns: Pointer to the new coordinate system structure, or NULL if the coordiate system could not be created as specified.

See also: smaxDestroyCoordinateSystem()

References XCoordinateSystem::axis, XCoordinateSystem::nAxis, and XCoordinateAxis::step.

◆ smaxDestroyCoordinateSystem()

void smaxDestroyCoordinateSystem ( XCoordinateSystem * coords )

Deallocates a coordinate system structure.

Parameters

coords Pointer to the coordinate system to discard.

See also: smaxCreateCoordinateSystem()

References XCoordinateSystem::axis.

◆ smaxGetCoordinateAxis()

XCoordinateAxis * smaxGetCoordinateAxis	(	const char *	id,
		int	n )

Returns the n'th coordinate axis for a given SMA-X coordinate system table id.

Parameters

id	Fully qualified SMA-X coordinate system ID.
n	The (0-based) index of the coordinate axis

Returns: Pointer to a newly allocated XCoordinateAxis structure or NULL if the axis is undefined, or could not be retrieved from the database.

See also: smaxSetCoordinateAxis()

References XCoordinateAxis::name, XCoordinateAxis::refIndex, XCoordinateAxis::refValue, smaxError(), smaxGetRedis(), XCoordinateAxis::step, and XCoordinateAxis::unit.

◆ smaxGetCoordinateSystem()

XCoordinateSystem * smaxGetCoordinateSystem	(	const char *	table,
		const char *	key )

Returns the coordinate system, if any, associated to a given SMA-X variable.

Parameters

table	Hash table name.
key	Variable / field name in table.

Returns: A newly allocated coordinate system structure, or NULL.

See also: smaxSetCoordinateSystem(); smaxGetCoordinateAxis()

References XCoordinateSystem::axis, META_COORDS, XCoordinateSystem::nAxis, and smaxGetCoordinateAxis().

◆ smaxGetDescription()

char * smaxGetDescription	(	const char *	table,
		const char *	key )

Returns a concise description of a variable.

Parameters

table	Hash table name.
key	Variable / field name in table.

Returns: Variable description or NULL or empty string if the variable has no description assiciated with it.

See also: smaxSetDescription()

References META_DESCRIPTION, and smaxPullMeta().

◆ smaxGetUnits()

char * smaxGetUnits	(	const char *	table,
		const char *	key )

Returns the physical unit name, if any, for the given variable.

Parameters

table	Hash table name.
key	Variable / field name in table.

Returns: Unit name (e.g. "W / Hz"), or NULL or empty string if the variable has no designated physical unit.

See also: smaxSetUnits()

References META_UNIT, and smaxPullMeta().

◆ smaxPullMeta()

char * smaxPullMeta	(	const char *	meta,
		const char *	table,
		const char *	key,
		int *	len )

Retrieves a metadata string value for a given variable from the database

Parameters

	meta	Root meta table name, usually something like "<metaname>".
	table	Hash table name.
	key	Variable / field name in table.
[out]	len	The length of the returned string (>=0), or else an error code (<0).

Returns: The string metadata value or NULL.

See also: setPushMeta()

References smaxError(), and smaxGetRedis().

◆ smaxPullTime()

double smaxPullTime	(	const char *	table,
		const char *	key )

Retrieves the timestamp for a given variable from the database.

Parameters

[in]	table	Hash table name (or NULL if key is an aggregate ID).
[in]	key	Variable / field name in table.

Returns: (s) UNIX timestamp, as fractional seconds since 1 Jan 1970, or NAN if there was an error.

See also: setPushMeta()

References SMAX_TIMESTAMPS, and smaxPullMeta().

◆ smaxPullTypeDimension()

XType smaxPullTypeDimension	(	const char *	table,
		const char *	key,
		int *	ndim,
		int *	sizes )

Retrieves the timestamp for a given variable from the database.

Parameters

[in]	table	Hash table name (or NULL if key is an aggregate ID).
[in]	key	Variable / field name in table.
[out]	ndim	Pointer to integer in which to return the dimensionality of the variable, or NULL if not requested.
[out]	sizes	Array to store sizes along each dimension, which should hold X_MAX_DIMS integers, or NULL if dimensions are not requested.

Returns: Type of data stored under the specified table/key ID.

See also: setPushMeta()

References SMAX_DIMS, SMAX_TYPES, smaxPullMeta(), and smaxTypeForString().

◆ smaxPushMeta()

int smaxPushMeta	(	const char *	meta,
		const char *	table,
		const char *	key,
		const char *	value )

Adds/updates metadata associated with an SMA-X variable. The data will be pushed via the Redis pipeline channel.

Parameters

meta	Root meta table name, usually something like "<metaname>".
table	Hash table name.
key	Variable / field name in table.
value	Metadata string value.

Returns: X_SUCCESS (0) if the metadata was successfully retrieved X_INCOMPLETE if the meatdata was successfully written but an update notification was not sent or else the return value of redisxSetValue()

See also: smaxPullMeta(), redisxSetValue()

References smaxError(), smaxGetProgramID(), and smaxGetRedis().

◆ smaxSetCoordinateAxis()

int smaxSetCoordinateAxis	(	const char *	id,
		int	n,
		const XCoordinateAxis *	axis )

Defines the n'th coordinate axis for a given SMA-X coordinate system table id.

Parameters

id	Fully qualified SMA-X coordinate system ID.
n	The (0-based) index of the coordinate axis
axis	Pointer to the structure describing the coordinate axis.

Returns: X_SUCCESS (0) if the coordinate axis was successfully set in the database. or else the return value of redisxMultiSet().

See also: smaxSetCoordinateAxis(), redisxMultiSet()

References RedisEntry::key, XCoordinateAxis::name, XCoordinateAxis::refIndex, XCoordinateAxis::refValue, smaxGetRedis(), XCoordinateAxis::step, XCoordinateAxis::unit, and RedisEntry::value.

◆ smaxSetCoordinateSystem()

int smaxSetCoordinateSystem	(	const char *	table,
		const char *	key,
		const XCoordinateSystem *	coords )

Sets the coordinate system metadata for data in the database.

Parameters

table	Hash table name.
key	Variable / field name in table.
coords	Pointer to the coordinate system structure associated to this variable.

Returns: X_SUCCESS (0) if the coordinate system was successfully sent to SMA-X or else the first error encountered by xSetCoordinateAxis()

See also: smaxGetCoordinateSystem(); smaxSetCoordinateAxis()

References XCoordinateSystem::axis, META_COORDS, XCoordinateSystem::nAxis, and smaxSetCoordinateAxis().

◆ smaxSetDescription()

int smaxSetDescription	(	const char *	table,
		const char *	key,
		const char *	description )

Sets the static description for a given SMA-X variable.

Parameters

table	Hash table name.
key	Variable / field name in table.
description	Concise but descriptive summary of the meaning of the variable.

Returns: X_SUCCESS (0) If successful or else the return value of smaxPushMeta()

See also: smaxSetDescription(), smaxPushMeta()

References META_DESCRIPTION, and smaxPushMeta().

◆ smaxSetUnits()

int smaxSetUnits	(	const char *	table,
		const char *	key,
		const char *	unit )

Sets the physical unit name for a given SMA-X variable.

Parameters

table	Hash table name.
key	Variable / field name in table.
unit	Standard unit specification, e.g. "W / Hz" or "W Hz**{-1}".

Returns: X_SUCCESS (0) If successful or else the return value of smaxPushMeta()

See also: smaxGetUnits(), smaxPushMeta()

References META_UNIT, and smaxPushMeta().

Functions

Detailed Description

Function Documentation

◆ smaxCreateCoordinateSystem()

◆ smaxDestroyCoordinateSystem()

◆ smaxGetCoordinateAxis()

◆ smaxGetCoordinateSystem()

◆ smaxGetDescription()

◆ smaxGetUnits()

◆ smaxPullMeta()

◆ smaxPullTime()

◆ smaxPullTypeDimension()

◆ smaxPushMeta()

◆ smaxSetCoordinateAxis()

◆ smaxSetCoordinateSystem()

◆ smaxSetDescription()

◆ smaxSetUnits()