Alarm API Calls File Reference

TINE Local Alarm Server plus API routines. More...

Functions
int	AppendAlarmInfoTable (char *eqm, ADS *ads)
	Inserts an alarm definition into the alarm definition table. More...
int	AppendAlarmInfoTableEx (char *eqm, ADS *ads, char *filterString)
	Inserts an alarm definition into the alarm definition table. The extended call accepts a parseable filter string. More...
int	AppendAlarmWatchTable (char *eqm, char *prp, char *dev, int siz, int fmt, int atyp, int sev, int sys, ALM_THRESHOLDS *thr)
	Inserts a property to be monitored into the local alarm server's Watch Table. More...
int	ApplyAlarmWatchFilter (char *eqm, char *prp, char *dev, char *parsableFilterString)
	Applies a filter to an existing local alarm server's Watch Table. More...
void	ClearAlarm (char *eqm, int devNr)
	Instructs the local alarm server table that the given alarm is to be cleared. More...
void	ClearDeviceAlarm (char *eqm, char *devname)
	Instructs the local alarm server table that the given alarm is to be cleared. More...
int	GetAlarmCodeOscillationWindow (const char *eqm, int code)
	Gets the size of the alarm oscillation window in clear counts. More...
int	GetAlarmCollapseWindow (void)
	Gets the size of the alarm collapse window in counts. More...
int	GetAlarmDataChangeWindow (void)
	Gets the size of the alarm datachange window in seconds. More...
int	GetAlarmDefinition (char *eqm, UINT32 code, ADS *ads)
	Gets the alarm definition for the alarm code specified. More...
int	GetAlarmHeartbeat (void)
	Gets the size of the heartbeat alarm window in seconds before the 'heartbeat' flag is applied to an alarm. More...
int	GetAlarmOscillationWindow (void)
	Gets the size of the alarm oscillation window in clear counts. More...
int	GetAlarmTableMaximumSize (void)
	Gets the maximum number of alarms managed by the local alarm server. More...
int	GetAlarmTerminationWindow (void)
	Gets the size of the termination window in seconds before a terminated alarm is discarded from the local alarm list. More...
int	GetAllowOfflineAlarms (void)
	Gets the local alarm server setting to allow or disallow alarms for devices declared offline. More...
int	GetNewAlarmWindow (void)
	Gets the size of the new alarm window in seconds before a new alarm is no longer declared as new. More...
void	RemoveAlarm (char *eqm, int devNr, UINT32 code)
	Instructs the local alarm server table that the given alarm is to be marked for removal. More...
void	RemoveDeviceAlarm (char *eqm, char *devname, UINT32 code)
	Instructs the local alarm server table that the given alarm is to be marked for removal. More...
int	SetAlarm (char *eqm, int devNr, UINT32 almCode, BYTE *almData)
	Inserts an alarm into the local alarm server table. More...
int	SetAlarmCodeOscillationWindow (const char *eqm, int code, int value)
	Sets the size of the alarm oscillation window in clear counts. More...
int	SetAlarmCollapseWindow (int value)
	Sets the size of the alarm collapse window in counts. More...
void	SetAlarmDataChangeWindow (int timeInSeconds)
	Sets the size of the alarm datachange window in seconds. More...
int	SetAlarmEx (char *eqm, int devNr, UINT32 almCode, BYTE *almData, BYTE flags)
	Inserts an alarm into the local alarm server table. More...
int	SetAlarmEx2 (char *eqm, int devNr, UINT32 almCode, char *almTag, BYTE *almData, BYTE flags)
	Inserts an alarm into the local alarm server table. More...
void	SetAlarmHeartbeat (int timeInSeconds)
	Sets the size of the heartbeat alarm window in seconds before the 'heartbeat' flag is applied to an alarm. More...
int	SetAlarmOscillationWindow (int value)
	Sets the size of the alarm oscillation window in clear counts. More...
void	SetAlarmTableMaximumSize (int tableSize)
	Sets the maximum number of alarms managed by the local alarm server. More...
void	SetAlarmTerminationWindow (int timeInSeconds)
	Sets the size of the termination window in seconds before a terminated alarm is discarded from the local alarm list. More...
void	SetAllowOfflineAlarms (int value)
	Instructs the local alarm server to allow or disallow alarms for devices declared offline. More...
void	SetAvailableMemoryThreshold (UINT32 minAvailBytes)
	Sets the threshold (in bytes) used in setting 'low main memory' alarms. More...
void	SetDelayAlarmSurvey (int delayInSeconds)
	Instructs the local alarm server to delay surveying alarms (for the alarm watch table) More...
int	SetDeviceAlarm (char *eqm, char *devname, UINT32 almCode, BYTE *almData, BYTE flags)
	Inserts an alarm into the local alarm server table. More...
int	SetDeviceAlarmEx (char *eqm, char *devname, UINT32 almCode, char *almTag, BYTE *almData, BYTE flags)
	Inserts an alarm into the local alarm server table. More...
int	SetFreeBlocksAlarmThreshold (char *path, UINT32 minFreeBlocks)
	Sets the threshold (in blocks) used in setting 'low disk space' alarms. More...
