smax.h File Reference

Data Structures
struct	XCoordinateAxis
	Structure that defines a coordinate axis in an XCoordinateSystem for an SMA-X data array. More...
struct	XCoordinateSystem
	Structure that defines a coordinate system, with one or more XCoordinateAxis. More...
struct	XMessage
	SMA-X program message. More...
struct	XMeta
	SMA-X standard metadata. More...
struct	XSyncPoint
	Synchronization point that can be waited upon when queueing pipelined pulls. More...

Macros
#define	META_COORDS   "<coords>"
	Redis hash table in which data coordinates system descriptions are stored.
#define	META_DESCRIPTION   "<descriptions>"
	Redis hash table in which variable descriptions are stored.
#define	META_UNIT   "<units>"
	Redis hash table in which data physical unit names are stored.
#define	SMAX_DEFAULT_HOSTNAME   "smax"
	Host name of Redis server used for SMA-X.
#define	SMAX_DEFAULT_MAX_QUEUED   1024
	Maximum number of pull requests allowed to be queued at once.
#define	SMAX_DEFAULT_PIPELINE_ENABLED   TRUE
	Whether pipelining is enabled by default.
#define	SMAX_DIMS   "<dims>"
	Redis meta table where variable dimensions are stored.
#define	SMAX_MAJOR_VERSION   0
	API major version.
#define	SMAX_MINOR_VERSION   9
	API minor version.
#define	SMAX_MSG_DEBUG   "debug"
	Program debug messages (also e.g. traces).
#define	SMAX_MSG_DETAIL   "detail"
	Additional program detail provided (e.g. for verbose mode)
#define	SMAX_MSG_ERROR   "error"
	Program errors.
#define	SMAX_MSG_INFO   "info"
	Informational program message.
#define	SMAX_MSG_PROGRESS   "progress"
	Program progress update.
#define	SMAX_MSG_STATUS   "status"
	Program status update.
#define	SMAX_MSG_WARNING   "warning"
	Program warnings.
#define	SMAX_ORIGIN_LENGTH   80
	(bytes) Maximum length of 'origin' meatdata, including termination.
#define	SMAX_ORIGINS   "<origins>"
	Redis meta table where variable origins are stored.
#define	SMAX_PATCHLEVEL   0
	Integer sub version of the release.
#define	SMAX_PIPE_READ_TIMEOUT_MILLIS   3000
	(ms) Timeout for pipelined (queued) pull requests
#define	SMAX_READS   "<reads>"
	Redis meta table where the number of times a variable has been read is stored.
#define	SMAX_RECONNECT_RETRY_SECONDS   3
	(s) Time between reconnection attempts on lost SMA-X connections.
#define	SMAX_RELEASE_STRING   "-devel"
	Additional release information in version, e.g. "-1", or "-rc1".
#define	SMAX_RESTORE_QUEUE_ON_RECONNECT   TRUE
	Whether read queues are restored if SMA-X is disconnected/reconnected.
#define	SMAX_SCRIPTS   "scripts"
	Redis table in which the built-in LUA script hashes are stored.
#define	SMAX_TIMESTAMPS   "<timestamps>"
	Redis meta table where variable timestamps are stored.
#define	SMAX_TYPES
	Redis meta table where variable types are stored.
#define	SMAX_UPDATES   SMAX_UPDATES_ROOT X_SEP
	PUB/SUB message channel heade for hash table updates.
#define	SMAX_UPDATES_LENGTH
	String length of SMA-X update channel prefix.
#define	SMAX_UPDATES_ROOT   "smax"
	Notification class for SMA-X updates.
#define	SMAX_VERSION_STRING
#define	SMAX_WRITES   "<writes>"
	Redis meta table where the number of times a variable has been written is stored.
#define	X_META_INIT   { 0, X_UNKNOWN, -1, {0}, -1, {'\0'}, {0}, 0 }

Functions
int	smax2xField (XField *f)
int	smax2xStruct (XStructure *s)
int	smaxAddConnectHook (void(*setupCall)(void))
int	smaxAddDefaultMessageProcessor (const char *host, const char *prog, const char *type)
int	smaxAddDisconnectHook (void(*cleanupCall)(void))
int	smaxAddMessageProcessor (const char *host, const char *prog, const char *type, void(*f)(XMessage *))
int	smaxAddSubscriber (const char *stem, RedisSubscriberCall f)
int	smaxConnect ()
int	smaxConnectTo (const char *server)
XField *	smaxCreate1DField (const char *name, XType type, int size, const void *value)
XField *	smaxCreateBooleanField (const char *name, boolean value)
XCoordinateSystem *	smaxCreateCoordinateSystem (int nAxis)
XField *	smaxCreateDoubleField (const char *name, double value)
XField *	smaxCreateField (const char *name, XType type, int ndim, const int *sizes, const void *value)
XField *	smaxCreateIntField (const char *name, int value)
XField *	smaxCreateLongField (const char *name, long long value)
XMeta *	smaxCreateMeta ()
XField *	smaxCreateScalarField (const char *name, XType type, const void *value)
XField *	smaxCreateStringField (const char *name, const char *value)
XSyncPoint *	smaxCreateSyncPoint ()
void	smaxDestroyCoordinateSystem (XCoordinateSystem *coords)
void	smaxDestroySyncPoint (XSyncPoint *sync)
int	smaxDisconnect ()
int	smaxError (const char *func, int errorCode)
const char *	smaxErrorDescription (int code)
int	smaxGetArrayField (const XStructure *s, const char *name, void *dst, XType type, int count)
boolean	smaxGetBooleanField (const XStructure *s, const char *name, boolean defaultValue)
XCoordinateAxis *	smaxGetCoordinateAxis (const char *id, int n)
XCoordinateSystem *	smaxGetCoordinateSystem (const char *table, const char *key)
char *	smaxGetDescription (const char *table, const char *key)
double	smaxGetDoubleField (const XStructure *s, const char *name, double defaultValue)
char *	smaxGetHostName ()
char **	smaxGetKeys (const char *table, int *n)
int	smaxGetLazyCached (const char *table, const char *key, XType type, int count, void *value, XMeta *meta)
int	smaxGetLazyUpdateCount (const char *table, const char *key)
long long	smaxGetLongField (const XStructure *s, const char *name, long long defaultValue)
int	smaxGetMetaCount (const XMeta *m)
char *	smaxGetProgramID ()
char *	smaxGetRawField (const XStructure *s, const char *name, char *defaultValue)
Redis *	smaxGetRedis ()
char *	smaxGetScriptSHA1 (const char *scriptName, int *status)
int	smaxGetServerTime (struct timespec *t)
double	smaxGetTime (const char *timestamp)
char *	smaxGetUnits (const char *table, const char *key)
int	smaxIsConnected ()
boolean	smaxIsPipelined ()
boolean	smaxIsResilient ()
boolean	smaxIsVerbose ()
int	smaxKeyCount (const char *table)
int	smaxLazyCache (const char *table, const char *key, XType type)
int	smaxLazyEnd (const char *table, const char *key)
int	smaxLazyFlush ()
int	smaxLazyPull (const char *table, const char *key, XType type, int count, void *value, XMeta *meta)
int	smaxLazyPullChars (const char *table, const char *key, char *buf, int n)
double	smaxLazyPullDouble (const char *table, const char *key)
double	smaxLazyPullDoubleDefault (const char *table, const char *key, double defaultValue)
long long	smaxLazyPullLong (const char *table, const char *key, long long defaultValue)
char *	smaxLazyPullString (const char *table, const char *key)
int	smaxLazyPullStruct (const char *id, XStructure *s)
int	smaxParseTime (const char *timestamp, time_t *secs, long *nanosecs)
int	smaxPull (const char *table, const char *key, XType type, int count, void *value, XMeta *meta)
double	smaxPullDouble (const char *table, const char *key)
double	smaxPullDoubleDefault (const char *table, const char *key, double defaultValue)
double *	smaxPullDoubles (const char *table, const char *key, XMeta *meta, int *n)
int	smaxPullInt (const char *table, const char *key, int defaultValue)
int *	smaxPullInts (const char *table, const char *key, XMeta *meta, int *n)
long long	smaxPullLong (const char *table, const char *key, long long defaultValue)
long long *	smaxPullLongs (const char *table, const char *key, XMeta *meta, int *n)
char *	smaxPullMeta (const char *meta, const char *table, const char *key, int *status)
char *	smaxPullRaw (const char *table, const char *key, XMeta *meta, int *status)
char *	smaxPullString (const char *table, const char *key)
char **	smaxPullStrings (const char *table, const char *key, XMeta *meta, int *n)
XStructure *	smaxPullStruct (const char *name, XMeta *meta, int *status)
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	smaxQueue (const char *table, const char *key, XType type, int count, void *value, XMeta *meta)
int	smaxQueueCallback (void(*f)(void *), void *arg)
int	smaxReconnect ()
int	smaxReleaseWaits ()
int	smaxRemoveConnectHook (void(*setupCall)(void))
int	smaxRemoveDisconnectHook (void(*cleanupCall)(void))
int	smaxRemoveMessageProcessor (int id)
int	smaxRemoveSubscribers (RedisSubscriberCall f)
void	smaxResetMeta (XMeta *m)
int	smaxSendDebug (const char *msg,...)
int	smaxSendDetail (const char *msg,...)
int	smaxSendError (const char *msg,...)
int	smaxSendInfo (const char *msg,...)
int	smaxSendProgress (double fraction, const char *msg,...)
int	smaxSendStatus (const char *msg,...)
int	smaxSendWarning (const char *msg,...)
int	smaxSetAuth (const char *username, const char *password)
int	smaxSetCoordinateAxis (const char *id, int n, const XCoordinateAxis *axis)
int	smaxSetCoordinateSystem (const char *table, const char *key, const XCoordinateSystem *coords)
int	smaxSetDB (int idx)
int	smaxSetDescription (const char *table, const char *key, const char *description)
void	smaxSetHostName (const char *name)
int	smaxSetMaxPendingPulls (int n)
void	smaxSetMessageSenderID (const char *id)
void	smaxSetOrigin (XMeta *m, const char *origin)
int	smaxSetPipelineConsumer (void(*f)(RESP *))
int	smaxSetPipelined (boolean isEnabled)
void	smaxSetResilient (boolean value)
void	smaxSetResilientExit (boolean value)
int	smaxSetServer (const char *host, int port)
int	smaxSetTcpBuf (int size)
int	smaxSetUnits (const char *table, const char *key, const char *unit)
void	smaxSetVerbose (boolean value)
int	smaxShare (const char *table, const char *key, const void *value, XType type, int count)
int	smaxShareArray (const char *table, const char *key, const void *value, XType type, int ndim, const int *sizes)
int	smaxShareBoolean (const char *table, const char *key, boolean value)
int	smaxShareBooleans (const char *table, const char *key, const boolean *values, int n)
int	smaxShareBytes (const char *table, const char *key, const char *values, int n)
int	smaxShareDouble (const char *table, const char *key, double value)
int	smaxShareDoubles (const char *table, const char *key, const double *values, int n)
int	smaxShareField (const char *table, const XField *f)
int	smaxShareFloats (const char *table, const char *key, const float *values, int n)
int	smaxShareHex (const char *table, const char *key, long long value)
int	smaxShareInt (const char *table, const char *key, long long value)
int	smaxShareInts (const char *table, const char *key, const int *values, int n)
int	smaxShareLongs (const char *table, const char *key, const long long *values, int n)
int	smaxShareShorts (const char *table, const char *key, const short *values, int n)
int	smaxShareString (const char *table, const char *key, const char *sValue)
int	smaxShareStrings (const char *table, const char *key, const char **sValues, int n)
int	smaxShareStruct (const char *id, const XStructure *s)
int	smaxStringToValues (const char *str, void *value, XType type, int count, int *parsed)
char *	smaxStringType (XType type)
int	smaxSubscribe (const char *table, const char *key)
int	smaxSync (XSyncPoint *sync, int timeoutMillis)
int	smaxTimestamp (char *buf)
int	smaxTimeToString (const struct timespec *time, char *buf)
	*‍/
