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:

alarmActionType
alarmActionData

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

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:

Usage

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.

See also

smc_connect_ex, smc_drop_alarm, smc_get_command_info