void	SetNewAlarmWindow (int timeInSeconds)
	Sets the size of the new alarm window in seconds before a new alarm is no longer declared as new. More...

Variables
int	AlarmDataChangeWindow = DEFAULT_ALARM_DATACHANGE_WINDOW
	Determines the minimum time a data change alarm is to keep its timestamp in the local alarm table. More...
int	AlarmHeartbeat = DEFAULT_ALARM_HEARTBEAT
	Determines the time interval at the 'HEARTBEAT' flag will be re-issued for persistent alarms. More...
int	AlarmInstantWindow = DEFAULT_INSTANT_WINDOW
	Determines the minimum time an alarm is to remain in the local alarm table before it can be removed. More...
int	AlarmTestState = 0
	Determines the minimum time an alarm is to remain in the local alarm table before it can be removed. More...
int	AlarmWindow = DEFAULT_ALARM_WINDOW
	Determines the minimum time an alarm is to remain in the local alarm table before it can be removed. More...
int	MaxNumberAlarms = MAXALARMS
	Determines the maximum number of alarms which can be maintained in the local alarm server's alarm list. More...
int	TerminationWindow = DEFAULT_TERMINATION_WINDOW
	Determines the minimum time an expired alarm is to remain in the local alarm table. More...

Detailed Description

TINE Local Alarm Server plus API routines.

The API routines offered here pertain directly to the TINE Local Alarm Server maintained on the running server. A server can of course run without setting alarms. However a control system will suffer if important information relating to the health of the system is surpressed. One can set a certain category of alarms (threshold alarms) without issuing any API call, but instead supplying a startup configuration file 'almwatch.csv' with instructions as to which properties to call and into what range the data returned must fall in order to function properly. Otherwise calls to ClearAlarm() and SetAlarm() for instance should be made inside a server's IO loop where necessary.

Function Documentation

AppendAlarmInfoTable()

int AppendAlarmInfoTable	(	char *	eqm,
		ADS *	ads
	)

Inserts an alarm definition into the alarm definition table.

As an alternative to the <local name>-alarms.csv configuration file, the front end server can make use of this API call in order to fill in the alarm definition table describing locally generated alarms. This is particularly useful for embedded platforms where there is no file system, or where a TINE server is used as a translation layer and needs to map a given alarm system onto the TINE alarm system.

Parameters

eqm	is the 6-character local equipment identifier name, which is internal to server.
ads	is a pointer to an Alarm Definition Structure (ADS) containing the alarm table information which is to be appended to the alarm definition table.

Returns

0 upon success, otherwise a TINE error code.

 
  strncpy(ads.alarmTag,"Threshold exceeded",16);
  ads.alarmCode = 512;
  ads.alarmMask = 0xff;
  ads.alarmSeverity = 7;
  ads.alarmDataFormat = BFMT(CF_FLOAT);
  ads.alarmDataArraySize = 1;
  ads.alarmSystem = 640;
  strncpy(ads.alarmText,"Take action immediately!",40);
  strncpy(ads.dataText,"Current threshold setting",40);
  strncpy(ads.url,"alarm512.html",40);
  if ((cc=AppendAlarmInfoTable(EQPMODNAME,&ads)) != 0)
  {
    feclog("appendAlarmInfoTable : %s",erlst[cc]);
  }

References AppendAlarmInfoTableEx().

AppendAlarmInfoTableEx()

int AppendAlarmInfoTableEx	(	char *	eqm,
		ADS *	ads,
		char *	filterString
	)

Inserts an alarm definition into the alarm definition table. The extended call accepts a parseable filter string.

As an alternative to the <local name>-alarms.csv configuration file, the front end server can make use of this API call in order to fill in the alarm definition table describing locally generated alarms. This is particularly useful for embedded platforms where there is no file system, or where a TINE server is used as a translation layer and needs to map a given alarm system onto the TINE alarm system.

Parameters

eqm	is the 6-character local equipment identifier name, which is internal to server.
ads	is a pointer to an Alarm Definition Structure (ADS) containing the alarm table information which is to be appended to the alarm definition table.
filterString	is a parsable filter string defining the filter condition. This should be of the form /<context>/<server/<device>[<property>]<comparator><value> where <comparator> is one of '=', '!=', '>', or '<' and <value> is the filter's threshold value. The filter target address should deliver (or be able to deliver) a single numeric or string name value. If the filter string cannot be parsed of the target address does not exists, then no filter will be established. The filter conditions must be met for the alarm specified in the ADS to be applied via any of the SetAlarm() methods. Unless, in addition, the filterString has been concatenated with an optional severity, which should be used when the filter criterion is not met. The optional serverity should be specified by appending &sev=<severity> at the end of the filter string.

Returns

0 upon success, otherwise a TINE error code.

 
  strncpy(ads.alarmTag,"Threshold exceeded",16);
  ads.alarmCode = 512;
  ads.alarmMask = 0xff;
  ads.alarmSeverity = 7;
  ads.alarmDataFormat = BFMT(CF_FLOAT);
  ads.alarmDataArraySize = 1;
  ads.alarmSystem = 640;
  strncpy(ads.alarmText,"Take action immediately!",40);
  strncpy(ads.dataText,"Current threshold setting",40);
  strncpy(ads.url,"alarm512.html",40);
  if ((cc=AppendAlarmInfoTableEx(EQPMODNAME,&ads),"/PETRA/Idc/Buffer-0[I]>0.05") != 0)
  {
    feclog("appendAlarmInfoTable : %s",erlst[cc]);
  }