XType	smaxTypeForString (const char *type)
int	smaxUnpackStrings (const char *data, int len, int count, char **dst)
int	smaxUnsubscribe (const char *table, const char *key)
char *	smaxValuesToString (const void *value, XType type, int count, char *trybuf, int trylength)
int	smaxWaitOnAnySubscribed (char **changedTable, char **changedKey, int timeout)
int	smaxWaitOnSubscribed (const char *table, const char *key, int timeout)
int	smaxWaitOnSubscribedGroup (const char *matchTable, char **changedKey, int timeout)
int	smaxWaitOnSubscribedVar (const char *matchKey, char **changedTable, int timeout)
int	smaxWaitQueueComplete (int timeoutMillis)
int	x2smaxField (XField *f)
int	x2smaxStruct (XStructure *s)

Detailed Description

Date

Jan 26, 2018

Author

Attila Kovacs

Macro Definition Documentation

SMAX_TYPES

#define SMAX_TYPES

Redis meta table where variable types are stored.

Character arrays a treated somewhat differently, with the element size bundled in the type, to allow variable length strings to be properly parsed into them without overflow...

SMAX_VERSION_STRING

#define SMAX_VERSION_STRING

The version string for this library

X_META_INIT

#define X_META_INIT   { 0, X_UNKNOWN, -1, {0}, -1, {'\0'}, {0}, 0 }

Default initialized for SMA-X medatadata structure. You should always initialize local metadata with this.

Function Documentation

smax2xField()

int smax2xField

(

XField *

f

)

Converts SMA-X field with serialized string value storage to a standard xchange field with a native value storage.

Parameters

f	Pointer to field to convert

Returns

X_SUCCESS (0) if successful, or X_NULL if the input field or the deserialized value is NULL, X_TYPE_INVALID if the field is of a type that cannot be deserialized, or else an error code returned by smaxStringToValues().

See also

x2smaxField()

smax2xStruct()

References FALSE, XField::isSerialized, smax2xStruct(), smaxStringToValues(), XField::type, XField::value, x_error(), X_NULL, X_RAW, X_SIZE_INVALID, X_STRUCT, X_SUCCESS, x_trace(), X_TYPE_INVALID, xElementSizeOf(), and xGetFieldCount().

smax2xStruct()

int smax2xStruct

(

XStructure *

s

)

Converts an SMA-X structure with serialized string value storage to a standard xchange structure with a native value storage.

Parameters

s	Pointer to structure to convert

Returns

X_SUCCESS (0) if successful, or X_STRUCT_INVALID if the structure is NULL, or had a NULL substructure, or else an error code returned by smax2xField().

See also

x2smaxStruct()

smax2xField()

References XStructure::firstField, XField::next, smax2xField(), x_error(), X_STRUCT_INVALID, and X_SUCCESS.

smaxAddConnectHook()

int smaxAddConnectHook

(

void(*)(void)

setupCall

)

Add a callback function for when SMA-X is connected. It's a wrapper to redisxAddConnectHook().

Parameters

setupCall

Callback function

Returns

X_SUCCESS (0) or an error code (<0) from redisxAddConnectHook().

See also

smaxRemoveConnectHook()

smaxConnect()

smaxConnectTo()

References redisxAddConnectHook(), smaxGetRedis(), and X_SUCCESS.

smaxAddDefaultMessageProcessor()

int smaxAddDefaultMessageProcessor	(	const char *	host,
		const char *	prog,
		const char *	type
	)

Report messages to stdout/stderr in default formats.

Parameters

host	Host name where messages originate from, or "*" or NULL if any.
prog	Program name of message originator, or "*" or NULL if any.
type	Message type, or "*" or NULL if any.

Returns

Serial ID number (> 0) of the message processor, or X_NULL.

References smaxAddMessageProcessor().

smaxAddDisconnectHook()

int smaxAddDisconnectHook

(

void(*)(void)

cleanupCall

)

Add a callback function for when SMA-X is disconnected. It's a wrapper to redisxAddDisconnectHook().

Parameters

cleanupCall

Callback function

Returns

X_SUCCESS (0) or an error code (<0) from redisxAddConnectHook().

See also

smaxRemoveDisconnectHook()

smaxDisconnect()

References redisxAddDisconnectHook(), smaxGetRedis(), and X_SUCCESS.

smaxAddMessageProcessor()

int smaxAddMessageProcessor	(	const char *	host,
		const char *	prog,
		const char *	type,
		void(*)(XMessage *)	f
	)

Adds a message processor function for a specific host (or all hosts), a specific program (or all programs), and a specific message type (or all message types).

Parameters

host	Host name where messages originate from, or "*" or NULL if any.
prog	Program name of message originator, or "*" or NULL if any.
type	Message type, or "*" or NULL if any.
f	Callback function

Returns

Serial ID number (> 0) of the message processor, or X_NULL if callback function is null, or X_FAILURE if malloc failed.

See also

smaxRemoveMessageProcessor()

References MESSAGES_PREFIX, redisxAddSubscriber(), redisxSubscribe(), smaxGetRedis(), smaxRemoveMessageProcessor(), x_error(), X_NULL, X_SEP, X_SEP_LENGTH, X_SUCCESS, x_trace(), and xStringCopyOf().

smaxAddSubscriber()

int smaxAddSubscriber	(	const char *	idStem,
		RedisSubscriberCall	f
	)

Add a subcriber (callback) function to process incoming PUB/SUB messages for a given SMA-X table (or id). The function should itself check that the channel receiving notification is indeed what it expectes before acting on it, as the callback routine will be invoked for any update inside the specified table, unless the table argument refers to a specific aggregate ID of a single variable. This call only registers the callback routine for SMA-X update notifications for variables that begin with the specified stem. You will still have to subscrive to any relevant variables with smaxSubscribe() to enable delivering update notifications for the variables of your choice.

Parameters

idStem	Table name or ID stem for which the supplied callback function will be invoked as long as the beginning of the PUB/SUB update channel matches the given stem. Alternatively, it can be a fully qualified SMA-X ID (of the form table:key) f a single variable.
f	The function to call when there is an incoming PUB/SUB update to a channel starting with stem.

Returns

X_SUCCESS if successful, or else an approriate error code by redisxAddSubscriber()

See also

smaxSubscribe()

References redisxAddSubscriber(), SMAX_UPDATES_ROOT, smaxGetRedis(), X_SUCCESS, and xGetAggregateID().

smaxConnect()

int smaxConnect

(

)

Initializes the SMA-X sharing library in this runtime instance.

Returns

X_SUCCESS If the library was successfully initialized X_ALREADY_OPEN If SMA-X sharing was already open. X_NO_SERVICE If the there was an issue establishing the necessary network connection(s). X_NAME_INVALID If the redis server name lookup failed. X_NULL If the Redis IP address is NULL

See also

smaxSetServer()

smaxSetAuth()

smaxConnectTo()

smaxDisconnect()

smaxReconnect()

smaxIsConnected()

References FALSE, redisxConnect(), redisxInit(), redisxSelectDB(), redisxSetPassword(), redisxSetPort(), redisxSetTcpBuf(), redisxSetTransmitErrorHandler(), redisxSetUser(), SMAX_DEFAULT_HOSTNAME, smaxAddConnectHook(), smaxAddDisconnectHook(), smaxAddSubscriber(), smaxGetProgramID(), smaxIsConnected(), smaxLazyFlush(), smaxReleaseWaits(), smaxSetPipelineConsumer(), smaxSetResilient(), smaxTransmitErrorHandler(), TRUE, X_NO_INIT, X_SUCCESS, x_trace(), and xvprintf.

smaxConnectTo()

int smaxConnectTo

(

const char *

server

)

Initializes the SMA-X sharing library in this runtime instance with the specified Redis server. SMA-X is initialized in resilient mode, so that we'll automatically attempt to reconnect to the Redis server if the connection is severed (once it was established). If that is not the desired behavior, you should call smaxSetResilient(FALSE) after connecting.

Parameters

server

SMA-X Redis server name or IP address, e.g. "127.0.0.1".

Returns

X_SUCCESS If the library was successfully initialized X_NO_SERVICE If the there was an issue establishing the necessary network connection(s).

See also

smaxConnect()

smaxDisconnect()

smaxReconnect()

smaxIsConnected()

smaxSetResilient()

References smaxConnect(), smaxSetServer(), and X_SUCCESS.

smaxCreate1DField()

XField * smaxCreate1DField	(	const char *	name,
		XType	type,
		int	size,
		const void *	value
	)

Creates a field for 1-D array of a given name and type using specified native values. It is like xCreate1DField() except that the field is created in serialized form.

Parameters

name	Field name
type	Storage type, e.g. X_INT.
size	Array size.
value	Pointer to the native array in memory.

Returns

A newly created field with the supplied data, or NULL if there was an error.

See also

xSetField()

References smaxCreateField(), and x_trace_null().

smaxCreateBooleanField()

XField * smaxCreateBooleanField	(	const char *	name,
		boolean	value
	)

Creates a field holding a single boolean value. It is like xCreateBooleanField() except that the field is created in serialized form.

Parameters

name	Field name
value	Associated value

Returns

A newly created field with the supplied data, or NULL if there was an error.

See also

xSetField()

References smaxCreateScalarField(), X_BOOLEAN, and x_trace_null().

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, XCoordinateAxis::step, x_error(), and X_MAX_DIMS.

smaxCreateDoubleField()

XField * smaxCreateDoubleField	(	const char *	name,
		double	value
	)

Creates a field holding a single double-precision value. It is like xCreateDoubleField() except that the field is created in serialized form.

Parameters

name	Field name
value	Associated value

Returns

A newly created field with the supplied data, or NULL if there was an error.

See also

xSetField()

References smaxCreateScalarField(), X_DOUBLE, and x_trace_null().

smaxCreateField()

XField * smaxCreateField	(	const char *	name,
		XType	type,
		int	ndim,
		const int *	sizes,
		const void *	value
	)

Creates a generic field of a given name and type and dimensions using the specified native values. It is like xCreateField() except that the field is created in serialized form for SMA-X.

Parameters

name	Field name
type	Storage type, e.g. X_INT.
ndim	Number of dimensionas (1:20). If ndim < 1, it will be reinterpreted as ndim=1, size[0]=1;
sizes	Array of sizes along each dimensions, with at least ndim elements, or NULL with ndim<1.
value	Pointer to the native data location in memory. Unless it is of type X_STRUCT, the data stored in the field is a copy (for type X_RAW) or serialized string (otherwise).

Returns

A newly created field with the supplied data, or NULL if there was an error.

See also

xSetField()

References XField::isSerialized, smaxValuesToString(), TRUE, XField::value, X_RAW, X_STRING, X_STRUCT, x_trace_null(), xCreateField(), xGetElementCount(), and xStringElementSizeOf().

smaxCreateIntField()

XField * smaxCreateIntField	(	const char *	name,
		int	value
	)

Creates a field holding a single integer value. It is like xCreateIntField() except that the field is created in serialized form.

Parameters

name	Field name
value	Associated value

Returns

A newly created field with the supplied data, or NULL if there was an error.

See also

xSetField()

References smaxCreateScalarField(), X_INT, and x_trace_null().

smaxCreateLongField()

XField * smaxCreateLongField	(	const char *	name,
		long long	value
	)

Creates a field holding a single wide (64-bit) integer value. It is like xCreateLongField() except that the field is created in serialized form.

Parameters

name	Field name
value	Associated value

Returns

A newly created field with the supplied data, or NULL if there was an error.

See also

xSetField()

References smaxCreateScalarField(), X_LONG, and x_trace_null().

smaxCreateMeta()

XMeta * smaxCreateMeta

(

)

Creates a new SMA-X metadata object with defaults. Effectively the same as calling calloc() followed by xResetMeta().

Returns

Pointer to a new metadata object initialized to defaults.

See also

X_META_INIT

References smaxResetMeta().

smaxCreateScalarField()

XField * smaxCreateScalarField	(	const char *	name,
		XType	type,
		const void *	value
	)

