smax-clib v1.0
A C/C++ client library for SMA-X
Loading...
Searching...
No Matches
smax-control.c File Reference

Functions

char * smaxControl (const char *table, const char *key, const void *value, XType type, int count, const char *replyTable, const char *replyKey, int timeout)
 
boolean smaxControlBoolean (const char *table, const char *key, boolean value, const char *replyTable, const char *replyKey, boolean defaultReply, int timeout)
 
double smaxControlDouble (const char *table, const char *key, double value, const char *replyTable, const char *replyKey, int timeout)
 
int smaxControlInt (const char *table, const char *key, int value, const char *replyTable, const char *replyKey, int defaultReply, int timeout)
 
char * smaxControlString (const char *table, const char *key, const char *value, const char *replyTable, const char *replyKey, int timeout)
 
int smaxSetControlFunction (const char *table, const char *key, SMAXControlFunction func, void *parg)
 

Detailed Description

Date
Created on Jun 11, 2025
Author
Attila Kovacs

Send and process control 'commands' via SMA-X by setting or monitored designated control variables Clients will set these and wait for a response in another variable, while servers will monitor the control variables and execute designated control functions when these variables are updated. The controlled application is expected to act on the request passed in the control variable, and post the result (such as the actual value) after the request was processed in the designated 'reply' variable.

For example, we set system:subsystem:control_voltage to 0.123456 to request that the given subsystem outputs the desired voltage. The program that controls the subsystem, monitors the control_voltage for requests ('commands'), and then sets the output voltage to the nearest possible value, then posts the actual value that was applied in system:subsystem:voltage. Suppose, it's DAC has a resolution of 0.01 V. In that case, it might 'reply' with voltage set to 0.12.

It is important that for every request received, the control program should post exactly one reply in the designated response variable.

The control calls of this module will simply wait for an update of the reply variable, and return the value set by the control program after the request is sent.

Since
1.0

Function Documentation

◆ smaxControl()

char * smaxControl ( const char *  table,
const char *  key,
const void *  value,
XType  type,
int  count,
const char *  replyTable,
const char *  replyKey,
int  timeout 
)

Sets an SMA-X control variable, and returns the response to the monitored reply value.

Parameters
tableSMA-X table name
keyThe command keyword
valuePointer to the value to set
typeThe type of the value
countNumber of elements in value
replyTableSMA-X table in which the reply is expected. It may also be NULL if it's the same as the table in which the control variable was set.
replyKeyThe keyword to monitor for responses.
timeout[s] Maximum time to wait for a response before returning NULL.
Returns
The raw value of the replyKey after it has changed, or NULL if there was an error (errno will indicate the type of error).
See also
smaxControlBoolean()
smaxControlInt()
smaxControlDouble()
smaxControlString()

References FALSE, smaxError(), smaxErrorDescription(), smaxShare(), smaxSubscribe(), smaxUnsubscribe(), x_error(), X_NAME_INVALID, X_SUCCESS, x_trace_null(), and x_warn().

◆ smaxControlBoolean()

boolean smaxControlBoolean ( const char *  table,
const char *  key,
boolean  value,
const char *  replyTable,
const char *  replyKey,
boolean  defaultReply,
int  timeout 
)

Sets a boolean type SMA-X control variable, and returns the boolean response to the monitored reply, or the specified default value in case of an error.

Parameters
tableSMA-X table name
keyThe command keyword
valuePointer to the value to set
replyTableSMA-X table in which the reply is expected. It may also be NULL if it's the same as the table in which the control variable was set.
replyKeyThe keyword to monitor for responses.
defaultReplyThe value to return in case of an error
timeout[s] Maximum time to wait for a response before returning NULL.
Returns
The boolean value of the monitored keyword after it updated, or the specified default value if there was an error (errno will indicate the type of error).
See also
smaxControlInt()
smaxControlDouble()
smaxControlString()

References smaxControl(), X_BOOLEAN, x_trace(), and xParseBoolean().

◆ smaxControlDouble()

double smaxControlDouble ( const char *  table,
const char *  key,
double  value,
const char *  replyTable,
const char *  replyKey,
int  timeout 
)

Sets a atring type SMA-X control variable, and returns the string response to the monitored reply, or NULL in case of an error.