Referenced by AppendAlarmInfoTable().

AppendAlarmWatchTable()

int AppendAlarmWatchTable	(	char *	eqm,
		char *	prp,
		char *	dev,
		int	siz,
		int	fmt,
		int	atyp,
		int	sev,
		int	sys,
		ALM_THRESHOLDS *	thr
	)

Inserts a property to be monitored into the local alarm server's Watch Table.

Certain alarms are to be set whenever the value of a property exceeds a defineable threshold. Such alarms can be managed automatically by the local alarm server if the alarm criteria are entered into the alarm watch table. This can be achieved by calling this routine (or supplying a startup configuration file almwatch.csv).

Parameters

eqm	is the 6-character local equipment identifier name, which is internal to server.
prp	is the property which is to be called by the local alarm server
dev	is the device name associated with the property to be called by the local alarm server
siz	is the data array size to be called by the local alarm server
fmt	is the TINE data format to be called by the local alarm server
atyp	is the TINE data array type to be applied to the property called by the local alarm server
sev	is the severity of the alarm issued when the data returned by the call exceed the given thresholds.
sys	is the alarm system identifier to be associated with the alarm.
thr	is an ALM_THRESHOLDS object specifying the threshold criteria for setting the alarm

Note

Information can also be entered into the alarm watch table by supplying the startup configuration file almwatch.csv, where the input parameters are given in the relevant columns. This is frequently the preferred way of inputting such alarm information, since if does not involve hard-coding such alarm criteria.

Returns

0 upon success, otherwise a TINE error code.

References argument_list_error, and out_of_server_memory.

ApplyAlarmWatchFilter()

int ApplyAlarmWatchFilter	(	char *	eqm,
		char *	prp,
		char *	dev,
		char *	parsableFilterString
	)

Applies a filter to an existing local alarm server's Watch Table.

A server can filter out automatic watch table alarms by applying a filter condition which must be satisfied.

Parameters

eqm	is the 6-character local equipment identifier name, which is internal to server.
prp	is the property which is to be called by the local alarm server
dev	is the device name associated with the property to be called by the local alarm server
parsableFilterString	is a parsable filter string defining the filter condition. This should be of the form /<context>/<server/<device>[<property>]<comparator><value> where <comparator> is one of '=', '!=', '>', or '<' and <value> is the filter's threshold value. The filter target address should deliver (or be able to deliver) a single numeric or string name value. Multiple comparator/value combinations can be ANDed (&&) or ORed (||) to refine the filter condition. If the filter string cannot be parsed or the target address does not exists, then no filter will be established. In addition, the filterString can be concatenated with an optional severity, which should be used when the filter criterion is not met. The optional serverity should be specified by appending &sev=<severity> at the end of the filter string.

Returns

0 upon success, otherwise a TINE error code.

ClearAlarm()

void ClearAlarm	(	char *	eqm,
		int	devNr
	)

Instructs the local alarm server table that the given alarm is to be cleared.

A server can clear alarms for specific device by giving its device number.
Note that all alarms for the device specified are cleared. Also note, that "clearing" an alarm means that its "clear" counter is incremented.
It is not removed immediately from the local alarm list. For further information, please see the discussion of the local alarm server.

Parameters

eqm	is the 6-character local equipment identifier name, which is internal to server.
devNr	is the device number of the device for which all alarms is to be cleared.

 
    ClearAlarm("EQP1",1); // clear all alarms for device #1

Referenced by ClearDeviceAlarm().

ClearDeviceAlarm()

void ClearDeviceAlarm	(	char *	eqm,
		char *	devname
	)

Instructs the local alarm server table that the given alarm is to be cleared.

A server can clear alarms for specific device by giving its registered device name.
Note that all alarms for the device specified are cleared. Also note, that "clearing" an alarm means that its "clear" counter is incremented.
It is not removed immediately from the local alarm list. For further information, please see the discussion of the local alarm server.

Parameters

eqm	is the 6-character local equipment identifier name, which is internal to server.
devname	is the registered device name of the device for which all alarms is to be cleared.

 
    ClearDeviceAlarm("EQP1","DEVICE1"); // clear all alarms for "DEVICE1"

References ClearAlarm(), and GetDeviceNumber().

GetAlarmCodeOscillationWindow()

int GetAlarmCodeOscillationWindow	(	const char *	eqm,
		int	code
	)

Gets the size of the alarm oscillation window in clear counts.

A call to a member of the ClearAlarm() family will increment the alarm's clear counter. Typically ClearAlarm() is always called at the beginning of an i/o loop and SetAlarm() is called if warranted according to alarm conditions later in the same loop. If the clear counter has reached the current oscillation window setting, the alarm is then marked for termination and removal. If the clear counter has been incremented by more than a single count AND a SetAlarm() is then called, the alarm is marked as 'oscillating' as it appears to the alarm sub system that the alarm conditions are not persistent by appear to come and go. The oscillation window is by default set to 8 counts. As a terminated alarm will nonetheless reside in the local alarm tables for a time equal to the current termination window (default = 30 seconds) the oscillation window will automatically 'grow' if an alarm has been marked as terminated but reappears within the termination window. The maximum oscillation window will however not exceed 128 (corresponding to approximately 2 minutes, assuming a 1 Hz i/o loop is in play).