Creates a scalar field of a given name and type using the specified native value. It is like xCreateScalarField() except that the field is created in serialized form.

Parameters

name	Field name
type	Storage type, e.g. X_INT.
value	Pointer to the native data location in memory.

Returns

A newly created scalar field with the supplied data, or NULL if there was an error.

See also

xSetField()

References smaxCreate1DField(), and x_trace_null().

smaxCreateStringField()

XField * smaxCreateStringField	(	const char *	name,
		const char *	value
	)

Creates a field holding a single string value. It is like xCreateStringField() except that the field is created in serialized form.

Parameters

name	Field name
value	Associated value

Returns

A newly created field referencing the supplied string, or NULL if there was an error.

References smaxCreateScalarField(), X_STRING, and x_trace_null().

smaxCreateSyncPoint()

XSyncPoint * smaxCreateSyncPoint

(

)

Creates a synchronization point that can be waited upon until all elements queued prior to creation are processed (retrieved from the database.

Returns

Pointer to a newly created synchronization point that can be waited upon.

See also

smaxSync()

smaxQueue()

smaxQueueCallback()

References XSyncPoint::isComplete, XSyncPoint::lock, XSyncPoint::status, X_INCOMPLETE, and X_SUCCESS.

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.

smaxDestroySyncPoint()

void smaxDestroySyncPoint

(

XSyncPoint *

s

)

Destroys a synchronization point, releasing the memory space allocated to it.

Parameters

s	Pointer to the synchronization point to discard.

References XSyncPoint::isComplete, and XSyncPoint::lock.

smaxDisconnect()

int smaxDisconnect

(

)

Disables the SMA-X sharing capability, closing underlying network connections.

Returns

X_SUCCESS (0) if the sharing was properly ended. X_NO_INIT if SMA-X was has not been started prior to this call.

See also

smaxConnect()

smaxConnectTo()

smaxReconnect()

smaxIsConnected()

References redisxDisconnect(), smaxIsConnected(), x_error(), X_NO_INIT, X_SUCCESS, and xvprintf.

smaxError()

int smaxError	(	const char *	func,
		int	errorCode
	)

Prints a descriptive error message to stderr, and returns the error code.

Parameters

func	String that describes the function or location where the error occurred.
errorCode	Error code that describes the failure.

Returns

Same error code as specified on input.

References redisxError(), smaxErrorDescription(), X_NO_SERVICE, and xDebug.

smaxErrorDescription()

const char * smaxErrorDescription

(

int

code

)

Returns a string description for one of the RM error codes.

Parameters

code	One of the error codes defined in 'xchange.h' or in 'smax.h' (e.g. X_NO_PIPELINE)

References redisxErrorDescription().

smaxGetArrayField()

int smaxGetArrayField	(	const XStructure *	s,
		const char *	name,
		void *	dst,
		XType	type,
		int	count
	)

Gets the data of an SMA-X structure field as an array of values of the specified type and element count. The field's data will be truncated or padded with zeroes to provide the requested element count always.

Parameters

	s	Pointer to SMA-X structure
	name	Field name
[out]	dst	Array to return values in.
	type	Type of data.
	count	Number of elements in return array. The field data will be truncated or padded as necessary.

Returns

X_SUCCESS (0) if successful, or X_STRUCT_INVALID if the input structure is NULL, X_NULL if dst is NULL, X_SIZE_INVALID if n is 0 or negative, X_NAME_INVALID if the structure does not have a field by the specified name, or else an error returned by smaxStringtoValues().

References smaxStringToValues(), XField::value, x_error(), X_NAME_INVALID, X_NULL, X_SIZE_INVALID, X_STRUCT_INVALID, X_SUCCESS, and xGetField().

smaxGetBooleanField()

boolean smaxGetBooleanField	(	const XStructure *	s,
		const char *	name,
		boolean	defaultValue
	)

Returns the first value in a structure's field as an integer, or the specified default value if there is no such field in the structure, or the content cannot be parse into an integer.

Parameters

s	Pointer to the XStructure.
name	Field name
defaultValue	Value to return if no corresponding integer field value.

Returns

The (first) field value as a long long, or the default value if there is no such field.

See also

xGetField()

References XField::value, xGetField(), and xParseBoolean().

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 RedisEntry::key, XCoordinateAxis::name, redisxGetTable(), XCoordinateAxis::refIndex, XCoordinateAxis::refValue, smaxGetRedis(), XCoordinateAxis::step, XCoordinateAxis::unit, RedisEntry::value, x_error(), x_trace_null(), and xGetAggregateID().

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, smaxGetCoordinateAxis(), X_MAX_DIMS, x_trace_null(), and xGetAggregateID().

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, smaxPullMeta(), X_SUCCESS, and x_trace_null().

smaxGetDoubleField()

double smaxGetDoubleField	(	const XStructure *	s,
		const char *	name,
		double	defaultValue
	)

Returns the first value in a structure's field as a double precision float, or the specified default value if there is no such field in the structure, or the content cannot be parse into an double.

Parameters

s	Pointer to the XStructure.
name	Field name
defaultValue	Value to return if no corresponding integer field value.

Returns

The (first) field value as a double, or the specified default if there is no such field.

See also

xGetField()

References XField::value, and xGetField().

smaxGetHostName()

char * smaxGetHostName

(

)

Returns the host name on which this program is running. It returns a reference to the same static variable every time. As such you should never call free() on the returned value. Note, that only the leading part of the host name is returned, so for a host that is registered as 'somenode.somedomain' only 'somenode' is returned.

Returns

The host name string (leading part only).

See also

smaxSetHostName()

References xStringCopyOf().

smaxGetKeys()

char ** smaxGetKeys	(	const char *	table,
		int *	n
	)

Returns a snapshot of the key names stored in a given Redis hash table, ot NULL if there was an error.

Parameters

	table	Host name or owner ID whose variable to count.
[out]	n	Pointer to which the number of keys (>=0) or an error (<0) is returned. An error returned by redisxGetKeys(), or else:

X_NO_INIT if the SMA-X sharing was not initialized, e.g. via smaxConnect(). X_GROUP_INVALID if the table name is invalid. X_NULL if the output 'n' pointer is NULL.

Returns

An array of pointers to the names of Redis keys.

See also

smaxKeyCount()

References redisxGetKeys(), x_error(), x_trace_null(), and xvprintf.

smaxGetLazyCached()

int smaxGetLazyCached	(	const char *	table,
		const char *	key,
		XType	type,
		int	count,
		void *	value,
		XMeta *	meta
	)

Retrieve a variable from the local cache (if available), or else pull from the SMA-X database. If local caching was not previously eanbled, it will be enabled with this call, so that subsequent calls will always return data from the locally updated cache with minimal overhead and effectively no latency.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
type	The SMA-X variable type, e.g. X_FLOAT or X_CHARS(40), of the buffer.
count	The number of elements to retrieve
value	Pointer to the native data buffer in which to restore values
meta	Optional metadata pointer, or NULL if metadata is not required.

Returns

X_SUCCESS (0), or X_NO_SERVICE is SMA-X is not accessible, or another error (<0) from smax.h or xchange.h.

See also

sa smaxLazyCache()

sa smaxLaxyPull()

References TRUE, X_NO_SERVICE, X_SUCCESS, and x_trace().

smaxGetLazyUpdateCount()

int smaxGetLazyUpdateCount	(	const char *	table,
		const char *	key
	)

Returns the actual number of times a variable has been updated from SMA-X. It may be useful information when deciding if lazy pulling is appropriate (it is if the number of pull requests exceeds the actual number of transfers significantly).

Parameters

table	The hash table name.
key	The variable name under which the data is stored.

Returns

The number of times a variable has been updated, or -1 if the variable is not being monitored, or if the arguments are invalid.

smaxGetLongField()

long long smaxGetLongField	(	const XStructure *	s,
		const char *	name,
		long long	defaultValue
	)

Returns the first value in a structure's field as an integer, or the specified default value if there is no such field in the structure, or the content cannot be parse into an integer.

Parameters

s	Pointer to the XStructure.
name	Field name
defaultValue	Value to return if no corresponding integer field value.

Returns

The (first) field value as a long long, or the default value if there is no such field.

See also

xGetField()

References XField::value, and xGetField().

smaxGetMetaCount()

int smaxGetMetaCount

(

const XMeta *

m

)

Returns the number of elements stored from a metadata.

Parameters

m	pointer to metadata that defines the dimension and shape of elements.

Returns

the total number of elements represented by the metadata

References XMeta::storeDim, XMeta::storeSizes, and xGetElementCount().

smaxGetProgramID()

char * smaxGetProgramID

(

)

Returns the SMA-X program ID.

Returns

The SMA-X program ID as <hostname>:<programname>, e.g. "hal9000:statusServer".

References smaxGetHostName(), and xGetAggregateID().

smaxGetRawField()

char * smaxGetRawField	(	const XStructure *	s,
		const char *	name,
		char *	defaultValue
	)

Returns the string value in a structure's field, or the specified default value if there is no such field in the structure.

Parameters

s	Pointer to the XStructure.
name	Field name
defaultValue	Value to return if no corresponding integer field value.

Returns

The field's string (raw) value, or the specified default if there is no such field.

See also

xGetField()

References XField::value, and xGetField().

smaxGetRedis()

Redis * smaxGetRedis

(

)

Returns the Redis connection information for SMA-X

Returns

The structure containing the Redis connection data.

See also

smaxConnect()

smaxConnectTo()

smaxIsConnected()

smaxGetScriptSHA1()

char * smaxGetScriptSHA1	(	const char *	scriptName,
		int *	status
	)

Gets the SHA1 script ID for the currently loaded script with the specified name.

Parameters

scriptName	Case-sensitive name of the script, e.g. "GetStruct".
status	Pointer int which to return status, which is X_SUCCESS if the SHA1 id was successfully obtained, or else an appropriate error code.

Returns

String buffer with the SHA1 key or NULL if it could not be retrieved. (The caller is responsible freeing the buffer after use.)

References redisxCheckDestroyRESP(), redisxDestroyRESP(), redisxRequest(), RESP_BULK_STRING, SMAX_SCRIPTS, smaxGetRedis(), RESP::value, x_error(), X_NAME_INVALID, and x_trace_null().

smaxGetServerTime()

int smaxGetServerTime

(

struct timespec *

t

)

Returns the current time on the Redis server instance.

Parameters

t	Pointer to a timespec structure in which to return the server time.

Returns

X_SUCCESS (0) if successful, or X_NO_INIT if not connected to SMA-X, or X_NULL if either argument is NULL, or X_PARSE_ERROR if could not parse the response, or another error returned by redisxCheckRESP().

References redisxGetTime(), smaxGetRedis(), and X_SUCCESS.

smaxGetTime()

double smaxGetTime

(

const char *

timestamp

)

Returns the a sub-second precision UNIX time value for the given SMA-X timestamp

Parameters

timestamp

The string timestamp returned by SMA-X

Returns

Corresponding UNIX time with sub-second precision, or NAN if the input could not be parsed.

References NAN, smaxParseTime(), x_error(), X_NULL, and x_trace().

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, smaxPullMeta(), X_SUCCESS, and x_trace_null().

smaxIsConnected()

int smaxIsConnected

(

)

Checks whether SMA-X sharing is currently open (by a preceding call to smaxConnect() call.

See also

smaxConnect()

smaxConnectTo()

smaxDisconnect()

smaxReconnect()

References redisxIsConnected().

smaxIsPipelined()

boolean smaxIsPipelined

(

)

Check if SMA-X is configured with pipeline mode enabled.

Returns

TRUE (1) if the pipeline is enabled, or else FALSE (0)

See also

smaxSetPipelined()

smaxIsResilient()

boolean smaxIsResilient

(

)

Checks whether the resiliency feature has been enabled.

Returns

TRUE if enabled, otherwise FALSE.

See also

smaxSetResilient()

smaxIsVerbose()

boolean smaxIsVerbose

(

)

Checks id verbose reporting is enabled.

Returns

TRUE if verbose reporting is enabled, otherwise FALSE.

See also

smaxSetVerbose()

References redisxIsVerbose().

smaxKeyCount()

int smaxKeyCount

(

const char *

table

)

Retrieve the current number of variables stored on host (or owner ID).

Parameters

table

Hash table name.

Returns

The number of keys (fields) in the specified table (>= 0), or an error code (<0), such as: X_NO_INIT if the SMA-X sharing was not initialized, e.g. via smaConnect(). X_GROUP_INVALID if the table name is invalid. or one of the errors (<0) returned by redisxRequest().

See also

smaxGetKeys()

References RESP::n, redisxCheckRESP(), redisxDestroyRESP(), redisxRequest(), RESP_INT, x_error(), X_GROUP_INVALID, x_trace(), and xvprintf.

smaxLazyCache()

int smaxLazyCache	(	const char *	table,
		const char *	key,
		XType	type
	)

Specify that a specific variable should be cached for minimum overhead lazy access. When a variable is lazy cached its local copy is automatically updated in the background so that accessing it is always nearly instantaneous. Lazy caching is a good choice for variables that change less frequently than they are polled typically. For variables that change frequently (ans used less frequently), lazy caching is not a great choice since it consumes network bandwidth even when the variable is not being accessed.

Once a variable is lazy cached, it can be accessed instantaneously via smaxGetLazyCached() without any blocking network operations.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
type	The SMA-X variable type, e.g. X_FLOAT or X_CHARS(40), of the buffer.

Returns

X_SUCCESS (0) or X_NO_SERVICE.

See also

smaxGetLazyCached()

References FALSE, TRUE, X_NO_SERVICE, X_SUCCESS, and x_trace().

smaxLazyEnd()

int smaxLazyEnd	(	const char *	table,
		const char *	key
	)

Stops processing lazy updates in the background for a given variable.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.

Returns

X_SUCCESS (0)

See also

smaxLazyFlush()

smaxLazyPull()

References X_SUCCESS.

smaxLazyFlush()

int smaxLazyFlush

(

)

Discards caches for all lazy variables (i.e. stops all subscriptions to variable updates, at least until the next smaxLazyPull() call). Generally speaking, it's a good idea to call this routine when one is done using a set of lazy variables for the time being, but want to avoid the tedium of calling smaxLazyEnd() individually for each of them. Note however, that after flushing the lazy caches, the fist lazy call following for each variable will inevitably result in a real SMA-X pull. So use it carefully!

Returns

Number of monitor points flushed.

See also

smaxLazyPull()

smaxLazyEnd()

References smaxRemoveSubscribers().

smaxLazyPull()

int smaxLazyPull	(	const char *	table,
		const char *	key,
		XType	type,
		int	count,
		void *	value,
		XMeta *	meta
	)

Poll an infrequently changing variable without stressing out the network or the SMA-X database. The first lazy pull for a variable will fetch its value from SMA-X and subscribe to update notifications. Subsequent smaxLazyPull() calls to the same variable will retrieve its value from a local cache (without contacting SMA-X) as long as it is unchanged.

Note, after you are done using a variable that has been lazy pulled, you should call smaxLazyEnd() to signal that it no longer requires to be cached and updated in the background, or call smaxLazyFlush() to flush all lazy caches for all lazy variables (if that is what you want).

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
type	The SMA-X variable type, e.g. X_FLOAT or X_CHARS(40), of the buffer.
count	The number of points to retrieve into the buffer.
value	Pointer to the buffer to which the data is to be retrieved.
meta	Pointer to metadata or NULL if no metadata is needed.

Returns

X_SUCCESS (0) on success, or else an error code (<0) of smaxPull().

See also

smaxLazyEnd()

smaxLazyFlush()

smaxPull()

smaxQueue()

References x_error(), X_NO_SERVICE, X_NULL, X_SUCCESS, and x_trace().

smaxLazyPullChars()

int smaxLazyPullChars	(	const char *	table,
		const char *	key,
		char *	buf,
		int	n
	)

Lazy pulls a string value into the specified string buffer.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
buf	Buffer to fill with stored data
n	Number of bytes to fill in buffer. The retrieved data will be truncated as necessary.

Returns

X_SUCCESS (0) if successful, or the error code (<0) returned by smaxLazyPull().

References smaxLazyPull(), X_CHARS, and X_SUCCESS.

smaxLazyPullDouble()

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

Returns a single double-precision value for a given SMA-X variable, or NAN if the value could not be retrieved.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.

Returns

The floating-point value stored in SMA-X, or NaN if the value could not be retrieved.

See also

smaxLazyPullDoubleDefault()

smaxPullDouble()

References NAN, and smaxLazyPullDoubleDefault().

smaxLazyPullDoubleDefault()

double smaxLazyPullDoubleDefault	(	const char *	table,
		const char *	key,
		double	defaultValue
	)

Returns a single double-precision value for a given SMA-X variable, or a default value if the value could not be retrieved.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
defaultValue	The value to return in case of an error.

Returns

The floating-point value stored in SMA-X, or the specified default if the value could not be retrieved.

See also

smaxLazyPullDouble()

smaxPullDoubleDefault()

References smaxLazyPull(), and X_DOUBLE.

smaxLazyPullLong()

long long smaxLazyPullLong	(	const char *	table,
		const char *	key,
		long long	defaultValue
	)

Returns a single integer value for a given SMA-X variable, or a default value if the value could not be retrieved.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
defaultValue	The value to return in case of an error.

Returns

The long integer value stored in SMA-X, or the specified default if the value could not be retrieved.

See also

smaxPullLong()

References smaxLazyPull(), and X_LONG.

smaxLazyPullString()

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

Returns a single string value for a given SMA-X variable, or a NULL if the value could not be retrieved.

Parameters

table	Hash table name.
key	Variable name under which the data is stored.

Returns

Pointer to the string value stored in SMA-X, or NULL if the value could not be retrieved.

See also

smaxPullString()

References smaxLazyPull(), X_STRING, and x_trace_null().

smaxLazyPullStruct()

int smaxLazyPullStruct	(	const char *	id,
		XStructure *	s
	)

Lazy pulls data into a structure, discarding any prior data that the structure might contain.

Parameters

[in]	id	Aggregate structure ID.
[out]	s	Destination structure to populate with the retrieved fields

Returns

X_SUCCESS (0) if successful, or the error code (<0) returned by smaxLazyPull().

See also

smaxPullStruct()

xCreateStruct()

References smaxLazyPull(), X_STRUCT, and X_SUCCESS.

smaxParseTime()

int smaxParseTime	(	const char *	timestamp,
		time_t *	secs,
		long *	nanosecs
	)

Parses a timestamp into broken-down UNIX time.

Parameters

[in]	timestamp	Timestamp string as returned in redis queries;
[out]	secs	Pointer to the returned UNIX time (seconds).
[out]	nanosecs	Pointer to the retuned sub-second remainder as nanoseconds, or NULL if nor requested.

Returns

X_SUCCESS(0) if the timestamp was successfully parsed. X_NULL if there was no timestamp (empty or invalid string), or the secs argument is NULL. X_PARSE_ERROR if the seconds could not be parsed. 1 if there was an error parsing the nanosec part. X_NULL if the secs arhument is NULL

References x_error(), X_NULL, X_PARSE_ERROR, and X_SUCCESS.

smaxPull()

int smaxPull	(	const char *	table,
		const char *	key,
		XType	type,
		int	count,
		void *	value,
		XMeta *	meta
	)

Pull data from the specified hash table. This calls data via the interactive client to Redis.

Parameters

[in]	table	Hash table name.
[in]	key	Variable name under which the data is stored.
[in]	type	SMA-X variable type, e.g. X_FLOAT or X_CHARS(40), of the buffer.
[in]	count	Number of points to retrieve into the buffer.
[out]	value	Pointer to the buffer to which the data is to be retrieved.
[out]	meta	Pointer to metadata or NULL if no metadata is needed.

Returns

X_SUCCESS (0) if successful, or X_NO_INIT if the SMA-X library was not initialized. X_GROUP_INVALID if the 'table' argument is invalid. X_NAME_INVALID if the 'key' argument is invalid. X_NULL if an essential argument is NULL or contains NULL. X_NO_SERVICE if there was no connection to the Redis server. X_FAILURE if there was an underlying failure.

See also

smaxLazyPull()

smaxQueue()

References REDISX_INTERACTIVE_CHANNEL, X_NULL, X_STRUCT, X_SUCCESS, x_trace(), xGetAggregateID(), and xStringCopyOf().

smaxPullDouble()

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

Returns a single floating-point value for a given SMA-X variable, or a NAN if the value could not be retrieved.

Parameters

table	Hash table name.
key	Variable name under which the data is stored.

Returns

The floating-point value stored in SMA-X, or NAN if the value could not be retrieved.

See also

smaxLazyPullDouble()

smaxPullDoubleDefault()

References NAN, and smaxPullDoubleDefault().

smaxPullDoubleDefault()

double smaxPullDoubleDefault	(	const char *	table,
		const char *	key,
		double	defaultValue
	)

Returns a single floating-point value for a given SMA-X variable, or a specified default value if the SMA-X value could not be retrieved.

Parameters

table	Hash table name.
key	Variable name under which the data is stored.
defaultValue	The value to return in case of an error.

Returns

The floating-point value stored in SMA-X, or the specified default if the value could not be retrieved.

See also

smaxLazyPullDoubleDefault()

smaxPullDouble()

References smaxPull(), and X_DOUBLE.

smaxPullDoubles()

double * smaxPullDoubles	(	const char *	table,
		const char *	key,
		XMeta *	meta,
		int *	n
	)

Returns a dynamically allocated array of doubles stored in an SMA-X variable.

Parameters

[in]	table	The hash table name.
[in]	key	The variable name under which the data is stored.
[out]	meta	(optional) Pointer to metadata to be filled or NULL if not required.
[out]	n	Pointer to which the number of double is returned (if *n > 0) or else an error code.

Returns

Pointer to C double[] array containing *n elements, or NULL.

See also

smaxPullDouble()

smaxPullFloats()

References X_DOUBLE, and x_trace_null().

smaxPullInt()

int smaxPullInt	(	const char *	table,
		const char *	key,
		int	defaultValue
	)

Returns a single integer value for a given SMA-X variable, or a default value if the value could not be retrieved.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
defaultValue	The value to return in case of an error.

Returns

The integer value stored in SMA-X, or the specified default if the value could not be retrieved.

See also

smaxLazyPullInt()

smaxPullInts()

smaPullLong()

References smaxPull(), and X_INT.

smaxPullInts()

int * smaxPullInts	(	const char *	table,
		const char *	key,
		XMeta *	meta,
		int *	n
	)

Returns a dynamically allocated array of integers stored in an SMA-X variable.

Parameters

[in]	table	The hash table name.
[in]	key	The variable name under which the data is stored.
[out]	meta	(optional) Pointer to metadata to be filled or NULL if not required.
[out]	n	Pointer to which the number of integers is returned (if *n > 0) or else an error code.

Returns

Pointer to C int[] array containing *n elements, or NULL.

See also

smaxPullShorts()

smaxPullLongs()

smaxPullInt()

References X_INT, and x_trace_null().

smaxPullLong()

long long smaxPullLong	(	const char *	table,
		const char *	key,
		long long	defaultValue
	)

Returns a single integer value for a given SMA-X variable, or a default value if the value could not be retrieved.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
defaultValue	The value to return in case of an error.

Returns

The integer value stored in SMA-X, or the specified default if the value could not be retrieved.

See also

smaxLazyPullLong()

smaxPullLongs()

smaxPullInt()

References smaxPull(), and X_LONG.

smaxPullLongs()

long long * smaxPullLongs	(	const char *	table,
		const char *	key,
		XMeta *	meta,
		int *	n
	)

Returns a dynamically allocated array of long long (int64) integers stored in an SMA-X variable.

Parameters

[in]	table	The hash table name.
[in]	key	The variable name under which the data is stored.
[out]	meta	(optional) Pointer to metadata to be filled or NULL if not required.
[out]	n	Pointer to which the number of integers is returned (if *n > 0) or else an error code.

Returns

Pointer to C int[] array containing *n elements, or NULL.

See also

smaxPullInts()

smaxPullShorts()

smaxPullLong()

References X_INT, and x_trace_null().

smaxPullMeta()

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

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.
status	Pointer to int in which to return a X_SUCCESS or an error code.

Returns

The string metadata value or NULL.

See also

setPushMeta()

References redisxGetStringValue(), smaxGetRedis(), x_error(), X_GROUP_INVALID, X_NO_INIT, x_trace_null(), and xGetAggregateID().

smaxPullRaw()

char * smaxPullRaw	(	const char *	table,
		const char *	key,
		XMeta *	meta,
		int *	status
	)

Returns a dynamically allocated buffer with the raw string value stored in SMA-X. This call can also be used to get single string values from SMA-X, since for single string the stored raw value is simply the string itself. However, to properly retrieve string arrays, you want to use smaxPullStrings() instead.

Parameters

[in]	table	The hash table name.
[in]	key	The variable name under which the data is stored.
[out]	meta	(optional) Pointer to metadata to be filled or NULL if not required.
[out]	status	Pointer int which an error status is returned.

Returns

Pointer to C array containing the elements of the specified type, or NULL.

See also

smaxPullStrings()

References smaxPull(), x_error(), X_RAW, and x_trace_null().

smaxPullString()

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

Returns a single string value for a given SMA-X variable, or a NULL if the value could not be retrieved.

Parameters

table	Hash table name.
key	Variable name under which the data is stored.

Returns

Pouinter to the string value stored in SMA-X, or NULL if the value could not be retrieved.

See also

smaxLazyPullString()

smaxPullStrings()

References smaxPull(), X_STRING, and x_trace_null().

smaxPullStrings()

char ** smaxPullStrings	(	const char *	table,
		const char *	key,
		XMeta *	meta,
		int *	n
	)

Returns an array of pointers to individuals strings inside the retrieved contiguous data buffer. Thus, to discard the returned data after use, you must first discard the underlying buffer (as pointed by the first element) before discarding the array of pointers themselves. E.g.:

char **array = smaxPullStrings("mygroup", "myfield", &meta); ... if(array != NULL) { free(array[0]); // discards the underlying contiguous buffer free(array); // discards the array of pointers. }

Parameters

[in]	table	The hash table name.
[in]	key	The variable name under which the data is stored.
[out]	meta	(optional) Pointer to metadata to be filled or NULL if not required.
[out]	n	Pointer to which the number of double is returned (if *n > 0) or else an error code.

Returns

Pointer to a an array of strings (char *) containing *n elements, or NULL.

See also

smaxPullString()

smaxPullRaw()

References smaxGetMetaCount(), smaxPullRaw(), XMeta::storeBytes, x_error(), X_META_INIT, and x_trace_null().

smaxPullStruct()

XStructure * smaxPullStruct	(	const char *	id,
		XMeta *	meta,
		int *	status
	)

Returns a dynamically allocated XStrucure for the specified hashtable in SMA-X.

Parameters

[in]	id	Aggregated structure ID.
[out]	meta	(optional) Pointer to metadata to be filled or NULL if not required.
[out]	status	Pointer int which an error status is returned.

Returns

Pointer to an XStructure, or NULL.

See also

smaxLazyPullStruct()

xDestroyStruct()

References smaxPull(), x_error(), X_STRUCT, and x_trace_null().

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 NAN, SMAX_TIMESTAMPS, smaxPullMeta(), and x_trace_null().

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(), smaxTypeForString(), x_trace(), X_UNKNOWN, and xParseDims().

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 FALSE, redisxNotify(), redisxSetValue(), smaxGetProgramID(), smaxGetRedis(), x_error(), X_GROUP_INVALID, X_INCOMPLETE, X_NO_INIT, X_NULL, X_SUCCESS, x_trace(), and xGetAggregateID().

smaxQueue()

int smaxQueue	(	const char *	table,
		const char *	key,
		XType	type,
		int	count,
		void *	value,
		XMeta *	meta
	)

Queues a pull requests for pipelined data retrieval. Because pipelined pulls are executed on a separate Redis client from the one used for sharing values, e.g. via smaxShare(), there is no guarantee as to the order of this pull operation and previously initiated shares from the same thread. This would only be an issue if you are trying to use queued read to read back a value you have just shared – which is not really a good use case anyway, as it generates network traffic for not real reason. But, if you must read back a value you have shared, you probably should use a regular smaxPull() call to ensure ordering.

Parameters

	table	Hash table name.
	key	Variable name under which the data is stored.
	type	SMA-X variable type, e.g. X_FLOAT or X_CHARS(40), of the buffer.
	count	Number of points to retrieve into the buffer.
[out]	value	Pointer to the buffer to which the data is to be retrieved.
[out]	meta	Pointer to the corresponding metadata structure, or NULL.

Returns

X_SUCCESS (0) if successful X_NAME_INVALID if the table and key are both NULL X_NULL if the value field is NULL or the return value of xQueue().

See also

smaxPull()

smaxLazyPull()

smaxCreateSyncPoint()

smaxQueueCallback()

References REDISX_PIPELINE_CHANNEL, SMAX_PIPE_READ_TIMEOUT_MILLIS, x_error(), X_GROUP_INVALID, X_NAME_INVALID, X_NO_SERVICE, X_NULL, X_SUCCESS, x_trace(), and xStringCopyOf().

smaxQueueCallback()

int smaxQueueCallback	(	void(*)(void *)	f,
		void *	arg
	)

Adds a callback function to the queue to be called with the specified argument once all prior requests in the queue have been fullfilled (retrieved from the database).

As a general rule callbacks added to the pipeline should return very fast, and avoid blocking operations for the most part (using mutexes that may block for very short periods only may be excepted). If the user needs to do more processing, or make blocking calls (e.g. IO operartions) that may not return for longer periods, the callback should fire off processing in a separate thread, or else simply move the result into another asynchronous processing queue.

Parameters

f	The callback function that takes a pointer argument
arg	Argument to call the specified function with.

Returns

X_SUCCESS (0) or else X_NULL if the function parameter is NULL.

See also

smaxCreateSyncPoint()

smaxQueue()

References x_error(), X_NULL, and X_SUCCESS.

smaxReconnect()

int smaxReconnect

(

)

Reconnects to the SMA-X server. It will try connecting repeatedly at regular intervals until the connection is made. If resilient mode is enabled, then locally accumulated shares will be sent to the Redis server upon reconnection. However, subscriptions are not automatically re-established. The caller is responsible for reinstate any necessary subscriptions after the reconnection or via an approproate connection hook.

Returns

X_SUCCESS (0) if successful X_NO_INIT if SMA-X was never initialized.

or the error returned by redisxReconnect().

See also

smaxConnect()

smaxConnectTo()

smaxDisconnect()

smaxIsConnected()

smaxSetResilient()

smaxAddConnectHook()

References redisxReconnect(), SMAX_RECONNECT_RETRY_SECONDS, x_error(), X_NO_INIT, X_SUCCESS, and xvprintf.

smaxReleaseWaits()

int smaxReleaseWaits

(

)

Unblocks all smax_wait*() calls, which will return X_REL_PREMATURE, as a result.

Returns

X_SUCCESS (0)

See also

smaxWaitOnAnySubscribed()

References RELEASEID, X_SUCCESS, and xvprintf.

smaxRemoveConnectHook()

int smaxRemoveConnectHook

(

void(*)(void)

setupCall

)

Remove a post-connection callback function. It's a wrapper to redisxRemoveConnectHook().

Parameters

setupCall

Callback function

Returns

X_SUCCESS (0) or an error code (<0) from redisxAddConnectHook().

See also

smaxAddConnectHook()

smaxConnect()

smaxConnectTo()

References redisxRemoveConnectHook(), smaxGetRedis(), and X_SUCCESS.

smaxRemoveDisconnectHook()

int smaxRemoveDisconnectHook

(

void(*)(void)

cleanupCall

)

Remove a post-cdisconnect callback function. It's a wrapper to redisxRemiveDisconnectHook().

Parameters

cleanupCall

Callback function

Returns

X_SUCCESS (0) or an error code (<0) from redisxAddConnectHook().

See also

smaxAddDisconnectHook()

smaxDisconnect()

References redisxRemoveDisconnectHook(), smaxGetRedis(), and X_SUCCESS.

smaxRemoveMessageProcessor()

int smaxRemoveMessageProcessor

(

int

id

)

Stops a running message processor.

Parameters

id	Message processor ID, as returned by smaxAddMessageProcessor()

Returns

X_SUCCESS (0) if successful, or X_NULL if no message processor is running by that ID.

See also

smaxAddMessageProcessor()

References redisxRemoveSubscribers(), redisxUnsubscribe(), smaxGetRedis(), X_NULL, and X_SUCCESS.

smaxRemoveSubscribers()

int smaxRemoveSubscribers

(

RedisSubscriberCall

f

)

Remove all instances of a subscriber callback function from the current list of functions processing PUB/SUB messages. This call only deactivates the callback routine, but does not stop the delivery of update notifications from the Redis server. You should therefore also call smaxUnsubscribe() as appropriate to stop notifications for variables that no longer have associated callbacks.

Parameters

f	Function to remove

Returns

X_SUCCESS (0) if successful, or else an error (<0) returned by redisxRemoveSubscriber().

See also

smaxUnsubscribe()

References redisxRemoveSubscribers(), smaxGetRedis(), and X_SUCCESS.

smaxResetMeta()

void smaxResetMeta

(

XMeta *

m

)

Set metadata to their default values. After resetting the supplied metadata will have exactly the same content as if it were initialized with the X_META_INIT macro.

Parameters

m	Pointer to the metadata that is to be cleared.

See also

X_META_INIT

References X_META_INIT.

smaxSendDebug()

int smaxSendDebug	(	const char *	msg,
			...
	)

Broadcast a debugging message via SMA-X (e.g. program traces). Works just like printf().

Parameters

msg	Message text (may include format specifications for additional vararg parameters)

Returns

X_SUCCESS (0), or else an X error.

References SMAX_MSG_DEBUG, and X_SUCCESS.

smaxSendDetail()

int smaxSendDetail	(	const char *	msg,
			...
	)

Broadcast non-essential verbose informational detail via SMA-X. Works just like printf().

Parameters

msg	Message text (may include format specifications for additional vararg parameters)

Returns

X_SUCCESS (0), or else an X error.

References SMAX_MSG_DETAIL, and X_SUCCESS.

smaxSendError()

int smaxSendError	(	const char *	msg,
			...
	)

Broadcast an error message via SMA-X. Errors should be used for an issues that impair program functionality. Works just like printf().

Parameters

msg	Message text (may include format specifications for additional vararg parameters)

Returns

X_SUCCESS (0), or else an X error.

See also

smaxSendWarning();

smaxSendDebug();

References SMAX_MSG_ERROR, and X_SUCCESS.

smaxSendInfo()

int smaxSendInfo	(	const char *	msg,
			...
	)

Broadcast an informational message via SMA-X. These should be confirmations or essential information reported back to users. Non-essential information should be sent with sendDetail() instead. Works just like printf().

Parameters

msg	Message text (may include format specifications for additional vararg parameters)

Returns

X_SUCCESS (0), or else an X error.

See also

sendDetail()

sendStatus()

References SMAX_MSG_INFO, and X_SUCCESS.

smaxSendProgress()

int smaxSendProgress	(	double	fraction,
		const char *	msg,
			...
	)

Broadcast a progress update over SMA-X. Apart from the progress fraction argument, it works just like printf().

Parameters

fraction	(0.0:1.0) Completion fraction.
msg	Message text (may include format specifications for additional vararg parameters)

Returns

X_SUCCESS (0), or else an X error.

References SMAX_MSG_DETAIL, x_error(), X_NULL, and X_SUCCESS.

smaxSendStatus()

int smaxSendStatus	(	const char *	msg,
			...
	)

Broadcast a program status update via SMA-X. Works just like printf().

Parameters

msg	Message text (may include format specifications for additional vararg parameters)

Returns

X_SUCCESS (0), or else an X error.

See also

sendInfo()

References SMAX_MSG_STATUS, and X_SUCCESS.

smaxSendWarning()

int smaxSendWarning	(	const char *	msg,
			...
	)

Broadcast a warning message via SMA-X. Warnings should be used for any potentially problematic issues that nonetheless do not impair program functionality. Works just like printf().

Parameters

msg	Message text (may include format specifications for additional vararg parameters)

Returns

X_SUCCESS (0), or else an X error.

See also

smaxSendError();

smaxSendDebug();

References SMAX_MSG_WARNING, and X_SUCCESS.

smaxSetAuth()

int smaxSetAuth	(	const char *	username,
		const char *	password
	)

Sets the SMA-X database authentication parameters (if any) before connecting to the SMA-X server.

Parameters

username	Redis ACL user name (if any), or NULL for no user-based authentication
password	Redis database password (if any), or NULL if the database is not password protected

Returns

X_SUCCESS (0) if successful, or X_ALREADY_OPEN if cannot alter the server configuration because we are already in a connected state.

See also

smaxSetServer()

smaxConnect()

References smaxIsConnected(), X_ALREADY_OPEN, x_error(), X_SUCCESS, and xStringCopyOf().

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 FALSE, RedisEntry::key, XCoordinateAxis::name, redisxMultiSet(), XCoordinateAxis::refIndex, XCoordinateAxis::refValue, smaxGetRedis(), XCoordinateAxis::step, XCoordinateAxis::unit, RedisEntry::value, X_FAILURE, X_SUCCESS, x_trace(), and xGetAggregateID().

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, smaxSetCoordinateAxis(), X_NULL, X_SUCCESS, x_trace(), and xGetAggregateID().

smaxSetDB()

int smaxSetDB

(

int

idx

)

Sets a non-default Redis database index to use for SMA-X before connecting to the SMA-X server.

Parameters

idx	The Redis database index to use (if not the default one)

Returns

X_SUCCESS (0) if successful, or X_ALREADY_OPEN if cannot alter the server configuration because we are already in a connected state.

See also

smaxSetServer()

smaxConnect()

References smaxIsConnected(), X_ALREADY_OPEN, x_error(), and X_SUCCESS.

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, smaxPushMeta(), and X_SUCCESS.

smaxSetHostName()

void smaxSetHostName

(

const char *

name

)

Changes the host name to the user-specified value instead of the default (leading component of the value returned by gethostname()). Subsequent calls to smaxGetHostName() will return the newly set value. An argument of NULL resets to the default.

Parameters

name	the host name to use, or NULL to revert to the default (leading component of gethostname()).

See also

smaxGetHostName()

References xStringCopyOf().

smaxSetMaxPendingPulls()

int smaxSetMaxPendingPulls

(

int

n

)

Configures how many pull requests can be queued in when piped pulls are enabled. If the queue reaches the specified limit, no new pull requests can be submitted until responses arrive, draining the queue somewhat.

Parameters

n	The maximum number of pull requests that can be queued.

Returns

TRUE if the argument was valid, and the queue size was set to it, otherwise FALSE

References x_error(), X_FAILURE, and X_SUCCESS.

smaxSetMessageSenderID()

void smaxSetMessageSenderID

(

const char *

id

)

Sets the sender ID for outgoing program messages. By default the sender ID is <host>:<program> for the program that calls this function, but it can be modified to use some other SMA-X style hierarchical ID also.

Parameters

id	The new sender ID for outgoing program messages, or NULL to reinstate the default <host>:<program> style ID. The argument is not referenced and can be deallocated as desired after the call without affecting the newly defined message ID.

References xStringCopyOf().

smaxSetOrigin()

void smaxSetOrigin	(	XMeta *	m,
		const char *	origin
	)

Sets the 'origin' field of an SMA-X metadata to the specified value, truncating as necessary to fit into the allotted fixed storage.

Parameters

origin	The origination information, usually as hostname:progname
m	Pointer to metadata to set.

References XMeta::origin, and SMAX_ORIGIN_LENGTH.

smaxSetPipelineConsumer()

int smaxSetPipelineConsumer

(

void(*)(RESP *)

f

)

Change the pipeline response consumer function (from it's default or other previous consumer). It is a wrapper for redisxSetPipelineConsumer().

Parameters

f	The function to process ALL pipeline responses from Redis.

Returns

X_SUCCESS (0) if successful, or else an error by redisxSetPipelineConsumer()

See also

smaxSetPipelined()

smaxIsPipelined()

References redisxSetPipelineConsumer(), smaxGetRedis(), and X_SUCCESS.

smaxSetPipelined()

int smaxSetPipelined

(

boolean

isEnabled

)

Enable or disable pipelined write operations (enabled by default). When pipelining, share calls will return as soon as the request is sent to the Redis server, without waiting for a response. Instead, responses are consumed asynchronously by a dedicated thread, which will report errors to stderr. Pipelined writes can have a significant performance advantage over handshaking at the cost of one extra socket connection to Redis (dedicated to pipelining) and the extra thread consuming responses.

The default state of pipelined writes might vary by platform (e.g. enabled on Linux, disabled on LynxOS).

IMPORTANT: calls to smaxSetPipelined() must precede the call to smaxConnect().

Parameters

isEnabled

TRUE to enable pipelined writes, FALSE to disable (default is enabled).

Returns

X_SUCCESS (0) if successful, or X_ALREADY_OPEN if cannot alter the server configuration because we are already in a connected state.

See also

smaxIsPipelined()

smaxSetPipelineConsumer()

References smaxIsConnected(), X_ALREADY_OPEN, x_error(), and X_SUCCESS.

smaxSetResilient()

void smaxSetResilient

(

boolean

value

)

Enables the resiliency feature of the library, which keeps track of local changes destined to the database when the database is not reachable, and sending all locally stored updates once the database comes online again. However, after sending all pending updates to the remote server, the program may exit (default behavior), unless smaxSetResilientExit() is set to FALSE (0), so that it can be restarted in a fresh state, setting up subscriptions and scripts again as necessary.

Parameters

value

TRUE (non-zero) to enable, or FALSE (0) to disable resiliency.

See also

smaxIsResilient()

smaxSetResilientExit()

References FALSE, smaxAddConnectHook(), smaxRemoveConnectHook(), TRUE, and xvprintf.

smaxSetResilientExit()

void smaxSetResilientExit

(

boolean

value

)

Sets whether the program should exit in resilient mode, after having pushed all local updates. The default is to exit since the reconnecting in resilient mode does not by itself re-establish existing subscriptions. However, when subscriptions aren't used, or if they are set up as a connect hook, the user may want the program to simply continue. This is possible by passing FALSE (0) as the argument to this call. This setting only takes effect when resilient mode is enabled. Otherwise, the exit policy is set by the RedisX library.

Parameters

value

Whether to exit the program after all local updates have been pushed to SMA-X after a recovering from an outage.

See also

smaxSetResilient()

smaxAddConnectHook()

References FALSE, and TRUE.

smaxSetServer()

int smaxSetServer	(	const char *	host,
		int	port
	)

Configures the SMA-X server before connecting.

Parameters

host	The SMA-X REdis server host name or IP address.
port	The Redis port number on the SMA-X server, or &lt=0 to use the default

Returns

X_SUCCESS (0) if successful, or X_ALREADY_OPEN if cannot alter the server configuration because we are already in a connected state.

See also

smaxSetAuth()

smaxSetDB()

smaxConnect()

References REDISX_TCP_PORT, smaxIsConnected(), X_ALREADY_OPEN, x_error(), X_SUCCESS, and xStringCopyOf().

smaxSetTcpBuf()

int smaxSetTcpBuf

(

int

size

)

Set the size of the TCP/IP buffers (send and receive) for future client connections.

Parameters

size	(bytes) requested buffer size, or <= 0 to use default value

See also

smaxConnect;

References smaxIsConnected(), X_ALREADY_OPEN, x_error(), and X_SUCCESS.

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, smaxPushMeta(), and X_SUCCESS.

smaxSetVerbose()

void smaxSetVerbose

(

boolean

value

)

Enable or disable verbose reporting of all SMA-X operations (and possibly some details of them). Reporting is done on the standard output (stdout). It may be useful when debugging programs that use the SMA-X interface. Verbose reporting is DISABLED by default.

Parameters

value

TRUE to enable verbose reporting, or FALSE to disable.

See also

smaxIsVerbose()

References redisxSetVerbose().

smaxShare()

int smaxShare	(	const char *	table,
		const char *	key,
		const void *	value,
		XType	type,
		int	count
	)

Share the data into a Redis hash table over the interactive Redis client. It's a fire-and-forget type implementation, which sends the data to Redis, without waiting for confirmation of its arrival. The choice improves the efficiency and throughput, and minimizes execution time, of the call, but it also means that a pipelined pull request in quick succession, e.g. via smaxQueue(), may return a value on the pipeline client before this call is fully executed on the interactive Redis client.

(It is generally unlikely that you will follow this share call with a pipelined pull of the same variable. It would not only create superflous network traffic for no good reason, but it also would have unpredictable results. So, don't.)

Parameters

table	Hash table name in which to share entry.
key	Variable name under which the data is stored.
value	Pointer to the buffer whose data is to be shared.
type	SMA-X variable type, e.g. X_FLOAT or X_CHARS(40), of the buffer.
count	Number of 1D elements.

Returns

X_SUCCESS (0) if successful, or X_NO_INIT if the SMA-X library was not initialized. X_GROUP_INVALID if the table name is invalid. X_NAME_INVALID if the 'key' argument is invalid. X_SIZE_INVALID if count < 1 or count > X_MAX_ELEMENTS X_NULL if the 'value' argument is NULL. X_NO_SERVICE if there was no connection to the Redis server. X_FAILURE if there was an underlying failure.

See also

smaxShareArray()

smaxShareField()

smaxShareStruct()

References smaxShareArray(), and X_SUCCESS.

smaxShareArray()

int smaxShareArray	(	const char *	table,
		const char *	key,
		const void *	ptr,
		XType	type,
		int	ndim,
		const int *	sizes
	)

Share a multidimensional array, such as an int[][][], or float[][], in a single atomic transaction.

Parameters

table	Hash table in which to write entry.
key	Variable name under which the data is stored.
ptr	Pointer to the data buffer, such as an int[][][] or float[][].
type	SMA-X variable type, e.g. X_FLOAT or X_CHARS(40), of the buffer.
ndim	Dimensionality of the data (0 <= ndim <= X_MAX_DIMS).
sizes	An array of ints containing the sizes along each dimension.

Returns

X_SUCCESS (0) if successful, or X_NO_INIT if the SMA-X library was not initialized. X_GROUP_INVALID if the table name is invalid. X_NAME_INVALID if the 'key' argument is invalid. X_SIZE_INVALID if ndim or sizes are invalid. X_NULL if the 'value' argument is NULL. X_NO_SERVICE if there was no connection to the Redis server. X_FAILURE if there was an underlying failure.

See also

smaxShare()

References XField::isSerialized, XField::name, XField::ndim, REDISX_CMDBUF_SIZE, XField::sizes, smaxShareField(), smaxValuesToString(), TRUE, XField::type, XField::value, x_error(), X_MAX_ELEMENTS, X_NULL, X_RAW, X_SIZE_INVALID, X_STRUCT, X_SUCCESS, x_trace(), and xGetElementCount().

smaxShareBoolean()

int smaxShareBoolean	(	const char *	table,
		const char *	key,
		boolean	value
	)

Shares a single boolean value to SMA-X. All non-zero values are mapped to "1".

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
value	A boolean value.

Returns

X_SUCCESS (0), or else an appropriate error code (<0) from smaxShare().

See also

smaxShareBooleans()

References smaxShareBooleans(), and X_SUCCESS.

smaxShareBooleans()

int smaxShareBooleans	(	const char *	table,
		const char *	key,
		const boolean *	values,
		int	n
	)

Shares an array of boolean values to SMA-X. All non-zero values are mapped to "1".

Parameters

table	Hash table name.
key	Variable name under which the data is stored.
values	Pointer to boolean[] array.
n	Number of elements in array to share.

Returns

X_SUCCESS (0), or else an appropriate error code (<0) from smaxShare().

See also

smaxShareBoolean()

References smaxShare(), X_BOOLEAN, and X_SUCCESS.

smaxShareBytes()

int smaxShareBytes	(	const char *	table,
		const char *	key,
		const char *	values,
		int	n
	)

Shares a binary sequence to SMA-X.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
values	pointer to the byte buffer.
n	Number of bytes in buffer to share.

Returns

X_SUCCESS (0), or else an appropriate error code (<0) from smaxShare().

See also

smaxShareShorts()

smaxShareInts()

smaxShareLongs()

smaxShareInt()

References smaxShare(), X_BYTE, and X_SUCCESS.

smaxShareDouble()

int smaxShareDouble	(	const char *	table,
		const char *	key,
		double	value
	)

Shares a single floating point value to SMA-X.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
value	floating-point value.

Returns

X_SUCCESS (0), or else an appropriate error code (<0) from smaxShare().

See also

smaxShareDoubles()

smaxShareFloats()

References smaxShareDoubles(), and X_SUCCESS.

smaxShareDoubles()

int smaxShareDoubles	(	const char *	table,
		const char *	key,
		const double *	values,
		int	n
	)

Shares an array of doubles to SMA-X.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
values	Pointer to double[] array.
n	Number of elements in array to share.

Returns

X_SUCCESS (0), or else an appropriate error code (<0) from smaxShare().

See also

smaxShareDouble()

smaxShareFloats()

References smaxShare(), X_DOUBLE, and X_SUCCESS.

smaxShareField()

int smaxShareField	(	const char *	table,
		const XField *	f
	)

Share a field object, which may contain any SMA-X data type.

Parameters

table	Hash table in which to write entry.
f	Pointer for XField holding the data to share.

Returns

X_SUCCESS (0) if successful, or X_NO_INIT if the SMA-X library was not initialized. X_GROUP_INVALID if the table name is invalid. X_NAME_INVALID if the 'key' argument is invalid. X_SIZE_INVALID if ndim or sizes are invalid. X_NULL if the 'value' argument is NULL. X_NO_SERVICE if there was no connection to the Redis server. X_FAILURE if there was an underlying failure.

See also

smaxShare()

smaxShareField()

smaxShareStruct()

xSetField()

xGetField()

References XField::name, smaxShareStruct(), XField::type, XField::value, X_NO_SERVICE, X_STRUCT, X_SUCCESS, x_trace(), and xGetAggregateID().

smaxShareFloats()

int smaxShareFloats	(	const char *	table,
		const char *	key,
		const float *	values,
		int	n
	)

Shares an array of floats to SMA-X.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
values	Pointer to float[] array.
n	Number of elements in array to share.

Returns

X_SUCCESS (0), or else an appropriate error code (<0) from smaxShare().

See also

smaxShareDouble()

smaxShareDoubles()

References smaxShare(), X_FLOAT, and X_SUCCESS.

smaxShareHex()

int smaxShareHex	(	const char *	table,
		const char *	key,
		long long	value
	)

Shares a single integer value to SMA-X in a hexadecimal representatin.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
value	Integer value.

Returns

X_SUCCESS (0), or else an appropriate error code (<0) from smaxShare().

See also

smaxShareInt()

References smaxShare(), X_LONG_HEX, and X_SUCCESS.

smaxShareInt()

int smaxShareInt	(	const char *	table,
		const char *	key,
		long long	value
	)

Shares a single integer value to SMA-X.

Parameters

table	Hash table name.
key	Variable name under which the data is stored.
value	Integer value.

Returns

X_SUCCESS (0), or else an appropriate error code (<0) from smaxShare().

See also

smaxShareHex()

smaxShareInts()

References smaxShareLongs(), and X_SUCCESS.

smaxShareInts()

int smaxShareInts	(	const char *	table,
		const char *	key,
		const int *	values,
		int	n
	)

Shares an array of long integers to SMA-X.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
values	Pointer to int[] array.
n	Number of elements in array to share.

Returns

X_SUCCESS (0), or else an appropriate error code (<0) from smaxShare().

See also

smaxShareLongs()

smaxShareShorts()

smaxShareBytes()

smaxShareInt()

References smaxShare(), X_INT, and X_SUCCESS.

smaxShareLongs()

int smaxShareLongs	(	const char *	table,
		const char *	key,
		const long long *	values,
		int	n
	)

Shares an array of wide integers to SMA-X.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
values	Pointer to long long[] array.
n	Number of elements in array to share.

Returns

X_SUCCESS (0), or else an appropriate error code (<0) from smaxShare().

See also

smaxShareInts()

smaxShareShorts()

smaxShareBytes()

smaxShareInt()

References smaxShare(), X_LONG, and X_SUCCESS.

smaxShareShorts()

int smaxShareShorts	(	const char *	table,
		const char *	key,
		const short *	values,
		int	n
	)

Shares an array of shorts to SMA-X.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
values	Pointer to short[] array.
n	Number of elements in array to share.

Returns

X_SUCCESS(0), or else an appropriate error code (<0) from smaxShare().

See also

smaxShareInt()

smaxShareBytes()

smaxShareInts()

smaxShareLongs()

References smaxShare(), X_SHORT, and X_SUCCESS.

smaxShareString()

int smaxShareString	(	const char *	table,
		const char *	key,
		const char *	sValue
	)

Shares a single string value to SMA-X.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
sValue	Pointer to string.

Returns

X_SUCCESS (0), or else an appropriate error code (<0) from smaxShare().

See also

smaxShareStrings()

References smaxShare(), X_RAW, and X_SUCCESS.

smaxShareStrings()

int smaxShareStrings	(	const char *	table,
		const char *	key,
		const char **	sValues,
		int	n
	)

Shares an array of strings to SMA-X.

Parameters

table	The hash table name.
key	The variable name under which the data is stored.
sValues	Pointer to array of string pointers.
n	Number of elements in array to share.

Returns

X_SUCCESS (0), or else an appropriate error code (<0) from smaxShare().

See also

smaxShareString()

References smaxShare(), x_error(), X_NULL, X_RAW, and X_SUCCESS.

smaxShareStruct()

int smaxShareStruct	(	const char *	id,
		const XStructure *	s
	)

Share a structure, and all its data including recursive sub-structures, in a single atromic transaction.

Parameters

id	Structure's ID, i.e. its own aggregated hash table name.
s	Pointer to the structure data.

Returns

X_SUCCESS (0) if successful, or X_NO_INIT if the SMA-X library was not initialized. X_GROUP_INVALID if the table name is invalid. X_NAME_INVALID if the 'key' argument is invalid. X_NULL if the 'value' argument is NULL. X_NO_SERVICE if there was no connection to the Redis server. X_FAILURE if there was an underlying failure.

See also

smaxShare()

smaxShareField()

xCreateStruct()

References smaxCreateField(), X_NO_SERVICE, X_STRUCT, and X_SUCCESS.

smaxStringToValues()

int smaxStringToValues	(	const char *	str,
		void *	value,
		XType	type,
		int	eCount,
		int *	pos
	)

Deserializes a string to binary values.

Parameters

[in]	str	Serialized ASCII representation of the data (as stored by Redis).
[out]	value	Pointer to the buffer that will hold the binary values. The caller is responsible for ensuring the buffer is sufficiently sized for holding the data for the given variable.
[in]	type	Share type, e.g. X_INT. The types X_RAW, X_STRUCT are not supported by this function.
[in]	eCount	Number of elements to retrieve. Ignored for X_STRUCT.
[out]	pos	Parse position, i.e. the number of characters parsed from the input string...

Returns

Number of elements successfully parsed, or a negative error code:

                        X_NULL               If the value or str argument is NULL.
                        X_TYPE_INVALID       If the type is not supported.
                        X_SIZE_INVALID       If size is invalid (e.g. X_RAW, X_STRUCT)
                        X_PARSE_ERROR        If the tokens could not be parsed in the format expected

References smaxUnpackStrings(), X_BOOLEAN, X_BYTE, X_BYTE_HEX, X_DOUBLE, x_error(), X_FLOAT, X_INT, X_INT_HEX, X_LONG, X_LONG_HEX, X_NULL, X_RAW, X_SHORT, X_SHORT_HEX, X_SIZE_INVALID, X_STRING, X_STRUCT, x_trace(), X_TYPE_INVALID, xElementSizeOf(), xIsCharSequence(), xParseBoolean(), xParseDouble(), and xZero().

smaxStringType()

char * smaxStringType

(

XType

type

)

Returns the string type for a given XType argument as a constant expression. For examples X_LONG -> "int64".

Parameters

type	SMA-X type, e.g. X_FLOAT

Returns

Corresponding string type, e.g. "float". (Default is "string" – since typically anything can be represented as strings.)

See also

smaxTypeForString()

References X_BOOLEAN, X_BYTE, X_BYTE_HEX, X_DOUBLE, x_error(), X_FLOAT, X_INT, X_INT_HEX, X_LONG, X_LONG_HEX, X_RAW, X_SHORT, X_SHORT_HEX, X_STRING, X_STRUCT, and X_UNKNOWN.

smaxSubscribe()

int smaxSubscribe	(	const char *	table,
		const char *	key
	)

Subscribes to a specific key(s) in specific group(s). Both the group and key names may contain Redis subscription patterns, e.g. '*' or '?', or bound characters in square-brackets, e.g. '[ab]'. The subscription only enables receiving update notifications from Redis for the specified variable or variables. After subscribing, you can either wait on the subscribed variables to change, or add callback functions to process subscribed variables changes, via smaxAddSubscriber().

Parameters

table	Variable group pattern, i.e. hash-table names. (NULL is the same as '*').
key	Variable name pattern. (if NULL then subscribes only to the table stem).

Returns

X_SUCCESS if successfully subscribed to the Redis distribution channel. X_NO_SERVICE if there is no active connection to the Redis server. X_NULL if the channel argument is NULL X_NO_INIT if the SMA-X library was not initialized.

See also

smaxUnsubscribe()

smaxWaitOnSubscribed()

smaxWaitOnSubscribedGroup()

smaxWaitOnSubscribedVar()

smaxWaitOnAnySubscribed()

smaxAddSubscriber()

References redisxSubscribe(), and X_SUCCESS.

smaxSync()

int smaxSync	(	XSyncPoint *	sync,
		int	timeoutMillis
	)

Waits for the queue to reach the specified sync point, up to an optional timeout limit.

Parameters

sync

Pointer to a queued synchronization point.

timeoutMillis

An optional timeout in milliseconds. When set to a positive value The call will be guaranteed to return in the specified interval, whether or not the pipelined reads all succeeded. The return value can be used to check for errors or if the call timed out before all data were collected. If X_TIMEDOUT is returned, smax_end_bulk_pulls() may be called again to allow more time for the queued read operations to complete. 0 or negative timeout values will cause the call to wait indefinitely until reads are complete.

Returns

X_SUCCESS (0) if all reads have completed successfully, or the first read error that was enountered (e.g. RM_INVALID_KEY), or: X_TIMEDOUT if the call timed out while still awaiting data for the queued read requests. X_NULL if the SyncPoint argument is NULL, or its mutex/condition field have not been initialized. X_FAILURE if the SyncPoint's mutex has not been initialized.

or the first pull error encountered in the queue since the current batch began.

See also

smaxCreateSyncPoint()

smaxWaitQueueComplete()

References XSyncPoint::isComplete, XSyncPoint::lock, XSyncPoint::status, x_error(), X_FAILURE, X_INCOMPLETE, X_NULL, X_SUCCESS, X_TIMEDOUT, x_trace(), and xvprintf.

smaxTimestamp()

int smaxTimestamp

(

char *

buf

)

Prints the current time into the supplied buffer with subsecond precision.

Parameters

[out]

buf

Pointer to string buffer, must be at least X_TIMESTAMP_LENGTH in size.

Returns

Number of characters printed, not including the terminating '\0', or else an error code (<0) if the buf argument is NULL.

References smaxTimeToString().

smaxTimeToString()

int smaxTimeToString	(	const struct timespec *	time,
		char *	buf
	)

*‍/

Prints the given UNIX time into the supplied buffer with subsecond precision.

Parameters

[in]	time	Pointer to time value.
[out]	buf	Pointer to string buffer, must be at least X_TIMESTAMP_LENGTH in size.

Returns

Number of characters printed, not including the terminating '\0', or else an error code (<0) if the buf argument is NULL.

References x_error(), and X_NULL.

smaxTypeForString()

XType smaxTypeForString

(

const char *

type

)

Returns the XType for a given case-sensitive type string. For example "float" -> X_FLOAT. The value "raw" will return X_RAW.

Parameters

type	String type, e.g. "struct".

Returns

Corresponding XType, e.g. X_STRUCT. (The default return value is X_RAW, since all Redis values can be represented as raw strings.)

See also

smaxStringType()

References X_BOOLEAN, X_BYTE, X_DOUBLE, x_error(), X_FLOAT, X_INT, X_LONG, X_RAW, X_SHORT, X_STRING, X_STRUCT, and X_UNKNOWN.

smaxUnpackStrings()

int smaxUnpackStrings	(	const char *	data,
		int	len,
		int	count,
		char **	dst
	)

Returns an array of dynamically allocated strings from a packed buffer of consecutive 0-terminated or '\r'-separated string elements.

Parameters

[in]	data	Pointer to the packed string data buffer.
[in]	len	length of packed string (excl. termination).
[in]	count	Number of string elements expected. If fewer than that are found in the packed data, then the returned array of pointers will be padded with NULL.
[out]	dst	An array of string pointers (of size 'count') which will point to dynamically allocated string (char*) elements. The array is assumed to be uninitialized, and elements will be allocated as necessary.

Returns

X_SUCCESS (0) if successful, or X_NULL if one of the argument pointers is NULL, or else X_INCOMPLETE if some of the components were too large to unpack (alloc error).

References x_error(), X_INCOMPLETE, X_NULL, and X_SUCCESS.

smaxUnsubscribe()

int smaxUnsubscribe	(	const char *	table,
		const char *	key
	)

Unsubscribes from a specific key(s) in specific group(s). Both the group and key names may contain Redis subscription patterns, e.g. '*' or '?', or bound characters in square-brackets, e.g. '[ab]'. Unsubscribing will only stops the delivery of update notifications for the affected varuiables, but does not deactivate the associated callbacks for these added via smaxAddSubscriber(). Therefore you should also call smaxRemovesubscribers() as appropriate to deactivate actions that can no longer get triggered by updates.

Parameters

table	Variable group pattern, i.e. structure or hash-table name(s) (NULL is the same as '*').
key	Variable name pattern. (if NULL then unsubscribes only from the table stem).

Returns

X_SUCCESS if successfully unsubscribed to the Redis distribution channel. X_NO_SERVICE if there is no active connection to the Redis server. X_NULL if the channel argument is NULL X_NO_INIT if the SMA-X library was not initialized.

See also

smaxSubscribe()

smaxRemoveSubscribers()

References redisxUnsubscribe(), and X_SUCCESS.

smaxValuesToString()

char * smaxValuesToString	(	const void *	value,
		XType	type,
		int	eCount,
		char *	trybuf,
		int	trylength
	)

Serializes binary values into a string representation (for Redis).

Parameters

[in]	value	Pointer to an array of values, or NULL to produce all zeroes. If type is X_STRING value should be a pointer to a char** (array of string pointers), as opposed to X_CHAR(n), which expects a contiguous char* buffer with [n * eCount] length (Note, a char[eCount][n] is equivalent to such a char* buffer).
[in]	type	Share type, e.g. X_DOUBLE. All type except X_STRUCT are supported.
[in]	eCount	Number of elements (ignored for X_RAW).
[in,out]	trybuf	(optional) An optional pointer to a buffer that will be used if sufficient (can be NULL).
[in]	trylength	(optional) Size of the optional buffer.

Returns

The pointer to the string buffer holding the ASCII values. It may be the supplied buffer (if sufficient), the input value (if type is X_RAW) or else a dynamically allocated buffer, or NULL if the key is malformed. If the returned value is neither the input value nor trybuf, then the caller is responsible for calling free() on the dynamically allocated buffer after use.

References X_BOOLEAN, X_BYTE, X_BYTE_HEX, X_DOUBLE, x_error(), X_FLOAT, X_INT, X_INT_HEX, X_LONG, X_LONG_HEX, X_RAW, X_SHORT, X_SHORT_HEX, X_STRING, X_STRUCT, x_trace_null(), X_UNKNOWN, xElementSizeOf(), xIsCharSequence(), xPrintDouble(), xPrintFloat(), and xStringElementSizeOf().

smaxWaitOnAnySubscribed()

int smaxWaitOnAnySubscribed	(	char **	changedTable,
		char **	changedKey,
		int	timeout
	)

Waits until any variable was pushed on any host, returning both the host and variable name for the updated value. The variable must be already subscribed to with smaxSubscribe(), or else the wait will not receive update notifications.

Parameters

[out]	changedTable	Pointer to the variable that points to the string buffer for the returned table name or NULL. The lease of the buffer is for the call only.
[out]	changedKey	Pointer to the variable that points to the string buffer for the returned variable name or NULL. The lease of the buffer is for the call only.
[in]	timeout	(s) Timeout value. 0 or negative values result in an indefinite wait.

Returns

X_SUCCESS (0) if a variable was pushed on a host. X_NO_INIT if the SMA-X sharing was not initialized via smaxConnect(). X_NO_SERVICE if the connection was broken X_GROUP_INVALID if the buffer for the returned table name is NULL. X_NAME_INVALID if the buffer for the returned variable name is NULL. X_INTERRUPTED if smaxReleaseWaits() was called. X_INCOMPLETE if the wait timed out.

See also

smaxSubscribe()

smaxWaitOnSubscribed()

smaxWaitOnSubscribedGroup()

smaxReleaseWaits()

References RELEASEID, smaxIsConnected(), x_error(), X_GROUP_INVALID, X_INCOMPLETE, X_INTERRUPTED, X_NAME_INVALID, X_NO_SERVICE, X_SEP_LENGTH, X_SUCCESS, xdprintf, xLastSeparator(), xStringCopyOf(), and xvprintf.

smaxWaitOnSubscribed()

int smaxWaitOnSubscribed	(	const char *	table,
		const char *	key,
		int	timeout
	)

Waits for a specific pushed entry. There must be an active subscription that includes the specified group & variable, or else the call will block indefinitely.

Parameters

table	Hash table name
key	Variable name to wait on.
timeout	(s) Timeout value. 0 or negative values result in an indefinite wait.

Returns

X_SUCCESS (0) if the variable was updated on some host (or owner). X_NO_INIT if the SMA-X sharing was not initialized via smaxConnect(). X_GROUP_INVALID if the 'group' argument is NULL; X_NAME_INVALID if the 'key' argument is NULL. X_REL_PREMATURE if smaxReleaseWaits() was called.

See also

smaxSubscribe()

smaxWaitOnSubscribed()

smaxWaitOnSubscribedGroup()

smaxWaitOnSubscribedVar()

smaxWaitOnAnySubscribed()

smaxReleaseWaits()

References x_error(), X_GROUP_INVALID, X_NAME_INVALID, and X_SUCCESS.

smaxWaitOnSubscribedGroup()

int smaxWaitOnSubscribedGroup	(	const char *	matchTable,
		char **	changedKey,
		int	timeout
	)

Waits for changes on a specific group. The must be an active subscription including that group, or else the call will block indefinitely.

Parameters

[in]	matchTable	Hash table name (e.g. owner ID) to wait on.
[out]	changedKey	Pointer to the string that holds the name of the variable which unblocked the wait or which is set to NULL. The lease of the buffer is for the call only. The caller should copy its content if persistent storage is required.
[in]	timeout	(s) Timeout value. 0 or negative values result in an indefinite wait.

Returns

X_SUCCESS (0) if a variable was updated on the host. X_NO_INIT if the SMA-X sharing was not initialized via smaxConnect(). X_GROUP_INVALID if the table name to match is invalid. X_REL_PREMATURE if smaxReleaseWaits() was called.

See also

smaxSubscribe()

smaxWaitOnSubscribedVar()

smaxWaitOnSubscribed()

smaxWaitOnAnySubscribed()

smaxReleaseWaits()

References x_error(), X_GROUP_INVALID, and X_SUCCESS.

smaxWaitOnSubscribedVar()

int smaxWaitOnSubscribedVar	(	const char *	matchKey,
		char **	changedTable,
		int	timeout
	)

Waits for a specific pushed variable from any group/table. There must be an active subscription that includes the specified variable in one or more groups/tables, or else the call will block indefinitely.

Parameters

[in]	matchKey	Variable name to wait on.
[out]	changedTable	Pointer to the string that holds the name of the table which unblocked the wait or which is set to NULL. The lease of the buffer is for the call only. The caller should copy its content if persistent storage is required.
[in]	timeout	(s) Timeout value. 0 or negative values result in an indefinite wait.

Returns

X_SUCCESS (0) if the variable was updated on some host (or owner). X_NO_INIT if the SMA-X sharing was not initialized via smaxConnect(). X_NAME_INVALID if the 'key' argument is NULL. X_REL_PREMATURE if smaxReleaseWaits() was called.

See also

smaxSubscribe()

smaxWaitOnSubscribedGroup()

smaxWaitOnSubscribed()

smaxWaitOnAnySubscribed()

smaxReleaseWaits()

References x_error(), X_NAME_INVALID, and X_SUCCESS.

smaxWaitQueueComplete()

int smaxWaitQueueComplete

(

int

timeoutMillis

)

Waits until all queued pull requests have been retrieved from the database, or until the specified timeout it reached.

Parameters

timeoutMillis

An optional timeout in milliseconds. When set to a positive value The call will be guaranteed to return in the specified interval, whether or not the pipelined reads all succeeded. The return value can be used to check for errors or if the call timed out before all data were collected. If X_TIMEDOUT is returned, smax_end_bulk_pulls() may be called again to allow more time for the queued read operations to complete. 0 or negative timeout values will cause the call to wait indefinitely until reads are complete.

Returns

X_SUCCESS (0) if all reads have completed successfully, or the first read error that was enountered (e.g. RM_INVALID_KEY), or: X_TIMEDOUT if the call timed out while still awaiting data for the queued read requests.

See also

smaxSync()

References XSyncPoint::isComplete, XSyncPoint::lock, smaxSync(), XSyncPoint::status, X_INCOMPLETE, and X_SUCCESS.

x2smaxField()

int x2smaxField

(

XField *

f

)

Converts a standard xchange field (with a native value storage) to an SMA-X field with serialized string value storage.

Parameters

[in,out]

f

Pointer to field to convert

Returns

X_SUCCESS (0) if successful, or X_NULL if the input field or the serialized value is NULL.

See also

smax2xField()

x2smaxStruct()

References XField::isSerialized, smaxValuesToString(), TRUE, XField::type, XField::value, x2smaxStruct(), x_error(), X_NULL, X_RAW, X_STRUCT, X_SUCCESS, x_trace(), and xGetFieldCount().

x2smaxStruct()

int x2smaxStruct

(

XStructure *

s

)

Converts a standard xchange structure (with a native value storage) to an SMA-X structure with serialized string value storage.

Parameters

s	Pointer to structure to convert

Returns

X_SUCCESS (0) if successful, or X_STRUCT_INVALID if the structure is NULL, or had a NULL substructure. X_NULL if there was a field that could not be converted.

See also

smax2xStruct()

x2smaxField()

References XStructure::firstField, XField::next, x2smaxField(), x_error(), X_STRUCT_INVALID, and X_SUCCESS.