Parameters
tableSMA-X table name
keyThe command keyword
valuePointer to the value to set
replyTableSMA-X table in which the reply is expected. It may also be NULL if it's the same as the table in which the control variable was set.
replyKeyThe keyword to monitor for responses.
timeout[s] Maximum time to wait for a response before returning NAN.
Returns
The double-precision value of the monitored keyword after it updated, or NAN if there was an error (errno will indicate the type of error).
See also
smaxControlBoolean()
smaxControlInt()
smaxControlDouble()

References NAN, smaxControl(), X_DOUBLE, and x_trace_null().

◆ smaxControlInt()

int smaxControlInt ( const char *  table,
const char *  key,
int  value,
const char *  replyTable,
const char *  replyKey,
int  defaultReply,
int  timeout 
)

Sets an integer-type SMA-X control variable, and returns the integer response to the monitored reply, or the specified default value in case of an error.

Parameters
tableSMA-X table name
keyThe command keyword
valuePointer to the value to set
replyTableSMA-X table in which the reply is expected. It may also be NULL if it's the same as the table in which the control variable was set.
replyKeyThe keyword to monitor for responses.
defaultReplyThe value to return in case of an error
timeout[s] Maximum time to wait for a response before returning NULL.
Returns
The integer value of the monitored keyword after it updated, or the specified default value if there was an error (errno will indicate the type of error).
See also
smaxControlBoolean()
smaxControlInt()
smaxControlString()

References smaxControl(), X_INT, and x_trace().

◆ smaxControlString()

char * smaxControlString ( const char *  table,
const char *  key,
const char *  value,
const char *  replyTable,
const char *  replyKey,
int  timeout 
)

Sets a atring type SMA-X control variable, and returns the string response to the monitored reply, or NULL in case of an error.

Parameters
tableSMA-X table name
keyThe command keyword
valuePointer to the value to set
replyTableSMA-X table in which the reply is expected. It may also be NULL if it's the same as the table in which the control variable was set.
replyKeyThe keyword to monitor for responses.
timeout[s] Maximum time to wait for a response before returning NULL.
Returns
The raw string value of the monitored keyword after it updated, or NULL if there was an error (errno will indicate the type of error).
See also
smaxControlBoolean()
smaxControlInt()
smaxControlDouble()
Since
1.1

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

◆ smaxSetControlFunction()

int smaxSetControlFunction ( const char *  table,
const char *  key,
SMAXControlFunction  func,
void *  parg 
)

Configures an SMA-X control function. The designated function will be called every time the monitored control variable is updated in the database, so it may act on the update as appropriate. If another control functions was already defined for the variable, it will be replaced with the new function. The same control function may be used with multiple control variables, given that the triggering control variable is passed to it as arguments.

When the control variables are updated, the associated control functions will be called asynchronously, such that previous control calls may be executing still while new ones are called. The design allows for control functions to take their sweet time executing, without holding up other time-sensitive SMA-X processing. If simultaneous execution of control functions is undesired, the control function(s) should implement mutexing as necessary to avoid conflicts / clobbering.

As a result of the asynchronous execution, there is also no guarantee of maintaining call order with respect to the order in which the control variables are updated. If two updates arrive in quick succession, it is possible that the asynchronous thread of the second one will make its call to its control function before the first one gets a chance. Thus, if order is important, you might want to process updates with a custom lower-level RedisxSubscriberCall wrapper instead (see smaxAddSubscriber()).

Parameters
tableThe hash table in which the control variable resides.
keythe control variable to monitor. It may not contain a sepatator.
funcThe new function to call if the monitored control variable receives an update, or NULL to clear a previously configured function for the given variable.
pargOptional pointer argument to pass along to the command procesing function, or NULL if the control function does not need extra data.
Returns
X_SUCCESS (0)

References SMAX_UPDATES, smaxAddSubscriber(), smaxSubscribe(), smaxUnsubscribe(), XField::value, x_error(), X_GROUP_INVALID, X_NAME_INVALID, X_SEP, X_SEP_LENGTH, X_SUCCESS, x_trace(), X_UNKNOWN, xAllocLookup(), xCreateField(), xDestroyField(), xGetAggregateID(), xLookupPut(), and xLookupRemove().