Unlike GetAlarmOscillationWindow(), this routine targets a specific alarm code.

Parameters

eqm	is the 6-character local equipment identifier name, which is internal to server.
code	is the alarm code for which the oscillation window is to be applied

Returns

the size of the alarm oscillation window (default = 8), or, if negative, the negative value of a TINE return code (e.g. non_existent if the given equipment module does not exist or the alarm code is unknown).

See also

SetAlarmCodeOscillationWindow()

GetAlarmCollapseWindow()

int GetAlarmCollapseWindow

(

void

)

Gets the size of the alarm collapse window in counts.

At any given time the prevailing alarm conditions might give rise to an 'alarm storm', where an unusally large number of alarms are seen (due to e.g. hardware modules that are turned off during a shutdown). Such alarms are generally 'not interesting' and should not create extra network traffic, resource allocation, archiving, etc. if this can be avoided. As such, if the number of alarms for a given equipment module exceeds the current 'alarm collapse window' setting, the alarm information will be 'compressed' to a single alarm indicating that there are 'more than' the collapse window number of alarms.

Returns

the size of the alarm collapse window. (default = 100).

See also

SetAlarmCollapseWindow()

GetAlarmDataChangeWindow()

int GetAlarmDataChangeWindow

(

void

)

Gets the size of the alarm datachange window in seconds.

When an alarm provides alarm data with the appropriate SetAlarm() call, the alarm will be tagged with the 'DATACHANGE' flag if the supplied data differ from that provided with the previous call to SetAlarm(). The alarm timestamp will be adjusted to the current time ONLY if the data change is seen outside of the current AlarmDataChangeWindow (in seconds). The value of the alarm timestamp is relevant in the acquisition of the existing alarm table by the central alarm server. If this window is too short and the alarm data is constantly changing this can result in very long 'alarm chains' to display and archive. Default is 30 seconds. The caller can discover this time window with this call.

Returns

the size of the alarm data change window.

References AlarmDataChangeWindow.

GetAlarmDefinition()

int GetAlarmDefinition	(	char *	eqm,
		UINT32	code,
		ADS *	ads
	)

Gets the alarm definition for the alarm code specified.

Parameters

eqm	(input) is the 6-character local equipment identifier name, which is internal to server.
code	(input) is the alarm code for which the alarm definition is desired.
ads	(output) is a pointer reference to an alarm definition structure (ADS) to be filled in upon successful completion.

Returns

0 upon success, otherwise a TINE error code.

References invalid_parameter.

GetAlarmHeartbeat()

int GetAlarmHeartbeat

(

void

)

Gets the size of the heartbeat alarm window in seconds before the 'heartbeat' flag is applied to an alarm.

A server flags an alarm with a heartbeat when it has persistent in the local alarm list for a time span equal to this window. Default is 1200 seconds. The caller can discover this time window with this call.

Parameters

timeInSeconds

is the size of the heartbeat window.

References AlarmHeartbeat.

GetAlarmOscillationWindow()

int GetAlarmOscillationWindow

(

void

)

Gets the size of the alarm oscillation window in clear counts.

A call to a member of the ClearAlarm() family will increment the alarm's clear counter. Typically ClearAlarm() is always called at the beginning of an i/o loop and SetAlarm() is called if warranted according to alarm conditions later in the same loop. If the clear counter has reached the current oscillation window setting, the alarm is then marked for termination and removal. If the clear counter has been incremented by more than a single count AND a SetAlarm() is then called, the alarm is marked as 'oscillating' as it appears to the alarm sub system that the alarm conditions are not persistent by appear to come and go. The oscillation window is by default set to 8 counts. As a terminated alarm will nonetheless reside in the local alarm tables for a time equal to the current termination window (default = 30 seconds) the oscillation window will automatically 'grow' if an alarm has been marked as terminated but reappears within the termination window. The maximum oscillation window will however not exceed 128 (corresponding to approximately 2 minutes, assuming a 1 Hz i/o loop is in play).

Returns

the size of the alarm oscillation window. (default = 8).

See also

SetAlarmOscillationWindow()

GetAlarmTableMaximumSize()

int GetAlarmTableMaximumSize

(

void

)

Gets the maximum number of alarms managed by the local alarm server.

A server keeps a maximum number of alarms in its local table at one time before it begins to discard the older alarms. The caller can retrieve this number with this call. Default is 500.

Returns

the maximum number of alarms to be maintained in the local alarm table.

References MaxNumberAlarms.

GetAlarmTerminationWindow()

int GetAlarmTerminationWindow

(

void

)

Gets the size of the termination window in seconds before a terminated alarm is discarded from the local alarm list.

A server keeps keeps a terminated alarm in its list (marked as terminated) for a length of time specified by the termination window. This allows the central alarm server and/or other interested parties enough time to discover that the alarm has been terminated. Default is 4 seconds. The caller can discover this time window with this call.

Returns

the size of the termination window.

