smc_create_alarm_ex

Description

Creates an alarm on one data item within a view on a connection.

Syntax

SMC_RETURN_CODE smc_create_alarm_ex
 (SMC_CONNECT_ID          clientId,
 	SMC_VIEW_ID             viewId,
 	SMC_DATAITEM_STRUCTP    dataItemHandle,
 	SMC_VALUE_UNIONP        alarmValueDataHandle,
 	SMC_DATAITEM_TYPE       alarmDatatype,
 	SMC_ALARM_ACTION_TYPE   alarmActionType, 
 	SMC_CHARP               alarmActionData,
 	SMC_VOIDP               userDataHandle,
 	SMC_GEN_CALLBACK        alarmCallback,
 	SMC_ALARM_IDP           alarmIdHandle)

Parameters

clientId: identifies the connection.

viewId: identifies a view created on the connection.

dataItemHandle: pointer to data item and statistic type.

alarmValueDataHandle: pointer to threshold at or above which the alarm is triggered.

alarmDatatype

the datatype of the alarm value must be one of the following and must match the expected datatype for the given data item:

SMC_DI_TYPE_DOUBLE
SMC_DI_TYPE_INT
SMC_DI_TYPE_LONG

alarmActionType

SMC_ALARM_A_NOTIFY (SMC_SERVER_ M_LIVE mode only) – invokes the alarm callback.
SMC_ALARM_A_EXEC_PROC (SMC_SERVER_ M_HISTORICAL mode only) – invokes the specified external program.
SMC_ALARM_A_LOG_TO_FILE (SMC_SERVER_ M_HISTORICAL mode only) – writes a message to the log file.

alarmActionData

pointer to null-terminated string whose contents depend on alarmActionType. If alarmActionType equals:

SMC_ALARM_A_NOTIFY – alarmActionData is ignored.
SMC_ALARM_A_EXEC_PROC – null-terminated string that contains the filename and optional parameter list of the program to invoke.
SMC_ALARM_A_LOG_TO_FILE – null-terminated string that contains the log file name.

These file names are on the system where Historical Server is running (which need not be where the application is running). The Historical Server must have access to the files.

userDataHandle: user-supplied pointer.

alarmCallback: identifies the notification function employed by alarmActionType, SMC_ALARM_A_NOTIFY.

alarmIdHandle: pointer to a variable, which should be declared as type SMC_ALARM_ID. If the call to smc_create_alarm succeeds, this variable contains the ID for the alarm.

Returns

Return value	Indicates
SMC_RET_SUCCESS	Function succeeded.
SMC_RET_FAILURE	Function failed.
SMC_RET_INVALID_CONNECT	Connection does not exist.

Examples

Example 1

This example assumes that:

You have created a connection using smc_connect_ex and have a clientId.
You have created a view on the connection and have a viewId.
The view contains the dataItem SMC_NAME_PAGE_LOGICAL_READ, SMC_STAT_VALUE_SAMPLE.

You have defined an alarm handler function, myAlarmHandler.

SMC_DATAITEM_STRUCT  dataItem =
                    { SMC_NAME_PAGE_LOGICAL_READ,
                      SMC_STAT_VALUE_SAMPLE };
 SMC_DATAITEM_STRUCTP dataItemHandle = &dataItem;
 SMC_VALUE_UNION alarmValue;
 SMC_VALUE_UNIONP alarmValueHandle = &alarmValue;
 SMC_ALARM_ID  alarmId;
 SMC_ALARM_IDP alarmIdHandle = &alarmId;
 alarmValue.longValue = 10L;
 
 if (smc_create_alarm_ex(clientId,
         viewId,
         dataItemHandle,
         alarmValueHandle,
         SMC_DI_TYPE_LONG,
         SMC_ALARM_A_NOTIFY,
         NULL, /* ignored */
         NULL,				/* no user data */
         myAlarmHandler,
         alarmIdHandle) != SMC_RET_SUCCESS) 
 {
 		printf("smc_create_alarm_ex failed\n");
 		/* do some cleanup */
 }

Usage

Alarms can be created on result data items, but not on key data items.
alarmIds are unique only within a given view.
Alarms are triggered for each row of a view where the data item value meets or exceeds the threshold.
Alarms are applied after filters, in the context of a refresh call.
Alarms are triggered at each refresh based upon a data item’s value (state) rather than the change of a data item’s value (transition).
Multiple alarms can be created on the same data item.
When used in a Historical Server connection during the definition of a recording session, smc_create_alarm_ex defines an alarm that will be created during the execution of a recording session.
Alarms cannot be defined in a Historical Server connection during a playback session.
When creating a log-to-file alarm, if you specify a UNIX directory for the location of the log file, be sure that the directory is valid and mounted on the machine where Historical Server is running. Also be sure that you have write permissions to the directory. If the directory you specify is invalid, unmounted, or not writable, Historical Server does not create a log file, nor does it issue a message advising you that the location is invalid.

The syntax of the alarm callback is:

SMC_VOID AlarmCallback
 (SMC_CONNECT_ID       clientId,
 	SMC_COMMAND_ID			       commandId,
 	SMC_VOIDP            userDataHandle)

Valid server modes

Mode	Availability
SMC_SERVER_M_LIVE	Yes
SMC_SERVER_M_HISTORICAL	Yes (for recording)

Errors

Error	Indicates
SMC_RET_INSUFFICIENT_MEMORY	Insufficient memory
SMC_RET_INVALID_ALARM_VALUE	Invalid alarm value
SMC_RET_INVALID_API_FUNCTION	Invalid use of obsolete and replacement functions within the same program
SMC_RET_INVALID_DATAITEM_FOR_ ALARM	Data item statistic type or alarm value mismatched
SMC_RET_INVALID_DATATYPE	Invalid datatype
SMC_RET_INVALID_DINAME	Data item does not exist
SMC_RET_INVALID_DISTAT	Data item statistic type does not exist
SMC_RET_INVALID_PARAMETER	Invalid parameter value
SMC_RET_INVALID_VIEWID	View does not exist
SMC_RET_INTERNAL_ERROR	Internal error

Callback parameters

Parameter	Description
clientId	Identifies the connection.
commandId	Identifies the instance of a command.
userDataHandle	Pointer that was set by the call to smc_create_alarm for this alarm.

The alarm callback function uses smc_get_command_info to obtain information about the circumstances that triggered the alarm.