This subroutine adds a request to receive a point value when an alarm condition exists. Point Management sends the point value to the requester when the point is in an alarm condition.

The alarm condition is specified as a combination of Alarm or Warning and High or Low. For example, it is possible to request to be notified about an Alarm High condition or a Warning Low condition, or any other combination. When the status of the point satisfies the specified condition, Point Management sends the point value. Point Management continues to send the value whenever a point value enters the state specified by the alarm condition until the request is canceled.

The following table shows the relationship between the setting of the parameters aw_state and high_low, and the point state when your application receives notification. For example, the table shows that if aw_state = PTM_AW_ALARM and high_low = PTM_LOW, your application will receive the point data when the point state goes into Alarm Low state.

aw_state	high_low	point state
PTM_AW_ALARM	PTM_LOW	Alarm Low
PTM_AW_WARNING	PTM_LOW	Warning Low
PTM_AW_WARNING + PTM_AW_ALARM	PTM_LOW	Warning Low or Alarm Low
PTM_AW_ALARM	PTM_AW_ALARM	Alarm High
PTM_AW_WARNING	PTM_HIGH	Warning High
PTM_AW_WARNING + PTM_AW_ALARM	PTM_HIGH	Warning High or Alarm High
PTM_AW_ALARM	PTM_HIGH + PTM_LOW	Alarm High or Alarm Low
PTM_AW_WARNING	PTM_HIGH + PTM_LOW	Warning High or Warning Low
PTM_AW_WARNING + PTM_AW_ALARM	PTM_HIGH + PTM_LOW	Any alarm state

An On-Alarm request may only be made for point types for which alarms may be defined. That is, an "On-Alarm" request may not be made for BITSTRING, OCTET_STRING, and CHARACTER_STRING types, or for points that are more than one element in length.

Syntax

int PTMAP_add_onalarm ( sl_adr, point_adr, aw_state,

                        high_low, immediate,

                        req_adr, retstat )

PTMAP_ADDR      *sl_adr;

PTMAP_ADDR      *point_adr;

PTM_AW          aw_state;

PTM_HIGH_LOW    high_low;

COR_BOOLEAN     immediate

PTMAP_ADDR      *req_adr;

COR_STATUS      *retstat;

Input Arguments

sl_adr	A Shopping List ID created by a call to PTMAP_add_sl.
point_adr	A point ID created by a call to PTMAP_add_point.
aw_state	The alarm or warning state. The possibilities are:
	PTM_AW_ALARM - send on alarm only
	PTM_AW_WARNING - send on warning only
	PTM_AW_ALARM + PTM_AW_WARNING - send on either alarm or warning
high_low	The variance direction for which the alarm state applies. The possibilities are:
	PTM_HIGH - send on high alarm
	PTM_LOW - send on low alarm
	PTM_HIGH + PTM_LOW - send on either high or low alarm
immediate	Set to TRUE if the application requires an immediate response from Point Management containing the point value whether or not the point is in alarm state. Following the immediate response, the point value is sent to the application only when the alarm state of the point changes.

Output Arguments

req_adr	Identifier used to reference this request.
retstat	Pointer to status structure. The following errors may be returned (see Appendix A for an explanation of this code):
	PTMAP_ADDR_PTR_NULL
	PTMAP_SL_ADR_NULL
	PTMAP_SL_ADDR_NOTF
	PTMAP_SEQ_NUM_MISMATCH
	PTMAP_INVAL_ONALARM_LIMIT
	PTMAP_INVAL_ONALARM_STATE
	PTMAP_INVAL_DATA_TYPE
	PTMAP_INVAL_ELEMENTS

Return Value

The contents of retstat.status.

More information

Point Management API subroutines.

---