References TerminationWindow.

GetAllowOfflineAlarms()

int GetAllowOfflineAlarms

(

void

)

Gets the local alarm server setting to allow or disallow alarms for devices declared offline.

Returns

the current setting (DEFAULT = FALSE)

GetNewAlarmWindow()

int GetNewAlarmWindow

(

void

)

Gets the size of the new alarm window in seconds before a new alarm is no longer declared as new.

A server flags an alarm as new when it first appears in its list. After a short time span, the 'new' flag is removed by additional calls to SetAlarm for the same alarm. Default is 3 seconds. The caller can discover this time window with this call.

Returns

the size of the new alarm window.

References AlarmWindow.

RemoveAlarm()

void RemoveAlarm	(	char *	eqm,
		int	devNr,
		UINT32	code
	)

Instructs the local alarm server table that the given alarm is to be marked for removal.

A server can remove alarms for specific device by giving its device number.
Note that only the alarm specified for the device specified is removed. Also note, that "removing" an alarm means that termination bit will be set. It is subsequently marked for removal from the local alarm list. For further information, please see the discussion of the local alarm server.

Parameters

eqm	is the 6-character local equipment identifier name, which is internal to server.
devNr	is the device number of the device for which all alarms is to be removed.
code	is the alarm code, which identifies the specific alarm to be removed

 
    RemoveAlarm("EQP1",1,512);

RemoveDeviceAlarm()

void RemoveDeviceAlarm	(	char *	eqm,
		char *	devname,
		UINT32	code
	)

Instructs the local alarm server table that the given alarm is to be marked for removal.

A server can remove alarms for specific device by giving its registered device name.
Note that only the alarm specified for the device specified is removed. Also note, that "removing" an alarm means that termination bit will be set. It is subsequently marked for removal from the local alarm list. For further information, please see the discussion of the local alarm server.

Parameters

eqm	is the 6-character local equipment identifier name, which is internal to server.
devname	is the registered device name of the device for which all alarms is to be removed.
code	is the alarm code, which identifies the specific alarm to be removed

 
    RemoveDeviceAlarm("EQP1","DEVICE1",512);

References GetDeviceNumber().

SetAlarm()

int SetAlarm	(	char *	eqm,
		int	devNr,
		UINT32	almCode,
		BYTE *	almData
	)

Inserts an alarm into the local alarm server table.

A server can set an alarm for a specific device by giving its device number.
For further information, please see the discussion of the local alarm server.

Parameters

eqm	is the 6-character local equipment identifier name, which is internal to server.
devNr	is the device number of the device for which the alarm is to be set.
almCode	is the registered alarm code which defines the alarm
almData	is (up to 64-byte) the optional alarm data set, which supplies additional information for the alarm.

Returns

0 upon success, otherwise a TINE error code.

 
    if ((cc=SetAlarm("EQP1",1,512,NULL)) != 0)
    {
      feclog("Couldn’t set alarm : %s\n",erlst[cc]);
    }

References SetAlarmEx().

SetAlarmCodeOscillationWindow()

int SetAlarmCodeOscillationWindow	(	const char *	eqm,
		int	code,
		int	value
	)

Sets the size of the alarm oscillation window in clear counts.

A call to a member of the ClearAlarm() family will increment the alarm's clear counter. Typically ClearAlarm() is always called at the beginning of an i/o loop and SetAlarm() is called if warranted according to alarm conditions later in the same loop. If the clear counter has reached the current oscillation window setting, the alarm is then marked for termination and removal. If the clear counter has been incremented by more than a single count AND a SetAlarm() is then called, the alarm is marked as 'oscillating' as it appears to the alarm sub system that the alarm conditions are not persistent by appear to come and go. The oscillation window is by default set to 8 counts. As a terminated alarm will nonetheless reside in the local alarm tables for a time equal to the current termination window (default = 30 seconds) the oscillation window will automatically 'grow' if an alarm has been marked as terminated but reappears within the termination window. The maximum oscillation window will however not exceed 128 (corresponding to approximately 2 minutes, assuming a 1 Hz i/o loop is in play). A call to this routine will not only fix the alarm oscillation window but 'pin' it to the value given (i.e. so that it will not automatically grow).

Unlike SetAlarmOscillationWindow(), this routine can be used to apply an oscillation window to a specific alarm code, without affecting the behavior of other alarm types.

Parameters

eqm	is the 6-character local equipment identifier name, which is internal to server.
code	is the alarm code for which the oscillation window is to be applied
clearCounts	is the size of the alarm oscillation window. (default = 8).

Note

calling this routine will pin the oscillation window to the given setting so that the value will not 'grow' following the re-setting of a terminated alarm.

See also

SetAlarmOscillationWindow(), GetAlarmCodeOscillationWindow()

SetAlarmCollapseWindow()

int SetAlarmCollapseWindow

(

int

value

)

Sets the size of the alarm collapse window in counts.

At any given time the prevailing alarm conditions might give rise to an 'alarm storm', where an unusally large number of alarms are seen (due to e.g. hardware modules that are turned off during a shutdown). Such alarms are generally 'not interesting' and should not create extra network traffic, resource allocation, archiving, etc. if this can be avoided. As such, if the number of alarms for a given equipment module exceeds the current 'alarm collapse window' setting, the alarm information will be 'compressed' to a single alarm indicating that there are 'more than' the collapse window number of alarms. The value of the collapse window can be set via this call.

Parameters

value

is the size of the alarm collapse window. (default = 100).

Note

the alarm collapse window is applied to ALL alarms independent of alarm code or device.

See also

GetAlarmCollapseWindow()

References feclog(), and out_of_range.

SetAlarmDataChangeWindow()

void SetAlarmDataChangeWindow

(

int

timeInSeconds

)

Sets the size of the alarm datachange window in seconds.

When an alarm provides alarm data with the appropriate SetAlarm() call, the alarm will be tagged with the 'DATACHANGE' flag if the supplied data differ from that provided with the previous call to SetAlarm(). The alarm timestamp will be adjusted to the current time ONLY if the data change is seen outside of the current AlarmDataChangeWindow (in seconds). The value of the alarm timestamp is relevant in the acquisition of the existing alarm table by the central alarm server. If this window is too short and the alarm data is constantly changing this can result in very long 'alarm chains' to display and archive. Default is 30 seconds. The caller can discover this time window with this call.

Parameters

timeInSeconds

is the size of the alarm data change window. (default = 30).

References AlarmDataChangeWindow.

SetAlarmEx()

int SetAlarmEx	(	char *	eqm,
		int	devNr,
		UINT32	almCode,
		BYTE *	almData,
		BYTE	almFlags
	)

Inserts an alarm into the local alarm server table.

This is the extended call corresponding to SetAlarm(), the difference being the additional argument 'flags' which can be used to set the alarm descriptor. A server can set an alarm for a specific device by giving its device number.
For further information, please see the discussion of the local alarm server.

Parameters

eqm	is the 6-character local equipment identifier name, which is internal to server.
devNr	is the device number of the device for which the alarm is to be set.
almCode	is the registered alarm code which defines the alarm
almData	is the optional alarm data set, which supplies additional information for the alarm.
almFlags	is the optional alarm flag which is used in the alarm descriptor information.

Returns

0 upon success, otherwise a TINE error code.

 
    if ((cc=SetAlarmEx("EQP1",1,512,NULL,almNEW)) != 0)
    {
      feclog("Couldn’t set alarm : %s\n",erlst[cc]);
    }

Referenced by SetAlarm().

SetAlarmEx2()

int SetAlarmEx2	(	char *	eqm,
		int	devNr,
		UINT32	almCode,
		char *	almTag,
		BYTE *	almData,
		BYTE	flags
	)

Inserts an alarm into the local alarm server table.

This is the second extended call corresponding to SetAlarm(), the difference being the additional argument 'flags' which can be used to set the alarm descriptor and the additional argument 'almTag' which can be used to supply a dynamic alarm tag which will override the static tag otherwise assigned from the corresponding alarm definition. A server can set an alarm for a specific device by giving its device number. For further information, please see the discussion of the local alarm server.

Parameters

eqm	is the 6-character local equipment identifier name, which is internal to server.
devNr	is the device number of the device for which the alarm is to be set.
almCode	is the registered alarm code which defines the alarm
almTag	is an optional alarm tag to apply to the alarm. If NULL then the static alarm tag registered in the alarm definition for the alarm code given will be used.
almData	is the optional alarm data set, which supplies additional information for the alarm.
almFlags	is the optional alarm flag which is used in the alarm descriptor information.

Returns

0 upon success, otherwise a TINE error code.

 
    if ((cc=SetAlarmEx("EQP1",1,512,NULL,almNEW)) != 0)
    {
      feclog("Couldn’t set alarm : %s\n",erlst[cc]);
    }

SetAlarmHeartbeat()

void SetAlarmHeartbeat

(

int

timeInSeconds

)

Sets the size of the heartbeat alarm window in seconds before the 'heartbeat' flag is applied to an alarm.

A server flags an alarm with a heartbeat when it has persistent in the local alarm list for a time span equal to this window. Default is 1200 seconds. The caller can set this window with this call.

Parameters

timeInSeconds

is the size of the heartbeat window.

References AlarmHeartbeat.

SetAlarmOscillationWindow()

int SetAlarmOscillationWindow

(

int

clearCounts

)

Sets the size of the alarm oscillation window in clear counts.

A call to a member of the ClearAlarm() family will increment the alarm's clear counter. Typically ClearAlarm() is always called at the beginning of an i/o loop and SetAlarm() is called if warranted according to alarm conditions later in the same loop. If the clear counter has reached the current oscillation window setting, the alarm is then marked for termination and removal. If the clear counter has been incremented by more than a single count AND a SetAlarm() is then called, the alarm is marked as 'oscillating' as it appears to the alarm sub system that the alarm conditions are not persistent by appear to come and go. The oscillation window is by default set to 8 counts. As a terminated alarm will nonetheless reside in the local alarm tables for a time equal to the current termination window (default = 30 seconds) the oscillation window will automatically 'grow' if an alarm has been marked as terminated but reappears within the termination window. The maximum oscillation window will however not exceed 128 (corresponding to approximately 2 minutes, assuming a 1 Hz i/o loop is in play). A call to this routine will not only fix the alarm oscillation window but 'pin' it to the value given (i.e. so that it will not automatically grow).

Parameters

clearCounts

is the size of the alarm oscillation window. (default = 8).

Note

calling this routine will pin the oscillation window to the given setting so that the value will not 'grow' following the re-setting of a terminated alarm.

the alarm oscillation window is applied to ALL alarms independent of alarm code or device. Once called, this will effectively 'pin' the alarm oscillation value for all alarm types to this value. Applying an oscillation window to a specific alarm can be achieved by calling SetAlarmCodeOscillationWindow();

See also

GetAlarmOscillationWindow(), SetAlarmCodeOscillationWindow()

References out_of_range.

SetAlarmTableMaximumSize()

void SetAlarmTableMaximumSize

(

int

tableSize

)

Sets the maximum number of alarms managed by the local alarm server.

A server keeps a maximum number of alarms in its local table at one time before it begins to discard the older alarms. The caller can adjust this number with this call. Default is 500.

Parameters

tableSize

is the maximum number of alarms to be maintained in the local alarm table.

References MaxNumberAlarms.

SetAlarmTerminationWindow()

void SetAlarmTerminationWindow

(

int

timeInSeconds

)

Sets the size of the termination window in seconds before a terminated alarm is discarded from the local alarm list.

A server keeps keeps a terminated alarm in its list (marked as terminated) for a length of time specified by the termination window. This allows the central alarm server and/or other interested parties enough time to discover that the alarm has been terminated. The caller can set this window with this call.

Parameters

timeInSeconds

is the size of the termination window. (Default: 30)

References TerminationWindow.

SetAllowOfflineAlarms()

void SetAllowOfflineAlarms

(

int

value

)

Instructs the local alarm server to allow or disallow alarms for devices declared offline.

Parameters

value

is the desired setting (DEFAULT = FALSE)

SetAvailableMemoryThreshold()

void SetAvailableMemoryThreshold

(

UINT32

minAvailBytes

)

Sets the threshold (in bytes) used in setting 'low main memory' alarms.

A server can set automatic 'low_main_memory' alarms by setting this threshold to a positive non-zero number. (default = 0).

Parameters

minAvailBytes

gives the minimum number of bytes which should be available main memory before an alarm in is issued.

SetDelayAlarmSurvey()

void SetDelayAlarmSurvey

(

int

delayInSeconds

)

Instructs the local alarm server to delay surveying alarms (for the alarm watch table)

If the alarm watch subsystem needs to be delayed for any reason (e.g. initialization) this routine may be used for such purposes. Also, the environment variable TINE_DELAY_ALARM_SURVEY can be used to delay the alarm watch survey during initialization.

Parameters

delayInSeconds

is the amount of time in seconds to delay the alarm survey

SetDeviceAlarm()

int SetDeviceAlarm	(	char *	eqm,
		char *	devname,
		UINT32	almCode,
		BYTE *	almData,
		BYTE	almFlags
	)

Inserts an alarm into the local alarm server table.

Analogous to SetAlarmEx(), this call inserts alarms into the local alarm server table. A server can set an alarm for a specific device by giving its device name. This is sometime preferred over specifying its device number as in SetAlarm() or SetAlarmEx(). For further information, please see the discussion of the local alarm server.

Parameters

eqm	is the 6-character local equipment identifier name, which is internal to server.
devname	is the registered device name of the device for which the alarm is to be set.
almCode	is the registered alarm code which defines the alarm
almData	is (up to 64-byte) the optional alarm data set, which supplies additional information for the alarm.
almFlags	is the optional alarm flag which is used in the alarm descriptor information.

Returns

0 upon success, otherwise a TINE error code.

 
    if ((cc=SetDeviceAlarm("EQP1","DEVICE1",512,NULL,almNEW)) != 0)
    {
      feclog("Couldn’t set alarm : %s\n",erlst[cc]);
    }

SetDeviceAlarmEx()

int SetDeviceAlarmEx	(	char *	eqm,
		char *	devname,
		UINT32	almCode,
		char *	almTag,
		BYTE *	almData,
		BYTE	flags
	)

Inserts an alarm into the local alarm server table.

Analogous to SetAlarmEx2(), this call inserts alarms into the local alarm server table. A server can set an alarm for a specific device by giving its device name. This is sometime preferred over specifying its device number as in SetAlarm() or SetAlarmEx(). For further information, please see the discussion of the local alarm server.

Parameters

eqm	is the 6-character local equipment identifier name, which is internal to server.
devname	is the registered device name of the device for which the alarm is to be set.
almCode	is the registered alarm code which defines the alarm
almTag	is an optional alarm tag to apply to the alarm. If NULL then the static alarm tag registered in the alarm definition for the alarm code given will be used.
almData	is (up to 64-byte) the optional alarm data set, which supplies additional information for the alarm.
almFlags	is the optional alarm flag which is used in the alarm descriptor information.

Returns

0 upon success, otherwise a TINE error code.

 
    if ((cc=SetDeviceAlarm("EQP1","DEVICE1",512,NULL,almNEW)) != 0)
    {
      feclog("Couldn’t set alarm : %s\n",erlst[cc]);
    }

SetFreeBlocksAlarmThreshold()

int SetFreeBlocksAlarmThreshold	(	char *	path,
		UINT32	minFreeBlocks
	)

Sets the threshold (in blocks) used in setting 'low disk space' alarms.

A server can set automatic 'low_disk_space' alarms by setting this threshold to a positive non-zero number for the disk path in question.
(default = 0).

Parameters

path	gives a path defining a disk mount to be monitored
minFreeBlocks	gives the minimum number of (1-Kbyte) blocks which should be available before an alarm is issued.

Returns

0 upon success of a tine error code (resources_exhausted if an attempt to monitor more than 10 disks is attempted.

Note

This routine is only available for those operating systems with disks!

Example

 
  SetFreeBlocksAlarmThreshold("C:\\HISTORY",200000);
 

SetNewAlarmWindow()

void SetNewAlarmWindow

(

int

timeInSeconds

)

Sets the size of the new alarm window in seconds before a new alarm is no longer declared as new.

A server flags an alarm as new when it first appears in its list. After a short time span, the 'new' flag is removed by additional calls to SetAlarm for the same alarm. Default is 3 seconds. The caller can set this window with this call.

Parameters

timeInSeconds

is the size of the new alarm window.

References AlarmWindow.

Variable Documentation

AlarmDataChangeWindow

int AlarmDataChangeWindow = DEFAULT_ALARM_DATACHANGE_WINDOW

Determines the minimum time a data change alarm is to keep its timestamp in the local alarm table.

Alarms supplying data can be updating the alarm data quite often. Each change of alarm data will be represented in the alarm itself. However the timestamp of the alarm will not be updated unless a time interval larger than the AlarmDataChangeWindow has occured.

Default: 30 sec

Example:

AlarmDataChangeWindow = 40; // make the data change window a bit longer

Referenced by GetAlarmDataChangeWindow(), and SetAlarmDataChangeWindow().

AlarmHeartbeat

int AlarmHeartbeat = DEFAULT_ALARM_HEARTBEAT

Determines the time interval at the 'HEARTBEAT' flag will be re-issued for persistent alarms.

The purpose of an alarm is to alert operators or maintenance staff to a problem.
If an alarm persists and is not dealt with, its timestamp is adjusted to the current time at intervals given by the AlarmHeartbeat value. This will call attention to the alarm. It also places the alarm at regular intervals in an archive of alarms. The developer can set this to any desired value (usually at initialization time).

Default: 1200 sec

Example:

AlarmHeartbeat = 3600; // heartbeat once per hour

Referenced by GetAlarmHeartbeat(), and SetAlarmHeartbeat().

AlarmInstantWindow

int AlarmInstantWindow = DEFAULT_INSTANT_WINDOW

Determines the minimum time an alarm is to remain in the local alarm table before it can be removed.

Transient alarms (with no duration) are immediately marked for termination as soon as they are set. The AlarmInstantWindow determines the amount of time in seconds an "Instant" Alarm is to remain in the alarm list (default 4 seconds).

Default: 30 sec

Example:

AlarmInstantWindow = 40; // keep transient alarms in the table a bit longer

AlarmTestState

int AlarmTestState = 0

Determines the minimum time an alarm is to remain in the local alarm table before it can be removed.

When developing the alarm logic for a particular server is frequently useful to mark the alarms being set with the almTEST bit. This can either be done on an individual basis using the SetAlarmEx() call, or one can set the global variable AlarmTestState to a non-zero value.

Default: FALSE

Example:

AlarmTestState = TRUE; // just testing ...

AlarmWindow

int AlarmWindow = DEFAULT_ALARM_WINDOW

Determines the minimum time an alarm is to remain in the local alarm table before it can be removed.

IO routines can sometimes set and clear alarms at such a high frequency that an alarm could go unnoticed if it appeared and disappeared before a client had a chance to read it. The AlarmWindow value determines the amount of time (in seconds) an alarm must remain in the local alarm list before it can be removed. The default is 3 seconds, which is generally fine for a central alarm reader polling at 1 second intervals.

Default: 3 sec

Example:

AlarmWindow = 10; // keep alarms in the table a bit longer

Referenced by GetNewAlarmWindow(), and SetNewAlarmWindow().

MaxNumberAlarms

int MaxNumberAlarms = MAXALARMS

Determines the maximum number of alarms which can be maintained in the local alarm server's alarm list.

Each registered device can have an associated alarm link list. The length of this list will not exceed the value entered for MaxNumAlarms (default 100). The default is generally more than enough. Primarily this variable serves as a safety valve against sudden alarm avalanches.

Default: 100

Example:

MaxNumberAlarms = 500;

Referenced by GetAlarmTableMaximumSize(), and SetAlarmTableMaximumSize().

TerminationWindow

int TerminationWindow = DEFAULT_TERMINATION_WINDOW

Determines the minimum time an expired alarm is to remain in the local alarm table.

Terminated alarms remain in the local alarm table for an amount of time specified by this variable. Thus a client monitoring the local alarm list will be able tosee that the alarm was set and has finished.

Default: 30 sec

Example:

TerminationWindow = 40; // keep terminated alarms in the table a bit longer

Referenced by GetAlarmTerminationWindow(), and SetAlarmTerminationWindow().